pi-proactive 0.2.0-beta.2 → 0.2.0-beta.3

package/build/src/config.js

@@ -409,6 +409,505 @@ function applyContentRefs(cfg, raw, dir) {
     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}）` };
+}
 /**
  * 读取配置（含**外置内容解析**）。
  *
@@ -419,9 +918,9 @@ function applyContentRefs(cfg, raw, dir) {
 export function loadConfig(opts) {
     const base = defaultConfig();
     const dir = proactiveDir();
+    const file = path.join(dir, "config.json");
     let raw;
     try {
-        const file = path.join(dir, "config.json");
         if (!fs.existsSync(file))
             return base;
         raw = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -432,9 +931,17 @@ export function loadConfig(opts) {
     // 未知版本 → **拒绝按已知格式解析**（规范 V3）：回落缺省 + 可观察提示，
     // 且**不覆盖原文件**（saveEnabled 侧同样拒绝写入）。
     if (isPlainObject(raw) && !isKnownOnDiskVersion(raw.version)) {
-        reportForeignVersion("config.json", path.join(dir, "config.json"), 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);
@@ -467,8 +974,8 @@ export function saveEnabled(enabled, opts) {
         return file;
     }
     raw.enabled = enabled;
-    // 原子写（tmp 独占 + 同目录 rename + 0600 + fsync：配置属「不能丢」的面，规范 I3）。
-    writeAtomicFile(file, `${JSON.stringify(raw, null, 2)}\n`, { durable: true });
+    // 原子写 + **写前备份**（M9：tmp 独占 + 同目录 rename + 0600 + fsync；备份让「撤销上一次改动」可行）。
+    writeConfigAtomic(raw, { agentDir });
     return file;
 }
 /**