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

package/build/src/assistant.js

@@ -0,0 +1,572 @@
+// 【S0 归属】L3 宿主集成（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 直接面对宿主/操作系统；内核面（机制/协议/记录/决策/目标/接口）不在本文件。
+/**
+ * 会话内「常驻助理」控制面（`/proactive assistant on|off|status|restart`）。
+ *
+ * ## 为什么有这层（缺口的事实）
+ *
+ * 用户原话：「没有 /proactive daemon install」——
+ * 常驻助理的**控制逻辑**早就有了（CLI 侧 `pi-proactive daemon install|uninstall|status`，
+ * 见 `tools/cli.mjs` 与 `tools/daemon-install.sh`），但**会话里没有入口**：
+ * 用户想「打开常驻」时只能切到终端跑 CLI → 「用户只面对三件事（打开 / 它会做什么 / 怎么回应）」
+ * 里的【打开】在会话内**做不成**（见 `docs/product/ux-mvp-spec.md` §3）。
+ *
+ * ## 硬约束（本文件的设计前提）
+ *
+ * 1. **复用同一套 daemon 控制实现**：安装 / 卸载**只调用** `tools/daemon-install.sh` 与
+ *    `tools/daemon-uninstall.sh` —— 与 CLI **同一份脚本**（本文件不复制任何安装逻辑）。
+ * 2. **安装不得阻塞会话**：安装要等 launchd/systemd 冷启动 + 心跳前进（实测数十秒），
+ *    在会话里同步等待 = 用户看着界面卡住 → 本文件**立即回执「正在安装…」**，
+ *    后台跑完再用**事件流 / 状态**报结果（`/proactive assistant status` 看得到）。
+ * 3. **失败必须可操作**：缺什么 / 怎么手动跑 / 怎么清理，三样都要说。
+ * 4. **状态口径单一**：宿主 / 进程 / 心跳 / 上次联系 全部读**文件事实**
+ *    （`host.json` / `heartbeat.json` / `contacts.jsonl`）→ 会话内看到的与 CLI 看到的是同一份。
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { proactiveDir, resolveAgentDir } from "./config.js";
+import { heartbeatPath, hostStatePath, readContactEntries } from "./daemon-config.js";
+/**
+ * 心跳陈旧阈值（ms）：常驻值班默认 30s 一跳 → 5 分钟 = 10 跳没来 → 判定「心跳已停」。
+ *
+ * 为什么要它：心跳文件在 ≠ 值班进程还活着（进程崩了文件还在）→ 只看文件会撒谎。
+ */
+export const HEARTBEAT_STALE_MS = 5 * 60_000;
+/**
+ * 定位包根与两个常驻脚本。
+ *
+ * 两种落位都要认（与 `src/health.ts` 的 `pluginVersionFrom` 同一套办法）：
+ * - 源码态 `pi-proactive/src/assistant.ts` → 包根在**上一级**；
+ * - 产物态 `<包>/build/src/assistant.js` → 包根在**上两级**。
+ *
+ * 环境变量 `PI_PROACTIVE_PKG_ROOT` 可显式指定包根（自测 / 特殊落位用）。
+ */
+export function resolveAssistantScripts(baseDir) {
+    const here = baseDir ?? path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [];
+    const envRoot = process.env.PI_PROACTIVE_PKG_ROOT;
+    if (envRoot !== undefined && envRoot !== "")
+        candidates.push(path.resolve(envRoot));
+    // 顺序：源码态优先（`..`），产物态回落（`../..`）。
+    for (const up of ["..", "../.."])
+        candidates.push(path.resolve(here, up));
+    const tried = [];
+    for (const root of candidates) {
+        const install = path.join(root, "tools", "daemon-install.sh");
+        tried.push(install);
+        if (!fs.existsSync(install))
+            continue;
+        return {
+            pkgRoot: root,
+            install,
+            uninstall: path.join(root, "tools", "daemon-uninstall.sh"),
+        };
+    }
+    return {
+        error: `找不到常驻安装脚本（试过 ${tried.join("、")}）—— ` +
+            `重新安装 pi-proactive（npm i -g pi-proactive），或手动执行 npx pi-proactive daemon install；` +
+            `清理残留：rm -rf <agent-dir>/proactive/daemon && rm -f ~/Library/LaunchAgents/com.pi-proactive.daemon.plist`,
+        tried,
+    };
+}
+/** 操作状态文件：`<agentDir>/proactive/assistant.json`（**不放** daemon 目录：卸载会删掉那个目录）。 */
+export function assistantStatePath(agentDir) {
+    return path.join(proactiveDir(agentDir), "assistant.json");
+}
+/** 读操作状态（坏文件不当场崩，按「没有记录」处理）。 */
+export function readAssistantAction(agentDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(assistantStatePath(agentDir), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const rec = parsed;
+        if (typeof rec.action !== "string" || typeof rec.startedAt !== "number")
+            return undefined;
+        return rec;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 写操作状态（原子写；坏目录不抛 —— 状态是**可观测性**，不是业务数据）。 */
+export function writeAssistantAction(agentDir, state) {
+    const file = assistantStatePath(agentDir);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // ignore: 写不进去也不能影响主流程
+    }
+}
+/** 进程是否还活着。 */
+function pidAlive(pid) {
+    if (pid === undefined || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 读常驻状态（只读；坏文件按「没有」处理，绝不抛）。 */
+export function readAssistantStatus(agentDir, now = Date.now()) {
+    const status = { installed: false, present: false, pidAlive: false };
+    const host = readJsonSafe(hostStatePath(agentDir));
+    if (host !== undefined) {
+        status.present = true;
+        if (typeof host.hostKind === "string")
+            status.hostKind = host.hostKind;
+        if (typeof host.unitPath === "string" && host.unitPath !== "")
+            status.unitPath = host.unitPath;
+        if (typeof host.workspaceId === "string" && host.workspaceId !== "")
+            status.workspaceId = host.workspaceId;
+    }
+    const hb = readJsonSafe(heartbeatPath(agentDir));
+    if (hb !== undefined) {
+        status.present = true;
+        if (typeof hb.ts === "number") {
+            status.heartbeatTs = hb.ts;
+            status.heartbeatAgeMs = Math.max(0, now - hb.ts);
+        }
+        if (typeof hb.pid === "number") {
+            status.pid = hb.pid;
+            status.pidAlive = pidAlive(hb.pid);
+        }
+        if (status.hostKind === undefined && typeof hb.host === "string")
+            status.hostKind = hb.host;
+    }
+    // **真在跑吗**：心跳在 + （进程活着 ｜ 心跳新鲜但拿不到 pid）才算常驻。
+    const fresh = status.heartbeatAgeMs !== undefined && status.heartbeatAgeMs <= HEARTBEAT_STALE_MS;
+    if (hb !== undefined) {
+        if (status.pid !== undefined) {
+            status.installed = status.pidAlive;
+            if (!status.installed)
+                status.notRunningReason = "process-dead";
+        }
+        else {
+            status.installed = fresh;
+            if (!fresh)
+                status.notRunningReason = "heartbeat-stale";
+        }
+        if (status.installed && !fresh)
+            status.notRunningReason = "heartbeat-stale";
+    }
+    const contacts = readContactEntries(agentDir);
+    const last = contacts.length > 0 ? contacts[contacts.length - 1] : undefined;
+    if (last !== undefined) {
+        status.lastContactTs = last.ts;
+        if (last.targetAgentId !== undefined)
+            status.lastContactTarget = last.targetAgentId;
+    }
+    status.action = readAssistantAction(agentDir);
+    return status;
+}
+/** 读 JSON（坏文件 / 不存在 → undefined，绝不抛）。 */
+function readJsonSafe(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 「多久之前」（人话）。 */
+export function formatAgo(ms) {
+    if (ms < 1000)
+        return "刚刚";
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s} 秒前`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m} 分钟前`;
+    const h = Math.round(m / 60);
+    if (h < 24)
+        return `${h} 小时前`;
+    return `${Math.round(h / 24)} 天前`;
+}
+/** 时刻（本地时区，秒级）。 */
+function formatTime(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())}`;
+}
+/**
+ * 常驻状态的人话视图（宿主 + 进程 + 心跳 + 上次联系 —— 四项缺一不可）。
+ *
+ * 口径说明：**只报文件里读到的**，读不到就说「无」→ 不给用户「它还在跑」的错觉。
+ */
+export function formatAssistantStatus(status) {
+    const lines = [];
+    if (status.installed) {
+        lines.push("常驻助理：已常驻");
+    }
+    else if (status.notRunningReason === "process-dead") {
+        lines.push("常驻助理：未常驻（心跳文件在，但值班进程已经不在）");
+    }
+    else if (status.notRunningReason === "heartbeat-stale") {
+        lines.push("常驻助理：未常驻（心跳已停）");
+    }
+    else {
+        lines.push("常驻助理：未常驻");
+    }
+    if (status.hostKind !== undefined) {
+        const unit = status.unitPath === undefined ? "" : `（单元 ${status.unitPath}）`;
+        const ws = status.workspaceId === undefined ? "" : `（workspace ${status.workspaceId}）`;
+        lines.push(`  · 宿主：${status.hostKind}${unit}${ws}`);
+    }
+    else {
+        lines.push("  · 宿主：无");
+    }
+    if (status.pid !== undefined) {
+        lines.push(`  · 进程：pid=${status.pid} ${status.pidAlive ? "在跑" : "不在"}`);
+    }
+    else {
+        lines.push("  · 进程：无");
+    }
+    if (status.heartbeatTs !== undefined) {
+        lines.push(`  · 心跳：${formatAgo(status.heartbeatAgeMs ?? 0)}（ts ${status.heartbeatTs}）`);
+    }
+    else {
+        lines.push("  · 心跳：无");
+    }
+    if (status.lastContactTs !== undefined) {
+        const target = status.lastContactTarget === undefined ? "" : `（对象 ${status.lastContactTarget}）`;
+        lines.push(`  · 上次联系：${formatAgo(Math.max(0, Date.now() - status.lastContactTs))}${target}`);
+    }
+    else {
+        lines.push("  · 上次联系：无");
+    }
+    if (status.action !== undefined) {
+        const act = status.action;
+        const done = act.finishedAt !== undefined;
+        const verdict = done ? (act.ok === true ? "成功" : `失败（退出码 ${String(act.exitCode ?? "?")}）`) : "进行中";
+        lines.push(`  · 最近操作：${act.action} · ${verdict}（${formatTime(act.startedAt)} 起）`);
+        if (done && act.ok === false) {
+            // 失败要**可操作**：光说「失败」没用 → 把失败输出与清理办法一并给出。
+            const tail = (act.output ?? "").trim();
+            if (tail !== "")
+                lines.push(`  · 上次失败输出：${tail.split("\n").slice(-6).join(" ｜ ")}`);
+            lines.push("  · 清理：/proactive assistant off（清单元 / 进程 / 状态目录）或 bash <包目录>/tools/daemon-uninstall.sh");
+        }
+    }
+    if (!status.installed) {
+        lines.push("  · 打开：/proactive assistant on");
+    }
+    return lines.join("\n");
+}
+/** 常驻目录（安装日志放这儿 → 卸载时一起清掉，不留残留）。 */
+function daemonLogDir(agentDir) {
+    return path.join(proactiveDir(agentDir), "daemon");
+}
+/** 脚本参数（**只传脚本认识的参数** → 与 CLI 的参数契约同一套）。 */
+function scriptArgs(opts, agentDir) {
+    const args = ["--agent-dir", agentDir];
+    const label = opts.label ?? process.env.PI_PROACTIVE_DAEMON_LABEL;
+    if (label !== undefined && label !== "")
+        args.push("--label", label);
+    const service = opts.serviceName ?? process.env.PI_PROACTIVE_DAEMON_SERVICE;
+    if (service !== undefined && service !== "")
+        args.push("--service-name", service);
+    if (opts.agentId !== undefined && opts.agentId !== "")
+        args.push("--agent-id", opts.agentId);
+    if (opts.host !== undefined && opts.host !== "")
+        args.push("--host", opts.host);
+    return args;
+}
+/** 取脚本落位（注入优先 → 解析）。 */
+function scriptsOf(opts) {
+    if (opts.scripts !== undefined)
+        return opts.scripts;
+    return resolveAssistantScripts();
+}
+/**
+ * 打开常驻助理（**立即返回，不阻塞会话**）。
+ *
+ * 流程：起后台进程跑安装脚本 → 立刻回执「正在安装…」→ 装完由 `onDone` 报结果，
+ * 结果同时落盘（`assistant.json`）→ `/proactive assistant status` 随时可查。
+ */
+export async function requestAssistantInstall(opts = {}) {
+    const agentDir = opts.agentDir ?? resolveAgentDir();
+    const scripts = scriptsOf(opts);
+    if ("error" in scripts) {
+        return { text: `proactive: ${scripts.error}`, level: "error" };
+    }
+    const previous = readAssistantAction(agentDir);
+    if (previous !== undefined && previous.finishedAt === undefined && pidAlive(previous.pid)) {
+        return {
+            text: `常驻助理：正在安装…（上一次安装还在跑，pid=${String(previous.pid)}）\n` +
+                `  · 看结果：/proactive assistant status`,
+            level: "info",
+        };
+    }
+    const logDir = daemonLogDir(agentDir);
+    const logFile = path.join(logDir, "assistant-install.log");
+    try {
+        fs.mkdirSync(logDir, { recursive: true });
+        fs.writeFileSync(logFile, "");
+    }
+    catch {
+        // ignore: 日志写不了也要能装
+    }
+    const out = fs.openSync(logFile, "a");
+    let spawned;
+    try {
+        spawned = spawn("bash", [scripts.install, ...scriptArgs(opts, agentDir)], {
+            detached: true,
+            stdio: ["ignore", out, out],
+        });
+    }
+    catch (err) {
+        fs.closeSync(out);
+        return {
+            text: `proactive: 常驻助理安装起不来：${err instanceof Error ? err.message : String(err)}\n` +
+                `  · 手动等价命令：bash ${scripts.install} --agent-dir ${agentDir}\n` +
+                `  · 清理命令：bash ${scripts.uninstall} --agent-dir ${agentDir}`,
+            level: "error",
+        };
+    }
+    fs.closeSync(out);
+    const child = spawned;
+    const startedAt = Date.now();
+    const actionKind = opts.action === "restart" ? "restart" : "install";
+    writeAssistantAction(agentDir, {
+        action: actionKind,
+        startedAt,
+        pid: child.pid,
+    });
+    // 后台跑完 → 落状态 + 报结果（**不阻塞调用方**）。
+    child.on("close", (code) => {
+        const output = readTail(logFile);
+        const ok = code === 0 && /已常驻/.test(output);
+        void (async () => {
+            // 失败 → **自动回滚**（与 CLI `daemon install` 同一口径：装不成功就不给用户留单元 / 进程）。
+            // 不回滚的后果（实测）：安装装到一半失败 → launchd 单元仍已加载 → 反复拉起失败进程。
+            const rollback = ok ? "" : await rollbackInstall(scripts, scriptArgs(opts, agentDir));
+            writeAssistantAction(agentDir, {
+                action: actionKind,
+                startedAt,
+                finishedAt: Date.now(),
+                ok,
+                exitCode: code ?? -1,
+                output: output.slice(-2000),
+                pid: child.pid,
+            });
+            const text = ok
+                ? `已常驻\n${output.trim()}`
+                : installFailureText(code, output, scripts, agentDir, rollback);
+            opts.onDone?.(text);
+        })();
+    });
+    // spawn 失败（如 bash 不在 PATH）不会 throw，而是异步发 'error' —— 必须挂监听，
+    // 否则未处理的 error 事件会把整个会话带崩。
+    child.on("error", (err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        void (async () => {
+            const rollback = await rollbackInstall(scripts, scriptArgs(opts, agentDir));
+            writeAssistantAction(agentDir, {
+                action: actionKind,
+                startedAt,
+                finishedAt: Date.now(),
+                ok: false,
+                exitCode: 127,
+                output: message,
+                pid: child.pid,
+            });
+            opts.onDone?.(installFailureText(127, message, scripts, agentDir, rollback));
+        })();
+    });
+    child.unref();
+    return {
+        text: `常驻助理：正在安装…（不阻塞本会话）\n` +
+            `  · 看结果：/proactive assistant status（装完会显示「已常驻」或失败原因）\n` +
+            `  · 手动等价命令：bash ${scripts.install} --agent-dir ${agentDir}\n` +
+            `  · 想关掉：/proactive assistant off`,
+        level: "info",
+    };
+}
+/** 安装失败的回执（缺什么 / 怎么手动跑 / 怎么清理 —— 三样都要说）。 */
+async function rollbackInstall(scripts, args) {
+    const result = await runScript(scripts.uninstall, args, 60_000);
+    const output = `${result.stdout}\n${result.stderr}`.trim();
+    return result.code === 0 ? output : `回滚未成功（退出码 ${String(result.code ?? "?")}）：${output}`;
+}
+/** 安装失败的回执（缺什么 / 怎么手动跑 / 怎么清理 —— 三样都要说）。 */
+function installFailureText(code, output, scripts, agentDir, rollback = "") {
+    const lines = [
+        `常驻助理：安装失败（退出码 ${String(code ?? "?")}）`,
+        `  · 输出：\n${indent(output.trim())}`,
+    ];
+    if (rollback !== "") {
+        lines.push(`  · 已自动回滚（不留已加载的单元）：\n${indent(rollback)}`);
+    }
+    lines.push(`  · 手动重试：bash ${scripts.install} --agent-dir ${agentDir}`);
+    lines.push(`  · 清理残留：bash ${scripts.uninstall} --agent-dir ${agentDir}`);
+    return lines.join("\n");
+}
+/** 缩进（多行输出嵌进回执）。 */
+function indent(text) {
+    if (text === "")
+        return "    （无输出）";
+    return text
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n");
+}
+/** 读文件尾部（最多 n 字符）。 */
+function readTail(file, n = 4000) {
+    try {
+        const raw = fs.readFileSync(file, "utf8");
+        return raw.length <= n ? raw : raw.slice(raw.length - n);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * 关闭常驻助理（同步等卸载脚本跑完 → 回执含**残留终检**）。
+ *
+ * 为什么不后台跑：卸载的结论就是「有没有残留」，不等完就报等于没结论。
+ * 超时上限 60s（超了 → 如实说超时，并给出清理命令）。
+ */
+export async function requestAssistantUninstall(opts = {}) {
+    const agentDir = opts.agentDir ?? resolveAgentDir();
+    const scripts = scriptsOf(opts);
+    if ("error" in scripts) {
+        return { text: `proactive: ${scripts.error}`, level: "error" };
+    }
+    const startedAt = Date.now();
+    const before = readAssistantStatus(agentDir);
+    const unitPath = before.unitPath;
+    const args = scriptArgs(opts, agentDir);
+    const result = await runScript(scripts.uninstall, args, 60_000);
+    const output = `${result.stdout}\n${result.stderr}`.trim();
+    const timedOut = result.timedOut;
+    writeAssistantAction(agentDir, {
+        action: "uninstall",
+        startedAt,
+        finishedAt: Date.now(),
+        ok: !timedOut && result.code === 0,
+        exitCode: result.code ?? -1,
+        output: output.slice(-2000),
+    });
+    // **独立终检**（不只信脚本自己的结论）：进程 / 单元文件 / 状态目录。
+    const residue = await residueCheck(agentDir, unitPath, before.pid);
+    const lines = [];
+    if (!before.present) {
+        // 从来没装过 → 不谎报「已关闭」（那会让用户以为关掉了什么）。
+        lines.push("常驻助理：未常驻（没有可关闭的东西）");
+    }
+    else {
+        lines.push(`常驻助理：${!timedOut && result.code === 0 ? "已关闭" : "关闭失败"}`);
+    }
+    lines.push(`  · 残留终检：${residue.residue === 0 ? "无残留" : `有残留 ${String(residue.residue)} 项`}`);
+    lines.push(`  · 任务 ${String(residue.tasks)} / 进程 ${String(residue.processes)} / 单元 ${String(residue.units)}`);
+    if (residue.detail.length > 0)
+        lines.push(`  · 明细：${residue.detail.join("；")}`);
+    if (timedOut) {
+        lines.push("  · 说明：卸载脚本超时（60s）→ 状态未知，请手动再跑一次并看残留");
+    }
+    if (output !== "")
+        lines.push(indent(output));
+    lines.push(`  · 手动等价命令：bash ${scripts.uninstall} --agent-dir ${agentDir}`);
+    const level = !timedOut && result.code === 0 && residue.residue === 0 ? "info" : "error";
+    return { text: lines.join("\n"), level };
+}
+/** 卸载残留终检：进程 / 单元文件 / 状态目录 / 任务表。 */
+async function residueCheck(agentDir, unitPath, pid) {
+    const detail = [];
+    let processes = 0;
+    let units = 0;
+    if (pidAlive(pid)) {
+        processes += 1;
+        detail.push(`值班进程还在（pid=${String(pid)}）`);
+    }
+    if (unitPath !== undefined && fs.existsSync(unitPath)) {
+        units += 1;
+        detail.push(`单元文件还在（${unitPath}）`);
+    }
+    if (fs.existsSync(daemonLogDir(agentDir))) {
+        units += 1;
+        detail.push(`状态/日志目录还在（${daemonLogDir(agentDir)}）`);
+    }
+    // 任务表：卸载**默认保留用户数据**（任务 / 事件流 / 邮箱）→ 这里只报数量，不当残留。
+    const tasksFile = path.join(proactiveDir(agentDir), "tasks.json");
+    let tasks = 0;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(tasksFile, "utf8"));
+        if (Array.isArray(parsed))
+            tasks = parsed.length;
+        else if (typeof parsed === "object" && parsed !== null) {
+            const list = parsed.tasks;
+            if (Array.isArray(list))
+                tasks = list.length;
+        }
+    }
+    catch {
+        tasks = 0;
+    }
+    return { residue: processes + units, tasks, processes, units, detail };
+}
+/** 跑一个脚本（等它结束；带超时）。 */
+function runScript(file, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn("bash", [file, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        timer.unref?.();
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: 127, stdout, stderr: `${stderr}\n${err instanceof Error ? err.message : String(err)}`, timedOut });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}
+/**
+ * 会话内 `assistant` 子命令的**统一入口**（命令面与模型工具面共用这一段 → 逐字一致）。
+ *
+ * @param action `on` / `off` / `status` / `restart`
+ */
+export async function handleAssistantCommand(action, opts = {}) {
+    switch (action) {
+        case "on":
+            return await requestAssistantInstall(opts);
+        case "restart":
+            return await requestAssistantInstall({ ...opts, action: "restart" });
+        case "off":
+            return await requestAssistantUninstall(opts);
+        case "status": {
+            const agentDir = opts.agentDir ?? resolveAgentDir();
+            return { text: formatAssistantStatus(readAssistantStatus(agentDir)), level: "info" };
+        }
+        default:
+            return {
+                text: "proactive: 用法：/proactive assistant on | off | status | restart",
+                level: "error",
+            };
+    }
+}

package/build/src/commands.js

@@ -6,6 +6,7 @@ import { formatHealthReport, healthToJson } from "./health.js";
 import { formatLineageHistory } from "./lineage.js";
 import { formatPeerDirectory, formatPeerList } from "./peer.js";
 import { readProgressEta } from "./progress-eta.js";
+import { handleAssistantCommand } from "./assistant.js";
 import { Registry } from "./registry.js";
 const DETECT_LABEL = {
     terminal: "终端输入",
@@ -279,6 +280,7 @@ export const SUBCOMMANDS = "status | on | off | test | tasks | cancel <id> | idl
     " | history [peer|me] [条数] | doctor [--json]" +
     " | progress" +
     " | tell <peer> <内容> [--kind ask|task|notify]" +
+    " | assistant on|off|status|restart" +
     " | config [undo] [--json]";
 /** `/proactive status` 末尾的指路行（MANUAL）。 */
 export const HELP_POINTER = "指路：/proactive help 看命令表与最常见故障；详细文档见 <安装目录>/README.md（随包分发）。";
@@ -453,6 +455,17 @@ export async function dispatchProactiveCommand(args, ctx, opts = {}) {
             }
             return { text, level: "info" };
         }
+        case "assistant": {
+            // 会话内常驻助理（on / off / status / restart）。
+            // **与模型工具面共用同一段实现**（`handleAssistantCommand`）→ 输出逐字一致。
+            // 安装**不阻塞**：立即回执「正在安装…」，结果由 `ctx.assistantDone` 异步回传 + 落盘可查。
+            const action = (parts[1] ?? "status").toLowerCase();
+            const outcome = await handleAssistantCommand(action, {
+                agentDir: ctx.agentDir ?? resolveAgentDir(),
+                ...(ctx.assistantDone === undefined ? {} : { onDone: ctx.assistantDone }),
+            });
+            return { text: outcome.text, level: outcome.level };
+        }
         case "spawn": {
             const result = await ctx.spawnPeerSession(parts[1]);
             if (!result.ok) {

package/build/src/config.js

@@ -410,6 +410,22 @@ function applyContentRefs(cfg, raw, dir) {
         cfg.externalContent = resolved;
 }
 /** 全部配置项（顺序 = 清单展示顺序）。 */
+/**
+ * daemon 配置面【专属】的顶层键：由 src/daemon-config.ts 解析与校验。
+ * 主配置不认识它们，但也不该把它们判成"未知项"（同一份 config.json，两个解析器，键集必须一致）。
+ */
+export const DAEMON_OWNED_KEYS = [
+    "version",
+    "enabled",
+    "agentId",
+    "dryRun",
+    "budget",
+    "permissions",
+    "tickIntervalMs",
+    "handoverHour",
+    "staleSocketMs",
+    "staleExecutionMs",
+];
 export const CONFIG_KEY_SPECS = [
     {
         path: "enabled",
@@ -754,6 +770,10 @@ export function validateConfig(raw, file) {
                 walkContentRefs(value, p, file, issues);
                 continue;
             }
+            if (!p.includes(".") && DAEMON_OWNED_KEYS.includes(p)) {
+                // daemon 配置面自有键 → 主配置不校验、不报错（由 daemon-config.ts 负责）
+                continue;
+            }
             const spec = byPath.get(p);
             if (spec !== undefined) {
                 if (!matchesSpec(spec, value)) {

package/build/src/content.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 /**
  * CFG1 · C1：外置内容解析层（提示词 / agent 定义从配置文件搬到独立文件）。
  *

package/build/src/daemon-host.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L3 宿主集成（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 直接面对宿主/操作系统；内核面（机制/协议/记录/决策/目标/接口）不在本文件。
 /**
  * 常驻**宿主**判定（双宿主：herdr 优先 → 自带 launchd/systemd 回落）。
  *

package/build/src/daemon.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L2 适配器 · 宿主相关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 宿主概念只许出现在这一层；这里的耦合是**适配**，不是内核耦合。
 /**
  * DAEMON7：常驻值班循环（headless · 非交互会话）。
  *

package/build/src/dedupe.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 import fs from "node:fs";
 import path from "node:path";
 import { isKnownOnDiskVersion, onDiskVersionOf, proactiveDir, reportForeignVersion, resolveAgentDir, writeAtomicFile, } from "./config.js";

package/build/src/health.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L2 适配器 · 宿主相关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 宿主概念只许出现在这一层；这里的耦合是**适配**，不是内核耦合。
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import os from "node:os";

package/build/src/lineage.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 /**
  * 统一事件流（血缘）：把「为什么触发」（因）与「结果如何」（果）落到**一个**只追加的 JSONL。
  *