dsh-decision-log

Readme

<p align="center">
  <img src="./assets/readme/hero.svg" width="100%" alt="dsh-decision-log · 决策日志 —— AI 干活的「小本本」：每个决定都记下，再也不怕当初为啥这么干">
</p>

<div align="center">

[![DSH](https://img.shields.io/badge/DeepSeek_Harness-0.1.x-6C5CE7?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)

</div>

---

## ✨ 它是什么？一句话讲透

> **这个插件是给 AI 干活时用的"会议纪要本"。** AI 每做一个重要决定（比如"用 A 方案不用 B 方案"），你让它记一笔，它就写进项目里的 `DECISIONS.md`。从此不管换新对话、换同事、还是过三个月回来看，**"当初为什么这么做"永远有据可查。**

它不是任务清单（那是 todo），不是聊天记录（那是 session），它是**项目的"决策记忆"**——代码的 git 记的是"改了什么"，它记的是"为什么这么改"。

---

## 📌 使用前请先知道（很重要，30 秒读完）

**这个插件装好后，不会在你界面上蹦出个新按钮、新窗口、新面板。** 它是那种"藏在后台、随叫随到"的插件——需要**召唤**它，它才干活。

- **平时它隐身**：你该聊天聊天、该干活干活，界面上看不出它存在；
- **你"召唤"它**：当你对 AI 说"**记一下：……**"，或者敲 `/log-decision` 命令，它立刻现身——把你这句话（连同上下文、理由）**写进这个小本本**：`<你的项目>/.dsh/DECISIONS.md`；
- **记完继续隐身**：落盘后它回到后台，等下一次召唤；
- **它还会主动做一件事**：每次对话轮次开始时，它悄悄把"已记录的决定"注入给 AI 看，让 AI 别忘事——**这是它唯一主动的动作**，除此之外一切都要你开口召唤。

### 🎉 第一次使用会发生什么？（放心，一切正常）

**当你第一次召唤这个插件（说"记一下"或敲 `/log-decision`）时，它会在你的项目里自动做两件事——注意，是它自己做的，你什么都不用管：**

1. **自动新建一个文件夹**：`<你的项目>/.dsh/`（它放小本本的地方）；
2. **自动放一本空白的 `DECISIONS.md`**：里面有表头、有格式，但一条记录都没有。

**看到项目里突然多出个 `.dsh/` 文件夹和文件？别慌，这是设计好的正常行为，不是 bug、不是病毒、更不需要你手动创建！**

- ✅ **只建一次**：只在**第一次**使用的时候建，以后任何一次调用都不会重复建、也不会覆盖你已有的记录；
- ✅ **完全透明**：就是两份普通文件，你可以随时打开看、改、删（删了下次召唤它会重新建一本空的）；
- ✅ **不影响任何东西**：它不碰你的代码、不动你的聊天记录，只是静静地放一本"小本本"在项目里。

**从第二次使用开始，一切照常**：文件已经在，插件直接往里面记，你完全感觉不到"初始化"这件事的存在。

> 💡 补充：从**第一次**开始，**每次对话** dsh 里的 AI 都会自动读到这本小本本的内容（摘要自动注入），所以就算一条都还没记，AI 也知道"有这么个本子在记录决策"——这件事跟"第一次"无关，是每次都发生的。

**你的记录存哪？存你电脑上，一个独立的 MD 文件夹，不上云：**

```
你的项目文件夹/
└── .dsh/                  ← 插件第一次使用自动新建的 MD 文件夹（只建一次）
    └── DECISIONS.md       ← 所有决定都记在这里（纯 Markdown，任何 AI 可读，可 git 提交）
```

所以本质上是三件事：**① 装好它（后台就位）→ ② 第一次使用自动建好 MD 文件夹（.dsh/DECISIONS.md，只此一次）→ ③ 需要时召唤它（说"记一下"或敲命令），记录落进这个任何 AI 都能读的本地文件**。数据 100% 在你电脑上，不是云端、不经过任何服务器。

> 一句话记住它：**一个隐身的小秘书——你喊它才出来，它只做一件事：把"定了什么、为什么"记进你项目里的 MD 文件。**

---

## 🌍 划重点：这份 MD，任何 AI 都能读！！！

**这是这个插件最容易被低估的一个能力——请务必看这一节！**

你记下的 `DECISIONS.md`，**不专属 dsh，不绑定任何一家 AI**！它就是一份**最普通的 Markdown 文件**，放在你电脑上，路径固定、随时可访问！这意味着：

- 🤖 **Claude 能读！** 干活前让它"读一下 `<项目>/.dsh/DECISIONS.md`"，它立刻知道项目决策全貌，不用你重新讲！
- 🤖 **Cursor 能读！** 写代码前让它看一眼，它不会写出跟你已定方案冲突的东西！
- 🤖 **ChatGPT 能读！** 把文件拖给它，它马上进入状态！
- 🤖 **任何 AI 都能读！** 只要是能读 Markdown 的工具，都能读这份文件——**你的决策记录从此不锁死在任何一个 AI 生态里！**

**为什么这很重要？** 因为你的决策记忆应该**跟着项目走、跟着文件走、跟着你自己走**——而不是跟着某一个 AI 的聊天记录走！

- 今天用 dsh 干活，记的决策明天能用 Claude 续上！
- 换工具？换 AI？换电脑？**文件还在，记忆就在！**
- 团队协作？同事用 Cursor、你用 dsh——**同一份文件，谁都读得懂！**

> 💡 **把它当"项目通用记忆文件"用**：不止 dsh 的 AI 会读它，你可以在任何 AI 工具里引用这个路径——比如让 Claude 干活前先读一遍，让 Cursor 写代码前先看一遍，它就像一个"随身携带的项目决策手册"。

**说白了：你记的不是"给 dsh 的话"，是"给所有 AI 的话"！一次记录，万物可读！**

---

## 😫 先看看这些场景，你熟不熟？

### 场景一：AI 的"失忆循环"
周一你让 AI 定了"登录用 JWT 不用 session cookie"，聊了半小时把方案敲定。周二新开一个对话想继续干活——**AI 一脸茫然："请问登录方案选哪个？"** 你只能重新讲一遍。

### 场景二：代码的"身世之谜"
三个月后，你看着一段代码想："这里为啥用 Redis 不用 Memcached？当时脑子进水了？" 翻聊天记录？早没了。问同事？没人记得。**代码还在，但"为什么"丢了。**

### 场景三：交接的"说不清楚"
任务要交接给新会话或新同事。人家问："这块为什么这么写？""之前定过什么约束？" 你嘴巴张了又合，只能憋出一句"呃……反正当时就这么定的"。

### 场景四：AI 的"朝令夕改"
你让 AI 干活干到一半，它突然说"我觉得应该把方案推倒重来"——因为它**忘了你 20 分钟前刚拍板定下的方案**。

---

## 💡 装上它之后，同样的场景变成这样：

| 之前 | 之后 |
|---|---|
| 新对话的 AI 失忆，重问一遍 | 新对话的 AI **自带记忆**："之前定了用 JWT" |
| "为啥用 Redis" 没人知道 | 翻一眼 `DECISIONS.md`，**理由写得清清楚楚** |
| 交接时嘴巴说不清 | **直接把决策文件甩过去**，比嘴说清楚一百倍 |
| AI 中途想推翻方案 | 注入摘要提醒它："历史已定，**勿重复讨论，推翻需先说明理由**" |

**一句话：花两秒记一笔，省未来两小时。**

---

## 🚀 安装（一句话的事，剩下的交给 AI）

**把下面这段话整个复制，发给你的 dsh AI（或任何 AI 助手），它会自动帮你装好、重启、跑冒烟测试：**

```
帮我安装 dsh-decision-log 插件：
1. 运行 dsh plugin --profile web add github:yuyolin/dsh-decision-log
2. 重启 dsh Web UI（启动命令要带 --patch）
3. 跑冒烟测试：开一个会话，执行 /log-decision 测试，确认返回"决策已记录"
4. 把结果告诉我
```

> 如果你在**本地开发**这个插件，把第 1 步换成：`dsh plugin --profile web add "link:D:/dsh-decision-log"` 即可。

**想自己动手？** 也完全可以，就三条命令：

```bash
# 1. 安装
dsh plugin --profile web add github:yuyolin/dsh-decision-log

# 2. 重启 Web UI（必须带 --patch，否则插件不生效）
npx @deepseek-ai/dsh web --patch

# 3. 验证：开个会话，输入
/log-decision 测试
```

看到"决策已记录"就说明它活了 ✅（这条测试记录留着或删掉都行）。

> 要是没反应，十有八九是没带 `--patch` 或者没重启——**装完不重启 = 白装**，这话放哪个软件身上都成立。

---

## 🎯 怎么用？简单到不像插件

### 玩法一：直接说人话（强烈推荐，什么也不用学）

你就把 AI 当成一个**随身带小本本的助理**。敲定一个决定，随口说一句：

```
记一下：登录用 JWT 不用 session cookie
```

AI 秒懂，自己记好，还会回你：

```
✅ 决策已记录到 D:\work\myproject\.dsh\DECISIONS.md（当前共 3 条）
- 用 JWT 不用 session cookie（accepted）
- 理由：跨端无状态，避免 session 同步
```

**再多举几个例子，全是大白话：**

- 🗣️ `把刚才选 X 方案的决定记下来`
- 🗣️ `记住，缓存用 Redis 不用 Memcached，因为持久化更强`
- 🗣️ `我们定好了：数据库用 PostgreSQL，记一下`
- 🗣️ `图表库用 ECharts 不用 AntV，记个档`

**什么时候说这句话？** 记住一个直觉：**凡是"我们最终选了哪个"这种话说出口，就补一句"记一下"。** 两秒钟的事，未来省两小时。

### 玩法二：输入框敲命令（你想自己记的时候）

```
/log-decision 用 Redis 不用 Memcached
```

想写详细点，带上背景和理由：

```
/log-decision 用 Redis 不用 Memcached --context 缓存层选型 --reason 持久化更强
```

| 参数 | 意思 | 例子 |
|---|---|---|
| `--context` | 在什么背景下做的决定 | `--context 缓存层选型` |
| `--reason` | 为什么这么选（**最值钱**） | `--reason 持久化更强` |
| `--status` | 状态，默认 `accepted` 不用管 | `--status superseded`（已推翻） |

**改主意了？** 不用删，补记两条，完整保留"先这样、后那样、为啥变"的故事：

```
/log-decision 缓存方案改为 Memcached --reason 团队更熟
/log-decision 用 Redis 不用 Memcached --reason 已换方案 --status superseded
```

### 玩法三：让 AI 记全套（信息量拉满）

```
把刚才的选型记一下，要带上备选方案和理由
```

AI 会记全：决策 / 背景 / 备选方案 / 理由 / 涉及文件——一条完整记录。

记完随时可以查：

- 📖 `查一下我们定过哪些事` —— 列出所有决策
- 🔍 `关于登录有没有什么决定？` —— 关键词搜索
- 🧹 `审计一下决策记录` —— 检查有没有记重、记乱
- 📄 `把决策文档导出来看看` —— 查看完整内容

---

## 🧠 最妙的部分：换了新对话，它自己就记得

这是最省心的设计——**你不用手动喂新对话**。

每次新对话、每轮新开始，插件都会**自动**把"已定过的事"塞给 AI 看，就像 AI 入职前先读了一遍项目手册：

```
📌 决策记录（已有 3 条，其中 1 条待确认，请说"确认"或"拒绝"）：
- [待确认] 图表库换 ECharts — 社区更活跃
- [accepted] 用 JWT 不用 session cookie — 跨端无状态，避免 session 同步
(... 其余 1 条见 .dsh/DECISIONS.md)
```

**效果：**
- ✅ 新对话的 AI 天生知道旧决定，不再重复问
- ✅ AI 想推翻旧方案？得先说明理由——**防止随手推翻已定的事**
- ✅ **AI 自动记的决策是"待确认"状态**（防止 AI 自作主张乱记）——你看到摘要里的"待确认"，说一句"确认"或"拒绝"，AI 就会调用 `decision_confirm` / `decision_reject` 标记，确认后才算生效
- ✅ 只注入最新几条 + 总数，**几乎不占 token**（默认上限 2000 字符）

**整套闭环长这样 👇**

<p align="center">
  <img src="./assets/readme/workflow.svg" width="100%" alt="决策闭环：你拍板 → decision_log 落盘 → 写入 .dsh/DECISIONS.md → 每轮新对话自动注入摘要 → AI 带着记忆干活">
</p>

---

## 📁 记下来的东西，长这样

文件在**项目文件夹**里的 `.dsh/DECISIONS.md`（每个项目一份，互不串门）。**插件第一次使用时会自动新建 `.dsh/` 这个 MD 文件夹并生成空白文件**（只有表头、零条记录），你随时可以打开看：

```markdown
---
schema: dsh-decision-log/v1
updated_at: 2026-08-24T16:00:00+08:00
count: 2
---

## [2026-08-24T15:30:00+08:00] 用 JWT 不用 session cookie
- 状态: accepted
- 上下文: 登录模块改造
- 备选: [session cookie, OAuth]
- 理由: 跨端无状态，避免 session 同步
- 涉及文件: [src/auth/session.ts]
- 来源: session-abc123 (seq 42)

## [2026-08-24T16:10:00+08:00] 缓存用 Redis 不用 Memcached
- 状态: accepted
- 理由: 持久化更强
```

它就是一份**普通 Markdown**，所以你能：

- 🤖 **给任何 AI 读！** Claude / Cursor / ChatGPT 或其他工具，只要让它读这个路径（`<项目>/.dsh/DECISIONS.md`），立刻知道项目决策全貌！
- 🔄 **提交 git！** `git add .dsh/DECISIONS.md && git commit`，决策和代码一起版本化！
- 📤 **交接甩文件！** 新同事/新会话，直接把这份文件发过去，比嘴说清楚！
- 🕰️ **回看演变！** 用 git 看这份文件的历史，"决策是怎么一步步变过来的"一目了然！
- 🤝 **代码评审对照！** PR 讨论时，"当时为什么这么写"直接引用！

---

## 💰 说点实在的：它到底帮你省了什么？

| 你花的成本 | 你省下的 |
|---|---|
| 每次说完"定了用 X"补一句"记一下"（2 秒） | 新对话重讲一遍方案（10 分钟） |
| 敲一行 `/log-decision`（5 秒） | 三个月后翻聊天记录找"为什么"（半小时，还找不到） |
| 一次交接把文件甩过去（1 分钟） | 交接时反复口述背景（一下午） |
| 几乎为 0 的 token 成本 | AI 反复推翻已定方案带来的返工（无限） |

**这不是一个"锦上添花"的插件，这是一个"省心"的插件——装一次，用一年。**

---

## ❓ 常见问题

**Q：装好了但没反应？**
A：三步检查：① 启动命令带没带 `--patch` ② 重启没重启 ③ `/log-decision 测试` 有没有返回。——三步走完还不行，把 `/log-decision 测试` 的返回截图发我，比我俩隔着屏幕猜快。

**Q：我说"记一下"，AI 没记？**
A：先确认插件装好（见上）。装好了还不记，就明说"用 decision_log 工具记录"引导它。

**Q：AI 记的决策怎么变成"待确认"？我要怎么确认？**
A：这是**审批门**设计——AI 自动记的决策默认是"待确认"（pending）状态，防止 AI 自作主张乱记。你会在对话摘要里看到"待确认"，直接说一句"**确认**"或"**拒绝**"，AI 就会调 `decision_confirm` / `decision_reject` 标记，确认后才算生效。手动用 `/log-decision` 记的则直接是已确认状态。

**Q：记错了能改吗？**
A：不用改文件。补记一条新的，旧标 `superseded`（已推翻），保留完整历史。

**Q：两个项目会记混吗？**
A：不会。每个项目各有一份 `.dsh/DECISIONS.md`，完全隔离。

**Q：会很烧 token 吗？越用越久会不会越来越贵？**
A：不会，每轮只注入最新几条摘要（2000 字符硬上限），**记录 100 条和 1000 条消耗几乎一样**（实测约 1000~1100 token）。完整账本见文末《🔬 老实交代》章节。

**Q：这跟 todo、跟聊天记录有啥区别？**
A：todo 是"接下来做什么"，聊天记录是"说过什么"，决策日志是"**定了什么、为什么**"——是项目的决策资产，随代码版本化、可 diff、可交接。

---

## 🛡️ 权限与安全

- 只读写**当前工作区**的 `.dsh/DECISIONS.md`，以当前 dsh 进程权限运行
- **只读源会话**：从 `exec.agent.session` 读取元数据，绝不改写会话日志
- 自动识别只输出"候选"日志，**不自动落盘**——落盘必须经 `decision_log`（模型或用户显式触发）
- 不触发任何高危操作（无删除、无远程调用、无 shell 执行）

## 📦 兼容性

- Node.js: ^22.19.0 || >=24.0.0
- dsh: 0.1.x（官方 API：`agent.session`、`ctx.fs`、`agent/pre-step`、`session/event`）
- 纯 JS，无原生二进制依赖，Windows / Linux / macOS 通吃

## 🛠️ 开发

```bash
npm install
npm run build     # esbuild 编译到 lib/
npm test          # node --test（store/extractor/audit 纯逻辑测试）
```

## 🗺️ 路线图

- [x] Phase 1: MVP —— decision_log 手动记录 + 落盘 + 查询 + 审计 + 注入摘要
- [ ] Phase 2: 自动识别决策候选增强（LLM 蒸馏理由）+ Web UI 投影
- [ ] Phase 3: 跨会话语义去重（ctx.sessionQuery）+ git commit 关联

---

## 🔬 老实交代：越用越久，token 会越来越重吗？

先说结论，别慌：**不会。** 用一年和用一天，每轮对话多花的 token 基本一个样。下面把账摊开算给你看。

### 为啥不会越来越重？核心就一条

插件**从来不把整本 `DECISIONS.md` 塞给 AI**——真要那样，记个一年肯定爆。

它的做法特别朴素，就三步：

1. 每轮对话开始，只挑文件里**最新的一批**决策给 AI 看（不是全部）；
2. 攒到 **2000 字符**就打住，多出来的不看了，只留一行小字：`(... 其余 N 条见 .dsh/DECISIONS.md)`；
3. 想看全部？随时喊 `decision_list` 按需查，或者直接打开文件——**完整内容永远躺在文件里，从不进对话**。

打个比方：这就像你读书，每次开工前只看**目录最新那几页**，而不是把整本书背进脑子里。书随时能翻，但平常就放那儿，不占你脑子。

### 实测数据（真的跑过，不是编的）

| 记了多少条 | 每轮注入多少 | 实际 token |
|---|---|---|
| 100 条 | ~2060 字符（触顶了） | ≈ **1097** |
| 1000 条 | ~2039 字符（还是触顶） | ≈ **1075** |

看见没？从 100 条干到 1000 条，翻了十倍，每轮消耗反而**几乎没动**——因为它早就触顶了，再多也不看了。这就是"恒定成本"：**本子不管记多厚，AI 每轮只看固定大小的一页。**

### 这点成本，值不值？

1100 token 是个什么概念？AI 正常回你一段话，动辄就是 1000~3000 token。也就是说，插件注入的这点东西，**约等于 AI 多说一两句话的功夫**。

但你换来的是啥？

- 不用每次重讲背景，省下几百上千 token；
- 不会因为 AI 失忆而返工，可能省下几万 token 的重做成本；
- 决策可查可审计，团队协作不再靠嘴，这部分没法用 token 算，但肯定值。

**花 1100 token 买保险，避免 N 倍的返工费——这笔账，怎么算都划算。**

### 一句话总结

> **本子可以越记越厚，但 AI 每轮只看固定的一页。** 该花的一分不多花，不该花的一分不少省。放心用，越用越值！

## 👋 关于作者（唠两句）

嗨，这个插件是我（**yuyolin**）瞎折腾出来的。

我平时就爱捣鼓 DeepSeek Harness 这玩意儿，因为它"什么都能当插件装"这个思路我特别喜欢。做这个决策日志的起因也简单：我受够了每次换个对话，AI 就跟失忆了一样，之前定好的事全得重讲一遍，烦死了。所以干脆自己写个插件，让 AI 记住"咱当初是咋定的"。

这个我还在 dsh 那边折腾了俩别的，感兴趣的也可以翻翻：

- **dsh-task-bootstrap**（拖即续）：活干到一半想换对话？打包带走，接着干
- **dsh-drag-handoff**：直接把任务卡拖进新对话，fork 个新上下文

用着爽不爽、哪里卡壳、想要啥新功能，甚至想拉着我一起搞点新活——都欢迎来戳我：

- 📮 邮箱：**yuyolin9@gmail.com**
- 🐙 GitHub：[yuyolin](https://github.com/yuyolin)

每条消息我都会看，别客气，直接来。

## 📄 License

MIT — 自由使用，欢迎提 PR、提 issue、点 star ⭐