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

package/build/src/supervisor-web.js

@@ -0,0 +1,262 @@
+/**
+ * Web 监督面（**只读 · 本地优先 · 无依赖**）。
+ *
+ * 形态：`pi-proactive web [--port N] [--agent-dir D]` → Node 内置 http，**只监听 127.0.0.1**。
+ *
+ * 边界（越界即不合格）：
+ * - **只读**：没有任何写配置的入口（无表单 / 无按钮 / 无写路由；写方法一律 405）；
+ * - **单一数据源**：页面与 API 的数字全部来自 `src/supervisor-state.ts` 的**同一份聚合**
+ *   （本模块**不重算**任何指标）；
+ * - **本地优先**：绑定地址固定 `127.0.0.1`（不从其它网卡暴露）；
+ * - **无依赖**：只用 Node 内置 `http` / `fs` / `path`，前端零框架零构建（样式内联）。
+ *
+ * 页面六块：状态卡 / 联系时间线 / 托付 / 阻塞 / 预算 / 守恒灯。
+ */
+import http from "node:http";
+import { collectSupervisorState, formatBudgetLine, formatConservationLine, formatEntrustmentConservationLine, formatStatusLine, formatSupervisorSummary, } from "./supervisor-state.js";
+/** 只监听的地址（**本地优先**：默认不暴露到局域网/公网）。 */
+export const SUPERVISOR_HOST = "127.0.0.1";
+/** HTML 转义（页面内容来自本地文件，仍按不可信处理）。 */
+function esc(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** 毫秒 → `MM-DD HH:mm:ss`（本地时区）。 */
+function fmtTime(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+const STYLE = `
+:root { color-scheme: light dark; }
+body { font: 14px/1.6 -apple-system, "PingFang SC", "Noto Sans CJK SC", system-ui, sans-serif; margin: 0; padding: 24px; }
+h1 { font-size: 18px; margin: 0 0 4px; }
+.sub { opacity: .65; font-size: 12px; margin-bottom: 16px; }
+.grid { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(340px, 1fr)); }
+section { border: 1px solid rgba(128,128,128,.35); border-radius: 8px; padding: 12px 14px; }
+section h2 { font-size: 14px; margin: 0 0 8px; letter-spacing: .04em; }
+table { width: 100%; border-collapse: collapse; font-size: 12.5px; }
+td, th { text-align: left; padding: 2px 6px 2px 0; vertical-align: top; }
+.k { opacity: .6; white-space: nowrap; }
+.ok { color: #1a7f37; font-weight: 600; }
+.bad { color: #b42318; font-weight: 600; }
+ul { margin: 4px 0 0; padding-left: 18px; }
+li { font-size: 12.5px; }
+details { margin-top: 8px; font-size: 12px; opacity: .8; }
+code { font-size: 11.5px; }
+`;
+/** 一行键值表。 */
+function row(key, value) {
+    return `<tr><td class="k">${esc(key)}</td><td>${value}</td></tr>`;
+}
+/** 状态卡。 */
+function renderStatus(state) {
+    const s = state.status;
+    return [
+        "<table>",
+        row("摘要", esc(formatSupervisorSummary(state))),
+        row("宿主 / 进程", esc(formatStatusLine(state))),
+        row("在不在", s.running ? '<span class="ok">在跑</span>' : `<span class="bad">不在${s.notRunningReason ? `（${esc(s.notRunningReason)}）` : ""}</span>`),
+        row("心跳时刻", s.heartbeatTs === undefined ? "—" : esc(fmtTime(s.heartbeatTs))),
+        row("上次联系", s.lastContactTs === undefined ? "从未" : esc(fmtTime(s.lastContactTs))),
+        row("值班身份", esc(s.agentId ?? "—")),
+        row("运行形态", esc(s.runMode ?? "—")),
+        row("总开关 / 联系开关", `${s.enabled === undefined ? "—" : s.enabled ? "开" : "关"} / ${s.contactEnabled === undefined ? "—" : s.contactEnabled ? "开" : "关"}`),
+        "</table>",
+    ].join("");
+}
+/** 联系时间线。 */
+function renderTimeline(state) {
+    if (state.timeline.length === 0)
+        return "<p>暂无记录</p>";
+    const rows = state.timeline
+        .slice()
+        .reverse()
+        .map((t) => {
+        const len = t.bodyLen === undefined ? "" : ` · 正文 ${t.bodyLen} 字`;
+        const digest = t.bodyDigest === undefined ? "" : ` · 摘要 ${t.bodyDigest}`;
+        const peer = t.peer === undefined ? "" : ` · 对端 ${t.peer}`;
+        return `<li><span class="k">${esc(fmtTime(t.ts))}</span> · ${esc(t.summary)}${esc(len)}${esc(digest)}${esc(peer)}</li>`;
+    })
+        .join("");
+    return `<ul>${rows}</ul>`;
+}
+/** 托付（含目标）。 */
+function renderTrusts(state) {
+    if (state.trusts.length === 0 && state.goals.length === 0)
+        return "<p>暂无托付</p>";
+    const parts = [];
+    if (state.trusts.length > 0) {
+        const rows = state.trusts
+            .map((t) => `<li>${esc(t.target)} · <span class="k">${esc(t.status)}</span>${t.needsHuman ? " · 需人决策" : ""}${t.humanReason ? ` · ${esc(t.humanReason)}` : ""}</li>`)
+            .join("");
+        parts.push(`<table><tr><th>托付</th><th>状态</th></tr></table><ul>${rows}</ul>`);
+    }
+    if (state.goals.length > 0) {
+        const rows = state.goals
+            .map((g) => `<li>${esc(g.title)} · <span class="k">${esc(g.status)}</span> · 推进 ${g.progressSteps} 步 · 行动 ${g.usedActions}/${g.maxActions}${g.humanReason ? ` · ${esc(g.humanReason)}` : ""}</li>`)
+            .join("");
+        parts.push(`<ul>${rows}</ul>`);
+    }
+    return parts.join("");
+}
+/** 阻塞。 */
+function renderBlockers(state) {
+    if (state.blockers.length === 0)
+        return '<p class="ok">无阻塞</p>';
+    const rows = state.blockers
+        .map((b) => `<li>${esc(b.title)}${b.detail ? ` · ${esc(b.detail)}` : ""}</li>`)
+        .join("");
+    return `<ul>${rows}</ul>`;
+}
+/** 预算。 */
+function renderBudget(state) {
+    return [
+        "<table>",
+        row("余量", esc(formatBudgetLine(state))),
+        row("闸门", state.budget.exhausted ? `<span class="bad">${esc(state.budget.reason ?? "已耗尽")}</span>` : '<span class="ok">未耗尽</span>'),
+        row("耗尽时降级", state.budget.degradeToObserve ? "降级为只观察" : "直接停下"),
+        row("配置", state.budget.configured ? "已读 daemon.json" : "未配置（按缺省上限显示）"),
+        "</table>",
+    ].join("");
+}
+/** 守恒灯。 */
+function renderConservation(state) {
+    const c = state.conservation;
+    return [
+        "<table>",
+        row("行为四段", esc(formatConservationLine(state))),
+        row("托付四段", esc(formatEntrustmentConservationLine(state))),
+        row("回应率", `${(c.responseRate * 100).toFixed(1)}%`),
+        row("托付闭环率", `${(c.closureRate * 100).toFixed(1)}%`),
+        row("守候时长", `${Math.round(c.watchDurationMs / 1000)} 秒`),
+        row("判定", c.equal ? '<span class="ok">四段相等（无悬空）</span>' : '<span class="bad">四段不等（有悬空）</span>'),
+        "</table>",
+    ].join("");
+}
+/** 渲染整页（**服务端渲染**：一处渲染实现 → 页面与 API 不会各说各话）。 */
+export function renderSupervisorHtml(state) {
+    return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="refresh" content="5">
+<title>pi-proactive 监督面</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<h1>pi-proactive 监督面（只读）</h1>
+<p class="sub">数据源：${esc(state.agentDir)} · 聚合于 ${esc(fmtTime(state.generatedAt))} · 本页只读，改配置请回 Pi 会话</p>
+<div class="grid">
+<section><h2>① 状态卡</h2>${renderStatus(state)}</section>
+<section><h2>② 联系时间线</h2>${renderTimeline(state)}</section>
+<section><h2>③ 托付</h2>${renderTrusts(state)}</section>
+<section><h2>④ 阻塞</h2>${renderBlockers(state)}</section>
+<section><h2>⑤ 预算</h2>${renderBudget(state)}</section>
+<section><h2>⑥ 守恒灯</h2>${renderConservation(state)}</section>
+</div>
+<details><summary>数据源路径（可折叠）</summary>
+<code>${esc(state.agentDir)}/proactive/lineage/*.jsonl</code><br>
+<code>${esc(state.agentDir)}/proactive/daemon/heartbeat.json</code><br>
+<code>${esc(state.agentDir)}/proactive/daemon/state.json</code><br>
+<code>${esc(state.agentDir)}/proactive/daemon.json</code><br>
+<code>${esc(state.agentDir)}/proactive/trust/registry.json</code>
+</details>
+</body>
+</html>
+`;
+}
+/**
+ * 启动 Web 监督面（**只监听 127.0.0.1**）。
+ *
+ * @param opts 见 {@link SupervisorWebOptions}。
+ */
+export async function startSupervisorWeb(opts = {}) {
+    const port = opts.port ?? 7799;
+    const collect = () => collectSupervisorState({
+        ...(opts.agentDir !== undefined ? { agentDir: opts.agentDir } : {}),
+        ...(opts.agentId !== undefined ? { agentId: opts.agentId } : {}),
+        ...(opts.timelineLimit !== undefined ? { timelineLimit: opts.timelineLimit } : {}),
+    });
+    const server = http.createServer((req, res) => {
+        // **只读**：只接受 GET / HEAD；其余方法一律 405（页面不提供任何写入口）。
+        const method = (req.method ?? "GET").toUpperCase();
+        if (method !== "GET" && method !== "HEAD") {
+            res.writeHead(405, { "content-type": "text/plain; charset=utf-8" });
+            res.end("只读：监督面不接受写操作\n");
+            return;
+        }
+        const url = req.url ?? "/";
+        const pathOnly = url.split("?")[0];
+        try {
+            if (pathOnly === "/" || pathOnly === "/index.html") {
+                const body = renderSupervisorHtml(collect());
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/state") {
+                const body = JSON.stringify(collect(), null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/timeline") {
+                const state = collect();
+                const body = JSON.stringify({ timeline: state.timeline, conservation: state.conservation }, null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/trusts") {
+                const state = collect();
+                const body = JSON.stringify({ trusts: state.trusts, goals: state.goals }, null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            if (pathOnly === "/api/budget") {
+                const state = collect();
+                const body = JSON.stringify({ budget: state.budget, blockers: state.blockers }, null, 2);
+                res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+                res.end(method === "HEAD" ? undefined : body);
+                return;
+            }
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("没有这个页面\n");
+        }
+        catch (err) {
+            res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+            res.end(`监督面内部错误：${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // **只监听 127.0.0.1**（不传 host → 会监听全部网卡 → 违反本地优先）。
+        server.listen(port, SUPERVISOR_HOST, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const actualPort = typeof address === "object" && address !== null ? address.port : port;
+    let closed = false;
+    return {
+        url: `http://${SUPERVISOR_HOST}:${actualPort}`,
+        port: actualPort,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                // 断开残留连接，保证端口**立即**释放（否则 close 会挂住）。
+                server.closeAllConnections?.();
+            });
+        },
+    };
+}

package/build/src/task-store.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 { PROACTIVE_FILE_MODE, chmodQuiet, ensureDir, proactiveDir, resolveAgentDir, writeAtomicFile, } from "./config.js";

package/build/src/thread.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 { agentSegment } from "./envelope.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-proactive",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.5",
   "description": "给 Pi 增加主动性：空闲时主动推进或提问、按时间点主动发起任务、多个会话之间对话协作。（专有软件：分发物不含源码，使用条款见包内 LICENSE）",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -46,16 +46,17 @@
     "apiVerificationNote": "本扩展的全部宿主 API 断言只对 @earendil-works/pi-coding-agent 1.3.0 验证过；升级宿主后行为可能变化，需重跑 runtime 探针后再用。"
   },
   "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-agent-core": "*"
+    "typebox": "*"
   },
-  "dependencies": {
-    "typebox": "^1.3.27"
+  "bin": {
+    "pi-proactive": "./build/cli.mjs"
   },
   "bundledDependencies": [
     "typebox"
   ],
-  "bin": {
-    "pi-proactive": "./build/cli.mjs"
+  "dependencies": {
+    "typebox": "^1.3.27"
   }
 }

package/skills/pi-proactive/SKILL.md

@@ -21,14 +21,15 @@ description: >-
 <!-- BEGIN:GEN tools -->
 | 工具 | 参数 | 作用 | 定义位置 |
 | --- | --- | --- | --- |
-| `schedule_task` | prompt（必填）：任务提示词<br>intent（可选）：投递意图，默认 wake（取值：wake \| interrupt \| queue \| notify）<br>askUser（可选）：触发时是否向用户提问（仅本地）<br>when（可选）：触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601；缺省按 10m 处理 | 预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。when 支持时长（10m）、时刻（18:30）或 ISO 时间；缺省按 10m 处理。 | `pi-proactive/extensions/proactive.ts:640` |
-| `message_agent` | to（必填）：目标 agent 的名字或 agentId<br>kind（可选）：消息语义（对方要不要回我）；缺省 notify（取值：notify \| ask \| task \| reply \| broadcast）<br>subject（可选）：标题<br>body（必填）：正文<br>intent（可选）：投递意图（怎么投给对方）；缺省 wake（取值：wake \| interrupt \| queue \| notify）<br>threadId（可选）：话题 / 会话 id（可选） | 给另一个正在运行的 agent 会话发消息（跨进程协作）。对端在线时走 socket 直达；不在线时消息落盘到对端邮箱，待其上线后处理。 | `pi-proactive/extensions/proactive.ts:685` |
-| `list_peers` | name（可选）：名字子串（大小写敏感；也命中 agentId）。同名歧义时返回与 message_agent 报错完全一致的候选<br>status（可选）：按在场状态过滤（online = 在线 = 空闲 ∪ 忙碌）（取值：online \| idle \| busy \| offline）<br>capability（可选）：按能力标签过滤（如 message_agent）<br>includeOffline（可选）：是否包含离线对端（缺省 false = 只给在线） | 列出本机可见的其它 agent 对端（名字 / agentId / 在场状态 / 心跳龄 / 能力标签 / 在途任务数 / 传输方式），可按名字、状态、能力过滤。**只读**：不产生任何对外行为。发消息前先查它（先查后发），别盲发 —— 离线对端现在打扰它不合适。 | `pi-proactive/extensions/proactive.ts:759` |
-| `proactive_query` | action（必填）：查询动作（与 /proactive 子命令同名）（取值：peers \| history \| status \| tasks \| doctor \| help \| config）<br>name（可选）：peers：名字子串过滤<br>all（可选）：peers：是否包含离线对端<br>idle（可选）：peers：只看空闲对端<br>detail（可选）：peers：只看这一个 agentId<br>scope（可选）：history：范围（对端 / 我）（取值：peer \| me）<br>peer（可选）：history：按对端 agentId 过滤<br>limit（可选）：history：条数（1-200 的整数）<br>json（可选）：doctor / config：输出 JSON | 查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）/ 查配置清单（config）。**只读**：不产生任何对外行为。 | `pi-proactive/extensions/proactive.ts:796` |
-| `progress_query` |  | 查项目进度与 ETA：返回**区间 + 置信度 + 归因 + 阻塞项**（不给单点数字）。口径唯一（scripts/progress-clock.py），与人侧 `/proactive progress` 同源同口径、逐字一致。**只读**：不产生任何对外行为。 | `pi-proactive/extensions/proactive.ts:822` |
-| `proactive_schedule` | action（必填）：排程动作（与 /proactive 子命令同名）（取值：in \| at \| every \| cancel）<br>when（可选）：in/at/every：触发时间（时长 10m / 时刻 18:30）<br>content（可选）：in/at/every：任务内容<br>id（可选）：cancel：任务 id | 排程域：定时（in）/ 定点（at）/ 周期（every）/ 取消（cancel）。落到真实任务表，到点由调度器投递；与命令面 `/proactive in\|at\|every\|cancel` 同源。 | `pi-proactive/extensions/proactive.ts:836` |
-| `proactive_peer` | action（必填）：对端动作（与 /proactive 子命令同名）（取值：tell \| spawn）<br>peer（可选）：tell：目标对端（名字或 agentId）<br>content（可选）：tell：指令内容<br>kind（可选）：tell：指令类型（缺省 ask）（取值：ask \| task \| notify）<br>subject（可选）：tell：标题<br>thread（可选）：tell：线程 id<br>name（可选）：spawn：对端名字 | 对端协作域：给对端下指令（tell）/ 创建对端会话（spawn，受同时存活数上限）。tell 的目标解析与回执三态与命令面 `/proactive tell` 完全同源。 | `pi-proactive/extensions/proactive.ts:855` |
-| `proactive_manage` | action（必填）：管理动作（与 /proactive 子命令同名）（取值：on \| off \| idle \| test）<br>state（可选）：idle：开 / 关（取值：on \| off） | 管理域：主动性总开关（on/off）、空闲触发开关（idle）、自检（test）。这些能力属 human-gated：调用只会回报「需人工确认」并给出可复制的人工指令，**不会**自行改动全局开关。 | `pi-proactive/extensions/proactive.ts:877` |
+| `schedule_task` | prompt（必填）：任务提示词<br>intent（可选）：投递意图，默认 wake（取值：wake \| interrupt \| queue \| notify）<br>askUser（可选）：触发时是否向用户提问（仅本地）<br>when（可选）：触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601；缺省按 10m 处理 | 预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。when 支持时长（10m）、时刻（18:30）或 ISO 时间；缺省按 10m 处理。 | `pi-proactive/extensions/proactive.ts:647` |
+| `message_agent` | to（必填）：目标 agent 的名字或 agentId<br>kind（可选）：消息语义（对方要不要回我）；缺省 notify（取值：notify \| ask \| task \| reply \| broadcast）<br>subject（可选）：标题<br>body（必填）：正文<br>intent（可选）：投递意图（怎么投给对方）；缺省 wake（取值：wake \| interrupt \| queue \| notify）<br>threadId（可选）：话题 / 会话 id（可选） | 给另一个正在运行的 agent 会话发消息（跨进程协作）。对端在线时走 socket 直达；不在线时消息落盘到对端邮箱，待其上线后处理。 | `pi-proactive/extensions/proactive.ts:692` |
+| `list_peers` | name（可选）：名字子串（大小写敏感；也命中 agentId）。同名歧义时返回与 message_agent 报错完全一致的候选<br>status（可选）：按在场状态过滤（online = 在线 = 空闲 ∪ 忙碌）（取值：online \| idle \| busy \| offline）<br>capability（可选）：按能力标签过滤（如 message_agent）<br>includeOffline（可选）：是否包含离线对端（缺省 false = 只给在线） | 列出本机可见的其它 agent 对端（名字 / agentId / 在场状态 / 心跳龄 / 能力标签 / 在途任务数 / 传输方式），可按名字、状态、能力过滤。**只读**：不产生任何对外行为。发消息前先查它（先查后发），别盲发 —— 离线对端现在打扰它不合适。 | `pi-proactive/extensions/proactive.ts:766` |
+| `proactive_query` | action（必填）：查询动作（与 /proactive 子命令同名）（取值：peers \| history \| status \| tasks \| doctor \| help \| config \| supervisor）<br>name（可选）：peers：名字子串过滤<br>all（可选）：peers：是否包含离线对端<br>idle（可选）：peers：只看空闲对端<br>detail（可选）：peers：只看这一个 agentId<br>scope（可选）：history：范围（对端 / 我）（取值：peer \| me）<br>peer（可选）：history：按对端 agentId 过滤<br>limit（可选）：history：条数（1-200 的整数）<br>json（可选）：doctor / config：输出 JSON | 查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）/ 查配置清单（config）/ 看监督面（supervisor）。**只读**：不产生任何对外行为。 | `pi-proactive/extensions/proactive.ts:803` |
+| `progress_query` |  | 查项目进度与 ETA：返回**区间 + 置信度 + 归因 + 阻塞项**（不给单点数字）。口径唯一（scripts/progress-clock.py），与人侧 `/proactive progress` 同源同口径、逐字一致。**只读**：不产生任何对外行为。 | `pi-proactive/extensions/proactive.ts:841` |
+| `proactive_schedule` | action（必填）：排程动作（与 /proactive 子命令同名）（取值：in \| at \| every \| cancel）<br>when（可选）：in/at/every：触发时间（时长 10m / 时刻 18:30）<br>content（可选）：in/at/every：任务内容<br>id（可选）：cancel：任务 id | 排程域：定时（in）/ 定点（at）/ 周期（every）/ 取消（cancel）。落到真实任务表，到点由调度器投递；与命令面 `/proactive in\|at\|every\|cancel` 同源。 | `pi-proactive/extensions/proactive.ts:855` |
+| `proactive_peer` | action（必填）：对端动作（与 /proactive 子命令同名）（取值：tell \| spawn）<br>peer（可选）：tell：目标对端（名字或 agentId）<br>content（可选）：tell：指令内容<br>kind（可选）：tell：指令类型（缺省 ask）（取值：ask \| task \| notify）<br>subject（可选）：tell：标题<br>thread（可选）：tell：线程 id<br>name（可选）：spawn：对端名字 | 对端协作域：给对端下指令（tell）/ 创建对端会话（spawn，受同时存活数上限）。tell 的目标解析与回执三态与命令面 `/proactive tell` 完全同源。 | `pi-proactive/extensions/proactive.ts:874` |
+| `proactive_manage` | action（必填）：管理动作（与 /proactive 子命令同名）（取值：on \| off \| idle \| test）<br>state（可选）：idle：开 / 关（取值：on \| off） | 管理域：主动性总开关（on/off）、空闲触发开关（idle）、自检（test）。这些能力属 human-gated：调用只会回报「需人工确认」并给出可复制的人工指令，**不会**自行改动全局开关。 | `pi-proactive/extensions/proactive.ts:913` |
+| `proactive_assistant` | action（必填）：常驻助理动作：on 打开 / off 关闭 / status 看状态 / restart 重装（与 /proactive assistant 同名）（取值：on \| off \| status \| restart） | 常驻助理（7×24）控制：on 打开 / off 关闭 / status 看状态 / restart 重装。与人侧 `/proactive assistant …` 同源同分派 → 逐字一致；安装**不阻塞**（立即回执「正在安装…」，结果用 status 查）。装上默认 enabled=false + 干跑 → 不花钱、不主动打扰。 | `pi-proactive/extensions/proactive.ts:925` |
 <!-- END:GEN tools -->
 
 > 工具面真源 = 实现：上表由 `scripts/gen-doc-tables.sh` 从扩展的 `registerTool` 注册项与参数 schema 自动生成，**不要手改**。
@@ -140,27 +141,28 @@ description: >-
 <!-- BEGIN:GEN commands -->
 | 命令 | 参数形态 | 做什么 | 状态 |
 | --- | --- | --- | --- |
-| `/proactive status` | `无` | 总览：开关、空闲计时、待触发任务、对端在线、上次主动、本小时用量。 | 已实现 · `pi-proactive/src/commands.ts:617` |
-| `/proactive on` | `无` | 打开全部「代理自发」行为（空闲触发、模型自调度、跨会话自发请求）。 | 已实现 · `pi-proactive/src/commands.ts:653` |
-| `/proactive off` | `无` | 关闭全部「代理自发」行为；已排期任务保留但不再触发。 | 已实现 · `pi-proactive/src/commands.ts:654` |
-| `/proactive test` | `无` | 立即模拟一次触发（走完整「护栏 → 投递」链路），用于验证主动能力是否真的生效。 | 已实现 · `pi-proactive/src/commands.ts:732` |
-| `/proactive tasks` | `无` | 列出所有待触发任务（编号 / 类型 / 下次到期 / 归属 / 触发次数）。 | 已实现 · `pi-proactive/src/commands.ts:735` |
-| `/proactive cancel` | `<id>` | 取消一个任务。 | 已实现 · `pi-proactive/src/commands.ts:761` |
-| `/proactive idle` | `on\|off` | 打开 / 关闭空闲触发并设定阈值（on 可带时长参数，省略 = 用上次设定）。 | 已实现 · `pi-proactive/src/commands.ts:801` |
-| `/proactive peers` | `[--all\|--idle\|--name <子串>\|--detail <agentId>]` | 列出已注册的对端与在线状态（名字 / 忙闲 / 最后心跳）；可加 --all / --idle / --name / --detail。 | 已实现 · `pi-proactive/src/commands.ts:674` |
-| `/proactive spawn` | `[名字]` | 创建一个对端会话（子进程 pi --mode rpc）；本会话退出时一并终止。 | 已实现 · `pi-proactive/src/commands.ts:709` |
-| `/proactive in` | `<时长> <内容>` | 排一个延迟任务（默认只属于当前会话）。 | 已实现 · `pi-proactive/src/commands.ts:779` |
-| `/proactive at` | `<HH:MM> <内容>` | 排一个绝对时间任务。 | 已实现 · `pi-proactive/src/commands.ts:780` |
-| `/proactive every` | `<时长> <内容>` | 排一个周期任务。 | 已实现 · `pi-proactive/src/commands.ts:781` |
-| `/proactive help` | `无` | 打印命令速查表（命令表 / 配置键 / 最常见故障 / 详细文档路径）。 | 已实现 · `pi-proactive/src/commands.ts:816` |
-| `/proactive history` | `[peer\|me] [条数]` | 查看最近的主动行为记录（时间 / 类型 / 目标 / 结果 / 被护栏拦下的原因）。 | 已实现 · `pi-proactive/src/commands.ts:739` |
-| `/proactive doctor` | `[--json]` | 只读体检：逐项健康判定 + 处置建议（--json 机器可读）；不打扰、不耗额度。 | 已实现 · `pi-proactive/src/commands.ts:625` |
-| `/proactive progress` | `无` | 项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字；口径 = scripts/progress-clock.py）。 | 已实现 · `pi-proactive/src/commands.ts:633` |
-| `/proactive tell` | `<peer> <内容> [--kind ask\|task\|notify]` | 人侧给另一个会话下指令（--kind ask\|task\|notify，缺省 ask 要回话）；回信落回本会话。 | 已实现 · `pi-proactive/src/commands.ts:729` |
-| `/proactive config` | `[undo] [--json]` | 列出全部配置项（当前值 / 缺省值 / 取值范围 / 一句说明），先报警写错的项；config undo 撤销上一次配置改动。 | 已实现 · `pi-proactive/src/commands.ts:640` |
+| `/proactive status` | `无` | 总览：开关、空闲计时、待触发任务、对端在线、上次主动、本小时用量。 | 已实现 · `pi-proactive/src/commands.ts:632` |
+| `/proactive on` | `无` | 打开全部「代理自发」行为（空闲触发、模型自调度、跨会话自发请求）。 | 已实现 · `pi-proactive/src/commands.ts:668` |
+| `/proactive off` | `无` | 关闭全部「代理自发」行为；已排期任务保留但不再触发。 | 已实现 · `pi-proactive/src/commands.ts:669` |
+| `/proactive test` | `无` | 立即模拟一次触发（走完整「护栏 → 投递」链路），用于验证主动能力是否真的生效。 | 已实现 · `pi-proactive/src/commands.ts:758` |
+| `/proactive tasks` | `无` | 列出所有待触发任务（编号 / 类型 / 下次到期 / 归属 / 触发次数）。 | 已实现 · `pi-proactive/src/commands.ts:761` |
+| `/proactive cancel` | `<id>` | 取消一个任务。 | 已实现 · `pi-proactive/src/commands.ts:787` |
+| `/proactive idle` | `on\|off` | 打开 / 关闭空闲触发并设定阈值（on 可带时长参数，省略 = 用上次设定）。 | 已实现 · `pi-proactive/src/commands.ts:827` |
+| `/proactive peers` | `[--all\|--idle\|--name <子串>\|--detail <agentId>]` | 列出已注册的对端与在线状态（名字 / 忙闲 / 最后心跳）；可加 --all / --idle / --name / --detail。 | 已实现 · `pi-proactive/src/commands.ts:689` |
+| `/proactive spawn` | `[名字]` | 创建一个对端会话（子进程 pi --mode rpc）；本会话退出时一并终止。 | 已实现 · `pi-proactive/src/commands.ts:735` |
+| `/proactive in` | `<时长> <内容>` | 排一个延迟任务（默认只属于当前会话）。 | 已实现 · `pi-proactive/src/commands.ts:805` |
+| `/proactive at` | `<HH:MM> <内容>` | 排一个绝对时间任务。 | 已实现 · `pi-proactive/src/commands.ts:806` |
+| `/proactive every` | `<时长> <内容>` | 排一个周期任务。 | 已实现 · `pi-proactive/src/commands.ts:807` |
+| `/proactive help` | `无` | 打印命令速查表（命令表 / 配置键 / 最常见故障 / 详细文档路径）。 | 已实现 · `pi-proactive/src/commands.ts:842` |
+| `/proactive history` | `[peer\|me] [条数]` | 查看最近的主动行为记录（时间 / 类型 / 目标 / 结果 / 被护栏拦下的原因）。 | 已实现 · `pi-proactive/src/commands.ts:765` |
+| `/proactive doctor` | `[--json]` | 只读体检：逐项健康判定 + 处置建议（--json 机器可读）；不打扰、不耗额度。 | 已实现 · `pi-proactive/src/commands.ts:640` |
+| `/proactive progress` | `无` | 项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字；口径 = scripts/progress-clock.py）。 | 已实现 · `pi-proactive/src/commands.ts:648` |
+| `/proactive tell` | `<peer> <内容> [--kind ask\|task\|notify]` | 人侧给另一个会话下指令（--kind ask\|task\|notify，缺省 ask 要回话）；回信落回本会话。 | 已实现 · `pi-proactive/src/commands.ts:755` |
+| `/proactive assistant` | `on\|off\|status\|restart` | 常驻助理（7×24）控制：on 打开（后台装，不阻塞会话）/ off 关闭（回执含残留终检）/ status 看宿主·进程·心跳·上次联系 / restart 重装。与终端 CLI 共用同一套安装/卸载实现。 | 已实现 · `pi-proactive/src/commands.ts:724` |
+| `/proactive config` | `[undo] [--json]` | 列出全部配置项（当前值 / 缺省值 / 取值范围 / 一句说明），先报警写错的项；config undo 撤销上一次配置改动。 | 已实现 · `pi-proactive/src/commands.ts:655` |
 <!-- END:GEN commands -->
 
-> 命令面真源 = 实现：上表由 `scripts/gen-doc-tables.sh` 从扩展的 `SUBCOMMANDS` + `switch (sub)` 分派自动生成（**共 18 个命令**），**不要手改**。
+> 命令面真源 = 实现：上表由 `scripts/gen-doc-tables.sh` 从扩展的 `SUBCOMMANDS` + `switch (sub)` 分派自动生成（**共 19 个命令**），**不要手改**。
 
 ## 不要做的事
 
@@ -183,3 +185,66 @@ description: >-
 
 补充：消息回执是 `queued` → 尚未送达（见陷阱 1）；`/proactive test` 可强制走一次投递链路自检
 （不受总开关与冷却影响）。
+
+## 数字员工与托付（用户说人话即可，先理解意图再选能力）
+
+> 这一节是【模型用的说明书】：用户会用自然语言提要求，你要把人话映射到下面的能力。
+
+### 常驻数字员工（"让它一直在 / 别老烦我 / 它现在在干嘛"）
+```
+/proactive assistant on      打开常驻数字员工（装常驻进程 + 注册系统通知；回执含"已常驻"与三证据）
+/proactive assistant status   看它是否在跑：宿主 / 进程 / 心跳龄期 / 上次联系 / 预算余量
+/proactive assistant off     关闭（残留终检为空：任务 0 / 进程 0 / 单元 0）
+/proactive assistant restart  重启（等价再跑一次 on）
+```
+人话映射示例：
+  "让它以后一直帮我盯着" → assistant on ｜ "它现在在干嘛" → assistant status ｜ "别老烦我了" → assistant off
+★ 不要让用户手改配置文件、不要让用户装系统服务 —— 这些由上面一条命令完成。
+
+### 托付（"帮我盯着 X，Y 发生时告诉我"）
+```
+/proactive trust add "<目标>" [--when <条件>] [--notify <渠道>]   登记托付
+/proactive trust list                                          看托付：状态（活跃/已达成/已撤销）/ 下次检查 / 进度
+/proactive trust cancel <id>                                   撤销托付
+/proactive inbox                                              它问我、我还没答的
+/proactive ask "<问题>" [--wait]                                主动问它（默认异步回执；--wait 会等，超时也回执）
+```
+人话映射示例：
+  "帮我盯着 CI 变绿" → trust add（并回执"记下了，我会在变绿时告诉你"）
+  "我托付的事怎么样了"   → trust list ｜ "这个不用盯了" → trust cancel
+  "它找我啥了"           → inbox ｜ "问一下它进度" → ask
+★ 托付里的"需要人担责的决定"必须回到人（human-gated），不要自行结账。
+
+### 三层主动性（用户想要"它自己动起来"时，说清是哪一层）
+```
+L-B 托付型    我明确说"盯着 X"                    → trust add
+L-C 目标驱动  我给目标（"把发布流程跑通"）          → goal 相关命令，由它自己拆解推进、遇阻才问
+L-D 自主推进  它从未竟目标里自己发现下一步             → 由它自己推进；不可逆/对外动作仍需人确认
+```
+★ 空闲触发的主动是【浅层】：默认静默，只在确有价值且可等时开口；空转的主动是负价值。
+
+### 监督（"它今天对我做了什么"）
+```
+会话内   状态栏有摘要；pi-proactive web 起本地看板（127.0.0.1，只读）
+/proactive progress   进度与 ETA：区间 + 置信度 + 归因 + 第 3 层阻塞项（【无单点 ETA】）
+/proactive history    血缘与应答记录（触发→投递→回应→结账 四段）
+/proactive doctor     巡检健康与告警
+```
+★ 监督面是【看】的；改配置请回会话里用自然语言，不要在页面里改。
+
+### 配置（三层作用域，改配置前先知道值来自哪一层）
+```
+会话级 > agent 级 > 全局默认（每层只覆盖显式声明的键）
+★ 安全类键（预算上限 / 权限阶梯 / 来源校验 / 联系白名单）取【最严】——局部不得放宽
+/proactive config    看全部配置项与当前值、默认值、取值范围
+```
+人话映射示例："把空闲时间改成 20 分钟" → 改对应配置项 ｜ "它多久找我一次" → 看 idleTrigger.afterMs
+★ 拼错或未知的配置项会被指名并给出最相近键 —— 不要绕过它。
+
+## 不要做的事（模型侧）
+```
+× 不要让用户去装系统服务、改配置文件、开终端 —— 门槛最低的形态是"在 pi-agent 里说人话"
+× 不要在用户没表达托付时替他登记托付（那是替他做决定）
+× 不要把"待办/想法"说成"已达成" —— 未达成必须显式说明
+× 不要用单点时间承诺，用区间 + 置信度 + 阻塞项
+```

package/tools/cli.mjs

@@ -5,7 +5,7 @@
 // 单一真源：本文件是 build/cli.mjs 的**源文件**（build/ 是编译产物，不入库）。
 // build-release.sh 负责把它复制到 build/cli.mjs → npm 包的 bin 入口。
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import path from "node:path";
 import fs from "node:fs";
 
@@ -39,9 +39,18 @@ const CLI_FLAGS = {
 		"--service-name",
 		"--no-start",
 		"--purge-data",
+		"--purge-data",
 	],
 };
 
+/**
+ * `web` 子命令自己的参数（**不进 CLI_FLAGS**）。
+ *
+ * 为什么单独一张表：CLI_FLAGS 是「**转发给 .sh 脚本**的参数契约」（T1 逐条核对
+ * cli 声明的每个参数都被对应 .sh 接受）；web 不转发给任何 .sh → 不属于那张表。
+ */
+const WEB_FLAGS = ["--port", "--agent-dir", "--json"];
+
 const USAGE = `pi-proactive — 给 Pi 增加主动性（空闲主动、按点主动、多会话协作）
 
 用法：
@@ -51,6 +60,7 @@ const USAGE = `pi-proactive — 给 Pi 增加主动性（空闲主动、按点
   pi-proactive progress           进度与 ETA（区间/置信度/阻塞项）
   pi-proactive config             查看配置（全部项/当前值/默认值/范围/说明）
   pi-proactive history            主动行为与应答的血缘记录
+  pi-proactive web                本地 Web 监督面（只读；只监听 127.0.0.1；--port/--agent-dir/--json）
 
 安装（任选其一）：
   npx pi-proactive daemon install
@@ -76,8 +86,8 @@ const script = (name) => {
 };
 
 /** 参数白名单校验（**转发前**拦下未知参数 → 不把错误留给脚本去猜）。 */
-function checkFlags(sub, args) {
-	const allowed = CLI_FLAGS[sub] ?? [];
+/** 参数白名单校验（**转发前**拦下未知参数 → 不把错误留给脚本去猜）。 */
+function checkFlags(allowed, args) {
 	for (const a of args) {
 		if (!a.startsWith("--")) continue;
 		const name = a.split("=")[0];
@@ -105,7 +115,7 @@ if (cmd === "daemon") {
 		process.exit(2);
 	}
 	const rest = argv.slice(2);
-	checkFlags(sub, rest);
+	checkFlags(CLI_FLAGS[sub] ?? [], rest);
 	const code = await run("bash", [s, ...rest]);
 	if (code !== 0 && sub === "install") {
 		// 失败即回滚（不给自己留 launchd 任务 / 进程 / 单元文件）。
@@ -116,6 +126,60 @@ if (cmd === "daemon") {
 	process.exit(code);
 }
 
+/**
+ * 定位监督面模块（**两种落位**都要认：源码态 .ts / 产物态 .js）。
+ *
+ * 产物态：cli 在 <pkg>/build/cli.mjs → 模块在 <pkg>/build/src/*.js；
+ * 源码态：cli 在 <pkg>/tools/cli.mjs  → 模块在 <pkg>/src/*.ts。
+ */
+async function loadSupervisorModule(base) {
+	const candidates = [
+		path.join(here, "src", `${base}.js`),
+		path.join(here, "..", "src", `${base}.ts`),
+	];
+	for (const file of candidates) {
+		if (!fs.existsSync(file)) continue;
+		return await import(pathToFileURL(file).href);
+	}
+	throw new Error(`包内缺少监督面模块（${base}）—— 请重新安装 pi-proactive`);
+}
+
+/** `pi-proactive web`：本地 Web 监督面（**只读**；只监听 127.0.0.1）。 */
+if (cmd === "web") {
+	const rest = argv.slice(1);
+	checkFlags(WEB_FLAGS, rest);
+	const portIdx = rest.indexOf("--port");
+	let port = 7799;
+	if (portIdx >= 0) {
+		port = Number(rest[portIdx + 1]);
+		if (!Number.isInteger(port) || port < 0 || port > 65535) {
+			console.error(`--port 需要 0-65535 的整数（实际：${rest[portIdx + 1]}）`);
+			process.exit(2);
+		}
+	}
+	const dirIdx = rest.indexOf("--agent-dir");
+	const agentDir = dirIdx >= 0 ? rest[dirIdx + 1] : undefined;
+	const stateMod = await loadSupervisorModule("supervisor-state");
+	const webMod = await loadSupervisorModule("supervisor-web");
+	// --json：非交互取数（不开服务）→ 监督信息在无 TUI 的环境里同样可取。
+	if (rest.includes("--json")) {
+		const state = stateMod.collectSupervisorState(agentDir !== undefined ? { agentDir } : {});
+		console.log(JSON.stringify(state, null, 2));
+		process.exit(0);
+	}
+	const handle = await webMod.startSupervisorWeb({ port, ...(agentDir !== undefined ? { agentDir } : {}) });
+	console.log(`[pi-proactive] 监督面已启动：${handle.url}`);
+	console.log("[pi-proactive] 只读（改配置请回 Pi 会话）；只监听 127.0.0.1；Ctrl-C 退出");
+	const shutdown = async () => {
+		await handle.close();
+		process.exit(0);
+	};
+	process.on("SIGINT", () => void shutdown());
+	process.on("SIGTERM", () => void shutdown());
+}
+
 // 其余子命令暂由宿主命令面提供（保持"同一分派"口径）；此处给出明确指引而非另写实现
-console.error(`「${cmd}」由 Pi 宿主内的 /proactive ${cmd} 提供；请在 Pi 会话中执行。`);
-process.exit(2);
+else {
+	console.error(`「${cmd}」由 Pi 宿主内的 /proactive ${cmd} 提供；请在 Pi 会话中执行。`);
+	process.exit(2);
+}