pi-proactive 0.2.0-beta.7 → 0.2.0-beta.8

package/CHANGELOG.md

@@ -8,7 +8,24 @@
 ---
 
 
-### 0.2.0-beta.7 — 补齐交付三件套（HTML 使用手册 + BREAKING CHANGES）
+### 0.2.0-beta.8 — App 模式（不想开终端就能用）
+
+**用户可见新增**
+- `app/app.mjs`：App 最小可用外壳 —— 一条命令 `start` 起 pi 并注入 pi-proactive，附通知与只读监督面
+  · 子命令：`start` / `stop` / `status` / `describe` / `guide` / `ask "<…>"`
+  · **状态等待代替固定等待**：等扩展真的注册了才叫就绪；超时明确报【未就绪】+ 诊断（不 sleep 后假装成功）
+  · 默认用【专属短路径 agent 根】（端点 <100B）；`--shared` 才与宿主共用 `~/.pi/agent`
+  · `stop` 后七处零残留（进程 / socket / 端点 / agent 根 / 锁 / 日志 / launchd 单元）
+- `app/evidence.mjs`：一条命令打出 AC1–AC6 + D1–D4 的实际取证
+- 使用手册 `manual/USAGE.html` 新增 App 一节
+
+**修复**
+- 凭据谎报：pi 在新建 agent 根会写空 `{}` auth.json —— 此前被当作"有凭据"而谎报"能做事"；现按内容判定（只有真有 provider 条目才算）
+
+**仍标【未验证】**
+- 模型真回话（隔离根无凭据，零真实模型调用）· 通知中心肉眼可见 · "助理第一次主动联系我" · 信箱路径未取证 · Windows 分支未实现
+
+0.2.0-beta.7 — 补齐交付三件套（HTML 使用手册 + BREAKING CHANGES）
 
 **用户可见新增**
 - `docs/USAGE.html`：随包发布的 HTML 使用手册（安装 / 三条入口 / 常驻助理 / 状态一屏三块 / 按成因分性的故障排查 / 开发者向枚举与对拍）

package/README.md

@@ -406,25 +406,25 @@ Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的
 <!-- BEGIN:GEN commands -->
 | 命令 | 参数形态 | 做什么 | 状态 |
 | --- | --- | --- | --- |
-| `/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` |
+| `/proactive status` | `无` | 总览：开关、空闲计时、待触发任务、对端在线、上次主动、本小时用量。 | 已实现 · `pi-proactive/src/commands.ts:633` |
+| `/proactive on` | `无` | 打开全部「代理自发」行为（空闲触发、模型自调度、跨会话自发请求）。 | 已实现 · `pi-proactive/src/commands.ts:669` |
+| `/proactive off` | `无` | 关闭全部「代理自发」行为；已排期任务保留但不再触发。 | 已实现 · `pi-proactive/src/commands.ts:670` |
+| `/proactive test` | `无` | 立即模拟一次触发（走完整「护栏 → 投递」链路），用于验证主动能力是否真的生效。 | 已实现 · `pi-proactive/src/commands.ts:806` |
+| `/proactive tasks` | `无` | 列出所有待触发任务（编号 / 类型 / 下次到期 / 归属 / 触发次数）。 | 已实现 · `pi-proactive/src/commands.ts:809` |
+| `/proactive cancel` | `<id>` | 取消一个任务。 | 已实现 · `pi-proactive/src/commands.ts:835` |
+| `/proactive idle` | `on\|off` | 打开 / 关闭空闲触发并设定阈值（on 可带时长参数，省略 = 用上次设定）。 | 已实现 · `pi-proactive/src/commands.ts:875` |
+| `/proactive peers` | `[--all\|--idle\|--name <子串>\|--detail <agentId>]` | 列出已注册的对端与在线状态（名字 / 忙闲 / 最后心跳）；可加 --all / --idle / --name / --detail。 | 已实现 · `pi-proactive/src/commands.ts:690` |
+| `/proactive spawn` | `[名字]` | 创建一个对端会话（子进程 pi --mode rpc）；本会话退出时一并终止。 | 已实现 · `pi-proactive/src/commands.ts:783` |
+| `/proactive in` | `<时长> <内容>` | 排一个延迟任务（默认只属于当前会话）。 | 已实现 · `pi-proactive/src/commands.ts:853` |
+| `/proactive at` | `<HH:MM> <内容>` | 排一个绝对时间任务。 | 已实现 · `pi-proactive/src/commands.ts:854` |
+| `/proactive every` | `<时长> <内容>` | 排一个周期任务。 | 已实现 · `pi-proactive/src/commands.ts:855` |
+| `/proactive help` | `无` | 打印命令速查表（命令表 / 配置键 / 最常见故障 / 详细文档路径）。 | 已实现 · `pi-proactive/src/commands.ts:890` |
+| `/proactive history` | `[peer\|me] [条数]` | 查看最近的主动行为记录（时间 / 类型 / 目标 / 结果 / 被护栏拦下的原因）。 | 已实现 · `pi-proactive/src/commands.ts:813` |
+| `/proactive doctor` | `[--json]` | 只读体检：逐项健康判定 + 处置建议（--json 机器可读）；不打扰、不耗额度。 | 已实现 · `pi-proactive/src/commands.ts:641` |
+| `/proactive progress` | `无` | 项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字；口径 = scripts/progress-clock.py）。 | 已实现 · `pi-proactive/src/commands.ts:649` |
+| `/proactive tell` | `<peer> <内容> [--kind ask\|task\|notify]` | 人侧给另一个会话下指令（--kind ask\|task\|notify，缺省 ask 要回话）；回信落回本会话。 | 已实现 · `pi-proactive/src/commands.ts:803` |
+| `/proactive assistant` | `on\|off\|status\|restart` | 常驻助理（7×24）控制：on 打开（后台装，不阻塞会话）/ off 关闭（回执含残留终检）/ status 看宿主·进程·心跳·上次联系 / restart 重装。与终端 CLI 共用同一套安装/卸载实现。 | 已实现 · `pi-proactive/src/commands.ts:772` |
+| `/proactive config` | `[undo] [--json]` | 列出全部配置项（当前值 / 缺省值 / 取值范围 / 一句说明），先报警写错的项；config undo 撤销上一次配置改动。 | 已实现 · `pi-proactive/src/commands.ts:656` |
 <!-- END:GEN commands -->
 
 排期命令的排期结果会**当场回执**（任务 id、相对到期、绝对到期），任务**落盘**在任务表里，进程退出后仍在，

