dsh-decision-log
DeepSeek Harness 决策日志：通过 decision_log / decision_list / decision_audit 工具把关键决策（选了什么 + 为什么）沉淀为可版本化的 DECISIONS.md，并在后续会话自动注入摘要，让决策可追溯、不重复、不推翻。
README
✨ 它是什么？一句话讲透
这个插件是给 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 文件夹，不上云：
▼text复制代码你的项目文件夹/ └── .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 助手），它会自动帮你装好、重启、跑冒烟测试：
▼text复制代码帮我安装 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 当成一个随身带小本本的助理。敲定一个决定，随口说一句：
▼text复制代码记一下：登录用 JWT 不用 session cookie
AI 秒懂，自己记好，还会回你：
▼text复制代码✅ 决策已记录到 D:\work\myproject\.dsh\DECISIONS.md（当前共 3 条） - 用 JWT 不用 session cookie（accepted） - 理由：跨端无状态，避免 session 同步
再多举几个例子，全是大白话：
- 🗣️
把刚才选 X 方案的决定记下来 - 🗣️
记住，缓存用 Redis 不用 Memcached，因为持久化更强 - 🗣️
我们定好了：数据库用 PostgreSQL，记一下 - 🗣️
图表库用 ECharts 不用 AntV，记个档
什么时候说这句话？ 记住一个直觉：凡是"我们最终选了哪个"这种话说出口，就补一句"记一下"。 两秒钟的事，未来省两小时。
玩法二：输入框敲命令（你想自己记的时候）
▼text复制代码/log-decision 用 Redis 不用 Memcached
想写详细点，带上背景和理由：
▼text复制代码/log-decision 用 Redis 不用 Memcached --context 缓存层选型 --reason 持久化更强
| 参数 | 意思 | 例子 |
|---|---|---|
--context | 在什么背景下做的决定 | --context 缓存层选型 |
--reason | 为什么这么选（最值钱） | --reason 持久化更强 |
--status | 状态，默认 accepted 不用管 | --status superseded（已推翻） |
改主意了？ 不用删，补记两条，完整保留"先这样、后那样、为啥变"的故事：
▼text复制代码/log-decision 缓存方案改为 Memcached --reason 团队更熟 /log-decision 用 Redis 不用 Memcached --reason 已换方案 --status superseded
玩法三：让 AI 记全套（信息量拉满）
▼text复制代码把刚才的选型记一下，要带上备选方案和理由
AI 会记全：决策 / 背景 / 备选方案 / 理由 / 涉及文件——一条完整记录。
记完随时可以查：
- 📖
查一下我们定过哪些事—— 列出所有决策 - 🔍
关于登录有没有什么决定？—— 关键词搜索 - 🧹
审计一下决策记录—— 检查有没有记重、记乱 - 📄
把决策文档导出来看看—— 查看完整内容
🧠 最妙的部分：换了新对话，它自己就记得
这是最省心的设计——你不用手动喂新对话。
每次新对话、每轮新开始，插件都会自动把"已定过的事"塞给 AI 看，就像 AI 入职前先读了一遍项目手册：
▼text复制代码📌 决策记录（已有 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 文件夹并生成空白文件（只有表头、零条记录），你随时可以打开看：
▼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 纯逻辑测试）
🗺️ 路线图
- 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 个新上下文
用着爽不爽、哪里卡壳、想要啥新功能，甚至想拉着我一起搞点新活——都欢迎来戳我：
- 📮 邮箱：yuyolin9@gmail.com
- 🐙 GitHub：yuyolin
每条消息我都会看，别客气，直接来。
📄 License
MIT — 自由使用，欢迎提 PR、提 issue、点 star ⭐
