dsh-gokifu-compact

dsh plugin --profile web add dsh-gokifu-compact

dsh-GOkifu-compact

当前版本：1.18.3（稳定版；上一稳定版 1.18.2） · npm dsh-gokifu-compact · GitHub Releases · 更新记录见 [CHANGELOG.md](CHANGELOG.md)

DSH 的棋谱式上下文压缩后端 —— 把「历史 → 一段摘要」换成「历史 → 可复盘的棋谱 DAG + 每步只有 415 tokens 的热清单」。

热清单     417 tokens       （2000 边合成夹具 · L5 降级档 · 2026-11-02 实测；旧版全量 28,800；+27% 来自出处全档保留，−31 来自标记汇总与冗余指针清理（C51/C52/C56））
失败保留   8 / 8            （历史口径 †；官方 8 段模板 4.67 / 8）
清单开销   未复现/待测       （原载 0.2% = 历史单会话 v1.3.1 后实测；无复跑命令、无对照组；源 evidence/真实计费核对.md）
验证       668 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †

GO = 围棋，kifu = 棋谱，compact = 压缩。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。

这个插件把 agent 的每一步变成一手棋（节点）、把当时的思考变成评语（目标 / 约束 / 失败原因），

整个任务变成一局可以复盘的棋。棋谱是给模型用的，不是给人看的 —— 热清单里的每个字都为模型决策服务。

† 历史口径（未复现）：失败保留 8/8、真实包 8/8、真实进程 fold 3~6/6 都是早期真机测量，本轮没有复跑命令、没有复现，不要当现行指标引用。

417 tokens 的口径：这是 2000 边合成夹具在 L5 降级档下的结果，不是真实会话均值。

真实会话校准（C72）：node scripts/ledger-calibration.mjs 对当前 live 24 个会话图按生产选项渲染 ——

p50 = 419、p90 = 521、min 32、max 688，超预算 3/24（快照见 evidence/ledger-calibration.md）。

⇒ 合成夹具的中位数与实际会话基本一致（417 vs 419），不是虚高。

~~真实会话里预算按 字符数/3 估算，实测系统性低估 5.2%~22.1%（中位 9.7%）（见 计划表.md 的 OPT-TOKENS 节）；真实会话口径尚未校准 —— 正解是引入宿主 tokenizer（ctx.tokenMeter）后重测，未做。~~

⇒ 1.13.0 已校准：热清单预算改成按字符类别加权 —— CJK 1 token/字 + 其余 1/4 token/字

（ASCII 侧对齐宿主 dsh-token-meter 的 CHARS_PER_TOKEN = 4；全角标点算 CJK）。

锚点：2478 字符的真实热清单，旧口径 826（−8.8%） → 新口径 933，网关实测 905（+3.1%）。

归档 176 会话复算：avg 412.40 → 417.88、max 826 → 933、over-500 25 → 25

（张数没变是渲染器自适应降档换来的；只换公式不重渲染会是 over 56 ⇒ 旧口径那 25 张里有 31 张靠低估撑出来）。

注意两套口径并存：会话压力 / fold 触发由宿主 ctx.tokenMeter.measure(session) 定价，热清单是本文这套加权估算。

---

功能

• 增量 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 回洗历史误报。
• 归档收尾 —— 归档一个会话时补做一次折叠（尾巴 ≥ 40 事件才花模型调用）；1.17.6 起挂在 domain/changed，因为 GUI 归档不发 session/disposed。
• 补账 —— 归档那一刻没压完的会话，账是欠着的（归档会话没有 agent，宿主的压缩只对 idle agent 有效）；面板一键补：取消归档 → resume → 收尾折叠 → 原样归档回去。
• 面板 —— 上下文压缩面板：状态 / 检查更新 / 补账 / 最近活跃会话（含已修正失败占比）/ 今天（含折叠成本估算）/ 配置。

面板

DSH 的「上下文压缩」面板（POST /gokifu/api，同一套信任检查，不新开路由）：

卡 · 说清什么

状态 · 版本、profile、当前配置生效值

检查更新 · 当前/最新版本、是否有新版、可复制的升级命令（只拼命令，绝不执行安装；已知不新时不给命令）

补账 · 已归档但没压完的会话：先「检查欠账（不调模型）」看清单，再「开始补账」

最近活跃会话 · fold 次数 / 失败边 / 已修正失败（同一条命令后来跑通了 —— 这些行在清单里沉底）/ 上次遮蔽

