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

package/build/src/activity.js

@@ -0,0 +1,130 @@
+/**
+ * 活动度追踪：维护「用户空闲基线」与对端消息时间。
+ *
+ * 规则（IDLEFIX 修订，依据 `pi-proactive/docs/idle-ground-truth.md` §6.2 前提 1/2）：
+ * - **两个基线**：
+ *   - `lastUserActivityAt` —— **仅用户输入**刷新（`mark("user")`；`terminal` 档的终端按键）。
+ *     **语义保留不变**：`idleDetect` 档位、`input-only` vs `terminal` 的差异，
+ *     仍然只决定**用户输入**是否被计入。
+ *   - `lastAnyActivityAt` —— 「**最近任何活动**」基线：用户输入 **+ 代理活动**
+ *     （模型回合起止 / 工具调用 / 助手消息落定）都刷新它 → **空闲判定用它**
+ *     （`snapshot().idleForMs = now - lastAnyActivityAt`）。
+ * - `peer` 消息只记录 `lastPeerMessageAt`，**不刷新任何基线**（防两个 agent 互聊掩盖用户离开）。
+ * - `agent` 活动**只**刷新「最近任何活动」基线，**不**刷新用户基线（用户输入语义保留）。
+ * - `self`（插件自己投递的主动消息）**不刷新任何基线** —— 否则插件会被自己的动作
+ *   无限推迟下一次触发（自锁）。
+ */
+export class ActivityTracker {
+    idleDetect;
+    now;
+    isBusy;
+    lastUserActivityAt;
+    /** 「最近任何活动」基线（用户输入 + 代理活动）；空闲判定用这个。 */
+    lastAnyActivityAt;
+    lastPeerMessageAt;
+    detachTerminalInput;
+    constructor(opts = {}) {
+        this.idleDetect = opts.idleDetect ?? "off";
+        this.now = opts.now ?? Date.now;
+        this.isBusy = opts.isBusy ?? (() => false);
+        // 初始基线 = 构造时刻，否则刚启动就被判空闲。
+        this.lastUserActivityAt = this.now();
+        this.lastAnyActivityAt = this.lastUserActivityAt;
+    }
+    /**
+     * 记一次活动。
+     *
+     * - `user`：刷新**用户基线**与「最近任何活动」基线；
+     * - `agent`：只刷新「最近任何活动」基线（代理在干活 → 用户不是「离开了」）；
+     * - `peer`：只记 `lastPeerMessageAt`；
+     * - `self`：**什么都不刷新**（插件自投递 → 防自锁）。
+     */
+    mark(actor) {
+        const at = this.now();
+        if (actor === "user") {
+            this.lastUserActivityAt = at;
+            this.lastAnyActivityAt = at;
+        }
+        else if (actor === "agent") {
+            this.lastAnyActivityAt = at;
+        }
+        else if (actor === "peer") {
+            this.lastPeerMessageAt = at;
+        }
+        // "self"：插件自己投递的主动消息 → 两个基线都不刷新（自锁防护）。
+    }
+    /**
+     * 快照。
+     *
+     * - `lastUserActivityAt` —— 距最近**用户输入**（语义保留，不受代理活动影响）；
+     * - `idleForMs` —— 距最近**任何活动**（判定基线；用户输入 + 代理活动）。
+     * - `busy` —— 宿主注入的忙闲信号（由调用方决定「代理是否已交回控制权」）。
+     */
+    snapshot() {
+        const now = this.now();
+        let busy = false;
+        try {
+            busy = this.isBusy();
+        }
+        catch {
+            busy = false; // 宿主注入失败不得影响快照
+        }
+        return {
+            lastUserActivityAt: this.lastUserActivityAt,
+            ...(this.lastPeerMessageAt !== undefined ? { lastPeerMessageAt: this.lastPeerMessageAt } : {}),
+            busy,
+            idleForMs: now - this.lastAnyActivityAt,
+        };
+    }
+    setIdleDetect(v) {
+        this.idleDetect = v;
+        // 非 terminal 模式不再使用终端输入：立刻解除订阅。
+        if (v !== "terminal")
+            this.detach();
+    }
+    /**
+     * 登记终端输入订阅的退订函数（宿主 `ctx.ui.onTerminalInput()` 的返回值）。
+     * 非 `terminal` 模式直接退订——此时终端按键不作为活动来源。
+     */
+    attachTerminalInput(unsubscribe) {
+        if (this.idleDetect !== "terminal") {
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* 退订失败不影响追踪 */
+            }
+            this.detachTerminalInput = undefined;
+            return;
+        }
+        this.detachTerminalInput = unsubscribe;
+    }
+    /**
+     * 宿主把终端按键事件喂进来。仅 `terminal` 模式计为用户活动（刷新**两个**基线）；
+     * 其它模式忽略（RPC 下 `onTerminalInput` 是 no-op，见 implementation-spec §6.1 第 4 行）。
+     */
+    handleTerminalInput() {
+        if (this.idleDetect !== "terminal")
+            return;
+        try {
+            const at = this.now();
+            this.lastUserActivityAt = at;
+            this.lastAnyActivityAt = at;
+        }
+        catch {
+            /* 时间源异常不得让宿主崩溃 */
+        }
+    }
+    detach() {
+        const unsub = this.detachTerminalInput;
+        this.detachTerminalInput = undefined;
+        if (!unsub)
+            return;
+        try {
+            unsub();
+        }
+        catch {
+            /* 退订失败不影响追踪 */
+        }
+    }
+}

