pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,246 @@
+/**
+ * 端到端复演（设计稿 15 章 M6 验收硬指标）：一条假技能从发现走到复验，六段状态可断言。
+ *
+ * 只允许在临时工作区跑（调用方负责建目录），因为这条链路会真的写 `.pi/skills/` 下的技能文件。
+ * 评审可用 `fakeReview` 注入假结论（省 token）；真跑走 `reviewSpawn`，其余环节一律真写盘。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createApplyTools } from "./evolution-apply.ts";
+import { captureGate0, saveGate0, type GitRunner } from "./gate0.ts";
+import { loadHardRules, type CompiledRule } from "./hard-rules.ts";
+import { createGitRunner } from "./proc.ts";
+import { validateProposal } from "./proposal.ts";
+import { postProcessReview } from "./review-post.ts";
+import { buildReviewPrompt } from "./review-prompt.ts";
+import { runReviewChild, type ReviewSpawn } from "./review-run.ts";
+import { updateRunStatus, writeRunRecord, type RunStatus } from "./runs.ts";
+import { buildSessionIndex } from "./session-index.ts";
+import { directQueue, type MutationQueue } from "./telemetry.ts";
+import { FAKE_REVIEW_TEXT, REPLAY_AFTER, REPLAY_BEFORE, REPLAY_DIFF, fakeSessionText } from "./replay-fixture.ts";
+
+export const REPLAY_STAGES = ["discover", "propose", "review", "approve", "apply", "verify"] as const;
+export type ReplayStage = (typeof REPLAY_STAGES)[number];
+
+const STAGE_LABEL: Record<ReplayStage, string> = {
+  discover: "发现",
+  propose: "提案",
+  review: "评审",
+  approve: "人批",
+  apply: "采纳",
+  verify: "复验",
+};
+
+export interface ReplayOptions {
+  cwd: string;
+  evolutionDir: string;
+  /** true = 用内置假评审结论（不烧 token）；false = 真起 `pi -p` */
+  fakeReview: boolean;
+  skillName?: string;
+  now?: () => number;
+  log?: (msg: string) => void;
+  queue?: MutationQueue;
+  git?: GitRunner;
+  reviewSpawn?: ReviewSpawn;
+  reviewModel?: string;
+  reviewTimeoutMs?: number;
+  fakeReviewText?: string;
+  rulesFile?: string;
+}
+
+export interface ReplayOutcome {
+  ok: boolean;
+  runId: string;
+  /** 六段各自的结果（人话） */
+  stages: Record<ReplayStage, string>;
+  /** run.json 的 status 变迁序列 */
+  statuses: string[];
+  failures: string[];
+  lines: string[];
+}
+
+function fakeGit(): GitRunner {
+  return () => ({ code: 0, out: "" });
+}
+
+async function writeText(queue: MutationQueue, file: string, text: string): Promise<void> {
+  await queue(file, async () => {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, text, "utf8");
+  });
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function runReplay(options: ReplayOptions): Promise<ReplayOutcome> {
+  const now = options.now ?? (() => Date.now());
+  const log = options.log ?? (() => {});
+  const queue = options.queue ?? directQueue;
+  const git = options.git ?? createGitRunner();
+  const skill = options.skillName ?? "replay-demo";
+  const started = now();
+  const runId = `replay-${started.toString(36)}`;
+  const evolutionDir = options.evolutionDir;
+  const runDir = path.join(evolutionDir, "runs", runId);
+  const skillFile = path.join(options.cwd, ".pi", "skills", skill, "SKILL.md");
+
+  const stages = Object.fromEntries(REPLAY_STAGES.map((stage) => [stage, "未执行"])) as Record<ReplayStage, string>;
+  const statuses: string[] = [];
+  const failures: string[] = [];
+
+  const recordStatus = (): void => {
+    const record = readJson<{ status?: string }>(path.join(runDir, "run.json"));
+    if (record?.status) statuses.push(record.status);
+  };
+  const fail = (stage: ReplayStage, why: string): void => {
+    stages[stage] = `失败：${why}`;
+    failures.push(`${stage}：${why}`);
+  };
+
+  // ── 1. 发现：技能在盘上 + 会话索引 + run.json（dispatched → analyzed）
+  await writeText(queue, skillFile, REPLAY_BEFORE);
+  const sessionFile = path.join(evolutionDir, "session", "session.jsonl");
+  await writeText(queue, sessionFile, fakeSessionText(options.cwd, started));
+  const index = buildSessionIndex(fs.readFileSync(sessionFile, "utf8"));
+
+  await writeRunRecord(
+    runDir,
+    {
+      runId,
+      status: "dispatched" as RunStatus,
+      trigger: "manual",
+      sessionId: "replay-session",
+      sessionHash: "replay",
+      sessionFile,
+      evidenceMode: "session+telemetry",
+      dispatchedAt: started,
+      dispatchedAtIso: new Date(started).toISOString(),
+      pid: process.pid,
+      cwd: options.cwd,
+      skills: [skill],
+      stages: [],
+      artifacts: {},
+    },
+    queue,
+  );
+  recordStatus();
+  await writeText(queue, path.join(runDir, "00-session", "index.json"), `${JSON.stringify(index, null, 2)}\n`);
+  await updateRunStatus(evolutionDir, runId, "analyzed", queue);
+  recordStatus();
+  stages.discover = `技能 ${skill} · 会话索引 ${index.stats.lines} 行 · run ${runId}`;
+
+  // ── 2. 提案：写 02-proposal.{json,diff}
+  const diff = REPLAY_DIFF;
+  await writeText(
+    queue,
+    path.join(runDir, "02-proposal.json"),
+    `${JSON.stringify({ type: "improve", skill, diffFile: "02-proposal.diff", rationale: "复演：补一条索引优先" }, null, 2)}\n`,
+  );
+  await writeText(queue, path.join(runDir, "02-proposal.diff"), diff);
+  const proposal = validateProposal(runDir);
+  if (proposal.status !== "ok") fail("propose", `提案校验 ${proposal.status}（${proposal.detail ?? "无详情"}）`);
+  else {
+    await updateRunStatus(evolutionDir, runId, "proposed", queue, { proposal });
+    recordStatus();
+    stages.propose = `improve ${skill}（diff ${diff.split("\n").length} 行）`;
+  }
+
+  // ── 3. 评审
+  if (failures.length === 0) {
+    let text: string;
+    if (options.fakeReview) text = options.fakeReviewText ?? FAKE_REVIEW_TEXT;
+    else {
+      const compiled = loadHardRules(options.rulesFile ?? path.join(evolutionDir, "rules", "hard-rules.json"));
+      for (const invalid of compiled.invalid) log(`[复演] 硬规则不可用：${invalid}`);
+      const rules: readonly CompiledRule[] = compiled.compiled;
+      const prompt = buildReviewPrompt({ skillName: skill, skillText: REPLAY_AFTER, diffApplied: true, diff, hardRules: rules });
+      const outcome = await runReviewChild({
+        prompt,
+        cwd: options.cwd,
+        ...(options.reviewModel ? { model: options.reviewModel } : {}),
+        ...(options.reviewSpawn ? { spawnFn: options.reviewSpawn } : {}),
+        ...(options.reviewTimeoutMs ? { timeoutMs: options.reviewTimeoutMs } : {}),
+        log,
+      });
+      if (outcome.status !== "text") {
+        fail("review", `评审子进程 ${outcome.status}：${outcome.detail ?? "无详情"}`);
+        text = "";
+      } else text = outcome.text;
+    }
+    if (failures.length === 0) {
+      const reviewed = postProcessReview(text);
+      const verdict = (reviewed.detail && reviewed.status === "invalid") ? `invalid（${reviewed.detail}）` : String(reviewed.verdict ?? "unknown");
+      const reviewRecord = {
+        status: reviewed.status === "ok" && reviewed.verdict === "pass" ? "reviewed" : "rejected",
+        verdict: reviewed.verdict ?? null,
+        blocking: reviewed.blocking ?? [],
+        notes: reviewed.notes ?? [],
+        reviewerModel: options.reviewModel ?? "inherit",
+        proposerModel: "inherit",
+        sameModel: (options.reviewModel ?? "inherit") === "inherit",
+        at: now(),
+      };
+      await writeText(queue, path.join(runDir, "03-review.json"), `${JSON.stringify(reviewRecord, null, 2)}\n`);
+      if (reviewRecord.status !== "reviewed") fail("review", `评审未通过：${verdict}`);
+      else {
+        await updateRunStatus(evolutionDir, runId, "reviewed", queue, { review: reviewRecord });
+        recordStatus();
+        stages.review = `verdict=${verdict}（${options.fakeReview ? "假评审" : "真评审"}）`;
+      }
+    }
+  }
+
+  // ── 4. 人批：闸0 快照 → 入队 → approve
+  if (failures.length === 0) {
+    await saveGate0(evolutionDir, captureGate0(git, options.cwd, now()), queue);
+    const tools = createApplyTools({
+      evolutionDir,
+      cwd: options.cwd,
+      queue,
+      now,
+      log,
+      git,
+      loadDiagnostics: () => [],
+      runMdCheck: () => ({ code: 0, output: "复演跳过 md-check（临时目录没有仓库脚本）" }),
+    });
+    await tools.enqueueReady();
+    const text = await tools.approve(runId, false);
+    const item = readJson<unknown>(path.join(evolutionDir, "queue.json"));
+    const queueText = JSON.stringify(item ?? {});
+    if (!queueText.includes('"applied"')) fail("approve", `approve 未落实：${text.split("\n")[0] ?? ""}`);
+    else stages.approve = `approve ${runId} → applied（${text.split("\n")[0] ?? ""}）`;
+  }
+
+  // ── 5. 采纳：05-applied.diff + 技能文件真的变了
+  if (failures.length === 0) {
+    const applied = fs.existsSync(path.join(runDir, "05-applied.diff"));
+    const text = fs.existsSync(skillFile) ? fs.readFileSync(skillFile, "utf8") : "";
+    if (!applied) fail("apply", "05-applied.diff 缺失");
+    else if (!text.includes("index.json 再读会话原文")) fail("apply", "技能文件未按提案改动");
+    else {
+      recordStatus();
+      stages.apply = `05-applied.diff 已写，技能文件已更新（${text.length} 字节）`;
+    }
+  }
+
+  // ── 6. 复验：06-verify.json 里每道闸都要 ok
+  if (failures.length === 0) {
+    const verify = readJson<{ status?: string; gates?: { id: string; ok: boolean }[] }>(path.join(runDir, "06-verify.json"));
+    if (!verify) fail("verify", "06-verify.json 缺失");
+    else {
+      const bad = (verify.gates ?? []).filter((gate) => !gate.ok);
+      if (verify.status !== "applied") fail("verify", `06-verify.json status=${verify.status ?? "?"}`);
+      else if (bad.length > 0) fail("verify", `闸未过：${bad.map((gate) => gate.id).join("、")}`);
+      else stages.verify = `${verify.gates?.length ?? 0} 道闸全 ok`;
+    }
+  }
+
+  const lines = REPLAY_STAGES.map((stage) => `${STAGE_LABEL[stage]}（${stage}）：${stages[stage]}`);
+  return { ok: failures.length === 0, runId, stages, statuses, failures, lines };
+}

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

