pi-skill-evolve 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,285 @@
+/**
+ * `/skill-evolve report --week`：一周一句结论的周报（设计稿 14.2 + 10.4）。
+ *
+ * 术语纪律：能观测的只有「技能文件是否被读取」，所以这份报告里只有**加载率**，
+ * 任何地方都不许写成「使用率」（读 ≠ 用，读了没照做也测不到）。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { listSkillDirs } from "./hard-rules.ts";
+import { createReferenceScan } from "./proc.ts";
+import { readFrontmatter } from "./proposal.ts";
+import { readQueue, type QueueItem } from "./queue.ts";
+import { listRuns } from "./runs.ts";
+import { ratio, readEvents, type TelemetryEvent, type TelemetrySkill } from "./telemetry.ts";
+import { isoWeek } from "./metrics.ts";
+
+/** 零加载候选的判据：近 4 周每周都有曝光、且一次都没被读过 */
+export const CANDIDATE_WEEKS = 4;
+
+export interface SkillRef {
+  name: string;
+  description: string;
+}
+
+/** 引用面清单：由 proc.ts 的 rg / 文件探测提供，单测注入假实现 */
+export interface ReferenceScan {
+  cursorStub: boolean;
+  agentsIndex: boolean;
+  /** 其它技能 / 文档里提到该技能名的处数 */
+  mentions: number;
+}
+
+export interface AppliedRun {
+  skill: string;
+  /** 采纳（或入队）时刻：进化收益的前后 7 天窗口以它为界 */
+  at: number;
+}
+
+export interface WeeklyInput {
+  cwd: string;
+  now: number;
+  events: readonly TelemetryEvent[];
+  runs: readonly { runId: string; status: string; dispatchedAt: number | null }[];
+  queue: readonly QueueItem[];
+  skills: readonly SkillRef[];
+  applied: readonly AppliedRun[];
+  referenceScan?: (skill: string) => ReferenceScan;
+}
+
+interface SkillWeek {
+  advertised: number;
+  loaded: number;
+}
+
+function weekOf(ts: number): string {
+  return isoWeek(ts);
+}
+
+function emptyStat(): SkillWeek {
+  return { advertised: 0, loaded: 0 };
+}
+
+/** 周 → 技能 → 曝光/加载：零加载候选与趋势表都从这张表出 */
+function perSkillWeeks(events: readonly TelemetryEvent[]): Map<string, Map<string, SkillWeek>> {
+  const table = new Map<string, Map<string, SkillWeek>>();
+  const bucket = (week: string, skill: string): SkillWeek => {
+    let inner = table.get(week);
+    if (!inner) {
+      inner = new Map<string, SkillWeek>();
+      table.set(week, inner);
+    }
+    let stat = inner.get(skill);
+    if (!stat) {
+      stat = emptyStat();
+      inner.set(skill, stat);
+    }
+    return stat;
+  };
+  for (const event of events) {
+    if (typeof event.ts !== "number") continue;
+    const week = weekOf(event.ts);
+    if (event.kind === "advertised") {
+      const skills = Array.isArray(event.skills) ? (event.skills as TelemetrySkill[]) : [];
+      for (const skill of skills) {
+        if (!skill || typeof skill.name !== "string" || skill.disabled === true) continue;
+        bucket(week, skill.name).advertised += 1;
+      }
+    } else if (event.kind === "loaded" && typeof event.skill === "string") {
+      bucket(week, event.skill).loaded += 1;
+    }
+  }
+  return table;
+}
+
+function percent(part: number, total: number): string {
+  return `${(ratio(part, total) * 100).toFixed(1)}%`;
+}
+
+/** 描述重叠度：中文按二元组、英文按词，取 Jaccard；用来区分「真没人用」和「两个技能抢同一件事」 */
+export function descriptionOverlap(left: string, right: string): number {
+  const tokens = (text: string): Set<string> => {
+    const set = new Set<string>();
+    for (const word of text.toLowerCase().match(/[a-z0-9]{2,}/g) ?? []) set.add(word);
+    const cjk = (text.match(/[\u4e00-\u9fa5]+/g) ?? []).join("");
+    for (let index = 0; index + 1 < cjk.length; index += 1) set.add(cjk.slice(index, index + 2));
+    return set;
+  };
+  const a = tokens(left);
+  const b = tokens(right);
+  if (a.size === 0 || b.size === 0) return 0;
+  let shared = 0;
+  for (const token of a) if (b.has(token)) shared += 1;
+  return shared / (a.size + b.size - shared);
+}
+
+function topOverlap(skill: SkillRef, all: readonly SkillRef[]): { name: string; score: number } | null {
+  let best: { name: string; score: number } | null = null;
+  for (const other of all) {
+    if (other.name === skill.name) continue;
+    const score = descriptionOverlap(skill.description, other.description);
+    if (score > 0 && (best === null || score > best.score)) best = { name: other.name, score };
+  }
+  return best;
+}
+
+/** 进化收益：采纳后 7 天该技能加载率相对前 7 天的变化（单位 pp）；任一窗口无曝光 = 样本不足 */
+function gainOf(input: WeeklyInput, applied: AppliedRun): string {
+  const before = emptyStat();
+  const after = emptyStat();
+  const day = 86_400_000;
+  for (const event of input.events) {
+    if (typeof event.ts !== "number") continue;
+    const inBefore = event.ts >= applied.at - 7 * day && event.ts < applied.at;
+    const inAfter = event.ts >= applied.at && event.ts < applied.at + 7 * day;
+    if (!inBefore && !inAfter) continue;
+    const isAdvertised = event.kind === "advertised" && Array.isArray(event.skills)
+      && (event.skills as TelemetrySkill[]).some((skill) => skill?.name === applied.skill && skill.disabled !== true);
+    const target = inBefore ? before : after;
+    if (isAdvertised) target.advertised += 1;
+    else if (event.kind === "loaded" && event.skill === applied.skill) target.loaded += 1;
+  }
+  if (before.advertised === 0 || after.advertised === 0) return "样本不足";
+  const delta = (ratio(after.loaded, after.advertised) - ratio(before.loaded, before.advertised)) * 100;
+  return `${delta >= 0 ? "+" : ""}${delta.toFixed(1)}pp`;
+}
+
+export function buildWeeklyReport(input: WeeklyInput): string {
+  const table = perSkillWeeks(input.events);
+  const currentWeek = weekOf(input.now);
+  const lines: string[] = [`技能进化周报：${currentWeek}（工作区：${input.cwd}，只含 .pi/skills）`];
+
+  const weeks = [...table.keys()].sort().slice(-CANDIDATE_WEEKS);
+  for (const week of weeks) {
+    const stats = [...(table.get(week)?.values() ?? [])];
+    const advertised = stats.reduce((sum, stat) => sum + stat.advertised, 0);
+    const loaded = stats.reduce((sum, stat) => sum + stat.loaded, 0);
+    lines.push(`  ${week}  曝光 ${advertised} · 加载 ${loaded} · 加载率 ${percent(loaded, advertised)}`);
+  }
+
+  let advertised = 0;
+  let loaded = 0;
+  let failed = 0;
+  const attribution = new Map<string, number>();
+  const conflicts = { p0: 0, p1: 0, stock: 0, added: 0 };
+  for (const event of input.events) {
+    if (event.kind === "advertised") {
+      const skills = Array.isArray(event.skills) ? (event.skills as TelemetrySkill[]) : [];
+      advertised += skills.filter((skill) => skill?.disabled !== true).length;
+    } else if (event.kind === "loaded") loaded += 1;
+    else if (event.kind === "failed") failed += 1;
+    else if (event.kind === "attributed" && typeof event.category === "string") {
+      attribution.set(event.category, (attribution.get(event.category) ?? 0) + 1);
+    } else if (event.kind === "conflict") {
+      if (event.level === "P0") conflicts.p0 += 1;
+      else if (event.level === "P1") conflicts.p1 += 1;
+      if (event.stock === true) conflicts.stock += 1;
+      else conflicts.added += 1;
+    }
+  }
+
+  lines.push(`加载率 ${percent(loaded, advertised)}（加载 ${loaded} / 曝光 ${advertised}）`);
+  // 分母是「加载 + 尝试失败」：只除加载数会算出 >100% 的假值
+  lines.push(`尝试失败率 ${percent(failed, loaded + failed)}（失败 ${failed} / 尝试 ${loaded + failed}）`);
+  const attributionTotal = [...attribution.values()].reduce((sum, count) => sum + count, 0);
+  const distribution = ["A", "B", "C", "D", "E", "F", "G"]
+    .map((key) => `${key} ${attribution.get(key) ?? 0}`)
+    .join(" · ");
+  lines.push(`归因分布：${distribution}${attributionTotal === 0 ? "（本次无归因记录）" : ""}`);
+  lines.push(`冲突密度：存量 ${conflicts.stock} 条 / 新增 ${conflicts.added} 条（P0 ${conflicts.p0} · P1 ${conflicts.p1}）`);
+
+  // stale = 卡死没出提案，既不是提案也不能算耗掉一次机会，排除在外（否则卡死越多采纳率越低）
+  const proposed = input.runs.filter(
+    (run) => run.status !== "dispatched" && run.status !== "abandoned" && run.status !== "stale",
+  ).length;
+  const appliedRuns = input.runs.filter((run) => run.status === "applied").length;
+  const rolledBack = input.runs.filter((run) => run.status === "rolled-back").length;
+  lines.push(`采纳率 ${percent(appliedRuns, proposed)}（采纳 ${appliedRuns} / 提案 ${proposed}）`);
+  lines.push(`回滚率 ${percent(rolledBack, appliedRuns + rolledBack)}（回滚 ${rolledBack} / 采纳 ${appliedRuns}）`);
+
+  const gains = (input.applied ?? []).map((run) => `${run.skill} ${gainOf(input, run)}`);
+  lines.push(`进化收益（采纳后 7 天加载率 Δ）：${gains.length > 0 ? gains.join("、") : "样本不足"}`);
+
+  lines.push(`零加载候选（近 ${CANDIDATE_WEEKS} 周 曝光>0 且 加载=0）：`);
+  const candidates: string[] = [];
+  for (const skill of input.skills) {
+    const hit = weeks.length === CANDIDATE_WEEKS
+      && weeks.every((week) => {
+        const stat = table.get(week)?.get(skill.name);
+        return stat !== undefined && stat.advertised > 0 && stat.loaded === 0;
+      });
+    if (!hit) continue;
+    const refs = input.referenceScan?.(skill.name);
+    const parts: string[] = [];
+    if (refs) {
+      parts.push(`.cursor stub ${refs.cursorStub ? "有" : "缺"}`);
+      parts.push(`AGENTS 索引 ${refs.agentsIndex ? "有" : "缺"}`);
+      parts.push(`其它引用 ${refs.mentions} 处`);
+    }
+    const overlap = topOverlap(skill, input.skills);
+    parts.push(overlap ? `描述重叠 ${overlap.name} ${overlap.score.toFixed(2)}` : "描述重叠 无");
+    candidates.push(`  · ${skill.name}  ${parts.join(" · ")}`);
+  }
+  if (weeks.length < CANDIDATE_WEEKS) {
+    lines.push(`  样本不足：当前只有 ${weeks.length} 周遥测，需要连续 ${CANDIDATE_WEEKS} 周`);
+  } else if (candidates.length === 0) {
+    lines.push("  无");
+  } else {
+    lines.push(...candidates);
+  }
+
+  lines.push("注：加载率只反映「技能文件被读取」，读 ≠ 用；只读 description 就照做的情况记不到。");
+  lines.push("候选表只是提醒，不是判决；删技能要 /skill-evolve approve <runId> --prune");
+  return lines.join("\n");
+}
+
+export interface WeeklyDeps {
+  cwd: string;
+  evolutionDir: string;
+  telemetryDir: string;
+  now?: () => number;
+  loadSkills?: () => { skills: { name: string; description: string }[] };
+  referenceScan?: (skill: string) => ReferenceScan;
+}
+
+/** 技能名 + description：零加载候选要靠描述重叠度判断「是不是兄弟技能在抢」 */
+function readSkillRefs(cwd: string): SkillRef[] {
+  const dirs = listSkillDirs(path.join(cwd, ".pi", "skills"));
+  const refs: SkillRef[] = [];
+  for (const name of dirs) {
+    let text: string;
+    try {
+      text = fs.readFileSync(path.join(cwd, ".pi", "skills", name, "SKILL.md"), "utf8");
+    } catch {
+      continue;
+    }
+    refs.push({ name, description: readFrontmatter(text).description ?? "" });
+  }
+  return refs;
+}
+
+/** 生产入口：读盘 + 组数据，报告本体在 buildWeeklyReport。weekText 每次调用都重读，避免拿到旧盘面 */
+export function createWeeklyReport(deps: WeeklyDeps): { weekText(): string } {
+  const now = deps.now ?? (() => Date.now());
+  const loadSkills = deps.loadSkills ?? (() => ({ skills: readSkillRefs(deps.cwd) }));
+  const referenceScan = deps.referenceScan ?? createReferenceScan(deps.cwd);
+  const weekText = (): string => {
+    const time = now();
+    const queue = readQueue(deps.evolutionDir);
+    const applied = queue
+      .filter((item) => item.status === "applied")
+      .map((item) => ({ skill: item.skill, at: item.createdAt }));
+    const skills = loadSkills().skills.map((skill) => ({ name: skill.name, description: skill.description ?? "" }));
+    return buildWeeklyReport({
+      cwd: deps.cwd,
+      now: time,
+      events: readEvents(deps.telemetryDir, CANDIDATE_WEEKS * 7, time),
+      runs: listRuns(deps.evolutionDir, 50),
+      queue,
+      skills,
+      applied,
+      referenceScan,
+    });
+  };
+  return { weekText };
+}

