pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,300 @@
+/**
+ * 派生复盘子进程：抢锁 → 写 run.json 与会话索引 → detached spawn → unref。
+ *
+ * 主会话侧的铁律（设计稿 4.3）：`dispatch()` 背后的长活儿全在 Promise 里，所有错误在内部吞掉，
+ * 绝不惊动用户正在做的事。
+ *
+ * 去抖语义（设计稿 4.4）：`idleMs` 窗口内又结束一轮，不叠加新进程，而是把这一轮**记进 pending**；
+ * 窗口过去后的下一次结算，把 pending 合并成一次派发，子进程读同一个会话文件，自然覆盖整段。
+ * 若整个会话再也没等到那个「下一次」，`flushPending()` 在退出前补发最后一次。
+ */
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import { mergeAttributions, type Attribution } from "./attribution.ts";
+import type { EvolutionConfig } from "./config.ts";
+import { acquireLock, releaseLock, writeOwnerSync } from "./lock.ts";
+import { buildPrompt, readPromptTemplateSync } from "./prompt.ts";
+import { writeRunRecord, type RunRecord } from "./runs.ts";
+import { writeSessionIndex } from "./session-index.ts";
+import { CHILD_LOG, resolvePiBin, spawnDetached, uniqueRunId, sessionHashOf, type SpawnLike } from "./spawn-plan.ts";
+import { mergePendingRounds } from "./pending.ts";
+import { watchRunChild } from "./run-watch.ts";
+import { spawnReviewSupervisor, type SupervisorSpawn } from "./review-spawn.ts";
+import { guardBusy } from "./single-flight.ts";
+import { flushPendingSync, type PendingRounds, type ShutdownResult } from "./shutdown-dispatch.ts";
+import type { MutationQueue, TelemetryWriter } from "./telemetry.ts";
+
+export interface DispatchInput {
+  sessionId: string;
+  skills: string[];
+  sessionFile?: string;
+  /** 已经机械归因过的技能（A~E）：写进 prompt，复盘 agent 不必重判 */
+  attributions?: Attribution[];
+}
+
+export interface DispatchDeps {
+  evolutionDir: string;
+  cwd: string;
+  config: EvolutionConfig;
+  telemetry: TelemetryWriter;
+  queue: MutationQueue;
+  promptTemplatePath: string;
+  log?: (msg: string) => void;
+  now?: () => number;
+  env?: NodeJS.ProcessEnv;
+  spawnFn?: SpawnLike;
+  /** 评审模型（"inherit" 或 provider/model）：每次派生现取，配置改动立即生效 */
+  reviewModel?: () => string;
+  /** 必红自检没过 → 整条流水线停用（设计稿 12.4） */
+  selftestFailed?: () => boolean;
+  /** 评审督导的 spawn（默认 node spawn；单测注入假实现） */
+  supervisorSpawnFn?: SupervisorSpawn;
+  /** pid 存活判定（全局单飞闸用；单测注入，测试里不起真子进程） */
+  alive?: (pid: number) => boolean;
+}
+
+export interface DispatchedRun {
+  runId: string;
+  runDir: string;
+  pid: number | null;
+}
+
+/** 派发结果：调用方（命令 / 事件）要据此出文案，所以不能再只用 null 表示「没派」 */
+export type DispatchOutcome =
+  | { status: "dispatched"; run: DispatchedRun }
+  | { status: "skipped"; why: "disabled" | "cap" | "lock" | "lock-error" | "selftest-failed" | "busy"; ownerPid: number | null }
+  | { status: "superseded"; rounds: number };
+
+export interface DispatchOptions {
+  /** 手动 `/skill-evolve run`：跳过去抖与单会话上限，但**仍必须守全局锁** */
+  bypassThrottle?: boolean;
+  trigger?: RunRecord["trigger"];
+}
+
+/** 去抖：窗口内又结束一轮，只更新 pending，不再叠加进程 */
+export function shouldDebounce(lastDispatchAt: number | undefined, now: number, idleMs: number): boolean {
+  return typeof lastDispatchAt === "number" && now - lastDispatchAt < idleMs;
+}
+
+export interface Dispatcher {
+  dispatch(input: DispatchInput, options?: DispatchOptions): Promise<DispatchOutcome>;
+  /** 退出前同步补发所有 pending，返回真正派发成功的条数；任何失败都不抛 */
+  flushPending(): number;
+}
+
+export function createDispatcher(deps: DispatchDeps): Dispatcher {
+  const log = deps.log ?? (() => {});
+  const env = deps.env ?? process.env;
+  const now = (): number => deps.now?.() ?? Date.now();
+  const lastDispatchAt = new Map<string, number>();
+  const dispatchCount = new Map<string, number>();
+  /** 被去抖挡下的轮次，等窗口过去后在下一个结算点合并派发 */
+  const pending = new Map<string, PendingRounds>();
+  /** 一次进程生命周期内最多持有一把锁；释放后置回 false */
+  let lockHeld = false;
+
+  const releaseOnce = async (): Promise<void> => {
+    if (!lockHeld) return;
+    lockHeld = false;
+    await releaseLock(deps.evolutionDir, log);
+  };
+
+  const mergePending = (input: DispatchInput, at: number): PendingRounds => {
+    const merged = mergePendingRounds(pending.get(input.sessionId), input, at);
+    pending.set(input.sessionId, merged);
+    return merged;
+  };
+
+  const run = async (input: DispatchInput, options: DispatchOptions = {}): Promise<DispatchOutcome> => {
+    const at = now();
+    const bypass = options.bypassThrottle === true;
+    const trigger: RunRecord["trigger"] = options.trigger ?? (bypass ? "manual" : "auto");
+
+    if (!deps.config.enabled) {
+      deps.telemetry.append({ kind: "skipped", sessionId: input.sessionId, why: "disabled", trigger });
+      return { status: "skipped", why: "disabled", ownerPid: null };
+    }
+
+    // 必红自检没过就别再产出提案：评审器不可信时，继续派发只是在制造假结论
+    if (deps.selftestFailed?.() === true) {
+      deps.telemetry.append({ kind: "skipped", sessionId: input.sessionId, why: "selftest-failed", trigger });
+      log("[skill-evolve] 跳过派生：必红自检未通过（评审器不可信，流水线停用）");
+      return { status: "skipped", why: "selftest-failed", ownerPid: null };
+    }
+
+    if (!bypass) {
+      const last = lastDispatchAt.get(input.sessionId);
+      if (shouldDebounce(last, at, deps.config.idleMs)) {
+        const carried = mergePending(input, at);
+        deps.telemetry.append({
+          kind: "superseded",
+          sessionId: input.sessionId,
+          lastDispatchAt: last ?? 0,
+          idleMs: deps.config.idleMs,
+          rounds: carried.rounds,
+        });
+        log(`[skill-evolve] 去抖：并入待复盘区间（已累计 ${carried.rounds} 轮，静默窗口过后补一次）`);
+        return { status: "superseded", rounds: carried.rounds };
+      }
+      const used = dispatchCount.get(input.sessionId) ?? 0;
+      if (used >= deps.config.perSessionCap) {
+        deps.telemetry.append({ kind: "skipped", sessionId: input.sessionId, why: "cap", cap: deps.config.perSessionCap });
+        return { status: "skipped", why: "cap", ownerPid: null };
+      }
+    }
+
+    // 全局单飞（跨会话也成立）：已有复盘或督导在跑这一轮就不叠进程；放去抖 / 上限之后，那两条是「本轮不派」的既定语义
+    const occupant = guardBusy({ evolutionDir: deps.evolutionDir, sessionId: input.sessionId, telemetry: deps.telemetry, trigger, alive: deps.alive, log });
+    if (occupant) return { status: "skipped", why: "busy", ownerPid: occupant.pid };
+
+    const carried = pending.get(input.sessionId);
+    // 合并派发：本轮 + 之前被去抖挡下的所有轮次，覆盖起点取第一次被挡下的时刻
+    const skills = carried
+      ? [...carried.skills, ...input.skills.filter((name) => !carried.skills.includes(name))]
+      : [...input.skills];
+    const attributions = mergeAttributions(carried?.attributions, input.attributions);
+    const coverage = carried ? { rounds: carried.rounds + 1, since: carried.since } : undefined;
+
+    const runId = uniqueRunId(deps.evolutionDir, input.sessionId, at);
+    const runDir = path.join(deps.evolutionDir, "runs", runId);
+    const lock = await acquireLock({
+      evolutionDir: deps.evolutionDir,
+      owner: { pid: process.pid, ts: at, sessionId: input.sessionId },
+      maxRuntimeMs: deps.config.maxRuntimeMs,
+      log,
+      now: () => at,
+    });
+    if (!lock.ok) {
+      const why = lock.why === "error" ? "lock-error" : "lock";
+      deps.telemetry.append({
+        kind: "skipped",
+        sessionId: input.sessionId,
+        why,
+        ownerPid: lock.owner?.pid ?? null,
+        trigger,
+      });
+      log(`[skill-evolve] 跳过派生：锁不可用（owner pid ${lock.owner?.pid ?? "未知"}）`);
+      return { status: "skipped", why, ownerPid: lock.owner?.pid ?? null };
+    }
+    lockHeld = true;
+
+    try {
+      const indexFile = path.join(runDir, "00-session", "index.json");
+      const sessionFile = input.sessionFile ?? carried?.sessionFile;
+      let evidenceMode: RunRecord["evidenceMode"] = "telemetry-only";
+      if (sessionFile) {
+        const index = await writeSessionIndex({ sessionFile, outDir: path.dirname(indexFile), queue: deps.queue, log });
+        if (index) evidenceMode = "session+telemetry";
+      }
+
+      const record: RunRecord = {
+        runId,
+        status: "dispatched",
+        trigger,
+        sessionId: input.sessionId,
+        sessionHash: sessionHashOf(input.sessionId),
+        sessionFile: sessionFile ?? null,
+        evidenceMode,
+        dispatchedAt: at,
+        dispatchedAtIso: new Date(at).toISOString(),
+        pid: null,
+        cwd: deps.cwd,
+        skills,
+        coverage,
+        stages: [{ name: "dispatch", model: null, usage: null, ms: 0 }],
+        artifacts: evidenceMode === "session+telemetry" ? { "00-session/index.json": indexFile } : {},
+      };
+      await writeRunRecord(runDir, record, deps.queue);
+
+      const prompt = buildPrompt({
+        template: readPromptTemplateSync(deps.promptTemplatePath, log),
+        sessionFile,
+        // telemetry-only 时 00-session/index.json 根本没生成，别把不存在的路径写进 prompt
+        indexFile: evidenceMode === "session+telemetry" ? indexFile : undefined,
+        runDir,
+        sessionId: input.sessionId,
+        skills,
+        attributions,
+        dispatchedAt: at,
+        coverage,
+      });
+      const piBin = resolvePiBin(env);
+      const spawnFn: SpawnLike = deps.spawnFn ?? (spawn as unknown as SpawnLike);
+      const child = spawnDetached(spawnFn, piBin, ["-p", "--no-session", "-ns", prompt], {
+        cwd: deps.cwd,
+        env: { ...env, SKILL_EVOLVE_CHILD: "1" },
+        // stdout+stderr 落到 run 目录：子进程怎么死的，只有这份日志答得出来
+        logFile: path.join(runDir, CHILD_LOG),
+      });
+
+      record.pid = child.pid ?? null;
+      await writeRunRecord(runDir, record, deps.queue);
+      // 锁的 owner 换成子进程：主进程若先死，owner.pid 指向死进程会让下一个派发把还在跑的 run 当孤儿回收
+      writeOwnerSync(deps.evolutionDir, { pid: child.pid ?? process.pid, ts: at, sessionId: input.sessionId }, log);
+      deps.telemetry.append({ kind: "dispatched", sessionId: input.sessionId, runId, pid: record.pid, trigger, rounds: coverage?.rounds ?? 1 });
+      log(
+        `[skill-evolve] 已派生复盘：runId ${runId} pid ${record.pid ?? "未知"}（${piBin}，覆盖 ${coverage?.rounds ?? 1} 轮）`,
+      );
+
+      pending.delete(input.sessionId);
+      lastDispatchAt.set(input.sessionId, at);
+      dispatchCount.set(input.sessionId, (dispatchCount.get(input.sessionId) ?? 0) + 1);
+      watchRunChild(child, { runDir, queue: deps.queue, log, onExit: releaseOnce });
+      // 同一次派发再起一个独立督导：等 02-proposal.json → 另起评审进程 → 写 03-review.*
+      spawnReviewSupervisor({
+        runDir,
+        cwd: deps.cwd,
+        env,
+        reviewModel: deps.reviewModel?.() ?? "inherit",
+        spawnFn: deps.supervisorSpawnFn,
+        sessionId: input.sessionId, telemetry: deps.telemetry, ...(deps.alive ? { alive: deps.alive } : {}),
+        log,
+      });
+      return { status: "dispatched", run: { runId, runDir, pid: record.pid } };
+    } catch (error) {
+      log(`[skill-evolve] 派生失败：${String(error)}`);
+      await releaseOnce();
+      return { status: "skipped", why: "lock-error", ownerPid: null };
+    }
+  };
+
+  const flushPending = (): number => {
+    if (pending.size === 0) return 0;
+    const at = now();
+    let dispatched = 0;
+    for (const item of [...pending.values()]) {
+      let result: ShutdownResult = "failed";
+      try {
+        result = flushPendingSync(
+          item,
+          {
+            evolutionDir: deps.evolutionDir,
+            cwd: deps.cwd,
+            promptTemplatePath: deps.promptTemplatePath,
+            maxRuntimeMs: deps.config.maxRuntimeMs,
+            telemetry: deps.telemetry,
+            env,
+            spawnFn: deps.spawnFn ?? (spawn as unknown as SpawnLike),
+            ...(deps.reviewModel ? { reviewModel: deps.reviewModel() } : {}),
+            ...(deps.supervisorSpawnFn ? { supervisorSpawnFn: deps.supervisorSpawnFn } : {}), ...(deps.alive ? { alive: deps.alive } : {}),
+            log,
+          },
+          at,
+        );
+      } catch (error) {
+        // flushPendingSync 自己已 try/catch；这里再兜一层，退出路径不允许抛
+        log(`[skill-evolve] 退出补发失败：${String(error)}`);
+      }
+      if (result === "dispatched") {
+        dispatched += 1;
+        lastDispatchAt.set(item.sessionId, at);
+        dispatchCount.set(item.sessionId, (dispatchCount.get(item.sessionId) ?? 0) + 1);
+      }
+      // 退出是最后一次机会：无论成败都从这里清掉，避免 shutdown 被调用两次时重复派发
+      pending.delete(item.sessionId);
+    }
+    return dispatched;
+  };
+
+  return { dispatch: run, flushPending };
+}

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

