dsh-gokifu-compact 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 更新记录
 
+## 1.8.1 — 2026-10-29
+
+### doctor：一天的 fold 收益一眼可见
+
+- 新增「今天 fold 的总量」：`N 次（M 个会话）· 合计遮蔽 X tokens` —— 数据来自各会话棋谱的
+  `foldMarks`（按 fold 发生的 `at` 过滤，不按文件 mtime），不用翻会话日志
+- 实测（2026-10-29）：今天 26 次 fold / 12 个会话 / 遮蔽 **2,304,388 tokens**；重启后 **0 失败**
+- 「上次 fold 的成本」继续显示真实 usage（含 provider 缓存字段：一次缓存命中的 fold 只有
+  5,329 新输入 + 647,168 缓存读，冷启动那次则是 629,184 全新输入）
+
+## 1.8.0 — 2026-10-29
+
+### 配置 id 统一 + 安装改成「两条命令、不用手改 YAML」
+
+- **配置项 id 改名**：preset 里的 `- id: chess-context` → `- id: gokifu-compact`，
+  与展示名 `dsh-GOkifu-compact` 对齐（注入消息的 `source.kind` 仍是 `chess-context` ——
+  那是跨版本的数据契约，改了会让历史会话里的旧清单认不出来）
+- **新增 CLI**：`dsh-gokifu-compact install | revert | doctor`
+  - `install` 自动找 profile/preset，把 preset 的 compaction group 里
+    `@deepseek-ai/dsh-compaction-basic` 那一行换成 `dsh-gokifu-compact`；
+    带备份（`.bak-before-gokifu-*`）、幂等、`--dry-run`、旧 id 自动纠偏
+  - `revert` 恢复最近一次备份；`doctor` 转发体检
+  - 逻辑只有一份（`scripts/install.mjs`），`test/install.mjs` 变成薄封装
+- **不再声明 `dsh.bundle`**：本插件是「agent preset 内的压缩后端」，不是 profile 级 bundle。
+  声明 bundle 会让 `dsh plugin add` 把它塞进 `dsh.profile.bundles`，于是顶层再挂一份，
+  与 preset 内那份形成双实例（`ctx.compaction` 只能注册一次 ⇒ 构造期抛错）
+- preset 示例默认写 `auto: true`：关掉原生 `compaction-basic` 不影响自动压缩 ——
+  本插件继承同一个 `BasicCompactionEngine`（同一套 between-step 压力触发与 context-overflow 兜底），
+  换的只是「压缩范围 = 上一个 checkpoint 之后」和「失败记忆逐字保留」
+- `doctor` 新增两项检查：压缩后端已接管 / 原生已让位
+- README 安装段重写为两步命令；新增 FAQ「关掉原生压缩，自动压缩还在吗？」
+
+### 真机首折实测 + 三处收尾修复
+
+- **GUI 里第一次真实 fold 成功**（重启后第一轮触发，`session-e16faf2b`）：
+  遮蔽 seq 9–3167 / **440,847 tok** → 摘要 2 块 4.2K 字符（输入 629,184 / 输出 2,902 tok，`magpie/group/deepseek-v4.1-flash1017`）；
+  surface 节点 1391 → 373，对话消息从 ~574K 降到 ~157K（面板 81% → 约 16%），热清单仍只有 1 条（就地替换生效）
+- **修 `graph.checkpointSeq` 记错**：原来写「被遮蔽区间起点」（fold 后已不在 surface 上，实机一直是 9），
+  改成写「checkpoint 消息的 seq」
+- **`doctor` 三处改进**：压缩统计改 **1 小时窗口 + 最近成功/失败时间**（历史失败不再吓人，
+  判定看「最新一条是不是成功」）；新增「上次 fold 的成本（真实 usage）」；树新鲜度支持批量修复
+- **`test/build-tree.mjs --all`**：一次性重建所有 index.md 落后于 graph.json 的会话（本次修了 48 个 / 1760 个节点文件）
+- **摘要输出上限抬高**：`maxTokens` 默认 2048 → 4096，preset 3072 → **8192** ——
+  实测一次 fold 用掉 2,902 tok，3072 太贴边，触顶会 MAX_TOKENS 截断（截断 = fold 失败）
+- **`graph.lastFoldUsage`**：每次 fold 的真实 usage（输入/输出/provider/model/时间）写进棋谱，计费对账不必再翻会话日志；
+  `doctor` 对新旧图都能显示（旧图没有该字段时从会话日志的 `compaction/summary` 事件兜底）
+
+### 测试
+
+118 项单测全绿 · `verify-install` 13 项全过（含 isolate group 内仍是我们的引擎行）
+
 ## 1.7.1 — 2026-10-29
 
 ### 发布后收尾

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MYCF711
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,261 +1,196 @@
 # dsh-GOkifu-compact
 