package/build/src/commands.js

@@ -0,0 +1,496 @@
+import { randomUUID } from "node:crypto";
+import { IDLE_ENABLE_HINT, effectiveIdleDetect } from "./idle.js";
+import { DEFAULT_WHEN_MS, SUPPORTED_DURATION_FORMATS, SUPPORTED_WHEN_FORMATS, parseScheduleExpression, } from "./scheduler.js";
+import { resolveAgentDir } from "./config.js";
+import { formatHealthReport, healthToJson } from "./health.js";
+import { formatLineageHistory } from "./lineage.js";
+import { formatPeerDirectory, formatPeerList } from "./peer.js";
+import { Registry } from "./registry.js";
+const DETECT_LABEL = {
+    terminal: "终端输入",
+    "input-only": "输入事件（保守模式）",
+    off: "关闭",
+};
+/** 时长 → 人类可读（10m / 2h30m / 45s）。 */
+export function formatDuration(ms) {
+    const v = Math.max(0, Math.round(ms / 1000));
+    if (v < 60)
+        return `${v}s`;
+    const m = Math.floor(v / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    const rest = m % 60;
+    return rest === 0 ? `${h}h` : `${h}h${rest}m`;
+}
+/**
+ * 由「配置 + 活动快照 + 空闲判定」拼出 `/proactive status` 的状态字段。
+ * 集成入口只需把 evaluateIdle 的结果与 tracker 快照丢进来。
+ */
+export function buildStatusState(args) {
+    const { config, snapshot, decision } = args;
+    return {
+        enabled: config.enabled,
+        idleDetect: decision.effectiveIdleDetect,
+        idleForMs: snapshot.idleForMs,
+        idleTriggerEnabled: config.idleTrigger.enabled,
+        afterMs: config.idleTrigger.afterMs,
+        askTimeoutMs: config.askTimeoutMs,
+        limits: {
+            minGapMs: config.limits.minGapMs,
+            maxPerHour: config.limits.maxPerHour,
+            ...(config.limits.quietHours ? { quietHours: config.limits.quietHours } : {}),
+        },
+        ...(config.idleTrigger.enabled ? { nextTriggerInMs: decision.remainingMs } : {}),
+        busy: snapshot.busy,
+    };
+}
+/** `/proactive status` 的多行文本。 */
+export function formatStatus(state) {
+    const lines = [];
+    lines.push(`主动性：${state.enabled ? "已开启" : "已关闭"} (enabled=${state.enabled})`);
+    lines.push(`空闲触发：${state.idleTriggerEnabled ? `开 · 阈值 ${formatDuration(state.afterMs)}` : "关"} (idleTriggerEnabled=${state.idleTriggerEnabled})`);
+    lines.push(`空闲检测：${DETECT_LABEL[state.idleDetect]} (idleDetect=${state.idleDetect})`);
+    lines.push(`空闲计时：${state.idleTriggerEnabled ? formatDuration(state.idleForMs) : "—（未启用）"} (idleForMs=${state.idleForMs})`);
+    lines.push(`提问超时：${formatDuration(state.askTimeoutMs)} (askTimeoutMs=${state.askTimeoutMs})`);
+    const qh = state.limits.quietHours
+        ? ` · 静默时段 ${state.limits.quietHours.from}-${state.limits.quietHours.to} (quietHours=${state.limits.quietHours.from}-${state.limits.quietHours.to})`
+        : " · 静默时段 未设置 (quietHours=无)";
+    lines.push(`限制：最短间隔 ${formatDuration(state.limits.minGapMs)} (minGapMs=${state.limits.minGapMs}) · 每小时上限 ${state.limits.maxPerHour} (maxPerHour=${state.limits.maxPerHour})${qh}`);
+    if (!state.idleTriggerEnabled) {
+        lines.push("下次空闲触发：—（空闲触发未开启） (nextTriggerInMs=—)");
+    }
+    else if (state.nextTriggerInMs === undefined) {
+        lines.push("下次空闲触发：已达阈值 (nextTriggerInMs=0)");
+    }
+    else if (state.nextTriggerInMs <= 0) {
+        lines.push("下次空闲触发：已达阈值 (nextTriggerInMs=0)");
+    }
+    else {
+        lines.push(`下次空闲触发：还有 ${formatDuration(state.nextTriggerInMs)} (nextTriggerInMs=${state.nextTriggerInMs})`);
+    }
+    return lines.join("\n");
+}
+/** 空闲判定的用户可见说明（为什么触发 / 为什么没触发）。 */
+export function formatIdleDecision(decision) {
+    switch (decision.reason) {
+        case "eligible":
+            return `已达到空闲阈值（空闲 ${formatDuration(decision.idleForMs)}），可以主动推进一次。`;
+        case "disabled":
+            return "主动性已关闭，不会主动打扰（/proactive on 打开）。";
+        case "idle-trigger-disabled":
+            return `空闲触发未开启，不会主动打扰。${IDLE_ENABLE_HINT}`;
+        case "detect-off":
+            return `空闲检测已关闭：没有输入信号时不会猜你在不在。${IDLE_ENABLE_HINT}`;
+        case "threshold":
+            return `还没到空闲阈值，还差 ${formatDuration(decision.remainingMs)}。`;
+        case "busy":
+            return "代理正在忙，本轮不打断，等这轮结束再说。";
+        case "cooldown":
+            return decision.cooldownRemainingMs !== undefined
+                ? `冷却中：上次主动后至少要再等 ${formatDuration(decision.cooldownRemainingMs)}。`
+                : "冷却中：上次主动后需要再等一会儿。";
+        case "rate-limit":
+            return `本小时主动次数已用满（上限 ${decision.maxPerHour ?? "?"} 次），等下一个小时或手动放宽。`;
+        case "quiet-hours":
+            return decision.quietHours
+                ? `静默时段（${decision.quietHours.from}-${decision.quietHours.to}）内不主动打扰。`
+                : "静默时段内不主动打扰。";
+        case "deliver-failed":
+            return "投递失败：这一轮没有推进（详见插件日志），下一轮会重试。";
+        default:
+            return "当前不触发。";
+    }
+}
+/**
+ * 打开/关闭主动性开关（**已落盘**：X4 起写 `<agent-dir>/proactive/config.json` 的 `enabled`，重启后仍生效）。
+ * 返回新配置，不就地修改传入对象。
+ */
+export function toggleEnabled(config, on) {
+    return {
+        ...config,
+        enabled: on,
+        idleTrigger: { ...config.idleTrigger },
+        limits: { ...config.limits },
+    };
+}
+/** `/proactive on|off` 的用户可见返回文案。 */
+export function formatToggle(config, on) {
+    const idle = config.idleTrigger.enabled ? "开" : "关";
+    const lines = on
+        ? [`主动性：已开启`, `已经开启（当前：空闲触发 ${idle}）`]
+        : [`主动性：已关闭`, `已经关闭（当前：空闲触发 ${idle}）`];
+    lines.push("提示：开关已落盘，重启后仍生效。");
+    return lines.join("\n");
+}
+/**
+ * `/proactive idle on|off`：开关空闲触发（**内存态**：不落盘，重启后回到配置文件里的设置）。
+ *
+ * 顺带把「空闲检测档位 = off」切到 "input-only"：检测档位关着时，空闲触发开了也不会真的触发
+ * （默认配置就是 idleDetect="off"）→ 开关必须让功能**可达**，否则命令等于空转。
+ * 主动性总开关（`enabled`）不受影响：用户 `/proactive off` 之后仍需 `/proactive on`。
+ */
+export function toggleIdleTrigger(config, on) {
+    return {
+        ...config,
+        idleDetect: on && config.idleDetect === "off" ? "input-only" : config.idleDetect,
+        idleTrigger: { ...config.idleTrigger, enabled: on },
+        limits: { ...config.limits },
+    };
+}
+export function formatIdleToggle(config, on, info = {}) {
+    const lines = [];
+    if (on) {
+        lines.push(`空闲触发：开 · 阈值 ${formatDuration(config.idleTrigger.afterMs)} (idleTriggerEnabled=true)`);
+    }
+    else {
+        lines.push("空闲触发：关 (idleTriggerEnabled=false)");
+    }
+    if (info.detectSwitched) {
+        lines.push("空闲检测档位原为 off，已切到 input-only（否则空闲触发不会真的触发）");
+    }
+    if (info.masterOff) {
+        lines.push("注意：主动性总开关当前是关的，需 /proactive on 后空闲触发才会真的触发");
+    }
+    lines.push("提示：这是内存态，重启后回到配置文件里的设置。");
+    return lines.join("\n");
+}
+/** 相对到期时间（还有多久 / 已过期多久）。 */
+export function formatDueRelative(dueAt, now = Date.now()) {
+    const diff = dueAt - now;
+    return diff >= 0 ? `还有 ${formatDuration(diff)}` : `已过期 ${formatDuration(-diff)}`;
+}
+/** `/proactive tasks` 的用户可见列表（每行：id / 类型 / 相对到期 / 意图 / 归属 / 开关）。 */
+export function formatTaskList(tasks, now = Date.now()) {
+    if (tasks.length === 0)
+        return "没有待触发任务";
+    const lines = [`待触发任务 ${tasks.length} 个：`];
+    for (const t of tasks) {
+        lines.push(`${t.id} · ${t.schedule} · ${formatDueRelative(t.dueAt, now)} · intent=${t.intent} · scope=${t.scope} · enabled=${t.enabled}`);
+    }
+    return lines.join("\n");
+}
+/** `/proactive cancel <id>` 成功后的回执。 */
+export function formatCancelResult(task) {
+    return `已取消 ${task.id} · ${task.schedule} · intent=${task.intent}`;
+}
+/** `/proactive cancel <id>` 找不到任务时的回执（列出当前任务，便于用户改 id）。 */
+export function formatCancelMissing(id, tasks) {
+    const ids = tasks.map((t) => t.id).join("、");
+    return ids === "" ? `找不到编号 ${id} · 当前没有任务` : `找不到编号 ${id} · 当前任务：${ids}`;
+}
+/** 排期写法的用法说明（错误提示与命令面共用同一份，避免文案漂移）。 */
+export const SCHEDULE_USAGE = `用法：/proactive in <时长> <内容>、/proactive at <HH:MM> <内容>、/proactive every <时长> <内容>` +
+    `（时长支持 ${SUPPORTED_DURATION_FORMATS}）`;
+/** 绝对时间（本地时区）→ `YYYY-MM-DD HH:MM:SS`。 */
+export function formatAbsoluteTime(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/**
+ * 排期成功后的回执：任务 id + 相对到期 + 绝对到期（repeat 另给周期）。
+ */
+export function formatScheduleResult(task, now = Date.now(), info = {}) {
+    const lines = [];
+    lines.push(`已排期 ${task.id}`);
+    lines.push(`类型：${task.schedule === "repeat" ? "重复" : "单次"} (schedule=${task.schedule})`);
+    lines.push(`到期：${formatDueRelative(task.dueAt, now)}（${formatAbsoluteTime(task.dueAt)}）`);
+    if (task.schedule === "repeat" && task.intervalMs !== undefined) {
+        lines.push(`周期：${formatDuration(task.intervalMs)}`);
+    }
+    if (info.rolledToTomorrow)
+        lines.push("说明：今天的该时刻已过，已顺延到明天");
+    if (info.defaulted)
+        lines.push(`说明：未指定触发时间，按默认时长 ${formatDuration(DEFAULT_WHEN_MS)} 处理`);
+    lines.push(`任务内容：${task.prompt}`);
+    return lines.join("\n");
+}
+/** 错误 → 人可读文案（命令面与工具面共用，避免两处各写一份）。 */
+export function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * human-gated 回执文案（**单一真源**：模型工具面用；命令面不经过这里 —— 命令面由人触发）。
+ *
+ * 口径（brief-v4 §9.1）：「全部自然语言驱动」落在**入口可达性**上，不落在「模型可自主执行一切」上。
+ */
+export function formatHumanGatedNotice(notice) {
+    return (`proactive: 该能力（${notice.capabilityId}）属 human-gated：${notice.reason}` +
+        `模型不得自行执行。请人工执行：${notice.humanCommand}`);
+}
+/** 命令面清单（**单一真源**：命令描述、未知子命令提示、能力目录共用）。 */
+export const SUBCOMMANDS = "status | on | off | test | tasks | cancel <id> | idle on|off | peers [--all|--idle|--name <子串>|--detail <agentId>] | spawn [名字]" +
+    " | in <时长> <内容> | at <HH:MM> <内容> | every <时长> <内容> | help" +
+    " | history [peer|me] [条数] | doctor [--json]" +
+    " | tell <peer> <内容> [--kind ask|task|notify]";
+/** `/proactive status` 末尾的指路行（MANUAL）。 */
+export const HELP_POINTER = "指路：/proactive help 看命令表与最常见故障；详细文档见 <安装目录>/README.md（随包分发）。";
+/**
+ * 对端目录查询（**同源实现**）：命令面 `peers --…`、模型工具 `list_peers`、
+ * 域工具 `proactive_query(peers)` 都走这里 → 字段集 / 在线判定 / 歧义候选逐字一致。
+ */
+export function queryPeerDirectory(opts) {
+    const directory = opts.registry.listPeers({
+        ...(opts.query.name === undefined ? {} : { name: opts.query.name }),
+        ...(opts.query.status === undefined ? {} : { status: opts.query.status }),
+        ...(opts.query.capability === undefined ? {} : { capability: opts.query.capability }),
+        ...(opts.query.includeOffline === undefined ? {} : { includeOffline: opts.query.includeOffline }),
+    }, { selfAgentId: opts.selfAgentId, inFlight: opts.inFlight });
+    return { directory, text: formatPeerDirectory(directory) };
+}
+/**
+ * 排期落库（**同源实现**）：命令面 `in|at|every`、模型工具 `schedule_task`、
+ * 域工具 `proactive_schedule` 都走这里 → 解析、校验、落库、回执口径只有一份。
+ */
+export function createScheduledTask(input) {
+    const now = input.now ?? Date.now();
+    const when = (input.when ?? "").trim();
+    const content = input.content.trim();
+    if (input.form !== "auto" && when === "") {
+        return { ok: false, error: `缺少时间。${SCHEDULE_USAGE}` };
+    }
+    if (content === "") {
+        return { ok: false, error: `缺少任务内容。${SCHEDULE_USAGE}` };
+    }
+    let expr;
+    try {
+        expr = parseScheduleExpression(when === "" ? undefined : when, now);
+    }
+    catch (err) {
+        return { ok: false, error: errText(err) };
+    }
+    // at 只收时刻，in/every 只收时长（写错类型 → 明确报错，不静默改写）。
+    if (input.form !== "auto") {
+        const wantKind = input.form === "at" ? "clock" : "duration";
+        if (expr.form !== wantKind) {
+            const hint = input.form === "at" ? "at 只接受 HH:MM 时刻（如 18:30）" : `${input.form} 只接受时长（如 10m）`;
+            return { ok: false, error: `${hint}，你给的是 "${when}"。支持格式：${SUPPORTED_WHEN_FORMATS}。` };
+        }
+    }
+    const task = {
+        id: `t-${randomUUID()}`,
+        schedule: input.form === "every" ? "repeat" : "once",
+        dueAt: expr.dueAt,
+        ...(input.form === "every" && expr.durationMs !== undefined ? { intervalMs: expr.durationMs } : {}),
+        prompt: content,
+        intent: input.intent ?? input.config.idleTrigger.intent,
+        askUser: input.askUser ?? false,
+        enabled: true,
+        createdAt: now,
+        fireCount: 0,
+        source: input.source,
+        ownerAgentId: input.agentId,
+        ...(input.sessionId === undefined ? {} : { ownerSessionId: input.sessionId }),
+        scope: "session",
+        ...(input.triggeredBy === undefined ? {} : { triggeredBy: input.triggeredBy }),
+    };
+    input.store.add(task);
+    return {
+        ok: true,
+        task,
+        now,
+        info: { rolledToTomorrow: expr.rolledToTomorrow, defaulted: expr.form === "default" },
+    };
+}
+/**
+ * **命令面 / 模型工具面的同一个分派**。
+ *
+ * 命令面（`/proactive …`）与模型工具（`proactive_query` / `proactive_schedule` /
+ * `proactive_peer` / `proactive_manage`）都调它 → 同一能力只有一份实现（**同源**）。
+ *
+ * 返回值是**一条**输出（`text` + `level`）：命令面直接 notify，工具面原样回给模型。
+ */
+export async function dispatchProactiveCommand(args, ctx, opts = {}) {
+    const origin = opts.origin ?? "user";
+    const parts = (args ?? "").trim().split(/\s+/).filter(Boolean);
+    const sub = parts[0] ?? "status";
+    switch (sub) {
+        case "status": {
+            const decision = ctx.evaluateIdle();
+            const state = buildStatusState({ config: ctx.getConfig(), snapshot: ctx.snapshot(), decision });
+            return {
+                text: `${formatStatus(state)}\n${formatIdleDecision(decision)}\n${ctx.recentEventsHint()}\n${HELP_POINTER}`,
+                level: "info",
+            };
+        }
+        case "doctor": {
+            // 只读体检：**统一真源**在 src/health.ts（doctor 与巡检脚本共用同一套判定）。
+            // **不产生任何对外行为**：不注入、不提问、不排期、不写文件、不消耗额度。
+            const report = ctx.collectHealth();
+            const asJson = parts.slice(1).includes("--json");
+            return { text: asJson ? healthToJson(report) : formatHealthReport(report), level: "info" };
+        }
+        case "on":
+        case "off": {
+            const on = sub === "on";
+            ctx.setConfig(toggleEnabled(ctx.getConfig(), on));
+            // 落盘（原子写）：开关必须重启后仍生效。
+            let persisted = "";
+            try {
+                persisted = ctx.persistEnabled(on);
+            }
+            catch (err) {
+                console.error("[proactive] 开关落盘失败:", err);
+            }
+            const idleState = ctx.getConfig().idleTrigger.enabled ? "开" : "关";
+            return {
+                text: `主动性：${on ? "已开启" : "已关闭"}（enabled=${on}）\n` +
+                    `已经${on ? "开启" : "关闭"}（当前：空闲触发 ${idleState}）\n` +
+                    `${on ? "定时投递与空闲触发均已恢复。" : "定时投递与空闲触发均已停止。"}\n` +
+                    `开关已落盘到 ${persisted}（重启后仍生效）。`,
+                level: "info",
+            };
+        }
+        case "peers": {
+            const flags = parts.slice(1);
+            const wantAll = flags.includes("--all");
+            const wantIdle = flags.includes("--idle");
+            const nameAt = flags.indexOf("--name");
+            const nameFilter = nameAt >= 0 ? flags[nameAt + 1] : undefined;
+            const detailAt = flags.indexOf("--detail");
+            const detailId = detailAt >= 0 ? flags[detailAt + 1] : undefined;
+            const filtered = wantAll || wantIdle || nameFilter !== undefined || detailId !== undefined;
+            if (!filtered) {
+                // 无参数 → 人侧速览（字段集是「人看」那套；与既有实现逐字一致）。
+                const peers = (ctx.registry?.list() ?? []).filter((p) => p.agentId !== ctx.agentId);
+                return { text: formatPeerList(peers, Date.now()), level: "info" };
+            }
+            // 一旦给了过滤/详情参数 → 走**与 `list_peers` 同源**的目录视图。
+            const registry = ctx.registry ?? new Registry({ agentDir: resolveAgentDir() });
+            const { directory, text } = queryPeerDirectory({
+                registry,
+                selfAgentId: ctx.agentId,
+                inFlight: ctx.inFlightForPeer,
+                query: {
+                    ...(wantAll || detailId !== undefined ? { includeOffline: true } : {}),
+                    ...(wantIdle ? { status: "idle" } : {}),
+                    ...(nameFilter === undefined ? {} : { name: nameFilter }),
+                },
+            });
+            if (detailId !== undefined) {
+                const one = directory.peers.filter((p) => p.agentId === detailId);
+                if (one.length === 0) {
+                    return { text: `proactive: 未找到对端 ${detailId}（用 /proactive peers --all 看全部）`, level: "error" };
+                }
+                return { text: formatPeerDirectory({ ...directory, peers: one, ambiguous: null }), level: "info" };
+            }
+            return { text, level: "info" };
+        }
+        case "spawn": {
+            const result = await ctx.spawnPeerSession(parts[1]);
+            if (!result.ok) {
+                return {
+                    text: `proactive: 创建对端失败（${result.phase} 阶段）：${result.reason}` +
+                        `${result.error === undefined ? "" : `\n细节：${result.error}`}`,
+                    level: "error",
+                };
+            }
+            return {
+                text: `已创建对端会话：${result.name}\n` +
+                    `agentId：${result.agentId}\n` +
+                    `状态：${result.state}（已登记 → 可交互）\n` +
+                    `寻址：按这个名字或这个 agentId 都能找到它（message_agent / list_peers 都用它）。\n` +
+                    `它会在本会话退出时被一并终止（不留孤儿进程）。`,
+                level: "info",
+            };
+        }
+        case "tell": {
+            return await ctx.tellPeer(parts.slice(1).join(" "));
+        }
+        case "test": {
+            return await ctx.selfTest();
+        }
+        case "tasks": {
+            const tasks = ctx.store?.list() ?? [];
+            return { text: formatTaskList(tasks, Date.now()), level: "info" };
+        }
+        case "history": {
+            // 人侧回看（因 + 果）：按时间序列出事件，可按对端过滤。
+            const log = ctx.lineage;
+            if (!log) {
+                return { text: "proactive: session_start 尚未触发，事件流未初始化", level: "error" };
+            }
+            let scope;
+            let peer;
+            let limit = 20;
+            for (const arg of parts.slice(1)) {
+                if (arg === "peer")
+                    scope = "peer";
+                else if (arg === "me")
+                    scope = "me";
+                else if (/^\d+$/.test(arg))
+                    limit = Math.min(200, Math.max(1, Number(arg)));
+                else
+                    peer = arg; // 具体的对端 agentId
+            }
+            const events = log.history({
+                ...(scope !== undefined ? { scope } : {}),
+                ...(peer !== undefined ? { peer } : {}),
+                limit,
+            });
+            return { text: formatLineageHistory(events), level: "info" };
+        }
+        case "cancel": {
+            const id = parts[1];
+            if (!id) {
+                return { text: "proactive: 用法：/proactive cancel <id>", level: "error" };
+            }
+            const store = ctx.store;
+            if (!store) {
+                return { text: "proactive: session_start 尚未触发，任务表未初始化", level: "error" };
+            }
+            const tasks = store.list();
+            const target = tasks.find((t) => t.id === id);
+            if (!target) {
+                return { text: formatCancelMissing(id, tasks), level: "error" };
+            }
+            // remove() 同时清理该任务的认领文件。
+            store.remove(id);
+            return { text: formatCancelResult(target), level: "info" };
+        }
+        case "in":
+        case "at":
+        case "every": {
+            const store = ctx.store;
+            if (!store) {
+                return { text: "proactive: session_start 尚未触发，任务表未初始化", level: "error" };
+            }
+            const result = createScheduledTask({
+                store,
+                config: ctx.getConfig(),
+                agentId: ctx.agentId,
+                ...(ctx.sessionId === undefined ? {} : { sessionId: ctx.sessionId }),
+                form: sub,
+                when: parts[1],
+                content: parts.slice(2).join(" "),
+                source: origin === "model" ? "model" : "user",
+            });
+            if (!result.ok) {
+                return { text: `proactive: ${result.error}`, level: "error" };
+            }
+            return { text: formatScheduleResult(result.task, result.now, result.info), level: "info" };
+        }
+        case "idle": {
+            const arg = (parts[1] ?? "").toLowerCase();
+            if (arg !== "on" && arg !== "off") {
+                return { text: "proactive: 用法：/proactive idle on | /proactive idle off", level: "error" };
+            }
+            const on = arg === "on";
+            const detectSwitched = on && ctx.getConfig().idleDetect === "off";
+            ctx.setConfig(toggleIdleTrigger(ctx.getConfig(), on));
+            // 档位可能变了 → 追踪器要跟着换（否则检测档位与配置不一致）。
+            ctx.setIdleDetect(effectiveIdleDetect(ctx.getConfig().idleDetect, ctx.runtimeMode));
+            return {
+                text: formatIdleToggle(ctx.getConfig(), on, { detectSwitched, masterOff: !ctx.getConfig().enabled }),
+                level: "info",
+            };
+        }
+        case "help": {
+            return { text: ctx.helpText(), level: "info" };
+        }
+        default: {
+            return { text: `proactive: 未知子命令 "${sub}"，可用：${SUBCOMMANDS}`, level: "error" };
+        }
+    }
+}