@modusensus/dsh-mneme 0.14.0-beta.1 → 0.14.0-beta.2

package/lib/pipeline-observations.js

@@ -1,181 +1,181 @@
-/**
- * P3 的两个产出：观察旁挂（丙方案）与 tool 不符检出。
- *
- * ## 背景（一句话）
- *
- * 自动归属被实测否决（14.2%，第三方复核 74% 变体唯一），所以写账由人确认；
- * 而人确认时说「这一步做了」，可与本次**实际观察到的业务动作**对不上——
- * 「声明是 npm test，这次一次 npm test 都没看到」。这个矛盾是步骤表过时的信号，
- * 就是 P3 要捕的东西（设计见 mneme-research/mo-foundations/10 号）。
- *
- * ## 丙方案：观察为什么不进账本、要旁挂
- *
- * 账本 `.runs.jsonl` 是**已发布的数据契约**（v0.9.0 发出去的形状），为 P3 加字段
- * 是「动已发布契约」，代价与风险都不必要。所以观察走旁挂文件：
- *
- *     <memoryDir>/observations/<项目键>/<工作流id>.jsonl
- *
- * 这在这个仓库有**三次同构先例**：candidates / proposals / 本目录。
- * 共同纪律：**项目键分桶、只增不改（append-only）、不进仓库、坏行跳过但计数**。
- *
- * ## 🔴 隐私
- *
- * 观察清单的每一项都来自 `pipeline-activities` 的产物——那一层已经**剥掉了位置参数**
- * （完整命令行含绝对路径，路径含本机用户名）。本模块**只存 `{key, count, flags}`**，
- * 拒收任何带命令原文的形状。这是第二道闸：即使上游改了，这里也不放行。
- */
-
-import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-
-/** 展开 `~`；观察旁挂跟 candidates/proposals 一样是本地状态（candidates.js 的 expandHome 同构）。
- *  config.memoryDir 的默认值是 "~/.dsh/memory"，不展开的话 readdir 在带 "~" 的字面路径上
- *  永远落空——旁挂静默读不到，fix-step-tool 提议少一类（CodeRabbit #458 F2）。 */
-function expandHome(p) {
-  const s = String(p || "");
-  if (s === "~") return homedir();
-  if (s.startsWith("~/") || s.startsWith("~\\")) return join(homedir(), s.slice(2));
-  return s;
-}
-
-/** 观察旁挂的目录：`<memoryDir>/observations/<项目键>/`。与 candidates/proposals 同构。 */
-export function observationDir({ memoryDir, projectKey } = {}) {
-  if (!projectKey || String(projectKey).trim() === "") return null;
-  const base = expandHome(memoryDir && String(memoryDir).trim() ? memoryDir : "~/.dsh/memory");
-  return join(base, "observations", projectKey);
-}
-
-/** 观察行的形状闸：只认 {key, count}（flags 可选且必须是旗标数组）。多一个字段都拒。 */
-export function validateObservationLine(raw) {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, reason: "not-object" };
-  if (typeof raw.key !== "string" || raw.key.trim() === "") return { ok: false, reason: "bad-key" };
-  if (!Number.isInteger(raw.count) || raw.count < 1) return { ok: false, reason: "bad-count" };
-  if (raw.flags !== undefined && !Array.isArray(raw.flags)) return { ok: false, reason: "bad-flags" };
-  if (raw.command !== undefined || raw.args !== undefined || raw.segments !== undefined) {
-    // 🔴 命令原文（或其片段）不许出现在观察行里——那是位置参数泄露的口子
-    return { ok: false, reason: "forbidden-field" };
-  }
-  return { ok: true };
-}
-
-/**
- * 落盘一次确认时的观察清单（append-only，幂等键 = confirmAt）。
- *
- * 返回 `{ok, file, lines}`；传 `dryRun: true` 时只校验不写（测试与预览用）。
- */
-export function saveObservations({ dir, pipelineId, confirmAt, activities, dryRun = false } = {}) {
-  if (!dir) return { ok: false, reason: "no-dir" };
-  if (!pipelineId || typeof pipelineId !== "string") return { ok: false, reason: "no-pipeline-id" };
-  if (typeof confirmAt !== "string" || confirmAt.trim() === "") return { ok: false, reason: "no-confirm-at" };
-  if (!Array.isArray(activities)) return { ok: false, reason: "bad-activities" };
-
-  const valid = [];
-  for (const a of activities) {
-    // 🔴 先验**原始输入**再构造：多带 command/args/segments 的行要**大声拒**，
-    // 不是悄悄剥掉——静默剥离会把上游的形状 bug 藏进一次"成功"的写入里。
-    const v0 = validateObservationLine(a);
-    if (!v0.ok) return { ok: false, reason: "invalid-line:" + v0.reason, file: null, lines: 0 };
-    const line = { key: a.key, count: a.count, ...(Array.isArray(a.flags) && a.flags.length ? { flags: a.flags } : {}) };
-    valid.push(line);
-  }
-
-  const record = { contract: "mneme.observations/v1", pipelineId, confirmAt, activities: valid };
-  const file = join(dir, `${pipelineId}.jsonl`);
-
-  // 幂等：同一 confirmAt 已写过就不重复（confirm 保留待确认状态重答的场景会重放）
-  if (existsSync(file)) {
-    const seen = readFileSync(file, "utf8").split("\n").filter((l) => l.trim());
-    for (const l of seen) {
-      try { if (JSON.parse(l).confirmAt === confirmAt) return { ok: true, file, lines: 0, duplicate: true }; }
-      catch { /* 坏行：与读侧同一纪律，跳过但不出声 */ }
-    }
-  }
-
-  if (dryRun) return { ok: true, file, lines: valid.length, dryRun: true };
-  mkdirSync(dir, { recursive: true });
-  appendFileSync(file, JSON.stringify(record) + "\n", "utf8");
-  return { ok: true, file, lines: valid.length };
-}
-
-/** 读一个工作流攒下的全部观察（按 confirmAt 升序，坏行跳过并计数）。 */
-export function loadObservations(dir, pipelineId) {
-  if (!dir || !pipelineId) return { records: [], unreadable: 0 };
-  const file = join(dir, `${pipelineId}.jsonl`);
-  if (!existsSync(file)) return { records: [], unreadable: 0 };
-  const records = [];
-  let unreadable = 0;
-  for (const l of readFileSync(file, "utf8").split("\n")) {
-    if (!l.trim()) continue;
-    try {
-      const r = JSON.parse(l);
-      if (r?.contract === "mneme.observations/v1" && Array.isArray(r.activities)) records.push(r);
-      else unreadable += 1;
-    } catch { unreadable += 1; }
-  }
-  return { records, unreadable };
-}
-
-/**
- * 批量读多个工作流的观察，压成 readPipelineDoc 要的形状：
- *   { [pipelineId]: { latest: { activities } } }
- *
- * `latest` 取最后一条记录（confirmAt 升序写入，末条即最近一次确认）。
- * 没有观察的 id 不出现在结果里——读侧用 `?? null` 降级，不制造空壳。
- */
-export function loadObservationsById(dir, pipelineIds) {
-  const out = {};
-  for (const id of pipelineIds || []) {
-    if (typeof id !== "string" || id.trim() === "") continue;
-    const { records, unreadable } = loadObservations(dir, id);
-    if (records.length === 0) {
-      // 有文件但全坏也如实记一条空 latest？——不。空 = 没有观察，与坏文件同形处理，
-      //  unreadable 的计数只在单工作流读取时暴露，批量视图里降级为「没有」。
-      continue;
-    }
-    const last = records[records.length - 1];
-    out[id] = { latest: { activities: last.activities }, unreadable };
-  }
-  return out;
-}
-
-/**
- * 🔴 核心判据：从「人确认的执行集」与「本次观察到的动作」里算出 tool 不符。
- *
- * - `pipeline.steps[].tool`：人手写的声明（可能是 `git push`，或 `a / b` 多锚点）
- * - `confirmedDone`：人说了 done 的 stepId 集合
- * - `activities`：本次观察到的业务动作（`{key, count}`）——**只认 key，不认命令原文**
- *
- * 返回不符清单。**unsure 与没答不进判据**（那不是「做了但没看到」，是「没确认」）。
- * `declared` 原样带出，不含路径（tool 是作者手写的，且没有经过本模块之外的清洗——
- * 若作者把路径写进 tool，那是步骤表自己的内容，应由步骤表校验层管，不在这里扩大职责）。
- */
-export function toolMismatches({ pipeline, confirmedDone, activities } = {}) {
-  if (!pipeline || !Array.isArray(pipeline.steps)) return { ok: false, reason: "no-pipeline", items: [] };
-  if (!(confirmedDone instanceof Set)) return { ok: false, reason: "bad-confirmed", items: [] };
-  if (!Array.isArray(activities)) return { ok: false, reason: "bad-activities", items: [] };
-
-  const seen = new Set(activities.map((a) => String(a?.key ?? "").toLowerCase()).filter(Boolean));
-  const items = [];
-  for (const step of pipeline.steps) {
-    if (!confirmedDone.has(step.id)) continue;
-    const declared = typeof step.tool === "string" ? step.tool.trim() : "";
-    if (declared === "") continue;              // 纯人判步骤（无 tool 声明）无从矛盾
-    const anchors = declared.split("/").map((t) => t.trim().toLowerCase()).filter(Boolean);
-    // 多锚点（`a / b`）任一出现即算对上——它们是作者声明的同义做法
-    const hit = anchors.some((a) => seen.has(a));
-    if (!hit) {
-      items.push({
-        stepId: step.id,
-        title: step.title,
-        declared,
-        observedTop: activities
-          .slice()
-          .sort((a, b) => (b.count ?? 0) - (a.count ?? 0))
-          .slice(0, 3)
-          .map((a) => `${a.key} ×${a.count}`)
-      });
-    }
-  }
-  return { ok: true, items };
-}
+/**
+ * P3 的两个产出：观察旁挂（丙方案）与 tool 不符检出。
+ *
+ * ## 背景（一句话）
+ *
+ * 自动归属被实测否决（14.2%，第三方复核 74% 变体唯一），所以写账由人确认；
+ * 而人确认时说「这一步做了」，可与本次**实际观察到的业务动作**对不上——
+ * 「声明是 npm test，这次一次 npm test 都没看到」。这个矛盾是步骤表过时的信号，
+ * 就是 P3 要捕的东西（设计见 mneme-research/mo-foundations/10 号）。
+ *
+ * ## 丙方案：观察为什么不进账本、要旁挂
+ *
+ * 账本 `.runs.jsonl` 是**已发布的数据契约**（v0.9.0 发出去的形状），为 P3 加字段
+ * 是「动已发布契约」，代价与风险都不必要。所以观察走旁挂文件：
+ *
+ *     <memoryDir>/observations/<项目键>/<工作流id>.jsonl
+ *
+ * 这在这个仓库有**三次同构先例**：candidates / proposals / 本目录。
+ * 共同纪律：**项目键分桶、只增不改（append-only）、不进仓库、坏行跳过但计数**。
+ *
+ * ## 🔴 隐私
+ *
+ * 观察清单的每一项都来自 `pipeline-activities` 的产物——那一层已经**剥掉了位置参数**
+ * （完整命令行含绝对路径，路径含本机用户名）。本模块**只存 `{key, count, flags}`**，
+ * 拒收任何带命令原文的形状。这是第二道闸：即使上游改了，这里也不放行。
+ */
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** 展开 `~`；观察旁挂跟 candidates/proposals 一样是本地状态（candidates.js 的 expandHome 同构）。
+ *  config.memoryDir 的默认值是 "~/.dsh/memory"，不展开的话 readdir 在带 "~" 的字面路径上
+ *  永远落空——旁挂静默读不到，fix-step-tool 提议少一类（CodeRabbit #458 F2）。 */
+function expandHome(p) {
+  const s = String(p || "");
+  if (s === "~") return homedir();
+  if (s.startsWith("~/") || s.startsWith("~\\")) return join(homedir(), s.slice(2));
+  return s;
+}
+
+/** 观察旁挂的目录：`<memoryDir>/observations/<项目键>/`。与 candidates/proposals 同构。 */
+export function observationDir({ memoryDir, projectKey } = {}) {
+  if (!projectKey || String(projectKey).trim() === "") return null;
+  const base = expandHome(memoryDir && String(memoryDir).trim() ? memoryDir : "~/.dsh/memory");
+  return join(base, "observations", projectKey);
+}
+
+/** 观察行的形状闸：只认 {key, count}（flags 可选且必须是旗标数组）。多一个字段都拒。 */
+export function validateObservationLine(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, reason: "not-object" };
+  if (typeof raw.key !== "string" || raw.key.trim() === "") return { ok: false, reason: "bad-key" };
+  if (!Number.isInteger(raw.count) || raw.count < 1) return { ok: false, reason: "bad-count" };
+  if (raw.flags !== undefined && !Array.isArray(raw.flags)) return { ok: false, reason: "bad-flags" };
+  if (raw.command !== undefined || raw.args !== undefined || raw.segments !== undefined) {
+    // 🔴 命令原文（或其片段）不许出现在观察行里——那是位置参数泄露的口子
+    return { ok: false, reason: "forbidden-field" };
+  }
+  return { ok: true };
+}
+
+/**
+ * 落盘一次确认时的观察清单（append-only，幂等键 = confirmAt）。
+ *
+ * 返回 `{ok, file, lines}`；传 `dryRun: true` 时只校验不写（测试与预览用）。
+ */
+export function saveObservations({ dir, pipelineId, confirmAt, activities, dryRun = false } = {}) {
+  if (!dir) return { ok: false, reason: "no-dir" };
+  if (!pipelineId || typeof pipelineId !== "string") return { ok: false, reason: "no-pipeline-id" };
+  if (typeof confirmAt !== "string" || confirmAt.trim() === "") return { ok: false, reason: "no-confirm-at" };
+  if (!Array.isArray(activities)) return { ok: false, reason: "bad-activities" };
+
+  const valid = [];
+  for (const a of activities) {
+    // 🔴 先验**原始输入**再构造：多带 command/args/segments 的行要**大声拒**，
+    // 不是悄悄剥掉——静默剥离会把上游的形状 bug 藏进一次"成功"的写入里。
+    const v0 = validateObservationLine(a);
+    if (!v0.ok) return { ok: false, reason: "invalid-line:" + v0.reason, file: null, lines: 0 };
+    const line = { key: a.key, count: a.count, ...(Array.isArray(a.flags) && a.flags.length ? { flags: a.flags } : {}) };
+    valid.push(line);
+  }
+
+  const record = { contract: "mneme.observations/v1", pipelineId, confirmAt, activities: valid };
+  const file = join(dir, `${pipelineId}.jsonl`);
+
+  // 幂等：同一 confirmAt 已写过就不重复（confirm 保留待确认状态重答的场景会重放）
+  if (existsSync(file)) {
+    const seen = readFileSync(file, "utf8").split("\n").filter((l) => l.trim());
+    for (const l of seen) {
+      try { if (JSON.parse(l).confirmAt === confirmAt) return { ok: true, file, lines: 0, duplicate: true }; }
+      catch { /* 坏行：与读侧同一纪律，跳过但不出声 */ }
+    }
+  }
+
+  if (dryRun) return { ok: true, file, lines: valid.length, dryRun: true };
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(file, JSON.stringify(record) + "\n", "utf8");
+  return { ok: true, file, lines: valid.length };
+}
+
+/** 读一个工作流攒下的全部观察（按 confirmAt 升序，坏行跳过并计数）。 */
+export function loadObservations(dir, pipelineId) {
+  if (!dir || !pipelineId) return { records: [], unreadable: 0 };
+  const file = join(dir, `${pipelineId}.jsonl`);
+  if (!existsSync(file)) return { records: [], unreadable: 0 };
+  const records = [];
+  let unreadable = 0;
+  for (const l of readFileSync(file, "utf8").split("\n")) {
+    if (!l.trim()) continue;
+    try {
+      const r = JSON.parse(l);
+      if (r?.contract === "mneme.observations/v1" && Array.isArray(r.activities)) records.push(r);
+      else unreadable += 1;
+    } catch { unreadable += 1; }
+  }
+  return { records, unreadable };
+}
+
+/**
+ * 批量读多个工作流的观察，压成 readPipelineDoc 要的形状：
+ *   { [pipelineId]: { latest: { activities } } }
+ *
+ * `latest` 取最后一条记录（confirmAt 升序写入，末条即最近一次确认）。
+ * 没有观察的 id 不出现在结果里——读侧用 `?? null` 降级，不制造空壳。
+ */
+export function loadObservationsById(dir, pipelineIds) {
+  const out = {};
+  for (const id of pipelineIds || []) {
+    if (typeof id !== "string" || id.trim() === "") continue;
+    const { records, unreadable } = loadObservations(dir, id);
+    if (records.length === 0) {
+      // 有文件但全坏也如实记一条空 latest？——不。空 = 没有观察，与坏文件同形处理，
+      //  unreadable 的计数只在单工作流读取时暴露，批量视图里降级为「没有」。
+      continue;
+    }
+    const last = records[records.length - 1];
+    out[id] = { latest: { activities: last.activities }, unreadable };
+  }
+  return out;
+}
+
+/**
+ * 🔴 核心判据：从「人确认的执行集」与「本次观察到的动作」里算出 tool 不符。
+ *
+ * - `pipeline.steps[].tool`：人手写的声明（可能是 `git push`，或 `a / b` 多锚点）
+ * - `confirmedDone`：人说了 done 的 stepId 集合
+ * - `activities`：本次观察到的业务动作（`{key, count}`）——**只认 key，不认命令原文**
+ *
+ * 返回不符清单。**unsure 与没答不进判据**（那不是「做了但没看到」，是「没确认」）。
+ * `declared` 原样带出，不含路径（tool 是作者手写的，且没有经过本模块之外的清洗——
+ * 若作者把路径写进 tool，那是步骤表自己的内容，应由步骤表校验层管，不在这里扩大职责）。
+ */
+export function toolMismatches({ pipeline, confirmedDone, activities } = {}) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) return { ok: false, reason: "no-pipeline", items: [] };
+  if (!(confirmedDone instanceof Set)) return { ok: false, reason: "bad-confirmed", items: [] };
+  if (!Array.isArray(activities)) return { ok: false, reason: "bad-activities", items: [] };
+
+  const seen = new Set(activities.map((a) => String(a?.key ?? "").toLowerCase()).filter(Boolean));
+  const items = [];
+  for (const step of pipeline.steps) {
+    if (!confirmedDone.has(step.id)) continue;
+    const declared = typeof step.tool === "string" ? step.tool.trim() : "";
+    if (declared === "") continue;              // 纯人判步骤（无 tool 声明）无从矛盾
+    const anchors = declared.split("/").map((t) => t.trim().toLowerCase()).filter(Boolean);
+    // 多锚点（`a / b`）任一出现即算对上——它们是作者声明的同义做法
+    const hit = anchors.some((a) => seen.has(a));
+    if (!hit) {
+      items.push({
+        stepId: step.id,
+        title: step.title,
+        declared,
+        observedTop: activities
+          .slice()
+          .sort((a, b) => (b.count ?? 0) - (a.count ?? 0))
+          .slice(0, 3)
+          .map((a) => `${a.key} ×${a.count}`)
+      });
+    }
+  }
+  return { ok: true, items };
+}

