pi-proactive 0.0.0-stage → 0.2.0-beta.2

package/build/src/config.js

@@ -0,0 +1,483 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ContentStore } from "./content.js";
+/**
+ * **跨模块共享的落盘原语**（目录/文件权限 + 原子写 + 版本判定）。
+ *
+ * 为什么放在本文件：`proactiveDir()` / `resolveAgentDir()` 已是所有持久化面的共同依赖，
+ * 落盘原语与它们同源 → 避免「每个面各写一套」（同一不变量在 6 处漂移的根因）。
+ */
+/** 落盘**目录**权限（0700）——规范 P0（docs/a2a-protocol.md §8.3）。 */
+export const PROACTIVE_DIR_MODE = 0o700;
+/** 落盘**文件**权限（0600）——规范 P0。 */
+export const PROACTIVE_FILE_MODE = 0o600;
+/**
+ * 落盘格式版本号。
+ *
+ * 命名与 `task-store` 的记录级 `version:"v1"` 约定一致（同一个 `v<major>` 记法）。
+ * **兼容规则**：文件**没有** version 字段 = 旧格式 = 按 `v1` 读（升级不丢数据）。
+ */
+export const ON_DISK_VERSION = "v1";
+/**
+ * 版本是否可识别：缺省（无 version 字段）视为 `v1`；其它值 = **不认识**。
+ *
+ * 读方遇到不认识的版本必须**拒绝按已知格式解析**（规范 V3），且不得覆盖原文件。
+ */
+export function isKnownOnDiskVersion(value) {
+    return value === undefined || value === ON_DISK_VERSION;
+}
+/** 取落盘对象的 `version` 字段（非对象 / 无该字段 → undefined = 「无版本」= v1）。 */
+export function onDiskVersionOf(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return value.version;
+}
+/**
+ * 确保目录存在且权限为 **0700**。
+ *
+ * 必须**显式 chmod**：`mkdirSync` 的 mode 会被 umask 削弱，且**已存在的目录**根本不会改权限
+ * → 只传 mode 不够（规范 P0 要求「实际权限」收紧）。
+ */
+export function ensureDir(dir) {
+    const existed = fs.existsSync(dir);
+    // 不用 mkdir 的 mode 选项（会被 umask 削弱，且**已存在的目录**不会改权限）→
+    // 紧接着显式 chmod 到目标权限（见下）。
+    fs.mkdirSync(dir, { recursive: true });
+    if (!existed) {
+        // 新建目录：umask 可能削弱 owner 位 → 显式 chmod 到 0700。
+        chmodQuiet(dir, PROACTIVE_DIR_MODE);
+        return;
+    }
+    // **已存在**的目录：只**收紧 group/other**（不动 owner 位）。
+    // 为什么不动 owner 位：用户刻意设置的只读目录（如 0555）是「显式意图」，
+    // 把它加成 0700 等于替用户放开写权限 —— 落盘失败要如实报错，而不是被我们悄悄绕过。
+    try {
+        const perm = fs.statSync(dir).mode & 0o777;
+        if ((perm & 0o077) !== 0)
+            chmodQuiet(dir, perm & ~0o077);
+    }
+    catch {
+        // 读不到 mode 就放弃收紧（目录可能不属于当前用户）
+    }
+}
+/**
+ * chmod（**失败即抛**）：用于「权限收紧失败不得静默放行」的硬边界（socket 端点）。
+ *
+ * 与 {@link chmodQuiet} 的区别：quiet 失败只忽略（尽力而为），strict 失败抛错
+ * → 调用方必须**拒绝继续**（例如：端点收紧失败 ⇒ 不开 socket 通道）。
+ */
+export function chmodStrict(file, perm) {
+    fs.chmodSync(file, perm);
+}
+/**
+ * 路径包含性校验：把 `segments` 拼到 `base` 下，并**确认结果仍在 `base` 之内**。
+ *
+ * 为什么需要：目录名由外部可控的 `agentId` / 信封 id 派生（`agentSegment()` 只把
+ * `/ \\ 空白` 换成 `_`，**点号不动**）→ `agentId = ".."` 会让 `path.join()` 逃出一层目录。
+ * 这是**接收侧**的最后一道防线（写端 `outbox.ts` 的拼接本卡未改，见威胁模型残余风险）。
+ *
+ * 逃逸 → 抛错（**不得**静默继续：静默 = 把越界写当成正常路径）。
+ */
+export function containedPath(base, ...segments) {
+    const root = path.resolve(base);
+    const target = path.resolve(root, ...segments);
+    if (target !== root && !target.startsWith(root + path.sep)) {
+        throw new Error(`路径越界（必须位于 ${root} 之内）：${segments.join("/")}`);
+    }
+    return target;
+}
+export function hardenProactivePermissions(agentDir) {
+    const report = { dirs: 0, files: 0, failures: [] };
+    const root = proactiveDir(agentDir);
+    const walk = (dir, depth) => {
+        if (depth > 8)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // 目录不存在 → 无事可做
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isSymbolicLink())
+                continue; // 不跟随符号链接
+            if (entry.isDirectory()) {
+                try {
+                    fs.chmodSync(full, PROACTIVE_DIR_MODE);
+                    report.dirs += 1;
+                }
+                catch (e) {
+                    const error = e instanceof Error ? e.message : String(e);
+                    report.failures.push({ path: full, error });
+                    console.error(`[proactive] 目录权限收紧失败（0700）：${full}：${error}`);
+                }
+                walk(full, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            try {
+                fs.chmodSync(full, PROACTIVE_FILE_MODE);
+                report.files += 1;
+            }
+            catch (e) {
+                const error = e instanceof Error ? e.message : String(e);
+                report.failures.push({ path: full, error });
+                console.error(`[proactive] 文件权限收紧失败（0600）：${full}：${error}`);
+            }
+        }
+    };
+    // 根目录自身也要收紧（`proactive/` 可能早于本次实现就已存在）。
+    try {
+        if (fs.existsSync(root)) {
+            fs.chmodSync(root, PROACTIVE_DIR_MODE);
+            report.dirs += 1;
+        }
+    }
+    catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        report.failures.push({ path: root, error });
+        console.error(`[proactive] 目录权限收紧失败（0700）：${root}：${error}`);
+    }
+    walk(root, 0);
+    return report;
+}
+/**
+ * 原子写（tmp + rename）：**tmp 路径对并发写者独占**，文件权限 0600，可选 fsync。
+ *
+ * - **tmp 独占**（偏差 P-D6 / 规范 I2）：先用 `O_EXCL` 抢占 `<file>.tmp`；抢不到（EEXIST，
+ *   说明另一个写者正在用）→ 退到唯一名 `<file>.tmp-<pid>-<ts36>-<rand>`。
+ *   ⇒ 同一时刻**没有任何两个写者写同一个 tmp**，rename 发布的永远是**自己**写的内容。
+ * - **同目录**：tmp 与目标同目录 → `rename(2)` 原子（跨文件系统会失败）。
+ * - **0600**：建文件时带 mode，并**显式 chmod**（umask 只会削弱、既有文件不会改）。
+ * - **durable**：写完后 `fsync(文件)` → `rename` → `fsync(父目录)`（规范 I3，掉电持久性）。
+ */
+export function writeAtomicFile(file, content, opts) {
+    const dir = path.dirname(file);
+    ensureDir(dir);
+    const tmp = openExclusiveTemp(file);
+    try {
+        try {
+            fs.writeFileSync(tmp.fd, content, "utf8");
+            if (opts?.durable)
+                fs.fsyncSync(tmp.fd);
+        }
+        finally {
+            fs.closeSync(tmp.fd);
+        }
+        chmodQuiet(tmp.path, PROACTIVE_FILE_MODE);
+        fs.renameSync(tmp.path, file);
+        if (opts?.durable)
+            fsyncDir(dir);
+    }
+    catch (e) {
+        try {
+            fs.unlinkSync(tmp.path);
+        }
+        catch {
+            // tmp 残留由 GC 兜底（偏差 P-D2 的回收责任方）
+        }
+        throw e;
+    }
+}
+/**
+ * 抢占一个**独占**的临时文件（O_EXCL）：`<file>.tmp` 抢不到 → 退到带 pid/时间戳/随机后缀的唯一名。
+ *
+ * 返回已打开的 fd（调用方负责关闭）。
+ */
+function openExclusiveTemp(file) {
+    const candidates = [`${file}.tmp`];
+    for (let i = 0; i < 8; i++) {
+        candidates.push(`${file}.tmp-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+    }
+    for (const candidate of candidates) {
+        try {
+            const fd = fs.openSync(candidate, "wx", PROACTIVE_FILE_MODE);
+            return { path: candidate, fd };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+    }
+    throw new Error(`无法取得独占临时文件：${file}.tmp`);
+}
+/** chmod（失败不抛：权限收紧是「尽力而为」，不能因此让落盘失败）。 */
+export function chmodQuiet(file, perm) {
+    try {
+        fs.chmodSync(file, perm);
+    }
+    catch {
+        // 忽略（文件可能已被删除，或不属于当前用户）
+    }
+}
+/** fsync 父目录（rename 的持久性：目录项本身落盘）。失败不阻断（平台差异）。 */
+function fsyncDir(dir) {
+    try {
+        const fd = fs.openSync(dir, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // 目录 fsync 不可用时：内容已 fsync，rename 的持久性退化为「尽力而为」
+    }
+}
+export function resolveAgentDir() {
+    return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+}
+export function proactiveDir(agentDir = resolveAgentDir()) {
+    return path.join(agentDir, "proactive");
+}
+/**
+ * 决策环的**缺省**配置（brief-v4 §1.2 / §7 第 1 步）。
+ *
+ * 缺省值的语义（与旧 `afterMs` 判定的等价性见 `src/idle.ts` 的 `evaluateIdle`）：
+ * - `threshold = 1`：`score = value * urgency / interruptionCost >= 1`；
+ * - `observeRatio = 0.5`：分数落在 `[0.5, 1)` → 降级为「只观察」（记账但不打扰）；
+ * - `repeatedInterruptionWeight = 0.5`：**近 1 小时打扰次数 >= 2** 时打断代价才开始变贵
+ *   （第 1 次打扰不加价 → 常规场景与旧行为一致）。
+ */
+export const DEFAULT_DECISION_CONFIG = {
+    enabled: true,
+    threshold: 1,
+    observeRatio: 0.5,
+    repeatedInterruptionWeight: 0.5,
+    busyInterruptionWeight: 1,
+    quietInterruptionWeight: 1,
+};
+/**
+ * 取生效的决策环配置（配置缺项 → 缺省值）。
+ *
+ * 为什么单独一个函数：`ProactiveConfig.decision` 是**可选**的（旧配置文件 / 既有测试用例里没有这一节），
+ * 而决策环**必须**拿到完整的可调输入 → 缺省补齐只在这一处发生。
+ */
+export function resolveDecisionConfig(config) {
+    const d = config.decision ?? {};
+    const base = DEFAULT_DECISION_CONFIG;
+    return {
+        enabled: typeof d.enabled === "boolean" ? d.enabled : base.enabled,
+        threshold: num(d.threshold, base.threshold),
+        observeRatio: num(d.observeRatio, base.observeRatio),
+        repeatedInterruptionWeight: num(d.repeatedInterruptionWeight, base.repeatedInterruptionWeight),
+        busyInterruptionWeight: num(d.busyInterruptionWeight, base.busyInterruptionWeight),
+        quietInterruptionWeight: num(d.quietInterruptionWeight, base.quietInterruptionWeight),
+    };
+}
+export function defaultConfig() {
+    return {
+        enabled: true,
+        idleDetect: "off",
+        askTimeoutMs: 120000,
+        idleTrigger: {
+            enabled: false,
+            afterMs: 600000,
+            intent: "wake",
+            prompt: "",
+        },
+        limits: {
+            minGapMs: 300000,
+            maxPerHour: 6,
+        },
+        decision: { ...DEFAULT_DECISION_CONFIG },
+        peerWatch: {
+            enabled: false,
+            afterIdleMs: 600000,
+        },
+    };
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function num(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function bool(v, fallback) {
+    return typeof v === "boolean" ? v : fallback;
+}
+function str(v, fallback) {
+    return typeof v === "string" ? v : fallback;
+}
+function oneOf(v, allowed, fallback) {
+    return typeof v === "string" && allowed.includes(v) ? v : fallback;
+}
+function mergeConfig(base, raw) {
+    if (!isPlainObject(raw))
+        return base;
+    const idleDetect = oneOf(raw.idleDetect, ["terminal", "input-only", "off"], base.idleDetect);
+    const it = isPlainObject(raw.idleTrigger) ? raw.idleTrigger : {};
+    const limits = isPlainObject(raw.limits) ? raw.limits : {};
+    const decision = isPlainObject(raw.decision) ? raw.decision : {};
+    const qh = limits.quietHours;
+    const pw = isPlainObject(raw.peerWatch) ? raw.peerWatch : {};
+    let quietHours = base.limits.quietHours;
+    if (isPlainObject(qh)) {
+        quietHours = { from: str(qh.from, base.limits.quietHours?.from ?? "22:00"), to: str(qh.to, base.limits.quietHours?.to ?? "08:00") };
+    }
+    else if (qh !== undefined) {
+        quietHours = undefined;
+    }
+    const merged = {
+        enabled: bool(raw.enabled, base.enabled),
+        idleDetect,
+        askTimeoutMs: num(raw.askTimeoutMs, base.askTimeoutMs),
+        idleTrigger: {
+            enabled: bool(it.enabled, base.idleTrigger.enabled),
+            afterMs: num(it.afterMs, base.idleTrigger.afterMs),
+            intent: oneOf(it.intent, ["wake", "interrupt", "queue", "notify"], base.idleTrigger.intent),
+            prompt: str(it.prompt, base.idleTrigger.prompt),
+        },
+        limits: {
+            minGapMs: num(limits.minGapMs, base.limits.minGapMs),
+            maxPerHour: num(limits.maxPerHour, base.limits.maxPerHour),
+        },
+        decision: {
+            enabled: bool(decision.enabled, base.decision?.enabled ?? DEFAULT_DECISION_CONFIG.enabled),
+            threshold: num(decision.threshold, base.decision?.threshold ?? DEFAULT_DECISION_CONFIG.threshold),
+            observeRatio: num(decision.observeRatio, base.decision?.observeRatio ?? DEFAULT_DECISION_CONFIG.observeRatio),
+            repeatedInterruptionWeight: num(decision.repeatedInterruptionWeight, base.decision?.repeatedInterruptionWeight ?? DEFAULT_DECISION_CONFIG.repeatedInterruptionWeight),
+            busyInterruptionWeight: num(decision.busyInterruptionWeight, base.decision?.busyInterruptionWeight ?? DEFAULT_DECISION_CONFIG.busyInterruptionWeight),
+            quietInterruptionWeight: num(decision.quietInterruptionWeight, base.decision?.quietInterruptionWeight ?? DEFAULT_DECISION_CONFIG.quietInterruptionWeight),
+        },
+        peerWatch: {
+            enabled: bool(pw.enabled, base.peerWatch.enabled),
+            afterIdleMs: num(pw.afterIdleMs, base.peerWatch.afterIdleMs),
+        },
+    };
+    if (typeof it.askUser === "boolean")
+        merged.idleTrigger.askUser = it.askUser;
+    if (quietHours !== undefined)
+        merged.limits.quietHours = quietHours;
+    return merged;
+}
+/**
+ * 把配置里的**内容引用**（`promptRef` / `agentRef`）解析成实际内容（CFG1 · C1/C2）。
+ *
+ * 两种引用写法：
+ * 1. `idleTrigger.promptRef: "idle-probe"` → `<配置目录>/prompts/idle-probe.md`；
+ * 2. `contentRefs: { "<名字>": { "promptRef": "..." } | { "agentRef": "..." } }`
+ *    → `prompts/` 或 `agents/` 下的同名 `.md`（agent 定义走这条路）。
+ *
+ * **优先级（规范 §4）：内联优先。** 同层仍有内联 `prompt`（旧配置）时，内联生效并给一次性提示；
+ * 两者都无 → 用缺省。**加载失败一律抛错**（悬空 / 空 / 格式错 / 越界），
+ * **绝不**静默回退缺省（那会让「提示词悄悄变空」变成看不见的故障）。
+ */
+function applyContentRefs(cfg, raw, dir) {
+    const rawObj = isPlainObject(raw) ? raw : {};
+    const it = isPlainObject(rawObj.idleTrigger) ? rawObj.idleTrigger : {};
+    const prompts = new ContentStore(dir, "prompts");
+    const agents = new ContentStore(dir, "agents");
+    const resolved = {};
+    // ── idleTrigger.promptRef ──
+    const promptRef = typeof it.promptRef === "string" ? it.promptRef.trim() : "";
+    if (promptRef !== "") {
+        const inline = typeof it.prompt === "string" ? it.prompt : "";
+        if (inline !== "") {
+            // 内联优先（旧配置零改动继续可用）+ 一次性提示（让用户知道 ref 被忽略了）。
+            console.warn(`[proactive] idleTrigger 同时配置了内联 prompt 与 promptRef="${promptRef}" → 以内联 prompt 为准（promptRef 不生效；规范 §4）`);
+        }
+        else {
+            const entry = prompts.resolveEntry(promptRef);
+            cfg.idleTrigger.prompt = entry.body;
+            resolved["idleTrigger.prompt"] = entry;
+        }
+    }
+    // ── 通用引用表 contentRefs ──
+    const refs = isPlainObject(rawObj.contentRefs) ? rawObj.contentRefs : {};
+    for (const [name, value] of Object.entries(refs)) {
+        if (!isPlainObject(value))
+            continue;
+        const p = typeof value.promptRef === "string" ? value.promptRef.trim() : "";
+        const a = typeof value.agentRef === "string" ? value.agentRef.trim() : "";
+        if (p !== "" && a !== "") {
+            throw new Error(`[proactive] 外置内容引用冲突：contentRefs.${name} 同时配置了 promptRef 与 agentRef → 只允许一个`);
+        }
+        if (p !== "") {
+            resolved[name] = prompts.resolveEntry(p);
+            continue;
+        }
+        if (a !== "") {
+            resolved[name] = agents.resolveEntry(a);
+        }
+    }
+    if (Object.keys(resolved).length > 0)
+        cfg.externalContent = resolved;
+}
+/**
+ * 读取配置（含**外置内容解析**）。
+ *
+ * 失败语义（与「坏 JSON 回落缺省」刻意不同）：
+ * - `config.json` 读不出 / 解析失败 → 回落缺省（老契约：配置文件坏掉不得拖垮宿主）；
+ * - **外置内容引用失败** → **抛错**（规范 §9：失败必须抛错并指名 ref 与路径）。
+ */
+export function loadConfig(opts) {
+    const base = defaultConfig();
+    const dir = proactiveDir();
+    let raw;
+    try {
+        const file = path.join(dir, "config.json");
+        if (!fs.existsSync(file))
+            return base;
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return base;
+    }
+    // 未知版本 → **拒绝按已知格式解析**（规范 V3）：回落缺省 + 可观察提示，
+    // 且**不覆盖原文件**（saveEnabled 侧同样拒绝写入）。
+    if (isPlainObject(raw) && !isKnownOnDiskVersion(raw.version)) {
+        reportForeignVersion("config.json", path.join(dir, "config.json"), raw.version);
+        return base;
+    }
+    const merged = mergeConfig(base, raw);
+    // 外置内容引用失败 → **抛错**（不静默回退）：ref 与路径都在错误消息里。
+    applyContentRefs(merged, raw, dir);
+    return merged;
+}
+/**
+ * 原子写配置（tmp + rename）：`<agentDir>/proactive/config.json`。
+ *
+ * 只改 `enabled` 一个字段，**其余内容原样保留**（用户在配置文件里写的其它字段不能被
+ * 一次开关操作抹掉）；文件不存在或读不出来 → 只写 `enabled`（不抛错）。
+ *
+ * 用途：M5c RP-11 M-4 —— `/proactive on|off` 必须落盘（重启后仍生效）。
+ */
+export function saveEnabled(enabled, opts) {
+    const agentDir = opts?.agentDir ?? resolveAgentDir();
+    const dir = proactiveDir(agentDir);
+    const file = path.join(dir, "config.json");
+    let raw = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (isPlainObject(parsed))
+            raw = parsed;
+    }
+    catch {
+        // 读不出来 → 只写 enabled（不抛错）
+    }
+    // 未知版本 → **拒绝写入**（不得用默认值覆盖用户数据，规范 V3②）。
+    if (!isKnownOnDiskVersion(raw.version)) {
+        reportForeignVersion("config.json", file, raw.version);
+        return file;
+    }
+    raw.enabled = enabled;
+    // 原子写（tmp 独占 + 同目录 rename + 0600 + fsync：配置属「不能丢」的面，规范 I3）。
+    writeAtomicFile(file, `${JSON.stringify(raw, null, 2)}\n`, { durable: true });
+    return file;
+}
+/**
+ * 未知版本的**可观察提示**（规范 V3③：不得只有静默）。
+ *
+ * 通道限制：当前只有 `task-store` 有宿主级用户可见通道（`ctx.ui.notify`，见 P-D5）；
+ * 其余落盘面只有 stderr 通道 → 记为残余限制（deviations P-D1 的 residualLimits）。
+ */
+export function reportForeignVersion(surface, file, version) {
+    const text = typeof version === "string" ? version : (JSON.stringify(version) ?? "缺失");
+    console.error(`[proactive] ${surface} 版本无法识别（version=${text}）→ 拒绝按已知格式解析（保留原文件，不覆盖）：${file}`);
+}

package/build/src/content.js

@@ -0,0 +1,198 @@
+/**
+ * CFG1 · C1：外置内容解析层（提示词 / agent 定义从配置文件搬到独立文件）。
+ *
+ * 需求原文（docs/project/config-externalization-spec.md §0）：
+ *   「在配置中，相对复杂的配置，例如提示词，agent 等等应该使用独立的文件进行维护，
+ *     在配置文件中维护，会很臃肿。」
+ *
+ * 约定（D1，规范 §4）：
+ *   `<配置目录>/config.json`  —— 只留标量 / 短枚举 + 引用
+ *   `<配置目录>/prompts/<ref>.md` —— 提示词
+ *   `<配置目录>/agents/<ref>.md`  —— agent 定义
+ *
+ * 三条硬护栏（规范 §8）：
+ *   ① **路径逃逸**：解析后必须仍在配置根目录内（含符号链接实路径）→ 否则拒绝并报错；
+ *   ② **悬空 / 空 / 格式错**：一律**抛错并指名 ref 与路径**，**禁止**静默回退默认；
+ *   ③ **半读半改**：内容**单次读入快照**（readFileSync 一次读定），避免读到拼接内容。
+ *
+ * 依赖：只用 node 内置 `fs` / `path`（不引入新运行时依赖）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * 外置内容加载失败（**显式错误**：消息里必须同时出现 ref 与路径）。
+ *
+ * 为什么单独一个错误类型：调用方（门禁 / doctor）需要**按原因分类**统计
+ * （悬空 / 空 / 格式错 / 越界），而不是靠正则匹配消息。
+ */
+export class ContentError extends Error {
+    /** 失败原因分类（门禁 / doctor 按这个分类统计）。 */
+    reason;
+    /** 出问题的引用名。 */
+    ref;
+    /** 出问题的文件路径。 */
+    path;
+    constructor(reason, ref, filePath, detail) {
+        super(`[proactive] 外置内容加载失败：ref="${ref}" 路径=${filePath} 原因=${detail}`);
+        this.name = "ContentError";
+        this.reason = reason;
+        this.ref = ref;
+        this.path = filePath;
+    }
+}
+/**
+ * 解析可选的 front-matter（`---` 包裹的 `key: value` 块）。
+ *
+ * 格式约定（**刻意极简**，不引 YAML 依赖）：
+ *   - 文件首行是 `---` → 进入 front-matter 模式，必须有**闭合**的 `---`；
+ *   - 块内每行必须是 `key: value`（key 限 `[A-Za-z0-9_.-]`）→ 否则**格式错**；
+ *   - 块之后的正文是内容本体。
+ */
+function parseFrontMatter(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return { meta: {}, body: text.trim() };
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        throw new Error("格式错：front-matter 未闭合（缺少结束的 ---）");
+    const meta = {};
+    for (const line of lines.slice(1, end)) {
+        if (line.trim() === "")
+            continue;
+        const m = /^([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line);
+        if (!m)
+            throw new Error(`格式错：front-matter 行不是 key: value —— "${line}"`);
+        meta[m[1]] = m[2].trim();
+    }
+    return { meta, body: lines.slice(end + 1).join("\n").trim() };
+}
+/**
+ * 外置内容存储（**一个配置根目录一份**）。
+ *
+ * 用法：
+ *   const store = new ContentStore(configDir, "prompts");
+ *   store.resolve("idle-probe");            // → 正文
+ *   store.resolveEntry("idle-probe");       // → {category, ref, path, meta, body}
+ *   store.list("agents");                   // → ["example-reviewer", ...]
+ */
+export class ContentStore {
+    /** 配置根目录（`config.json` 所在目录）——解析**不得**越出它。 */
+    root;
+    /** 默认类目。 */
+    category;
+    constructor(root, category) {
+        this.root = root;
+        this.category = category;
+    }
+    /** 解析一个引用 → 正文（失败抛 {@link ContentError}）。 */
+    resolve(ref) {
+        return this.resolveEntry(ref).body;
+    }
+    /** 解析一个引用 → 完整条目（失败抛 {@link ContentError}）。 */
+    resolveEntry(ref, category = this.category) {
+        const name = typeof ref === "string" ? ref.trim() : "";
+        if (name === "") {
+            throw new ContentError("format", String(ref), this.categoryDir(category), "引用为空");
+        }
+        const categoryDir = this.categoryDir(category);
+        // `<ref>.md`；ref 允许含 `/`（子目录），但**解析后必须仍在配置根目录内**。
+        const file = path.resolve(categoryDir, `${name}.md`);
+        if (!this.inside(this.root, file) || !this.inside(categoryDir, file)) {
+            throw new ContentError("escape", name, file, "路径越界（必须位于配置根目录内）");
+        }
+        let real;
+        try {
+            real = fs.realpathSync(file);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === "ENOENT") {
+                throw new ContentError("missing", name, file, "文件不存在");
+            }
+            throw new ContentError("io", name, file, `无法访问（${String(e)}）`);
+        }
+        // 符号链接指向配置根目录之外 → 同样拒绝（词法检查拦不住这一类）。
+        // 注意：比较的基准必须是**根目录的实路径**（macOS 上 /var → /private/var 是符号链接）。
+        const rootReal = this.realRoot();
+        const categoryReal = this.realPath(categoryDir);
+        if (!this.inside(rootReal, real) || !this.inside(categoryReal, real)) {
+            throw new ContentError("escape", name, real, "路径越界（实路径在配置根目录之外）");
+        }
+        let stat;
+        try {
+            stat = fs.statSync(real);
+        }
+        catch (e) {
+            throw new ContentError("io", name, real, `无法访问（${String(e)}）`);
+        }
+        if (!stat.isFile()) {
+            throw new ContentError("format", name, real, "不是普通文件");
+        }
+        // 单次读入快照（外部程序可能正在改文件 → 避免半读半改）。
+        let text;
+        try {
+            text = fs.readFileSync(real, "utf8");
+        }
+        catch (e) {
+            throw new ContentError("io", name, real, `读取失败（${String(e)}）`);
+        }
+        if (text.trim() === "") {
+            throw new ContentError("empty", name, real, "空文件（内容为空）");
+        }
+        let parsed;
+        try {
+            parsed = parseFrontMatter(text);
+        }
+        catch (e) {
+            throw new ContentError("format", name, real, e instanceof Error ? e.message : String(e));
+        }
+        if (parsed.body === "") {
+            throw new ContentError("empty", name, real, "空内容（只有 front-matter，没有正文）");
+        }
+        return { category, ref: name, path: real, meta: parsed.meta, body: parsed.body };
+    }
+    /** 枚举某个类目下的条目（`.md` 文件 → 逻辑名，排序返回；目录不存在 → 空数组）。 */
+    list(category = this.category) {
+        const dir = this.categoryDir(category);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return []; // 目录不存在 → 没有条目（不是错误）
+        }
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith(".md"))
+            .map((e) => e.name.slice(0, -3))
+            .sort();
+    }
+    /** 类目目录（`<root>/prompts` / `<root>/agents`）。 */
+    categoryDir(category) {
+        return path.join(path.resolve(this.root), category);
+    }
+    /** 根目录的**实路径**（取不到就退回词法路径）。 */
+    realRoot() {
+        return this.realPath(path.resolve(this.root));
+    }
+    /** 实路径（取不到就退回词法路径）。 */
+    realPath(p) {
+        try {
+            return fs.realpathSync(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    }
+    /** 包含性判断（`base` 自身不算越界；子路径才算）。 */
+    inside(base, target) {
+        const root = path.resolve(base);
+        const t = path.resolve(target);
+        return t.startsWith(root + path.sep);
+    }
+}