dsh-ledger-watch

dsh plugin --profile web add dsh-ledger-watch

dsh-ledger-watch · 经验账本指示灯

一句话：踩过的坑不必再踩一次。 本插件自带一套最小账本工具（brief.ps1 查、add-lesson.ps1 记），安装时自动部署并接好 AGENTS.md：模型动手前查账本、踩坑后记成规则 —— 插件负责盯着它有没有真的这么做，并把结果摆在面板上。

目的：让模型真的在查经验账本、记下踩过的坑、修正失效的规则 —— 也就是自我提升 / 自我避坑 / 自我升级。

界面只是指示灯：显示「当前会话有没有查过账本」，以及经验账本的健康度。

它不是审计系统，不是监控用户行为的工具，也不生产规则（规则由 lesson-ledger 账本技能生产）。

装完即用：install.ps1 自己部署账本技能（brief.ps1 / add-lesson.ps1）并写入 AGENTS.md 托管块，用户不需要手工建目录、贴配置或跑脚本。首屏也不会指责你（没就绪时是一句说明，不是一根红条）。

上图是真实运行界面（会话 id 与证据文件路径已替换为占位符）：顶部一行是启用指示灯（本会话有没有查经验账本），下面是结论条、本会话指标、可疑信号、事件时间线，页脚是账本健康度与召回状态。

<details>

<summary><b>English summary</b></summary>

What it is. A bundle plugin for DeepSeek Harness that answers one question per session: did this session actually consult the lesson ledger, and did it record the pitfalls it hit?

What problem it solves. "I'll remember not to repeat that mistake" is unverifiable. This plugin turns it into data you can check: a per-session indicator, a closing-report callout, and the ledger's health (rules needing rework / rules already revised).

What it is not. Not an audit system, not user-behaviour monitoring, and it does not produce rules — the rules live in the lesson-ledger skill; this plugin only reports whether they were used.

Zero manual setup. install.ps1 provisions the ledger skill (brief.ps1 / add-lesson.ps1) and writes a managed block into AGENTS.md; no manual folders, config pasting or script runs. The first screen explains a missing setup instead of accusing you.

Optional auto-recall (default OFF). The host half can inject the most relevant ledger rules into the step as a system-reminder. It ships disabled because an independent acceptance pass measured ~69% precision on an 87–100 entry Chinese ledger; enable it with recallMode: 'high-confidence' only after reading the admission thresholds in the repo's own quality gate. The panel always shows the current state of this switch, including when it is off and why.

Zero runtime dependencies. The host half uses only Node built-ins; the browser half requires only React (provided by the host).

</details>

两个界面

界面 · 插槽 · 说明

会话顶部 tab「经验账本」 · conversation.view（order 30，在「画廊」之后） · 主界面：启用指示灯 + 账本健康度 + 本会话指标 + 可疑信号 + 事件时间线 + 其它会话

输入框下方药丸 · conversation.composer.dock（5 秒轮询） · ● 账本 5 / 11，圆点颜色 = 结论；在本 tab 内随输入框一起隐藏且停止轮询

本 tab 在屏时会隐藏宿主输入框（[data-composer-seat] + 把 --dsh-composer-height 归零），切走即恢复。

指示灯与判定口径

显示 · 含义

避坑功能已启用（绿） · 本会话查过账本（queries > 0）

避坑功能未启用（红） · 本会话一次都没查过账本，但已经在动工具

本会话不在监视范围内（灰） · 插件从没观测到这个会话（sessionKnown === false）：重启前就已存在的会话、或跑在别的进程里的会话。与「没查账本」是两回事，不能混为一谈

结论 又查又记 / 查了没记 / 记了没查 / 未查询 / 无活动 · 由 queries 与 records 组合得出；「不在监视范围内」时不显示结论（没有观测就没有结论）

⚠ 补记横幅 · needRecord：本会话有失败的工具调用，却一条坑都没记 → 收尾请用 add-lesson.ps1 补记

首次使用（没装账本技能时）

插件不生产规则。ledgerDir（默认 ~/.agents/skills/lesson-ledger）里没有 lessons/ 与 workspaces/ 时，

面板不会判红（那不是你的错，是还没有账本可查），而是出一张引导卡：

1. 装 lesson-ledger 技能（把该目录放进你的技能目录）；

2. 把一段 AGENTS.md 片段贴进去（开工自报，让模型每次先查账本）—— 卡上可以一键复制；

3. 用 add-lesson.ps1 记第一条坑。

三种状态由 scanLedger() 给出，界面据此分流：missing（技能没装）/ empty（技能在、零条目）/ ready（可查）。

观测范围（重要）

插件只在 DSH 运行期间通过 ctx.on('tools/result') 观测工具调用，因此：

