dsh-ledger-memory（台账记忆）

一个 DSH（DeepSeek Harness）宿主侧插件：让 AI 用可复现的方式，把项目里的工作记住。

它管的不是聊天记录，而是一个项目自己的记忆载体 —— 台账： 可回溯、可追查、只追加、按周归档。围绕它还有活动日志、上下文压缩与跨会话交接。

不预设任何模板 —— 台账的文件名、分几个文件、有哪些字段，全部由 AI 在初始化时 按项目类型自己决定；插件只做检测 / 注入 / 回写 / 归档 / Git 配合这些流程性工作。

---

它解决什么问题

问题	它怎么做
换个会话就"忘了这个项目干到哪"	会话开始把活跃台账全文注入上下文；内容没变则不重复注入（防打烂 prompt 缓存）
AI 走完一轮，成果没落地	回合末把「完成了什么 / 卡在哪 / 下一步」写回活跃台账
台账越来越长，读不完	超阈值时把最旧的已完成条目移进 归档目录/YYYY-MM/weekN，只追加不删除
细节被上下文压缩抹掉	压缩之前把用户原话、报错原文、改过哪些文件落盘成一份逐字胶囊；压缩后与台账一起注回
新会话接不上旧会话	写一份交接单，并把指针推进新会话的第一轮注入（不是等你来问）
想查"谁什么时候改过这份台账"	台账末尾自动维护一张变更登记；完整历史在只追加的活动日志里
只是一次性排查，不是项目	ledger_note 写一份问题记录（现象 → 根因 → 结论 → 做了什么），不建台账

三层上下文压缩

层	触发	做什么
① 常态 · 增量	水位比上次压缩涨约 20 点	只压最旧一段，把上涨的 20 点压成 10 点
② 兜底 · 全量	水位到 70%（内核默认是 80%）	全量压缩，但保留指向所需内容的指针：用户原话 / 报错原文 / 改过哪些文件 / 去哪重读
③ 终局 · 交接	你要换会话时	交接单让新对话无缝接上

① 是棘轮，不是"压回原位"：每轮压掉固定的一段（默认 10 点），水位于是逐级上抬—— 设计轨迹是 10 → 30 → 20 → 40 → 30 → 50 → 40 → 60 → 50 → 70， 第五、六次增量就撞上 70% 的全量压缩。 ★ 两个设置项配套：deltaTriggerPoints（涨多少点触发，默认 20）与 deltaRemovePoints（每轮压掉多少点，默认 10）；差值就是净涨。

⚠️ 诚实标注：上面那条轨迹是设计意图与数学推演，不是实测录像。 棘轮逻辑经过离线自检与逐行数学核验，但修复后的真实长会话轨迹尚未被独立测量 —— 这一点在项目台账里也如实记着。若你在真实使用中发现水位长时间在同一区间摆动， 那正是需要反馈的现象。

围绕这三层有一条铁律：先记台账，再压缩。水位提醒发出的那一刻，插件会记住 「已经要求它写台账了」，在它写完之前不压缩 —— 否则压掉的正是这一轮唯一的那份进展。

安装

需要 Node.js ≥ 22.19。

# 走 npm
npm install dsh-ledger-memory

# 或走 DSH 自己的插件命令
dsh plugin add dsh-ledger-memory

装完重启客户端才生效 —— 内核对已加载的插件不会因文件改动自动重载。

升级（★ 如果"界面显示有新版本，却怎么装都是旧的"，看这里）

从 1.0.0 起，正常升级不需要做任何特殊操作 —— ^1.0.0 允许整段 1.x， 所以 1.1、1.2 都在范围内，能自己爬上去。

但如果你是更早的 0.x 版本升上来、且恰好卡住了，那是两个叠加的原因：

1. 依赖被写成 ^0.1.0 这种旧范围。 0.x 的插入符语义是 ^0.1.0 = >=0.1.0 <0.2.0 —— 不允许跨次版本，所以天花板永远是 0.1.1。 （1.x 没有这个问题：^1.0.0 的天花板是 2.0.0。）
2. pnpm-workspace.yaml 里可能留着一行过期的豁免（pnpm 装成功时会自己往这里追加）：

   minimumReleaseAgeExclude:
     - dsh-ledger-memory@0.1.0     # ← 这行就是枷锁
   

   ★ 卸载重装治不好它 —— 卸载动不了这个文件。这也正是"反复卸载重装仍是旧版"的原因。

