pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,172 @@
+/**
+ * 趋势指标：把遥测事件按 ISO 周聚合，落 `.pi/evolution/metrics.jsonl`（已 gitignore）。
+ *
+ * 两条纪律：
+ * 1. 只做聚合，不做解释——归因结论在 01-findings.json / 周报里；
+ * 2. 除零一律返回 0（`ratio`），指标里出现 NaN 比没指标更糟。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ratio, type MutationQueue, type TelemetryEvent } from "./telemetry.ts";
+
+/** 归因分布只统计 A~G 七类（semantic 是「判不动」的兜底，不算一类原因） */
+export const ATTRIBUTION_KEYS = ["A", "B", "C", "D", "E", "F", "G"] as const;
+export type AttributionKey = (typeof ATTRIBUTION_KEYS)[number];
+
+export interface MetricsRow {
+  /** 落盘时刻（毫秒） */
+  ts: number;
+  /** ISO 周，如 `2026-W45` */
+  week: string;
+  advertised: number;
+  loaded: number;
+  attemptedFailed: number;
+  /** loaded / advertised */
+  loadRate: number;
+  conflicts: { p0: number; p1: number };
+  proposed: number;
+  applied: number;
+  rolledBack: number;
+  attribution: Record<AttributionKey, number>;
+  /** 单 run 行才带；按周汇总行省略（去重键：week + runId） */
+  runId?: string;
+}
+
+/** 指标要看的 run 侧面：只取状态与派发时刻，其余字段与趋势无关 */
+export interface MetricsRun {
+  runId: string;
+  status: string;
+  dispatchedAt: number | null;
+}
+
+/** 走到过提案阶段的 run（用来算采纳率的分母） */
+const PROPOSED_STATUSES = new Set(["proposed", "reviewed", "rejected", "review_failed", "applied", "rolled-back", "unauthorized_write", "failed"]);
+
+/** ISO-8601 周编号：`2026-W45`。用 UTC 计算，避免本地时区跨年把同一周拆成两周 */
+export function isoWeek(ts: number): string {
+  const date = new Date(ts);
+  const thursday = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const weekday = thursday.getUTCDay() || 7;
+  thursday.setUTCDate(thursday.getUTCDate() + 4 - weekday);
+  const yearStart = Date.UTC(thursday.getUTCFullYear(), 0, 1);
+  const week = Math.ceil(((thursday.getTime() - yearStart) / 86_400_000 + 1) / 7);
+  return `${thursday.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function emptyRow(week: string, ts: number): MetricsRow {
+  return {
+    ts,
+    week,
+    advertised: 0,
+    loaded: 0,
+    attemptedFailed: 0,
+    loadRate: 0,
+    conflicts: { p0: 0, p1: 0 },
+    proposed: 0,
+    applied: 0,
+    rolledBack: 0,
+    attribution: { A: 0, B: 0, C: 0, D: 0, E: 0, F: 0, G: 0 },
+  };
+}
+
+function skillsOf(event: TelemetryEvent): { name: string; disabled: boolean }[] {
+  const raw = Array.isArray(event.skills) ? (event.skills as { name?: unknown; disabled?: unknown }[]) : [];
+  return raw
+    .filter((skill) => typeof skill?.name === "string")
+    .map((skill) => ({ name: String(skill.name), disabled: skill.disabled === true }));
+}
+
+/**
+ * 按 ISO 周聚合。`runs` 可选：提案数 / 采纳数 / 回滚数只有 run.json 知道（复盘子进程不写遥测）。
+ */
+export function buildMetrics(events: readonly TelemetryEvent[], now: number, runs: readonly MetricsRun[] = []): MetricsRow[] {
+  const weeks = new Map<string, MetricsRow>();
+  const rowOf = (ts: number): MetricsRow => {
+    const week = isoWeek(ts);
+    let row = weeks.get(week);
+    if (!row) {
+      row = emptyRow(week, now);
+      weeks.set(week, row);
+    }
+    return row;
+  };
+
+  for (const event of events) {
+    if (typeof event.ts !== "number" || !Number.isFinite(event.ts)) continue;
+    const row = rowOf(event.ts);
+    if (event.kind === "advertised") {
+      row.advertised += skillsOf(event).filter((skill) => !skill.disabled).length;
+    } else if (event.kind === "loaded") {
+      row.loaded += 1;
+    } else if (event.kind === "failed") {
+      row.attemptedFailed += 1;
+    } else if (event.kind === "conflict") {
+      if (event.level === "P0") row.conflicts.p0 += 1;
+      else if (event.level === "P1") row.conflicts.p1 += 1;
+    } else if (event.kind === "attributed") {
+      const category = typeof event.category === "string" ? event.category : "";
+      if ((ATTRIBUTION_KEYS as readonly string[]).includes(category)) {
+        row.attribution[category as AttributionKey] += 1;
+      }
+    }
+  }
+
+  for (const run of runs) {
+    if (run.dispatchedAt === null) continue;
+    const row = rowOf(run.dispatchedAt);
+    if (PROPOSED_STATUSES.has(run.status)) row.proposed += 1;
+    if (run.status === "applied") row.applied += 1;
+    if (run.status === "rolled-back") row.rolledBack += 1;
+  }
+
+  for (const row of weeks.values()) row.loadRate = ratio(row.loaded, row.advertised);
+  return [...weeks.values()].sort((a, b) => a.week.localeCompare(b.week));
+}
+
+export function metricsFile(evolutionDir: string): string {
+  return path.join(evolutionDir, "metrics.jsonl");
+}
+
+/** 去重键：同一周的汇总行只写一次；单 run 行按 week + runId 区分 */
+function keyOf(row: MetricsRow): string {
+  return `${row.week}|${row.runId ?? ""}`;
+}
+
+export function readMetrics(evolutionDir: string): MetricsRow[] {
+  let text: string;
+  try {
+    text = fs.readFileSync(metricsFile(evolutionDir), "utf8");
+  } catch {
+    return [];
+  }
+  const rows: MetricsRow[] = [];
+  for (const line of text.split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      const parsed = JSON.parse(line) as MetricsRow;
+      if (typeof parsed.week === "string") rows.push(parsed);
+    } catch {
+      // 坏行跳过：旁路数据不值得让整份趋势报错
+    }
+  }
+  return rows;
+}
+
+/** 追加一行；同 week（+runId）已有则跳过，返回是否真的写入 */
+export async function appendMetrics(evolutionDir: string, row: MetricsRow, queue: MutationQueue): Promise<boolean> {
+  const file = metricsFile(evolutionDir);
+  const key = keyOf(row);
+  if (readMetrics(evolutionDir).some((existing) => keyOf(existing) === key)) return false;
+  await queue(file, async () => {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.appendFile(file, `${JSON.stringify(row)}\n`, "utf8");
+  });
+  return true;
+}
+
+/** 回滚率 = rolledBack / applied；没有采纳样本时为 0（「样本不足」由调用方判断） */
+export function rollbackRate(rows: readonly MetricsRow[]): number {
+  const applied = rows.reduce((sum, row) => sum + row.applied, 0);
+  const rolledBack = rows.reduce((sum, row) => sum + row.rolledBack, 0);
+  return ratio(rolledBack, applied);
+}

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

@@ -0,0 +1,95 @@
+/**
+ * 模型配置（设计稿 12.5）：`propose.model` / `review.model` 两个键，值 `"inherit"` 或 `provider/model`。
+ *
+ * `inherit` = 跟随主会话当前模型（`ctx.model`）。默认两边都是 inherit —— 用户不配置也能跑，
+ * 但同模型自评的独立性天然有限，所以评审产物里必须写清 `sameModel`。
+ */
+import * as fs from "node:fs";
+import { configFile, readRawConfig } from "./config.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+export const INHERIT = "inherit";
+export type ModelKind = "propose" | "review";
+
+export interface ModelConfig {
+  propose: string;
+  review: string;
+}
+
+export const DEFAULT_MODEL_CONFIG: Readonly<ModelConfig> = Object.freeze({ propose: INHERIT, review: INHERIT });
+
+/** provider/id，id 允许带 `:thinking` 后缀（pi 的 --model 语法） */
+const SPEC = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+/** 非法值一律退回 inherit：配置错误不该让整条流水线停摆 */
+export function normalizeModelSpec(value: unknown): string {
+  return typeof value === "string" && SPEC.test(value.trim()) ? value.trim() : INHERIT;
+}
+
+/** 从 config.json 的原始对象里取模型配置（`{propose:{model},review:{model}}`） */
+export function readModelConfig(raw: unknown): ModelConfig {
+  const input = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+  const pick = (key: ModelKind): string => {
+    const node = input[key];
+    if (!node || typeof node !== "object") return INHERIT;
+    return normalizeModelSpec((node as Record<string, unknown>).model);
+  };
+  return { propose: pick("propose"), review: pick("review") };
+}
+
+export function loadModelConfig(evolutionDir: string): ModelConfig {
+  return readModelConfig(readRawConfig(evolutionDir));
+}
+
+export interface ModelHost {
+  model?: { provider?: string; id?: string };
+}
+
+/** inherit → 主会话当前的 `provider/id`；主会话没有模型时仍返回 inherit（调用方不传 --model） */
+export function resolveModel(kind: ModelKind, config: ModelConfig, host: ModelHost): string {
+  const spec = config[kind] ?? INHERIT;
+  if (spec !== INHERIT) return spec;
+  const provider = host.model?.provider;
+  const id = host.model?.id;
+  return provider && id ? `${provider}/${id}` : INHERIT;
+}
+
+/** `/skill-evolve config` 的选择项：第一项固定是「跟随主会话」 */
+export function modelChoices(models: readonly { provider?: string; id?: string }[]): string[] {
+  const choices = [`跟随主会话（${INHERIT}）`];
+  for (const model of models) {
+    if (model.provider && model.id) choices.push(`${model.provider}/${model.id}`);
+  }
+  return choices;
+}
+
+/** 把选择项还原成配置值 */
+export function specFromChoice(choice: string): string {
+  return choice.startsWith("跟随主会话") ? INHERIT : normalizeModelSpec(choice);
+}
+
+/** 写回一个键：只改 `propose.model` / `review.model`，其余字段原样保留 */
+export async function saveModelSpec(
+  evolutionDir: string,
+  kind: ModelKind,
+  spec: string,
+  queue: MutationQueue,
+): Promise<ModelConfig> {
+  const raw = readRawConfig(evolutionDir);
+  const next = readModelConfig({ ...raw, [kind]: { ...(raw[kind] as object | undefined), model: normalizeModelSpec(spec) } });
+  const merged = {
+    ...raw,
+    propose: { ...(raw.propose as object | undefined), model: next.propose },
+    review: { ...(raw.review as object | undefined), model: next.review },
+  };
+  const file = configFile(evolutionDir);
+  await queue(file, async () => {
+    await fs.promises.mkdir(evolutionDir, { recursive: true });
+    await fs.promises.writeFile(file, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  });
+  return next;
+}
+
+export function describeModelConfig(config: ModelConfig): string {
+  return `提案模型 ${config.propose} · 评审模型 ${config.review}（${INHERIT} = 跟随主会话）`;
+}

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

@@ -0,0 +1,132 @@
+/**
+ * 失败 / 待批 / 自动采纳的会话送达（设计稿 14.1「会话内可见」的补丁）。
+ *
+ * 为什么必须有：用户从飞书进来时没有 TUI，widget 与状态栏一眼都看不到，唯一能看见的是会话消息。
+ * 复盘子进程悄悄死掉、评审悄悄通过等人批、auto 悄悄改了技能 —— 这三件事不写进会话，
+ * 就等于「静默失败」（见 AGENTS.md 的个人约定第 8 条）。
+ *
+ * 两条纪律：
+ * 1. 一律 `pi.sendMessage`（CustomMessage，不触发新回合），绝不用 `sendUserMessage`
+ *    —— 那会让 agent 为一条通知再跑一整轮，烧 token 还打断用户；
+ * 2. 同一 run 的同一类事件只发一次：判据落 `runs/<runId>/notified.json`，跨进程重启也认。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readQueue } from "./queue.ts";
+import { listRuns } from "./runs.ts";
+import { readRunError, type StaleReason } from "./stale.ts";
+
+export type NotifyKind = "stale" | "pending-approval" | "auto-applied";
+
+export interface NotifyEvent {
+  runId: string;
+  kind: NotifyKind;
+  /** 直接交给 pi.sendMessage 的正文：最多两行，不带 diff */
+  text: string;
+}
+
+export const NOTIFIED_FILE = "notified.json";
+/** 日志末行截断长度：会话消息要短，长尾巴进 run-error.json 看 */
+const TAIL_CHARS = 120;
+
+export interface NotifyDeps {
+  evolutionDir: string;
+  now?: number;
+  /** 生产传 `text => pi.sendMessage(...)`；拿不到（老版本 / 无 UI）就不传，只写日志 */
+  send?: (text: string) => void;
+  log?: (msg: string) => void;
+}
+
+const REASON_LABEL: Record<StaleReason, string> = { "child-exited": "子进程已退出", timeout: "超时" };
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function readNotified(runDir: string): NotifyKind[] {
+  const raw = readJson<{ kinds?: unknown }>(path.join(runDir, NOTIFIED_FILE));
+  const kinds = Array.isArray(raw?.kinds) ? raw.kinds : [];
+  return kinds.filter((kind): kind is NotifyKind => kind === "stale" || kind === "pending-approval" || kind === "auto-applied");
+}
+
+function clip(text: string): string {
+  const trimmed = text.trim();
+  return trimmed.length > TAIL_CHARS ? `${trimmed.slice(0, TAIL_CHARS)}…` : trimmed;
+}
+
+/** 三类事件的判定全部只看「已落盘的事实」：队列状态 + run.json 状态，不猜中间态 */
+export function collectNotifications(evolutionDir: string): NotifyEvent[] {
+  const events: NotifyEvent[] = [];
+  const runs = listRuns(evolutionDir, 50);
+  const runIds = new Set(runs.map((run) => run.runId));
+  for (const run of runs) {
+    if (run.status !== "stale") continue;
+    const error = readRunError(path.join(evolutionDir, "runs", run.runId));
+    const reason = error?.reason ?? "child-exited";
+    const tail = error && error.childLogTail.length > 0 ? clip(error.childLogTail[error.childLogTail.length - 1]!) : "";
+    events.push({
+      runId: run.runId,
+      kind: "stale",
+      text: `技能复盘失败：${run.runId}（${REASON_LABEL[reason]}）\n日志末行：${tail.length > 0 ? tail : "（子进程没留下输出）"}`,
+    });
+  }
+  for (const item of readQueue(evolutionDir)) {
+    // 队列里没有对应 run 目录的条目（手工塞的）不推送：没有证据就没必要打扰用户
+    if (!runIds.has(item.runId)) continue;
+    if (item.status === "pending" && item.level === "approval") {
+      events.push({
+        runId: item.runId,
+        kind: "pending-approval",
+        text: `待批：${item.runId} 改动 ${item.skill || "（未知技能）"}\n/skill-evolve approve ${item.runId}`,
+      });
+    } else if (item.status === "applied" && item.level === "auto") {
+      events.push({
+        runId: item.runId,
+        kind: "auto-applied",
+        text: `已自动采纳：${item.runId}（${item.skill || "未知技能"}）`,
+      });
+    }
+  }
+  return events;
+}
+
+function writeNotified(runDir: string, kinds: NotifyKind[], at: number, log?: (msg: string) => void): void {
+  try {
+    fs.mkdirSync(runDir, { recursive: true });
+    fs.writeFileSync(path.join(runDir, NOTIFIED_FILE), `${JSON.stringify({ kinds, at }, null, 2)}\n`, "utf8");
+  } catch (error) {
+    // 写不进去只会导致下次重复推送，不该把刷新流程搞挂
+    log?.(`[skill-evolve] 记 notified.json 失败（${runDir}）：${String(error)}`);
+  }
+}
+
+/**
+ * 发一遍「还没发过」的事件。返回本次真的发出去的条目（单测靠它断言去重）。
+ * `send` 抛错时**不**记 notified：下一轮还能重试，丢通知比重复一次更糟。
+ */
+export function deliverNotifications(deps: NotifyDeps): NotifyEvent[] {
+  const delivered: NotifyEvent[] = [];
+  for (const event of collectNotifications(deps.evolutionDir)) {
+    const runDir = path.join(deps.evolutionDir, "runs", event.runId);
+    const known = readNotified(runDir);
+    if (known.includes(event.kind)) continue;
+    if (deps.send) {
+      try {
+        deps.send(event.text);
+      } catch (error) {
+        deps.log?.(`[skill-evolve] 会话消息发送失败（${event.runId}）：${String(error)}`);
+        continue;
+      }
+    } else {
+      // 无 UI / 老版本 pi：降级成日志，行为与「发出去了」等价（不再重试，免得刷日志）
+      deps.log?.(`[skill-evolve] ${event.text.replace(/\n/g, " ｜ ")}`);
+    }
+    writeNotified(runDir, [...known, event.kind], deps.now ?? Date.now(), deps.log);
+    delivered.push(event);
+  }
+  return delivered;
+}

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

@@ -0,0 +1,174 @@
+/**
+ * 面板层（设计稿 14.1 的前三层）：实时 widget / 状态栏 / `/tree` 条目。
+ *
+ * 三条纪律：
+ * 1. 没数据就不占位——widget 返回 null 由调用方清空，不显示「0」这种噪音；
+ * 2. 状态栏只显示最紧急的一件事，其余一律不挤进去；
+ * 3. 这里只读盘算数值，不建定时器、不写文件（刷新时机由 index.ts 决定）。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isPidAlive } from "./lock.ts";
+import { readQueue } from "./queue.ts";
+import { listRuns } from "./runs.ts";
+import { classifyStale, type StaleDeps } from "./stale.ts";
+
+/** 回滚率告警线：设计稿 14.2 定的 5%，样本少于 5 次不下结论 */
+export const ROLLBACK_ALERT = 0.05;
+export const MIN_APPLY_SAMPLES = 5;
+
+/** 进行中的「复盘」：派发出去还没出评审结论的那些 run */
+const IN_FLIGHT = new Set(["dispatched", "analyzed", "proposed", "review_failed"]);
+
+export interface PanelState {
+  reviewing: number;
+  /** 已判定卡死的 run 数（run.json status=stale）：它在状态栏/ widget 上压过「待批」 */
+  staleCount: number;
+  pendingApprovals: number;
+  lastAppliedAt: number | null;
+  rollbackRate: number;
+  appliedSamples: number;
+}
+
+function fileText(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** 采纳时刻取 04-decision.json 的 at；读不到才退回入队时刻（宁可偏早，也不编一个时间） */
+function appliedAtOf(evolutionDir: string, runId: string, fallback: number): number {
+  const raw = fileText(path.join(evolutionDir, "runs", runId, "04-decision.json"));
+  if (raw === null) return fallback;
+  try {
+    const at = (JSON.parse(raw) as { at?: unknown }).at;
+    return typeof at === "number" && Number.isFinite(at) ? at : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function collectPanelState(input: {
+  evolutionDir: string;
+  now?: number;
+  /** 单 run 上限（来自配置）：pid 还活着但跑太久也算卡死 */
+  maxRuntimeMs?: number;
+  /** pid 存活判定，单测注入（默认 kill(pid,0)） */
+  alive?: (pid: number) => boolean;
+}): PanelState {
+  const queue = readQueue(input.evolutionDir);
+  const runs = listRuns(input.evolutionDir, 50);
+  const now = input.now ?? Date.now();
+  const staleDeps: StaleDeps = {};
+  if (input.maxRuntimeMs !== undefined) staleDeps.maxRuntimeMs = input.maxRuntimeMs;
+  if (input.alive !== undefined) staleDeps.alive = input.alive;
+  const aliveOf = input.alive ?? isPidAlive;
+  const applied = queue.filter((item) => item.status === "applied");
+  const rolledBack = queue.filter((item) => item.status === "rolled-back").length;
+  const lastApplied = applied.reduce<{ at: number } | null>((best, item) => {
+    const at = appliedAtOf(input.evolutionDir, item.runId, item.createdAt);
+    return best === null || at > best.at ? { at } : best;
+  }, null);
+  return {
+    // 只数活着的：子进程死掉的 run 不该继续挂着「复盘 N」，否则面板永远在骗人。
+    // dispatched 保留宽限期（刚派发就判死会误报）；analyzed / proposed 已经是「结论写完了」，
+    // 进程退出属正常 —— 只有督导还活着（评审中）才算「复盘」，否则 8 条做完的 would-be 复盘
+    // 会永远挂在面板头上（2026-11-08 真事：报「复盘中 8」，实际一个进程都没在跑）。
+    reviewing: runs.filter((run) => {
+      if (!IN_FLIGHT.has(run.status)) return false;
+      if (classifyStale(run, now, staleDeps).stale) return false;
+      if (run.status === "dispatched") return true;
+      return (run.pid !== null && aliveOf(run.pid)) || (run.supervisorPid !== null && aliveOf(run.supervisorPid));
+    }).length,
+    // 已经落成 stale 的 + 判据命中但还没落盘的都要算：只数 run.json 里的 status，会让
+    // 「网页说卡死 3、实际列表 4 条」这种自相矛盾的数字漏出去（web 面板只读，不在那里补写盘）
+    staleCount: runs.filter((run) => run.status === "stale" || classifyStale(run, now, staleDeps).stale).length,
+    pendingApprovals: queue.filter((item) => item.status === "pending" && item.level === "approval").length,
+    lastAppliedAt: lastApplied?.at ?? null,
+    rollbackRate: applied.length + rolledBack > 0 ? rolledBack / (applied.length + rolledBack) : 0,
+    appliedSamples: applied.length + rolledBack,
+  };
+}
+
+/** `MM-DD`：面板只有一格宽，不写年份 */
+export function shortDate(ts: number): string {
+  const date = new Date(ts);
+  return `${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+
+/** widget 内容；全零返回 null（调用方用 undefined 清空，不留一行「复盘 0 / 待批 0」） */
+export function panelWidget(state: PanelState): string[] | null {
+  const parts: string[] = [];
+  if (state.staleCount > 0) parts.push(`复盘失败 ${state.staleCount}`);
+  if (state.reviewing > 0) parts.push(`复盘 ${state.reviewing}`);
+  if (state.pendingApprovals > 0) parts.push(`待批 ${state.pendingApprovals}`);
+  if (state.lastAppliedAt !== null) parts.push(`上次采纳 ${shortDate(state.lastAppliedAt)}`);
+  return parts.length > 0 ? [parts.join(" / ")] : null;
+}
+
+/** 状态栏：只放最紧急的一件（失败 > 待批 > 回滚率告警），都没有就清空 */
+export function statusLine(state: PanelState): string | null {
+  if (state.staleCount > 0) return `复盘失败 ${state.staleCount}`;
+  if (state.pendingApprovals > 0) return `待批 ${state.pendingApprovals}`;
+  if (state.appliedSamples >= MIN_APPLY_SAMPLES && state.rollbackRate > ROLLBACK_ALERT) {
+    const percent = (state.rollbackRate * 100).toFixed(0);
+    return `回滚率 ${percent}% 超 5%，建议关 auto`;
+  }
+  return null;
+}
+
+/** `/tree` 条目的展示行（数据由 pi.appendEntry 落进会话，不参与 LLM 上下文） */
+export interface PanelEntry {
+  kind: "dispatched" | "reviewed" | "applied" | "rolled-back" | "stale";
+  runId: string;
+  detail?: string;
+  at: number;
+}
+
+const ENTRY_LABEL: Record<PanelEntry["kind"], string> = {
+  dispatched: "派发复盘",
+  reviewed: "评审结论",
+  applied: "采纳",
+  "rolled-back": "回滚",
+  stale: "卡死",
+};
+
+export function entryLines(entry: PanelEntry): string[] {
+  const stamp = shortDate(entry.at);
+  const detail = entry.detail ? ` · ${entry.detail}` : "";
+  return [`[skill-evolve] ${ENTRY_LABEL[entry.kind]} ${entry.runId} · ${stamp}${detail}`];
+}
+
+/** 状态变迁 → `/tree` 条目：只认「评审结论 / 采纳 / 回滚」，派发由调用方单独记（它先于 run.json 出现） */
+const STATUS_ENTRY: Record<string, PanelEntry["kind"] | undefined> = {
+  reviewed: "reviewed",
+  rejected: "reviewed",
+  review_failed: "reviewed",
+  applied: "applied",
+  "rolled-back": "rolled-back",
+  stale: "stale",
+};
+
+/**
+ * 把 run 的状态与上次见到的比，产出新条目。`seen` 会被就地更新：
+ * 调用方每次刷新传同一份 Map，就能保证一条状态只发一次条目（含重启后的第一轮「补记」）。
+ */
+export function statusEntries(
+  runs: readonly { runId: string; status: string }[],
+  seen: Map<string, string>,
+  now: number,
+): PanelEntry[] {
+  const entries: PanelEntry[] = [];
+  for (const run of runs) {
+    const previous = seen.get(run.runId);
+    if (previous === run.status) continue;
+    seen.set(run.runId, run.status);
+    const kind = STATUS_ENTRY[run.status];
+    if (!kind) continue;
+    const detail = run.status === kind ? undefined : run.status;
+    entries.push({ kind, runId: run.runId, at: now, ...(detail ? { detail } : {}) });
+  }
+  return entries;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 去抖期间把新一轮并进「待复盘区间」：轮数累加、技能去重、起点保留第一次被挡下的时刻。
+ *
+ * 纯函数，单独放一个文件让 dispatch.ts 守住 300 行闸门，也便于直接单测合并语义。
+ */
+import { mergeAttributions, type Attribution } from "./attribution.ts";
+import type { PendingRounds } from "./shutdown-dispatch.ts";
+
+export interface PendingInput {
+  sessionId: string;
+  skills: string[];
+  sessionFile?: string;
+  attributions?: Attribution[];
+}
+
+export function mergePendingRounds(carried: PendingRounds | undefined, input: PendingInput, at: number): PendingRounds {
+  if (!carried) {
+    return {
+      sessionId: input.sessionId,
+      since: at,
+      rounds: 1,
+      skills: [...input.skills],
+      sessionFile: input.sessionFile,
+      attributions: mergeAttributions(undefined, input.attributions),
+    };
+  }
+  return {
+    ...carried,
+    rounds: carried.rounds + 1,
+    skills: [...carried.skills, ...input.skills.filter((name) => !carried.skills.includes(name))],
+    sessionFile: input.sessionFile ?? carried.sessionFile,
+    attributions: mergeAttributions(carried.attributions, input.attributions),
+  };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 生产环境的子进程封装：git 摘要、md-check 复验、auto 级的单独 commit、候选技能的引用面扫描。
+ *
+ * 全部同步（spawnSync）：采纳是人触发的短路径，阻塞一两百毫秒可以接受；
+ * 用异步反而会拉宽「写盘成功但 commit 还没跑」的窗口。
+ * 单测不 import 本文件 —— 闸门里的 git / md-check / commit 都是注入点。
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { GitRunner } from "./gate0.ts";
+import type { QueueItem } from "./queue.ts";
+import type { ReferenceScan } from "./weekly.ts";
+
+export function createGitRunner(): GitRunner {
+  return (args, cwd) => {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return { code: result.status ?? 1, out: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+  };
+}
+
+export function createMdCheckRunner(cwd: string): (absPath: string) => { code: number; output: string } {
+  const script = path.join(cwd, ".pi", "skills", "md-check", "scripts", "check_md.py");
+  return (absPath) => {
+    const result = spawnSync("python3", [script, absPath], { cwd, encoding: "utf8" });
+    return { code: result.status ?? 1, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+  };
+}
+
+/** auto 级成功后单独一条 `docs(skill): ...`；失败由调用方回滚该条 */
+export function createCommitRunner(cwd: string): (item: QueueItem) => { ok: boolean; hash?: string; detail?: string } {
+  return (item) => {
+    const add = spawnSync("git", ["add", "--", ...item.targets], { cwd, encoding: "utf8" });
+    if ((add.status ?? 1) !== 0) return { ok: false, detail: `git add 失败：${(add.stderr ?? "").trim()}` };
+    const message = `docs(skill): ${item.skill} ${item.proposalType ?? "improve"}（${item.runId}）`;
+    const commit = spawnSync("git", ["commit", "-m", message, "--", ...item.targets], { cwd, encoding: "utf8" });
+    if ((commit.status ?? 1) !== 0) return { ok: false, detail: `git commit 失败：${(commit.stderr ?? "").trim()}` };
+    const head = spawnSync("git", ["rev-parse", "--short", "HEAD"], { cwd, encoding: "utf8" });
+    return { ok: true, hash: (head.stdout ?? "").trim() };
+  };
+}
+
+/**
+ * 零加载候选的引用面清单（设计稿 10.4 的五处收口里能自动查的三处）：
+ * `.cursor` stub、`AGENTS.md` 索引行、其它技能里的提及。`rg` 不在 PATH 时按 0 处理并记日志。
+ */
+export function createReferenceScan(cwd: string): (skill: string) => ReferenceScan {
+  return (skill) => {
+    const cursorStub = fs.existsSync(path.join(cwd, ".cursor", "skills", skill, "SKILL.md"));
+    let agentsIndex = false;
+    for (const file of [path.join(cwd, "AGENTS.md"), path.join(cwd, ".pi", "AGENTS.md")]) {
+      try {
+        const rows = fs.readFileSync(file, "utf8").split("\n");
+        if (rows.some((row) => row.includes(`\`${skill}\``) && row.trimStart().startsWith("-"))) agentsIndex = true;
+      } catch {
+        // 索引文件不存在是正常情况（AGENTS.md 只在部分仓里）
+      }
+    }
+    const result = spawnSync("rg", ["-l", "-F", skill, path.join(cwd, ".pi", "skills")], { cwd, encoding: "utf8" });
+    const hits = (result.stdout ?? "").split("\n").filter((line) => line.trim().length > 0);
+    const ownDir = `${path.join(cwd, ".pi", "skills", skill)}${path.sep}`;
+    const mentions = hits.filter((file) => !file.startsWith(ownDir)).length;
+    return { cursorStub, agentsIndex, mentions };
+  };
+}