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

package/CHANGELOG.md

@@ -7,6 +7,22 @@
 
 ---
 
+## 0.2.0-beta.4 — 2026-10-31
+
+### 新增
+- **会话内常驻助理入口**：`/proactive assistant on|off|status|restart`（+ 模型工具 `proactive_assistant`），与命令面**同源逐字一致**。
+- **托付与对话闭环**：`/proactive trust add|list|cancel`、`/proactive ask`、`/proactive inbox` —— 人话与斜杠命令同源。
+- **Web + TUI 双监督面**：`pi-proactive web`（本地 127.0.0.1）+ pi-agent 内状态栏摘要与面板；两���数字**逐字一致**（同一状态聚合模块）。
+- **配置三层作用域**：会话 > agent > 全局；安全类键**取最严**（护栏不可被局部放宽）。
+- **产品设计面**（独立工程目录 `docs/product/digital-employee/`）：8 页详细设计 HTML + 2 个高保真可交互原型 + ADR 决策记录。
+- **S0 内核面契约**：`docs/project/kernel-contract-s0.md` + 边界机检（内核适配 pi-agent 但不耦合）。
+
+### 修复
+- npm 包 `bin` 入口丢失（`.npmignore` 覆盖 `.gitignore`，使 `build/` 得以进包）。
+- `typebox` 归位 `peerDependencies`（符合 host-provided 扩展约定，消除加载告警）。
+- 产物构建链：每次先清空再构建，杜绝沿用陈旧产物；产物清单核对缺件即失败。
+- 安装失败自动回滚；卸载失败报告残留并给出清理命令。
+
 ## 0.2.0-beta.3 — 2026-10-29
 
 ### 新增

package/README.md

@@ -63,6 +63,21 @@ pi --extension ./pi-proactive/extensions/proactive.ts
 
 需要一个**人不在场也在干活**的常驻代理时再开（它会真花你的账号额度）：
 
+**在会话里开 / 关（推荐：不用切终端）**：
+
+```
+/proactive assistant on        # 打开常驻助理（后台装，不阻塞会话；装完看 status）
+/proactive assistant status    # 常驻状态：宿主 / 进程 / 心跳 / 上次联系
+/proactive assistant off       # 关闭（回执含残留终检：任务 / 进程 / 单元）
+/proactive assistant restart   # 重装
+```
+
+- `on` **立即回执「正在安装…」**（不等 launchd/systemd 冷启动）→ 装完用 `assistant status` 看结果；
+- 会话内与终端 CLI **共用同一套安装/卸载实现**（`tools/daemon-install.sh` / `tools/daemon-uninstall.sh`）；
+- 装不上时回执会给出**缺什么、怎么手动跑、怎么清理**三条可操作信息。
+
+**在终端里开 / 关（等价路径）**：
+
 ```bash
 # 安装（幂等；macOS 用 launchd，Linux 用 systemd --user）
 bash <安装目录>/tools/daemon-install.sh
@@ -380,30 +395,31 @@ Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的
 `switch`），未列出的子命令会被拒绝并提示可用清单。
 
 > **命令面真源 = 实现**：下表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/commands.ts` 的
-> `SUBCOMMANDS` ＋ `switch (sub)` 的 case 分派**自动生成**（共 **18 个命令**），**不要手改**；
+> `SUBCOMMANDS` ＋ `switch (sub)` 的 case 分派**自动生成**（共 **19 个命令**），**不要手改**；
 > 要改命令面请改实现，然后跑 `bash scripts/gen-doc-tables.sh --apply`（门禁 `scripts/check-doc-tables.sh` 校验）。
 
 <!-- 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 -->
 
 排期命令的排期结果会**当场回执**（任务 id、相对到期、绝对到期），任务**落盘**在任务表里，进程退出后仍在，
