dsh-gokifu-compact 1.11.7 → 1.11.8

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # 更新记录
 
+## 1.11.8 — 2026-10-31
+
+### sidecar 现在能**回灌**：归档掉的悬空边可以放回图里
+
+1.11.1 起 `migrate-dangling --apply` 把 settled residue 归档到 `graph.dangling.json`（sidecar），
+**但一直没有回灌工具** —— 报告里写「字段齐全、可回灌」，实际只能靠人手写 JSON。这一版把这条路补完。
+
+**新增（R14 `src/rooms/migrate.mjs`）**
+
+| 导出 | 作用 |
+|---|---|
+| `readSidecar(file)` | 读 + 校验：`format` / `version` / **非空 `edges`** / 每条边必须有 `id` / 会话匹配；**坏文件一律拒绝且不动图** |
+| `mergeSidecar(graph, sidecar, opts)` | 按 `edge.id` 合并；**同 id 跳过、不覆盖**；保留 sidecar 原字段；**原子写 `graph.json` + 重建 `index.md`** |
+| `mergeMany(target, opts)` | 目标可以是**文件或目录**；批量 |
+| `mergeBackupDir(opts)` | 回灌前先备份 `graph.json` / `index.md` 并落 `MERGE.json` |
+
+- **默认 dry-run**：只有 `--apply` 才写盘；**幂等** —— 二次 merge 0 条命中且**不写盘**。
+- CLI：`--merge-sidecar=<file|dir> [--apply] [--backup-dir=] [--json]`；有错误 **exit 1**。
+
+**CLI 摘要（`scripts/migrate-dangling.mjs`）**
+
+- 修掉 `main()` 里 merge 分支的**重复执行链**（只留 `mergeMany`，错误 exit 1），人类摘要移到输出链。
+- 无 `--json` 时打印：标题 / target / `sessions|merged|skipped` / 逐会话行 / backup 目录 / errors / dry-run 或已回灌提示；
+  **`--json` 仍是纯 JSON**（可 `JSON.parse`）。
+- `mergeMany`：目标不存在时**直接报「目标不存在」**（不再默默去读 `./graph.json`）。
+
+**测试 +7**（486 → 493）
+
+- M1 回灌与备份 · M2 幂等 · M3 **五类拒绝**（format/version/空 edges/边无 id/会话不匹配）· M4 同 id 不覆盖 · M5 `mergeMany` 批量
+- C1 **真跑 CLI 六态**（人类摘要 / `--json` / apply 备份 / 幂等 / 坏 version / 目标不存在）· C2 结构回归（merge 分支恰好 2 处）
+- 变异自检：覆盖已存在边 / dry-run 写盘 / 不校验 version / 执行链重复分支 / `--json` 走人类摘要 / 删人类摘要分支 —— 逐条红
+
+### 验证
+
+- 全量：**493 passed / 0 skipped / 0 failed**（37 个测试文件）
+- `migrate` **21/0** · `rooms` 15/0 · `verify-install` **16/16**
+- `npm pack --dry-run --json`：**71 文件**（数量不变；只改 `src/` `scripts/` `test/`）
+
+**未验证**
+
+- 回灌**没有对真实库跑过** —— 全部证据来自夹具；真实 `sessions/**` 的 apply 仍需主人授权 + 停插件窗口。
+- 回灌只按 `edge.id` 去重：**同一个「边」若在 sidecar 里 id 不同（历史重复归档），会被当成两条各插一次**。
+
 ## 1.11.7 — 2026-10-31
 
 ### 真实测试与门禁都不再「靠输出猜」

package/README.md

@@ -1,6 +1,6 @@
 # dsh-GOkifu-compact
 
-> 当前版本：**`1.11.7`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
+> 当前版本：**`1.11.8`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
 
 **DSH 的棋谱式上下文压缩后端 —— 把「历史 → 一段摘要」换成「历史 → 可复盘的棋谱 DAG + 每步只有 351 tokens 的热清单」。**
 
