pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,221 @@
+/**
+ * `/skill-audit`：把遥测里的归因记录、历史 missed、硬禁令现扫结果汇总成一份人读文本。
+ *
+ * 两个原则：
+ * 1. 只报事实 —— attributed 事件是 M2 之后写的；M2 之前的历史 missed 没有类别，
+ *    要么用当前快照现算（并标注「现算」），要么老实列进「未归因」，绝不把两者混成一份数字；
+ * 2. 加载率必须带注解 —— 「读了 description 就照做」「读了文件没照做」都不在「读文件」这条证据链里，
+ *    单看加载率会把最有用的技能判成最没用的。
+ */
+import {
+  CATEGORY_ORDER,
+  DISPOSITIONS,
+  type AttributionCategory,
+  type ExposedSkill,
+} from "./attribution.ts";
+import { splitHits } from "./baseline.ts";
+import type { HardRuleHit } from "./hard-rules.ts";
+import { summarize, type MissedStat, type TelemetryEvent, type TelemetrySkill, type TelemetrySummary } from "./telemetry.ts";
+
+export interface AuditCategoryRow {
+  category: AttributionCategory;
+  label: string;
+  count: number;
+  skills: { skill: string; count: number }[];
+}
+
+export interface AuditModel {
+  days: number;
+  summary: TelemetrySummary;
+  rows: AuditCategoryRow[];
+  /** 一个归因记录都没有的历史 missed（M2 之前采集的数据），不硬编类别 */
+  unattributed: MissedStat[];
+  conflicts: HardRuleHit[];
+  /** 存量债指纹：命中的算存量（设计稿 10.4 已接受），其余算新增 */
+  knownFingerprints: ReadonlySet<string>;
+  invalidRules: string[];
+  /** 归因条数来源统计：遥测里已有的 / 用当前快照现算的 */
+  fromTelemetry: number;
+  fromLive: number;
+}
+
+export const AUDIT_LOAD_RATE_NOTE = "加载率低 ≠ 技能没用：只读 description 就照做、读了文件却没照做，这两类都不在「读文件」这条证据链里。";
+
+/** 存量只列前几条：它们不是失败信号，列多了反而淹没真正要看的新增 */
+const STOCK_PREVIEW = 5;
+const SKILLS_PER_CATEGORY = 6;
+const LABEL_WIDTH = 15;
+const CATEGORY_WIDTH = 8;
+
+/** 中文按 2 列宽计算：不然 padEnd 出来的表格在终端里必错位 */
+function displayWidth(text: string): number {
+  let width = 0;
+  for (const char of text) width += /[\u3000-\u9fff\uff00-\uffef]/.test(char) ? 2 : 1;
+  return width;
+}
+
+function padTo(text: string, width: number): string {
+  return text + " ".repeat(Math.max(0, width - displayWidth(text)));
+}
+
+function asCategory(value: unknown): AttributionCategory | null {
+  return typeof value === "string" && (CATEGORY_ORDER as readonly string[]).includes(value)
+    ? (value as AttributionCategory)
+    : null;
+}
+
+function countMissed(events: readonly TelemetryEvent[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const event of events) {
+    if (event.kind !== "missed") continue;
+    const skill = typeof event.skill === "string" && event.skill.length > 0 ? event.skill : "(未知)";
+    counts.set(skill, (counts.get(skill) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/** 最近一次 advertised 里的技能快照：给现算归因提供 filePath / disabled */
+export function exposedFromEvents(events: readonly TelemetryEvent[]): ExposedSkill[] {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event.kind !== "advertised" || !Array.isArray(event.skills)) continue;
+    return (event.skills as TelemetrySkill[])
+      .filter((skill) => typeof skill?.name === "string")
+      .map((skill) => ({ name: skill.name, filePath: skill.filePath ?? "", disabled: skill.disabled === true }));
+  }
+  return [];
+}
+
+/** 最近一次 advertised 记下的 activeTools；没有记录就返回空（空 = 不知道，不能拿来判 E） */
+export function activeToolsFromEvents(events: readonly TelemetryEvent[]): string[] {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event.kind !== "advertised") continue;
+    if (!Array.isArray(event.activeTools)) return [];
+    return (event.activeTools as unknown[]).filter((tool): tool is string => typeof tool === "string");
+  }
+  return [];
+}
+
+export function buildAuditModel(input: {
+  days: number;
+  events: readonly TelemetryEvent[];
+  /** 给历史 missed 现算类别的回调；不给就把它们全列进「未归因」 */
+  classify?: (skill: string) => AttributionCategory;
+  conflicts: readonly HardRuleHit[];
+  knownFingerprints?: ReadonlySet<string>;
+  invalidRules: readonly string[];
+}): AuditModel {
+  const counted = new Map<AttributionCategory, Map<string, number>>();
+  const add = (category: AttributionCategory, skill: string, amount: number): void => {
+    const bucket = counted.get(category) ?? new Map<string, number>();
+    bucket.set(skill, (bucket.get(skill) ?? 0) + amount);
+    counted.set(category, bucket);
+  };
+
+  const covered = new Set<string>();
+  let fromTelemetry = 0;
+  for (const event of input.events) {
+    if (event.kind !== "attributed") continue;
+    const skill = typeof event.skill === "string" ? event.skill : "";
+    const category = asCategory(event.category);
+    if (skill.length === 0 || category === null) continue;
+    covered.add(skill);
+    add(category, skill, 1);
+    fromTelemetry += 1;
+  }
+
+  let fromLive = 0;
+  const unattributed: MissedStat[] = [];
+  const misses = countMissed(input.events);
+  for (const [skill, count] of misses) {
+    if (covered.has(skill)) continue;
+    if (input.classify !== undefined) {
+      add(input.classify(skill), skill, count);
+      fromLive += count;
+    } else {
+      unattributed.push({ skill, count });
+    }
+  }
+  unattributed.sort((a, b) => b.count - a.count || a.skill.localeCompare(b.skill));
+
+  const rows: AuditCategoryRow[] = CATEGORY_ORDER.map((category) => {
+    const bucket = counted.get(category) ?? new Map<string, number>();
+    const skills = [...bucket.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .slice(0, SKILLS_PER_CATEGORY)
+      .map(([skill, count]) => ({ skill, count }));
+    const count = [...bucket.values()].reduce((sum, value) => sum + value, 0);
+    return { category, label: DISPOSITIONS[category].label, count, skills };
+  });
+
+  return {
+    days: input.days,
+    summary: summarize(input.events),
+    rows,
+    unattributed,
+    conflicts: [...input.conflicts],
+    knownFingerprints: input.knownFingerprints ?? new Set<string>(),
+    invalidRules: [...input.invalidRules],
+    fromTelemetry,
+    fromLive,
+  };
+}
+
+/** 冲突段两段式：存量（已接受）只列前几条，新增才是本次要处理的失败信号 */
+function renderConflicts(model: AuditModel): string[] {
+  if (model.conflicts.length === 0) return ["  P0 命中 0 条（存量 0 / 新增 0）"];
+  const { stock, added } = splitHits(model.conflicts, model.knownFingerprints);
+  const line = (tag: string, hit: HardRuleHit): string =>
+    `    ${tag}  ${hit.ruleId}  ${hit.skill}:${hit.line}  ${hit.level}  「${hit.quote}」`;
+  const stockShown = stock.slice(0, STOCK_PREVIEW);
+  return [
+    `  P0 命中 ${model.conflicts.length} 条：存量（baseline）${stock.length} 条 · 新增 ${added.length} 条`,
+    ...(added.length === 0 ? [] : [...added.map((hit) => line("新增", hit))]),
+    ...(stock.length === 0 ? [] : ["  存量（已接受的存量债，只列前 5 条）："]),
+    ...stockShown.map((hit) => line("存量", hit)),
+    ...(stock.length > stockShown.length ? [`    存量其余 ${stock.length - stockShown.length} 条略`] : []),
+    ...(added.length === 0 ? [] : ["  新增命中：修掉它，或确认无害后跑 /skill-evolve baseline 接受"]),
+  ];
+}
+
+export function auditText(model: AuditModel): string {
+  const { summary } = model;
+  const percent = `${(summary.loadRate * 100).toFixed(1)}%`;
+  const rate = summary.advertised > 0 ? percent : "无曝光数据";
+  const total = model.rows.reduce((sum, row) => sum + row.count, 0);
+
+  const categoryLines = model.rows.flatMap((row) => {
+    const head = `  ${padTo(row.category, CATEGORY_WIDTH)} ${padTo(row.label, LABEL_WIDTH)} ${String(row.count).padStart(4)}`;
+    const detail = row.skills.map((item) => `      - ${item.skill} × ${item.count}`);
+    return [head, ...detail];
+  });
+
+  const categoryHeader = total === 0
+    ? `按类别（近 ${model.days} 天没有可归因的未命中）：`
+    : "按类别（顺序即设计稿第八章决策树，命中即停）：";
+
+  const conflictLines = renderConflicts(model);
+
+  return [
+    `技能进化 · 机械审计（近 ${model.days} 天）`,
+    `  曝光：${summary.rounds} 轮 / ${summary.advertised} 次 · 加载 ${summary.loaded} 次（读取失败 ${summary.failed} 次）· 加载率 ${rate}`,
+    `  归因来源：遥测 attributed ${model.fromTelemetry} 条 ＋ 当前快照现算 ${model.fromLive} 条`,
+    categoryHeader,
+    ...categoryLines,
+    ...(model.unattributed.length === 0
+      ? []
+      : [
+          `未归因（M2 之前的历史 missed，没有类别记录）：${model.unattributed.length} 个技能`,
+          ...model.unattributed.slice(0, 10).map((item, index) => `  ${index + 1}. ${item.skill} × ${item.count}`),
+        ]),
+    ...(summary.missedTop.length === 0
+      ? []
+      : ["未命中 top：", ...summary.missedTop.map((item, index) => `  ${index + 1}. ${item.skill} × ${item.count}`)]),
+    `机械冲突（现扫 .pi/skills，规则 .pi/evolution/rules/hard-rules.json）：`,
+    ...conflictLines,
+    ...(model.invalidRules.length === 0 ? [] : ["规则不可用：", ...model.invalidRules.map((item) => `  - ${item}`)]),
+    "",
+    `注意：${AUDIT_LOAD_RATE_NOTE}`,
+  ].join("\n");
+}

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

@@ -0,0 +1,176 @@
+/**
+ * 存量债基线（设计稿 10.4）：机械扫描命中的 P0 里，「已经认账」的那部分不算失败信号。
+ *
+ * 为什么要有它：`.pi/skills` 里本来就存在历史违规（例如 deploy-test 里的 grep 写法）。
+ * 新插件如果天天把它们报成红，等于宣布自己不可用 —— 所以命中分两段：存量（baseline）/ 新增。
+ * 只有「新增」才是本次要处理的问题。
+ *
+ * 指纹口径：ruleId + skill + sha256(quote 前 120 字)，**不含行号**。
+ * 行号会随正文增删上下漂移，带上行号就会把同一个老问题反复报成「新增」。
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { HardRuleHit } from "./hard-rules.ts";
+import { logLine } from "./logfile.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+/** 与 hard-rules.ts 的 QUOTE_MAX 同口径：quote 只留前 120 字，指纹也只算这 120 字 */
+export const FINGERPRINT_QUOTE_MAX = 120;
+export const BASELINE_VERSION = 1;
+
+export interface BaselineViolation {
+  ruleId: string;
+  level: string;
+  skill: string;
+  /** 行号只作参考，不进指纹：行号漂移不算新增 */
+  line: number;
+  quote: string;
+  fingerprint: string;
+}
+
+export interface Baseline {
+  version: number;
+  generatedAt: number;
+  /** true = 首次审计自动生成（把当时全部命中都当存量）；false = 人工 /skill-evolve baseline 接受 */
+  bootstrap: boolean;
+  violations: BaselineViolation[];
+}
+
+type HitLike = Pick<HardRuleHit, "ruleId" | "skill" | "quote">;
+
+export function fingerprintOf(hit: HitLike): string {
+  const quote = hit.quote.trim().slice(0, FINGERPRINT_QUOTE_MAX);
+  return createHash("sha256").update(`${hit.ruleId}\u0000${hit.skill}\u0000${quote}`).digest("hex").slice(0, 16);
+}
+
+export function toViolation(hit: HardRuleHit): BaselineViolation {
+  return {
+    ruleId: hit.ruleId,
+    level: hit.level,
+    skill: hit.skill,
+    line: hit.line,
+    quote: hit.quote,
+    fingerprint: fingerprintOf(hit),
+  };
+}
+
+/** bootstrap=true 供首次审计自动生成；false 供人工「接受当前全部命中」 */
+export function buildBaseline(hits: readonly HardRuleHit[], now: number, bootstrap: boolean): Baseline {
+  return {
+    version: BASELINE_VERSION,
+    generatedAt: now,
+    bootstrap,
+    violations: hits.map(toViolation),
+  };
+}
+
+export function baselinePath(evolutionDir: string): string {
+  return path.join(evolutionDir, "baseline.json");
+}
+
+/** 读基线：文件不存在是正常状态（返回 null），内容坏了也只当不存在，绝不抛 */
+export function readBaseline(file: string, log?: (msg: string) => void): Baseline | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as Baseline;
+    if (!Array.isArray(parsed.violations)) return null;
+    return parsed;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      log?.(`[skill-evolve] 存量基线读取失败，按不存在处理：${String(error)}`);
+    }
+    return null;
+  }
+}
+
+export async function saveBaseline(file: string, baseline: Baseline, queue: MutationQueue): Promise<void> {
+  await queue(path.resolve(file), async () => {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+  });
+}
+
+export function fingerprintsOf(baseline: Baseline | null): Set<string> {
+  return new Set((baseline?.violations ?? []).map((item) => item.fingerprint));
+}
+
+/** 按指纹切两段：known 里的算存量，其余算新增（同一条命中不会同时落两边） */
+export function splitHits(
+  hits: readonly HardRuleHit[],
+  known: ReadonlySet<string>,
+): { stock: HardRuleHit[]; added: HardRuleHit[] } {
+  const stock: HardRuleHit[] = [];
+  const added: HardRuleHit[] = [];
+  for (const hit of hits) {
+    if (known.has(fingerprintOf(hit))) stock.push(hit);
+    else added.push(hit);
+  }
+  return { stock, added };
+}
+
+export interface BaselineGateDeps {
+  file: string;
+  /** 当前命中：懒到第一次要用时才算，避免 factory 里读盘 */
+  hits: () => readonly HardRuleHit[];
+  now: () => number;
+  queue: MutationQueue;
+  log?: (msg: string) => void;
+}
+
+export interface BaselineGate {
+  /** 同步取：缺文件时按当前命中 bootstrap 并 fire-and-forget 写盘（settle 是同步的，不能 await） */
+  baseline(): Baseline;
+  isStock(hit: HardRuleHit): boolean;
+  /** `/skill-evolve baseline`：把当前全部命中写进基线，返回给人看的一句话 */
+  acceptAll(): Promise<string>;
+  /** `/skill-evolve baseline --reset`：清空清单（不是删文件 —— 删了下次审计又会自动 bootstrap 回存量） */
+  reset(): Promise<string>;
+  /** 等最后一次写盘落地（命令里要确认文件真的写了） */
+  settled(): Promise<void>;
+}
+
+export function createBaselineGate(deps: BaselineGateDeps): BaselineGate {
+  // 默认只落盘：基线文件就在 `.pi/evolution/` 下，日志走同一个目录的 logs/extension.log
+  const log = deps.log ?? ((msg: string) => logLine(path.dirname(deps.file), msg));
+  let cached: Baseline | null = null;
+  let pending: Promise<void> = Promise.resolve();
+
+  const persist = (baseline: Baseline): void => {
+    cached = baseline;
+    pending = saveBaseline(deps.file, baseline, deps.queue).catch((error: unknown) => {
+      log(`[skill-evolve] 存量基线写盘失败：${String(error)}`);
+    });
+  };
+
+  const baseline = (): Baseline => {
+    if (cached) return cached;
+    const onDisk = readBaseline(deps.file, log);
+    if (onDisk) {
+      cached = onDisk;
+      return cached;
+    }
+    // 首次审计：把此刻扫到的全部命中当存量接受，否则第一次运行就是一屏红
+    const created = buildBaseline(deps.hits(), deps.now(), true);
+    log(`[skill-evolve] 首次审计自动生成存量基线：${created.violations.length} 条（${deps.file}）`);
+    persist(created);
+    return created;
+  };
+
+  return {
+    baseline,
+    isStock: (hit) => fingerprintsOf(baseline()).has(fingerprintOf(hit)),
+    acceptAll: async () => {
+      const accepted = buildBaseline(deps.hits(), deps.now(), false);
+      persist(accepted);
+      await pending;
+      return `已接受 ${accepted.violations.length} 条存量 P0：${deps.file}`;
+    },
+    reset: async () => {
+      const empty = buildBaseline([], deps.now(), false);
+      persist(empty);
+      await pending;
+      return `已清空存量基线：${deps.file}（下次审计把所有命中都算新增）`;
+    },
+    settled: () => pending,
+  };
+}