@@ -0,0 +1,265 @@
+/**
+ * 采纳侧的胶水：扫「评审通过」的 run → 入队 → auto 自动应用 / approve 手动应用 → 人话输出。
+ *
+ * 为什么扫描在扩展进程：闸2 需要 withFileMutationQueue（只有 pi 运行时能给），
+ * 所以评审督导只写 03-review.json，真正写盘永远回到这里。主会话退出也不丢：
+ * 队列落在 `.pi/evolution/queue.json`，下次 session_start 接着采纳。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { applyRun, rejectRun, type ApplyDeps, type ApplyOutcome } from "./apply.ts";
+import { cleanupBackups } from "./apply-gates.ts";
+import { readProposalMeta } from "./apply-targets.ts";
+import { classifyChange } from "./classify-action.ts";
+import { captureGate0, saveGate0, type GitRunner } from "./gate0.ts";
+import { buildPrunePlan, renderPrunePlan } from "./prune-plan.ts";
+import { enqueue, findItem, markDone, readQueue, takePending, type QueueItem, type QueueStatus } from "./queue.ts";
+import { logLine } from "./logfile.ts";
+import { updateRunStatus } from "./runs.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+export interface ApplyToolsDeps {
+  evolutionDir: string;
+  cwd: string;
+  queue: MutationQueue;
+  now?: () => number;
+  log?: (msg: string) => void;
+  git: GitRunner;
+  loadDiagnostics: () => { path: string; message: string }[];
+  runMdCheck: (absPath: string) => { code: number; output: string };
+  commit?: ApplyDeps["commit"];
+}
+
+export interface ApplyTools {
+  /** session_start：闸0 快照 + 备份清理 + 扫队列并应用 auto 条 */
+  sessionStart(): void;
+  /** settle：评审可能刚写完，扫一遍（只应用 auto 条） */
+  settle(): void;
+  approve(runId: string, prune: boolean): Promise<string>;
+  /** 拒绝一条待批提案：只改队列与 run.json 状态，不动任何技能文件 */
+  reject(runId: string): Promise<string>;
+  queueText(): string;
+  /** 供测试与内部复用：返回实际应用成功的条数 */
+  autoApplyPending(): Promise<number>;
+  enqueueReady(): Promise<number>;
+}
+
+/** 只有评审通过（reviewed）的 run 才进队列；rejected / review_failed 一律不排 */
+const READY_STATUS = "reviewed";
+const MAX_SCAN = 50;
+
+function readText(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readRunJson(runDir: string): Record<string, unknown> | null {
+  const raw = readText(path.join(runDir, "run.json"));
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function stamp(ts: number): string {
+  return ts > 0 ? new Date(ts).toISOString() : "时间未知";
+}
+
+function renderOutcome(outcome: ApplyOutcome, item: QueueItem): string {
+  const head =
+    outcome.status === "applied"
+      ? `已采纳 ${item.runId}（${item.level} · ${item.skill}）`
+      : `采纳未完成 ${item.runId}：${outcome.status}`;
+  const lines = [head];
+  for (const gate of outcome.gates) {
+    lines.push(`  ${gate.ok ? "✔" : "✘"} ${gate.gate} ${gate.name} ${gate.ms}ms${gate.detail ? ` — ${gate.detail}` : ""}`);
+  }
+  if (outcome.wrote.length > 0) lines.push(`写入：${outcome.wrote.join("、")}`);
+  if (outcome.commit) lines.push(`commit：${outcome.commit}（docs(skill): …）`);
+  if (outcome.detail) lines.push(`说明：${outcome.detail}`);
+  if (outcome.status === "applied") lines.push("生效：未 reload，新会话生效（技能在 session_start 重新发现）");
+  if (outcome.status === "applied" && item.level === "approval") lines.push("提醒：approval 级不自动提交，请人工检查后 git commit");
+  if (outcome.status === "unauthorized_write") lines.push("告警：`.pi/skills` 在会话开始后被改动过，本次未写盘；证据见 06-verify.json");
+  return lines.join("\n");
+}
+
+export function createApplyTools(deps: ApplyToolsDeps): ApplyTools {
+  const now = deps.now ?? (() => Date.now());
+  // 默认只落盘（`.pi/evolution/logs/extension.log`）：TUI 默认零推送
+  const log = deps.log ?? ((msg: string) => logLine(deps.evolutionDir, msg));
+  const queueDeps = { evolutionDir: deps.evolutionDir, queue: deps.queue, now };
+
+  const targetsOf = (runDir: string, skill: string, type: string, fromDiff: readonly string[]): string[] => {
+    const known = readProposalMeta(runDir);
+    const head = type === "create" ? [`.pi/skills/${skill}/SKILL.md`] : [];
+    return [...new Set([...head, ...(known ? fromDiff : [])])];
+  };
+
+  const enqueueReady: ApplyTools["enqueueReady"] = async () => {
+    const runsDir = path.join(deps.evolutionDir, "runs");
+    let names: string[];
+    try {
+      names = fs.readdirSync(runsDir).slice(0, MAX_SCAN);
+    } catch {
+      return 0;
+    }
+    const known = new Set(readQueue(deps.evolutionDir).map((item) => item.runId));
+    let added = 0;
+    for (const name of names) {
+      if (known.has(name)) continue;
+      const runDir = path.join(runsDir, name);
+      const raw = readRunJson(runDir);
+      if (!raw || raw.status !== READY_STATUS) continue;
+      const meta = readProposalMeta(runDir);
+      if (!meta) continue;
+      const diffText = readText(path.join(runDir, meta.diffFile)) ?? "";
+      const graded = classifyChange({ diffText, proposalType: meta.type, skill: meta.skill });
+      if (graded.level === "forbidden") {
+        log(`[skill-evolve] ${name} 判 forbidden，不入队：${graded.reasons[0] ?? ""}`);
+        continue;
+      }
+      const result = await enqueue(queueDeps, {
+        runId: name,
+        level: graded.level,
+        skill: meta.skill,
+        targets: targetsOf(runDir, meta.skill, meta.type, graded.targets),
+        proposalType: meta.type,
+      });
+      if (result.supersededBy) log(`[skill-evolve] ${name} 被更早的 pending 顶掉（${result.supersededBy}）`);
+      else log(`[skill-evolve] ${name} 入队：${graded.level}（${graded.reasons[0] ?? ""}）`);
+      added += 1;
+    }
+    return added;
+  };
+
+  const writeDecision = async (runDir: string, item: QueueItem, outcome: ApplyOutcome): Promise<void> => {
+    const record = {
+      runId: item.runId,
+      level: item.level,
+      skill: item.skill,
+      approver: item.level === "auto" ? "auto" : "command",
+      status: outcome.status,
+      at: now(),
+      atIso: new Date(now()).toISOString(),
+      ...(outcome.detail ? { detail: outcome.detail } : {}),
+    };
+    const file = path.join(runDir, "04-decision.json");
+    await deps.queue(file, async () => {
+      await fs.promises.mkdir(runDir, { recursive: true });
+      await fs.promises.writeFile(file, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    });
+  };
+
+  const applyOne = async (item: QueueItem): Promise<ApplyOutcome> => {
+    const applyDeps: ApplyDeps = {
+      evolutionDir: deps.evolutionDir,
+      cwd: deps.cwd,
+      runId: item.runId,
+      queue: deps.queue,
+      now,
+      log,
+      git: deps.git,
+      loadDiagnostics: deps.loadDiagnostics,
+      runMdCheck: deps.runMdCheck,
+      ...(deps.commit ? { commit: deps.commit } : {}),
+    };
+    const outcome = await applyRun(item, applyDeps);
+    const status: QueueStatus =
+      outcome.status === "applied" ? "applied" : outcome.status === "rolled-back" ? "rolled-back" : "failed";
+    // 顺序不能换：先落决策记录，再改 run.json，最后改队列 / run 状态。
+    // 队列状态是外部可见的「终态标志」，进程若在中间被 kill，早写队列会留下
+    // 「已 applied 但读不到 04-decision.json」的空窗（approve.test.ts 的偶发 ENOENT 就是它）。
+    await writeDecision(path.join(deps.evolutionDir, "runs", item.runId), item, outcome);
+    await updateRunStatus(deps.evolutionDir, item.runId, outcome.status, deps.queue);
+    await markDone(queueDeps, item.runId, status, outcome.detail);
+    return outcome;
+  };
+
+  const autoApplyPending: ApplyTools["autoApplyPending"] = async () => {
+    let applied = 0;
+    for (const item of takePending(readQueue(deps.evolutionDir), "auto")) {
+      try {
+        const outcome = await applyOne(item);
+        if (outcome.status === "applied") applied += 1;
+        log(`[skill-evolve] auto 采纳 ${item.runId}：${outcome.status}${outcome.detail ? `（${outcome.detail}）` : ""}`);
+      } catch (error) {
+        // 单条失败不能拖垮整批：记 failed 后继续下一条
+        await markDone(queueDeps, item.runId, "failed", String(error));
+        log(`[skill-evolve] auto 采纳 ${item.runId} 异常：${String(error)}`);
+      }
+    }
+    return applied;
+  };
+
+  const scanAndApply = (): void => {
+    void enqueueReady()
+      .then(() => autoApplyPending())
+      .catch((error: unknown) => log(`[skill-evolve] 采纳扫描失败：${String(error)}`));
+  };
+
+  const sessionStart: ApplyTools["sessionStart"] = () => {
+    const time = now();
+    try {
+      cleanupBackups(deps.evolutionDir, time, log);
+    } catch (error) {
+      log(`[skill-evolve] 备份清理失败：${String(error)}`);
+    }
+    void saveGate0(deps.evolutionDir, captureGate0(deps.git, deps.cwd, time), deps.queue)
+      .then(() => enqueueReady())
+      .then(() => autoApplyPending())
+      .catch((error: unknown) => log(`[skill-evolve] 会话起点初始化失败：${String(error)}`));
+  };
+
+  const approve: ApplyTools["approve"] = async (runId, prune) => {
+    if (!runId) return "用法：/skill-evolve approve <runId> [--prune]";
+    const runDir = path.join(deps.evolutionDir, "runs", runId);
+    if (prune) {
+      const plan = buildPrunePlan(runDir, deps.cwd);
+      return plan ? renderPrunePlan(plan) : `找不到 ${runId} 的提案（02-proposal.json），无法生成删除清单`;
+    }
+    const item = findItem(readQueue(deps.evolutionDir), runId);
+    if (!item) return `队列里没有 ${runId}：先 /skill-evolve queue 看有哪些，或等评审通过后自动入队`;
+    if (item.status === "applied") return `${runId} 已经应用过（${item.detail ?? "无详情"}），无需重复操作`;
+    if (item.status !== "pending") return `${runId} 当前状态是 ${item.status}，只有 pending 能采纳`;
+    if (item.level === "forbidden") return `${runId} 被判 forbidden（删技能 / 改语义字段 / 路径越界），插件不执行`;
+    const outcome = await applyOne(item);
+    return renderOutcome(outcome, item);
+  };
+
+  const reject: ApplyTools["reject"] = async (runId) => {
+    if (!runId) return "用法：/skill-evolve approve <runId>（拒绝入口在 Web 面板的待审批页）";
+    const item = findItem(readQueue(deps.evolutionDir), runId);
+    if (!item) return `队列里没有 ${runId}：先 /skill-evolve queue 看有哪些，或等评审通过后自动入队`;
+    const outcome = await rejectRun(item, queueDeps);
+    if (!outcome.ok) return `拒绝未完成 ${runId}：${outcome.detail}`;
+    log(`[skill-evolve] 拒绝 ${item.runId}（${item.level} · ${item.skill}）：只改队列与 run 状态，未动技能文件`);
+    const tail = outcome.detail ? `（${outcome.detail}）` : "";
+    return `已拒绝 ${runId}（${item.level} · ${item.skill}）${tail}：技能文件未改动`;
+  };
+
+  const queueText: ApplyTools["queueText"] = () => {
+    const items = readQueue(deps.evolutionDir);
+    if (items.length === 0) return `采纳队列为空：${path.join(deps.evolutionDir, "queue.json")}（评审通过后自动入队）`;
+    const lines = [`采纳队列：${path.join(deps.evolutionDir, "queue.json")}`];
+    const groups: QueueStatus[] = ["pending", "applied", "rolled-back", "failed", "superseded", "rejected"];
+    for (const status of groups) {
+      const group = items.filter((item) => item.status === status).sort((a, b) => b.createdAt - a.createdAt);
+      if (group.length === 0) continue;
+      lines.push(`${status} ${group.length} 条`);
+      for (const item of group.slice(0, 5)) {
+        const detail = item.detail ? ` · ${item.detail}` : "";
+        lines.push(`  · ${item.runId}  ${item.level}  ${item.skill}  ${stamp(item.createdAt)}${detail}`);
+        if (status === "pending") lines.push(`    targets：${item.targets.join("、")}`);
+      }
+    }
+    lines.push("auto 级在 session_start / settle 自动执行；approval 用 /skill-evolve approve <runId> 或 Web 面板待审批页");
+    return lines.join("\n");
+  };
+
+  return { sessionStart, settle: scanAndApply, approve, reject, queueText, autoApplyPending, enqueueReady };
+}

package/extensions/skill-evolve/lib/evolution-model.ts

@@ -0,0 +1,72 @@
+/**
+ * 模型配置 + 必红自检的「动作层」：把 `model-config.ts`（读写配置）与 `selftest.ts`（跑自检）
+ * 拼成 evolution 与命令能直接用的三件事——取评审模型、改模型、跑自检。
+ *
+ * 放这里而不是塞进 evolution.ts：那边已经贴着 300 行闸门，而这一层与采集/门禁无关。
+ */
+import { loadModelConfig, resolveModel, saveModelSpec, type ModelConfig, type ModelKind } from "./model-config.ts";
+import { readSelftestReport, renderSelftestReport, runSelftest, type SelftestReport } from "./selftest.ts";
+import type { ReviewSpawn } from "./review-run.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+export interface ModelToolsDeps {
+  evolutionDir: string;
+  cwd: string;
+  queue: MutationQueue;
+  log: (msg: string) => void;
+  now?: () => number;
+  env?: NodeJS.ProcessEnv;
+  /** 主会话当前模型：inherit 时用它（拿不到就仍返回 inherit，让 pi 自己挑默认模型） */
+  hostModel?: () => { provider?: string; id?: string } | undefined;
+  reviewSpawnFn?: ReviewSpawn;
+  selftestTimeoutMs?: number;
+}
+
+export interface ModelTools {
+  config(): ModelConfig;
+  /** 评审该用哪个模型：`provider/id` 或 "inherit" */
+  reviewModel(): string;
+  setModel(kind: ModelKind, spec: string): Promise<string>;
+  /** `/skill-evolve selftest`：跑三个坏样本并回显 */
+  selftestText(): Promise<string>;
+  /** 派发门禁用：最近一次自检明确没过 → true（没跑过不算没过） */
+  selftestFailed(): boolean;
+  lastSelftest(): SelftestReport | undefined;
+}
+
+export function createModelTools(deps: ModelToolsDeps): ModelTools {
+  const log = deps.log;
+  const config = (): ModelConfig => loadModelConfig(deps.evolutionDir);
+  const reviewModel = (): string => resolveModel("review", config(), { model: deps.hostModel?.() });
+
+  return {
+    config,
+    reviewModel,
+    async setModel(kind: ModelKind, spec: string): Promise<string> {
+      const next = await saveModelSpec(deps.evolutionDir, kind, spec, deps.queue);
+      const label = kind === "propose" ? "提案" : "评审";
+      const warn = next.propose === next.review && next.review !== "inherit" ? "（提案与评审是同一个模型，独立性天然有限）" : "";
+      return `${label}模型已设为 ${next[kind]}${warn}（下次派发生效）`;
+    },
+    async selftestText(): Promise<string> {
+      const model = reviewModel();
+      const report = await runSelftest({
+        evolutionDir: deps.evolutionDir,
+        cwd: deps.cwd,
+        ...(model !== "inherit" ? { model } : {}),
+        ...(deps.env ? { env: deps.env } : {}),
+        ...(deps.reviewSpawnFn ? { spawnFn: deps.reviewSpawnFn } : {}),
+        ...(deps.now ? { now: deps.now } : {}),
+        ...(deps.selftestTimeoutMs ? { timeoutMs: deps.selftestTimeoutMs } : {}),
+        log,
+      });
+      return renderSelftestReport(report);
+    },
+    selftestFailed(): boolean {
+      return readSelftestReport(deps.evolutionDir)?.passed === false;
+    },
+    lastSelftest(): SelftestReport | undefined {
+      return readSelftestReport(deps.evolutionDir);
+    },
+  };
+}