@@ -8,7 +8,7 @@
 热清单     351 tokens       （2000 边合成夹具 · L5 降级档 · 2026-10-30/10-31 两次实测同值；旧版全量 28,800）
 失败保留   8 / 8            （历史口径 †；官方 8 段模板 4.67 / 8）
 清单开销   未复现/待测       （原载 0.2% = 历史单会话 v1.3.1 后实测；无复跑命令、无对照组；源 evidence/真实计费核对.md）
-验证       486 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †
+验证       493 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †
 ```
 
 GO = 围棋，kifu = 棋谱，compact = 压缩。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gokifu-compact",
-  "version": "1.11.7",
+  "version": "1.11.8",
   "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.",
   "repository": {
     "type": "git",

package/scripts/migrate-dangling.mjs

@@ -11,6 +11,8 @@
  *   node scripts/migrate-dangling.mjs --apply                # 真执行（先整目录备份；120s 新鲜度守卫）
  *   node scripts/migrate-dangling.mjs --verify --backup=<dir>  # 只读校验
  *   node scripts/migrate-dangling.mjs --rollback=<dir>       # 从备份逐字恢复
+ *   node scripts/migrate-dangling.mjs --merge-sidecar=<file|dir>          # 回灌 sidecar（默认 dry-run）
+ *   node scripts/migrate-dangling.mjs --merge-sidecar=<file|dir> --apply  # 真回灌（备份到 --backup-dir）
  *   --root=<sessionsRoot>  --backup-dir=<dir>  --now=<epochMs>
  *
  * 退出码：0 正常；1 校验失败/执行失败；2 参数错误。
@@ -18,13 +20,13 @@
 
 import nodeFs from "node:fs";
 import nodePath from "node:path";
-import { dryRun, apply, verify, rollback, sessionsRoot, backupsRoot } from "../src/rooms/migrate.mjs";
+import { dryRun, apply, verify, rollback, mergeMany, sessionsRoot, backupsRoot } from "../src/rooms/migrate.mjs";
 
 function parseArgs(argv) {
-  const opts = { mode: "dry-run", json: false, force: false, only: null, root: sessionsRoot(), backupRoot: backupsRoot(), backupDir: "", now: Date.now() };
+  const opts = { mode: "dry-run", json: false, force: false, only: null, root: sessionsRoot(), backupRoot: backupsRoot(), backupDir: "", mergeTarget: "", now: Date.now() };
   for (const arg of argv) {
     if (arg === "--dry-run") opts.mode = "dry-run";
-    else if (arg === "--apply") opts.mode = "apply";
+    else if (arg === "--apply") { opts.applyMerge = true; if (!opts.mergeTarget) opts.mode = "apply"; }
     else if (arg === "--force") opts.force = true;
     else if (arg === "--verify") opts.mode = "verify";
     else if (arg === "--json") opts.json = true;
@@ -34,6 +36,13 @@ function parseArgs(argv) {
     else if (arg.startsWith("--rollback=")) {
       opts.mode = "rollback";
       opts.backupDir = arg.slice("--rollback=".length);
+    } else if (arg.startsWith("--merge-sidecar=")) {
+      opts.mode = "merge";
+      opts.mergeTarget = arg.slice("--merge-sidecar=".length);
+      if (opts.mergeTarget.length === 0) {
+        console.error("--merge-sidecar= 需要一个 sidecar 文件或会话目录");
+        process.exit(2);
+      }
     } else if (arg.startsWith("--sessions=")) {
       opts.only = arg.slice("--sessions=".length).split(",").map((x) => x.trim()).filter(Boolean);
     } else if (arg.startsWith("--now=")) opts.now = Number(arg.slice("--now=".length));
@@ -55,6 +64,8 @@ function printHelp() {
   node scripts/migrate-dangling.mjs --apply [--force]                   # 执行（整目录备份 + 120s 新鲜度守卫）
   node scripts/migrate-dangling.mjs --verify --backup=<backupDir>       # 只读校验
   node scripts/migrate-dangling.mjs --rollback=<backupDir>              # 从备份恢复
+  node scripts/migrate-dangling.mjs --merge-sidecar=<file|dir> [--apply] [--backup-dir=<dir>]
+        # 回灌 sidecar：默认 dry-run（只报告将合并几条）；--apply 才写（先备份 graph.json/index.md）
 
 默认路径：<DSH_HOME>/chess-context/sessions ；备份：<DSH_HOME>/chess-context/migrate-backups`);
 }
