pi-skill-evolve 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,167 @@
+/**
+ * G3 机械硬禁令扫描（设计稿 9.1 六条）：只做「出现即 P0」的机械检查，不做语义判断。
+ *
+ * 规则正文在 .pi/evolution/rules/hard-rules.json（入库），这里只负责解析、编译、逐行扫描。
+ * 一条规则坏掉不许拖垮整条链路：逐条 try/catch，坏的记 invalid 后跳过。
+ */
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export interface HardRule {
+  id: string;
+  level: string;
+  pattern: string;
+  expect: string;
+  /** 同一行里出现即豁免的写法：本仓技能正文大量引用「禁止 grep -r」这类反例 */
+  allow?: string;
+  flags?: string;
+  why?: string;
+}
+
+export interface HardRuleHit {
+  ruleId: string;
+  level: string;
+  skill: string;
+  /** SKILL.md 的 1 基行号 */
+  line: number;
+  quote: string;
+}
+
+export interface CompiledRule {
+  rule: HardRule;
+  regex: RegExp;
+  allowRegex?: RegExp;
+}
+
+export interface CompiledRules {
+  compiled: CompiledRule[];
+  /** 坏规则 / 缺字段的规则，形如 `<规则id>: <原因>` */
+  invalid: string[];
+}
+
+export interface HardRuleScan {
+  hits: HardRuleHit[];
+  invalid: string[];
+}
+
+const QUOTE_MAX = 120;
+
+function compileOne(raw: unknown): CompiledRule | string {
+  if (typeof raw !== "object" || raw === null) return "无效规则：不是对象";
+  const rule = raw as Partial<HardRule>;
+  if (typeof rule.id !== "string" || rule.id.length === 0) return "无效规则：缺 id";
+  if (typeof rule.pattern !== "string" || rule.pattern.length === 0) return `${rule.id}: 缺 pattern`;
+  const level = typeof rule.level === "string" && rule.level.length > 0 ? rule.level : "P0";
+  const flags = typeof rule.flags === "string" ? rule.flags : "";
+  try {
+    const regex = new RegExp(rule.pattern, flags);
+    const allowRegex = typeof rule.allow === "string" && rule.allow.length > 0 ? new RegExp(rule.allow, flags) : undefined;
+    return {
+      rule: {
+        id: rule.id,
+        level,
+        pattern: rule.pattern,
+        expect: typeof rule.expect === "string" ? rule.expect : "",
+        why: typeof rule.why === "string" ? rule.why : "",
+        allow: rule.allow,
+        flags,
+      },
+      regex,
+      allowRegex,
+    };
+  } catch (error) {
+    return `${rule.id}: 正则编译失败（${(error as Error).message}）`;
+  }
+}
+
+/** 编译规则集：坏的跳过并记原因，绝不抛 */
+export function compileRules(raw: unknown): CompiledRules {
+  const list = Array.isArray((raw as { rules?: unknown })?.rules) ? ((raw as { rules: unknown[] }).rules) : [];
+  const compiled: CompiledRule[] = [];
+  const invalid: string[] = [];
+  for (const item of list) {
+    const result = compileOne(item);
+    if (typeof result === "string") invalid.push(result);
+    else compiled.push(result);
+  }
+  return { compiled, invalid };
+}
+
+/** 扫描一段 markdown 正文，返回命中行。纯函数，line 从 1 开始 */
+export function scanText(text: string, rules: CompiledRule[], skill: string): HardRuleHit[] {
+  const hits: HardRuleHit[] = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.length === 0) continue;
+    for (const item of rules) {
+      if (!item.regex.test(line)) continue;
+      if (item.allowRegex !== undefined && item.allowRegex.test(line)) continue;
+      hits.push({
+        ruleId: item.rule.id,
+        level: item.rule.level,
+        skill,
+        line: index + 1,
+        quote: line.trim().slice(0, QUOTE_MAX),
+      });
+    }
+  }
+  return hits;
+}
+
+/** 读规则文件；文件缺失 / JSON 坏 / 读失败都只返回 invalid，不抛 */
+export function loadHardRules(file: string): CompiledRules & { file: string } {
+  if (!existsSync(file)) return { file, compiled: [], invalid: [`规则文件不存在：${file}`] };
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    return { file, compiled: [], invalid: [`规则文件读取失败：${(error as Error).message}`] };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return { file, compiled: [], invalid: [`规则文件 JSON 解析失败：${(error as Error).message}`] };
+  }
+  return { file, ...compileRules(parsed) };
+}
+
+/** 扫 `.pi/skills/<名>/SKILL.md`；单个文件读失败只跳过它并记 invalid */
+export function scanSkillsDir(skillsDir: string, rules: CompiledRule[]): HardRuleScan {
+  const hits: HardRuleHit[] = [];
+  const invalid: string[] = [];
+  if (!existsSync(skillsDir)) return { hits, invalid: [`技能目录不存在：${skillsDir}`] };
+  let entries: string[];
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch (error) {
+    return { hits, invalid: [`技能目录读取失败：${(error as Error).message}`] };
+  }
+  for (const skill of entries) {
+    const file = join(skillsDir, skill, "SKILL.md");
+    if (!existsSync(file)) continue;
+    try {
+      hits.push(...scanText(readFileSync(file, "utf8"), rules, skill));
+    } catch (error) {
+      invalid.push(`${skill}: 读取失败（${(error as Error).message}）`);
+    }
+  }
+  return { hits, invalid };
+}
+
+/** 磁盘上 `.pi/skills/*` 的目录名清单，用于 D 类判定 */
+export function listSkillDirs(skillsDir: string): string[] {
+  if (!existsSync(skillsDir)) return [];
+  try {
+    return readdirSync(skillsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,215 @@
+/**
+ * 跨进程目录锁：`mkdir .pi/evolution/locks/dispatch` 原子创建即拿到锁。
+ *
+ * 为什么不用内存锁：复盘子进程是独立的 pi 进程，同一时刻只允许一个 run。
+ * 为什么不用文件锁库：零第三方依赖，`mkdir` 在 POSIX 与 Windows 上都是原子的。
+ * 防死锁：kill -9 之后目录会留下，靠「owner 的 pid 已不存在」立即回收；只有 owner.json
+ * 本身读不出来时才退化成「超过 2×maxRuntimeMs」兜底。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface LockOwner {
+  pid: number;
+  /** 抢锁毫秒戳 */
+  ts: number;
+  sessionId?: string;
+}
+
+/** pid 是否存活：EPERM 说明进程存在但当前用户无权发信号，同样算活着 */
+export function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+export function lockDir(evolutionDir: string): string {
+  return path.join(evolutionDir, "locks", "dispatch");
+}
+
+/**
+ * 是否回收这把锁（纯函数，可单测）。判据分两类：
+ * 1. owner.json 能读出合法 pid → **只看进程是否存活**：pid 已死立即回收，与等了多久无关。
+ *    理由：kill(pid, 0) 说「进程不存在」就说明没人持有这把锁；pid 复用导致的误判方向是「假活」
+ *    （继续阻塞，安全），不是「假死」（抢锁，危险）。
+ * 2. owner.json 缺失 / JSON 坏 / pid 或 ts 非法 → 无法证明有活着的持有者，才用
+ *    now - ts >= 2×maxRuntimeMs 兜底（ts 也读不出来时按残锁直接回收）。
+ */
+export function shouldReclaim(
+  owner: LockOwner | null,
+  now: number,
+  maxRuntimeMs: number,
+  alive: (pid: number) => boolean = isPidAlive,
+): boolean {
+  const pid = owner?.pid;
+  const ts = owner?.ts;
+  if (owner && Number.isInteger(pid) && pid > 0 && Number.isFinite(ts)) {
+    return !alive(pid);
+  }
+  if (!owner || !Number.isFinite(ts)) return true;
+  return now - (ts as number) >= 2 * maxRuntimeMs;
+}
+
+export function readOwnerSync(dir: string): LockOwner | null {
+  try {
+    const raw: unknown = JSON.parse(fs.readFileSync(path.join(dir, "owner.json"), "utf8"));
+    if (!raw || typeof raw !== "object") return null;
+    const owner = raw as LockOwner;
+    return { pid: Number(owner.pid), ts: Number(owner.ts), sessionId: owner.sessionId };
+  } catch {
+    return null;
+  }
+}
+
+export async function readOwner(dir: string): Promise<LockOwner | null> {
+  return readOwnerSync(dir);
+}
+
+export interface AcquireOptions {
+  evolutionDir: string;
+  owner: LockOwner;
+  maxRuntimeMs: number;
+  log?: (msg: string) => void;
+  now?: () => number;
+}
+
+export interface AcquireResult {
+  ok: boolean;
+  why?: "busy" | "error";
+  /** 抢失败时把当前的持有者带出来，日志与 status 用得上 */
+  owner?: LockOwner | null;
+}
+
+export async function acquireLock(options: AcquireOptions): Promise<AcquireResult> {
+  const log = options.log ?? (() => {});
+  const dir = lockDir(options.evolutionDir);
+  const now = options.now?.() ?? Date.now();
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await fs.promises.mkdir(path.dirname(dir), { recursive: true });
+      await fs.promises.mkdir(dir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") {
+        log(`[skill-evolve] 抢锁失败（mkdir）：${String(error)}`);
+        return { ok: false, why: "error" };
+      }
+      // 目录已存在：要么别人正拿着，要么是残锁
+      const owner = await readOwner(dir);
+      if (!shouldReclaim(owner, now, options.maxRuntimeMs)) return { ok: false, why: "busy", owner };
+      log(
+        `[skill-evolve] 回收孤儿锁：owner=${owner ? `pid ${owner.pid} @ ${new Date(owner.ts).toISOString()}` : "无 owner.json"}`,
+      );
+      try {
+        await fs.promises.rm(dir, { recursive: true, force: true });
+      } catch (rmError) {
+        log(`[skill-evolve] 回收残锁失败：${String(rmError)}`);
+        return { ok: false, why: "error" };
+      }
+      continue;
+    }
+    try {
+      await fs.promises.writeFile(path.join(dir, "owner.json"), `${JSON.stringify(options.owner)}\n`, "utf8");
+      log(`[skill-evolve] 起锁：pid ${options.owner.pid}（${dir}）`);
+      return { ok: true };
+    } catch (error) {
+      // 目录建好了但 owner 写不进去：立刻还回去，避免留下无人认领的锁
+      log(`[skill-evolve] 写 owner.json 失败：${String(error)}`);
+      await releaseLock(options.evolutionDir, options.log);
+      return { ok: false, why: "error" };
+    }
+  }
+  return { ok: false, why: "busy" };
+}
+
+/** 释放锁（幂等）：目录不在也算成功 */
+export async function releaseLock(evolutionDir: string, log: (msg: string) => void = () => {}): Promise<void> {
+  const dir = lockDir(evolutionDir);
+  try {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  } catch (error) {
+    log(`[skill-evolve] 释放锁失败：${String(error)}`);
+  }
+}
+
+function writeOwnerFile(dir: string, owner: LockOwner): void {
+  fs.writeFileSync(path.join(dir, "owner.json"), `${JSON.stringify(owner)}\n`, "utf8");
+}
+
+/**
+ * 同步抢锁：只给 `session_shutdown` 用 —— 主进程马上要退出，不能 await。
+ * 语义与 acquireLock 完全一致（mkdir 原子抢占 + 两轮「回收孤儿再抢」）。
+ */
+export function acquireLockSync(options: AcquireOptions): AcquireResult {
+  const log = options.log ?? (() => {});
+  const dir = lockDir(options.evolutionDir);
+  const now = options.now?.() ?? Date.now();
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.mkdirSync(path.dirname(dir), { recursive: true });
+      fs.mkdirSync(dir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") {
+        log(`[skill-evolve] 抢锁失败（mkdir）：${String(error)}`);
+        return { ok: false, why: "error" };
+      }
+      const owner = readOwnerSync(dir);
+      if (!shouldReclaim(owner, now, options.maxRuntimeMs)) return { ok: false, why: "busy", owner };
+      log(
+        `[skill-evolve] 回收孤儿锁：owner=${owner ? `pid ${owner.pid} @ ${new Date(owner.ts).toISOString()}` : "无 owner.json"}`,
+      );
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch (rmError) {
+        log(`[skill-evolve] 回收残锁失败：${String(rmError)}`);
+        return { ok: false, why: "error" };
+      }
+      continue;
+    }
+    try {
+      writeOwnerFile(dir, options.owner);
+      log(`[skill-evolve] 起锁：pid ${options.owner.pid}（${dir}）`);
+      return { ok: true };
+    } catch (error) {
+      log(`[skill-evolve] 写 owner.json 失败：${String(error)}`);
+      releaseLockSync(options.evolutionDir, options.log);
+      return { ok: false, why: "error" };
+    }
+  }
+  return { ok: false, why: "busy" };
+}
+
+/** 换掉锁的持有者：退出补发后要把 owner 指向复盘子进程，避免下次把活着的 run 当孤儿回收 */
+export function writeOwnerSync(
+  evolutionDir: string,
+  owner: LockOwner,
+  log: (msg: string) => void = () => {},
+): boolean {
+  try {
+    writeOwnerFile(lockDir(evolutionDir), owner);
+    return true;
+  } catch (error) {
+    log(`[skill-evolve] 改写 owner.json 失败：${String(error)}`);
+    return false;
+  }
+}
+
+/** 同步放锁：只给同步补发路径用（失败也只记日志） */
+export function releaseLockSync(evolutionDir: string, log: (msg: string) => void = () => {}): void {
+  try {
+    fs.rmSync(lockDir(evolutionDir), { recursive: true, force: true });
+  } catch (error) {
+    log(`[skill-evolve] 释放锁失败：${String(error)}`);
+  }
+}
+
+export async function lockState(evolutionDir: string): Promise<{ held: boolean; owner: LockOwner | null }> {
+  const dir = lockDir(evolutionDir);
+  const held = fs.existsSync(dir);
+  return { held, owner: held ? await readOwner(dir) : null };
+}

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

