pi-skill-evolve 0.0.0-stage → 0.1.0

package/extensions/skill-evolve/lib/apply-gates.ts

@@ -0,0 +1,204 @@
+/**
+ * 设计稿 13.2 的五道闸：授权核对 → 备份 → 原子写 → 复验 → 生效边界。
+ *
+ * 逐闸失败即回滚（闸0 是例外：它还没写盘，没有可回滚的东西）。
+ * git / md-check / skills diagnostics 全部走注入 —— 单测里绝不起真进程（M4 那 51 个督导进程的教训）。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { PlannedTarget } from "./apply-targets.ts";
+import { renderUnifiedDiff } from "./diff-gen.ts";
+import { captureGate0, gate0Drift, readGate0, type GitRunner } from "./gate0.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+export type GateId = "gate0" | "gate1" | "gate2" | "gate3" | "gate4";
+
+export interface GateResult {
+  gate: GateId;
+  name: string;
+  ok: boolean;
+  ms: number;
+  detail?: string;
+}
+
+export interface GateDeps {
+  evolutionDir: string;
+  cwd: string;
+  runId: string;
+  queue: MutationQueue;
+  now: () => number;
+  log: (msg: string) => void;
+  git: GitRunner;
+  /** 生产：loadSkillsFromDir({ dir: join(cwd,".pi/skills"), source:"project" }).diagnostics */
+  loadDiagnostics: () => { path: string; message: string }[];
+  /** 生产：spawnSync python3 .pi/skills/md-check/scripts/check_md.py <文件> */
+  runMdCheck: (absPath: string) => { code: number; output: string };
+}
+
+export interface GateRun {
+  ok: boolean;
+  /** 闸0 拒采：没写盘，调用方据此标 unauthorized_write 而不是 rolled-back */
+  unauthorized: boolean;
+  gates: GateResult[];
+  wrote: string[];
+  appliedDiff: string;
+  detail?: string;
+}
+
+export const BACKUP_RETENTION_DAYS = 30;
+const DAY_MS = 86_400_000;
+
+export function backupRoot(evolutionDir: string): string {
+  return path.join(evolutionDir, "backups");
+}
+
+export function backupDir(evolutionDir: string, runId: string): string {
+  return path.join(backupRoot(evolutionDir), runId);
+}
+
+/** 备份 30 天清理：只在 session_start 调，删不掉就留到下次（不影响采纳） */
+export function cleanupBackups(evolutionDir: string, now: number, log: (msg: string) => void): number {
+  let names: string[];
+  try {
+    names = fs.readdirSync(backupRoot(evolutionDir));
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const name of names) {
+    const dir = path.join(backupRoot(evolutionDir), name);
+    try {
+      if (now - fs.statSync(dir).mtimeMs <= BACKUP_RETENTION_DAYS * DAY_MS) continue;
+      fs.rmSync(dir, { recursive: true, force: true });
+      removed += 1;
+    } catch {
+      // 单个目录清不掉不影响采纳
+    }
+  }
+  if (removed > 0) log(`[skill-evolve] 清理 ${removed} 个超过 ${BACKUP_RETENTION_DAYS} 天的备份`);
+  return removed;
+}
+
+function readTextOrNull(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function escapeRe(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** 新增技能的引用面（设计稿 10.4 的 ②③）：缺 stub 或缺索引行就说明收口没做完 */
+function missingReferences(cwd: string, skill: string): string[] {
+  const missing: string[] = [];
+  if (!fs.existsSync(path.join(cwd, ".cursor", "skills", skill, "SKILL.md"))) missing.push(`.cursor/skills/${skill}/SKILL.md`);
+  const agents = readTextOrNull(path.join(cwd, "AGENTS.md")) ?? "";
+  if (!new RegExp(`^\\s*[-*]\\s+\`${escapeRe(skill)}\``, "m").test(agents)) missing.push(`AGENTS.md 索引表（- \`${skill}\` …）`);
+  return missing;
+}
+
+export async function restoreTargets(deps: GateDeps, targets: readonly PlannedTarget[], wrote: readonly string[]): Promise<string> {
+  for (const rel of wrote) {
+    const target = targets.find((item) => item.path === rel);
+    if (!target) continue;
+    await deps.queue(target.abs, async () => {
+      if (target.before === null) await fs.promises.rm(target.abs, { force: true });
+      else {
+        await fs.promises.mkdir(path.dirname(target.abs), { recursive: true });
+        await fs.promises.writeFile(target.abs, target.before, "utf8");
+      }
+    });
+  }
+  return `已从备份回滚 ${wrote.length} 个文件`;
+}
+
+export async function runGates(deps: GateDeps, targets: readonly PlannedTarget[]): Promise<GateRun> {
+  const gates: GateResult[] = [];
+  const wrote: string[] = [];
+  const appliedDiff = targets.map((target) => renderUnifiedDiff(target.path, target.before, target.after)).join("");
+  const fail = (detail: string, unauthorized = false): GateRun => ({ ok: false, unauthorized, gates, wrote, appliedDiff, detail });
+
+  // 闸0 · 授权核对：没写盘，所以这一闸失败时什么都没有落地
+  const t0 = deps.now();
+  const snapshot = readGate0(deps.evolutionDir);
+  const drift = gate0Drift(snapshot, captureGate0(deps.git, deps.cwd, deps.now()));
+  gates.push({ gate: "gate0", name: "授权核对", ok: drift.length === 0, ms: deps.now() - t0, ...(drift ? { detail: drift } : {}) });
+  if (drift.length > 0) {
+    deps.log(`[skill-evolve] ${drift}`);
+    return fail(drift, true);
+  }
+
+  // 闸1 · 备份：回滚的唯一依据，备份写不进去就不许写盘
+  const t1 = deps.now();
+  try {
+    for (const target of targets) {
+      if (target.before === null) continue;
+      const dest = path.join(backupDir(deps.evolutionDir, deps.runId), target.path);
+      await deps.queue(dest, async () => {
+        await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+        await fs.promises.writeFile(dest, target.before as string, "utf8");
+      });
+    }
+    for (const target of targets) {
+      if (target.before !== null && !fs.existsSync(path.join(backupDir(deps.evolutionDir, deps.runId), target.path))) {
+        throw new Error(`备份缺失：${target.path}`);
+      }
+    }
+    gates.push({ gate: "gate1", name: "备份", ok: true, ms: deps.now() - t1 });
+  } catch (error) {
+    gates.push({ gate: "gate1", name: "备份", ok: false, ms: deps.now() - t1, detail: String(error) });
+    return fail(`闸1 备份失败：${String(error)}`);
+  }
+
+  // 闸2 · 原子写：整个「重读 → 比对 → 写」窗口都在 withFileMutationQueue 里
+  const t2 = deps.now();
+  for (const target of targets) {
+    try {
+      await deps.queue(target.abs, async () => {
+        const current = readTextOrNull(target.abs);
+        if (current !== target.before) throw new Error(`磁盘内容与计划不一致：${target.path}`);
+        await fs.promises.mkdir(path.dirname(target.abs), { recursive: true });
+        await fs.promises.writeFile(target.abs, target.after, "utf8");
+      });
+      wrote.push(target.path);
+    } catch (error) {
+      gates.push({ gate: "gate2", name: "原子写", ok: false, ms: deps.now() - t2, detail: String(error) });
+      const detail = `${String(error)}；${await restoreTargets(deps, targets, wrote)}`;
+      return fail(`闸2 写入失败：${detail}`);
+    }
+  }
+  gates.push({ gate: "gate2", name: "原子写", ok: true, ms: deps.now() - t2 });
+
+  // 闸3 · 复验：diagnostics + md-check + 引用面
+  const t3 = deps.now();
+  const problems: string[] = [];
+  const diagnostics = deps.loadDiagnostics();
+  if (diagnostics.length > 0) problems.push(`skills diagnostics 非空：${diagnostics[0].message}`);
+  for (const target of targets.filter((item) => item.path.startsWith(".pi/skills/"))) {
+    const check = deps.runMdCheck(target.abs);
+    if (check.code !== 0) problems.push(`md-check 失败（${target.path}）：${check.output.trim().split("\n").slice(-2).join(" / ")}`);
+  }
+  for (const target of targets.filter((item) => item.before === null && /^\.pi\/skills\/[^/]+\/SKILL\.md$/.test(item.path))) {
+    const skill = target.path.split("/")[2];
+    const missing = missingReferences(deps.cwd, skill);
+    if (missing.length > 0) problems.push(`新增技能引用面缺：${missing.join("、")}`);
+  }
+  gates.push({
+    gate: "gate3",
+    name: "复验",
+    ok: problems.length === 0,
+    ms: deps.now() - t3,
+    ...(problems.length > 0 ? { detail: problems.join("；") } : {}),
+  });
+  if (problems.length > 0) {
+    const detail = `${problems.join("；")}；${await restoreTargets(deps, targets, wrote)}`;
+    return fail(`闸3 复验失败：${detail}`);
+  }
+
+  // 闸4 · 生效边界：不做 /reload，只提示新会话生效（技能在 session_start 重新发现）
+  gates.push({ gate: "gate4", name: "生效边界", ok: true, ms: 0, detail: "未 /reload：新会话生效" });
+  return { ok: true, unauthorized: false, gates, wrote, appliedDiff };
+}

package/extensions/skill-evolve/lib/apply-targets.ts

@@ -0,0 +1,90 @@
+/**
+ * 从 run 目录推出「这次采纳要写哪些文件、写成什么」。
+ *
+ * 为什么单独一层：apply 的五道闸只关心 (path, before, after)，把「提案 → 目标」的解析
+ * 与闸门执行分开，边界用例（多文件 diff、新建技能、diff 应用失败）才能单独测。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { applyUnifiedDiff } from "./diff-apply.ts";
+import { splitDiffByFile } from "./diff-gen.ts";
+
+export interface PlannedTarget {
+  /** 相对仓库根，统一用 `/` 分隔 */
+  path: string;
+  abs: string;
+  /** null = 新建文件 */
+  before: string | null;
+  after: string;
+}
+
+export interface PlanResult {
+  ok: boolean;
+  reason?: string;
+  skill: string;
+  type: string;
+  targets: PlannedTarget[];
+}
+
+export interface ProposalMeta {
+  type: string;
+  skill: string;
+  diffFile: string;
+  candidateFile?: string;
+}
+
+function readText(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function readProposalMeta(runDir: string): ProposalMeta | null {
+  const raw = readText(path.join(runDir, "02-proposal.json"));
+  if (raw === null) return null;
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (typeof parsed.skill !== "string" || parsed.skill.trim().length === 0) return null;
+    return {
+      type: typeof parsed.type === "string" ? parsed.type : "improve",
+      skill: parsed.skill.trim(),
+      diffFile: typeof parsed.diffFile === "string" ? parsed.diffFile : "02-proposal.diff",
+      ...(typeof parsed.candidateFile === "string" ? { candidateFile: parsed.candidateFile } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function planTargets(runDir: string, cwd: string): PlanResult {
+  const meta = readProposalMeta(runDir);
+  if (!meta) return { ok: false, reason: "02-proposal.json 缺失或不可读", skill: "", type: "", targets: [] };
+  const base = { skill: meta.skill, type: meta.type };
+  const targets: PlannedTarget[] = [];
+  const diffText = readText(path.join(runDir, meta.diffFile)) ?? "";
+
+  if (meta.type === "create") {
+    const candidateFile = meta.candidateFile ?? path.posix.join("candidate", meta.skill, "SKILL.md");
+    const after = readText(path.join(runDir, candidateFile));
+    if (after === null) return { ok: false, reason: `候选文件缺失：${candidateFile}`, ...base, targets: [] };
+    const rel = `.pi/skills/${meta.skill}/SKILL.md`;
+    targets.push({ path: rel, abs: path.join(cwd, rel), before: readText(path.join(cwd, rel)), after });
+  }
+
+  for (const { path: rel, chunk } of splitDiffByFile(diffText)) {
+    if (rel === null) return { ok: false, reason: "提案里含删除文件（+++ /dev/null），删除必须走 --prune 人批", ...base, targets: [] };
+    if (targets.some((target) => target.path === rel)) continue; // 新建技能的主文件已由 candidate 生成
+    const abs = path.join(cwd, rel);
+    const before = readText(abs);
+    const applied = applyUnifiedDiff(before ?? "", chunk);
+    if (!applied.ok) {
+      return { ok: false, reason: `diff 无法应用（${rel}）：${applied.reason ?? "未知原因"}`, ...base, targets: [] };
+    }
+    targets.push({ path: rel, abs, before, after: applied.text });
+  }
+
+  if (targets.length === 0) return { ok: false, reason: "提案没有任何可写目标", ...base, targets: [] };
+  return { ok: true, ...base, targets };
+}

package/extensions/skill-evolve/lib/apply.ts

@@ -0,0 +1,141 @@
+/**
+ * 采纳一条队列条目：解析目标 → 过五道闸 → 写 05/06 留证 → auto 级单独一条 commit。
+ *
+ * 只在扩展进程里跑（`withFileMutationQueue` 只有 pi 运行时能提供）。督导进程只写 03-review.json，
+ * 所以主会话退出也不会丢：队列在 `.pi/evolution/queue.json`，下次 session_start 接着采纳。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { planTargets } from "./apply-targets.ts";
+import { restoreTargets, runGates, type GateDeps, type GateResult } from "./apply-gates.ts";
+import { markDone, type QueueItem } from "./queue.ts";
+import { updateRunStatus } from "./runs.ts";
+
+export type ApplyStatus = "applied" | "rolled-back" | "failed" | "unauthorized_write";
+
+export interface ApplyOutcome {
+  runId: string;
+  status: ApplyStatus;
+  gates: GateResult[];
+  wrote: string[];
+  detail?: string;
+  /** auto 级成功后的 commit 短 hash（approval 级不自动提交，留给人手动提交） */
+  commit?: string | null;
+}
+
+export interface ApplyDeps extends GateDeps {
+  /** auto 级成功后单独一条 `docs(skill): ...`；返回 ok=false 即回滚该条 */
+  commit?: (item: QueueItem, runDir: string) => { ok: boolean; hash?: string; detail?: string };
+}
+
+export interface VerifyRecord {
+  runId: string;
+  status: ApplyStatus;
+  at: number;
+  atIso: string;
+  ms: number;
+  gates: GateResult[];
+  wrote: string[];
+  detail?: string;
+  commit?: string | null;
+}
+
+export const APPLIED_DIFF_FILE = "05-applied.diff";
+export const VERIFY_FILE = "06-verify.json";
+
+export function appliedDiffFile(runDir: string): string {
+  return path.join(runDir, APPLIED_DIFF_FILE);
+}
+
+export function verifyFile(runDir: string): string {
+  return path.join(runDir, VERIFY_FILE);
+}
+
+export function readVerify(runDir: string): VerifyRecord | null {
+  try {
+    return JSON.parse(fs.readFileSync(verifyFile(runDir), "utf8")) as VerifyRecord;
+  } catch {
+    return null;
+  }
+}
+
+async function writeText(deps: ApplyDeps, file: string, text: string): Promise<void> {
+  await deps.queue(file, async () => {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, text, "utf8");
+  });
+}
+
+export async function applyRun(item: QueueItem, deps: ApplyDeps): Promise<ApplyOutcome> {
+  const runDir = path.join(deps.evolutionDir, "runs", item.runId);
+  const started = deps.now();
+  const plan = planTargets(runDir, deps.cwd);
+  let outcome: ApplyOutcome;
+
+  if (!plan.ok) {
+    outcome = { runId: item.runId, status: "failed", gates: [], wrote: [], detail: plan.reason ?? "提案不可用" };
+  } else {
+    const run = await runGates({ ...deps, runId: item.runId }, plan.targets);
+    const status: ApplyStatus = run.ok
+      ? "applied"
+      : run.unauthorized
+        ? "unauthorized_write"
+        : run.wrote.length > 0
+          ? "rolled-back"
+          : "failed";
+    outcome = { runId: item.runId, status, gates: run.gates, wrote: run.wrote, ...(run.detail ? { detail: run.detail } : {}) };
+
+    if (run.ok) {
+      // 05 只记真实落盘的 diff：被闸拦下的提案不该留下「已应用」的证据
+      await writeText(deps, appliedDiffFile(runDir), run.appliedDiff);
+      if (item.level === "auto" && deps.commit) {
+        const committed = deps.commit(item, runDir);
+        if (committed.ok) outcome = { ...outcome, commit: committed.hash ?? null };
+        else {
+          const reverted = await restoreTargets(deps, plan.targets, run.wrote);
+          outcome = { ...outcome, status: "rolled-back", detail: `commit 失败：${committed.detail ?? "未知原因"}；${reverted}` };
+        }
+      }
+    }
+  }
+
+  const record: VerifyRecord = {
+    runId: item.runId,
+    status: outcome.status,
+    at: started,
+    atIso: new Date(started).toISOString(),
+    ms: deps.now() - started,
+    gates: outcome.gates,
+    wrote: outcome.wrote,
+    ...(outcome.detail ? { detail: outcome.detail } : {}),
+    ...(outcome.commit !== undefined ? { commit: outcome.commit } : {}),
+  };
+  await writeText(deps, verifyFile(runDir), `${JSON.stringify(record, null, 2)}\n`);
+  return outcome;
+}
+
+/** 拒绝只改状态：队列条目 + run.json，绝不碰任何技能文件（和采纳走的是两条路） */
+export interface RejectDeps {
+  evolutionDir: string;
+  queue: MutationQueue;
+}
+
+export interface RejectOutcome {
+  ok: boolean;
+  detail: string;
+}
+
+/**
+ * 否掉一条待批提案：队列 pending → rejected，run.json → rejected。
+ *
+ * 为什么不做更多：拒绝的语义是「这条提案不要了」，不是「撤销一次已发生的写入」——
+ * 回滚已经应用过的改动是另一条路径（05-applied.diff + restoreTargets）。这里写盘只写状态文件。
+ */
+export async function rejectRun(item: QueueItem, deps: RejectDeps): Promise<RejectOutcome> {
+  if (item.status !== "pending") return { ok: false, detail: `当前状态是 ${item.status}，只有 pending 能拒绝` };
+  // 顺序与 apply 相反：队列是外部可见的终态标志，run.json 缺了也不能让条目永远 pending
+  const marked = await markDone(deps, item.runId, "rejected", "人主动拒绝（未改任何技能文件）");
+  if (!marked) return { ok: false, detail: `队列里没有 ${item.runId}` };
+  const patched = await updateRunStatus(deps.evolutionDir, item.runId, "rejected", deps.queue);
+  return { ok: true, detail: patched ? "" : "run.json 不存在，只改了队列状态" };
+}

package/extensions/skill-evolve/lib/attribution.ts

@@ -0,0 +1,138 @@
+/**
+ * G2 机械归因：把「曝光了但没加载」的技能判定成 A~E 中的一类，判不动的留给复盘 agent 做 F/G。
+ *
+ * 判定顺序是硬的（设计稿第八章）：A → B → C → D → E → semantic，命中即停。
+ * 顺序颠倒的后果不是「少一条建议」，而是得到一堆「建议重写 description」的错误建议——
+ * 一个 frontmatter 坏掉、或者本轮根本没有 read 工具的会话，文案改成天花乱坠也加载不了。
+ *
+ * 本模块是纯函数：不读盘、不调 pi，输入全部由调用方（mechanical.ts）备好。
+ */
+
+export type AttributionCategory = "A" | "B" | "C" | "D" | "E" | "semantic";
+
+/** 报告与 prompt 都按这个顺序展示，别处不要再自己排序 */
+export const CATEGORY_ORDER: readonly AttributionCategory[] = ["A", "B", "C", "D", "E", "semantic"];
+
+export interface ExposedSkill {
+  name: string;
+  filePath: string;
+  /** 对应 Skill.disableModelInvocation */
+  disabled?: boolean;
+}
+
+export interface DiagnosticEntry {
+  file: string;
+  message: string;
+  /** pi 的 ResourceDiagnostic.type：warning / error / collision */
+  type?: string;
+}
+
+export interface LoadedSkill {
+  name: string;
+  filePath: string;
+}
+
+export interface AttributionInput {
+  /** 本轮曝光但没加载的技能名 */
+  missed: string[];
+  /** 本轮 prompt 里的技能（含被禁用的） */
+  exposed: ExposedSkill[];
+  /** loadSkillsFromDir 的发现结果（同名多次 = 发现顺序冲突） */
+  loadedFromPi: LoadedSkill[];
+  diagnostics: DiagnosticEntry[];
+  /** 本轮会话声明的工具名（pi.getActiveTools()） */
+  activeTools: string[];
+  /** 磁盘上 .pi/skills/* 的目录名 */
+  diskSkillNames: string[];
+}
+
+export interface Attribution {
+  skill: string;
+  category: AttributionCategory;
+  reason: string;
+}
+
+/** 每个类别的处置建议（设计稿第八章表格）：报告里照抄，不自动执行 */
+export const DISPOSITIONS: Record<AttributionCategory, { label: string; action: string; auto: string }> = {
+  A: { label: "设计如此", action: "提示「仅支持 /skill:名字 显式调用」，不视为缺陷", auto: "-" },
+  B: { label: "frontmatter 坏", action: "修 frontmatter（缺 description 或名字不合规）", auto: "auto" },
+  C: { label: "同名冲突", action: "改名或调整发现顺序（高风险，必须人批）", auto: "forbidden" },
+  D: { label: "不在发现范围", action: "只记「不在 .pi/skills 观测范围」，不清理", auto: "-" },
+  E: { label: "缺读工具", action: "提示会话配置缺 read/bash 工具，与技能内容无关", auto: "-" },
+  semantic: { label: "待语义判定", action: "由复盘 agent 判 F（兄弟竞争）/ G（文案路由词）", auto: "approval" },
+};
+
+const TOOL_NAMES_FOR_READING = ["read", "bash"];
+
+/** 路径比较：pi 的诊断里 file 可能是绝对路径也可能是相对的，末端一致就算同一个文件 */
+function samePath(a: string, b: string): boolean {
+  const norm = (value: string): string => value.replace(/\\/g, "/").replace(/\/+$/, "");
+  const left = norm(a);
+  const right = norm(b);
+  if (left.length === 0 || right.length === 0) return false;
+  return left === right || left.endsWith(right) || right.endsWith(left);
+}
+
+function namesSkill(message: string, name: string): boolean {
+  // 描述里出现 `name` 这个词才算，避免 "a" 命中 "schema"
+  return new RegExp(`(^|[^\\w-])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^\\w-]|$)`).test(message);
+}
+
+/** 归类一个未命中技能。顺序即设计稿的决策树，改动前先读第八章 */
+export function classifyOne(name: string, input: AttributionInput): Attribution {
+  const exposed = input.exposed.find((skill) => skill.name === name);
+  const found = input.loadedFromPi.filter((skill) => skill.name === name);
+
+  // A：disableModelInvocation —— 它本来就不进 prompt，不是缺陷
+  if (exposed?.disabled === true) {
+    return { skill: name, category: "A", reason: "disableModelInvocation=true，只能 /skill:<名> 显式调用" };
+  }
+
+  // B：frontmatter 坏（pi 只 warning 不报错，所以它「看起来存在」但没被正常加载）
+  const diagnostics = input.diagnostics.filter((entry) => samePath(entry.file, exposed?.filePath ?? ""));
+  if (diagnostics.length > 0) {
+    return { skill: name, category: "B", reason: `frontmatter/diagnostics：${diagnostics[0].message}` };
+  }
+
+  // C：同名被抢先（发现顺序问题）
+  if (found.length >= 2) {
+    return { skill: name, category: "C", reason: `同名在 ${found.length} 处被定义：${found.map((item) => item.filePath).join("、")}` };
+  }
+  const collision = input.diagnostics.find((entry) => entry.type === "collision" && namesSkill(entry.message, name));
+  if (collision) return { skill: name, category: "C", reason: `发现冲突：${collision.message}` };
+
+  // D：磁盘上有这个技能，但不在发现结果里 —— 不在观测范围
+  if (input.diskSkillNames.includes(name) && found.length === 0) {
+    return { skill: name, category: "D", reason: `磁盘上有 .pi/skills/${name}/，但 loadSkillsFromDir 没有返回它` };
+  }
+
+  // E：本轮根本没有读工具 —— 必须排在文案类之前，否则会得出「改 description」的错误建议
+  // 注意：activeTools 为空表示「没采到」，不是「工具全关了」；采集缺口不能拿来当结论
+  const hasReader = TOOL_NAMES_FOR_READING.some((tool) => input.activeTools.includes(tool));
+  if (input.activeTools.length > 0 && !hasReader) {
+    return {
+      skill: name,
+      category: "E",
+      reason: `本轮 activeTools 里既没有 read 也没有 bash（当前：${input.activeTools.join("、")}），模型读不到技能文件`,
+    };
+  }
+
+  return { skill: name, category: "semantic", reason: "机械层判不了，交给复盘 agent 判 F（兄弟竞争）/ G（文案路由词）" };
+}
+
+/** 对一批未命中技能逐个归类，保持传入顺序 */
+export function classifyMechanical(input: AttributionInput): Attribution[] {
+  return input.missed.map((name) => classifyOne(name, input));
+}
+
+/** 多轮合并时的归因去重：同一技能只留第一次的分类，避免一句话里出现两种结论 */
+export function mergeAttributions(
+  a: readonly Attribution[] | undefined,
+  b: readonly Attribution[] | undefined,
+): Attribution[] {
+  const merged: Attribution[] = [];
+  for (const item of [...(a ?? []), ...(b ?? [])]) {
+    if (!merged.some((existing) => existing.skill === item.skill)) merged.push(item);
+  }
+  return merged;
+}