@@ -68,6 +79,9 @@ function main() {
       result = dryRun(opts.root, { now: opts.now, only: opts.only });
     } else if (opts.mode === "apply") {
       result = apply(opts.root, { now: opts.now, backupRoot: opts.backupRoot, only: opts.only, maxAgeMs: opts.force ? 0 : undefined });
+    } else if (opts.mode === "merge") {
+      result = mergeMany(opts.mergeTarget, { apply: opts.applyMerge, backupRoot: opts.backupRoot, now: opts.now });
+      if (!result.ok) code = 1;
     } else if (opts.mode === "verify") {
       result = verify(opts.root, { now: opts.now, backupDir: opts.backupDir, only: opts.only });
       if (!result.ok) code = 1;
@@ -81,6 +95,24 @@ function main() {
   }
   if (opts.json) {
     console.log(JSON.stringify(result, null, 1));
+  } else if (opts.mode === "merge") {
+    // ★ task-157：merge 的人类摘要（--json 时走上一条分支给 JSON）。
+    //   旧版这里的 merge 分支被误插进**执行链**里（与同条件的 dispatch 分支重复），
+    //   结果永远不执行 ⇒ 不带 --json 时只能看到兜底的 JSON。
+    console.log(`== migrate-dangling ${result.mode} ==`);
+    console.log(`target: ${result.target}`);
+    console.log(`sessions: ${result.sessions}｜merged ${result.merged}｜skipped ${result.skipped}`);
+    for (const one of result.perSession ?? []) {
+      const bad = one.errors.length ? ` errors ${one.errors.length}` : "";
+      console.log(`  · ${one.session}: merged ${one.merged} / skipped ${one.skipped}${bad}`);
+      for (const err of one.errors) console.log(`      ✗ ${err}`);
+    }
+    if (result.backupDirs.length) console.log(`backup: ${result.backupDirs.join(", ")}`);
+    if (result.errors.length) {
+      console.log("errors:");
+      for (const err of result.errors) console.log(`- ${err}`);
+    }
+    console.log(opts.applyMerge ? "（已回灌并重建 index.md）" : "（dry-run：什么都没写；加 --apply 才回灌）");
   } else if (opts.mode === "dry-run") {
     console.log("== migrate-dangling dry-run ==");
     console.log(`root: ${result.root}`);

package/src/rooms/migrate.mjs

@@ -410,6 +410,210 @@ export function apply(root, { now = Date.now(), backupRoot = backupsRoot(), stam
   return summary;
 }
 
+/* ───────────────────────────── merge（sidecar 回灌） ───────────────────────────── */
+
+/**
+ * merge 的备份目录：`<backupRoot>/merge-<iso>`（apply 且真的写了才创建）。
+ * 与 apply 的整目录备份同根（`<DSH_HOME>/chess-context/migrate-backups`），便于排障时一处找齐。
+ */
+export function mergeBackupDir({ backupRoot = backupsRoot(), stamp = new Date() } = {}) {
+  const dir = nodePath.join(backupRoot, `merge-${stamp.toISOString().replace(/[:.]/g, "-")}`);
+  nodeFs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * 校验 sidecar 并读出边（纯只读，不碰图）。
+ * @returns {{ok:boolean, errors:string[], sidecar:any, edges:any[]}}
+ */
+export function readSidecar(file, { sessionId = "" } = {}) {
+  const errors = [];
+  let sidecar = null;
+  if (!nodeFs.existsSync(file)) return { ok: false, errors: [`sidecar 不存在：${file}`], sidecar: null, edges: [] };
+  try {
+    sidecar = JSON.parse(nodeFs.readFileSync(file, "utf8"));
+  } catch (error) {
+    return { ok: false, errors: [`sidecar 不是合法 JSON（${String(error?.message ?? error)}）`], sidecar: null, edges: [] };
+  }
+  if (sidecar === null || typeof sidecar !== "object") errors.push("sidecar 顶层不是对象");
+  if (sidecar?.format !== SIDECAR_FORMAT) errors.push(`sidecar format 不对：${String(sidecar?.format)}（应为 ${SIDECAR_FORMAT}）`);
+  if (sidecar?.version !== SIDECAR_VERSION) errors.push(`sidecar version 不支持：${String(sidecar?.version)}（应为 ${SIDECAR_VERSION}）`);
+  if (sessionId && typeof sidecar?.sessionId === "string" && sidecar.sessionId.length > 0 && sidecar.sessionId !== sessionId) {
+    errors.push(`sidecar 属于别的会话：${sidecar.sessionId}（当前 ${sessionId}）`);
+  }
+  const edges = Array.isArray(sidecar?.edges) ? sidecar.edges : null;
+  if (edges === null) errors.push("sidecar.edges 不是数组");
+  else if (edges.length === 0) errors.push("sidecar 里没有边（空边）");
+  if (Array.isArray(edges)) {
+    edges.forEach((edge, i) => {
+      if (edge === null || typeof edge !== "object") errors.push(`edges[${i}] 不是对象`);
+      else if (typeof edge.id !== "string" || edge.id.length === 0) errors.push(`edges[${i}] 缺 id`);
+    });
+  }
+  return { ok: errors.length === 0, errors, sidecar, edges: errors.length === 0 ? edges : [] };
+}
+
+/**
+ * 把一个 sidecar 回灌进会话图（R14）。
+ *
+ * 语义（与 apply 对称）：
+ *   · 按 **edge.id** 合并；图里已有同 id ⇒ **跳过**（绝不覆盖当前边）；
+ *   · 保留 sidecar 里的原字段（JSON 深拷贝，不重算/不改写）；
+ *   · 有改动才 `updatedAt = now`、原子写 graph.json、**重建 index.md**；
+ *   · **默认 dry-run**（不写任何文件）；`apply:true` 才写，写之前把 graph.json / index.md
+ *     备份到 `<backupRoot>/merge-<iso>/`，并落一份 `MERGE.json` 审计；
+ *   · 幂等：同一 sidecar 回灌第二次 ⇒ `merged:0`、`skipped:N`、不写盘、不建备份。
+ *
+ * @param {string} dir 会话目录（含 graph.json）
+ * @param {{sidecarFile?:string, apply?:boolean, backupRoot?:string, stamp?:Date, now?:number}} [options]
+ * @returns {{mode:string, session:string, sidecar:string, ok:boolean, dryRun:boolean, total:number, merged:number, skipped:number, duplicates:number, mergedIds:string[], errors:string[], backupDir:string, graphBytesBefore:number, graphBytesAfter:number, indexRebuilt:boolean}}
+ */
+export function mergeSidecar(dir, { sidecarFile = "", apply = false, backupRoot = backupsRoot(), stamp = new Date(), now = Date.now() } = {}) {
+  const session = nodePath.basename(dir);
+  const file = sidecarFile || nodePath.join(dir, SIDECAR_NAME);
+  const result = {
+    mode: apply ? "merge-apply" : "merge-dry-run",
+    session,
+    sidecar: file,
+    ok: false,
+    dryRun: !apply,
+    total: 0,
+    merged: 0,
+    skipped: 0,
+    duplicates: 0,
+    mergedIds: [],
+    errors: [],
+    backupDir: "",
+    graphBytesBefore: 0,
+    graphBytesAfter: 0,
+    indexRebuilt: false,
+  };
+
+  const graphFile = nodePath.join(dir, "graph.json");
+  if (!nodeFs.existsSync(graphFile)) {
+    result.errors.push(`会话目录里没有 graph.json：${graphFile}`);
+    return result;
+  }
+  const read = readSidecar(file, { sessionId: session });
+  if (!read.ok) {
+    result.errors.push(...read.errors);
+    return result;
+  }
+  result.total = read.edges.length;
+
+  let text;
+  let g;
+  try {
+    text = nodeFs.readFileSync(graphFile, "utf8");
+    g = fromJSON(text);
+  } catch (error) {
+    result.errors.push(`graph.json 读不出（${String(error?.message ?? error)}）`);
+    return result;
+  }
+  result.graphBytesBefore = Buffer.byteLength(text);
+
+  const seen = new Set();
+  for (const edge of read.edges) {
+    if (seen.has(edge.id)) {
+      result.duplicates += 1;
+      continue;
+    }
+    seen.add(edge.id);
+    if (g.edges && g.edges[edge.id]) {
+      result.skipped += 1;
+      continue;
+    }
+    g.edges[edge.id] = JSON.parse(JSON.stringify(edge));
+    result.mergedIds.push(edge.id);
+    result.merged += 1;
+  }
+
+  if (result.merged === 0) {
+    // 幂等：没有新边 ⇒ 一个字节都不写（不建备份、不碰 index.md）
+    result.graphBytesAfter = result.graphBytesBefore;
+    result.ok = true;
+    return result;
+  }
+
+  g.updatedAt = now;
+  const next = toJSON(g);
+  result.graphBytesAfter = Buffer.byteLength(next);
+
+  if (!apply) {
+    result.ok = true;
+    return result;
+  }
+
+  // ① 显式备份（graph.json + index.md）；② 原子写 graph.json；③ 重建 index.md；④ MERGE.json 审计
+  const backupDir = mergeBackupDir({ backupRoot, stamp });
+  result.backupDir = backupDir;
+  nodeFs.copyFileSync(graphFile, nodePath.join(backupDir, "graph.json"));
+  const indexFile = nodePath.join(dir, "index.md");
+  if (nodeFs.existsSync(indexFile)) nodeFs.copyFileSync(indexFile, nodePath.join(backupDir, "index.md"));
+  writeFileAtomic(graphFile, next);
+  writeFileAtomic(indexFile, renderIndexMd(g));
+  result.indexRebuilt = true;
+  writeFileAtomic(
+    nodePath.join(backupDir, "MERGE.json"),
+    JSON.stringify({ ...result, appliedAt: new Date(now).toISOString(), root: dir }, null, 1),
+  );
+  result.ok = true;
+  return result;
+}
+
+/**
+ * 回灌一批会话（CLI 用）：`target` 可以是单个 sidecar 文件、单个会话目录、或会话根目录。
+ * 返回汇总 + 每会话结果。任何一条出错 ⇒ `ok:false`（但已成功的仍然写完了，逐条可查）。
+ */
+export function mergeMany(target, { apply = false, backupRoot = backupsRoot(), stamp = new Date(), now = Date.now() } = {}) {
+  const dirs = [];
+  const sidecars = [];
+  if (!nodeFs.existsSync(target)) {
+    return {
+      mode: apply ? "merge-apply" : "merge-dry-run",
+      target,
+      sessions: 0,
+      merged: 0,
+      skipped: 0,
+      ok: false,
+      errors: [`目标不存在：${target}`],
+      backupDirs: [],
+      perSession: [],
+    };
+  }
+  if (nodeFs.statSync(target).isDirectory()) {
+    const direct = nodePath.join(target, SIDECAR_NAME);
+    if (nodeFs.existsSync(direct) && nodeFs.existsSync(nodePath.join(target, "graph.json"))) {
+      dirs.push(target);
+    } else {
+      for (const dir of listSessions(target)) {
+        if (nodeFs.existsSync(nodePath.join(dir, SIDECAR_NAME))) dirs.push(dir);
+      }
+    }
+  } else {
+    sidecars.push(target);
+  }
+  const perSession = dirs.map((dir) => mergeSidecar(dir, { apply, backupRoot, stamp, now }));
+  for (const file of sidecars) {
+    // sidecar 文件 → 会话目录 = 它的父目录
+    perSession.push(mergeSidecar(nodePath.dirname(file), { sidecarFile: file, apply, backupRoot, stamp, now }));
+  }
+  const merged = perSession.reduce((n, r) => n + r.merged, 0);
+  const skipped = perSession.reduce((n, r) => n + r.skipped, 0);
+  const errors = perSession.flatMap((r) => r.errors.map((e) => `${r.session}: ${e}`));
+  return {
+    mode: apply ? "merge-apply" : "merge-dry-run",
+    target,
+    sessions: perSession.length,
+    merged,
+    skipped,
+    ok: perSession.length > 0 && errors.length === 0,
+    errors,
+    backupDirs: perSession.map((r) => r.backupDir).filter(Boolean),
+    perSession,
+  };
+}
+
 /* ───────────────────────────── verify ───────────────────────────── */
 
 /**