dsh-decision-log

✨ 它是什么？一句话讲透

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

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

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

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

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

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

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

• 自动新建一个文件夹：<你的项目>/.dsh/（它放小本本的地方）；
• 自动放一本空白的 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" 即可。

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

# 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 字符）

整套闭环长这样 👇

📁 记下来的东西，长这样

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

---
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 通吃

🛠️ 开发

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

🗺️ 路线图

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

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

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

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

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

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

• 每轮对话开始，只挑文件里最新的一批决策给 AI 看（不是全部）；
• 攒到 2000 字符就打住，多出来的不看了，只留一行小字：(... 其余 N 条见 .dsh/DECISIONS.md)；
• 想看全部？随时喊 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 个新上下文

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

• 📮 邮箱：[e-mail]
• 🐙 GitHub：yuyolin

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

📄 License

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