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

package/build/src/config.js

@@ -0,0 +1,990 @@
+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;
+}
+/** 全部配置项（顺序 = 清单展示顺序）。 */
+export const CONFIG_KEY_SPECS = [
+    {
+        path: "enabled",
+        section: "总开关与检测",
+        type: "boolean",
+        defaultValue: true,
+        range: "true / false",
+        description: "主动性总开关：关掉后定时投递与空闲触发都不发生。",
+    },
+    {
+        path: "idleDetect",
+        section: "总开关与检测",
+        type: "enum",
+        defaultValue: "off",
+        values: ["terminal", "input-only", "off"],
+        range: "terminal | input-only | off",
+        description: "空闲检测档位：terminal（仅 TUI）/ input-only（只靠输入事件）/ off（关闭）。",
+    },
+    {
+        path: "askTimeoutMs",
+        section: "总开关与检测",
+        type: "number",
+        defaultValue: 120000,
+        range: "≥ 0（毫秒）",
+        description: "向你提问后等待回答的超时（毫秒）。",
+        aliases: ["asktimeout", "asktimeoutms", "questiontimeout"],
+    },
+    {
+        path: "idleTrigger.enabled",
+        section: "空闲触发",
+        type: "boolean",
+        defaultValue: false,
+        range: "true / false",
+        description: "空闲触发开关（缺省关 → 装上不打扰你）。",
+        aliases: ["idletriggerenabled", "idletriggeron"],
+    },
+    {
+        path: "idleTrigger.afterMs",
+        section: "空闲触发",
+        type: "number",
+        defaultValue: 600000,
+        range: "≥ 0（毫秒）",
+        description: "连续空闲多久后触发一次（毫秒）。",
+        aliases: ["idletimeout", "idleafterms", "idletriggerafterms", "idleafter"],
+    },
+    {
+        path: "idleTrigger.intent",
+        section: "空闲触发",
+        type: "enum",
+        defaultValue: "wake",
+        values: ["wake", "interrupt", "queue", "notify"],
+        range: "wake | interrupt | queue | notify",
+        description: "空闲触发时的投递意图（wake 唤醒 / interrupt 打断 / queue 排队 / notify 知会）。",
+    },
+    {
+        path: "idleTrigger.askUser",
+        section: "空闲触发",
+        type: "boolean",
+        range: "true / false（不写 = 不问）",
+        description: "空闲触发时是否向你提问。",
+        aliases: ["askuser"],
+    },
+    {
+        path: "idleTrigger.prompt",
+        section: "空闲触发",
+        type: "string",
+        defaultValue: "",
+        range: "任意文本",
+        description: "空闲触发时投给模型的正文（空 = 用缺省）。",
+    },
+    {
+        path: "idleTrigger.promptRef",
+        section: "空闲触发",
+        type: "string",
+        range: "<配置目录>/prompts/<名字>.md",
+        description: "引用外部提示词文件（比把长提示词塞进 JSON 好维护）。",
+        aliases: ["promptref"],
+    },
+    {
+        path: "limits.minGapMs",
+        section: "频控与静默",
+        type: "number",
+        defaultValue: 300000,
+        range: "≥ 0（毫秒）",
+        description: "两次主动打扰之间的最小间隔（毫秒）。",
+        aliases: ["mingap", "mingapms", "mininterval"],
+    },
+    {
+        path: "limits.maxPerHour",
+        section: "频控与静默",
+        type: "number",
+        defaultValue: 6,
+        range: "≥ 0（次 / 小时）",
+        description: "每小时最多主动打扰几次。",
+        aliases: ["maxperhour", "hourlymax", "perhour"],
+    },
+    {
+        path: "limits.quietHours.from",
+        section: "频控与静默",
+        type: "string",
+        defaultValue: "22:00",
+        range: "HH:MM",
+        description: "静默时段开始（这段时间不主动打扰）。",
+    },
+    {
+        path: "limits.quietHours.to",
+        section: "频控与静默",
+        type: "string",
+        defaultValue: "08:00",
+        range: "HH:MM",
+        description: "静默时段结束。",
+    },
+    {
+        path: "decision.enabled",
+        section: "决策环",
+        type: "boolean",
+        defaultValue: true,
+        range: "true / false",
+        description: "决策环开关（false = 退回旧的 afterMs 判定）。",
+    },
+    {
+        path: "decision.threshold",
+        section: "决策环",
+        type: "number",
+        defaultValue: 1,
+        range: "≥ 0",
+        description: "触发阈值：分数 ≥ 阈值才触发。",
+        aliases: ["threshold", "scorethreshold"],
+    },
+    {
+        path: "decision.observeRatio",
+        section: "决策环",
+        type: "number",
+        defaultValue: 0.5,
+        range: "0 ~ 1",
+        description: "观察带下界（相对阈值）：这一段只记账、不打扰。",
+        aliases: ["observeratio", "observethreshold"],
+    },
+    {
+        path: "decision.repeatedInterruptionWeight",
+        section: "决策环",
+        type: "number",
+        defaultValue: 0.5,
+        range: "≥ 0",
+        description: "近 1 小时重复打扰时，打断代价的加成。",
+        aliases: ["repeatedinterruptionweight"],
+    },
+    {
+        path: "decision.busyInterruptionWeight",
+        section: "决策环",
+        type: "number",
+        defaultValue: 1,
+        range: "≥ 0",
+        description: "你正忙（代理在跑）时，打断代价的加成。",
+        aliases: ["busyinterruptionweight"],
+    },
+    {
+        path: "decision.quietInterruptionWeight",
+        section: "决策环",
+        type: "number",
+        defaultValue: 1,
+        range: "≥ 0",
+        description: "落在静默时段时，打断代价的加成。",
+        aliases: ["quietinterruptionweight"],
+    },
+    {
+        path: "peerWatch.enabled",
+        section: "跨会话协作",
+        type: "boolean",
+        defaultValue: false,
+        range: "true / false",
+        description: "空闲时是否主动询问其它会话的进度。",
+        aliases: ["peerwatchenabled", "peerwatchon"],
+    },
+    {
+        path: "peerWatch.afterIdleMs",
+        section: "跨会话协作",
+        type: "number",
+        defaultValue: 600000,
+        range: "≥ 0（毫秒）",
+        description: "连续空闲多久后才去询问别的会话。",
+        aliases: ["afteridlems", "peeridle"],
+    },
+    {
+        path: "contentRefs",
+        section: "外置内容与版本",
+        type: "object",
+        range: "{ 名字: { promptRef | agentRef } }",
+        description: "引用外部提示词 / agent 定义的表（名字随便起，值里写 promptRef 或 agentRef）。",
+        aliases: ["contentrefs"],
+    },
+    {
+        path: "version",
+        section: "外置内容与版本",
+        type: "string",
+        defaultValue: ON_DISK_VERSION,
+        range: ON_DISK_VERSION,
+        description: "落盘格式版本（当前只认 v1）。",
+    },
+];
+/** 已知**容器**路径（对象本身不是可配置项，只承载子项）。 */
+const CONFIG_CONTAINER_PATHS = [
+    "idleTrigger",
+    "limits",
+    "limits.quietHours",
+    "decision",
+    "peerWatch",
+];
+/** 归一化：只留小写字母与数字（别名 / 编辑距离比较用）。 */
+function normalizeKey(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/** 编辑距离（Levenshtein）——「最相近的已知键」用。 */
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_unused, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur[j] = Math.min((cur[j - 1] ?? 0) + 1, (prev[j] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        prev = cur;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * 「你是不是想写 …」的建议：给一个写错/不认识的键名，指到最相近的已知键。
+ *
+ * 两级策略（先精确后模糊）：
+ * 1. **别名精确命中**（path 本身或口语别名）—— 用户嘴里的说法（「空闲超时」→ `idleTrigger.afterMs`）；
+ * 2. **编辑距离最近**（path 与口语别名都参与比对；带路径时比全名，不带路径时比末段）
+ *    —— 拼写笔误（「maxPerHOur」「ideltimeout」）。
+ *
+ * 毫无相近项（距离 > 2）时返回 undefined —— **不乱指**（乱指比不指更坏）。
+ */
+export function suggestConfigKey(unknown) {
+    const q = normalizeKey(unknown);
+    if (q === "")
+        return undefined;
+    for (const spec of CONFIG_KEY_SPECS) {
+        for (const alias of [spec.path, ...(spec.aliases ?? [])]) {
+            if (normalizeKey(alias) === q)
+                return spec.path;
+        }
+    }
+    const isPath = unknown.includes(".");
+    let best;
+    for (const spec of CONFIG_KEY_SPECS) {
+        const last = spec.path.split(".").pop() ?? spec.path;
+        const dFull = editDistance(q, normalizeKey(spec.path));
+        const dLast = editDistance(q, normalizeKey(last));
+        // 别名同样参与模糊比对：用户拼错的常是「口语别名」（ideltimeout ← idletimeout），
+        // 只比 path 会漏掉这类 → 指不出「你是不是想写 idleTrigger.afterMs」。
+        const dAlias = Math.min(Infinity, ...(spec.aliases ?? []).map((a) => editDistance(q, normalizeKey(a))));
+        const score = isPath ? Math.min(dFull, dAlias) : Math.min(dLast, dFull, dAlias);
+        if (best === undefined || score < best.score) {
+            best = { path: spec.path, score };
+            continue;
+        }
+        if (score === best.score) {
+            // 平手 → 取更短的路径（顶层项优先），再按字典序（结果确定）。
+            const shorter = spec.path.length < best.path.length;
+            const sameLen = spec.path.length === best.path.length && spec.path < best.path;
+            if (shorter || sameLen)
+                best = { path: spec.path, score };
+        }
+    }
+    if (best === undefined || best.score > 2)
+        return undefined;
+    return best.path;
+}
+/** 未知配置项 → 抛这个错（**不得**静默忽略）。 */
+export class ConfigValidationError extends Error {
+    /** 逐条问题（机器可读）。 */
+    issues;
+    constructor(issues) {
+        super(formatConfigIssues(issues));
+        this.name = "ConfigValidationError";
+        this.issues = issues;
+    }
+}
+/** 问题的类型名（人话）。 */
+function typeLabel(spec) {
+    switch (spec.type) {
+        case "boolean":
+            return "布尔（true / false）";
+        case "number":
+            return "数字";
+        case "string":
+            return "字符串";
+        case "enum":
+            return `枚举（${spec.values?.join(" | ") ?? ""}）`;
+        case "object":
+            return "对象";
+    }
+}
+/** 实际值的类型名（人话）。 */
+function valueTypeLabel(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "数组";
+    return typeof value;
+}
+/** 值是否与规格相符。 */
+function matchesSpec(spec, value) {
+    switch (spec.type) {
+        case "boolean":
+            return typeof value === "boolean";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "string":
+            return typeof value === "string";
+        case "enum":
+            return typeof value === "string" && (spec.values ?? []).includes(value);
+        case "object":
+            return isPlainObject(value);
+    }
+}
+/**
+ * 校验配置里的**键**（M8）：未知键 → 指名（阻断加载）；类型不符 → 指名（不阻断，按缺省回落）。
+ *
+ * 为什么类型不符不阻断：既有契约是「字段类型错误 → 回退缺省且不抛错」
+ * （`pi-proactive/tests/config.test.ts` 锁着这条）→ 改它会误伤既有用户配置。
+ * 但「静默」必须改成「**指名**」：问题照样进清单与体检报告。
+ */
+export function validateConfig(raw, file) {
+    const issues = [];
+    if (!isPlainObject(raw))
+        return issues;
+    const byPath = new Map(CONFIG_KEY_SPECS.map((spec) => [spec.path, spec]));
+    const walk = (obj, prefix) => {
+        for (const [key, value] of Object.entries(obj)) {
+            const p = prefix === "" ? key : `${prefix}.${key}`;
+            if (p === "contentRefs") {
+                walkContentRefs(value, p, file, issues);
+                continue;
+            }
+            const spec = byPath.get(p);
+            if (spec !== undefined) {
+                if (!matchesSpec(spec, value)) {
+                    issues.push({
+                        category: "type-mismatch",
+                        key: p,
+                        file,
+                        message: `配置项 "${p}" 类型不对（期望 ${typeLabel(spec)}，实际 ${valueTypeLabel(value)}）` +
+                            `→ 已按缺省值处理（文件：${file}）`,
+                    });
+                }
+                continue;
+            }
+            if (CONFIG_CONTAINER_PATHS.includes(p)) {
+                if (isPlainObject(value)) {
+                    walk(value, p);
+                }
+                else {
+                    issues.push({
+                        category: "type-mismatch",
+                        key: p,
+                        file,
+                        message: `配置项 "${p}" 类型不对（期望对象，实际 ${valueTypeLabel(value)}）→ 已按缺省值处理（文件：${file}）`,
+                    });
+                }
+                continue;
+            }
+            const suggestion = suggestConfigKey(p);
+            issues.push({
+                category: "unknown-key",
+                key: p,
+                file,
+                ...(suggestion === undefined ? {} : { suggestion }),
+                message: `未知配置项 "${p}"（文件：${file}）` +
+                    (suggestion === undefined ? "→ 没有相近的已知配置项" : `→ 你是不是想写 "${suggestion}"？`),
+            });
+        }
+    };
+    walk(raw, "");
+    return issues;
+}
+/** `contentRefs` 的内层键（只允许 promptRef / agentRef）。 */
+function walkContentRefs(value, prefix, file, issues) {
+    if (!isPlainObject(value)) {
+        issues.push({
+            category: "type-mismatch",
+            key: prefix,
+            file,
+            message: `配置项 "${prefix}" 类型不对（期望对象，实际 ${valueTypeLabel(value)}）→ 已按缺省值处理（文件：${file}）`,
+        });
+        return;
+    }
+    for (const [name, entry] of Object.entries(value)) {
+        if (!isPlainObject(entry))
+            continue;
+        for (const key of Object.keys(entry)) {
+            if (key === "promptRef" || key === "agentRef")
+                continue;
+            const p = `${prefix}.${name}.${key}`;
+            issues.push({
+                category: "unknown-key",
+                key: p,
+                file,
+                message: `未知配置项 "${p}"（文件：${file}）→ 只允许 promptRef 或 agentRef`,
+            });
+        }
+    }
+}
+/** 问题清单 → 人话 + 机器可读的一整段文本。 */
+export function formatConfigIssues(issues) {
+    const lines = ["[proactive] 配置校验失败（写错的配置项不会被静默忽略）："];
+    for (const issue of issues) {
+        lines.push(`  · ${issue.message}`);
+        lines.push(`    未知键名：${issue.key}` +
+            `    机器可读：CONFIG_${issue.category === "unknown-key" ? "UNKNOWN_KEY" : "TYPE_MISMATCH"}` +
+            ` key="${issue.key}" file="${issue.file}"` +
+            (issue.suggestion === undefined ? "" : ` suggestion="${issue.suggestion}"`));
+    }
+    return lines.join("\n");
+}
+/** 按点号路径取值（取不到 → undefined）。 */
+function readPath(raw, dotted) {
+    let cur = raw;
+    for (const seg of dotted.split(".")) {
+        if (!isPlainObject(cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+/**
+ * 读配置清单（M6）：全部项 + 当前值（**文件里写的**）+ 缺省值 + 取值范围 + 说明 + 问题清单。
+ *
+ * 为什么「当前值」取自**文件**而不是合并后的运行期配置：文件才是用户写的东西；
+ * 运行期配置在有未知项时会整体回落缺省 → 用它会把「你写的值」显示成「缺省值」（更迷惑）。
+ */
+export function readConfigReport(opts) {
+    const dir = proactiveDir(opts?.agentDir ?? resolveAgentDir());
+    const file = path.join(dir, "config.json");
+    let raw;
+    let exists = false;
+    try {
+        exists = fs.existsSync(file);
+        if (exists)
+            raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        raw = undefined;
+    }
+    const items = CONFIG_KEY_SPECS.map((spec) => ({
+        path: spec.path,
+        section: spec.section,
+        type: typeLabel(spec),
+        current: readPath(raw, spec.path),
+        defaultValue: spec.defaultValue,
+        range: spec.range,
+        description: spec.description,
+    }));
+    return { file, exists, items, issues: validateConfig(raw, file) };
+}
+/** 备份文件后缀（M9）。 */
+export const CONFIG_BACKUP_SUFFIX = ".bak";
+/**
+ * 原子写配置（M9）：**先备份**再原子写（tmp 独占 + 同目录 rename + 0600 + fsync）。
+ *
+ * 备份 = 写前的那份内容（`<config.json>.bak`）→ 撤销就是把它写回去。
+ */
+export function writeConfigAtomic(next, opts) {
+    const dir = proactiveDir(opts?.agentDir ?? resolveAgentDir());
+    const file = path.join(dir, "config.json");
+    let backup;
+    if (opts?.backup !== false && fs.existsSync(file)) {
+        backup = `${file}${CONFIG_BACKUP_SUFFIX}`;
+        writeAtomicFile(backup, fs.readFileSync(file, "utf8"), { durable: true });
+    }
+    writeAtomicFile(file, `${JSON.stringify(next, null, 2)}\n`, { durable: true });
+    return backup === undefined ? { file } : { file, backup };
+}
+/**
+ * 撤销上一次配置改动（M9）：把备份写回配置文件（原子写），并消费掉这份备份。
+ *
+ * 没有备份 → 如实说「没有可撤销的改动」（不抛错）。
+ */
+export function undoConfigChange(opts) {
+    const dir = proactiveDir(opts?.agentDir ?? resolveAgentDir());
+    const file = path.join(dir, "config.json");
+    const backup = `${file}${CONFIG_BACKUP_SUFFIX}`;
+    if (!fs.existsSync(backup)) {
+        return { ok: false, file, message: `没有可撤销的改动：找不到备份文件 ${backup}` };
+    }
+    writeAtomicFile(file, fs.readFileSync(backup, "utf8"), { durable: true });
+    fs.rmSync(backup, { force: true });
+    return { ok: true, file, message: `已撤销上一次配置改动（备份 ${backup} 已写回 ${file}）` };
+}
+/**
+ * 读取配置（含**外置内容解析**）。
+ *
+ * 失败语义（与「坏 JSON 回落缺省」刻意不同）：
+ * - `config.json` 读不出 / 解析失败 → 回落缺省（老契约：配置文件坏掉不得拖垮宿主）；
+ * - **外置内容引用失败** → **抛错**（规范 §9：失败必须抛错并指名 ref 与路径）。
+ */
+export function loadConfig(opts) {
+    const base = defaultConfig();
+    const dir = proactiveDir();
+    const file = path.join(dir, "config.json");
+    let raw;
+    try {
+        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", file, raw.version);
+        return base;
+    }
+    // M8：**未知配置项 → 报错并指名**（不再静默忽略：拼错键名是最恶劣的一种体验）。
+    const issues = validateConfig(raw, file);
+    const unknown = issues.filter((issue) => issue.category === "unknown-key");
+    if (unknown.length > 0)
+        throw new ConfigValidationError(unknown);
+    // 类型不符 → **指名但不阻断**（既有契约：按缺省回落，不抛错）。
+    for (const issue of issues)
+        console.error(`[proactive] ${issue.message}`);
+    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;
+    // 原子写 + **写前备份**（M9：tmp 独占 + 同目录 rename + 0600 + fsync；备份让「撤销上一次改动」可行）。
+    writeConfigAtomic(raw, { agentDir });
+    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}`);
+}