@@ -0,0 +1,52 @@
+/**
+ * 扩展自己的日志文件：`.pi/evolution/logs/extension.log`。
+ *
+ * 为什么不打终端（用户 2026-11-08：「tui 的这些推送不看了，影响我」）：每一次 settle 都可能派生
+ * 复盘 + 督导，台面上每轮刷两行进程号，等于把对话区当日志区。所以**默认一律落盘**，
+ * 只有 `PI_SKILL_EVOLVE_DEBUG=1` 才同步回显一份到 stdout（排查时才开）。
+ *
+ * 轮转：单文件超过 1MB 就改名成 `.1`（只留一份历史，够查一次事故，又不至于占满磁盘）。
+ * 写日志失败绝不向上抛：这条链路是旁路，不能因为盘满把派发搞挂。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** 轮转阈值：1MB；超过就把当前文件换成 `.1` */
+export const LOG_MAX_BYTES = 1024 * 1024;
+
+/** 日志文件路径（父目录由 logLine 按需创建） */
+export function logFile(evolutionDir: string): string {
+  return path.join(evolutionDir, "logs", "extension.log");
+}
+
+function rotateIfTooBig(file: string): void {
+  let size: number;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return; // 还没有日志文件：第一条 append 会自己建
+  }
+  if (size <= LOG_MAX_BYTES) return;
+  try {
+    // POSIX 下 rename 直接覆盖旧 `.1`：只留最近一轮历史，不做无限堆叠
+    fs.renameSync(file, `${file}.1`);
+  } catch {
+    // 轮转失败就继续追加：宁可文件变大，也不能丢日志
+  }
+}
+
+/**
+ * 追加一行日志。`debug` 缺省时看环境变量 `PI_SKILL_EVOLVE_DEBUG === "1"`；
+ * 显式传参只给单测用，免得测试之间互相污染环境变量。
+ */
+export function logLine(evolutionDir: string, msg: string, debug?: boolean): void {
+  if (debug ?? process.env.PI_SKILL_EVOLVE_DEBUG === "1") console.log(msg);
+  const file = logFile(evolutionDir);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    rotateIfTooBig(file);
+    fs.appendFileSync(file, `${new Date().toISOString()} ${msg}\n`, "utf8");
+  } catch {
+    // 盘满 / 权限不足：日志是旁路，静默跳过比把主流程带崩更合适
+  }
+}

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

