@modusensus/dsh-mneme 0.9.0 → 0.9.2

package/src/pipeline-activities.js

@@ -0,0 +1,178 @@
+/**
+ * 把 shell 观察压成**人能扫的「业务动作」清单**。
+ *
+ * ## 为什么需要这一层（三组实测逼出来的）
+ *
+ * 1. 拿单条命令去匹配手写步骤表，命中率只有 14.2~15.2%（非发版会话 4.4%，
+ *    区分力仅 3 倍）→ **拿清单套行为这条路走不通**。
+ * 2. 想用「整段命令」当分组键：每个会话中位 **539 组**、最多 7373 组
+ *    → 文献那套「聚类 + 人命名」直接照搬也不成立（网页活动本来只有几十个页面）。
+ * 3. 换「动词」当键：密度最高的全是 **PowerShell 管道语法**
+ *    （`write-output` 10619、`select-object` 10422、`}` 4864…）
+ *    → **「命令 ≈ 动作」这个预设是错的**：大部分"命令"不是活动，是句子成分。
+ * 4. 只留业务命令（git/gh/npm/node/docker…）后：业务段占 **6.5%**，
+ *    不同动词 **8 个**、不同前两词组 **1010 个** —— 这才是人能扫的量级。
+ *
+ * ## 这个模块的产出：一份「本次窗口观察到什么」清单
+ *
+ * 形态：`git status ×12`、`gh pr ×5`、`npm test ×3`。
+ * **不猜它对应哪一步**——那件事交给人（见 mneme-research 的 09 号文档）。
+ *
+ * ## 🔴 隐私：为什么只输出「动词 + 子命令」
+ *
+ * 完整命令行里**几乎必然含绝对路径**，而路径里含本机用户名。例如实测里真实出现过
+ * `set-location "c:\users\<用户名>\desktop\..."`。这条回执是要显示在界面上、
+ * 可能被截图的那一面——所以本模块有一条硬规则：
+ *
+ * > **位置参数一律丢弃，只保留动词、子命令与 `-` 开头的旗标。**
+ *
+ * 旗标是语义（`--rebase` / `--force` / `-m`），位置参数是数据（路径、文件名、id）。
+ * 只留前者，清单既表意又不泄露。这不是"顺手过滤"，是这一层存在的第二个理由。
+ */
+
+/**
+ * 业务命令的动词白名单。
+ *
+ * 判据不是"常见"，而是"**它的执行会构成工作流的一步**"——即它有语义
+ * （改仓库状态、发版、跑测试），而不是在组装文本（`write-output`、`foreach-object`）。
+ *
+ * 这张名单是**拍的**（实测里 6.5% 的段落在名单内），未验证覆盖率：
+ * 可能有业务动作用了别的工具（`python`、`curl`、`cargo`）。认不出来不产清单项，
+ * 是安全的方向——它只会让清单更短，不会让它更假。
+ */
+const BUSINESS_VERBS = new Set([
+  // 实测 21723 次调用里，真正命中的只有这四个：git / gh / npm / node。
+  // 其余先不收——认不出来只会让清单更短，不会让它更假；
+  // 等真有项目用上了再加（这一版刻意不做"猜未来会用到"的预留）。
+  "git", "gh", "npm", "npx", "node", "docker"
+]);
+
+/** 命令分隔符：与 pipeline-attribution 同一口径（只认两侧带空白的）。 */
+const SEPARATOR_RE = /\s*(?:;|&&|\|\||\|)\s*|\n/u;
+
+/** 重定向尾巴（`2>&1`、`> file`、`2>nul`）：不是命令的一部分。 */
+const REDIRECT_RE = /\s*\d?>\s*&?\s*\S+/gu;
+
+/** `cd <路径>`：前导定位语句，不是活动。 */
+const CD_RE = /^cd\s/iu;
+
+/**
+ * 这个 token 像不像一个**子命令**。
+ *
+ * 必须做这道校验，否则三件事都会发生（都是端到端实测抓到的）：
+ * 1. `node d:\dsh\...\probe.mjs` → 把**脚本路径**当成 sub，路径里的用户名被带出去；
+ * 2. `git -C $(Join-Path ...) log --oneline` → 把 `$(Join-Path` 当成 sub，清单里出现
+ *    `git (join-path -C --oneline` 这种读不懂的东西；
+ * 3. `node x.test.js` → **带点的文件名**被当成 sub（`x.test.js` 完全符合"小写字母起头
+ *    的短词"）。这条是加完前两条修复后复验时才冒出来的。
+ *
+ * 所以除了字符集，还要**排除含点的 token**：子命令带点是极罕见的
+ * （`git log` / `gh pr` / `npm test` / `kubectl get` 都不带），而文件名几乎都带。
+ * 宁可漏认一个，不可把文件名当子命令——后者会出现在给人看的清单里。
+ */
+function looksLikeSubcommand(token) {
+  if (typeof token !== "string") return false;
+  const t = token.replace(/^["']|["']$/gu, "");
+  // 一个正则同时挡住四类坏值：旗标（`-` 开头）、含点的文件名、`$(…)` 这类
+  // shell 片段、以及超长的东西。上一版写成五道 if，等价但更啰嗦。
+  return /^[a-z0-9][a-z0-9_-]{0,19}$/u.test(t);
+}
+
+/**
+ * 一条命令 → 一个业务动作。
+ *
+ * 返回 `{ verb, sub, flags }` 或 `null`（不是业务命令，或抽不出动词）。
+ * - `verb`：白名单里的动词（小写）
+ * - `sub`：**扫描出的第一个像子命令的 token**（不是"第一个非旗标 token"——那个
+ *   可能是路径或参数，见 `looksLikeSubcommand`）。找不到就是空串
+ * - `flags`：`-` 开头的旗标。**位置参数一律丢弃**（理由见文件头隐私一节）
+ */
+export function businessCommandOf(command) {
+  if (typeof command !== "string") return null;
+  const cleaned = command.replace(REDIRECT_RE, " ").trim();
+  if (cleaned === "" || CD_RE.test(cleaned)) return null;
+
+  const tokens = cleaned.split(/\s+/u).filter((t) => t !== "");
+  if (tokens.length === 0) return null;
+
+  const verb = tokens[0].toLowerCase().replace(/^["']|["']$/gu, "");
+  if (!BUSINESS_VERBS.has(verb)) return null;
+
+  // **扫描**而不是取第一个非旗标：`git -C <path> log` 的子命令在 `-C <值>` 之后。
+  let sub = "";
+  for (let i = 1; i < tokens.length; i += 1) {
+    if (looksLikeSubcommand(tokens[i])) {
+      sub = tokens[i].replace(/^["']|["']$/gu, "").toLowerCase();
+      break;
+    }
+  }
+
+  // 旗标：只留 `-` 开头的、短的、不含路径分隔符的（`--base=<path>` 这类直接丢）。
+  const flags = [];
+  for (const raw of tokens.slice(1)) {
+    const t = raw.replace(/^["']|["']$/gu, "");
+    if (t.startsWith("-") && t.length > 1 && t.length <= 24 && !/[/\\=]/u.test(t)) flags.push(t);
+  }
+
+  return { verb, sub, flags: [...new Set(flags)].slice(0, 4) };
+}
+
+/**
+ * 分组的键。
+ *
+ * 优先用子命令（`git status`）。**没有子命令时退而用第一个旗标**——因为对
+ * `node` / `npm` 这类工具，真正区分语义的常常就是旗标：`node --test`（跑测试）与
+ * `node --check`（查语法）是两件事，若键里只有 `node`，它们会被合并成一行，
+ * 清单就读不出差别了。这条是端到端实测里发现的（16 次 node 调用被并成一条）。
+ *
+ * **旗标仍然只是"补充"，不是主体**：`git status -C --porcelain` 的键是 `git status`，
+ * `-C`（它后面本来跟着一个被丢弃的路径）不该挤进键里。
+ */
+export function activityKey(activity) {
+  if (!activity) return "";
+  const tail = activity.sub || (Array.isArray(activity.flags) ? activity.flags[0] : "") || "";
+  return tail ? `${activity.verb} ${tail}` : activity.verb;
+}
+
+/**
+ * 一批观察 → 业务动作清单（按出现次数降序）。
+ *
+ * 每条：`{ key, verb, sub, count, flags }`；`flags` 是出现过的旗标并集（截断）。
+ * **不含任何位置参数**，因此不含路径与用户名。
+ */
+export function tallyActivities(observations) {
+  const groups = new Map();
+  let shellNoise = 0;
+  let totalSegments = 0;
+
+  for (const observation of observations || []) {
+    const command = observation?.command;
+    if (typeof command !== "string" || command.trim() === "") continue;
+    for (const raw of command.split(SEPARATOR_RE)) {
+      if (raw.trim() === "") continue;
+      totalSegments += 1;
+      const activity = businessCommandOf(raw);
+      if (!activity) {
+        shellNoise += 1;
+        continue;
+      }
+      const key = activityKey(activity);
+      const cur = groups.get(key) || { key, verb: activity.verb, sub: activity.sub, count: 0, flags: new Set() };
+      cur.count += 1;
+      for (const f of activity.flags) cur.flags.add(f);
+      groups.set(key, cur);
+    }
+  }
+
+  const activities = [...groups.values()]
+    .map((g) => ({ key: g.key, verb: g.verb, sub: g.sub, count: g.count, flags: [...g.flags].slice(0, 6) }))
+    .sort((a, b) => (b.count === a.count ? a.key.localeCompare(b.key) : b.count - a.count));
+
+  return {
+    activities,
+    // 两个数分开报：「业务动作很少」与「这条命令根本不是动作」是两件事。
+    businessSegments: activities.reduce((n, a) => n + a.count, 0),
+    shellNoise,
+    totalSegments
+  };
+}

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 })
+  });
+}