package/app/app.mjs

@@ -1024,6 +1024,8 @@ export async function stopApp(opts = {}) {
 		status: "stopped",
 		pid: lock.pid,
 		piPid: lock.piPid,
+		piBin: lock.piBin,
+		piBinSource: lock.piBinSource,
 		residue: residueReport(target, lock),
 	};
 }

package/app/evidence.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * `app/evidence.mjs` —— **M1a 验收取证脚本**（AC1–AC6 + D1–D4 的可复跑证据）。
+ *
+ * 用法：`node pi-proactive/app/evidence.mjs`
+ *
+ * App 本身的入口（同一目录的 app.mjs）：
+ *   node pi-proactive/app/app.mjs start     起 pi 并注入 pi-proactive（等扩展真的注册才算就绪）
+ *   node pi-proactive/app/app.mjs stop      停止 + 残留终检
+ *   node pi-proactive/app/app.mjs status    状态（含与面板同源的只读快照）
+ *   node pi-proactive/app/app.mjs describe  三问：它是谁 / 在干什么 / 怎么让它做事
+ *   node pi-proactive/app/app.mjs guide     首启引导（≤3 步）
+ *   node pi-proactive/app/app.mjs ask "…"   经 JSONL 下发一条 prompt（id 关联响应）
+ *
+ * 为什么有它：测试给的是「断言通过」，取证给的是**逐条的实际输出**（谁在跑、端点在哪、
+ * 通知发了没有、残留是不是零）。本脚本用**真 pi**（不碰模型：隔离 agent 根没有凭据 →
+ * prompt 被本地拒绝）跑一遍 AC1–AC6 + D1–D4 的外部可观察面。
+ *
+ * 纪律：
+ *   - 隔离：agent 根 = /tmp 下的 pp-evidence-<随机> 目录里的 pp-app-<pid>（**不写** live 目录 ~/.pi/agent/proactive）；
+ *   - 零真实模型调用：隔离根无凭据 → pi 在本地拒绝 prompt（不发网络请求）；
+ *   - 会真弹一条 macOS 通知（AC4 取证需要「系统侧可见」）；不可用时明确报降级；
+ *   - 结束清零：临时根、锁、日志、pi 子进程全部清掉。
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(here, "..");
+const app = await import(pathToFileURL(path.join(PKG_ROOT, "app", "app.mjs")).href);
+
+const base = fs.mkdtempSync("/tmp/pp-evidence-");
+const opts = { tmpDir: base, pid: process.pid, timeoutMs: 25_000, env: { ...process.env } };
+const line = (t) => console.log(`\n=== ${t} ===`);
+/** 本机在跑的 pi 进程数（按进程名计数 → 用来证明「没有第二份实例」）。 */
+const countPi = () =>
+	spawnSync("sh", ["-c", "ps ax -o comm= | grep -cx 'pi'"], { encoding: "utf8" }).stdout.trim();
+
+try {
+	line("D2 可发现性：三问（node app/app.mjs describe --json）");
+	const desc = app.describeApp();
+	for (const k of ["who", "what", "how"]) console.log(`${k}: ${desc[k]}`);
+	const src = fs.readFileSync(path.join(PKG_ROOT, "app", "app.mjs"), "utf8");
+	console.log("三问答案逐字存在于产物 app/app.mjs：", ["who", "what", "how"].every((k) => src.includes(desc[k])));
+
+	line("D1 引导：≤3 步、一次只问一件事、每步可「算了」");
+	const steps = app.guideSteps();
+	for (const s of steps) console.log(`- ${s.question}（${s.options.join(" / ")}）`);
+	console.log("步数（≤3）：", steps.length);
+
+	line("启动（真 pi · 单次注入）");
+	const before = countPi();
+	const started = await app.startApp(opts);
+	console.log("status         :", started.status);
+	console.log("pi 进程        :", started.piPid, started.piBin);
+	console.log("启动参数        :", (started.launchArgs || []).join(" "));
+	console.log("agent 根       :", started.agentRoot);
+	console.log("凭据           :", started.credential.detail);
+	console.log("通知通道       :", JSON.stringify(started.notify));
+	console.log("面板           :", started.panelUrl);
+	console.log("本机 pi 进程数  :", before, "→", countPi());
+
+	line("AC1 注入可证明（进程内扩展清单 = RPC get_commands 的真实返回）");
+	console.log("取证来源       :", started.evidence.extensionListSource);
+	console.log("扩展入口        :", started.evidence.extensionPath);
+	console.log("入口文件真实存在 :", fs.existsSync(String(started.evidence.extensionPath)));
+	console.log("命令名          :", started.evidence.extensionCommand);
+
+	line("AC2 承载（端点真的出现 + 短路径 + <100B）");
+	const ep = String(started.evidence.endpointPath);
+	console.log("端点路径        :", ep);
+	console.log("字节数          :", Buffer.byteLength(ep, "utf8"), "/ 上限 100");
+	console.log("落在 agent 根下 :", ep.startsWith(String(started.agentRoot)));
+	console.log("真实存在        :", fs.existsSync(ep));
+	console.log("是 unix socket  :", fs.existsSync(ep) ? fs.statSync(ep).isSocket() : false);
+	console.log("信箱目录        :", path.join(String(started.agentRoot), "proactive", "mailbox", String(started.agentId)));
+
+	line("D3 面板数字与命令面同源逐字一致");
+	const panel = await (await fetch(`${started.panelUrl}/api/state`)).json();
+	const cliPath = fs.existsSync(path.join(PKG_ROOT, "build", "cli.mjs"))
+		? path.join(PKG_ROOT, "build", "cli.mjs")
+		: path.join(PKG_ROOT, "tools", "cli.mjs");
+	const cmdState = JSON.parse(
+		spawnSync(process.execPath, [cliPath, "web", "--agent-dir", String(started.agentRoot), "--json"], {
+			encoding: "utf8",
+		}).stdout,
+	);
+	const strip = (o) => {
+		const c = { ...o };
+		delete c.generatedAt;
+		return c;
+	};
+	console.log(
+		"面板 /api/state ≡ 命令面 `pi-proactive web --json`：",
+		JSON.stringify(strip(panel)) === JSON.stringify(strip(cmdState)),
+	);
+	console.log(
+		"面板 /api/state ≡ App status 回执的 supervisor：",
+		JSON.stringify(strip(panel)) === JSON.stringify(strip(started.supervisor)),
+	);
+
+	line("AC3 驱动（JSONL 下发 prompt → id 关联响应）");
+	const asked = await app.askApp({ ...opts, message: "记住：CI 变绿时告诉我" });
+	console.log("请求            :", JSON.stringify(asked.request));
+	console.log("响应            :", JSON.stringify(asked.response));
+	console.log("id 关联         :", asked.response.id === asked.request.id);
+	console.log("说明            : 隔离 agent 根无凭据 → pi 在**本地**拒绝（不发网络请求 → 零真实模型调用）");
+
+	line("AC5 幂等：二次启动（不产生第二份实例 / 第二份通知注册）");
+	const again = await app.startApp(opts);
+	console.log("二次启动 status :", again.status, "｜pi 进程：", again.piPid, "｜App 进程：", again.pid);
+	console.log("本机 pi 进程数  :", countPi(), "（与首次启动相同 ⇒ 没有第二份实例）");
+
+	line("AC4 呈现：真实系统通知（macOS osascript → Notification Center 可见）");
+	const notifier = await app.createNotifier({ pkgRoot: PKG_ROOT });
+	console.log("通道可用        :", notifier.available, notifier.channel);
+	const sent = await notifier.send("M1a 取证：这是一条来自 pi-proactive App 的真实通知", {
+		title: "助理找你有事",
+	});
+	console.log("发送结果        :", JSON.stringify({ ok: sent.ok, detail: sent.detail }));
+	console.log("通知正文（四段）:\n" + sent.payload.body);
+
+	line("AC5/D4 停止 → 零残留终检");
+	const stopped = await app.stopApp(opts);
+	console.log("status          :", stopped.status);
+	console.log("残留终检        :", JSON.stringify(stopped.residue));
+	console.log(
+		"七处零残留      :",
+		!stopped.residue.appProcessAlive &&
+			!stopped.residue.piProcessAlive &&
+			!stopped.residue.endpointExists &&
+			!stopped.residue.socketExists &&
+			!stopped.residue.agentRootExists &&
+			!stopped.residue.lockExists &&
+			!stopped.residue.logExists,
+	);
+	console.log("本机 pi 进程数  :", countPi(), "（回到启动前 ⇒ 无孤儿 pi）");
+	console.log("基目录残留      :", fs.readdirSync(base).filter((n) => n.startsWith("pp-app") || n.endsWith(".lock")));
+} finally {
+	fs.rmSync(base, { recursive: true, force: true });
+	console.log("\n取证脚本结束（临时根已清）。");
+}

