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

package/CHANGELOG.md

@@ -7,6 +7,39 @@
 
 ---
 
+## 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
+
+### 新增
+- **交付形态**：`pi-proactive` npm 包新增 **bin 入口**（`npx pi-proactive daemon install` / `npm i -g`），无需仓库、无需 bash。
+- **一键常驻助理**：一条命令安装常驻进程（自动检测平台/双宿主，herdr 优先、系统宿主兜底接管）→ 回执「已常驻」+ 三证据自检 → 卸载零残留。
+- **主动联系**：常驻进程在会话离线时仍能主动联系并进入「它联系了我什么」清单；找不到已登记会话则不联系（留审计记录）；会话投递与设备通知双通道去重。
+- **ETA 与进度预期**：`/proactive progress`（人）· `progress_query`（AI）· 快照【进度与 ETA】段，三处同源同口径；输出为【区间 + 置信度 + 归因 + 第3层阻塞项】，无单点 ETA。
+- **托付 → 目标驱动 → 自主推进**：三层主动性同一循环（目标 → 候选 → 打分 → 执行 → 结账 → 回灌），六条护栏（预算硬上限 / 权限阶梯 / 可中止 / 不越界 / 可追溯 / 未达成不得静默结账）。
+- **配置可用性**：未知或拼错的配置项被指名（含最相近键建议），`/proactive config` 可查全部项与默认值；配置写入原子化 + 备份 + 可撤销。
+- **跨平台交付**：安装/卸载/运行统一为 Node 入口（一份逻辑 + 三份注册）。
+
+### 修复
+- 产物包内路径解析按运行环境取真源（开发态 src / 产物态 build），修复「装上跑不起来」。
+- 打包链每次先清空再构建，杜绝沿用陈旧产物（曾导致包内缺 daemon-host.js）。
+- 安装失败自动回滚；卸载失败报告残留并给出清理命令。
+- 门禁新增：G17 外置内容完整性 · G18 推进质量保障；G3 排除 node_modules；G5 纳入团队脚本与交付制品。
+
 ## 0.2.0-beta.2（专有 **产物包** 版：分发物不含源码）
 
 - **许可**：`license` 由 `MIT` 改为 **`SEE LICENSE IN LICENSE`**；新增**私有协议正文**文件 `LICENSE`（版权所有 / 仅限内部授权使用 / **禁止再分发** / 禁止反编译与再授权 / 授权期限与联系）
@@ -17,6 +50,18 @@
 - **新增** `scripts/tests/publish-preflight.test.sh`：上述判据的红→绿回归自测（含「`UNLICENSED` + 公开仍阻断」的回归用例）
 - **实现修正**：`src/health.ts` 的 `pluginVersion()` 支持产物态落位（`build/src/` → 上两级读 `package.json`），否则产物包内 `/proactive doctor` 会报版本 `unknown`
 - **前置动作**：beta.1（MIT 元数据、公开可下载）已由版权方在 npm 网页端撤销（`npm view pi-proactive` → 404），包名可重新占用