package/extensions/skill-evolve/prompts//345/244/215/347/233/230.md

@@ -0,0 +1,172 @@
+# 技能进化 · 复盘任务（M3）
+
+你是一个**后台复盘 agent**，不面向用户：没有人会读你的聊天回复，唯一的交付物是文件。
+你的任务是回答一个问题：**上一轮会话里，被曝光的技能为什么没被加载？**
+
+## 一、输入（全部已给在提示词末尾）
+
+- `会话ID`：上一轮会话的 ID。
+- `会话原文`：该会话 JSONL 的**绝对路径**。读它的唯一合法方式是本节「二」的抽查法。
+- `索引`：`00-session/index.json`，由脚本预先生成，含每一行的 `line`（1 起算）、`type`、`role?`、`ts?`、`chars`、`excerpt`（≤80 字）。
+- `run 目录`：`runs/<runId>/`，你**只能**往这里写文件。
+- `覆盖轮数`：本次复盘覆盖的是「刚刚结束的一轮」还是「合并了 N 轮待复盘区间」。
+  写的是 N 轮时，起点 ts 到现在的**每一轮**都在范围内：结论必须覆盖整段，不能只看最后一轮；
+  同一个技能在多轮里重复曝光的，`evidence` 要把各轮的行号都列上。
+
+如果会话原文一栏写着「不可用」（evidenceMode=telemetry-only）：不要编造证据，`evidence` 一律留空数组，`confidence` 不得高于 `low`，并在 `notes` 里写明「本轮无会话原文，结论仅来自遥测」。
+
+## 二、读会话：只许抽查，不许整文件读
+
+会话原文平均接近 1MB。**禁止**直接整文件读它（禁止 `cat`、禁止不带 offset/limit 的 read、禁止把它塞进任何命令输出）。
+
+正确做法：
+
+1. 先读 `index.json`，用 `excerpt` 找候选行：`advertised` 相关轮次、用户请求、被调用的工具、疑似读了别的技能的位置。
+2. 用行号附近的窗口读原文：`read <会话原文> offset=<目标行-10> limit=40`，或 `bash: sed -n '1000,1060p' <会话原文>`。
+3. 需要全文定位关键词时用 `rg -n '<关键词>' <会话原文>`，**只取命中行号**，再回到第 2 步取上下文。
+
+每次抽查都要能说出「我要在这几行验证哪条假设」。凑不出假设就说明证据不足，写 `confidence: low` 并说明缺口。
+
+## 三、技能文件怎么读（可以读，但不许改）
+
+- 想核对某技能 description 的措辞、或 frontmatter 是否损坏，可以读 `.pi/skills/<名>/SKILL.md`。
+- **绝对禁止修改 `.pi/skills/` 下任何文件**，也禁止修改 `.pi/settings.json`、`.pi/evolution/config.json`、遥测文件、其他 run 目录。本任务只出结论，不做改动。
+
+## 四、判断每条被曝光技能的结局
+
+对上一轮 `advertised` 事件里的**每一个**技能（提示词里会给技能名清单；完整记录在 `telemetry/` 当日分片里，可读但不必读）判定：
+
+- `loaded: true`：会话里确有读取该技能文件的动作（`read` 该 `SKILL.md`，或 `bash` 命令里出现 `skills/<名>/SKILL.md`）。给出该动作的行号。
+- `loaded: false`：没有这条证据。此时必须给出 `whyNotLoaded`，取下面 A~G 之一。
+
+### 归因代号（只许用这七个字母）
+
+| 代号 | 含义 | 判定要点 |
+|---|---|---|
+| `A` | 技能被配置成不参与模型调用（`disableModelInvocation: true`） | 它压根没进系统提示词，不该算「未加载」。看技能 frontmatter / 设置里的禁用项 |
+| `B` | frontmatter 坏了，技能没被正常发现 | 读该 `SKILL.md` 头部，看是否缺 `name`/`description`、YAML 是否破损 |
+| `C` | 同名技能被别人抢先（collision） | 同一名字有多份定义，实际生效的不是这份 |
+| `D` | 文件不在技能发现范围内 | 路径不在 `.pi/skills/`、或层级/命名不符合发现规则。只记录，不改 |
+| `E` | 本轮没有能读文件的工具（无 `read`、无 `bash`） | 看系统提示词的 selectedTools / 本轮实际调用过的工具 |
+| `F` | 兄弟技能被选中，它没有（描述重叠竞争） | 找到实际加载的同类技能，对比两边 description 的措辞差异 |
+| `G` | 用户请求与 description 没有共同的路由词 | 摘出用户原话里的关键词，指出 description 缺哪些词 |
+
+判不准就用 `confidence: low` 并在 `notes` 里写「需要人工判断」，**不要**为了凑字母硬套。
+
+### 机械层已经判过的：你只做 F/G（重要）
+
+提示词末尾有一节「已机械归因」：这些技能已经由脚本按机械判据定成 A~E（配置禁用 / frontmatter 诊断 / 同名冲突 /
+不在发现范围 / 本轮没有读工具）。对这些技能：
+
+- 直接沿用它的代号，**不要重判、不要改**；`evidence` 可以留空数组，`confidence` 写 `medium`
+  （机械判据不依赖会话证据）。
+- 只有当你在会话里查到**能推翻**它的证据时才允许改，且必须在 `notes` 里写「改判理由 + 证据行号」，
+  `confidence` 不得高于 `medium`。
+
+你真正要判的是**没出现在「已机械归因」清单里**的技能，而且只能给 `F`（兄弟技能被选中、描述重叠竞争）
+或 `G`（description 缺路由词）。机械判据已经排除了「配置 / 损坏 / 冲突 / 范围 / 工具」五种非文案原因，
+跳过它们直接建议「改写 description」是这条流程最常见的错判。
+
+### 两个必须承认的盲区（写进 `notes`）
+
+- 只读了技能 description 就照着做、从没打开 `SKILL.md`：本流程这类技能一律记 `loaded: false`，但其实它起作用了。
+- 读了 `SKILL.md` 却没照做：本流程记 `loaded: true`，但其实没起作用。
+- 所以「加载率低」不等于「技能没用」。你的结论只描述证据，不下价值判断。
+
+## 五、输出：`01-findings.json`（唯一交付物）
+
+写到 `<run 目录>/01-findings.json`，UTF-8，严格 JSON（不要注释、不要尾逗号）：
+
+```json
+{
+  "skills": [
+    {
+      "name": "技能名",
+      "advertised": true,
+      "loaded": false,
+      "whyNotLoaded": "G",
+      "confidence": "high",
+      "evidence": [{ "line": 1234 }]
+    }
+  ],
+  "notes": []
+}
+```
+
+字段约束：
+
+- `name`：与 `advertised` 里的技能名完全一致，不许改名或翻译。
+- `advertised`：固定 `true`（这批就是曝光清单里的）。
+- `loaded`：布尔。全部 `loaded: true` 的技能也照样列出，`whyNotLoaded` 省略该键。
+- `whyNotLoaded`：仅 `loaded: false` 时出现，取值 `"A"`–`"G"`。
+- `confidence`：`"high"` / `"medium"` / `"low"`，只有看到原文证据才配 `high`。
+- `evidence`：数组，每项 `{ "line": 行号 }`，可再加 `{ "ref": "..." }` 说明该行是什么；行号必须是**会话 JSONL 的物理行号**，与 `index.json` 的 `line` 同一套编号。给不出行号就不要写 `evidence` 项，改为把 `confidence` 降到 `low`。
+- **索引不可用时（prompt 里「索引」写「不可用」/ evidenceMode=telemetry-only）：`evidence` 必须为空数组 `[]`，`confidence` 不得高于 `low`**，并在 `notes` 里写「本轮无会话原文与索引，结论仅来自遥测」。
+- `notes`：字符串数组，写盲区提醒、证据缺口、需要人工确认的点。
+
+## 六、提案：只对「有把握」的 finding 生成（可选）
+
+满足**全部**条件的 finding 才生成提案：`loaded: false`、`whyNotLoaded` 是 `G`（或 `F` 且能指出兄弟技能的具体措辞差异）、
+`confidence` 是 `high`。其余一律不生成 —— 宁可没有提案，也不拿猜测去改技能。
+
+产物都写在 `<run 目录>` 下：
+
+1. `02-proposal.json`：
+
+```json
+{
+  "type": "improve",
+  "skill": "技能名",
+  "rationale": "一句话：缺哪些路由词、证据在哪几行",
+  "evidence": [1234, 1250],
+  "diffFile": "02-proposal.diff"
+}
+```
+
+- `type`：`improve`（改现有技能）/ `create`（新建）/ `merge`（合并两个重叠技能）/ `prune`（建议废弃）。
+- 新建技能时把 `diffFile` 换成 `"candidateFile": "candidate/<名>/SKILL.md"`，并同时产出该文件。
+- `evidence` 只许填**会话 JSONL 的物理行号**，与 `01-findings.json` 同一套编号。
+
+2. `02-proposal.diff`（`improve`/`merge`/`prune` 必填）：**unified diff**，不是整篇新正文。
+
+```
+--- a/.pi/skills/<名>/SKILL.md
++++ b/.pi/skills/<名>/SKILL.md
+@@ -12,6 +12,8 @@
+ 上下文行
+-旧行
++新行
+```
+
+- 文件头只能指向 `.pi/skills/...`；出现别的路径（例如 `b/rust_server/src/x.rs`）整份提案判 `bad_path` 作废。
+- 增删合计 > 40 行会被标 `too_large` 转人工，所以提案要小而准：只改 description / 触发词那几行。
+
+3. `candidate/<名>/SKILL.md`（`create` 必填）：frontmatter 必须有 `name` 与 `description`；
+   `name` 与目录名一致、≤20 字、只含小写字母/数字/短横线（`^[a-z0-9-]+$`）。
+
+## 七、三条禁令（违反即任务失败）
+
+1. 只能写 `<run 目录>/` 下的文件。`.pi/skills/`、`.pi/settings.json`、`.pi/evolution/config.json`、遥测、别的 run 目录一律不许写。
+2. 不许改 `.pi/skills/` 下任何文件（连「顺手修一下」也不行）—— 提案只是 diff，应用是人工后续动作。
+3. 不许 `git commit` / `git add` / `git push`，也不许在 `run 目录` 外建文件、建临时目录。
+
+## 八、收尾：把 run.json 标成 analyzed / proposed
+
+`<run 目录>/run.json` 已存在，`status` 是 `"dispatched"`。复盘完成后：
+
+1. 用 `read` 读它，用 `write` 整体写回（保持所有原字段不变）；
+2. 没生成提案时 `status` 写 `"analyzed"`；生成了提案时写 `"proposed"`，并追加
+   `"proposal": { "type", "skill", "status", "added", "removed", "file" }`
+   （`status` 填你自检的结论：`ok` / `too_large` / `bad_path` / `invalid_candidate`；`file` 是相对 run 目录的文件名）；
+3. 往 `stages` 数组追加一项：`{ "name": "analyze", "model": "<你实际用的模型名>", "usage": null, "ms": <你这次耗时毫秒> }`；
+4. 往 `artifacts` 加 `"01-findings.json": "<绝对路径>"`，有提案时再加 `"02-proposal.json"` 与 `02-proposal.diff`（或 candidate 路径）。
+
+如果中途发现证据不足以外的问题（比如索引缺行、会话原文读不到），不要伪造结论：`status` 改为 `"abandoned"`，加 `"abandonedReason": "<一句话原因>"`，然后在 `01-findings.json` 的 `notes` 里写明。
+
+## 九、红线
+
+- 不改任何技能、配置、遥测、别人的 run 目录。
+- 不整文件读会话原文。
+- 不虚构行号、不虚构技能名。
+- 不写聊天总结充当交付物：没有 `01-findings.json` 就算没做完。
+- 提案只在 `runs/<runId>/` 里，且只是 diff / candidate，不应用。