-> 已发布：npm `dsh-gokifu-compact@1.7.0` · [GitHub Release v1.7.0](https://github.com/MYCF711/dsh-GOkifu-compact/releases/tag/v1.7.0)
-> 安装：`dsh plugin --profile <name> add dsh-gokifu-compact`
+> 已发布：npm [`dsh-gokifu-compact@1.7.1`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Release v1.7.1](https://github.com/MYCF711/dsh-GOkifu-compact/releases/tag/v1.7.1)
 
-> 已经装好了？直接看 [快速开始](QUICKSTART.md)。
+**DSH 的棋谱式上下文压缩后端 —— 把「历史 → 一段摘要」换成「历史 → 可复盘的棋谱 DAG + 每步只有 323 tokens 的热清单」。**
 
-> **为什么叫 GOkifu-compact** —— **GO（围棋）+ kifu（棋谱）+ compact（压缩）**。
-> **展示名用大写 GO**（`GO` 才是围棋，`go` 是编程语言）；**npm 包名只能小写**（`dsh-gokifu-compact`，这是 npm 的硬限制）。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。这个插件做的事一样：把 agent 每一步变成一手棋（节点），把当时的思考变成评语（节点的目标 / 约束 / 失败原因），把整个任务变成一局可复盘的棋。高价值的棋局几年后仍能记起整盘怎么下；走到关键处，旧棋谱会吊起记忆，让人悬崖勒马。
+```
+热清单     323 tokens       （2000 边压力测试；旧版全量渲染 28,800）
+失败保留   8 / 8            （真实模型对照；官方 8 段模板 4.67 / 8）
+清单开销   0.2% of prompt   （v1.3.1 起；事故会话的旧版是 21.3%）
+验证       118 项单测 · 真实包 8/8 · 真实进程 fold 3~6/6
+```
 
-### 围棋术语对照（设计说明）
+GO = 围棋，kifu = 棋谱，compact = 压缩。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。
+这个插件把 agent 的每一步变成一手棋（节点）、把当时的思考变成评语（目标 / 约束 / 失败原因），
+整个任务变成一局可以复盘的棋。**棋谱是给模型用的，不是给人看的** —— 热清单里的每个字都为模型决策服务。
 
-| 中文 | 日文 | 英文 | 本插件对应 |
-|---|---|---|---|
-| 本手 | 本手（ほんて） | honte / proper move | 成功路径（标准定式） |
-| 恶手 | 悪手（あくしゅ） | aku / bad move | `[dead]` —— 没有成功路径经过 |
-| 俗手 | 俗手（ぞくしゅ） | zokusu / vulgar move | `[redundant]` —— 表面正常，实际多走了 |
-| 新手 | 新手（しんしゅ） | shinshu / new move | `[novel]` —— 探出新状态 |
-| 缓手 | 緩手（かんしゅ） | kanshu / slow move | `[longer]` —— 绕远 |
-| 手割 | 手割（てわり） | tewari | 手割分析（判断谁亏谁赚） |
-| 胜负手 | 勝負手（しょうぶて） | shobute | 关键决策点（未实现） |
+---
 
-**热清单里的标签仍用英文短词**（`dead` / `redundant` / `novel` / `longer`）——
-模型训练数据里这些词的出现频率比 `aku` / `zokusu` 高几个数量级，
-标签是给模型**执行**的，不是给人**欣赏**的。术语表放这里（给人看设计理念）。
+## 功能
 
-## 三层文件树
+- **增量 fold** —— 只压「上一个 checkpoint 之后」的新内容；一段历史一生只被摘要一次。
+- **失败记忆** —— 每条失败尝试的意图 / 动作 / 报错原文 / seq 由规则抽取并**逐字**保留，模型没有丢弃它的权限。
+- **手割（tewari）** —— 同一条失败边相对**每条**成功路径分别给结论：同型 / 绕路 / 探新，不是一个笼统的「失败」。
+- **热清单** —— 每步重建的小清单：语义标记（`blocked:permission` / `dead retry-if:e1`）+ 动态图例 + 报错原文；**就地替换**，surface 上永远只有一条。
+- **置换检测** —— 状态哈希命中历史节点时不新建分支，只在图上加一条边，并提示「回到节点 N —— 这里试过的路都记着」。
+- **三层树** —— `index.md`（全量索引）/ `nodes/<id>.md`（单节点细节）/ `graph.json`（数据源），模型按需往下查。
+- **压缩永不失败** —— 摘要三层降级：配置的摘要模型 → 当前路由模型 → 规则摘要（零模型调用），fold 一定能落地。
+- **可诊断** —— `doctor` 一条命令体检、`measure-billing` 按真实 usage 对账、`rewash` 回洗历史误报。
 
-每次 flush 额外写三层（`graph.json` 是数据源；`graph.md` 按需生成，见下）：
+## 怎么工作
 
-| 文件 | 内容 | 谁用 |
-|---|---|---|
-| `index.md` | 落子顺序（每节点一行 + 出边状态） | 模型先读这个 |
-| `nodes/<id>.md` | 单节点：评语 / 状态 / 入边 / 出边 / raw 链接 | 模型按需读 |
-| ~~`raw/<seq>.md`~~ | 已砍掉 —— 节点 JSON 与 `graph.json` 重复 | — |
+```
+每一步：事件流 ──► 棋谱 DAG（节点 = 状态；边 = 尝试 + 验证信号）
+                        │
+                        ▼
+              热清单（根目标 / 约束 / 成功路径 / 失败边）──► 注入模型
+                        │
+             到阈值（默认窗口 45% 且增量 ≥ 40K）
+                        ▼
+              增量 fold：只压上一个 checkpoint 之后 ──► 棋谱摘要（失败边逐字保留）
+```
 
-**设计依据**：`evidence/棋谱有效性实验.md` —— 干净子代理实验证明三层缺一不可：
-索引让模型看到全部死路，节点给详情，原始补抽取的漏。
+和官方 `dsh-compaction-basic` 的区别：
 
-旧会话补文件：`node test/build-tree.mjs <sessionDir>`。
+| | 官方 `compaction-basic` | 本插件 |
+|---|---|---|
+| 压缩范围 | 从 surface 第一个非 system 节点起（**含上次 checkpoint**） | 上一个 checkpoint **之后** |
+| 保留率 | 每轮重摘 → 按 ρ^k 衰减（实测安全规则 5 轮后剩 10%） | 一段内容只摘一次 |
+| 失败记录 | 融进散文摘要，模型可以丢 | 规则抽取 + 逐字注入，模型无权丢 |
+| 热上下文 | 无 | 323 tokens / 步，带语义标记与报错原文 |
 
+### 热上下文长什么样
 
-DSH（DeepSeek Harness）的上下文压缩后端。它把「历史 → 一段摘要」换成
-**「历史 → 棋谱 DAG（节点=状态，边=尝试+结果+验证信号） + 每步重建的极短热上下文」**。
+每步 `agent/pre-step` 注入（内容不变时复用；变了就**就地替换**上一条，surface 永远只有一条）：
 
-三句话讲清它和市面上所有方案的区别：
+```
+<chess-ledger>
+ROOT USER (verbatim): 把 tests/case*.test.js 跑绿：缓存键算错了。不要动 prod 配置。
+CONSTRAINTS (verbatim):
+- 不要动 prod 配置。
+CURRENT GOAL: 缓存键修好，case7 通过
+WORKING: user → n2 (exit 0)
+LEARNED (3 failed attempts):
+TRACE: <sessions>/<sid>/index.md  (per-node detail: nodes/<id>.md)
+# markers:
+#   dead = a working path avoids it — retry only if retry-if breaks
+#   redundant = working edge <edge> reaches the SAME position — take it
+#   blocked:permission = needs a permission this environment lacks — retry when it changes
+- e2 "把缓存键改成 JSON.stringify 全部参数" → AssertionError: case7 expected 1 got 2 … [dead retry-if:e1]
+- e3 "装全局 sqlite 依赖后再跑" → npm ERR! EACCES: permission denied, mkdir … [blocked:permission]
+</chess-ledger>
+```
 
-1. **增量 fold**：每次只压「上一个 checkpoint 之后」新增的部分 —— 一段内容一生只被摘要一次。
-   官方 `dsh-compaction-basic`（以及绝大多数商业 harness）每轮都把上一次的摘要再摘要一遍，
-   早期约束与否定结果按 ρ^k 衰减（Compaction Cliff 实测：安全规则 5 轮后只剩 10%）。
-2. **失败记忆是一等公民**：每条失败尝试（意图 / 动作 / 报错原文 / seq 坐标）由规则抽取，
-   **逐字**注入摘要 prompt，并在每步的热上下文里重建。模型没有「决定丢掉它」的权限。
-3. **置换检测**：状态哈希（世界状态 + 已知约束集）命中历史节点时，不新建分支，只在图上加一条
-   指向旧节点的边，并提示「回到节点 N —— 这里试过的路都记着」。
+预算不够时**降级不丢边**：先缩短意图与报错，再砍 seq，最后只列最近 N 条 + 汇总行。
+标记档位可调：`semantic`（默认）| `terse`（只写三态）| `off`（不打标记）。
 
----
+## 安装
 
-## 装
+**两步，不用手改任何 YAML。**
 
 ```bash
-# 1) 先看要改什么（不写盘）
-node test/install.mjs --dry-run
+# 1) 装包（DSH 会把它作为普通依赖装进 profile；不会把它塞进 bundles，避免双挂载）
+dsh plugin --profile <profile> add dsh-gokifu-compact
 
-# 2) 装（会备份 profile/package.json 与 preset 的 cordis.patch.yml）
-node test/install.mjs
+# 2) 一条命令接管压缩后端（自动改 preset 的 compaction group，带备份、可回滚、幂等）
+npx dsh-gokifu-compact install --profile <profile>
 
-# 3) 重启 DSH 后按 docs/重启后验证清单.md 四条确认
+# 3) 重启 DSH（插件在启动时加载），然后自检
+npx dsh-gokifu-compact doctor
+```
 
-# 回滚
-node test/rollback.mjs
+> 第 1 步会打印一条 `declares no dsh.bundle — installed as a plain dependency` —— **这是预期的**：
+> 本插件挂在 agent preset 里，不做 profile 级 bundle（做了会在顶层再挂一份，与 preset 内那份双实例冲突）。
+
+第 2 步做的是**唯一一件必须改文件的事**：把 agent preset 的 compaction group 里
+`@deepseek-ai/dsh-compaction-basic` 那一行换成 `dsh-gokifu-compact`。为什么脚本必须改文件而不是
+自动在启动时生效——因为那一行在 preset 的 `config.plugins` 数组内部，profile 级 / bundle 级的
+patch 打不到它（`applyEntryPatches` 只递归 `group: true` 且 `config` 为数组的条目）。
+脚本替你改、替你备份、也能替你还原：
+
+```bash
+npx dsh-gokifu-compact install --dry-run     # 先看会改什么（不写盘）
+npx dsh-gokifu-compact revert                # 还原（恢复 .bak-before-gokifu-* 备份）
 ```
 
-安装做三件事：
+**从源码（开发用，一条命令含链接 + 改 preset + 校验）**
 
-| # | 动作 | 为什么 |
-|---|---|---|
-| ① | `<profile>/node_modules/dsh-gokifu-compact` → 本项目的 junction | 让 preset 能按包名解析到它 |
-| ② | `profile/package.json` 的 `dependencies` 加一条 `link:` | 供 pnpm 感知（**不加 `dsh.profile.bundles`**，否则会在顶层再挂一份，与 preset 内那份冲突） |
-| ③ | preset 的 `cordis.patch.yml` 里把 group 内的 `compaction-basic` 换成 `dsh-gokifu-compact` | 真正生效的是 preset 内那一份（见 `docs/DSH-技术测绘.md` §9 陷阱 4） |
+```bash
+git clone https://github.com/MYCF711/dsh-GOkifu-compact.git
+cd dsh-GOkifu-compact
+node test/install.mjs --dry-run   # 预演
+node test/install.mjs             # 真装
+node test/rollback.mjs            # 回滚
+```
 
-> ⚠ **单实例硬规则**：`ctx.compaction` 在同一 isolate realm 里只能注册一次，
-> 注册第二个会在构造期抛 `service "compaction" has been registered`，并连带整个 preset generation 挂掉。
-> 安装脚本会把旧行替换掉，不要手工复制一份。
+> ⚠ **压缩后端只能有一个**：`ctx.compaction` 在同一 isolate realm 里只能注册一次，同时挂
+> `dsh-compaction-basic` 会在构造期抛 `service "compaction" has been registered`，并连累整个
+> preset generation。安装器做的就是「换掉那一行」；不要手工再复制一份。
 
 ## 配置
 
 ```yaml
-- id: chess-context
+- id: gokifu-compact
   name: 'dsh-gokifu-compact'
   config:
+    auto: true                # 自动压缩（继承基类的 between-step 压力触发）
     thresholdRatio: 0.45      # 压力闸：min(窗口×0.45, 窗口−输出预留−64K)
-    headroomTokens: 65536
-    retainRatio: 0.16         # 逐字保留的近期尾部
-    retainTokens:             # 或给绝对值（与 retainRatio 互斥）
     growthFloorTokens: 40000  # 增长闸：距上次 fold 至少新增这么多 token
-    minFoldTokens: 8000       # 被遮蔽内容少于这个数不值得压
+    retainRatio: 0.16         # 逐字保留的近期尾部
     summaryMode: hybrid       # hybrid | rules（零模型调用）| llm
-    maxTokens: 2048
-    summarizationProvider: magpie                 # 留空=跟随最近一次路由
-    summarizationModel: ima/deepseek-v4.1-flash   # 推荐：ima 免费模型，实测 8/8 死路、2/2 约束
+    maxTokens: 8192           # 摘要输出上限（实测一次 fold 用到 2,902，留足余量防截断）
+    summarizationProvider: '' # 留空 = 跟随当前路由（最稳）
+    summarizationModel: ''    # 想用免费模型，先确认 provider 的模型表里有那个 id
     hotLedger: true           # 每步注入失败清单
     hotLedgerMaxTokens: 500
-    hotLedgerMarkers: semantic # semantic（带语义+图例）| terse（只三态）| off
-    hotLedgerReplace: true   # 就地替换 surface 上的旧清单（surface 永远只有一条）
-    transposition: true       # 置换检测
-    tier2After: 8             # checkpoint 超过 8 个就把最老的两段合并
-    graphDir: ''              # 留空 = <DSH_HOME>/chess-context
-    auto: true
-```
-
-`summaryMode` 的取舍：
-
-| 模式 | 模型调用 | 适合 |
-|---|---|---|
-| `rules` | **0 次** | 高频小 fold、预算敏感；摘要由规则模板生成（目标/约束/死路/已验证/当前节点） |
-| `hybrid`（默认） | 1 次/fold | 需要模型补写「意图」与「下一步」；硬事实仍由规则给定 |
-| `llm` | 1 次/fold | 只在明确需要模型自由发挥时 |
-
-## 推荐摘要模型
-
-`summaryMode: hybrid` 需要一次模型调用。推荐把 `summarizationProvider` / `summarizationModel`
-指向 **ima 免费模型**（先用 `magpie-ima-local-auth` 插件接入）：
-
-```yaml
-summaryMode: hybrid
-summarizationProvider: magpie
-summarizationModel: ima/deepseek-v4.1-flash
+    hotLedgerMarkers: semantic # semantic | terse | off
+    hotLedgerReplace: true    # 就地替换旧清单（surface 永远一条）
 ```
 
-实测（同一份 8 条失败边 + 2 条约束的合成会话，3 次采样）：
-
-| 模板 | 死路保留 | 约束保留 | 摘要长度 |
-|---|---|---|---|
-| 本插件棋谱模板 + ima V4.1-Flash | **8/8（3/3 次）** | **2/2（3/3 次）** | 1,887 字符 |
-| 官方 8 段模板 | 5/8 | 0/2 | ~3,072 字符 |
-
-也就是说：**ima 这种免费小模型最适合的正是“单轮、结构化、无工具”的摘要任务**，而不是
-当 DSH 的 agent 后端。它在这里比官方模板更听话，而且不占主路由额度。
-
-证据：[evidence/ima-摘要测试.md](evidence/ima-摘要测试.md)（3 次采样原始输出）。
-
-## 它产出什么
-
-```
-<DSH_HOME>/chess-context/sessions/<session>/graph.json   完整 DAG（节点 + 边 + 索引）
-<DSH_HOME>/chess-context/sessions/<session>/graph.md     人读棋谱（节点/边/结果/置换标记）
-```
-
-DSH 自己的会话日志仍是原始记忆的唯一来源 —— 节点上只记 `seq` 坐标，需要逐字原文时按 seq 回读。
-
-## 热上下文长什么样
-
-每步 `agent/pre-step` 注入。**surface 上永远只有一条清单**：清单变了就**就地替换**上一条
-（DSH 的 `surfaceOp:{op:"replace"}`，官方 system-prompt / tool-result-pruner 用的同一机制），
-而不是再追加一条 —— 旧版不替换，实测一个会话累积 **176 条 / 81 万字符 ≈ 27 万 token**
-（`evidence/P1-4-清单替换实测.md`）。
-v1.5.0 之前追加出来的旧清单也会被**一次性换成一行占位**（surface 只支持 append/replace，不能删节点）——
-实测事故会话的 surface 上还压着 44 条 / 29.5 万字符 ≈ 9.8 万 token，下次打开该会话时自动清掉。
-
-**标记一定自带解释** ——
-清单里出现的每个标记，图例里都有对应的一行（按实际用到的动态生成，不浪费预算）：
-
-```
-<chess-ledger>
-ROOT USER (verbatim): 把 tests/case*.test.js 跑绿：缓存键算错了。不要动 prod 配置。
-CONSTRAINTS (verbatim):
-- 不要动 prod 配置。
-CURRENT GOAL: 缓存键修好，case7 通过
-WORKING: user → n2 (exit 0)
-LEARNED (3 failed attempts):
-# markers:
-#   dead = a working path avoids it — retry only if that path breaks
-#   redundant = working edge <edge> reaches the SAME position — take that one
-#   blocked:permission = needs a permission this environment lacks — retry when it changes
-- e2 "把缓存键改成 JSON.stringify 全部参数" → AssertionError: case7 expected 1 got 2 … [dead redundant:e1]
-- e3 "装全局 sqlite 依赖后再跑" → npm ERR! EACCES: permission denied, mkdir … [blocked:permission]
-</chess-ledger>
-```
+全部配置项与含义见 [`docs/性能与成本.md`](docs/性能与成本.md) 与 `src/engine.mjs` 的 `Config`。
 
-四条设计约束（都是实测逼出来的）：
+## 常见问题
 
-1. **标记说语义，不说缩写**：`blocked:permission` 比 `[blocked]` 多出的那截就是「什么条件变了能再试」，
-   而这正是 `revisit_if` 想给模型的东西（旧版只在 index.md 里给，热清单里看不到）。
-2. **图例跟着标记走**：旧版把图例绑在「检测到手割」上 ⇒ 一个只有 EACCES 的会话里 `[blocked]` 裸奔；
-   现在有标记必有图例，且只解释用得上的那几条。
-3. **原因（报错原文）任何档位都保留**：旧版 L3+ 把 `→ 原因` 整段砍掉，实测全库 133 条可见失败边里
-   只有 25 条带原因 —— 而模型判断「这是不是同一个坑」靠的就是报错原文。
-4. **手割标记对最近 30 条边算**（每条一次 BFS）：旧版「显示条数 ≤30 才算」⇒ 40 条失败边的会话
-   一条标记都没有，而模型只对最近几步做决策。
+**关掉原生压缩，自动压缩还在吗？** 在 —— 本插件**就是**那个自动压缩后端：它继承官方的
+`BasicCompactionEngine`（同一套 between-step 压力触发、context-overflow 兜底、事务语义），
+`auto` 默认 `true`，装的不是「替代品」而是「换引擎」。变的只是「压缩范围 = 上一个 checkpoint 之后」
+与「失败记忆逐字保留」。
 
-预算不够时**降级不丢边**：先砍意图与原因的**长度**，再砍 seq，最后只列最近 N 条 + 汇总行。
-标记档位可用 `hotLedgerMarkers` 调：`semantic`（默认）| `terse`（只写三态，省 token）| `off`。
+**压缩之后数字会降吗？会不会只增不减？** 会降。一次 fold 用一个 checkpoint **替换掉整段被遮蔽的
+历史**，tokenMeter 重新计算后数字直接下降；但不会归零 —— 还会保留逐字尾部（`retainRatio`，默认 16%）
+和摘要本身。典型形状是**锯齿**：涨到阈值（窗口 45%）→ 压到约 20% → 再涨。如果你看到「只涨不降」，
+先跑 `npx dsh-gokifu-compact doctor` 看压缩是不是在失败（`compaction/end` 的错误会直接列出来）。
 
-## 测试
+**装完没反应 / 压缩没触发？** 插件在 DSH 启动时加载，**必须重启**。重启后跑 `node test/doctor.mjs`，
+它会告诉你四件事：装没装上、摘要模型能不能解析、最近的压缩成功/失败、棋谱与树健不健康。
 
-```bash
-node test/run.mjs            # 118 项：图/判定/范围/热上下文/标记契约/事件落账/接线（假 DSH）
-node test/doctor.mjs         # 一条命令体检：安装 / 摘要模型 / 压缩成败 / 棋谱 / 树新鲜度
-node test/verify-install.mjs # 13 项：安装与挂载校验（含运行期 graph.json 证据）
-node test/verify-graphs.mjs  # 全库棋谱健康检查（worldHash 类型 / stateIndex / renderFacts 不抛错）
-node test/measure-billing.mjs # 真实 usage 计费审计（prompt / 缓存命中 / 清单占比 / fold 收支）
-node test/measure-ledger.mjs # 热清单的 token 与信息量（--terse / --off 可换档对比）
-node test/ab-render.mjs      # A/B 夹具：同一张棋谱的三种标记档位各渲染一份（模型消费者实验用）
-node test/rewash-graph.mjs   # 历史棋谱回洗（dry-run 默认；--apply 写盘并重建树）
-node test/real-headless-fold.mjs # **真实 dsh 进程**里触发 fold（headless profile + overlay；真 Session/真事务）
-node test/evidence.mjs       # 重算 evidence/模拟结果.md（计费、保留率、热上下文成本）
-node test/bench.mjs 2000     # 2000 条边的性能与体量
-
-# 用**真实的** @deepseek-ai 模块验证（从 app.asar 提取依赖闭包到 tmp，不重启 DSH）
-node test/real-modules.mjs   # import / 真 cordis 构造 / Config schema / 继承链
-node test/real-fold.mjs      # 真实 compactRegion 事务 + 棋谱摘要（rules 与 hybrid 都能跑通）
-node test/real-fold-trigger.mjs  # fold 自动触发（阈值/增长门/增量）；需要真实模型，结果非确定，手动跑
-
-# 用**真实模型**（magpie 默认路由组）验证
-node test/real-model.mjs     # 对照实验：本插件 8/8 vs 官方 4.67/8 失败边保留
-node test/real-e2e.mjs       # 真实 bash 失败 → 压缩 → 续跑 3/3
-```
+**会不会把失败记忆弄丢？** 不会。失败边由规则抽取并逐字注入摘要 prompt，模型输出后还会机械追加约束段；
+模型没有「决定丢掉某条」的权限。真实模型对照里本插件保留 8/8，官方 8 段模板平均 4.67/8。
 
-### v0.1.2 · 运行期修复（2026-10-28）
+**摘要模型要配吗？** 不用，留空就跟随当前路由。配了但 provider 的模型表里没有那个 id 时，
+引擎会退回路由模型；再不行就退回规则摘要（零模型调用）—— 宁可摘要朴素，也不让压缩失败。
 
-插件在真实会话里跑起来后，暴露并修掉了 8 个 bug，详见 [运行期修复报告](docs/运行期修复报告.md)；性能分解见 [性能与成本](docs/性能与成本.md)。
+**历史数据会不会把压缩弄坏？** 不会。插件加载棋谱时会自动修复旧格式（`worldHash` 对象 → 字符串、状态索引重建）；
+旧版本追加出来的几十条热清单会被一次性换成一行占位。全库 1,279 个坏字段实测归零。
 
-| Bug | 修复前 | 修复后 |
-|---|---|---|
-| 系统注入被当成用户的话 | user 节点 13 个（含 Hindsight/系统说明） | **3 个**（全是真人输入） |
-| 只读工具文本被当成失败 | failure 55 条（30+ 误报） | **8 条**（逐条核对全真） |
-| 落盘滞后 | 每 25 事件才写 | 变化后 1.2s debounce 写 |
-| 热上下文爆炸 | 1201 条边 → 28,800 tokens | **323 tokens**（L5 降级 + 汇总行 + 跳过装不下的档位） |
-| 标记裸奔（v1.4.0） | `[blocked]` 出现却无解释；`redundant`/`longer` 从不在图例里 | 标记自带语义（`blocked:permission`）+ **按用到的标记动态生成图例** |
-| 原因失踪（v1.4.0） | L3+ 把 `→ 报错原文` 整段砍掉（全库 133 条可见失败边只有 25 条带原因） | 任何档位都保留原因（最省档 25 字），带原因条数 89 → **209** |
+**为什么压缩还是会让 prompt 缓存失效？** DSH 的 surface `replace` 语义决定：替换点之后的 KV 前缀会失效。
+增量 fold 让替换点尽可能靠后，但无法消除（这是 seam 的语义，不是实现选择）。真实会话实测缓存命中率 94~97%。
 
-三层验证的分工：
+**能和多分支/子代理一起用吗？** 子代理各自独立会话、各自一张棋谱；主会话的置换提示只在同一会话内生效。
 
-| 层 | 文件 | 回答什么问题 |
-|---|---|---|
-| 纯函数 | `test/*.test.mjs` | 图不变量、判定规则、增量范围、热上下文降级 |
-| 假 DSH | `test/engine-harness.test.mjs` | engine 的接线：构造 / 落账 / 注入 / 门控 / 溢出自救 |
-| **真模块** | `test/real-modules.mjs` + `test/real-fold.mjs` | **重启后会不会崩**：依赖名对不对、能否继承官方事务、摘要是否真的替换了官方模板 |
+## 参考源
 
-最后一层是从 `app.asar` 里把 29 个 `@deepseek-ai/*` 包提取到 `tmp/dsh-gokifu-compact/modules`
-再 import 的 —— 它验证的是真实类，不是 stub。
+只借鉴**结构与规律**，未复制代码：
 
-## 已知边界（诚实清单）
+| 来源 | 用在哪 |
+|---|---|
+| [magpie-plugin-scaffold](https://github.com/MYCF711/magpie-plugin-scaffold)（MIT） | README 模板、发版七步、维护检查脚本（`scripts/`） |
+| [billion-context](https://github.com/ranxianglei/billion-context)（MIT + 署名附加条款） | 「增量 fold / 只压已消费内容」的架构不变量、缓存与保留率的判据 |
+| [opencode-dcp](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning)（MIT） | 「每个机制一节」的说明结构、对 prompt 缓存影响如实交代的写法 |
+| [DSH 官方 `dsh-compaction` / `dsh-compaction-basic`](https://github.com/deepseek-ai)（随 DSH 分发） | 继承 `compactRegion` / `surfaceOp: replace` 事务语义，只覆盖策略层 |
 
-- **压缩仍是替换**：DSH 的 surface replace 会让 KV 前缀从替换点起失效。增量 fold 让替换点尽可能靠后，
-  但无法消除（这是 seam 的语义，不是实现选择）。
-- **规则判定会误判**：判不出来的一律标 `unverified`，绝不标 `success`；`errorSnippet` 保留报错原文兜底。
-- **不做多分支并行执行**：无廉价验证器时多分支搜索是烧钱（ReSCALE 反证），本插件只做「失败后换路」的记录与提示。
-- **未在真实会话中重启验证过**（本会话不能重启自身）：接线由 harness 测试覆盖，运行期表现按
-  `docs/重启后验证清单.md` 核对。
+设计依据与实测数据在 [`docs/市场对标.md`](docs/市场对标.md) 与 [`evidence/`](evidence/)。
 
 ## 文档
 
-- [方案书](docs/方案书.md) · [计划表](docs/计划表.md)
-- [市场对标](docs/市场对标.md)（billion-context / opencode-dcp / LLMLingua / LCM / Compaction Cliff…）
-- [DSH 技术测绘](docs/DSH-技术测绘.md)（1300 行，每条带 asar 行号）
-- [最终报告](docs/最终报告.md) · [重启后验证清单](docs/重启后验证清单.md)
-- [证据：模拟结果](evidence/模拟结果.md)
+- [快速开始](QUICKSTART.md) · [方案书](docs/方案书.md) · [计划表](docs/计划表.md)
+- [三层树设计](docs/三层树设计.md) · [DSH 技术测绘](docs/DSH-技术测绘.md)（1300 行，带 asar 行号）
+- [性能与成本](docs/性能与成本.md) · [真实计费核对](evidence/真实计费核对.md)
+- [最终报告](docs/最终报告.md) · [P0 修复记录](docs/P0-worldhash-死循环-根因与修复方案.md)
+
+> 更新记录：[CHANGELOG.md](./CHANGELOG.md)（发版流程见 `scripts/release.mjs` 与 HANDOFF）
 
+## 许可
 
-> `graph.md`（整篇人读视图）不再自动写 —— 用 `node test/build-md.mjs <sessionDir>` 按需生成。
+MIT。见 [LICENSE](LICENSE)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gokifu-compact",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "DSH context-compression backend with a **go game record (kifu)** DAG: node = position, edge = attempted move + result. Incremental fold (each span summarized once), failure memory that survives compaction, transposition detection (chess-engine style), and a tiny hot ledger rebuilt every step.",
   "type": "module",
   "main": "src/engine.mjs",
@@ -14,11 +14,6 @@
   "engines": {
     "node": ">=20"
   },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
   "files": [
     "src",
     "!src/.engine-under-test.mjs",
@@ -27,7 +22,8 @@
     "evidence",
     "scripts",
     "CHANGELOG.md",
-    "QUICKSTART.md"
+    "QUICKSTART.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "node test/run.mjs",
@@ -66,5 +62,8 @@
     "@deepseek-ai/schemastery": {
       "optional": false
     }
+  },
+  "bin": {
+    "dsh-gokifu-compact": "./scripts/cli.mjs"
   }
 }

package/scripts/cli.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * dsh-gokifu-compact —— 命令行入口
+ *
+ *   dsh-gokifu-compact install [--profile desktop] [--preset personal-assistant] [--dry-run]
+ *   dsh-gokifu-compact revert  [--profile desktop]
+ *   dsh-gokifu-compact doctor  [--json]
+ *
+ * `install` 做的事只有一件是人手做起来最容易错的：把 agent preset 的 compaction group 里
+ * `@deepseek-ai/dsh-compaction-basic` 那一行换成 `dsh-gokifu-compact`（带备份、可回滚、幂等）。
+ * 为什么必须改 preset 文件而不是 bundle patch：见 scripts/install.mjs 顶部注释。
+ */
+import nodePath from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { run } from "./install.mjs";
+
+const HERE = nodePath.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const command = argv[0] ?? "";
+
+if (command === "install" || command === "revert") {
+  process.exitCode = run(argv);
+} else if (command === "doctor") {
+  const doctor = nodePath.join(HERE, "..", "test", "doctor.mjs");
+  try {
+    execFileSync(process.execPath, [doctor, ...argv.slice(1)], { stdio: "inherit" });
+  } catch (error) {
+    process.exitCode = typeof error?.status === "number" ? error.status : 1;
+  }
+} else {
+  console.log(`dsh-gokifu-compact — DSH 的棋谱式上下文压缩后端
+
+用法:
+  dsh-gokifu-compact install [--profile <name>] [--preset <name>] [--dry-run]
+      把压缩后端从 dsh-compaction-basic 换成 dsh-gokifu-compact（自动改 preset，带备份，幂等）
+  dsh-gokifu-compact revert  [--profile <name>]
+      还原上一次的 preset 备份
+  dsh-gokifu-compact doctor
+      体检：安装 / 摘要模型 / 压缩成败 / 棋谱 / 树新鲜度
+
+装包（先做这一步）:
+  dsh plugin --profile <name> add dsh-gokifu-compact
+`);
+  process.exitCode = command === "" || command === "--help" || command === "-h" ? 0 : 1;
+}

package/scripts/install.mjs

@@ -0,0 +1,283 @@
+/**
+ * install.mjs —— 一条命令让 dsh-gokifu-compact 接管压缩后端（不需要手改任何 YAML）
+ *
+ * 为什么必须改 preset 文件：DSH 的压缩后端是挂在 **agent preset 的 compaction group 里**
+ * 的一行（`@deepseek-ai/dsh-compaction-basic`）。那是 preset 的 `config.plugins` 数组内部，
+ * 不是 loader 顶层条目 —— profile 级 / bundle 级的 patch 打不到它
+ * （`applyEntryPatches` 只递归 `group: true` 且 `config` 为数组的条目，而 preset 的 plugins
+ * 是 `config.plugins`；实测记录见 docs/DSH-技术测绘.md §7.6）。
+ *
+ * 这个脚本就是替你改那一行，并且：
+ *   · 自动找 profile / preset（把 preset 里所有 `- id: compaction-basic` 块换掉）
+ *   · 改之前备份（`*.bak-before-gokifu-<ts>`），`revert` 一键还原
+ *   · `--dry-run` 只打印不写盘
+ *   · 幂等：已经换过就跳过；旧版本残留（有我们的 name、id 还是旧名）只改名
+ *   · 双模式：从仓库跑（会先建 junction + profile 依赖）/ 从已装的包跑（跳过链接）
+ *
+ * 用法：
+ *   dsh-gokifu-compact install [--profile desktop] [--preset personal-assistant] [--dry-run]
+ *   dsh-gokifu-compact revert  [--profile desktop]
+ *
+ * 兼容：`node test/install.mjs` 仍然可用（薄封装到这个文件）。
+ */
+
+import nodeFs from "node:fs";
+import nodePath from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const PKG_NAME = "dsh-gokifu-compact";
+export const ENTRY_ID = "gokifu-compact";
+
+const HERE = nodePath.dirname(fileURLToPath(import.meta.url));
+export const PROJECT_DIR = nodePath.resolve(HERE, "..");
+
+export function parseArgs(argv) {
+  const args = [...argv];
+  const command = args[0] && !args[0].startsWith("--") ? args.shift() : "install";
+  const get = (name, fallback) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+  };
+  return {
+    command,
+    dryRun: args.includes("--dry-run"),
+    profile: get("profile", process.env.DSH_PROFILE ?? "desktop"),
+    preset: get("preset", ""),
+    dshHome: get(
+      "home",
+      process.env.DSH_HOME ?? nodePath.join(process.env.USERPROFILE ?? process.env.HOME ?? ".", "DeepSeek Harness", "home"),
+    ),
+    log: args.includes("--quiet") ? () => {} : (...m) => console.log(...m),
+  };
+}
+
+function installedLocation(dshHome, profile) {
+  const profilePkg = nodePath.join(dshHome, "profiles", profile, "node_modules", PKG_NAME);
+  return nodePath.resolve(profilePkg) === PROJECT_DIR;
+}
+
+function presetsWithCompaction(dshHome) {
+  const root = nodePath.join(dshHome, "preset-bundles");
+  if (!nodeFs.existsSync(root)) return [];
+  const out = [];
+  for (const entry of nodeFs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = nodePath.join(root, entry.name, "cordis.patch.yml");
+    if (!nodeFs.existsSync(file)) continue;
+    const text = nodeFs.readFileSync(file, "utf8");
+    if (text.includes("- id: compaction-basic") || text.includes(PKG_NAME)) out.push({ name: entry.name, file, text });
+  }
+  return out;
+}
+
+/**
+ * 找到 `- id: compaction-basic` 那一块并整块替换（按缩进判断块边界）。
+ * @returns 新文本；找不到返回 null
+ */
+export function replaceCompactionBlock(text, blockLines) {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const startPattern = /^(\s*)- id: compaction-basic\s*$/;
+  let start = -1;
+  let foundIndent = "";
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = startPattern.exec(lines[i]);
+    if (m) {
+      start = i;
+      foundIndent = m[1];
+      break;
+    }
+  }
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line.trim().length === 0) continue;
+    if (/^\s*#/.test(line)) continue;
+    const lead = (/^\s*/.exec(line)[0] ?? "").length;
+    if (lead === foundIndent.length && /^-\s/.test(line.trim())) {
+      end = i;
+      break;
+    }
+    if (lead < foundIndent.length) {
+      end = i;
+      break;
+    }
+  }
+  const replacement = blockLines.map((line) => foundIndent + line);
+  return [...lines.slice(0, start), ...replacement, ...lines.slice(end)].join("\n");
+}
+
+/** 我们的引擎块（不含缩进，缩进由 replaceCompactionBlock 加）。 */
+export function engineBlock() {
+  return [
+    `# ★ 压缩后端：棋谱式增量 fold（失败记忆 + 手割 + 置换检测）。`,
+    `#   替换掉原来的 @deepseek-ai/dsh-compaction-basic —— 两者会抢同一个 ctx.compaction。`,
+    `#   回滚：dsh-gokifu-compact revert   （恢复 .bak-before-gokifu-* 备份）`,
+    `- id: ${ENTRY_ID}`,
+    `  name: '${PKG_NAME}'`,
+    `  config:`,
+    `    auto: true                # 自动压缩：继承基类的 between-step 压力触发`,
+    `    thresholdRatio: 0.45      # 压力闸：min(窗口×0.45, 窗口−输出预留−64K)`,
+    `    headroomTokens: 65536`,
+    `    retainRatio: 0.16         # 逐字保留的近期尾部`,
+    `    growthFloorTokens: 40000  # 增长闸：距上次 fold 至少新增这么多 token`,
+    `    minFoldTokens: 8000`,
+    `    summaryMode: hybrid       # hybrid | rules（零模型调用）| llm`,
+    `    summarizationProvider: '' # 留空 = 跟随当前路由`,
+    `    summarizationModel: ''    # 想用免费模型，先确认 provider 模型表里有那个 id`,
+    `    hotLedger: true`,
+    `    hotLedgerMaxTokens: 500`,
+    `    hotLedgerMarkers: semantic`,
+    `    hotLedgerReplace: true`,
+    `    transposition: true`,
+    `    tier2After: 8`,
+  ];
+}
+
+export function backupFile(file, ts = Date.now()) {
+  const target = `${file}.bak-before-gokifu-${ts}`;
+  nodeFs.copyFileSync(file, target);
+  return target;
+}
+
+export function revertPreset(file, log = console.log) {
+  const dir = nodePath.dirname(file);
+  const base = nodePath.basename(file);
+  const backups = nodeFs
+    .readdirSync(dir)
+    .filter((name) => name.startsWith(`${base}.bak-before-`))
+    .sort()
+    .reverse();
+  if (backups.length === 0) {
+    log(`  ! ${file} 没有备份可恢复`);
+    return false;
+  }
+  nodeFs.copyFileSync(nodePath.join(dir, backups[0]), file);
+  log(`  ✓ 已还原 ${file} ← ${backups[0]}`);
+  return true;
+}
+
+/** 旧版本残留：有我们的 name，但 id 还是别的（例如 chess-context）。只改 id 行。 */
+function renameLegacyId(text) {
+  const lines = text.split("\n");
+  let changed = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = /^(\s*)- id:\s*([A-Za-z0-9._-]+)\s*$/.exec(lines[i]);
+    if (!m || m[2] === ENTRY_ID) continue;
+    const near = lines.slice(i, i + 3).join("\n");
+    if (!near.includes(PKG_NAME)) continue;
+    lines[i] = `${m[1]}- id: ${ENTRY_ID}`;
+    changed = true;
+  }
+  return changed ? lines.join("\n") : null;
+}
+
+export function run(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  const { dryRun, profile, dshHome, log } = opts;
+  const profileDir = nodePath.join(dshHome, "profiles", profile);
+
+  if (!nodeFs.existsSync(profileDir)) {
+    console.error(`找不到 profile 目录：${profileDir}（用 --profile / --home 指定）`);
+    return 1;
+  }
+
+  const targets = presetsWithCompaction(dshHome).filter((p) => (opts.preset ? p.name === opts.preset : true));
+  if (targets.length === 0) {
+    console.error(`在 ${nodePath.join(dshHome, "preset-bundles")} 下没找到含 compaction-basic 的 preset`);
+    return 1;
+  }
+
+  log(`== dsh-gokifu-compact ${opts.command} ==`);
+  log(`profile: ${profileDir}`);
+  for (const t of targets) log(`preset : ${t.file}`);
+  log(dryRun ? "模式: dry-run（不写盘）\n" : "");
+
+  if (opts.command === "revert") {
+    for (const t of targets) revertPreset(t.file, log);
+    log("\n还原后重启 DSH 生效。");
+    return 0;
+  }
+
+  if (opts.command !== "install") {
+    console.error(`未知命令：${opts.command}（可用：install / revert）`);
+    return 1;
+  }
+
+  /* ① 确保包装进 profile（已装好则跳过） */
+  if (!installedLocation(dshHome, profile)) {
+    const dest = nodePath.join(profileDir, "node_modules", PKG_NAME);
+    if (nodeFs.existsSync(dest)) {
+      log(`  · ${dest} 已存在（不是本目录），跳过链接`);
+    } else if (dryRun) {
+      log(`  [dry] 会建 junction ${dest} → ${PROJECT_DIR}`);
+    } else {
+      nodeFs.mkdirSync(nodePath.dirname(dest), { recursive: true });
+      execFileSync("cmd", ["/c", "mklink", "/J", dest, PROJECT_DIR], { stdio: "ignore" });
+      log(`  ✓ junction: ${dest} → ${PROJECT_DIR}`);
+    }
+    const pkgFile = nodePath.join(profileDir, "package.json");
+    const pkg = JSON.parse(nodeFs.readFileSync(pkgFile, "utf8"));
+    if (!pkg.dependencies?.[PKG_NAME]) {
+      if (dryRun) log(`  [dry] 会在 package.json dependencies 加 ${PKG_NAME}`);
+      else {
+        nodeFs.copyFileSync(pkgFile, `${pkgFile}.bak-before-gokifu-${Date.now()}`);
+        pkg.dependencies = { ...(pkg.dependencies ?? {}), [PKG_NAME]: `link:${PROJECT_DIR.replace(/\\/g, "/")}` };
+        nodeFs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+        log("  ✓ profile/package.json 已加 dependency");
+      }
+    } else log(`  · profile/package.json 已有 ${PKG_NAME}`);
+  } else {
+    log(`  · 已从 profile 的 node_modules 运行（安装态），跳过链接`);
+  }
+
+  /* ② 换 preset 里的压缩后端 */
+  for (const t of targets) {
+    const hasOurs = t.text.includes(PKG_NAME);
+    const hasOurId = /^\s*- id: gokifu-compact\s*$/m.test(t.text);
+    if (hasOurs && hasOurId) {
+      log(`  · ${nodePath.basename(nodePath.dirname(t.file))}: 已是 ${ENTRY_ID}，跳过`);
+      continue;
+    }
+    if (hasOurs && !hasOurId) {
+      const renamed = renameLegacyId(t.text);
+      if (renamed === null) {
+        log(`  ! ${t.file}: 有 ${PKG_NAME} 但找不到可改的旧 id 行，跳过（请手工检查）`);
+        continue;
+      }
+      if (dryRun) {
+        log(`  [dry] ${t.file}: 旧 id 改名为 ${ENTRY_ID}`);
+        continue;
+      }
+      const backup = backupFile(t.file);
+      nodeFs.writeFileSync(t.file, renamed, "utf8");
+      log(`  ✓ ${t.file} 已把旧 id 改名为 ${ENTRY_ID}（备份 ${nodePath.basename(backup)}）`);
+      continue;
+    }
+    const next = replaceCompactionBlock(t.text, engineBlock());
+    if (next === null) {
+      log(`  ! ${t.file}: 找不到 compaction-basic 块，跳过`);
+      continue;
+    }
+    if (dryRun) {
+      log(`  [dry] ${t.file}: compaction-basic → ${ENTRY_ID}`);
+      continue;
+    }
+    const backup = backupFile(t.file);
+    nodeFs.writeFileSync(t.file, next, "utf8");
+    log(`  ✓ ${t.file} 已换后端（备份 ${nodePath.basename(backup)}）`);
+  }
+
+  if (dryRun) {
+    log("\n这是预演，什么都没改。真装去掉 --dry-run。");
+    return 0;
+  }
+  log("\n✓ 完成。重启 DSH 后生效（插件在启动时加载）。");
+  log("  重启后自检：npx dsh-gokifu-compact doctor");
+  log("  回滚：npx dsh-gokifu-compact revert");
+  return 0;
+}
+
+const invokedDirectly = process.argv[1] !== undefined && nodePath.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) process.exitCode = run();