package/lib/pipeline-observe.js

@@ -1,133 +1,133 @@
-/**
- * 把宿主的会话事件，翻成归属规则认得的**观察**。
- *
- * ## 为什么需要这一层（接线前实测出来的事实）
- *
- * 会话日志里的工具调用长这样：`name:"pwsh"`，`arguments:'{"command":"npm test"}'`。
- * 而工作流里人写的 `tool` 是**命令行**：`"npm test"`、`"git push <tag>"`。
- * **两者不重叠**——直接拿 `name` 去比，一条都对不上（实测 400 个会话里
- * `pwsh` 1399 次、`read` 1709 次、`glob` 183 次，而工作流写的是 npm/git/gh 命令）。
- *
- * 唯一能对上的是：**命令跑在哪个工具里**。所以这一层的职责就是把它抽出来——
- * `{name:"pwsh", arguments:{command:"npm test"}}` → `{command:"npm test"}`。
- *
- * ## 为什么只抽「命令执行器」，其余一律不给观察
- *
- * 真实工作流 19 步的 `tool` 全是 shell 命令（git / gh / npm / node）。而 `read`、`write`、
- * `glob`、`grep` 这些是**代理的日常动作**，不是任何工作流的一步。硬把
- * `read C:\…\file.js` 拼成一个「命令行」去参与匹配，只会制造噪声——而噪声的代价是
- * 把某一步凭空染色。所以认不出来命令执行器，就**不产观察**（返回 null），
- * 由上游记进 skipped 桶：**「不是工作流的动作」与「认不出是哪一步」是两件事。**
- *
- * ## 成败的三态
- *
- * `tool/result` 带 `message.isError`。只认 true/false 两个值，取不到时留 `null`
- * ——把「不知道」折叠成「失败」会给这一步打上不该有的 refuted 标记。
- */
-
-/** 命令执行器：只有跑在这些工具里的调用，才可能是工作流写成的那种命令行。 */
-const COMMAND_TOOLS = new Set(["pwsh", "bash", "sh", "shell", "cmd", "run_command", "terminal"]);
-
-/** 参数里哪个字段是命令行。按工具名给，取不到就退回常见字段名。 */
-const COMMAND_KEYS = ["command", "cmd", "script", "commandLine"];
-
-function parseArgs(raw) {
-  if (raw === null || raw === undefined) return null;
-  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
-  if (typeof raw !== "string") return null;
-  try {
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 这次工具调用是不是一条工作流命令。是就给出命令行，不是给 `null`。
- *
- * 返回 `{tool, command}`；`command` 已去掉首尾空白（比较由归属规则负责）。
- */
-export function commandFromToolCall(name, args) {
-  const tool = typeof name === "string" ? name.trim() : "";
-  if (tool === "" || !COMMAND_TOOLS.has(tool.toLowerCase())) return null;
-  const parsed = parseArgs(args);
-  if (!parsed) return null;
-  for (const key of COMMAND_KEYS) {
-    const value = parsed[key];
-    if (typeof value === "string" && value.trim() !== "") {
-      return { tool, command: value.trim() };
-    }
-  }
-  // 是命令执行器但参数里没有命令行（形状变了）：不猜，给 null。
-  return null;
-}
-
-/** `tool/result` 的成败：只认布尔，拿不到留 null（「不知道」不许折叠成「失败」）。 */
-export function outcomeOfToolResult(event) {
-  const message = event?.data?.message;
-  if (!message || typeof message !== "object") return null;
-  if (message.isError === true) return false;
-  if (message.isError === false) return true;
-  // 旧形状把 isError 挂在 content 的 tool-result 块上；两种都不认时留 null。
-  const blocks = Array.isArray(message.content) ? message.content : [];
-  const legacy = blocks.find((b) => b && b.type === "tool-result");
-  if (legacy && typeof legacy.isError === "boolean") return legacy.isError !== true;
-  return null;
-}
-
-/**
- * 把一串会话事件配对成观察列表（纯函数，便于测试与批处理）。
- *
- * 配对靠 `callId`：`tool/call` 先到、`tool/result` 后到。**只有拿到结果的调用才产观察**
- * ——结果决定了成败，而「调了但没结果」既不是成功也不是失败（可能被中断），
- * 拿它当一次成功使用是编造。
- *
- * 另外两条纪律：
- * - 认不出命令执行器的调用**直接丢**（进 `notCommands` 计数），不产观察
- * - 有调用没结果的，如实进 `dangling`，不产观察也不假装失败
- */
-export function pairObservations(events) {
-  const pending = new Map(); // callId -> {tool, command, at}
-  const observations = [];
-  const dangling = [];
-  let notCommands = 0;
-
-  for (const event of events || []) {
-    const type = event?.type;
-    if (type === "tool/call") {
-      const data = event.data ?? {};
-      const extracted = commandFromToolCall(data.name, data.arguments);
-      if (!extracted) {
-        notCommands += 1;
-        continue;
-      }
-      const callId = data.callId ?? null;
-      const entry = { ...extracted, at: event.at ?? null };
-      if (callId === null) {
-        // 没有 callId 就无法配对結果；不硬凑，如实记下。
-        dangling.push({ ...entry, why: "调用没有 callId，无法与结果配对" });
-        continue;
-      }
-      pending.set(callId, entry);
-      continue;
-    }
-
-    if (type === "tool/result") {
-      const callId = event?.data?.callId ?? event?.callId ?? null;
-      if (callId === null || !pending.has(callId)) continue;
-      const entry = pending.get(callId);
-      pending.delete(callId);
-      observations.push({
-        tool: entry.tool,
-        command: entry.command,
-        ok: outcomeOfToolResult(event),
-        at: entry.at
-      });
-    }
-  }
-
-  for (const entry of pending.values()) dangling.push({ ...entry, why: "调用没有等到结果" });
-
-  return { observations, dangling, notCommands };
-}
+/**
+ * 把宿主的会话事件，翻成归属规则认得的**观察**。
+ *
+ * ## 为什么需要这一层（接线前实测出来的事实）
+ *
+ * 会话日志里的工具调用长这样：`name:"pwsh"`，`arguments:'{"command":"npm test"}'`。
+ * 而工作流里人写的 `tool` 是**命令行**：`"npm test"`、`"git push <tag>"`。
+ * **两者不重叠**——直接拿 `name` 去比，一条都对不上（实测 400 个会话里
+ * `pwsh` 1399 次、`read` 1709 次、`glob` 183 次，而工作流写的是 npm/git/gh 命令）。
+ *
+ * 唯一能对上的是：**命令跑在哪个工具里**。所以这一层的职责就是把它抽出来——
+ * `{name:"pwsh", arguments:{command:"npm test"}}` → `{command:"npm test"}`。
+ *
+ * ## 为什么只抽「命令执行器」，其余一律不给观察
+ *
+ * 真实工作流 19 步的 `tool` 全是 shell 命令（git / gh / npm / node）。而 `read`、`write`、
+ * `glob`、`grep` 这些是**代理的日常动作**，不是任何工作流的一步。硬把
+ * `read C:\…\file.js` 拼成一个「命令行」去参与匹配，只会制造噪声——而噪声的代价是
+ * 把某一步凭空染色。所以认不出来命令执行器，就**不产观察**（返回 null），
+ * 由上游记进 skipped 桶：**「不是工作流的动作」与「认不出是哪一步」是两件事。**
+ *
+ * ## 成败的三态
+ *
+ * `tool/result` 带 `message.isError`。只认 true/false 两个值，取不到时留 `null`
+ * ——把「不知道」折叠成「失败」会给这一步打上不该有的 refuted 标记。
+ */
+
+/** 命令执行器：只有跑在这些工具里的调用，才可能是工作流写成的那种命令行。 */
+const COMMAND_TOOLS = new Set(["pwsh", "bash", "sh", "shell", "cmd", "run_command", "terminal"]);
+
+/** 参数里哪个字段是命令行。按工具名给，取不到就退回常见字段名。 */
+const COMMAND_KEYS = ["command", "cmd", "script", "commandLine"];
+
+function parseArgs(raw) {
+  if (raw === null || raw === undefined) return null;
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 这次工具调用是不是一条工作流命令。是就给出命令行，不是给 `null`。
+ *
+ * 返回 `{tool, command}`；`command` 已去掉首尾空白（比较由归属规则负责）。
+ */
+export function commandFromToolCall(name, args) {
+  const tool = typeof name === "string" ? name.trim() : "";
+  if (tool === "" || !COMMAND_TOOLS.has(tool.toLowerCase())) return null;
+  const parsed = parseArgs(args);
+  if (!parsed) return null;
+  for (const key of COMMAND_KEYS) {
+    const value = parsed[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return { tool, command: value.trim() };
+    }
+  }
+  // 是命令执行器但参数里没有命令行（形状变了）：不猜，给 null。
+  return null;
+}
+
+/** `tool/result` 的成败：只认布尔，拿不到留 null（「不知道」不许折叠成「失败」）。 */
+export function outcomeOfToolResult(event) {
+  const message = event?.data?.message;
+  if (!message || typeof message !== "object") return null;
+  if (message.isError === true) return false;
+  if (message.isError === false) return true;
+  // 旧形状把 isError 挂在 content 的 tool-result 块上；两种都不认时留 null。
+  const blocks = Array.isArray(message.content) ? message.content : [];
+  const legacy = blocks.find((b) => b && b.type === "tool-result");
+  if (legacy && typeof legacy.isError === "boolean") return legacy.isError !== true;
+  return null;
+}
+
+/**
+ * 把一串会话事件配对成观察列表（纯函数，便于测试与批处理）。
+ *
+ * 配对靠 `callId`：`tool/call` 先到、`tool/result` 后到。**只有拿到结果的调用才产观察**
+ * ——结果决定了成败，而「调了但没结果」既不是成功也不是失败（可能被中断），
+ * 拿它当一次成功使用是编造。
+ *
+ * 另外两条纪律：
+ * - 认不出命令执行器的调用**直接丢**（进 `notCommands` 计数），不产观察
+ * - 有调用没结果的，如实进 `dangling`，不产观察也不假装失败
+ */
+export function pairObservations(events) {
+  const pending = new Map(); // callId -> {tool, command, at}
+  const observations = [];
+  const dangling = [];
+  let notCommands = 0;
+
+  for (const event of events || []) {
+    const type = event?.type;
+    if (type === "tool/call") {
+      const data = event.data ?? {};
+      const extracted = commandFromToolCall(data.name, data.arguments);
+      if (!extracted) {
+        notCommands += 1;
+        continue;
+      }
+      const callId = data.callId ?? null;
+      const entry = { ...extracted, at: event.at ?? null };
+      if (callId === null) {
+        // 没有 callId 就无法配对結果；不硬凑，如实记下。
+        dangling.push({ ...entry, why: "调用没有 callId，无法与结果配对" });
+        continue;
+      }
+      pending.set(callId, entry);
+      continue;
+    }
+
+    if (type === "tool/result") {
+      const callId = event?.data?.callId ?? event?.callId ?? null;
+      if (callId === null || !pending.has(callId)) continue;
+      const entry = pending.get(callId);
+      pending.delete(callId);
+      observations.push({
+        tool: entry.tool,
+        command: entry.command,
+        ok: outcomeOfToolResult(event),
+        at: entry.at
+      });
+    }
+  }
+
+  for (const entry of pending.values()) dangling.push({ ...entry, why: "调用没有等到结果" });
+
+  return { observations, dangling, notCommands };
+}