• 内存里只有本进程启动之后见过的会话；state() 会把内存与证据文件 .watch.json 合并后再返回，

所以重启前活跃的会话仍能显示自己的历史计数（读路径与写路径共用一份合并，见 mergeWithPrevious）。

• 从未被观测到的会话（插件安装之前的老会话、或运行在其他进程里的会话）没有数据可补，

界面会明确显示「本会话不在监视范围内」，而不是「本会话还没开始」——后者会让人误以为所有会话内容一样。

• 落盘的会话列表上限 10 条（payload.sessions.slice(0, 10)），界面「其它会话」再截断到 8 条（SESSION_LIMIT）；

内存里最多保留 24 条（MAX_SESSIONS）。

计数口径（2026-10-27 评审后收紧）：

• 只认命令位真的调用了账本脚本（& …\brief.ps1、pwsh -File …\add-lesson.ps1、行首裸调用、任何路径形式）；

字符串字面量、注释、只是路径里出现 lesson-ledger 的无关命令都不算。

• 文件类工具：file_path 必须落在账本目录内；读证据文件本身不算（自指）。
• skill 工具加载 lesson-ledger 算一次查询。
• 失败的调用不算查询/记录（失败的 brief.ps1 没有产出任何信息）——只进事件流并计入 failures。
• 「记录 N」是动作次数，不等于「新增了 N 条坑」（同一条目反复编辑会重复计数）。

它怎么判断「这是不是一个坑」

它不判断。 插件不做语义判断，它只回答两个问题：这个会话有没有查过经验账本、有没有把坑记下来。判断「这段经历算不算坑」的是模型，判据写在账本技能与 ~/.dsh/AGENTS.md 里（用户纠正、同类错误第 2 次、失败原因不显然、实测与旧结论冲突、定位超 10 分钟）。

插件能做的是把可疑事件标出来，提醒模型回头看一眼。目前采集五类可观测信号：

信号 · 判据 · 对应的坑类型

failures · 工具调用失败（ok:false / isError / 数字退出码 / 结果文本里的 [exit code: N]） · 失败原因不显然

retries · 连续两次「同一工具 + 同一参数」（写类工具除外，它由下一项覆盖） · 同类错误第 2 次

rewrites · 同一个文件被写/改到第 3 次及以上 · 之前理解错了

corrections · 用户消息里出现纠正标记词（不对 / 错了 / 又犯 / 我说过 …）——只匹配标记词，不保存用户原文 · 用户纠正

churn · 工具调用 ≥ 25 次却一条坑都没记 · 干了很多活、什么都没沉淀

当 records === 0 且任一信号非零时，面板出 ⚠ 横幅、收尾自报点名，并写出具体是哪些信号（例如「失败调用 2 次 · 用户疑似纠正 1 次」）。

信号行常显：指标下方始终有一行 可疑信号：失败 2 · 重复 1（没有就显示「暂无」）。

原来只在「零记录」时出一条横幅 —— 用户记了一条坑，整块就消失了，48 条用例建起来的引擎没有出口。

边界：信号 ≠ 坑。失败调用可能只是探针故意跑失败；用户说「不对」也可能只是改需求。所以插件只提醒、不判定，也不会因为信号非零就自动往账本里写东西。

数据从哪来

宿主半边订阅 tools/result 与 session/event，把结果写成证据文件（宿主 console 模型读不到，只能落盘）：

~/.agents/skills/lesson-ledger\.watch.json

关键字段：build、ledger{entries,relapse,revised}、writeFailures、client（客户端回报自己的 build）、

current{queries,records,calls,failures,enabled,needRecord,verdict,events}、sessions[]。

写入是原子替换（tmp + rename，Windows 瞬态错误退避重试，退避用尽降级为直接写），

并会合并文件里已有的会话统计 —— 多实例或重启不会互相清空历史。

收尾自报（tools\closing.ps1）也会点名：本会话查了几次、记了几次、结论是什么。

安装（推荐：从 npm 装）

已发布到 npm：dsh-ledger-watch。这是唯一能进 DSH 插件市场搜索的形态（市场索引只收 npm 包）。

dsh plugin --profile web add dsh-ledger-watch
# 然后跑一次安装器把技能与 AGENTS.md 接线补齐（它不会重复下载包，只做本地配置）
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

也可以直接从 GitHub 装（不进市场搜索，但能跑）：

dsh plugin --profile web add github:OldManDing/dsh-ledger-watch

安装与生效方式（重要）

本包是 bundle 型插件（浏览器半边只能靠 bundle 进启动载荷）：

"dsh": {
  "bundle": { "patch": "./cordis.patch.yml" },
  "client": { "platform": "we

…(truncated)