修法：

cd <DSH_HOME>/profiles/<你的 profile>
cp package.json package.json.bak           # 备份
pnpm add dsh-ledger-memory@1.0.0           # ★ 关键就这一步：按精确版本装
# 然后重启客户端

★ 为什么"按精确版本装"这一步就能破局（实测）： pnpm 会把那一行自己改成 - dsh-ledger-memory@0.1.0 || 1.0.0（追加而非替换）， 于是新版本进了候选集，解析就取其中最新的 ⇒ 一步到位。

★ 建议顺手把那行清掉（不是必需，但更干净）：删掉 pnpm-workspace.yaml 里 - dsh-ledger-memory@… 那一行，以后就不会再有歧义。

自查（不需要任何额外文件）：打开 <DSH_HOME>/profiles/<你的 profile>/pnpm-workspace.yaml，看有没有 - dsh-ledger-memory@ 开头的那一行。有 ⇒ 就是它；没有 ⇒ 问题在依赖范围（上面第 1 条）。

本仓库里另有一个更省事的只读诊断：node tools/_probe-install-version.mjs。 ⚠️ 它只在本仓库里有、不在 npm 包里（包内只有 lib/、README.md、 cordis.patch.yml、package.json 与 tools/selftest.mjs）—— 所以从 npm 装的用户请用上面那条手工自查。

用法

不用配置什么。打开一个项目目录开始工作，插件会：

1. 发现这里还没有台账 ⇒ 注入一句提示，让 AI 来问你要不要初始化（它不会自己动手）；
2. 你同意后，AI 按这个项目的类型设计一套台账结构并登记；
3. 之后每个会话自动加载台账；到水位（或你要求）时，插件会提示 AI 回写并归档。

★ 说清楚"自动"到哪一步（免得你以为全自动）： 插件不会自己去写台账或归档 —— 它做的是在恰当的时机把指令注入给模型， 由模型调用 ledger_write / ledger_archive 完成。 这是刻意的：台账内容需要判断（什么值得留），而插件没有那个判断力。 因此模型忽略指令时，那一轮就不会落盘 —— 插件会在下一步再要求一次（闸门机制）。 回合末那张四选一卡片默认关闭（turnEndOffer），需要可在设置里打开。

手动命令

在对话里敲 /ledger（不带参数会弹一张可点的卡片），或用子命令：

/ledger status     看状态（有没有台账、用的哪个文件、几行、Git、日志开关）
/ledger show       把当前活跃台账全文打出来
/ledger init       初始化台账（由 AI 为这个项目设计一套结构）
/ledger update     让 AI 把本次会话的进展写回台账
/ledger archive    把最旧的已完成条目移进归档目录
/ledger compact    立刻做一次全量压缩（保留指针）
/ledger light      轻量压缩
/ledger log        查活动日志
/ledger handoff    写一份交接单
/ledger mode       看/切换压缩模式（steady / surgical）
/ledger lock       把本场对话锁到某个项目目录（总工作区里用）

对话建在总工作区时：锁定到子项目

有时对话是建在装着多个项目的总工作区上的。那时插件无从判断"这次说的是哪个项目"， 默认就都落在当前目录。解决办法是锁：

/ledger lock 20-DSH插件/04-其余插件/10.项目台账

锁定后，本场对话的所有工具调用都落在那个目录上，不必每次再指定。 /ledger lock 不带参数看当前状态，/ledger lock off 解锁。 会话第一轮弹的那张卡片里也有这个选项。

★ 锁定会记住：重启、关掉再开都还在，每场对话各记各的，互不影响。 记录放在 DSH 自己的数据目录（plugin-data/）里 —— 不在你的工作区里： 不建注册表、不在目标目录留任何标记，你的项目目录不会因此多出一个文件。