+- **发布**：已发到公共 npm —— `pi-proactive@0.2.0-beta.2`（dist-tag `latest` / `beta`；`license: SEE LICENSE IN LICENSE`；tarball 472.6 kB / 解包 2.2 MB / 1450 文件，其中 1449 个是 bundled typebox）；`npm view pi-proactive` 已复核版本 / description / license
+
+### 分发形态变更的宿主验证（证据）
+
+| 验证项 | 命令 | 实测结果 |
+|---|---|---|
+| 宿主接受 `.js` 入口 | `pi --mode rpc --no-session` + `get_commands`（隔离 agent 目录安装产物包） | 回显 `"sourceInfo":{"path":".../build/extensions/proactive.js"}` 且命令名 `proactive` 已注册 |
+| 产物包内 typebox 可解析 | `node -e "import('.../build/extensions/proactive.js')"` | `LOADED OK, default export type = function`（不依赖宿主 alias） |
+| 产物态版本号正确 | `/proactive doctor --json` | `"pluginVersion": "0.2.0-beta.2"`（修复前为 `unknown`） |
+| 分发物零 `.ts` | `tar -tzf pi-proactive-0.2.0-beta.2.tgz` 后统计以 `.ts` 结尾的条目 | `0` |
+| 发布前检查 | `bash scripts/ci/publish-preflight.sh --registry https://registry.npmjs.org --public` | 「✅ 检查通过」（退出码 0） |
+| 公开 npm 安装 | `pi install npm:pi-proactive` + 同上 rpc 检查 | 已注册 `proactive`，路径 `.../npm/node_modules/pi-proactive/build/extensions/proactive.js` |
 
 ## 许可与分发
 

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,28 +395,31 @@ Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的
 `switch`），未列出的子命令会被拒绝并提示可用清单。
 
 > **命令面真源 = 实现**：下表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/commands.ts` 的
-> `SUBCOMMANDS` ＋ `switch (sub)` 的 case 分派**自动生成**（共 **16 个命令**），**不要手改**；
+> `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:550` |
-| `/proactive on` | `无` | 打开全部「代理自发」行为（空闲触发、模型自调度、跨会话自发请求）。 | 已实现 · `pi-proactive/src/commands.ts:565` |
-| `/proactive off` | `无` | 关闭全部「代理自发」行为；已排期任务保留但不再触发。 | 已实现 · `pi-proactive/src/commands.ts:566` |
-| `/proactive test` | `无` | 立即模拟一次触发（走完整「护栏 → 投递」链路），用于验证主动能力是否真的生效。 | 已实现 · `pi-proactive/src/commands.ts:644` |
-| `/proactive tasks` | `无` | 列出所有待触发任务（编号 / 类型 / 下次到期 / 归属 / 触发次数）。 | 已实现 · `pi-proactive/src/commands.ts:647` |
-| `/proactive cancel` | `<id>` | 取消一个任务。 | 已实现 · `pi-proactive/src/commands.ts:673` |
-| `/proactive idle` | `on\|off` | 打开 / 关闭空闲触发并设定阈值（on 可带时长参数，省略 = 用上次设定）。 | 已实现 · `pi-proactive/src/commands.ts:713` |
-| `/proactive peers` | `[--all\|--idle\|--name <子串>\|--detail <agentId>]` | 列出已注册的对端与在线状态（名字 / 忙闲 / 最后心跳）；可加 --all / --idle / --name / --detail。 | 已实现 · `pi-proactive/src/commands.ts:586` |
-| `/proactive spawn` | `[名字]` | 创建一个对端会话（子进程 pi --mode rpc）；本会话退出时一并终止。 | 已实现 · `pi-proactive/src/commands.ts:621` |
-| `/proactive in` | `<时长> <内容>` | 排一个延迟任务（默认只属于当前会话）。 | 已实现 · `pi-proactive/src/commands.ts:691` |
-| `/proactive at` | `<HH:MM> <内容>` | 排一个绝对时间任务。 | 已实现 · `pi-proactive/src/commands.ts:692` |
-| `/proactive every` | `<时长> <内容>` | 排一个周期任务。 | 已实现 · `pi-proactive/src/commands.ts:693` |
-| `/proactive help` | `无` | 打印命令速查表（命令表 / 配置键 / 最常见故障 / 详细文档路径）。 | 已实现 · `pi-proactive/src/commands.ts:728` |
-| `/proactive history` | `[peer\|me] [条数]` | 查看最近的主动行为记录（时间 / 类型 / 目标 / 结果 / 被护栏拦下的原因）。 | 已实现 · `pi-proactive/src/commands.ts:651` |
-| `/proactive doctor` | `[--json]` | 只读体检：逐项健康判定 + 处置建议（--json 机器可读）；不打扰、不耗额度。 | 已实现 · `pi-proactive/src/commands.ts:558` |
-| `/proactive tell` | `<peer> <内容> [--kind ask\|task\|notify]` | 人侧给另一个会话下指令（--kind ask\|task\|notify，缺省 ask 要回话）；回信落回本会话。 | 已实现 · `pi-proactive/src/commands.ts:641` |
+| `/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、相对到期、绝对到期），任务**落盘**在任务表里，进程退出后仍在，
@@ -419,17 +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:624` |
-| `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:669` |
-| `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:743` |
-| `proactive_query` | action（必填）：查询动作（与 /proactive 子命令同名）（取值：peers \| history \| status \| tasks \| doctor \| help）<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：输出 JSON | 查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）。**只读**：不产生任何对外行为。 | `pi-proactive/extensions/proactive.ts:780` |
-| `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:806` |
-| `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:825` |
-| `proactive_manage` | action（必填）：管理动作（与 /proactive 子命令同名）（取值：on \| off \| idle \| test）<br>state（可选）：idle：开 / 关（取值：on \| off） | 管理域：主动性总开关（on/off）、空闲触发开关（idle）、自检（test）。这些能力属 human-gated：调用只会回报「需人工确认」并给出可复制的人工指令，**不会**自行改动全局开关。 | `pi-proactive/extensions/proactive.ts:847` |
+| `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 **自动生成**（共 **7 个模型工具**），**不要手改**；
+> `pi.registerTool({ name: … })` 注册项与参数 schema **自动生成**（共 **9 个模型工具**），**不要手改**；
 > 表中参数即真实 schema。下面三个小节是逐个工具的展开说明。
 
 ### `schedule_task`
@@ -534,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:516` |
+| `version` | `"v1"` | 落盘格式版本；无法识别时拒绝按已知格式解析（保留原文件，不覆盖）。 | `pi-proactive/src/config.ts:1121` |
 <!-- END:GEN config -->
 
 > **配置面真源 = 实现**：上表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/config.ts` 的
@@ -583,8 +603,9 @@ agents/<ref>.md     # agent 定义
 - 解析后的路径必须留在配置根目录内（越界路径与指向外部的符号链接都拒绝）；
 - 内容**单次读入快照**（外部程序同时改文件也不会读到半截内容）。
 