今天 · fold 次数、涉及会话、合计遮蔽、折叠成本估算（官方价目 × 真实 usage）

配置 · 摘要模型、阈值、标记档位等（写入 preset 的引擎块）

成本估算是估算：价目用 DeepSeek 官方 deepseek-flash 低峰价（命中 $0.003 / 未命中 $0.15 / 输出 $0.6 每 1M tokens），

不含宿主侧的 system/tools 开销；没有 usage 的 fold 不参与计算，页面会标出「N 次有 usage」。

细节与逐条判据见 [docs/发布说明-1.18.0.md](docs/发布说明-1.18.0.md)。

怎么工作

每一步：事件流 ──► 棋谱 DAG（节点 = 状态；边 = 尝试 + 验证信号）
                        │
                        ▼
              热清单（根目标 / 约束 / 成功路径 / 失败边）──► 注入模型
                        │
             到阈值（默认窗口 45% 且增量 ≥ 40K）
                        ▼
              增量 fold：只压上一个 checkpoint 之后 ──► 棋谱摘要（失败边逐字保留）

和官方 dsh-compaction-basic 的区别：

· 官方 compaction-basic · 本插件

压缩范围 · 从 surface 第一个非 system 节点起（含上次 checkpoint） · 上一个 checkpoint 之后

保留率 · 每轮重摘 → 按 ρ^k 衰减（实测安全规则 5 轮后剩 10%） · 一段内容只摘一次

失败记录 · 融进散文摘要，模型可以丢 · 规则抽取 + 逐字注入，模型无权丢

热上下文 · 无 · 417 tokens / 步（2000 边合成夹具 · L5 降级档；真实会话 p50 = 419（C72 实测）；较 1.16 的 351 增加 27%，用于换「出处不丢 + OPTIONS 不沉默」），带语义标记与报错原文

⚠ 棋谱落盘：graph.json 的语义（1.9.2 起）

graph.json 不再代表「最新状态」，而是「上一回合基线 + 当前增量」。

每次都重写整图（≤1.9.1）      增量落盘（1.9.2 起）
graph.json = 最新             graph.json              = 上一个回合边界的完整基线
                              graph.json.delta.jsonl  = 本回合的增量帧（带 baseHash + checksum）
                              （两者合并 = 最新状态）

⇒ 它在回合内落后一回合。 任何直接 JSON.parse(graph.json) 当「最新」的脚本，都会少一回合的数据。

graph.json 只在回合边界（agent/status idle）落一次完整快照；回合内的每一步只往

graph.json.delta.jsonl 追加一帧。

你要什么 · 怎么拿

最新状态（推荐） · 基线 + 增量一起读：fromJSON(graph.json 文本) → 用基线内容哈希 decodeDeltaFrames(delta 文本, baseHash) → 逐帧 applyDelta(g, frame)。三个函数都从包入口 dsh-gokifu-compact/graph 导出（源码 src/rooms/kifu-model.mjs，随包发布）；落盘/读盘侧（graphRoot / sessionPaths / createPersistStore 等）走 dsh-gokifu-compact/persist

上一回合基线（做 diff / 审计） · 直接读 graph.json 可以，但要说明「这是基线不是最新」

崩溃安全 · 每帧带 baseHash（generation）+ checksum31：半写帧解码时就地停止，加载时把 delta 截到最后一条好帧；旧 generation 的帧整体忽略

为什么这样设计：写放大从 ×80 / ×70 / ×62 降到 ×37 / ×33 / ×31（三张真实图 60 步 + 1 回合边界），

fold 后 flush 从 429–836 ms 降到 ≤95 ms；代价是「读的人必须知道这是增量结构」。

三条已知余量（选型时要知道）

1. 短回合写放大：每回合边界落一份完整基线（0.5–0.6 MB）。真实分布 p50=40 步/回合 ⇒ 写放大 ≈×20–25；

但极短回合（<10 步，p10=13.9）摊销不足，写放大仍可能 >×50。

2. dirty > 100 的 flush：fold 后只写 dirty 节点 —— 5–20 个 dirty 时 9–23 ms，100 个时约 87–89 ms

（改前全量 429–836 ms）。dirty 数极大时收益收窄。

3. appendFileSync 的原子性依赖 OS：本机 NTFS 上 1 KB 级追加已过半写测试；跨平台（尤其网络文件系统）未验证。

热上下文长什么样

每步 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> 

…(truncated)