package/build/src/commands.js

@@ -8,6 +8,7 @@ import { formatPeerDirectory, formatPeerList } from "./peer.js";
 import { readProgressEta } from "./progress-eta.js";
 import { handleAssistantCommand } from "./assistant.js";
 import { Registry } from "./registry.js";
+import { buildPanel, ensureSupervisorWeb, stopSupervisorWeb, DEFAULT_SUPERVISOR_WEB_PORT } from "./supervisor-panel.js";
 const DETECT_LABEL = {
     terminal: "终端输入",
     "input-only": "输入事件（保守模式）",
@@ -455,6 +456,53 @@ export async function dispatchProactiveCommand(args, ctx, opts = {}) {
             }
             return { text, level: "info" };
         }
+        case "panel": {
+            // 交互面板（三侧面）：**同源状态块** —— 数字与 status / peers / history / Web 看板一致。
+            //
+            // 为什么在命令面就地取数：① 监督聚合 = `collectSupervisorState`（同一份）；
+            // ② 对端目录 = **与 `/proactive peers --all` 同一个查询**（`queryPeerDirectory`）；
+            // ③ 主动联系流水 = `contacts.jsonl`（既有读法）→ 三块不各算一套。
+            const agentDir = ctx.agentDir ?? resolveAgentDir();
+            const registry = ctx.registry ?? new Registry({ agentDir });
+            const { directory } = queryPeerDirectory({
+                registry,
+                selfAgentId: ctx.agentId,
+                inFlight: ctx.inFlightForPeer,
+                query: { includeOffline: true },
+            });
+            const panel = buildPanel({ agentDir, agentId: ctx.agentId, peers: directory });
+            return { text: panel.text, level: "info" };
+        }
+        case "web": {
+            // 只读 Web 看板（**不阻塞**）：后台起服务后立刻回执可点 URL；重复调用**不重起**。
+            const flags = parts.slice(1);
+            const portAt = flags.indexOf("--port");
+            let port = DEFAULT_SUPERVISOR_WEB_PORT;
+            if (portAt >= 0) {
+                const raw = flags[portAt + 1] ?? "";
+                port = Number(raw);
+                if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                    return { text: `proactive: --port 需要 0-65535 的整数（实际：${raw}）`, level: "error" };
+                }
+            }
+            if (flags.includes("stop")) {
+                const stopped = await stopSupervisorWeb();
+                return { text: stopped ? "监督面已停止（端口已释放）" : "监督面本来就没在跑", level: "info" };
+            }
+            const outcome = await ensureSupervisorWeb({
+                port,
+                agentDir: ctx.agentDir ?? resolveAgentDir(),
+                agentId: ctx.agentId,
+            });
+            if (!outcome.ok) {
+                return { text: `proactive: ${outcome.error ?? "监督面启动失败"}`, level: "error" };
+            }
+            const head = outcome.alreadyRunning === true ? `已在运行 ${outcome.url}` : `监督面已启动 ${outcome.url}`;
+            return {
+                text: `${head}\n只读（改配置请回 Pi 会话）· 只监听 127.0.0.1 · 停止：/proactive web stop`,
+                level: "info",
+            };
+        }
         case "assistant": {
             // 会话内常驻助理（on / off / status / restart）。
             // **与模型工具面共用同一段实现**（`handleAssistantCommand`）→ 输出逐字一致。

package/build/src/supervisor-panel.js

@@ -0,0 +1,106 @@
+/**
+ * 交互入口的**接线层**：TUI 面板编排 + 只读 Web 服务的生命周期。
+ *
+ * 为什么单独一个模块：交互入口卡要接**两个**入口（TUI 面板 / Web 看板），
+ * 而这两件事都必须**同源**（同一份聚合、逐字一致）⇒ 编排与生命周期放在一处，
+ * 渲染留在 `src/supervisor-tui.ts`（纯文本，可被 Node 测试直接断言）。
+ *
+ * 纪律：
+ * - **只读**：本模块只读既有事实面（心跳 / 值班状态 / 事件流 / 主动联系清单 / 对端注册表）；
+ * - **不重算指标**：监督数字来自 `src/supervisor-state.ts` 的**同一份聚合**，
+ *   对端名单来自 `/proactive peers` 的**同一次目录查询**（渲染逐字复用）；
+ * - **幂等**：Web 服务重复调用**不重起**（端口数不增加）；失败必须**明确报错 + 可执行建议**。
+ */
+import { readContactEntries } from "./daemon-config.js";
+import { resolveAgentDir } from "./config.js";
+import { collectSupervisorState } from "./supervisor-state.js";
+import { formatInteractivePanel } from "./supervisor-tui.js";
+import { startSupervisorWeb } from "./supervisor-web.js";
+/** Web 监督面的缺省端口（与 CLI `pi-proactive web` 同一个）。 */
+export const DEFAULT_SUPERVISOR_WEB_PORT = 7799;
+/**
+ * 采集并渲染交互面板（**只读**：不写任何文件）。
+ *
+ * @param input 见 {@link PanelInput}。
+ */
+export function buildPanel(input = {}) {
+    const agentDir = input.agentDir ?? resolveAgentDir();
+    const now = input.now ?? Date.now();
+    const state = collectSupervisorState({
+        agentDir,
+        now,
+        ...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
+    });
+    const contacts = readContactEntries(agentDir);
+    const text = formatInteractivePanel({
+        state,
+        contacts,
+        ...(input.peers !== undefined ? { peers: input.peers } : {}),
+    }).join("\n");
+    return { state, contacts, text };
+}
+/** 当前进程内已在跑的看板句柄（**幂等的唯一真源**；进程退出即释放端口）。 */
+let running;
+/** 探一下端口上是不是**已经有一份监督面**（端口被别人占 ≠ 监督面在跑）。 */
+async function probeSupervisorWeb(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/state`, { signal: AbortSignal.timeout(1000) });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        if (typeof body?.status !== "object" || body.status === null)
+            return undefined;
+        return `http://127.0.0.1:${port}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 起只读 Web 监督面（**幂等**）。
+ *
+ * - 已在跑 → 直接回「已在运行 <url>」，**不重起**（端口数不增加）；
+ * - 端口被占 → 若占着的正是监督面 → 如实说「已在运行」；否则**明确报错 + 可执行建议**。
+ */
+export async function ensureSupervisorWeb(input = {}) {
+    if (running !== undefined) {
+        return { ok: true, url: running.url, port: running.port, alreadyRunning: true };
+    }
+    const port = input.port ?? DEFAULT_SUPERVISOR_WEB_PORT;
+    try {
+        const handle = await startSupervisorWeb({
+            port,
+            ...(input.agentDir !== undefined ? { agentDir: input.agentDir } : {}),
+            ...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
+        });
+        running = handle;
+        return { ok: true, url: handle.url, port: handle.port, alreadyRunning: false };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "EADDRINUSE") {
+            const existing = await probeSupervisorWeb(port);
+            if (existing !== undefined)
+                return { ok: true, url: existing, port, alreadyRunning: true };
+            return {
+                ok: false,
+                error: `端口 ${port} 已被占用（EADDRINUSE）—— 监督面没起来。\n` +
+                    `可执行建议：① 换一个端口：/proactive web --port ${port + 1}；` +
+                    `② 或先停掉占用它的进程：lsof -nP -iTCP:${port} -sTCP:LISTEN`,
+            };
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `监督面启动失败（端口 ${port}）：${detail}\n可执行建议：/proactive web --port 0（随机端口）` };
+    }
+}
+/**
+ * 停掉本进程内的看板（**释放端口**；幂等：本来没跑 → 返回 false）。
+ */
+export async function stopSupervisorWeb() {
+    if (running === undefined)
+        return false;
+    const handle = running;
+    running = undefined;
+    await handle.close();
+    return true;
+}

package/build/src/supervisor-tui.js

@@ -9,8 +9,9 @@
  * 着色由扩展层用宿主的 theme 加，宽度裁剪由扩展层做 → 本模块可被纯 Node 测试直接断言。
  */
 import { formatBudgetLine, formatConservationLine, formatEntrustmentConservationLine, formatStatusLine, formatSupervisorSummary, } from "./supervisor-state.js";
+import { formatPeerDirectory } from "./peer.js";
 /** 毫秒 → `MM-DD HH:mm:ss`（本地时区）。 */
-function fmtTime(ts) {
+export function formatSupervisorTime(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())}`;
@@ -39,7 +40,7 @@ export function formatSupervisorPanel(state, opts = {}) {
             const len = t.bodyLen === undefined ? "" : ` · 正文 ${t.bodyLen} 字`;
             const digest = t.bodyDigest === undefined ? "" : ` · 摘要 ${t.bodyDigest}`;
             const peer = t.peer === undefined ? "" : ` · 对端 ${t.peer}`;
-            lines.push(`      ${fmtTime(t.ts)}  ${t.summary}${len}${digest}${peer}`);
+            lines.push(`      ${formatSupervisorTime(t.ts)}  ${t.summary}${len}${digest}${peer}`);
         }
     }
     lines.push(`托付（${state.trusts.length}）`);
@@ -83,3 +84,126 @@ export function formatSupervisorPanel(state, opts = {}) {
 export function formatSupervisorText(state, opts = {}) {
     return formatSupervisorPanel(state, opts).join("\n");
 }
+/** 主动联系流水最多显示几条（缺省）。 */
+const DEFAULT_CONTACT_LIMIT = 5;
+/** 「在不在」的判定（**不猜**：心跳在 + 进程活着 = 在跑；装过但没跑 / 没装过 = 明说）。 */
+function livenessVerdict(state) {
+    if (!state.status.present)
+        return "未安装（没有心跳 / 宿主状态文件）—— 助理从未常驻";
+    if (!state.status.running) {
+        const reason = state.status.notRunningReason === undefined ? "" : `（原因：${state.status.notRunningReason}）`;
+        return `装过但当前没在运行${reason}`;
+    }
+    return "在跑（心跳在 + 进程活着）";
+}
+/** 当前模式（★干跑必须显式；被阻塞 / 预算耗尽一并点名）。 */
+function runModeLine(state) {
+    if (!state.status.running)
+        return "—（值班进程没在跑 → 形态未知）";
+    const base = state.status.runMode === "dry-run"
+        ? "干跑（dry-run）—— 只演练，不会真的动手"
+        : state.status.runMode === "live"
+            ? "真跑（live）"
+            : "未知（心跳里没有形态记录）";
+    const extra = [];
+    if (state.budget.exhausted)
+        extra.push("预算耗尽");
+    if (state.blockers.length > 0)
+        extra.push(`被阻塞（${state.blockers.length} 项）`);
+    return extra.length === 0 ? base : `${base} · ${extra.join(" · ")}`;
+}
+/** 对端分布（**同一份目录**的数字：在线 = 忙碌 + 空闲；总数 = 在线 + 离线）。 */
+function peerDistribution(peers) {
+    if (peers === undefined)
+        return "对端目录未初始化（协作层尚未起）";
+    const total = peers.peers.length;
+    const busy = peers.peers.filter((p) => p.status === "busy").length;
+    const idle = peers.peers.filter((p) => p.status === "idle").length;
+    const offline = peers.peers.filter((p) => p.status === "offline").length;
+    return `共 ${total} 个：在线 ${total - offline} · 忙碌 ${busy} · 空闲 ${idle} · 离线 ${offline}`;
+}
+/** 通道 → 人话（来源）。 */
+function channelLabel(channel) {
+    if (channel === "session")
+        return "会话通道";
+    if (channel === "device")
+        return "设备通道";
+    return channel;
+}
+/** 联系结局 → 人话（结果）。 */
+function outcomeLabel(outcome) {
+    switch (outcome) {
+        case "session":
+            return "已送达（会话）";
+        case "device":
+            return "已送达（设备）";
+        case "both":
+            return "已送达（会话+设备）";
+        case "skipped":
+            return "已跳过";
+        case "failed":
+            return "失败";
+        default:
+            return outcome;
+    }
+}
+/**
+ * 渲染交互面板的行（**只读**：没有任何可点的操作）。
+ *
+ * @param input 三份既有事实（监督聚合 / 对端目录 / 主动联系流水）。
+ */
+export function formatInteractivePanel(input) {
+    const { state, peers, contacts } = input;
+    const contactLimit = input.contactLimit ?? DEFAULT_CONTACT_LIMIT;
+    const lines = [];
+    lines.push("监督面板（只读 · 数字与 status / peers / history / Web 看板同源）");
+    lines.push(`聚合于 ${formatSupervisorTime(state.generatedAt)} · 数据源 ${state.agentDir}`);
+    lines.push("");
+    // ---- ① 在不在 ----
+    lines.push("① 在不在");
+    lines.push(`  判定  ${livenessVerdict(state)}`);
+    lines.push(`  状态  ${formatSupervisorSummary(state)}`);
+    lines.push(`  ${formatStatusLine(state)}`);
+    lines.push(`  模式  ${runModeLine(state)}`);
+    if (state.blockers.length === 0) {
+        lines.push("  阻塞  无");
+    }
+    else {
+        const shown = state.blockers.slice(0, 3).map((b) => b.title).join("；");
+        lines.push(`  阻塞  ${state.blockers.length} 项：${shown}`);
+    }
+    lines.push(`  预算  ${formatBudgetLine(state)}`);
+    lines.push("");
+    // ---- ② 有多少 ----
+    lines.push("② 有多少（对端 · 与 /proactive peers --all 同源）");
+    lines.push(`  分布  ${peerDistribution(peers)}`);
+    if (peers === undefined) {
+        lines.push("  名单  （无）");
+    }
+    else {
+        // 名单**逐字复用** `/proactive peers --all` 的渲染 → 两处不可能漂移。
+        for (const line of formatPeerDirectory(peers).split("\n"))
+            lines.push(line);
+    }
+    lines.push("");
+    // ---- ③ 有没有发生 ----
+    lines.push("③ 有没有发生（主动联系流水 · 同一份 contacts.jsonl）");
+    if (contacts.length === 0) {
+        lines.push("  主动联系  从未联系过（清单为空）");
+    }
+    else {
+        const last = contacts[contacts.length - 1];
+        const target = last.targetAgentId === undefined ? "" : `（对象 ${last.targetAgentId}）`;
+        lines.push(`  主动联系  共 ${contacts.length} 次 · 最近一次 ${formatSupervisorTime(last.ts)}${target}`);
+        const rows = contacts.slice(Math.max(0, contacts.length - contactLimit)).reverse();
+        lines.push(`  流水（最近 ${rows.length} 次）`);
+        for (const c of rows) {
+            const source = c.channels.length > 0 ? c.channels.map(channelLabel).join("+") : "无通道";
+            const to = c.targetAgentId ?? "（无对象）";
+            const reason = c.reason === undefined || c.reason === "" ? "" : `（${c.reason}）`;
+            lines.push(`    ${formatSupervisorTime(c.ts)} · ${source} · ${to} · ${outcomeLabel(c.outcome)}${reason}`);
+        }
+    }
+    lines.push(`  守恒  ${formatConservationLine(state)}`);
+    return lines;
+}

package/manual/USAGE.html

@@ -16,7 +16,7 @@ th{background:var(--code)}.warn{border-left:3px solid var(--warn);padding-left:1
 .ok{border-left:3px solid var(--ac);padding-left:12px;margin:12px 0}a{color:var(--ac)}
 </style></head><body>
 <h1>pi-proactive 使用手册</h1>
-<p class="v">版本 0.2.0-beta.7 ｜ 跨项目协作 · 主动触发 · 常驻助理 ｜ 本手册随 npm 包发布</p>
+<p class="v">版本 0.2.0-beta.8 ｜ 跨项目协作 · 主动触发 · 常驻助理 ｜ 本手册随 npm 包发布</p>
 
 <h2>1. 这是什么</h2>
 <p>pi-proactive 是 Pi Coding Agent 的扩展插件，给它加上四件事：<b>跨进程/跨项目消息协作</b>、<b>空闲主动触发</b>、<b>常驻值班助理</b>、<b>可观测的协作状态</b>。</p>
@@ -36,6 +36,17 @@ th{background:var(--code)}.warn{border-left:3px solid var(--warn);padding-left:1
 <tr><td><b>模型工具面</b></td><td>让 agent 自己查、自己协作</td><td><code>list_peers</code> · <code>message_agent</code> · <code>schedule_task</code> · <code>proactive_query</code> · <code>proactive_schedule</code> · <code>proactive_peer</code> · <code>proactive_manage</code></td></tr>
 <tr><td><b>CLI</b></td><td>脚本化 / 监督</td><td><code>pi-proactive --help</code></td></tr></table>
 
+<h2>3.5 App 模式（不想开终端就用它）</h2>
+<pre><code>node ~/.pi/agent/npm/node_modules/pi-proactive/app/app.mjs start   # 启动（起 pi + 注入插件 + 通知 + 面板）
+node ~/.pi/agent/npm/node_modules/pi-proactive/app/app.mjs status  # 一屏状态（助理在不在/对端多少/主动联系流水）
+node ~/.pi/agent/npm/node_modules/pi-proactive/app/app.mjs describe # 三问：它是谁/在干什么/怎么让它做事
+node ~/.pi/agent/npm/node_modules/pi-proactive/app/app.mjs guide   # 引导（≤3 步，一步一问，随时可说"算了"）
+node ~/.pi/agent/npm/node_modules/pi-proactive/app/app.mjs stop    # 停止（进程/socket/临时目录 七处零残留）</code></pre>
+<table><tr><th>模式</th><th>说明</th></tr>
+<tr><td>默认（专属 agent 根）</td><td>隔离干净，<b>但没有模型凭据 → 只能看不能做事</b>，App 会明说这一点</td></tr>
+<tr><td><code>--shared</code></td><td>与宿主 pi 共用 <code>~/.pi/agent</code>（有凭据、能做事）→ 排障时先看这一点</td></tr></table>
+<div class="warn"><b>Windows：</b>App 外壳暂未实现 Windows 分支（会明确报"尚未实现"，不假装能跑）。</div>
+
 <h2>4. 常驻助理（7×24）</h2>
 <pre><code># 安装常驻（跨平台：macOS launchd · Linux systemd --user · Windows 计划任务）
 node ~/.pi/agent/npm/node_modules/pi-proactive/tools/daemon-install.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-proactive",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "description": "给 Pi 增加主动性：空闲时主动推进或提问、按时间点主动发起任务、多个会话之间对话协作。（专有软件：分发物不含源码，使用条款见包内 LICENSE）",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/skills/pi-proactive/SKILL.md

@@ -141,25 +141,25 @@ description: >-
 <!-- BEGIN:GEN commands -->
 | 命令 | 参数形态 | 做什么 | 状态 |
 | --- | --- | --- | --- |
-| `/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` |
+| `/proactive status` | `无` | 总览：开关、空闲计时、待触发任务、对端在线、上次主动、本小时用量。 | 已实现 · `pi-proactive/src/commands.ts:633` |
+| `/proactive on` | `无` | 打开全部「代理自发」行为（空闲触发、模型自调度、跨会话自发请求）。 | 已实现 · `pi-proactive/src/commands.ts:669` |
+| `/proactive off` | `无` | 关闭全部「代理自发」行为；已排期任务保留但不再触发。 | 已实现 · `pi-proactive/src/commands.ts:670` |
+| `/proactive test` | `无` | 立即模拟一次触发（走完整「护栏 → 投递」链路），用于验证主动能力是否真的生效。 | 已实现 · `pi-proactive/src/commands.ts:806` |
+| `/proactive tasks` | `无` | 列出所有待触发任务（编号 / 类型 / 下次到期 / 归属 / 触发次数）。 | 已实现 · `pi-proactive/src/commands.ts:809` |
+| `/proactive cancel` | `<id>` | 取消一个任务。 | 已实现 · `pi-proactive/src/commands.ts:835` |
+| `/proactive idle` | `on\|off` | 打开 / 关闭空闲触发并设定阈值（on 可带时长参数，省略 = 用上次设定）。 | 已实现 · `pi-proactive/src/commands.ts:875` |
+| `/proactive peers` | `[--all\|--idle\|--name <子串>\|--detail <agentId>]` | 列出已注册的对端与在线状态（名字 / 忙闲 / 最后心跳）；可加 --all / --idle / --name / --detail。 | 已实现 · `pi-proactive/src/commands.ts:690` |
+| `/proactive spawn` | `[名字]` | 创建一个对端会话（子进程 pi --mode rpc）；本会话退出时一并终止。 | 已实现 · `pi-proactive/src/commands.ts:783` |
+| `/proactive in` | `<时长> <内容>` | 排一个延迟任务（默认只属于当前会话）。 | 已实现 · `pi-proactive/src/commands.ts:853` |
+| `/proactive at` | `<HH:MM> <内容>` | 排一个绝对时间任务。 | 已实现 · `pi-proactive/src/commands.ts:854` |
+| `/proactive every` | `<时长> <内容>` | 排一个周期任务。 | 已实现 · `pi-proactive/src/commands.ts:855` |
+| `/proactive help` | `无` | 打印命令速查表（命令表 / 配置键 / 最常见故障 / 详细文档路径）。 | 已实现 · `pi-proactive/src/commands.ts:890` |
+| `/proactive history` | `[peer\|me] [条数]` | 查看最近的主动行为记录（时间 / 类型 / 目标 / 结果 / 被护栏拦下的原因）。 | 已实现 · `pi-proactive/src/commands.ts:813` |
+| `/proactive doctor` | `[--json]` | 只读体检：逐项健康判定 + 处置建议（--json 机器可读）；不打扰、不耗额度。 | 已实现 · `pi-proactive/src/commands.ts:641` |
+| `/proactive progress` | `无` | 项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字；口径 = scripts/progress-clock.py）。 | 已实现 · `pi-proactive/src/commands.ts:649` |
+| `/proactive tell` | `<peer> <内容> [--kind ask\|task\|notify]` | 人侧给另一个会话下指令（--kind ask\|task\|notify，缺省 ask 要回话）；回信落回本会话。 | 已实现 · `pi-proactive/src/commands.ts:803` |
+| `/proactive assistant` | `on\|off\|status\|restart` | 常驻助理（7×24）控制：on 打开（后台装，不阻塞会话）/ off 关闭（回执含残留终检）/ status 看宿主·进程·心跳·上次联系 / restart 重装。与终端 CLI 共用同一套安装/卸载实现。 | 已实现 · `pi-proactive/src/commands.ts:772` |
+| `/proactive config` | `[undo] [--json]` | 列出全部配置项（当前值 / 缺省值 / 取值范围 / 一句说明），先报警写错的项；config undo 撤销上一次配置改动。 | 已实现 · `pi-proactive/src/commands.ts:656` |
 <!-- END:GEN commands -->
 
 > 命令面真源 = 实现：上表由 `scripts/gen-doc-tables.sh` 从扩展的 `SUBCOMMANDS` + `switch (sub)` 分派自动生成（**共 19 个命令**），**不要手改**。