★ 若当前目录自己就有台账，仍以当前目录为准 —— 锁只接管"没有台账"的目录。

★ 锁的目标目录被删掉或搬走后，这条锁自动失效（回到按工作目录解析）， 不会让后续操作指着一个不存在的地方报错。

设置面板

设置 → 项目台账（台账 / 压缩 / 日志），可调十三项：压缩模式、回合末卡片开关、 高保真压缩水位、增量压缩的触发涨幅与每轮压掉多少点、活动日志五档开关、活跃台账行数上限、 变更登记条数、水位提醒档位等。

一条要知道的语义：mode / maxActiveLines / changeRegisterMax / logLevels 以每个项目自己清单里的值为准。面板里这几项是新项目初始化时写进去的默认值。

两个压缩模式

压缩方式可以按项目选。默认是「正常推进」，两者共用同一套压缩，区别只在压缩前后多做或少做什么：

	正常推进（steady，默认）	反复追究（surgical）
压缩时怎么切	按位置：只压最旧一段，更早的一刀切	按内容分流，再压
谁做判断	不用判断（省一次模型输出）	AI 做一次分流
适合	一路向前干活	要反复回看约束与假设的活

「反复追究」怎么工作：水位到点时会先让 AI 调 ledger_triage 把这一段分成三个桶 ——

• 留（keep）：下一轮不知道就会做错的东西（当前状态、未验证的假设、你定过的约束）。压缩后逐字注回。
• 落（stash）：以后可能要查、但不该占上下文的（判断与理由、走不通的路、关键文件位置）。 写进项目的 _stash/，永不注入，需要时自己 grep。
• 丢（drop）：已被取代的，只进日志。

keep 有条数上限——留得太多等于没压，超了会按 AI 给的顺序截断并如实报出截掉几条。

切换：设置面板里选，或 /ledger mode steady / /ledger mode surgical（只影响当前项目）。

十四个工具

AI 在对话里调用，你也可以让它调用：

工具	作用
ledger_status	报告这个项目的台账状态（只读）
ledger_read	读台账 / 决策记录 / 归档
ledger_write	写活跃台账或决策记录
ledger_init	登记台账结构（四条硬约束：一个活跃台账 / 一份独立决策记录 / 一个只追加归档目录 / 行数上限）
ledger_archive	把旧条目移进只追加的归档
ledger_conform	检查一个既有项目的台账是否符合预期，能修的只做加法
ledger_note	写一份问题记录（非项目场景，有终点的那种）
ledger_log	查活动日志（五档，从不注入上下文）
ledger_log_write	追加一条回合小结
ledger_handoff	写交接单，供下一个会话接手
ledger_triage	把阶段性产出分成「留 / 落 / 丢」三个桶（「反复追究」模式用）
ledger_lock	把本场对话锁到某个项目目录（会记住，重启也在；记录不在你的工作区里）
ledger_compact	请求一次高保真压缩
ledger_checkpoint	把这一刻的选择交给用户（记台账 / 记+压缩 / 记+交接 / 跳过）

活动日志（五档）

挂在你为项目登记的日志目录下，只追加、永不改写，且从不注入上下文（按需查）：

档	内容
L0	台账变更的里程碑
L1	回合小结（带会话编号）
L2	文件流向
L3	工具调用流水（默认关）
L4	逐字存档你说过的每一句话（带会话编号与时间）

采集类档位只认会话的工作目录，不会去猜子项目。 在一个装着多个项目的目录里开会话时，采集类档位写不出东西 —— 这是刻意的。

依赖与许可

• 零运行时依赖（dependencies 为空）
• 唯一 peer 依赖：@deepseek-ai/cordis
• 许可：MIT

自检

仓库里带一套离线自检，不需要网络、不需要装 DSH：

npm test

已知边界

• 注入走 agent/pre-step（可替换本轮消息），不是 systemPrompt.context。
• 改代码后必须重启客户端，内核对已加载插件不会热重载。
• 采集类日志档位在"容器工作区"（装着多个项目的目录）里写不出东西。
• 压缩服务只能经 agentPresets.serviceFor(agent, "compaction") 取到，ctx.get("compaction") 恒为 undefined。