pi-skill-evolve 0.0.0-stage → 0.1.2

package/extensions/skill-evolve/test/evolution.test.ts

@@ -0,0 +1,378 @@
+/**
+ * 采集与门禁单测（零依赖，node --test）。
+ *
+ * 运行：
+ *   cd .pi/extensions/skill-evolve
+ *   node --experimental-strip-types --test test/evolution.test.ts
+ *
+ * 覆盖：一轮只结算一次（连续 agent_settled 只派生一次）、无曝光不派生、
+ * 子进程门禁、未命中只记「曝光了但没读」、读非曝光技能不算加载、状态与报告文本。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { fakeSupervisorSpawn } from "./fake-review-spawn.ts";
+import { createEvolution, isChildProcess, type Evolution } from "../lib/evolution.ts";
+import { writeWebPid } from "../lib/web/panel-pid.ts";
+import { directQueue, type TelemetryEvent, type TelemetrySkill } from "../lib/telemetry.ts";
+import type { SpawnedChild, SpawnLike } from "../lib/spawn-plan.ts";
+
+const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "prompts", "复盘.md");
+const NOW = 1_760_000_000_000;
+
+function skill(name: string, disabled = false): TelemetrySkill {
+  return { name, filePath: `/repo/.pi/skills/${name}/SKILL.md`, disabled, source: "project" };
+}
+
+interface Harness {
+  dir: string;
+  evo: Evolution;
+  spawns: number;
+  /** 模拟某个子进程退出（收尸会顺手放锁） */
+  exitChild: (index: number) => Promise<void>;
+  children: FakeChild[];
+  events: () => TelemetryEvent[];
+  tick: (ms: number) => void;
+}
+
+class FakeChild {
+  /** 锁回收用 kill(pid,0) 判存活：假 pid 会被当死进程，所以用真实存活的本进程 pid */
+  readonly pid = process.pid;
+  private listeners = new Map<string, (arg: unknown) => void>();
+  unref(): void {} // detached 子进程交还给 init，测试里无事可做
+  once(event: string, listener: (arg: unknown) => void): this {
+    this.listeners.set(event, listener);
+    return this;
+  }
+  emit(event: string, arg: unknown): void {
+    this.listeners.get(event)?.(arg);
+  }
+}
+
+/**
+ * 夹具的 config.json：生产默认全关（clone 即静默），所以每个用例都得显式打开；
+ * 要验证「默认啥都不做」的用例直接自己建目录、不走这个 helper。
+ */
+function writeConfig(dir: string, config: Record<string, unknown> = {}): void {
+  const evolutionDir = path.join(dir, ".pi", "evolution");
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(evolutionDir, "config.json"),
+    `${JSON.stringify({ enabled: true, telemetry: true, ...config }, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+function harness(env: NodeJS.ProcessEnv = {}, config: Record<string, unknown> = {}): Harness {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-evo-"));
+  writeConfig(dir, config);
+  let clock = NOW;
+  const children: FakeChild[] = [];
+  const spawnFn: SpawnLike = () => (children.push(new FakeChild()), children[children.length - 1] as unknown as SpawnedChild);
+  const evo = createEvolution({
+    cwd: dir,
+    promptTemplatePath: TEMPLATE,
+    queue: directQueue,
+    log: () => {},
+    now: () => clock,
+    env,
+    spawnFn,
+    // 假子进程的 pid 就是本进程 pid（锁回收要真 pid 才判得活）；单飞闸用注入的 alive 模拟「子进程已退出」
+    alive: () => false,
+    supervisorSpawnFn: fakeSupervisorSpawn([]),
+  });
+  return {
+    dir,
+    evo,
+    children,
+    get spawns() {
+      return children.length;
+    },
+    exitChild: async (index) => {
+      children[index].emit("exit", 0);
+      await settleAsync();
+    },
+    events: () => readTelemetry(dir),
+    tick: (ms) => {
+      clock += ms;
+    },
+  };
+}
+
+function readTelemetry(dir: string): TelemetryEvent[] {
+  const shard = path.join(dir, ".pi", "evolution", "telemetry");
+  let names: string[];
+  try {
+    names = fs.readdirSync(shard);
+  } catch {
+    return [];
+  }
+  const events: TelemetryEvent[] = [];
+  for (const name of names.sort()) {
+    for (const line of fs.readFileSync(path.join(shard, name), "utf8").split("\n")) {
+      if (line.trim().length === 0) continue;
+      events.push(JSON.parse(line));
+    }
+  }
+  return events;
+}
+
+/** 等派发链路（异步写盘 + spawn）跑完 */
+const settleAsync = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 150));
+
+test("isChildProcess：任一子进程环境变量在场即为子进程", () => {
+  assert.equal(isChildProcess({}), false);
+  for (const key of ["SKILL_EVOLVE_CHILD", "PI_SUBAGENT_CHILD", "PI_AGENT_RUNNER", "PI_ASYNC_NATIVE_RUNNER"]) {
+    assert.equal(isChildProcess({ [key]: "1" }), true);
+  }
+});
+
+test("连续 agent_settled 只派生一次（一轮只结算一次）", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "把需求推进到开发中", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.equal(h.spawns, 1);
+  assert.equal(h.events().filter((event) => event.kind === "pending").length, 1);
+});
+
+test("去抖：窗口内再结算一轮只写 superseded，不叠加进程", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "第一轮", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.equal(h.spawns, 1);
+
+  h.tick(1000); // 仍在 idleMs(90s) 内
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "第二轮", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.deepEqual([h.spawns, h.events().some((event) => event.kind === "superseded")], [1, true]);
+});
+
+test("本轮无技能曝光：不记未命中，也不派生", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "闲聊", skills: [] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.deepEqual([h.spawns, h.events().some((event) => event.kind === "missed")], [0, false]);
+});
+
+test("子进程门禁：SKILL_EVOLVE_CHILD=1 时照常采集但不派生", async () => {
+  const h = harness({ SKILL_EVOLVE_CHILD: "1" });
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.deepEqual([h.spawns, h.events().some((event) => event.kind === "pending")], [0, true]);
+});
+
+test("未命中只记「曝光了但没读」的技能，disabled 的不算曝光", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a"), skill("b"), skill("c", true)] });
+  h.evo.noteToolCall({ sessionId: "s1", toolCallId: "call-1", toolName: "read", input: { path: ".pi/skills/a/SKILL.md" } });
+  h.evo.resolveToolResult({ sessionId: "s1", toolCallId: "call-1", isError: false });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+
+  const events = h.events();
+  assert.equal(events.filter((event) => event.kind === "loaded").length, 1);
+  assert.deepEqual(events.filter((event) => event.kind === "missed").map((event) => event.skill), ["b"]);
+  const pending = events.find((event) => event.kind === "pending");
+  assert.deepEqual([pending?.exposed, pending?.missed], [2, 1]);
+});
+
+test("读技能失败记 failed，不记 loaded", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a")] });
+  h.evo.noteToolCall({ sessionId: "s1", toolCallId: "call-1", toolName: "bash", input: { command: 'cat ".pi/skills/a/SKILL.md"' } });
+  h.evo.resolveToolResult({ sessionId: "s1", toolCallId: "call-1", isError: true });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  const kinds = h.events().map((event) => event.kind);
+  assert.deepEqual([kinds.filter((kind) => kind === "failed").length, kinds.includes("loaded")], [1, false]);
+});
+
+test("读不在本轮曝光清单里的技能文件，不算一次加载", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("alpha")] });
+  h.evo.noteToolCall({ sessionId: "s1", toolCallId: "call-1", toolName: "read", input: { path: ".pi/skills/beta/SKILL.md" } });
+  h.evo.resolveToolResult({ sessionId: "s1", toolCallId: "call-1", isError: false });
+  assert.equal(h.events().some((event) => event.kind === "loaded"), false);
+});
+
+test("tool_result 对齐不到 tool_call 时静默忽略（跨会话/子代理的工具结果）", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a")] });
+  h.evo.resolveToolResult({ sessionId: "s1", toolCallId: "未知", isError: false });
+  await settleAsync();
+  assert.equal(h.events().some((event) => event.kind === "loaded"), false);
+});
+
+test("statusText / reportText：无数据也不崩，且带上盲区提示", async () => {
+  const h = harness();
+  const status = await h.evo.statusText();
+  assert.equal(status.includes("采集：开（遥测写入 .pi/evolution/telemetry/）｜复盘：开（会派生 agent）"), true);
+  assert.equal(status.includes("锁：空闲"), true);
+  const report = h.evo.reportText();
+  assert.equal(report.includes("无曝光数据"), true);
+  assert.equal(report.includes("加载率低 ≠ 技能没用"), true);
+});
+
+test("statusText：活着的 Web 面板记录多一行地址与 pid，死记录不显示", async () => {
+  const h = harness();
+  const evolutionDir = path.join(h.dir, ".pi", "evolution");
+  const url = "http://127.0.0.1:7788";
+  writeWebPid(evolutionDir, { pid: process.pid, host: "127.0.0.1", port: 7788, url, startedAt: NOW });
+  assert.equal((await h.evo.statusText()).includes(`Web 面板：${url}（pid ${process.pid}）`), true);
+  // 换成已死 pid：残记录不能当活面板显示（否则用户照着不存在的 pid 去清理）
+  writeWebPid(evolutionDir, { pid: 2_147_483_646, host: "127.0.0.1", port: 7788, url, startedAt: NOW });
+  assert.equal((await h.evo.statusText()).includes("Web 面板："), false);
+});
+
+test("reportText：按遥测给出曝光/加载/未命中", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a"), skill("b")] });
+  h.evo.noteToolCall({ sessionId: "s1", toolCallId: "call-1", toolName: "read", input: { path: ".pi/skills/a/SKILL.md" } });
+  h.evo.resolveToolResult({ sessionId: "s1", toolCallId: "call-1", isError: false });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  const report = h.evo.reportText();
+  assert.deepEqual(
+    [report.includes("曝光：1 轮 / 2 次"), report.includes("加载：1 次"), report.includes("50.0%"), report.includes("1. b × 1")],
+    [true, true, true, true],
+  );
+});
+
+test("setEnabled：写回 config.json（两个键一起切）并立即生效", async () => {
+  const h = harness();
+  const message = await h.evo.setEnabled(false);
+  assert.equal(message.includes("关闭"), true);
+  const raw = JSON.parse(fs.readFileSync(path.join(h.dir, ".pi", "evolution", "config.json"), "utf8"));
+  assert.deepEqual([raw.enabled, raw.telemetry], [false, false]);
+  assert.equal((await h.evo.statusText()).includes("采集：关（不写遥测）｜复盘：关（不会派生 agent）"), true);
+
+  await h.evo.setEnabled(true);
+  const back = JSON.parse(fs.readFileSync(path.join(h.dir, ".pi", "evolution", "config.json"), "utf8"));
+  assert.deepEqual([back.enabled, back.telemetry], [true, true]);
+});
+
+test("setFlag：只切一个字段，并把当前两个开关的状态写进回执", async () => {
+  const h = harness({}, { enabled: false, telemetry: false });
+  const text = await h.evo.setFlag("telemetry", true);
+  // 回执要能看出「只开了采集、复盘还关着」，否则用户以为已经会花 token 了
+  assert.equal(text.includes("采集：开（遥测写入 .pi/evolution/telemetry/）｜复盘：关（不会派生 agent）"), true);
+  const raw = JSON.parse(fs.readFileSync(path.join(h.dir, ".pi", "evolution", "config.json"), "utf8"));
+  assert.deepEqual([raw.enabled, raw.telemetry], [false, true], "setFlag(telemetry) 不碰复盘");
+  await h.evo.setFlag("enabled", true);
+  const after = JSON.parse(fs.readFileSync(path.join(h.dir, ".pi", "evolution", "config.json"), "utf8"));
+  assert.deepEqual([after.enabled, after.telemetry], [true, true], "setFlag(enabled) 不碰采集");
+});
+
+test("没有 config.json 时默认全关：不派生、不落遥测", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-evo-default-"));
+  const evo = createEvolution({
+    cwd: dir,
+    promptTemplatePath: TEMPLATE,
+    queue: directQueue,
+    log: () => {},
+    now: () => NOW,
+    env: {},
+    spawnFn: (() => {
+      throw new Error("默认全关时不该起子进程");
+    }) as unknown as SpawnLike,
+    supervisorSpawnFn: fakeSupervisorSpawn([]),
+  });
+  const status = await evo.statusText();
+  assert.equal(status.includes("采集：关（不写遥测）｜复盘：关（不会派生 agent）"), true);
+  evo.recordAdvertised({ sessionId: "s1", cwd: dir, prompt: "x", skills: [skill("a")] });
+  evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.deepEqual(readTelemetry(dir), [], "默认关：遥测也不写");
+});
+
+test("telemetry 关着时只记开关状态不落盘（on 之后才采集）", async () => {
+  const h = harness({}, { telemetry: false });
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a")] });
+  await settleAsync();
+  assert.deepEqual(h.events(), []);
+  await h.evo.setEnabled(true);
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "y", skills: [skill("a")] });
+  await settleAsync();
+  assert.equal(h.events().some((event) => event.kind === "advertised"), true, "on 之后同一会话就采集");
+});
+
+test("去抖尾巴：3 轮 → 1 次派发 + 2 次 superseded，shutdown 再补发一次（覆盖后 2 轮）", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "第1轮", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  assert.equal(h.spawns, 1);
+  await h.exitChild(0); // 第一轮的子进程跑完并放锁
+
+  for (const [prompt, name] of [["第2轮", "b"], ["第3轮", "c"]] as const) {
+    h.tick(1000);
+    h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt, skills: [skill(name)] });
+    h.evo.settle({ sessionId: "s1" });
+    await settleAsync();
+  }
+  assert.equal(h.spawns, 1);
+  assert.equal(h.events().filter((event) => event.kind === "superseded").length, 2);
+
+  h.evo.shutdown();
+  assert.equal(h.spawns, 2);
+  const shutdownRun = readRuns(h.dir).find((record) => record.trigger === "shutdown");
+  assert.deepEqual([shutdownRun?.skills, (shutdownRun?.coverage as { rounds: number } | undefined)?.rounds], [["b", "c"], 2]);
+  assert.equal(h.events().some((event) => event.kind === "dispatched" && event.trigger === "shutdown"), true);
+});
+
+test("shutdown：锁仍被在跑的 run 占着时写 skipped，不起第二个进程", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "第1轮", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  h.tick(1000);
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "第2轮", skills: [skill("a")] });
+  h.evo.settle({ sessionId: "s1" });
+  await settleAsync();
+  h.evo.shutdown(); // 锁仍被第一轮的 run 占着，补发必须让位
+  assert.equal(h.spawns, 1);
+  assert.equal(h.events().some((event) => event.kind === "skipped" && event.trigger === "shutdown"), true);
+});
+
+test("runNow：手动派发跳过去抖，锁被占时给明确文案", async () => {
+  const h = harness();
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a")] });
+
+  const first = await h.evo.runNow({ sessionId: "s1" });
+  assert.equal(first.includes("已派生复盘"), true);
+  assert.equal(first.includes(path.join(".pi", "evolution", "runs")), true);
+  assert.equal(h.spawns, 1);
+
+  // 子进程还在跑：第二次必须让位并说清是谁占着
+  const blocked = await h.evo.runNow({ sessionId: "s1" });
+  assert.equal(blocked.includes("已有复盘在跑（pid"), true);
+});
+
+test("runNow：总开关关着时提示先 on", async () => {
+  const h = harness();
+  await h.evo.setEnabled(false);
+  h.evo.recordAdvertised({ sessionId: "s1", cwd: h.dir, prompt: "x", skills: [skill("a")] });
+  const message = await h.evo.runNow({ sessionId: "s1" });
+  assert.equal(message.includes("/skill-evolve on"), true);
+});
+
+function readRuns(dir: string): Record<string, unknown>[] {
+  const runsDir = path.join(dir, ".pi", "evolution", "runs");
+  let names: string[];
+  try {
+    names = fs.readdirSync(runsDir);
+  } catch {
+    return [];
+  }
+  return names.map((name) => JSON.parse(fs.readFileSync(path.join(runsDir, name, "run.json"), "utf8")) as Record<string, unknown>);
+}

package/extensions/skill-evolve/test/fake-review-spawn.ts

@@ -0,0 +1,60 @@
+/**
+ * 评审子进程的假实现（只给测试用，文件名不匹配 *.test.ts 所以不会被当用例跑）。
+ *
+ * 真起 `pi` 一次要几十秒且要花额度；这里用 EventEmitter 复刻 runReviewChild 需要的
+ * 三个口子：stdout 收到文本、exit 结束、kill 可被调用。
+ */
+import { EventEmitter } from "node:events";
+import type { ReviewChild, ReviewSpawn } from "../lib/review-run.ts";
+import type { SupervisorSpawn } from "../lib/review-spawn.ts";
+
+export class FakeReviewChild extends EventEmitter implements ReviewChild {
+  pid = 4242;
+  stdout = new EventEmitter();
+  killed = false;
+  kill(): void {
+    this.killed = true;
+    this.emit("exit", 0);
+  }
+}
+
+/** 每次 spawn 依次取出 replies 里的一条（取完循环用最后一条）；1ms 后输出并退出 */
+export function fakeReviewSpawn(replies: readonly string[], delayMs = 1): ReviewSpawn {
+  let index = 0;
+  return () => {
+    const child = new FakeReviewChild();
+    const reply = replies[Math.min(index, replies.length - 1)];
+    index += 1;
+    setTimeout(() => {
+      child.stdout.emit("data", reply);
+      child.emit("exit", 0);
+    }, delayMs);
+    return child;
+  };
+}
+
+/** 永不退出的子进程：用来验超时路径（配假时钟，不真等） */
+export function hangingReviewSpawn(): ReviewSpawn {
+  return () => new FakeReviewChild();
+}
+
+/** 假时钟：sleep 推进 now，让 900s / 300s 超时在毫秒内跑完 */
+export function fakeClock(): { now: () => number; sleep: (ms: number) => Promise<void>; elapsed: () => number } {
+  let t = 1_700_000_000_000;
+  const start = t;
+  return {
+    now: () => t,
+    sleep: async (ms: number) => {
+      t += ms;
+    },
+    elapsed: () => t - start,
+  };
+}
+
+/** 假督导 spawn：只记下参数，绝不真起 node 进程（真督导会轮询 900 秒） */
+export function fakeSupervisorSpawn(calls: { args: string[]; options: Record<string, unknown> }[] = []): SupervisorSpawn {
+  return (_command, args, options) => {
+    calls.push({ args, options });
+    return { pid: 7777 };
+  };
+}

package/extensions/skill-evolve/test/hard-rules.test.ts

@@ -0,0 +1,123 @@
+/**
+ * G3 机械硬禁令扫描单测（零依赖，node --test）。
+ *
+ * 运行：
+ *   cd .pi/extensions/skill-evolve
+ *   node --experimental-strip-types --test test/hard-rules.test.ts
+ *
+ * 覆盖：坏正则不许拖垮整条链路、行号是 1 基物理行号、allow 豁免生效、
+ * 以及仓库里那份 hard-rules.json 本身是可用的（6 条 P0、字段齐全）。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { compileRules, listSkillDirs, loadHardRules, scanSkillsDir, scanText } from "../lib/hard-rules.ts";
+
+// 规则文件属于「工作区数据」而不是包里的一部分：源码仓在 .pi/evolution/rules/ 下有一份，
+// npm 包里没有。所以路径从当前文件往上推三层（.../extensions/skill-evolve/test → 仓库根），
+// 找不到就跳过 —— 不要写死某台机器的绝对路径（本地过、CI 挂就是死在这上面）。
+const REPO = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../..");
+const RULES_FILE = process.env.SKILL_EVOLVE_RULES ?? path.join(REPO, ".pi/evolution/rules/hard-rules.json");
+
+test("仓库自带的 hard-rules.json 能编译：6 条 P0、无坏规则、字段齐全", (t) => {
+  if (!fs.existsSync(RULES_FILE)) {
+    t.skip(`本机没有 ${RULES_FILE}（工作区数据，npm 包不附带）`);
+    return;
+  }
+  const loaded = loadHardRules(RULES_FILE);
+  assert.deepEqual(loaded.invalid, []);
+  assert.equal(loaded.compiled.length, 6);
+  for (const item of loaded.compiled) {
+    assert.equal(item.rule.level, "P0", `${item.rule.id} 必须是 P0`);
+    assert.ok(item.rule.expect.length > 0, `${item.rule.id} 缺 expect`);
+    assert.ok((item.rule.why ?? "").length > 0, `${item.rule.id} 缺 why`);
+  }
+});
+
+test("坏正则只丢掉那一条，其余规则照跑", () => {
+  const result = compileRules({
+    rules: [
+      { id: "good", level: "P0", pattern: "违规", expect: "x", why: "y" },
+      { id: "broken", level: "P0", pattern: "([", expect: "x", why: "y" },
+    ],
+  });
+  assert.equal(result.compiled.length, 1);
+  assert.equal(result.compiled[0].rule.id, "good");
+  assert.equal(result.invalid.length, 1);
+  assert.match(result.invalid[0], /^broken: 正则编译失败/);
+});
+
+test("缺 pattern 的规则记 invalid 且不抛", () => {
+  const result = compileRules({ rules: [{ id: "naked" }] });
+  assert.equal(result.compiled.length, 0);
+  assert.deepEqual(result.invalid, ["naked: 缺 pattern"]);
+});
+
+test("扫描：行号是 1 基物理行号，quote 是当行原文", () => {
+  const rules = compileRules({ rules: [{ id: "r", level: "P0", pattern: "grep -r" }] }).compiled;
+  const text = ["# 标题", "", "正常一行", "用 grep -r 搜全仓"].join("\n");
+  const hits = scanText(text, rules, "demo");
+  assert.equal(hits.length, 1);
+  assert.equal(hits[0].line, 4);
+  assert.equal(hits[0].skill, "demo");
+  assert.equal(hits[0].ruleId, "r");
+  assert.equal(hits[0].level, "P0");
+  assert.equal(hits[0].quote, "用 grep -r 搜全仓");
+});
+
+test("扫描：allow 命中时豁免（本仓技能大量写「禁止 grep -r」）", () => {
+  const rules = compileRules({
+    rules: [{ id: "r", level: "P0", pattern: "grep -r", allow: "禁止" }],
+  }).compiled;
+  const text = ["禁止 grep -r，必须用 rg", "用 grep -r 搜"].join("\n");
+  const hits = scanText(text, rules, "demo");
+  assert.equal(hits.length, 1);
+  assert.equal(hits[0].line, 2);
+});
+
+test("扫描：一条行同时命中两条规则时都给（不互斥）", () => {
+  const rules = compileRules({
+    rules: [
+      { id: "first", level: "P0", pattern: "golden" },
+      { id: "second", level: "P0", pattern: "允许" },
+    ],
+  }).compiled;
+  const hits = scanText("允许写 golden 测试", rules, "demo");
+  assert.deepEqual(hits.map((hit) => hit.ruleId).sort(), ["first", "second"]);
+  assert.ok(hits.every((hit) => hit.line === 1));
+});
+
+test("规则文件缺失 / JSON 坏都只返回 invalid", () => {
+  const missing = loadHardRules(path.join(os.tmpdir(), "不存在的规则文件.json"));
+  assert.equal(missing.compiled.length, 0);
+  assert.match(missing.invalid[0], /规则文件不存在/);
+
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hard-rules-"));
+  const broken = path.join(dir, "broken.json");
+  fs.writeFileSync(broken, "{ 坏 json", "utf8");
+  const parsed = loadHardRules(broken);
+  assert.equal(parsed.compiled.length, 0);
+  assert.match(parsed.invalid[0], /JSON 解析失败/);
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test("scanSkillsDir：只扫 */SKILL.md，读不到的文件跳过不抛", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skills-"));
+  fs.mkdirSync(path.join(dir, "one"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "one/SKILL.md"), "# one\n允许写 golden 测试\n", "utf8");
+  fs.mkdirSync(path.join(dir, "README"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "two"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "two/notes.md"), "允许写 golden 测试\n", "utf8");
+
+  const rules = compileRules({ rules: [{ id: "golden", level: "P0", pattern: "允许.{0,6}golden" }] }).compiled;
+  const scan = scanSkillsDir(dir, rules);
+  assert.equal(scan.hits.length, 1);
+  assert.equal(scan.hits[0].skill, "one");
+  assert.equal(scan.hits[0].line, 2);
+  assert.deepEqual(scan.invalid, []);
+  assert.deepEqual(listSkillDirs(dir), ["README", "one", "two"]); // 码位排序，大写在前
+  fs.rmSync(dir, { recursive: true, force: true });
+});