@@ -421,18 +437,19 @@ Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的
 <!-- 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` 从 `pi-proactive/extensions/proactive.ts` 的
-> `pi.registerTool({ name: … })` 注册项与参数 schema **自动生成**（共 **8 个模型工具**），**不要手改**；
+> `pi.registerTool({ name: … })` 注册项与参数 schema **自动生成**（共 **9 个模型工具**），**不要手改**；
 > 表中参数即真实 schema。下面三个小节是逐个工具的展开说明。
 
 ### `schedule_task`
@@ -537,7 +554,7 @@ Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的
 | `limits.quietHours` | `未设` | 静默时段 {from,to}（HH:MM，from 大于 to 表示跨零点），时段内不主动打扰。 | `pi-proactive/src/config.ts:386` |
 | `peerWatch.enabled` | `false` | 跨会话空闲协作（peer watch）开关。 | `pi-proactive/src/config.ts:351` |
 | `peerWatch.afterIdleMs` | `600000` | 连续空闲多久后才去询问 peer（毫秒）。 | `pi-proactive/src/config.ts:352` |
-| `version` | `"v1"` | 落盘格式版本；无法识别时拒绝按已知格式解析（保留原文件，不覆盖）。 | `pi-proactive/src/config.ts:1100` |
+| `version` | `"v1"` | 落盘格式版本；无法识别时拒绝按已知格式解析（保留原文件，不覆盖）。 | `pi-proactive/src/config.ts:1121` |
 <!-- END:GEN config -->
 
 > **配置面真源 = 实现**：上表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/config.ts` 的

package/build/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);
+}

package/build/extensions/proactive.js

@@ -44,6 +44,8 @@ import { SeenSet } from "../src/dedupe.js";
 import { Mailbox, gcStaleTemporaries } from "../src/mailbox.js";
 import { createEnvelope, nextHop } from "../src/envelope.js";
 import { writeToMailbox } from "../src/outbox.js";
+import { collectSupervisorState, formatSupervisorSummary } from "../src/supervisor-state.js";
+import { formatSupervisorPanel } from "../src/supervisor-tui.js";
 import { deliverCrossProcess, startSocketServer, } from "../src/socket.js";
 import { createScheduledTask, dispatchProactiveCommand, errText, formatHumanGatedNotice, formatIdleDecision, formatScheduleResult, queryPeerDirectory, SUBCOMMANDS, } from "../src/commands.js";
 const TICK_MS = 1000;
@@ -358,6 +360,7 @@ const proactiveQueryParameters = Type.Object({
         Type.Literal("doctor"),
         Type.Literal("help"),
         Type.Literal("config"),
+        Type.Literal("supervisor"),
     ], { description: "查询动作（与 /proactive 子命令同名）" }),
     name: Type.Optional(Type.String({ description: "peers：名字子串过滤" })),
     all: Type.Optional(Type.Boolean({ description: "peers：是否包含离线对端" })),
@@ -453,6 +456,10 @@ function commandContext() {
         },
         tellPeer: (args) => runTell(args),
         selfTest: () => runSelfTest(),
+        // 常驻助理后台装完 → 用户可见通道（命令面回执；工具面无此通道时静默落盘）。
+        assistantDone: (text) => {
+            currentCtx?.ui.notify(text);
+        },
     };
 }
 /**
@@ -675,10 +682,22 @@ export default function proactiveExtension(pi) {
     pi.registerTool({
         name: "proactive_query",
         label: "Proactive Query",
-        description: "查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）/ 查配置清单（config）。" +
+        description: "查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）/ 查配置清单（config）/ 看监督面（supervisor）。" +
             "**只读**：不产生任何对外行为。",
         parameters: proactiveQueryParameters,
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            // 监督面（只读）：**就地呈现**（不走命令面分派 —— 它不产生任何对外行为）。
+            // 数字与 Web 看板**同源**（同一份聚合模块）→ 两个面逐字一致。
+            if (params.action === "supervisor") {
+                const state = readSupervisorState();
+                if (state === undefined) {
+                    return { content: [{ type: "text", text: "proactive: 监督面读取失败（事实源不可读）" }], details: { level: "error" } };
+                }
+                return {
+                    content: [{ type: "text", text: formatSupervisorPanel(state).join("\n") }],
+                    details: { level: "info" },
+                };
+            }
             const parts = [params.action];
             if (params.action === "peers") {
                 if (params.all === true)
@@ -764,6 +783,19 @@ export default function proactiveExtension(pi) {
             return dispatchTool(parts.join(" "), { action: params.action });
         },
     });
+    /**
+     * 常驻域：会话内开 / 关 / 看常驻助理（7×24）。
+     *
+     * 与人侧 `/proactive assistant …` **共用同一分派**（`dispatchProactiveCommand`）→ 输出逐字一致。
+     */
+    const proactiveAssistantParameters = Type.Object({
+        action: Type.Union([
+            Type.Literal("on"),
+            Type.Literal("off"),
+            Type.Literal("status"),
+            Type.Literal("restart"),
+        ], { description: "常驻助理动作：on 打开 / off 关闭 / status 看状态 / restart 重装（与 /proactive assistant 同名）" }),
+    });
     pi.registerTool({
         name: "proactive_manage",
         label: "Proactive Manage",
@@ -774,6 +806,17 @@ export default function proactiveExtension(pi) {
             return manageTool(params.action, params.state);
         },
     });
