@modusensus/dsh-mneme 0.9.0 → 0.9.1

package/src/pipeline-attribution.js

@@ -0,0 +1,165 @@
+/**
+ * M.O.（Modus Operandi）的**归属规则**：把宿主的一次工具动作，映射成「它可能是工作流里的哪一步」。
+ *
+ * 这个模块存在的唯一理由，是执行链要记账时必须先回答一个问题：**这一次动作算哪一步？**
+ * 没有这条规则，观察到的动作与工作流里的步骤编号是两套东西，记下来的账谁也读不懂；
+ * 而「认真记了但没人能对账」比不记更糟——它会让面板显示一份看起来完整的假历史。
+ *
+ * ## 为什么只出候选，绝不下结论
+ *
+ * 本仓工作流里的 `tool` 字段是**人手写的自由文本**，实测形态：单命令（`npm test`）、
+ * 多命令并列（`git log / gh pr list`）、带占位符（`git push <tag>`），19 步里还有 4 步
+ * 是空的。拿这种文本去和宿主动作做精确匹配，命中率注定不高，而**误匹配的代价远大于漏匹配**：
+ * 把「推 tag」记成「推分支」，`deriveState` 就会据此把错误的一步染成可信。
+ *
+ * 所以本模块的产出是**候选 + 理由**，由人（或上游的显式动作）确认；认不出来就是空数组，
+ * **「认不出来」是合法答案，不许猜**。这与反事实判据那边同一条纪律：机器只写观察到的。
+ *
+ * ## 匹配分档
+ *
+ * - `exact`：归一化后整条命令相等（`npm test` ↔ `npm test`）
+ * - `weak`：命令头相同、参数不同或缺失（`git push` ↔ `git push <tag>`）
+ * - 其余不给候选
+ *
+ * 同一档内出现多条候选时，**全部返回**、不挑一个——挑一个就等于替人做了决定，而
+ * 「两条工作流步骤长得一样」这件事该由人看着消歧。
+ *
+ * ## 调用方要自己分的三桶
+ *
+ * 本模块只给 `attributionCandidates` 一个入口；把一批观察归类是调用方的事，但要照这条口径分：
+ *   matched   有候选（可能多条，由人消歧）
+ *   unmatched 命令拼得出来，但没有任何步骤对得上
+ *   skipped   命令行都拼不出来，归属无从谈起
+ *
+ * **「认不出来」与「没有这一步」必须长得不一样**，否则一份全是 unmatched 的报告会被读成
+ * 「这次什么也没做」——与账本那边「缺账」和「坏账」要分开是同一条纪律。
+ */
+
+/** 命令里的占位符：`<tag>` / `<版本>`。它们不是字面量，不该参与比较。
+ *  实测真实工作流只用尖括号这一种形态（`{}` 与 `[]` 各 0 次），不为假想的写法留分支。 */
+const PLACEHOLDER_RE = /<[^>]*>/gu;
+
+/**
+ * 命令分隔符：一人写的 `tool` 里常见 `git log / gh pr list` 这种并列写法。
+ * 用 `/` 分隔有歧义（路径里也有 `/`），所以只在**两侧有空白**时才当分隔符，
+ * 否则 `/` 属于参数的一部分（`gh workflow run release-prep.yml` 不能被切碎）。
+ * 实测真实工作流只出现这一种（`|` / `;` / `&&` 各 0 次），同样不留假想分支。
+ */
+const SEPARATOR_RE = /\s+\/\s+/u;
+
+/** 归一化：小写、去占位符、折叠空白。占位符去掉而不是替换成通配，否则 `git push <tag>` 会宽到能匹配一切。 */
+export function normalizeCommand(text) {
+  if (typeof text !== "string") return "";
+  return text
+    .replace(PLACEHOLDER_RE, " ")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .toLowerCase();
+}
+
+/** 一条 `tool` 文本可能包含多条并列命令：拆开，逐条参与匹配。 */
+export function commandParts(tool) {
+  if (typeof tool !== "string") return [];
+  return tool
+    .split(SEPARATOR_RE)
+    .map((part) => normalizeCommand(part))
+    .filter((part) => part !== "");
+}
+
+/** 切成词。命令行的词就是空格分隔的片段；这里不做完整的 shell 解析（引号、转义），
+ *  因为 `tool` 字段是**人写的说明文本**而不是可执行脚本，解析得越精细越容易把说明当脚本。 */
+function tokensOf(command) {
+  return command.split(" ").filter((t) => t !== "");
+}
+
+/**
+ * 一个是否是另一个的**词前缀**：`["gh","pr","create"]` 是 `["gh","pr","create","--base","main"]`
+ * 的前缀。这是「弱匹配」的判据。
+ *
+ * 为什么不用「第一个词相同」：真实工作流里 `git` 出现 5 次、`gh pr` 出现 4 次，按首词匹配
+ * 会让一次 `git push` 报出六条候选——**噪声盖过信号**，人看一眼就放弃了。
+ * 词前缀表达的是「这次跑的就是那一步，只是多带了参数」，这才是真实形态：
+ * 人写 `gh pr create`，agent 跑的是 `gh pr create --base main --title …`。
+ */
+function isTokenPrefix(shorter, longer) {
+  if (shorter.length === 0 || shorter.length > longer.length) return false;
+  for (let i = 0; i < shorter.length; i += 1) {
+    if (shorter[i] !== longer[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * 观察记录的形状（上游负责拼）。
+ *
+ * `command` 是**尽力而为**的命令行：宿主给的是工具名 + 结构化参数，把参数拼成命令行这件事
+ * 由调用方按工具类型做。拼不出来就给空串——空串不会匹配上任何东西，是安全的默认。
+ */
+export function normalizeObservation(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const command = normalizeCommand(raw.command);
+  if (command === "") return null; // 认不出命令行 = 这条观察对归属无用，直接丢给上游
+  return {
+    tool: typeof raw.tool === "string" ? raw.tool : "",
+    command,
+    ok: raw.ok === true ? true : raw.ok === false ? false : null // 三态：真 / 假 / 不知道
+  };
+}
+
+/**
+ * 给一次观察找候选步骤。返回按档位排序的数组（exact 在前），可能为空。
+ *
+ * **不返回「最佳候选」**：那会诱使调用方直接采用它。调用方要决策，就得自己面对
+ * 「可能为空」「可能多条」这两个事实。
+ */
+export function attributionCandidates(observation, pipeline) {
+  const obs = normalizeObservation(observation);
+  if (!obs || !pipeline || !Array.isArray(pipeline.steps)) return [];
+
+  const obsTokens = tokensOf(obs.command);
+  const out = [];
+  for (const step of pipeline.steps) {
+    const parts = commandParts(step.tool);
+    // 空 tool 的步骤**结构性地无法被归属**。这不是缺陷，是事实：作者没写它怎么跑。
+    // 把它报告出来（而不是跳过），好让「为什么这一步永远没账」有据可查。
+    if (parts.length === 0) continue;
+
+    for (const part of parts) {
+      if (part === obs.command) {
+        out.push({
+          stepId: step.id,
+          confidence: "exact",
+          matched: part,
+          why: `命令与步骤里写的完全一致（${part}）`
+        });
+        break;
+      }
+      const partTokens = tokensOf(part);
+      if (isTokenPrefix(partTokens, obsTokens) || isTokenPrefix(obsTokens, partTokens)) {
+        const longer = partTokens.length >= obsTokens.length ? part : obs.command;
+        out.push({
+          stepId: step.id,
+          confidence: "weak",
+          matched: part,
+          why: `像同一步但参数不同：步骤写的是「${part}」，这次是「${obs.command}」（${longer} 多带了参数）`
+        });
+        break;
+      }
+    }
+  }
+
+  out.sort((a, b) => (a.confidence === b.confidence ? a.stepId.localeCompare(b.stepId) : a.confidence === "exact" ? -1 : 1));
+  return out;
+}
+
+/**
+ * 结构性不可归属的步骤：作者没写 `tool`，所以它**永远不会**拿到账。
+ *
+ * 单独给一个入口，是为了让「为什么这一步永远没账」有据可查——否则它看起来只是
+ * 「还没跑过」，而真相是这条工作流根本没写明它怎么跑。
+ */
+export function unattributableSteps(pipeline) {
+  return (pipeline && Array.isArray(pipeline.steps) ? pipeline.steps : [])
+    .filter((s) => commandParts(s.tool).length === 0)
+    .map((s) => s.id);
+}

package/src/pipeline-command.js

@@ -0,0 +1,279 @@
+/**
+ * M.O. 的**开窗命令**：`/mo-run`。
+ *
+ * ## 为什么需要一条命令，而不是让插件自己判断
+ *
+ * 「哪条工作流正在被走」这件事**没法自动判**：工作流的 `trigger` 字段是人话
+ * （`{kind:"phrase", value:"发版"}`），拿它去匹配用户消息只能猜，而猜错会把一条
+ * **从没跑过的流程**记成跑过、还把节点染成可信。所以窗口的边界由**显式动作**划，
+ * 这条命令就是那个动作。
+ *
+ * 与仓库里既有的 `commands.js`（用户自定义指令）不同：那条路只把文本转发给模型，
+ * 不持有状态；这一条要真的开/关一个窗口，所以单独成模块。
+ *
+ * ## 三个子命令
+ *
+ * - `/mo-run start <pipeline-id>` —— 开窗。之后这个会话里的命令执行才可能被记账
+ * - `/mo-run stop` —— 结账并落盘
+ * - `/mo-run status` —— 只看「走到哪了」，不结账
+ *
+ * ## 为什么把结果文本说这么细
+ *
+ * 命令的回执是这个功能**唯一的对外窗口**（面板那一侧还没做）。它必须能回答：
+ * 开的哪条、走了几步、有多少条认不出来、为什么没写账。含糊其辞的回执会让使用者
+ * 以为「跑成功了」，而实际可能一条观察都没认出来——那正是这个功能最该避免的事。
+ */
+
+import { STR } from "./lang.js";
+
+/** 命令名与用法。名字走本仓的 `COMMAND_NAME` 约定：小写字母起头。 */
+export const MO_RUN_COMMAND = "mo-run";
+
+/**
+ * 解析 `/mo-run` 后面的原始输入。
+ *
+ * 五个子命令：
+ * - `start <id>`：开窗
+ * - `stop`：结账，**产出待确认清单**（P2 起不再自动落盘）
+ * - `confirm <答案>`：人确认哪几步走了 → 这才写账
+ * - `status`：看状态（不带参数时的默认，最安全）
+ *
+ * `confirm` 的答案格式刻意做成**最短的两种**，避免让人背语法：
+ * - `/mo-run confirm P6 V2` —— 这几步做了（空格分隔）
+ * - `/mo-run confirm P6:* V2:-` —— 带标记：`*` 做了、`-` 没做、`?` 不确定
+ *
+ * 没提到的步骤**什么都不写**（既不是"做了"也不是"没做"）——见 pipeline-confirm 的注释。
+ */
+export function parseMoRunInput(rawInput) {
+  const text = typeof rawInput === "string" ? rawInput.trim() : "";
+  if (text === "") return { action: "status" }; // 不带参数 = 看状态，最安全
+  const [verb, ...rest] = text.split(/\s+/u);
+  const arg = rest.join(" ").trim();
+  switch ((verb ?? "").toLowerCase()) {
+    case "start":
+      return { action: "start", pipelineId: arg };
+    case "stop":
+      return { action: "stop" };
+    case "confirm":
+      return { action: "confirm", answers: parseConfirmArg(arg) };
+    case "status":
+      return { action: "status" };
+    default:
+      return { action: "help", unknown: verb };
+  }
+}
+
+/**
+ * `confirm` 的参数 → `{ stepId: "done"|"notDone"|"unsure" }`。
+ *
+ * 两种写法都收：
+ * - `P6`        → done（最常用，直接列做了哪几步）
+ * - `P6:*` / `P6:-` / `P6:?` → done / notDone / unsure
+ *
+ * 解析不了的一律**不放进结果**（宁可少答，不可猜答案）——非法值会在
+ * `runFromAnswers` 那一层被拒，这里只负责拆分。
+ */
+export function parseConfirmArg(arg) {
+  const answers = {};
+  if (typeof arg !== "string" || arg.trim() === "") return answers;
+  for (const token of arg.split(/[\s,]+/u)) {
+    if (token === "") continue;
+    const [idPart, markPart] = token.split(":", 2);
+    const id = idPart.trim();
+    if (id === "") continue;
+    if (markPart === undefined || markPart.trim() === "") {
+      answers[id] = "done";
+      continue;
+    }
+    const mark = markPart.trim();
+    if (mark === "*") answers[id] = "done";
+    else if (mark === "-") answers[id] = "notDone";
+    else if (mark === "?") answers[id] = "unsure";
+    // 其它标记：不放进结果（不是"没做"，是"没答"）
+  }
+  return answers;
+}
+
+/**
+ * 把「本次观察到哪些业务动作」渲染成几行。
+ *
+ * 这是这一版回执的**主菜**：自动归属的命中率实测只有 14%，所以回执不再声称
+ * "我替你对上了哪几步"，而是如实列出"这一遍你干了什么"，由人决定它对不对得上。
+ *
+ * 只显示 `动词 子命令 ×次数`（可带旗标）——**位置参数在分桶层就被丢弃了**，
+ * 因为完整命令行含绝对路径（路径含本机用户名），而这条回执会显示在界面上。
+ * 那也是 pipeline-activities.js 存在的第二个理由。
+ */
+function renderActivities(activities, t, maxRows = 12) {
+  if (!Array.isArray(activities) || activities.length === 0) return "";
+  const rows = activities.slice(0, maxRows).map((a) => {
+    // 键在没有子命令时用的是第一个旗标（`node --test`）——那种情况下别再把同一个旗标
+    // 追加一遍，否则会渲染成 `node --test --test`（端到端复验时抓到的重复）。
+    const shown = (a.flags || []).filter((f) => !a.key.endsWith(f));
+    const flags = shown.length ? ` ${shown.join(" ")}` : "";
+    return `  ${a.key}${flags} ×${a.count}`;
+  });
+  const more = activities.length > maxRows ? `\n  …另有 ${activities.length - maxRows} 种` : "";
+  return `${t.activities(activities.length)}\n${rows.join("\n")}${more}`;
+}
+
+/**
+ * 把一次 `stop()` 的结果翻成人话。
+ *
+ * P2 起 `stop` **不再写账**，而是产出一份待确认清单。所以这里的重点从
+ * "记了几步"变成"**请你确认哪几步走了**"——并给出步骤表与观察到的动作，供人对照。
+ */
+function describeStop(result, language) {
+  const t = STR.moRunStop[language];
+  const activityBlock = renderActivities(result.activities, t);
+
+  if (result.ok && result.state === "awaiting-confirmation") {
+    const prop = result.proposal;
+    const lines = prop.steps.map((s, i) => {
+      const hint = s.hintCount ? `  ← 本次看到 ${s.hintCount} 条相近命令` : "";
+      return `  ${i + 1}. ${s.id}  ${s.title}${s.declared ? `  [${s.declared}]` : ""}${hint}`;
+    });
+    const parts = [t.awaiting(prop.pipelineId, prop.steps.length)];
+    parts.push(lines.join("\n"));
+    if (activityBlock) parts.push(activityBlock);
+    // 「这条命令不是动作」与「没归属上」是两件事，混在一起会让人以为工具坏了
+    if (result.shellNoise) parts.push(t.shellNoise(result.shellNoise));
+    if (result.notCommands) parts.push(t.notCommands(result.notCommands));
+    if (result.truncated) parts.push(t.truncated);
+    parts.push(t.confirmHow(prop.steps.map((s) => s.id).slice(0, 3).join(" ")));
+    return parts.filter(Boolean).join("\n");
+  }
+
+  if (result.ok) {
+    const parts = [t.ok(result.pipelineId, result.steps)];
+    if (activityBlock) parts.push(activityBlock);
+    if (result.truncated) parts.push(t.truncated);
+    return parts.filter(Boolean).join("\n");
+  }
+
+  switch (result.reason) {
+    case "no-open-window":
+      return t.noWindow;
+    case "write-failed":
+      return t.writeFailed(result.detail);
+    default:
+      return t.failed(result.reason);
+  }
+}
+
+/** 把一次 `confirm()` 的结果翻成人话。 */
+function describeConfirm(result, language) {
+  const t = STR.moRunConfirm[language];
+  if (result.ok) {
+    const parts = [t.ok(result.pipelineId, result.steps)];
+    if (result.notDone?.length) parts.push(t.notDone(result.notDone.join("、")));
+    if (result.unsure?.length) parts.push(t.unsure(result.unsure.join("、")));
+    if (result.unanswered?.length) parts.push(t.unanswered(result.unanswered.join("、")));
+    // P3 的核心产出：你说这步做了，但声明的命令这次一次都没出现。
+    // 三种可能（声明该改 / 本来不必敲 / 记错了）必须由人判——系统只负责把矛盾摆出来。
+    if (result.toolMismatches?.length) {
+      const rows = result.toolMismatches.map((m) => {
+        const seen = m.observedTop?.length ? `；本次实际看到 ${m.observedTop.join("、")}` : "；本次没有可对照的动作";
+        return `  ${m.stepId}（${m.title}）：声明 ${m.declared}，本次未出现${seen}`;
+      });
+      parts.push(t.mismatch(result.toolMismatches.length, rows.join("\n")));
+    }
+    // 旁挂回执：给不给只取决于 memoryDir 是否配置——静默关闭是设计，不是失败
+    if (result.observationsSaved?.ok) {
+      parts.push(t.obsSaved(result.observationsSaved.file));
+    }
+    return parts.filter(Boolean).join("\n");
+  }
+  switch (result.reason) {
+    case "nothing-to-confirm":
+      return t.nothingToConfirm;
+    case "no-answers":
+      // 说了"没做"是记录；什么都没说不是——这条区分很重要。
+      return t.noAnswers(result.notDone?.length ?? 0, result.unsure?.length ?? 0, result.unanswered?.length ?? 0);
+    case "bad-answer-value":
+      return t.badValue(result.stepId, result.value);
+    case "unknown-step":
+      return t.unknownStep(result.stepId);
+    case "write-failed":
+      return t.writeFailed(result.detail);
+    default:
+      return t.failed(result.reason);
+  }
+}
+
+function describeStart(result, language) {
+  const t = STR.moRunStart[language];
+  if (result.ok) return t.ok(result.pipelineId, result.steps);
+  switch (result.reason) {
+    case "already-open":
+      return t.alreadyOpen(result.pipelineId);
+    case "pipeline-not-found":
+      return t.notFound(result.available?.length ? result.available.join("、") : t.noneAvailable);
+    case "pipeline-unreadable":
+      return t.unreadable(result.detail);
+    case "no-project-root":
+      return t.noProject;
+    case "no-session":
+      return t.noSession;
+    default:
+      return t.failed(result.reason);
+  }
+}
+
+function describeStatus(status, language) {
+  const t = STR.moRunStatus[language];
+  if (status.awaitingConfirmation) return t.awaiting(status.pipelineId, status.steps ?? 0);
+  if (!status.open) return t.closed;
+  return t.open(status, status.recorded.join("、") || t.none);
+}
+
+/**
+ * 造命令的 handler。
+ *
+ * handler 的返回值走 DSH 的 CommandResult 契约：**只作 UI 回执，不会进模型上下文**。
+ * 这个功能的目的是记账，不是给模型派活，所以不需要 `agent.followup`。
+ */
+export function createMoRunHandler({ recorder, language = () => "zh" } = {}) {
+  return (invocation) => {
+    const lang = language();
+    try {
+      const parsed = parseMoRunInput(invocation?.rawInput);
+      const session = invocation?.agent?.session;
+
+      if (parsed.action === "help") {
+        return { kind: "success", text: STR.moRunUsage[lang] };
+      }
+      if (parsed.action === "start") {
+        if (!parsed.pipelineId) return { kind: "error", text: STR.moRunUsage[lang] };
+        return { kind: "success", text: describeStart(recorder.start({ session, pipelineId: parsed.pipelineId }), lang) };
+      }
+      if (parsed.action === "stop") {
+        return { kind: "success", text: describeStop(recorder.stop({ session }), lang) };
+      }
+      if (parsed.action === "confirm") {
+        const result = recorder.confirm({ session, answers: parsed.answers });
+        return { kind: result.ok ? "success" : "error", text: describeConfirm(result, lang) };
+      }
+      return { kind: "success", text: describeStatus(recorder.status({ session }), lang) };
+    } catch (error) {
+      // 命令是用户主动触发的动作，不是热路径；出错就如实回报，但绝不把异常抛进宿主。
+      return { kind: "error", text: STR.moRunUsage[lang] };
+    }
+  };
+}
+
+/**
+ * 注册命令。**默认关**：只有旗标打开才注册——beta 功能必须 opt-in，老用户行为不变。
+ *
+ * 返回 disposer（与仓库其它注册点一致）；没注册时返回 null。
+ */
+export function registerMoRunCommand({ ctx, recorder, enabled, language = () => "zh" }) {
+  if (enabled !== true) return null;
+  if (typeof ctx?.commands?.register !== "function") return null;
+  return ctx.commands.register({
+    name: MO_RUN_COMMAND,
+    description: STR.moRunDescription[language()],
+    input: { hint: STR.moRunInputHint[language()] },
+    handler: createMoRunHandler({ recorder, language })
+  });
+}

package/src/pipeline-confirm.js

@@ -0,0 +1,142 @@
+/**
+ * M.O. 的人确认层：把「本次观察到什么」变成「哪几步真的走了」。
+ *
+ * ## 为什么必须由人来说
+ *
+ * 自动归属被实测否决（详见 mneme-research 的 08/09）：
+ * - 拿单条命令匹配手写步骤表，唯一归属只有 **14.2%**；非发版会话也有 4.4%，**区分力仅 3 倍**
+ * - 放宽到"包含匹配"，天花板仍 14%，且大头是 `git log` / `git diff` 这类通用命令
+ * - 工作流里的关键步骤 `gh pr merge --rebase` 在 21723 次调用里**出现 0 次**——
+ *   说明清单本身可能与实际行为脱节
+ *
+ * 归到本文档的一句话：**机器猜不准，而猜错的代价是把没走过的步骤记成走过**
+ * （`deriveState` 会据此把它染成 `trusted`）。所以这一步交给人。
+ *
+ * ## 三个设计决定
+ *
+ * 1. **提案不改动任何东西**。`buildProposal` 是纯函数，产出的是"给人看的待确认清单"。
+ *    写账只发生在 `confirm` 之后，且只写人点过的步骤。
+ * 2. **"不确定"是一个合法的答案**。人可以对某一步说"我不知道"——它既不记为走过，
+ *    也不记为跳过。这与账本那边「缺字段的行不许被算成 uses」是同一条纪律：
+ *    **没确认 ≠ 没发生，也 ≠ 发生**。
+ * 3. **必须能报"整条流程都没走"**。人可以说"这次什么都没做"，那就是一条**零步 run**
+ *    ——但账本契约要求 `run.steps` 至少一项（见 `pipeline-runs` 的校验），所以那种情况
+ *    本模块如实返回 `{ kind: "nothing" }` 而不是伪造一条空 run。
+ */
+
+/**
+ * 造一份确认提案（纯函数，不落盘、不改任何状态）。
+ *
+ * 输入：
+ * - `pipeline`：本次要走的流程（含 steps）
+ * - `activities`：P1 产出的业务动作清单（`[{key, count, flags}]`），给人当参照
+ * - `hints`：自动归属的候选（可空），**只作提示**
+ *
+ * 输出刻意把两类信息分开：
+ * - `steps`：**流程自己的**步骤表（人在这里勾）
+ * - `activities`：**观察到的**业务动作（人在这对照）
+ * 两者不做自动配对——那正是被否决的那件事。
+ */
+export function buildProposal({ pipeline, activities = [], hints = null } = {}) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) {
+    return { ok: false, reason: "no-pipeline" };
+  }
+
+  const steps = pipeline.steps.map((s) => ({
+    id: s.id,
+    title: s.title,
+    // 步骤表里人写的 tool 原文——给对照用，不是匹配依据
+    declared: typeof s.tool === "string" ? s.tool : "",
+    // 机器给的候选提示：**只给一个次数**，不给命令行原文（原文含绝对路径）。
+    // 它只是提示，不预选——人仍然要自己说这一步做没做。
+    hintCount: Number.isFinite(hints?.[s.id]) ? hints[s.id] : 0
+  }));
+
+  return {
+    ok: true,
+    pipelineId: pipeline.id,
+    steps,
+    activities: activities.map((a) => ({ key: a.key, count: a.count, flags: a.flags || [] }))
+    // 不返回 answers 词表：命令层有自己的解析表，写死两份只会漂。
+    // 也不返回 pipelineTitle / observations：零消费者（ponytail 复核点名的两处）。
+  };
+}
+
+/**
+ * 校验并归一人的回答。
+ *
+ * `answers` 形如 `{ "P6": "done", "V2": "notDone" }`。
+ * **只认三类值**，其余一律拒——静默把非法值当"没发生"是编造的一种。
+ */
+export function normalizeAnswers(answersResult, pipeline) {
+  if (!pipeline || !Array.isArray(pipeline.steps)) return { ok: false, reason: "no-pipeline" };
+  if (!answersResult || typeof answersResult !== "object" || Array.isArray(answersResult)) {
+    return { ok: false, reason: "bad-answers" };
+  }
+  const ids = new Set(pipeline.steps.map((s) => s.id));
+  const clean = {};
+  for (const [id, value] of Object.entries(answersResult)) {
+    if (!ids.has(id)) return { ok: false, reason: "unknown-step", stepId: id };
+    if (value !== "done" && value !== "notDone" && value !== "unsure") {
+      return { ok: false, reason: "bad-answer-value", stepId: id, value };
+    }
+    clean[id] = value;
+  }
+  return { ok: true, answers: clean };
+}
+
+/**
+ * 把确认结果变成一条 run（**仍然不落盘**，落盘由调用方做）。
+ *
+ * 三种结局分得很清：
+ * - `kind:"run"`：**至少一条记录**（`done` 或 `notDone`）→ 产出一条 run
+ * - `kind:"nothing"`：**什么记录都没有**（全 unsure / 全没答）→ 不产 run
+ * - `kind:"error"`：回答非法
+ *
+ * ⚠️ 一处容易写错的语义（本文档的注释最初就写错过，被测试抓出来）：
+ * **「全部 notDone」不等于「零步」**。人确认"这两步这次都没做"是一条**合法且完整**的
+ * 记录（两条 `skipped`），它描述的事实是"走了这条流程、但一步都没执行"。
+ * 真正进 `nothing` 的只有**什么都没确认**（人没开口）——那才是没有信息可记。
+ *
+ * 关于 `notDone` 与 `unsure` 的差别（这是本模块最要紧的语义）：
+ * - 人明确说 **notDone**（这一步这次没做）→ 记 `skipped: true`
+ * - 人 **没回答**或说 **unsure** → **什么都不写**（既不 skipped 也不 uses）
+ *   因为"没确认"与"确认没做"是两回事，混起来会把"忘了勾"记成"这步被跳过"，
+ *   而跳过计数正是 `RETIRE_AFTER_SKIPS` 提议删步的依据——错一次就多一条错提议。
+ */
+export function runFromAnswers({ pipeline, answers, by = "human", triggeredBy = "", now = () => new Date() } = {}) {
+  const normalized = normalizeAnswers(answers, pipeline);
+  if (!normalized.ok) return { kind: "error", reason: normalized.reason, stepId: normalized.stepId, value: normalized.value };
+
+  const at = new Date(now()).toISOString();
+  const steps = [];
+  for (const step of pipeline.steps) {
+    const answer = normalized.answers[step.id];
+    if (answer === "done") {
+      steps.push({ id: step.id, at, skipped: false, detoured: false, refuted: false, note: "" });
+    } else if (answer === "notDone") {
+      steps.push({ id: step.id, at, skipped: true, detoured: false, refuted: false, note: "人确认这次没做" });
+    }
+    // unsure / 无回答 → 不写任何东西（见函数头注释）
+  }
+
+  if (steps.length === 0) {
+    return {
+      kind: "nothing",
+      reason: "no-steps-confirmed",
+      // 如实回报：哪些是"人确认没做"、哪些是"没答"
+      notDone: pipeline.steps.filter((s) => normalized.answers[s.id] === "notDone").map((s) => s.id),
+      unanswered: pipeline.steps.filter((s) => normalized.answers[s.id] === undefined).map((s) => s.id),
+      unsure: pipeline.steps.filter((s) => normalized.answers[s.id] === "unsure").map((s) => s.id)
+    };
+  }
+
+  return {
+    kind: "run",
+    run: { at, by, triggeredBy, steps },
+    // 没写进账的两种原因分开报——「确认没做」与「没答」不该长得一样
+    notDone: pipeline.steps.filter((s) => normalized.answers[s.id] === "notDone").map((s) => s.id),
+    unanswered: pipeline.steps.filter((s) => normalized.answers[s.id] === undefined).map((s) => s.id),
+    unsure: pipeline.steps.filter((s) => normalized.answers[s.id] === "unsure").map((s) => s.id)
+  };
+}