@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/src/inject.js

@@ -38,7 +38,12 @@ function visibleSeqsOf(session) {
 // session event log (same event shape summarize.js consumes) and returns the
 // most recent human message. Any failure degrades to "" — the injector then
 // falls back to the legacy rule-based pick, never breaking the render.
-function lastUserQuery(ctx) {
+//
+// v0.9.0：导出给 tools.js 的 memory_update 用。失败记录表的 query 与注入
+// 候选问的是同一件事——「当时到底想干什么」；这条取原话的路只该有一份实现。
+// 复制一份的代价本仓库付过几次（src/lib 平价、snapshotEvents 兼容层），所以
+// 这里只加 export，不改行为。
+export function lastUserQuery(ctx) {
   try {
     const session = ctx?.agent?.session;
     // DSH ≥0.1.2-rc only exposes events via snapshotEvents(); older builds
@@ -301,13 +306,44 @@ export function createInjector(ctx, service, settings, config, gate = null) {
     }).catch(() => { /* prefetch is best-effort */ });
   }
 
+  // 会话身份解析（v1.2 人格寻址用）：读 session.header.agentPreset——冻结的
+  // SessionHeader（issue #17 身份契约）。⚠️ 不能先读 requestHeader()：那返回
+  // EpochHeader（请求级头，首请求后为真），会把 session.header 遮蔽掉，身份取空
+  // （scope.js 同坑，本地实测踩过）。任何失败静默 → null（落 default 卡）。
+  function sessionAgentId(ctx) {
+    try {
+      const session = ctx?.agent?.session;
+      const header = session?.header ?? null;
+      const preset = header?.agentPreset;
+      return typeof preset === "string" && preset.trim() ? preset.trim() : null;
+    } catch {
+      return null;
+    }
+  }
+
   // User profile + rules: injected ahead of the memory block because they are
   // always-relevant instructions the agent should follow every turn.
-  function renderUserSettings() {
+  // 人格段（beta）：双闸门（config.personaEnabled && 卡.enabled）开时渲染在最前
+  // ——设计稿⑥：特化指令（人格）先出，画像与规则后出、后写覆盖占上风，rules 恒
+  // 最硬。v1.2 多卡：按会话身份取 byAgent 卡，身份缺失/无卡/卡关落 default。
+  // 任一闸关着时本函数输出与历史版本逐字节一致（老用户零变化）。人格段非空即
+  // 触发整块渲染（与 profile 同权）。
+  function renderUserSettings(ctx) {
     const profile = settings.getProfile().trim();
     const rules = settings.getRules();
-    if (!profile && !rules.length) return "";
+    const persona = config?.personaEnabled === true
+      ? settings.getPersonaFor(sessionAgentId(ctx))
+      : {};
+    const personaLines = persona?.enabled === true
+      ? [
+          ...(typeof persona.name === "string" && persona.name.trim() ? [STR.personaNameLine[language](persona.name.trim())] : []),
+          ...(typeof persona.personality === "string" && persona.personality.trim() ? [STR.personaPersonalityLine[language](persona.personality.trim())] : []),
+          ...(typeof persona.replyStyle === "string" && persona.replyStyle.trim() ? [STR.personaReplyStyleLine[language](persona.replyStyle.trim())] : [])
+        ]
+      : [];
+    if (!profile && !rules.length && !personaLines.length) return "";
     const lines = [STR.userSettingsHeader[language]];
+    lines.push(...personaLines);
     if (profile) lines.push(STR.profileLine[language](profile));
     for (const rule of rules) lines.push(STR.ruleLine[language](rule));
     return escapePromptVars(lines.join("\n"));
@@ -413,7 +449,7 @@ export function createInjector(ctx, service, settings, config, gate = null) {
     ctx.systemPrompt.context({
       name: "user-settings",
       order: 85,
-      text: renderUserSettings
+      text: (ctx) => renderUserSettings(ctx)
     })
   ];
 

package/src/lang.js

@@ -122,6 +122,20 @@ export const STR = {
     zh: (rule) => `- 规则：${rule}`,
     en: (rule) => `- Rule: ${rule}`
   },
+  // 人格定义页（beta）：人格段行（renderUserSettings 拼装，双闸门开时渲染）。
+  // 设计稿⑥：人格段在 profile/rules 之前——特化指令后出、通用底座压轴，rules 恒最硬。
+  personaNameLine: {
+    zh: (name) => `- 你的人格名字：${name}`,
+    en: (name) => `- Your persona name: ${name}`
+  },
+  personaPersonalityLine: {
+    zh: (text) => `- 人格性格设定：${text}`,
+    en: (text) => `- Persona personality: ${text}`
+  },
+  personaReplyStyleLine: {
+    zh: (text) => `- 回复要求：${text}`,
+    en: (text) => `- Reply style: ${text}`
+  },
 
   // --- summarize.js：蒸馏转录标签（进入 LLM 上下文） --------------------------
   transcriptUser: { zh: (t) => `用户：${t}`, en: (t) => `User: ${t}` },
@@ -223,6 +237,116 @@ export const STR = {
     en: (name) => `Failed to submit command ${name}; see logs`
   },
 
+  // --- pipeline-command.js：/mo-run 的开窗命令 -----------------------------------
+  // 回执是这个功能唯一的对外窗口（面板侧还没做），所以每一条都要说清「发生了什么、
+  // 为什么」——尤其失败时不许含糊成「完成」。
+  moRunDescription: {
+    zh: "M.O. 记账：显式开一次执行窗口，之后跑过的命令才可能被记下来",
+    en: "M.O. ledger: explicitly open an execution window; only commands run inside it can be recorded"
+  },
+  moRunInputHint: {
+    zh: "start <工作流 id> | stop | confirm <做了的步骤> | status",
+    en: "start <pipeline id> | stop | confirm <steps that ran> | status"
+  },
+  moRunUsage: {
+    zh: "用法：/mo-run start <工作流 id> → 走一遍 → /mo-run stop → /mo-run confirm <做了的步骤 id>\n\n停止时会给出一份待确认清单（含本次观察到的业务动作）；**确认之后才写账**。\n确认写法：`/mo-run confirm P6 V2` 表示这两步做了；`V2:-` 表示没做（记 skipped），`V2:?` 表示不确定（不写）。\n未提到的步骤什么都不写——「没确认」不等于「没发生」。\n\n它不会自己判断「你是不是在走某条流程」，也不会自己判断「哪几步走了」：这两件事都会猜错。",
+    en: "Usage: /mo-run start <pipeline id> → walk through it → /mo-run stop → /mo-run confirm <step ids that ran>\n\nStop gives you a checklist (with the business actions observed); **the ledger is only written after you confirm**.\nConfirm syntax: `/mo-run confirm P6 V2` means both ran; `V2:-` means not done (recorded as skipped), `V2:?` means unsure (not written).\nSteps you do not mention are written as nothing — unconfirmed is not the same as not-happened.\n\nIt never guesses whether you are walking a workflow, nor which steps ran: both guesses would be wrong."
+  },
+  moRunStart: {
+    zh: {
+      ok: (id, steps) => `已开窗：${id}（${steps} 步）。走完用 /mo-run stop 结账——它会给你一份待确认清单，**确认之后才写账**。`,
+      alreadyOpen: (id) => `这个会话已经开着窗口了：${id}。先用 /mo-run stop 结账，再开新的。`,
+      notFound: (ids) => `找不到这条工作流。可用：${ids}`,
+      noneAvailable: "（当前项目里没有读到任何工作流）",
+      unreadable: (detail) => `工作流读不出来：${detail}`,
+      noProject: "拿不到这个会话的工作目录，无法定位工作流。",
+      noSession: "拿不到会话身份，无法记账。",
+      failed: (reason) => `开窗失败：${reason}`
+    },
+    en: {
+      ok: (id, steps) => `Window opened: ${id} (${steps} steps). When done, run /mo-run stop — it gives you a checklist, and **the ledger is only written after you confirm**.`,
+      alreadyOpen: (id) => `This session already has an open window: ${id}. Run /mo-run stop first.`,
+      notFound: (ids) => `No such workflow. Available: ${ids}`,
+      noneAvailable: "(no workflow found in this project)",
+      unreadable: (detail) => `Workflow unreadable: ${detail}`,
+      noProject: "Cannot determine this session's working directory, so the workflow cannot be located.",
+      noSession: "No session identity available; nothing can be recorded.",
+      failed: (reason) => `Failed to open window: ${reason}`
+    }
+  },
+  moRunStop: {
+    zh: {
+      ok: (id, steps) => `已结账并落盘：${id}，记下 ${steps} 步。`,
+      awaiting: (id, steps) => `已结账：${id}（${steps} 步）。**还没有写账**——请确认哪几步真的走了：`,
+      confirmHow: (sample) =>
+        `\n用 /mo-run confirm ${sample} 列出「做了」的步骤；要标「没做」就写 ${String(sample).split(" ")[0]}:-\n未提到的步骤什么都不写（「没确认」不等于「没发生」）。`,
+      notCommands: (n) => `${n} 次调用不是命令执行器（读文件、检索这类），与工作流步骤无关。`,
+      truncated: "⚠️ 事件缓冲到上限被截断，这次记账可能不完整。",
+      noWindow: "这个会话没有开着窗口，没什么可结账的。",
+      activities: (n) => `本次观察到 ${n} 种业务动作（只留动作与旗标，位置参数略去）：`,
+      shellNoise: (n) => `另有 ${n} 段是 shell 语法（赋值、管道、输出），不是工作流的一步。`,
+      writeFailed: (detail) => `写盘失败：${detail}`,
+      failed: (reason) => `结账失败：${reason}`
+    },
+    en: {
+      ok: (id, steps) => `Closed and persisted: ${id}, ${steps} step(s) recorded.`,
+      awaiting: (id, steps) => `Closed: ${id} (${steps} steps). **Nothing persisted yet** — confirm which steps really ran:`,
+      confirmHow: (sample) =>
+        `\nUse /mo-run confirm ${sample} to list the steps that ran; mark one as not-done with ${String(sample).split(" ")[0]}:-\nSteps you do not mention are written as nothing (unconfirmed is not the same as not-happened).`,
+      notCommands: (n) => `${n} call(s) were not command executors (file reads, searches) and are irrelevant to workflow steps.`,
+      truncated: "⚠️ Event buffer hit its cap and was truncated; this record may be incomplete.",
+      noWindow: "No window is open for this session, so there is nothing to close.",
+      activities: (n) => `${n} kind(s) of business action observed this pass (actions and flags only; positional arguments omitted):`,
+      shellNoise: (n) => `Another ${n} segment(s) were shell syntax (assignments, pipes, output), not steps of a workflow.`,
+      writeFailed: (detail) => `Failed to write: ${detail}`,
+      failed: (reason) => `Failed to close: ${reason}`
+    }
+  },
+  moRunConfirm: {
+    zh: {
+      ok: (id, steps) => `已记入账本：${id}，${steps} 步。`,
+      notDone: (list) => `记为「这次没做」（skipped）：${list}`,
+      unsure: (list) => `你说不确定，没有写进账：${list}`,
+      unanswered: (list) => `没提到的步骤没有写进账：${list}`,
+      nothingToConfirm: "没有待确认的清单。先 /mo-run start <工作流 id>，走一遍，再 /mo-run stop。",
+      mismatch: (n, rows) => `⚠️ 有 ${n} 步你说做了、但声明的命令这次一次都没出现（是声明该改、还是本来不必敲？由你判）：\n${rows}`,
+      obsSaved: (file) => `本次观察已旁挂：${file}`,      noAnswers: (notDone, unsure, unanswered) =>
+        `一条都没确认，**没有落盘**。你说「没做」的 ${notDone} 步、不确定的 ${unsure} 步、没提到的 ${unanswered} 步。\n确认「做了」的步骤才会写账：/mo-run confirm <步骤 id>`,
+      badValue: (stepId, value) => `${stepId} 的回答「${value}」不合法。只认「做了」（或不写标记）/「没做」写作 -/「不确定」写作 ?`,
+      unknownStep: (stepId) => `没有这一步：${stepId}`,
+      writeFailed: (detail) => `写盘失败：${detail}`,
+      failed: (reason) => `确认失败：${reason}`
+    },
+    en: {
+      ok: (id, steps) => `Recorded: ${id}, ${steps} step(s).`,
+      notDone: (list) => `Marked as not done this pass (skipped): ${list}`,
+      unsure: (list) => `You were unsure; not written to the ledger: ${list}`,
+      unanswered: (list) => `Steps you did not mention were not written to the ledger: ${list}`,
+      nothingToConfirm: "Nothing to confirm. Run /mo-run start <pipeline id>, walk through it, then /mo-run stop.",
+      mismatch: (n, rows) => `⚠️ ${n} step(s) you marked done never showed their declared command this pass (stale declaration, or simply not needed? your call):\n${rows}`,
+      obsSaved: (file) => `Observations side-written to: ${file}`,      noAnswers: (notDone, unsure, unanswered) =>
+        `Nothing was confirmed; **nothing was persisted**. Not-done: ${notDone}, unsure: ${unsure}, unmentioned: ${unanswered}.\nOnly steps confirmed as done are recorded: /mo-run confirm <step id>`,
+      badValue: (stepId, value) => `Answer "${value}" for ${stepId} is invalid. Use done (no marker) / - for not-done / ? for unsure.`,
+      unknownStep: (stepId) => `No such step: ${stepId}`,
+      writeFailed: (detail) => `Failed to write: ${detail}`,
+      failed: (reason) => `Failed to confirm: ${reason}`
+    }
+  },
+  moRunStatus: {
+    zh: {
+      closed: "当前没有开着的执行窗口。用 /mo-run start <工作流 id> 开一个。",
+      awaiting: (id, steps) => `等你在确认：${id}（${steps} 步）。用 /mo-run confirm <做了的步骤 id> 写账。`,
+      open: (s, recorded) => `窗口开着：${s.pipelineId}\n开始于 ${s.startedAt}\n已缓冲 ${s.bufferedEvents} 条事件，识别出 ${recorded} 步${s.truncated ? "（缓冲已截断）" : ""}\n认不出 ${s.unattributed}，待确认 ${s.ambiguous}`,
+      none: "（还没有）"
+    },
+    en: {
+      closed: "No execution window is open. Open one with /mo-run start <pipeline id>.",
+      awaiting: (id, steps) => `Waiting for your confirmation: ${id} (${steps} steps). Write the ledger with /mo-run confirm <step ids that ran>.`,
+      open: (s, recorded) => `Window open: ${s.pipelineId}\nStarted ${s.startedAt}\n${s.bufferedEvents} event(s) buffered, ${recorded} step(s) recognized${s.truncated ? " (buffer truncated)" : ""}\nUnattributed ${s.unattributed}, ambiguous ${s.ambiguous}`,
+      none: "(none yet)"
+    }
+  },
+
   // --- mirror.js：镜像文件标签（渲染随实例语言；解析两种语言都认） ----------------
   mirrorLabel: {
     zh: { type: "类型", importance: "重要性", tags: "标签", updated: "更新时间", source: "来源", scope: "作用域", sensitivity: "敏感度" },

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