+    pi.registerTool({
+        name: "proactive_assistant",
+        label: "Proactive Assistant",
+        description: "常驻助理（7×24）控制：on 打开 / off 关闭 / status 看状态 / restart 重装。" +
+            "与人侧 `/proactive assistant …` 同源同分派 → 逐字一致；安装**不阻塞**（立即回执「正在安装…」，结果用 status 查）。" +
+            "装上默认 enabled=false + 干跑 → 不花钱、不主动打扰。",
+        parameters: proactiveAssistantParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return dispatchTool(`assistant ${params.action}`, { action: params.action });
+        },
+    });
     pi.registerCommand("proactive", {
         description: `proactive 主动机制：${SUBCOMMANDS}`,
         handler: async (args, cmdCtx) => {
@@ -787,6 +830,14 @@ export default function proactiveExtension(pi) {
             catch {
                 // ignore: 活动标记失败不得影响命令处理
             }
+            // 监督面（只读）：TUI 面板 / 非交互模式的纯文本；数字与 Web 看板**同源**。
+            //
+            // 为什么在这里就地处理（不走 commands.ts 的分派）：监督面是**只读呈现**，
+            // 不产生任何对外行为、不落盘 → 不需要进入命令面的能力分派表。
+            if (sub === "supervisor") {
+                await showSupervisorPanel(cmdCtx);
+                return;
+            }
             // 命令面子命令 → **能力 id**（与 `docs/project/capability-catalog.json` 逐字一致）。
             //
             // 为什么需要这张表：能力是**语义**，命令/工具只是入口；这张表是「命令面 ↔ 能力目录」的
@@ -827,6 +878,8 @@ export default function proactiveExtension(pi) {
                         return "manual-help";
                     case "config":
                         return "config-inspect";
+                    case "assistant":
+                        return "assistant-resident";
                     default:
                         return "unknown";
                 }
@@ -1064,6 +1117,7 @@ export default function proactiveExtension(pi) {
             // 退订终端输入（setIdleDetect("off") 会解除订阅）。
             tracker.setIdleDetect("off");
             currentCtx?.ui.setStatus(STATUS_KEY, undefined);
+            currentCtx?.ui.setStatus(SUPERVISOR_STATUS_KEY, undefined);
             currentCtx = undefined;
             currentPi = undefined;
         }
@@ -1130,6 +1184,8 @@ async function tick() {
         }
         // 未触发时用判定原因填状态栏。
         setStatus(ctx, evaluateIdle({ config, tracker, guard, runtimeMode: ctx.mode }));
+        // 监督面状态栏（助理在不在 · 上次联系 · 预算余量；与 Web 看板同源，内建节流）。
+        setSupervisorStatus(ctx);
     }
     catch (err) {
         console.error("[proactive] tick 失败:", err);
@@ -1153,6 +1209,129 @@ function setStatus(ctx, decision) {
         // ignore: 状态栏失败不得让宿主崩溃
     }
 }
+/**
+ * 监督面的状态栏（**第二个状态栏 key**）：助理在不在 · 上次联系 · 预算余量。
+ *
+ * 与主动机制的状态栏分开：前者是「我现在为什么（没）触发」，后者是「它对我做了什么」。
+ * 数字全部来自 `src/supervisor-state.ts` 的**同一份聚合**（与 Web 看板逐字一致）。
+ */
+const SUPERVISOR_STATUS_KEY = "proactive-supervisor";
+/** 上次写监督面状态栏的时刻（节流：最多每 5s 采集一次）。 */
+let lastSupervisorStatusAt = 0;
+/** 上次写进监督面状态栏的文本（内容未变不重写 → 不刷噪声）。 */
+let lastSupervisorStatusText = "";
+/** 写监督面状态栏（失败不得冒泡；内容未变不重写）。 */
+function setSupervisorStatus(ctx) {
+    try {
+        const now = Date.now();
+        if (now - lastSupervisorStatusAt < STATUS_THROTTLE_MS)
+            return;
+        lastSupervisorStatusAt = now;
+        const text = formatSupervisorSummary(collectSupervisorState({ agentDir: resolveAgentDir() }));
+        if (text === lastSupervisorStatusText)
+            return;
+        lastSupervisorStatusText = text;
+        ctx.ui.setStatus(SUPERVISOR_STATUS_KEY, text);
+    }
+    catch {
+        // ignore: 监督面状态栏失败不得让宿主崩溃
+    }
+}
+/**
+ * 采集监督面状态（**只读**；聚合失败 → undefined，调用方如实回执）。
+ */
+function readSupervisorState() {
+    try {
+        return collectSupervisorState({ agentDir: resolveAgentDir() });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 展示监督面（TUI 面板；非交互模式 → 同样的纯文本）。
+ *
+ * 只读：面板里没有任何可点/可改的操作（写操作只在 Pi 会话的自然语言/命令面）。
+ */
+async function showSupervisorPanel(ctx) {
+    const state = readSupervisorState();
+    if (state === undefined) {
+        ctx.ui.notify("proactive: 监督面读取失败（事实源不可读）", "error");
+        return;
+    }
+    const lines = formatSupervisorPanel(state);
+    // 非交互模式（json / print / rpc 无 TUI）：同样内容以纯文本给出 → 不依赖 TUI 能力。
+    if (ctx.mode !== "tui") {
+        console.log(lines.join("\n"));
+        return;
+    }
+    await ctx.ui.custom((tui, theme, keybindings, done) => {
+        let cachedWidth;
+        let cachedLines;
+        const invalidate = () => {
+            cachedWidth = undefined;
+            cachedLines = undefined;
+        };
+        return {
+            render(width) {
+                if (cachedLines !== undefined && cachedWidth === width)
+                    return cachedLines;
+                cachedWidth = width;
+                cachedLines = [...lines, theme.fg("dim", "按 Esc 关闭")].map((line) => truncateToColumns(line, width));
+                return cachedLines;
+            },
+            handleInput(data) {
+                const close = (() => {
+                    try {
+                        return keybindings.matches(data, "tui.select.cancel") || keybindings.matches(data, "tui.select.confirm");
+                    }
+                    catch {
+                        return data === "\x1b";
+                    }
+                })();
+                if (close) {
+                    done(undefined);
+                    return;
+                }
+                invalidate();
+                tui.requestRender();
+            },
+            invalidate,
+        };
+    });
+}
+/**
+ * 按**可见列宽**裁剪一行（CJK 算 2 列）。
+ *
+ * 为什么自己算：宿主有 `truncateToWidth`，但那是宿主包里的模块 → 扩展产物不依赖它
+ * （打包后扩展只保证 peerDependencies 可解析）。宽字符按 1 列裁会溢出 → 这里按 2 列算。
+ */
+function truncateToColumns(line, width) {
+    if (width <= 0)
+        return "";
+    let used = 0;
+    let out = "";
+    for (const ch of line) {
+        const w = isWideChar(ch) ? 2 : 1;
+        if (used + w > width)
+            break;
+        used += w;
+        out += ch;
+    }
+    return out;
+}
+/** 是否是宽字符（CJK / 全角）。 */
+function isWideChar(ch) {
+    const code = ch.codePointAt(0) ?? 0;
+    return ((code >= 0x1100 && code <= 0x115f) ||
+        (code >= 0x2e80 && code <= 0xa4cf) ||
+        (code >= 0xac00 && code <= 0xd7a3) ||
+        (code >= 0xf900 && code <= 0xfaff) ||
+        (code >= 0xfe30 && code <= 0xfe6f) ||
+        (code >= 0xff00 && code <= 0xff60) ||
+        (code >= 0xffe0 && code <= 0xffe6) ||
+        (code >= 0x20000 && code <= 0x3fffd));
+}
 /**
  * `/proactive test`：强制投递一次自检消息。
  *
@@ -2226,7 +2405,12 @@ function formatHelp() {
         "  doctor [--json]      只读体检：插件面各面状态 + 判据 + 处置建议（不打扰、不耗额度）",
         "  progress             项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字）",
         "  tell <peer> <内容>    人侧给对端 agent 下指令（--kind ask|task|notify；缺省 ask）",
+        "  assistant on          打开常驻助理（7×24；后台装，不阻塞会话；装完看 assistant status）",
+        "  assistant off         关闭常驻助理（回执含残留终检：任务 / 进程 / 单元）",
+        "  assistant status      常驻状态：宿主 / 进程 / 心跳 / 上次联系",
+        "  assistant restart     重装常驻助理（等价于再跑一次 on）",
         "  help                 本页",
+        "  supervisor           监督面（只读）：助理在不在 / 联系时间线 / 托付 / 阻塞 / 预算 / 守恒等式",
         "",
         "【配置键速查】（详表见 <安装目录>/README.md「配置」）",
         "  enabled               主动性总开关（默认 true）",