@@ -0,0 +1,95 @@
+/**
+ * 把机械层（归因 A~E + 硬禁令扫描）的结论写进遥测。
+ *
+ * 单独成文件的原因有两个：
+ * 1. evolution.ts 的 settle 只该负责「采集 + 门禁」，归因落盘的口径集中在一处更好查；
+ * 2. 这里能在单测里直接喂假遥测，验证「同一冲突只记一次」「故障只报一次」这两条去重规则。
+ */
+import type { Attribution } from "./attribution.ts";
+import { fingerprintOf } from "./baseline.ts";
+import type { HardRuleHit } from "./hard-rules.ts";
+import type { Mechanical } from "./mechanical.ts";
+import type { TelemetryEvent, TelemetrySkill } from "./telemetry.ts";
+
+export interface MechanicalReporterDeps {
+  mechanical: Mechanical;
+  /** 遥测 append（生产 = telemetry.append，测试 = 收集到数组） */
+  append: (event: TelemetryEvent) => void;
+  /** 命中是否属于存量债（设计稿 10.4）：周报要能分开统计，不能混成一个数 */
+  stockOf?: (hit: HardRuleHit) => boolean;
+  log?: (message: string) => void;
+}
+
+export interface MechanicalReportRequest {
+  sessionId: string;
+  /** 本轮真正曝光的技能（已剔除 disabled） */
+  exposed: TelemetrySkill[];
+  /** 其中没被读过的技能名 */
+  missed: string[];
+  activeTools: string[];
+}
+
+export interface MechanicalReporter {
+  /** 发现失败只报一次，不要每轮重复撞同一面墙 */
+  noteFailure(): void;
+  /** 返回本轮归因结果（派发时带进 prompt，让复盘 agent 只做 F/G） */
+  report(request: MechanicalReportRequest): Attribution[];
+  /** 已上报过的冲突条数，仅用于测试与日志 */
+  conflictCount(): number;
+}
+
+export function createMechanicalReporter(deps: MechanicalReporterDeps): MechanicalReporter {
+  let failureReported = false;
+  /** 硬禁令是「文件现状」不是「本轮事件」：同一条命中只记一次，避免每轮刷屏 */
+  const reportedConflicts = new Set<string>();
+
+  const noteFailure = (): void => {
+    if (failureReported) return;
+    const failed = deps.mechanical.snapshot().failed;
+    if (failed === undefined) return;
+    failureReported = true;
+    deps.log?.(`[skill-evolve] 技能发现失败：${failed}`);
+    deps.append({ kind: "handler_error", where: "mechanical", message: failed });
+  };
+
+  const report = (request: MechanicalReportRequest): Attribution[] => {
+    noteFailure();
+    const attributions = deps.mechanical.attribute({
+      missed: request.missed,
+      exposed: request.exposed.map((skill) => ({
+        name: skill.name,
+        filePath: skill.filePath,
+        disabled: skill.disabled,
+      })),
+      activeTools: request.activeTools,
+    });
+    for (const item of attributions) {
+      deps.append({
+        kind: "attributed",
+        sessionId: request.sessionId,
+        skill: item.skill,
+        category: item.category,
+        reason: item.reason,
+      });
+    }
+    for (const hit of deps.mechanical.conflicts().hits) {
+      // 去重键用指纹（不含行号）：行号漂移是同一条存量问题，不应被当成新命中再记一次
+      const key = fingerprintOf(hit);
+      if (reportedConflicts.has(key)) continue;
+      reportedConflicts.add(key);
+      deps.append({
+        kind: "conflict",
+        sessionId: request.sessionId,
+        ruleId: hit.ruleId,
+        level: hit.level,
+        skill: hit.skill,
+        line: hit.line,
+        quote: hit.quote,
+        stock: deps.stockOf?.(hit) ?? false,
+      });
+    }
+    return attributions;
+  };
+
+  return { noteFailure, report, conflictCount: () => reportedConflicts.size };
+}

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