package/src/engine.mjs

@@ -71,7 +71,7 @@ export const Config = z.object({
   retainTokens: z.number().description("逐字保留的近期尾部（绝对 token）；与 retainRatio 互斥"),
   summarizationProvider: z.string().default("").description("摘要模型 provider；留空=跟随最近一次路由"),
   summarizationModel: z.string().default("").description("摘要模型 model；留空=跟随最近一次路由"),
-  maxTokens: z.number().default(2048).description("摘要输出上限"),
+  maxTokens: z.number().default(4096).description("摘要输出上限"),
   compactionRetries: z.number().default(1),
   maxOverflowRetries: z.number().default(1),
   modelPolicies: z.array(z.any()).default([]),
@@ -500,6 +500,13 @@ export default class ChessCompactionEngine extends BasicCompactionEngine {
 ## 约束（机械保留，逐字；不由模型改写）
 ${constraintsBlock.split("\n").map((l) => `- ${l}`).join("\n")}` });
     }
+    // 记账：这次摘要调用了多少 token（provider 真实 usage）。#commit 会把它写进 graph.lastFoldUsage，
+    // doctor / 计费对账直接读，不用再翻会话日志里的 compaction/summary 事件。
+    if (assembler.usage !== undefined) {
+      this._lastSummaryUsage = assembler.usage;
+      this._lastSummaryProvider = used.provider;
+      this._lastSummaryModel = used.model;
+    }
     return {
       summary,
       rawOutput: raw,
@@ -624,7 +631,20 @@ ${constraintsBlock.split("\n").map((l) => `- ${l}`).join("\n")}` });
     const after = meter.measure(session);
     g.foldCount += 1;
     g.lastFoldTotalTokens = after.totalTokens;
-    g.checkpointSeq = range.start;
+    // 记「checkpoint 消息的 seq」，不是被遮蔽区间的起点 —— 后者 fold 之后已不在 surface 上，
+    // 任何读这个字段做判断的地方都会拿到一个不存在的 seq（2026-10-29 实机：值一直是 9）。
+    g.checkpointSeq = checkpointSeqs(session).at(-1) ?? null;
+    if (this._lastSummaryUsage !== undefined) {
+      g.lastFoldUsage = {
+        ...this._lastSummaryUsage,
+        provider: this._lastSummaryProvider ?? null,
+        model: this._lastSummaryModel ?? null,
+        at: Date.now(),
+      };
+      this._lastSummaryUsage = undefined;
+      this._lastSummaryProvider = undefined;
+      this._lastSummaryModel = undefined;
+    }
     g.foldMarks.push({
       at: Date.now(),
       seqStart: range.start,

package/src/graph.mjs

@@ -64,6 +64,7 @@ export function createGraph({ sessionId, cwd = "" }) {
     foldCount: 0,
     lastFoldTotalTokens: 0,
     foldMarks: [],      // 每次 fold 的 {at, seqStart, seqEnd, nodeIds, edgeIds}
+    lastFoldUsage: null,// 最近一次摘要调用的真实 usage {inputTokens, outputTokens, provider, model, at}
   };
 }