@@ -0,0 +1,181 @@
+/**
+ * `/skill-evolve status|report` 的纯文本渲染（无 IO，序列化口径集中在这里）。
+ *
+ * 拆出来是为了把 evolution.ts 压在 300 行以内：那边只管读盘与状态，
+ * 这里只管「拿到数据怎么排版」，所以本文件能被单测直接喂假数据。
+ */
+import type { EvolutionConfig } from "./config.ts";
+import type { DispatchOutcome } from "./dispatch.ts";
+import { flagStateText, TELEMETRY_OFF_WARNING, telemetryOffWhileEnabled } from "./flags.ts";
+import type { ProposalSummary } from "./proposal.ts";
+import type { RunReview, RunSummary } from "./runs.ts";
+import type { StaleRun } from "./stale.ts";
+import { UNTRUSTED_NOTE, type SelftestReport } from "./selftest.ts";
+import type { TelemetrySummary } from "./telemetry.ts";
+
+/** 提案摘要：只显示不应用（M3 只生成提案，评审/应用不在本版） */
+function proposalText(proposal: ProposalSummary): string {
+  const size = proposal.added + proposal.removed > 0 ? ` +${proposal.added}/-${proposal.removed}` : "";
+  return `｜提案 ${proposal.type} ${proposal.skill} [${proposal.status}]${size}`;
+}
+
+/** 评审摘要：结论 + 建议动作；同模型自评单独标出来，避免被当成独立复核 */
+function reviewText(review: RunReview): string {
+  const verdict = review.verdict ? `/${review.verdict}` : "";
+  const model = review.sameModel ? "｜同模型自评" : "";
+  return `｜评审 ${review.status}${verdict}（建议 ${review.action ?? "无"}${model}）`;
+}
+
+function runLine(run: RunSummary): string {
+  const extra = `${run.proposal ? proposalText(run.proposal) : ""}${run.review ? reviewText(run.review) : ""}`;
+  return `    ${run.runId}  ${run.status}  ${stamp(run.dispatchedAt)}${extra}`;
+}
+
+/** 自检红字：没过就把流水线停用这件事顶到 status 的最前面 */
+function selftestLine(selftest: SelftestReport | undefined): string[] {
+  if (!selftest) return ["  自检：还没跑过（/skill-evolve selftest）"];
+  if (!selftest.passed) return [`  【红】${UNTRUSTED_NOTE}`];
+  return [`  自检：通过（${selftest.atIso}）`];
+}
+
+/** 时间戳统一按 ISO 输出；null 表示历史 run 缺字段，不要伪造成当前时间 */
+function stamp(ts: number | null): string {
+  return ts ? new Date(ts).toISOString() : "时间未知";
+}
+
+/** runId 前半段就是会话哈希：状态行只留它，否则一条就占满整行 */
+export function shortRunId(runId: string): string {
+  return runId.split("-")[0] ?? runId;
+}
+
+/** 超长日志行截断：状态行不能被一行 panic 撞满 */
+function elide(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/**
+ * 卡死条目：`卡死 1 条：354df7db（child-exited，日志最后一行：…）`。
+ * 行内就要带原因与最后一句日志 —— “复盘失败”四个字本身没法定位问题。
+ */
+function staleLine(runs: readonly StaleRun[]): string[] {
+  if (runs.length === 0) return [];
+  // 同一会话可能派生多条 run（runId 前缀就是会话哈希）：撞车时退回完整 runId，免得两条长得一模一样
+  const prefixCount = new Map<string, number>();
+  for (const run of runs) {
+    const key = shortRunId(run.runId);
+    prefixCount.set(key, (prefixCount.get(key) ?? 0) + 1);
+  }
+  const items = runs.map((run) => {
+    const short = shortRunId(run.runId);
+    const id = (prefixCount.get(short) ?? 0) > 1 ? run.runId : short;
+    const tail = run.lastLine === null ? "无日志（child.log 不存在或为空）" : elide(run.lastLine, 80);
+    return `${id}（${run.reason}，日志最后一行：${tail}）`;
+  });
+  return [`  卡死 ${runs.length} 条：${items.join("，")}`];
+}
+
+export interface StatusInput {
+  config: EvolutionConfig;
+  /** 配置文件路径，让用户知道 on/off 改的是哪个文件 */
+  configPath: string;
+  telemetryDir: string;
+  /** undefined = 锁空闲；null = 锁在但 owner.json 读不出 pid */
+  lockPid: number | null | undefined;
+  /** 活着的 Web 面板（locks/web.json 且 pid 存活）；null/undefined 都表示不显示这一行 */
+  webPanel?: { url: string; pid: number } | null;
+  runs: RunSummary[];
+  /** 已判卡死的 run（lib/stale.ts）：有就单列一行，带原因与日志尾部 */
+  staleRuns?: StaleRun[];
+  selftest?: SelftestReport;
+}
+
+/**
+ * 开关行：采集与复盘分两段写。两个字段本来就是独立的，合成一句「已开」只会让人以为只有一个总开关；
+ * 第四种组合（只开复盘不采集）再补一句警告 —— 归因靠遥测，缺了就不能静默。
+ */
+export function switchLine(config: EvolutionConfig): string {
+  const hint = config.enabled && config.telemetry ? "/skill-evolve off 全关" : "/skill-evolve on 全开";
+  const line = `${flagStateText(config.enabled, config.telemetry)}（${hint}；collect / review 单独控制）`;
+  return telemetryOffWhileEnabled(config.enabled, config.telemetry) ? `${line} ⚠ ${TELEMETRY_OFF_WARNING}` : line;
+}
+
+/** Web 面板一行：只在记录活着时出现，死记录当作没起过（清理动作别照着它动手） */
+function webPanelLine(panel: { url: string; pid: number } | null | undefined): string[] {
+  return panel ? [`  Web 面板：${panel.url}（pid ${panel.pid}）`] : [];
+}
+
+export function renderStatus(input: StatusInput): string {
+  const { config, lockPid } = input;
+  const lockText =
+    lockPid === undefined ? "空闲" : `持有中（pid ${lockPid ?? "未知"}）`;
+  return [
+    "技能进化 · 状态",
+    `  ${switchLine(config)}`,
+    `  配置：${input.configPath}（不存在即默认全关）· 遥测目录：${input.telemetryDir}`,
+    `  去抖 ${Math.round(config.idleMs / 1000)}s · 单 run 上限 ${Math.round(config.maxRuntimeMs / 60_000)}min · 单会话派生上限 ${config.perSessionCap}`,
+    `  锁：${lockText}`,
+    ...webPanelLine(input.webPanel),
+    ...selftestLine(input.selftest),
+    ...staleLine(input.staleRuns ?? []),
+    ...(input.runs.length === 0
+      ? ["  最近 run：无"]
+      : ["  最近 run：", ...input.runs.map(runLine)]),
+  ].join("\n");
+}
+
+/** 报告固定的那句免责：加载率只覆盖「读了文件」这条证据链，读数时别当技能有效性的判决 */
+export const LOAD_RATE_NOTE = [
+  "注意：加载率低 ≠ 技能没用。只读了 description 就照做、读了文件却没照做，这两类都不在「读文件」这条证据链里；",
+  "      结论要配合 runs/<runId>/01-findings.json 一起看。",
+];
+
+export interface ReportInput {
+  days: number;
+  summary: TelemetrySummary;
+  runs: RunSummary[];
+  selftest?: SelftestReport;
+}
+
+export function renderReport(input: ReportInput): string {
+  const { summary, days } = input;
+  const missed = summary.missedTop;
+  return [
+    `技能进化 · 近 ${days} 天报告`,
+    `  曝光：${summary.rounds} 轮 / ${summary.advertised} 次`,
+    `  加载：${summary.loaded} 次（读取失败 ${summary.failed} 次）`,
+    `  加载率：${summary.advertised > 0 ? `${(summary.loadRate * 100).toFixed(1)}%` : "无曝光数据"}`,
+    ...(missed.length === 0
+      ? [`  未命中：${summary.missed} 次`]
+      : [
+          `  未命中：${summary.missed} 次，top${missed.length}：`,
+          ...missed.map((item, index) => `    ${index + 1}. ${item.skill} × ${item.count}`),
+        ]),
+    ...(input.runs.length === 0
+      ? ["  run：无"]
+      : ["  run：", ...input.runs.map(runLine)]),
+    ...selftestLine(input.selftest),
+    ...(input.runs.some((run) => run.proposal)
+      ? ["  提案只生成不应用：看 runs/<runId>/02-proposal.json 与 02-proposal.diff（或 candidate/），本版不评审不写入 .pi/skills"]
+      : []),
+    "",
+    ...LOAD_RATE_NOTE,
+  ].join("\n");
+}
+
+/** 手动 `/skill-evolve run` 的回执：把三种 outcome 翻译成一句人话（CLI 回显用） */
+export function renderManualDispatch(outcome: DispatchOutcome): string {
+  if (outcome.status === "dispatched") {
+    const { runId, pid, runDir } = outcome.run;
+    return [`已派生复盘：${runId}（pid ${pid ?? "未知"}）`, `  目录：${runDir}`].join("\n");
+  }
+  if (outcome.status === "skipped") {
+    if (outcome.why === "disabled") return "技能进化总开关是关的：先 /skill-evolve on";
+    if (outcome.why === "lock") return `已有复盘在跑（pid ${outcome.ownerPid ?? "未知"}），本次未派发`;
+    if (outcome.why === "selftest-failed") return `必红自检未通过，流水线停用：先 /skill-evolve selftest 看哪条坏样本没被拦住`;
+    if (outcome.why === "busy") {
+      return `已有子进程在跑（pid ${outcome.ownerPid ?? "未知"}），全局同时只允许一个；本次未派发`;
+    }
+    return `本次未派发：${outcome.why}`;
+  }
+  return `本轮已在待复盘区间里（累计 ${outcome.rounds} 轮），静默窗口过后会自动补一次`;
+}

package/extensions/skill-evolve/lib/review-post.ts

@@ -0,0 +1,101 @@
+/**
+ * 评审后处理（设计稿 12.3）：结构、证据、一致性由代码判，机械复验再独立跑一遍。
+ *
+ * 原则是「不信 LLM 自觉」：verdict 只要有一个字段不合规就判 invalid（重评一次仍 invalid 就转人工），
+ * pass 但带 blocking 是自相矛盾，直接 invalid；机械复验失败则一票 reject，覆盖 LLM 的 pass。
+ */
+
+export type ReviewVerdict = "pass" | "reject" | "revise";
+
+export interface ReviewEvidence {
+  file: string;
+  line: number;
+  quote: string;
+}
+
+export interface ReviewBlocking {
+  issue: string;
+  evidence: ReviewEvidence;
+}
+
+export type ReviewStatus = "ok" | "invalid" | "reject";
+
+export interface ReviewResult {
+  status: ReviewStatus;
+  verdict?: ReviewVerdict;
+  blocking: ReviewBlocking[];
+  notes?: string;
+  /** invalid / reject 的具体原因（机器可读前缀 + 人话） */
+  detail?: string;
+}
+
+const VERDICTS: readonly ReviewVerdict[] = ["pass", "reject", "revise"];
+
+/** 从模型输出里抠 JSON：容忍 ```json 围栏与前后废话，抠不出就当解析失败 */
+export function parseReviewJson(text: string): { json?: Record<string, unknown>; error?: string } {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+  const body = (fenced ? fenced[1] : text).trim();
+  const start = body.indexOf("{");
+  const end = body.lastIndexOf("}");
+  if (start < 0 || end <= start) return { error: `bad-json: 输出里没有 JSON 对象（${body.slice(0, 80)}）` };
+  try {
+    const parsed: unknown = JSON.parse(body.slice(start, end + 1));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { error: "bad-json: 顶层不是对象" };
+    return { json: parsed as Record<string, unknown> };
+  } catch (error) {
+    return { error: `bad-json: ${(error as Error).message}` };
+  }
+}
+
+function checkEvidence(raw: unknown): ReviewEvidence | string {
+  if (typeof raw !== "object" || raw === null) return "evidence 不是对象";
+  const item = raw as Record<string, unknown>;
+  const file = typeof item.file === "string" ? item.file.trim() : "";
+  if (file.length === 0) return "evidence.file 为空";
+  // 行号必须是正整数：字符串 "42"、0、-1、"第 42 行" 一律不算可定位证据
+  if (typeof item.line !== "number" || !Number.isInteger(item.line) || item.line <= 0) return "evidence.line 不是正整数";
+  const quote = typeof item.quote === "string" ? item.quote.trim() : "";
+  if (quote.length === 0) return "evidence.quote 为空";
+  return { file, line: item.line, quote };
+}
+
+/**
+ * 12.3 四步里的前三步（结构 / 证据 / 一致性）+ 可选的机械复验。
+ * `recheck` 由调用方注入（读盘 + loadSkillsFromDir），返回错误字符串表示复验失败。
+ */
+export function postProcessReview(text: string, opts: { recheck?: () => string | null } = {}): ReviewResult {
+  const parsed = parseReviewJson(text);
+  if (!parsed.json) return { status: "invalid", blocking: [], detail: parsed.error ?? "bad-json" };
+
+  const verdict = parsed.json.verdict;
+  if (typeof verdict !== "string" || !(VERDICTS as readonly string[]).includes(verdict)) {
+    return { status: "invalid", blocking: [], detail: `bad-verdict: ${String(verdict)}` };
+  }
+
+  const rawBlocking = parsed.json.blocking;
+  if (rawBlocking !== undefined && !Array.isArray(rawBlocking)) {
+    return { status: "invalid", blocking: [], verdict: verdict as ReviewVerdict, detail: "bad-blocking: blocking 不是数组" };
+  }
+  const blocked: ReviewBlocking[] = [];
+  for (const item of (rawBlocking ?? []) as unknown[]) {
+    if (typeof item !== "object" || item === null) {
+      return { status: "invalid", blocking: [], verdict: verdict as ReviewVerdict, detail: "missing-evidence: blocking 项不是对象" };
+    }
+    const evidence = checkEvidence((item as Record<string, unknown>).evidence);
+    if (typeof evidence === "string") {
+      return { status: "invalid", blocking: [], verdict: verdict as ReviewVerdict, detail: `missing-evidence: ${evidence}` };
+    }
+    const issue = typeof (item as Record<string, unknown>).issue === "string" ? String((item as Record<string, unknown>).issue) : "";
+    blocked.push({ issue: issue.length > 0 ? issue : "（未写 issue）", evidence });
+  }
+
+  const notes = typeof parsed.json.notes === "string" ? parsed.json.notes : undefined;
+  if (verdict === "pass" && blocked.length > 0) {
+    return { status: "invalid", blocking: blocked, verdict: "pass", detail: "contradiction: pass 却有 blocking" };
+  }
+
+  const failure = opts.recheck?.() ?? null;
+  if (failure) return { status: "reject", blocking: blocked, verdict: "reject", notes, detail: `frontmatter-invalid: ${failure}` };
+
+  return { status: "ok", blocking: blocked, verdict: verdict as ReviewVerdict, ...(notes ? { notes } : {}) };
+}

package/extensions/skill-evolve/lib/review-prompt.ts

@@ -0,0 +1,82 @@
+/**
+ * 评审 prompt 拼装（设计稿 12.2）：只给四样东西 —— 仓库硬约束、diff、改后全文、验收标准。
+ *
+ * 五条硬约束里的第 2 条是这里的唯一职责：**不给提案理由、不给 findings**，
+ * 否则评审员会顺着提案者的推理复述一遍，评不出真问题。所以入参里根本没有这两个字段，
+ * 单测直接断言产物里不出现这两个来源的痕迹。
+ */
+import type { CompiledRule } from "./hard-rules.ts";
+
+export interface ReviewRuleInput {
+  id: string;
+  level: string;
+  expect: string;
+  why?: string;
+}
+
+export interface ReviewPromptInput {
+  skillName: string;
+  /** 改动后的技能全文；diff 应用失败时是改动前的全文，靠 diffApplied 标注 */
+  skillText: string;
+  diffApplied: boolean;
+  diff: string;
+  hardRules: readonly ReviewRuleInput[] | readonly CompiledRule[];
+  /** 覆盖默认验收标准（必红自检用不到，但保留注入点便于单测） */
+  acceptance?: readonly string[];
+}
+
+export const ACCEPTANCE_STANDARDS: readonly string[] = [
+  "不得引入与硬约束冲突的条款",
+  "不得删除原有的明确禁止项",
+  "新增条款必须能用一句话说清「什么时候适用」",
+  "描述（description）必须包含触发场景词，且不超过 1024 字",
+];
+
+function ruleLines(items: readonly ReviewRuleInput[] | readonly CompiledRule[]): string[] {
+  if (items.length === 0) return ["（规则文件缺失：没有可注入的硬约束，此时应按验收标准判，拿不准的给 revise）"];
+  return items.map((item) => {
+    const rule = "rule" in item ? item.rule : item;
+    const impl = "rule" in item ? `（匹配 ${rule.pattern}）` : "";
+    return `- ${rule.id}（${rule.level}）：${rule.expect}${impl}${rule.why ? ` —— ${rule.why}` : ""}`;
+  });
+}
+
+export function buildReviewPrompt(input: ReviewPromptInput): string {
+  const acceptance = input.acceptance ?? ACCEPTANCE_STANDARDS;
+  const textHeader = input.diffApplied
+    ? "## 改动后的技能全文"
+    : "## 技能全文（diff 无法自动应用，下面是**改动前**的版本，只有上面的 diff 可信）";
+  return [
+    "你是本仓库的技能评审员。你只看到一个候选改动和仓库硬约束，看不到提案者的理由。",
+    "",
+    "## 仓库硬约束（违反任一条 = reject）",
+    ...ruleLines(input.hardRules),
+    "",
+    "## 候选改动（unified diff）",
+    "```diff",
+    input.diff.trimEnd(),
+    "```",
+    "",
+    textHeader,
+    "```markdown",
+    input.skillText.trimEnd(),
+    "```",
+    "",
+    "## 验收标准",
+    ...acceptance.map((item, index) => `${index + 1}. ${item}`),
+    "",
+    "## verdict 怎么选（别把能改的小毛病判成 reject）",
+    "- reject：删掉了原有的明确禁止项 / 引入与硬约束冲突的内容 / 改动方向本身就是错的",
+    "- revise：方向可以接受，但有具体的可修点（如 description 太笼统、缺触发场景词、某句表述含糊）",
+    "- pass：没有阻塞问题",
+    "",
+    "## 输出格式（严格遵守，只输出 JSON，不要代码围栏、不要解释）",
+    '{"verdict":"pass|reject|revise",',
+    ' "blocking":[{"issue":"...","evidence":{"file":"...","line":42,"quote":"原文"}}],',
+    ' "notes":"..."}',
+    "",
+    `技能名：${input.skillName}`,
+    "说明：blocking 每条都必须给 file/line/quote（quote 是被改动文件里的原文片段）；没有问题时 verdict=pass 且 blocking=[]。",
+    "",
+  ].join("\n");
+}

package/extensions/skill-evolve/lib/review-record.ts

@@ -0,0 +1,63 @@
+/**
+ * 评审结果的落盘形态（`03-review.json` / `03-review.md`）与从 run.json 取宿主模型名。
+ *
+ * 单独一个文件是因为评审督导已经接近 300 行闸门；这里全是纯函数，单测可直接调。
+ */
+import type { ActionLevel } from "./classify-action.ts";
+import type { ReviewBlocking, ReviewVerdict } from "./review-post.ts";
+
+export type SupervisorStatus = "reviewed" | "rejected" | "review_failed" | "skipped";
+
+export interface ReviewRecord {
+  status: SupervisorStatus;
+  reason?: string;
+  verdict?: ReviewVerdict;
+  blocking: ReviewBlocking[];
+  notes?: string;
+  action?: ActionLevel;
+  reviewerModel: string;
+  proposerModel: string;
+  sameModel: boolean;
+  attempts?: number;
+  detail?: string;
+  reviewedAt: number;
+  reviewedAtIso: string;
+}
+
+/** 提案者的实际模型：取 run.json 里最后一个带 model 的 stage（复盘子进程收尾会写 analyze） */
+export function stageModel(runRaw: string | undefined): string {
+  if (!runRaw) return "";
+  try {
+    const stages = (JSON.parse(runRaw) as Record<string, unknown>).stages;
+    if (!Array.isArray(stages)) return "";
+    for (let index = stages.length - 1; index >= 0; index -= 1) {
+      const stage = stages[index] as Record<string, unknown>;
+      if (typeof stage.model === "string" && stage.model.length > 0) return stage.model;
+    }
+  } catch {
+    return "";
+  }
+  return "";
+}
+
+export function renderReviewMarkdown(record: ReviewRecord, skill: string): string {
+  const lines: string[] = [];
+  // 首行就要立警告：同模型自评的独立性天然有限，人一眼得看见
+  if (record.sameModel) lines.push("> 同模型自评，独立性有限（proposer 与 reviewer 是同一个模型，请人工复核）", "");
+  lines.push(`# 评审结论：${record.verdict ?? record.status}`, "");
+  lines.push(`- 技能：${skill}`);
+  lines.push(`- status：${record.status}${record.detail ? `（${record.detail}）` : ""}`);
+  lines.push(`- 建议动作：${record.action ?? "无"}（本版一律不写 .pi/skills）`);
+  lines.push(`- 模型：reviewer=${record.reviewerModel} / proposer=${record.proposerModel}`);
+  if (record.blocking.length === 0) {
+    lines.push("", "blocking：无");
+  } else {
+    lines.push("", "## blocking", "");
+    for (const item of record.blocking) {
+      lines.push(`- ${item.issue}`, `  - 证据：${item.evidence.file}:${item.evidence.line} 「${item.evidence.quote}」`);
+    }
+  }
+  if (record.notes) lines.push("", "## notes", "", record.notes);
+  lines.push("");
+  return lines.join("\n");
+}