-示例：`pi-proactive/agents/example-reviewer.md` —— 复制到 `<agent-dir>/proactive/agents/` 后
-即可被上面的 `agentRef` 引用。
+示例：`pi-proactive/agents/example-reviewer.md`（agent 定义）与 `pi-proactive/prompts/idle-probe.md`（提示词）——
+复制到 `<agent-dir>/proactive/agents/` 或 `<agent-dir>/proactive/prompts/` 后，
+即可被上面的 `agentRef` / `promptRef` 引用。
 
 > `<agent-dir>/proactive/agents/` 下同时存在**两种**东西：对端注册表 `agents/<agentId>.json`
 > 与外置 agent 定义 `agents/<ref>.md` —— 按扩展名区分，互不覆盖。

package/build/cli.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// pi-proactive CLI —— 交付入口（npm bin / npx / 全局安装都指向这里）
+// 目标：用户只跑 `npx pi-proactive daemon install`，不需要仓库、不需要 bash。
+//
+// 单一真源：本文件是 build/cli.mjs 的**源文件**（build/ 是编译产物，不入库）。
+// build-release.sh 负责把它复制到 build/cli.mjs → npm 包的 bin 入口。
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(here, "..");
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+/**
+ * 本 CLI 会转发给常驻脚本的参数（**参数契约的单一真源**）。
+ *
+ * 为什么要有它：cli 转发参数、被调 .sh 解析参数，两边各写各的就会出现
+ * 「cli 传 --host、.sh 报未知参数」这类契约漂移（2026-10-29 实测根因 2）。
+ * 契约测试（pi-proactive/tests/daemon-packaged-runtime.test.ts）据此断言：
+ * **这里列出的每个参数，两个 .sh 都必须接受**。
+ */
+const CLI_FLAGS = {
+	install: [
+		"--host",
+		"--agent-dir",
+		"--agent-id",
+		"--label",
+		"--service-name",
+		"--no-start",
+	],
+	uninstall: [
+		"--host",
+		"--agent-dir",
+		"--agent-id",
+		"--label",
+		"--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 增加主动性（空闲主动、按点主动、多会话协作）
+
+用法：
+  pi-proactive daemon install     安装并启动常驻助理（回执「已常驻」）
+  pi-proactive daemon uninstall   卸载常驻助理（残留终检为空）
+  pi-proactive doctor             巡检健康
+  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
+  npm i -g pi-proactive && pi-proactive daemon install
+`;
+
+function run(file, args) {
+	return new Promise((resolve) => {
+		const p = spawn(file, args, { stdio: "inherit" });
+		p.on("close", (code) => resolve(code ?? 1));
+		p.on("error", () => resolve(2));
+	});
+}
+
+if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+	console.log(USAGE);
+	process.exit(0);
+}
+
+const script = (name) => {
+	const p = path.join(pkgRoot, "tools", name);
+	return fs.existsSync(p) ? p : null;
+};
+
+/** 参数白名单校验（**转发前**拦下未知参数 → 不把错误留给脚本去猜）。 */
+/** 参数白名单校验（**转发前**拦下未知参数 → 不把错误留给脚本去猜）。 */
+function checkFlags(allowed, args) {
+	for (const a of args) {
+		if (!a.startsWith("--")) continue;
+		const name = a.split("=")[0];
+		if (!allowed.includes(name)) {
+			console.error(`未知参数：${a}\n可用参数：${allowed.join(" ")}`);
+			process.exit(2);
+		}
+	}
+}
+
+if (cmd === "daemon") {
+	const sub = argv[1];
+	const map = {
+		install: "daemon-install.sh",
+		uninstall: "daemon-uninstall.sh",
+	};
+	const file = map[sub];
+	if (!file) {
+		console.error(`未知子命令：daemon ${sub ?? ""}\n${USAGE}`);
+		process.exit(2);
+	}
+	const s = script(file);
+	if (!s) {
+		console.error(`包内缺少 ${file} —— 请重新安装 pi-proactive`);
+		process.exit(2);
+	}
+	const rest = argv.slice(2);
+	checkFlags(CLI_FLAGS[sub] ?? [], rest);
+	const code = await run("bash", [s, ...rest]);
+	if (code !== 0 && sub === "install") {
+		// 失败即回滚（不给自己留 launchd 任务 / 进程 / 单元文件）。
+		console.error("[pi-proactive] 安装未成功 → 自动回滚（卸载自己刚注册的），避免留下残留");
+		const u = script("daemon-uninstall.sh");
+		if (u) await run("bash", [u, ...rest]);
+	}
+	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());
+}
+
+// 其余子命令暂由宿主命令面提供（保持"同一分派"口径）；此处给出明确指引而非另写实现
+else {
+	console.error(`「${cmd}」由 Pi 宿主内的 /proactive ${cmd} 提供；请在 Pi 会话中执行。`);
+	process.exit(2);
+}