package/extensions/skill-evolve/scripts/replay.ts

@@ -0,0 +1,93 @@
+/**
+ * 端到端复演脚本（M6 验收）：临时目录 + 假技能 + 假会话，走完 发现 → 提案 → 评审 → 人批 → 采纳 → 复验。
+ *
+ * 用法：
+ *   node --experimental-strip-types scripts/replay.ts            # 假评审，省 token（默认）
+ *   node --experimental-strip-types scripts/replay.ts --real     # 真起 `pi -p` 做评审
+ *   node --experimental-strip-types scripts/replay.ts --dir /tmp/xxx --keep
+ *
+ * 绝不写本仓：所有产物都在 `--dir` 指定的临时目录（默认 `mkdtemp`）。
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { REPLAY_BEFORE } from "../lib/replay-fixture.ts";
+import { runReplay } from "../lib/replay.ts";
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, "..", "..", "..", "..");
+
+interface Args {
+  real: boolean;
+  keep: boolean;
+  dir: string | null;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = { real: false, keep: false, dir: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index] as string;
+    if (item === "--real") args.real = true;
+    else if (item === "--fake") args.real = false;
+    else if (item === "--keep") args.keep = true;
+    else if (item === "--dir") {
+      args.dir = argv[index + 1] ?? null;
+      index += 1;
+    }
+  }
+  return args;
+}
+
+/** 造一个干净的临时工作区：技能已提交，闸0 的基线才是「干净」 */
+function prepareWorkdir(dir: string): void {
+  const skillFile = path.join(dir, ".pi", "skills", "replay-demo", "SKILL.md");
+  fs.mkdirSync(path.dirname(skillFile), { recursive: true });
+  fs.writeFileSync(skillFile, REPLAY_BEFORE, "utf8");
+  const git = (args: string[]): void => {
+    const result = spawnSync("git", args, { cwd: dir, encoding: "utf8" });
+    if (result.status !== 0) throw new Error(`git ${args.join(" ")} 失败：${result.stderr || result.stdout}`);
+  };
+  git(["init", "-q"]);
+  git(["add", "-A"]);
+  git(["-c", "user.email=replay@example.com", "-c", "user.name=replay", "commit", "-qm", "复演初始状态"]);
+
+  // 硬规则用真仓那一份：复演要验的正是真实评审规则
+  const rulesSrc = path.join(REPO_ROOT, ".pi", "evolution", "rules", "hard-rules.json");
+  if (fs.existsSync(rulesSrc)) {
+    const rulesDst = path.join(dir, ".pi", "evolution", "rules", "hard-rules.json");
+    fs.mkdirSync(path.dirname(rulesDst), { recursive: true });
+    fs.copyFileSync(rulesSrc, rulesDst);
+  }
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const dir = args.dir ?? fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-replay-"));
+  fs.mkdirSync(dir, { recursive: true });
+  prepareWorkdir(dir);
+  console.log(`[复演] 工作区：${dir}`);
+  console.log(`[复演] 评审：${args.real ? "真跑 pi -p" : "假评审（--real 可切真跑）"}`);
+
+  const outcome = await runReplay({
+    cwd: dir,
+    evolutionDir: path.join(dir, ".pi", "evolution"),
+    fakeReview: !args.real,
+    log: (msg) => console.log(msg),
+  });
+
+  console.log("");
+  for (const line of outcome.lines) console.log(line);
+  console.log("");
+  console.log(`[复演] run.json status 序列：${outcome.statuses.join(" → ")}`);
+  for (const failure of outcome.failures) console.log(`[复演] 失败：${failure}`);
+  console.log(`[复演] 结论：${outcome.ok ? "六段全通" : "存在失败段"}`);
+  if (!args.keep) {
+    // 保留在 /tmp 也没意义，失败时留证据
+    if (outcome.ok) fs.rmSync(dir, { recursive: true, force: true });
+    else console.log(`[复演] 失败现场保留：${dir}`);
+  }
+  process.exitCode = outcome.ok ? 0 : 1;
+}
+
+await main();