package/extensions/skill-evolve/lib/child-env.ts

@@ -0,0 +1,10 @@
+/**
+ * 子进程门禁（设计稿 4.2 门禁⓪）：任一环境变量在场就说明当前不是用户主会话。
+ *
+ * 单独成文件的原因：evolution.ts 要守 300 行；这里只是一个常量加一个判据，无副作用。
+ */
+const CHILD_ENV_KEYS = ["SKILL_EVOLVE_CHILD", "PI_SUBAGENT_CHILD", "PI_AGENT_RUNNER", "PI_ASYNC_NATIVE_RUNNER"];
+
+export function isChildProcess(env: NodeJS.ProcessEnv = process.env): boolean {
+  return CHILD_ENV_KEYS.some((key) => Boolean(env[key]));
+}

package/extensions/skill-evolve/lib/classify-action.ts

@@ -0,0 +1,161 @@
+/**
+ * 13.1 三级权限的代码判定：只看 diff 真改了什么，不看 LLM 写的 action 字段（它只作参考，冲突以本文件为准）。
+ *
+ * forbidden = 立即拒绝（删技能、改 frontmatter 语义字段、动插件自身、路径越界）；
+ * auto = settle 时自动应用（只动 description 文案、新建 .cursor 路由 stub、AGENTS.md 索引表增删一行）；
+ * approval = 其余全部（正文条款、新增技能、合并），必须 `/skill-evolve approve <runId>`。
+ *
+ * 为什么按「行」判而不是按意图判：模型可以声称自己只改了 description，代码只认它真改的行。
+ */
+
+export type ActionLevel = "auto" | "approval" | "forbidden";
+
+export interface ClassifyInput {
+  diffText: string;
+  /** improve / create / merge / prune */
+  proposalType: string;
+  skill: string;
+}
+
+export interface ClassifyResult {
+  level: ActionLevel;
+  /** 判定依据（人话，进 06-verify.json 与告警） */
+  reasons: string[];
+  /** diff 里出现的所有目标路径（相对仓库根） */
+  targets: string[];
+}
+
+export interface DiffSection {
+  path: string;
+  created: boolean;
+  deleted: boolean;
+  lines: { sign: "+" | "-" | " "; text: string }[];
+}
+
+/** 允许被采纳路径的白名单：路径本身就是授权边界，白名单外一律 forbidden */
+const ALLOWED_PATH = /^(?:\.pi\/skills\/[^/]+\/SKILL\.md|\.cursor\/skills\/[^/]+\/SKILL\.md|(?:\.pi\/)?AGENTS\.md)$/;
+const SKILL_FILE = /^(?:\.pi|\.cursor)\/skills\/[^/]+\/SKILL\.md$/;
+const CURSOR_STUB = /^\.cursor\/skills\/[^/]+\/SKILL\.md$/;
+const AGENTS_FILE = /(?:^|\/)AGENTS\.md$/;
+const PROTECTED_PATH = ".pi/extensions/skill-evolve";
+/** 换掉这三个字段就是换技能语义（名字 / 工具面 / 是否进 prompt），不许自动采纳 */
+const FORBIDDEN_FIELD = /^(name|allowed-tools|disable-model-invocation):/;
+const DESCRIPTION_START = /^description:/;
+/** AGENTS.md 的 Skill 索引表行：`- \`<名>\` —— <路径>` */
+const INDEX_ROW = /^\s*[-*]\s+`[^`]+`\s/;
+
+function normalizePath(raw: string): string | null {
+  const head = raw.split("\t")[0].trim();
+  if (head === "/dev/null" || head.length === 0) return null;
+  return head.replace(/^[ab]\//, "");
+}
+
+/** 按 `+++` 切开文件段：多文件 diff（技能文件 + .cursor stub + AGENTS.md）必须逐段判 */
+export function parseSections(diffText: string): DiffSection[] {
+  const sections: DiffSection[] = [];
+  let current: DiffSection | null = null;
+  let oldPath: string | null = null;
+  let oldIsNull = false;
+  for (const raw of diffText.split(/\r?\n/)) {
+    if (raw.startsWith("--- ")) {
+      oldPath = normalizePath(raw.slice(4));
+      oldIsNull = oldPath === null;
+      continue;
+    }
+    if (raw.startsWith("+++ ")) {
+      const newPath = normalizePath(raw.slice(4));
+      current = {
+        path: newPath ?? oldPath ?? "",
+        created: oldIsNull,
+        deleted: newPath === null,
+        lines: [],
+      };
+      sections.push(current);
+      continue;
+    }
+    if (!current || raw.length === 0) continue;
+    if (raw.startsWith("@@") || raw.startsWith("\\ ")) continue;
+    if (!raw.startsWith("+") && !raw.startsWith("-") && !raw.startsWith(" ")) continue;
+    current.lines.push({ sign: raw[0] as "+" | "-" | " ", text: raw.slice(1) });
+  }
+  return sections;
+}
+
+/**
+ * 标出每个改动行是否属于 description（含 YAML 续行：缩进 ≥2 且上一行在 description 里）。
+ * 只有这类行的改动才够格走 auto —— 它改的是「什么时候该用我」的措辞，不是行为约束。
+ */
+function descriptionFlags(section: DiffSection): boolean[] {
+  const flags: boolean[] = [];
+  let inDescription = false;
+  for (const line of section.lines) {
+    if (DESCRIPTION_START.test(line.text)) inDescription = true;
+    else if (line.text.trim().length === 0) {
+      // 空行不打断：folded / literal 块里允许空行
+    } else if (!/^\s{2,}\S/.test(line.text) || !inDescription) inDescription = false;
+    flags.push(inDescription);
+  }
+  return flags;
+}
+
+export function classifyChange(input: ClassifyInput): ClassifyResult {
+  const sections = parseSections(input.diffText);
+  const targets = sections.map((section) => section.path).filter((item) => item.length > 0);
+  const deny = (why: string): ClassifyResult => ({ level: "forbidden", reasons: [why], targets });
+
+  if (sections.length === 0) return { level: "approval", reasons: ["diff 里没有可判定的文件段"], targets };
+  if (input.proposalType === "prune") return deny("prune（删技能）必须人批：插件只出待执行清单，不真删");
+
+  for (const section of sections) {
+    if (section.deleted) return deny(`删除文件：${section.path || "(未知路径)"}`);
+    if (section.path.includes(PROTECTED_PATH)) return deny(`改动插件自身：${section.path}`);
+    if (!ALLOWED_PATH.test(section.path)) return deny(`路径越界：${section.path || "(未知路径)"}`);
+    for (const line of section.lines) {
+      // 只看增删行：上下文行里出现 `name:` 不是「改动字段」，否则任何挨着 frontmatter 的提案都会被误判 forbidden
+      if (line.sign === " " || line.text.trim().length === 0) continue;
+      if (FORBIDDEN_FIELD.test(line.text.trim())) return deny(`改动 frontmatter 字段：${line.text.trim()}`);
+    }
+  }
+
+  const changes = sections.flatMap((section) => section.lines.filter((line) => line.sign !== " "));
+  if (changes.length === 0) return { level: "approval", reasons: ["没有任何增删行"], targets };
+
+  // 逐段判「这一段自身是否够格 auto」：多文件提案必须每一段都够格，才能整条自动采纳
+  const sectionAuto = (section: DiffSection): boolean => {
+    // 新建 .cursor 路由 stub：内容天然只是指回 SSOT，没有行为约束
+    if (CURSOR_STUB.test(section.path)) return section.created;
+    // AGENTS.md：只认索引表行，且全文件合计只能一行（见下面的计数）
+    if (AGENTS_FILE.test(section.path)) {
+      return section.lines.every((line) => line.sign === " " || line.text.trim().length === 0 || INDEX_ROW.test(line.text));
+    }
+    if (!SKILL_FILE.test(section.path)) return false;
+    const flags = descriptionFlags(section);
+    return section.lines.every((line, index) => line.sign === " " || line.text.trim().length === 0 || flags[index]);
+  };
+
+  if (!sections.every(sectionAuto)) {
+    // 说清是哪一段不够格，方便人一眼看出为什么没自动采纳
+    const offender = sections.find((section) => !sectionAuto(section));
+    return {
+      level: "approval",
+      reasons: [`改动落在正文条款 / 新增技能 / 合并（${offender?.path ?? "未知路径"}）`],
+      targets,
+    };
+  }
+
+  // AGENTS.md 索引表只增/删一行：多行就是结构性改动
+  const agentsChanges = sections
+    .filter((section) => AGENTS_FILE.test(section.path))
+    .flatMap((section) => section.lines.filter((line) => line.sign !== " " && line.text.trim().length > 0));
+  if (agentsChanges.length > 1) return { level: "approval", reasons: ["AGENTS.md 改动超过一行索引"], targets };
+  if (agentsChanges.length === 1) return { level: "auto", reasons: ["AGENTS.md 索引表增删一行"], targets };
+
+  const cursorOnly = sections.every((section) => CURSOR_STUB.test(section.path));
+  if (cursorOnly) return { level: "auto", reasons: ["新建 .cursor 路由 stub"], targets };
+  return { level: "auto", reasons: ["只改 description（含续行）与 .cursor stub"], targets };
+}
+
+/** 只看级别的旧调用面（评审督导写 03-review.json 的 action 用） */
+export function classifyAction(diffText: string, proposalType: string): ActionLevel {
+  return classifyChange({ diffText, proposalType, skill: "" }).level;
+}

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

@@ -0,0 +1,100 @@
+/**
+ * `/skill-evolve` 的子命令路由与补全：只产出展示文本，方便单测。
+ */
+import { runConfigCommand } from "./config-command.ts";
+import type { ConfigFlag } from "./config.ts";
+import type { Evolution } from "./evolution.ts";
+import { COMMAND_FLAG, FLAG_EFFECT, FLAG_LABEL } from "./flags.ts";
+import type { WebLaunchRequest } from "./web/autostart.ts";
+
+export interface SubcommandItem {
+  value: string;
+  label: string;
+  description: string;
+}
+
+export const SUBCOMMANDS: readonly SubcommandItem[] = [
+  { value: "status", label: "status", description: "开关、去抖、锁、最近 run" },
+  { value: "report", label: "report", description: "近 7 天曝光/加载/未命中；--week 出周报（含零加载候选）" },
+  { value: "run", label: "run", description: "立即派发一次复盘（跳过去抖与上限，仍守全局锁）" },
+  { value: "baseline", label: "baseline", description: "把当前 P0 命中全部接受为存量（--reset 清空清单）" },
+  { value: "selftest", label: "selftest", description: "跑三个坏样本：评审器必须 reject/reject/revise，否则流水线停用" },
+  { value: "approve", label: "approve", description: "采纳某条 run（走五道闸）；--prune 只生成删技能清单，不真删" },
+  { value: "queue", label: "queue", description: "列采纳队列：pending / applied / rolled-back / failed / superseded" },
+  { value: "web", label: "web", description: "启动本机 Web 面板（127.0.0.1:7788，--port N 换端口，--once 不写进配置）" },
+  { value: "config", label: "config", description: "选提案/评审模型（inherit = 跟随主会话）" },
+  { value: "collect", label: "collect", description: "只开/关遥测采集（on|off；只写本地日志，不花 token）" },
+  { value: "review", label: "review", description: "只开/关自动复盘（on|off；会派生子进程，花 token）" },
+  { value: "on", label: "on", description: "采集与派生一起打开" },
+  { value: "off", label: "off", description: "采集与派生一起关闭" },
+];
+
+/** 补全：前缀命中就只给命中项；一个都没命中时给全量，避免用户看到空列表 */
+export function matchSubcommand(prefix: string): SubcommandItem[] {
+  const head = prefix.trim();
+  const hit = SUBCOMMANDS.filter((item) => item.value.startsWith(head));
+  return hit.length > 0 ? [...hit] : [...SUBCOMMANDS];
+}
+
+/** 命令需要知道「当前会话」才能手动派发，所以会话标识由调用方（index.ts）传入 */
+export interface CommandTarget {
+  sessionId: string;
+  sessionFile?: string;
+  /**
+   * `/skill-evolve web` 的启动器：面板必须由扩展持有单例并在 session_shutdown 关掉，
+   * 所以这里只注入一个回调，参数解析与文案留在本文件（可单测）。
+   */
+  web?: (request: WebLaunchRequest) => Promise<string>;
+}
+
+/** `web [--port N] [N] [--once]`：`--once` 表示只本次会话起、不写回配置 */
+export function parseWebArgs(args: readonly string[]): WebLaunchRequest {
+  const once = args.includes("--once");
+  // `--port 7799` 与 `web 7799` 两种写法都认；`--port` / `--once` 本身不能当端口解析
+  const port = parseWebPort(args.find((item) => item !== "--port" && item !== "--once"));
+  return port === undefined ? { once } : { once, port };
+}
+
+/** `web [--port N]` / `web [N]`：只认 1~65535 的整数，其余返回 undefined 用默认端口 */
+export function parseWebPort(arg: string | undefined): number | undefined {
+  if (!arg) return undefined;
+  const value = Number.parseInt(arg, 10);
+  return Number.isInteger(value) && value > 0 && value < 65536 ? value : undefined;
+}
+
+export async function runCommand(args: string, evo: Evolution, target: CommandTarget): Promise<string> {
+  const parts = args.trim().split(/\s+/).filter((part) => part.length > 0);
+  const [name, arg] = parts;
+  const command = name && name.length > 0 ? name : "status";
+  if (command === "report") {
+    // `--week` 是 M6 的周报：加载率 / 归因分布 / 冲突密度 / 采纳率 / 回滚率 / 进化收益 + 零加载候选
+    if (arg === "--week") return evo.observe.weekReportText();
+    const days = Number.parseInt(arg ?? "", 10);
+    return evo.reportText(Number.isFinite(days) && days > 0 ? days : 7);
+  }
+  if (command === "run") return evo.runNow(target);
+  if (command === "baseline") return evo.acceptBaseline(arg === "--reset" ? "reset" : "accept");
+  if (command === "selftest") return evo.model.selftestText();
+  // 非 TUI 兜底：真正能交互选模型的路径在 index.ts（那里才拿得到 ctx.ui.select）
+  if (command === "config") return runConfigCommand(null, evo.model, arg);
+  if (command === "on" || command === "off") return evo.setEnabled(command === "on");
+  // `collect on|off` 只动 telemetry、`review on|off` 只动 enabled：缺参数或写错就给用法，一概不改配置
+  if (command === "collect" || command === "review") {
+    const field: ConfigFlag = COMMAND_FLAG[command];
+    const value = arg === "on" ? true : arg === "off" ? false : null;
+    if (value === null) {
+      return `用法：/skill-evolve ${command} on|off —— 只改「${FLAG_LABEL[field]}」（${FLAG_EFFECT[field]}），配置未改动`;
+    }
+    return evo.setFlag(field, value);
+  }
+  if (command === "queue") return evo.apply.queueText();
+  if (command === "web") {
+    if (!target.web) return "用法：/skill-evolve web [--port N] [--once]\n当前环境没有注入面板启动器（只在 pi 会话里可用）";
+    return target.web(parseWebArgs(parts.slice(1)));
+  }
+  // approve 可能带第二个参数（`--prune`），所以这里直接用整串剩余部分
+  if (command === "approve") return evo.apply.approve(arg ?? "", parts.includes("--prune"));
+  if (command === "status") return evo.statusText();
+  const usage = SUBCOMMANDS.map((item) => item.value).join("|");
+  return `未知子命令：${command}\n用法：/skill-evolve [${usage}]`;
+}