@@ -0,0 +1,136 @@
+/**
+ * 机械层的现场勘查：把 pi 的技能发现结果、磁盘目录清单、硬禁令扫描结果缓存成一份快照，
+ * 再喂给纯函数做归因（attribution.ts）与冲突判定（hard-rules.ts）。
+ *
+ * 缓存与注入的理由：
+ * - `loadSkillsFromDir` 要解析 28 个 SKILL.md 的 frontmatter，每进程只做一次；
+ * - 硬禁令扫描要读 28 个文件（实测 8ms），只在第一次 settle 做一次，绝不放进 factory；
+ * - 所有依赖靠注入，这样本模块不 import pi 包，能被 `node --test` 直接跑。
+ */
+
+import { join } from "node:path";
+import {
+  classifyMechanical,
+  type Attribution,
+  type DiagnosticEntry,
+  type ExposedSkill,
+} from "./attribution.ts";
+import {
+  listSkillDirs,
+  loadHardRules,
+  scanSkillsDir,
+  type HardRuleHit,
+  type CompiledRules,
+} from "./hard-rules.ts";
+
+export interface SnapshotSkill {
+  name: string;
+  filePath: string;
+}
+
+export interface SkillsSnapshot {
+  skills: SnapshotSkill[];
+  diagnostics: DiagnosticEntry[];
+  /** 磁盘上 .pi/skills/* 的目录名 */
+  diskSkillNames: string[];
+  /** 发现失败的原因（此时 skills 为空，调用方要记 handler_error） */
+  failed?: string;
+}
+
+/** pi 的 ResourceDiagnostic → 本模块的 DiagnosticEntry（字段名是 path 不是 file） */
+export interface RawDiagnostic {
+  path?: string;
+  message: string;
+  type?: string;
+}
+
+export interface MechanicalDeps {
+  cwd: string;
+  /** 生产实现：() => loadSkillsFromDir({ dir: join(cwd, ".pi/skills"), source: "project" }) */
+  loadSkills: () => { skills: SnapshotSkill[]; diagnostics: RawDiagnostic[] };
+  /** .pi/evolution/rules/hard-rules.json 绝对路径 */
+  rulesFile: string;
+  log: (message: string) => void;
+}
+
+export interface AttributeRequest {
+  /** 本轮曝光但没加载的技能名 */
+  missed: string[];
+  /** 本轮 prompt 里的技能 */
+  exposed: ExposedSkill[];
+  /** 本轮 activeTools（pi.getActiveTools()） */
+  activeTools: string[];
+}
+
+export interface ConflictScan {
+  hits: HardRuleHit[];
+  invalid: string[];
+}
+
+export interface Mechanical {
+  snapshot(): SkillsSnapshot;
+  attribute(request: AttributeRequest): Attribution[];
+  conflicts(): ConflictScan;
+}
+
+export function createMechanical(deps: MechanicalDeps): Mechanical {
+  const skillsDir = join(deps.cwd, ".pi", "skills");
+  let cachedSnapshot: SkillsSnapshot | undefined;
+  let cachedRules: CompiledRules | undefined;
+  let cachedConflicts: ConflictScan | undefined;
+
+  const snapshot = (): SkillsSnapshot => {
+    if (cachedSnapshot !== undefined) return cachedSnapshot;
+    const diskSkillNames = listSkillDirs(skillsDir);
+    try {
+      const result = deps.loadSkills();
+      cachedSnapshot = {
+        skills: result.skills.map((skill) => ({ name: skill.name, filePath: skill.filePath })),
+        diagnostics: result.diagnostics.map((entry) => ({
+          file: entry.path ?? "",
+          message: entry.message,
+          type: entry.type,
+        })),
+        diskSkillNames,
+      };
+    } catch (error) {
+      const message = (error as Error).message;
+      deps.log(`技能发现失败，机械归因降级为 D/semantic：${message}`);
+      cachedSnapshot = { skills: [], diagnostics: [], diskSkillNames, failed: message };
+    }
+    return cachedSnapshot;
+  };
+
+  const rules = (): CompiledRules => {
+    if (cachedRules !== undefined) return cachedRules;
+    const loaded = loadHardRules(deps.rulesFile);
+    for (const item of loaded.invalid) deps.log(`硬禁令规则不可用：${item}`);
+    cachedRules = { compiled: loaded.compiled, invalid: loaded.invalid };
+    return cachedRules;
+  };
+
+  return {
+    snapshot,
+
+    attribute(request: AttributeRequest): Attribution[] {
+      const current = snapshot();
+      return classifyMechanical({
+        missed: request.missed,
+        exposed: request.exposed,
+        loadedFromPi: current.skills,
+        diagnostics: current.diagnostics,
+        activeTools: request.activeTools,
+        diskSkillNames: current.diskSkillNames,
+      });
+    },
+
+    conflicts(): ConflictScan {
+      if (cachedConflicts !== undefined) return cachedConflicts;
+      const compiled = rules();
+      const scanned = scanSkillsDir(skillsDir, compiled.compiled);
+      for (const item of scanned.invalid) deps.log(`硬禁令扫描跳过：${item}`);
+      cachedConflicts = { hits: scanned.hits, invalid: [...compiled.invalid, ...scanned.invalid] };
+      return cachedConflicts;
+    },
+  };
+}