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

package/CHANGELOG.md

@@ -7,6 +7,23 @@
 
 ---
 
+## 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 +34,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

@@ -380,28 +380,30 @@ Usage: `/proactive <子命令>`。下表**逐条对应实现里实际注册的
 `switch`），未列出的子命令会被拒绝并提示可用清单。
 
 > **命令面真源 = 实现**：下表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/commands.ts` 的
-> `SUBCOMMANDS` ＋ `switch (sub)` 的 case 分派**自动生成**（共 **16 个命令**），**不要手改**；
+> `SUBCOMMANDS` ＋ `switch (sub)` 的 case 分派**自动生成**（共 **18 个命令**），**不要手改**；
 > 要改命令面请改实现，然后跑 `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: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` |
 <!-- END:GEN commands -->
 
 排期命令的排期结果会**当场回执**（任务 id、相对到期、绝对到期），任务**落盘**在任务表里，进程退出后仍在，
@@ -419,17 +421,18 @@ 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: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` |
 <!-- END:GEN tools -->
 
 > **模型工具面真源 = 实现**：上表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/extensions/proactive.ts` 的
-> `pi.registerTool({ name: … })` 注册项与参数 schema **自动生成**（共 **7 个模型工具**），**不要手改**；
+> `pi.registerTool({ name: … })` 注册项与参数 schema **自动生成**（共 **8 个模型工具**），**不要手改**；
 > 表中参数即真实 schema。下面三个小节是逐个工具的展开说明。
 
 ### `schedule_task`
@@ -534,7 +537,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:1100` |
 <!-- END:GEN config -->
 
 > **配置面真源 = 实现**：上表由 `scripts/gen-doc-tables.sh` 从 `pi-proactive/src/config.ts` 的
@@ -583,8 +586,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,121 @@
+#!/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 } 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",
+	],
+};
+
+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            主动行为与应答的血缘记录
+
+安装（任选其一）：
+  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(sub, args) {
+	const allowed = CLI_FLAGS[sub] ?? [];
+	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(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);
+}
+
+// 其余子命令暂由宿主命令面提供（保持"同一分派"口径）；此处给出明确指引而非另写实现
+console.error(`「${cmd}」由 Pi 宿主内的 /proactive ${cmd} 提供；请在 Pi 会话中执行。`);
+process.exit(2);

package/build/extensions/proactive.js

@@ -27,7 +27,7 @@ import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { Type } from "typebox";
-import { PROACTIVE_FILE_MODE, chmodQuiet, defaultConfig, ensureDir, hardenProactivePermissions, loadConfig, resolveAgentDir, saveEnabled, } from "../src/config.js";
+import { PROACTIVE_FILE_MODE, chmodQuiet, defaultConfig, ensureDir, hardenProactivePermissions, loadConfig, resolveAgentDir, saveEnabled, ConfigValidationError } from "../src/config.js";
 import { ActivityTracker } from "../src/activity.js";
 import { Guard } from "../src/guard.js";
 import { Trigger } from "../src/trigger.js";
@@ -286,11 +286,27 @@ let peerWatch;
 const threadStores = new Map();
 /** peer watch 扫描节流（ms）：注册表读盘不必每秒做。 */
 let lastPeerWatchAt = 0;
+/**
+ * 最近一次**配置校验错误**（拼错的配置项 → 必须让用户看见，不得静默忽略）。
+ *
+ * 通道限制：配置加载发生在宿主给出 `ctx` 之前 → 先存起来，
+ * 由 `session_start`（拿得到 `ctx.ui.notify`）呈现给用户（stderr 亦有一份）。
+ */
+let pendingConfigError;
 function safeConfig() {
     try {
+        pendingConfigError = undefined;
         return loadConfig();
     }
-    catch {
+    catch (err) {
+        if (err instanceof ConfigValidationError) {
+            // M8：未知配置项 → **报错并指名**（键名 + 文件路径 + 建议值）。
+            pendingConfigError = err.message;
+            console.error(err.message);
+        }
+        else {
+            console.error("[proactive] 配置加载失败:", err);
+        }
         return defaultConfig();
     }
 }
@@ -332,7 +348,7 @@ const scheduleTaskParameters = Type.Object({
  * 参数名与命令面一致（`when` / `content` / `id` / `peer` / `scope` / `limit` / `name` / `all` …），
  * `action` 的取值就是命令面的子命令名 → 语义同源、可机检。
  */
-/** 查询域：查对端 / 看历史 / 看状态 / 看任务 / 只读体检 / 看手册。 */
+/** 查询域：查对端 / 看历史 / 看状态 / 看任务 / 只读体检 / 看手册 / 查配置清单。 */
 const proactiveQueryParameters = Type.Object({
     action: Type.Union([
         Type.Literal("peers"),
@@ -341,6 +357,7 @@ const proactiveQueryParameters = Type.Object({
         Type.Literal("tasks"),
         Type.Literal("doctor"),
         Type.Literal("help"),
+        Type.Literal("config"),
     ], { description: "查询动作（与 /proactive 子命令同名）" }),
     name: Type.Optional(Type.String({ description: "peers：名字子串过滤" })),
     all: Type.Optional(Type.Boolean({ description: "peers：是否包含离线对端" })),
@@ -349,8 +366,15 @@ const proactiveQueryParameters = Type.Object({
     scope: Type.Optional(Type.Union([Type.Literal("peer"), Type.Literal("me")], { description: "history：范围（对端 / 我）" })),
     peer: Type.Optional(Type.String({ description: "history：按对端 agentId 过滤" })),
     limit: Type.Optional(Type.String({ description: "history：条数（1-200 的整数）" })),
-    json: Type.Optional(Type.Boolean({ description: "doctor：输出 JSON" })),
+    json: Type.Optional(Type.Boolean({ description: "doctor / config：输出 JSON" })),
 });
+/**
+ * 进度 / ETA 查询（任务卡 ETA · E3）。
+ *
+ * 与人侧 `/proactive progress` **同源同口径**：同一个分派（`dispatchProactiveCommand`）→
+ * 同一份快照 → 两侧正文逐字一致。
+ */
+const progressQueryParameters = Type.Object({});
 /** 排程域：定时 / 定点 / 周期 / 取消。 */
 const proactiveScheduleParameters = Type.Object({
     action: Type.Union([Type.Literal("in"), Type.Literal("at"), Type.Literal("every"), Type.Literal("cancel")], { description: "排程动作（与 /proactive 子命令同名）" }),
@@ -651,7 +675,7 @@ export default function proactiveExtension(pi) {
     pi.registerTool({
         name: "proactive_query",
         label: "Proactive Query",
-        description: "查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）。" +
+        description: "查询域：查对端（peers）/ 看主动行为历史（history）/ 看状态（status）/ 看任务（tasks）/ 只读体检（doctor）/ 看命令手册（help）/ 查配置清单（config）。" +
             "**只读**：不产生任何对外行为。",
         parameters: proactiveQueryParameters,
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -675,12 +699,24 @@ export default function proactiveExtension(pi) {
                 if (params.limit !== undefined && /^\d+$/.test(params.limit))
                     parts.push(params.limit);
             }
-            else if (params.action === "doctor" && params.json === true) {
+            else if ((params.action === "doctor" || params.action === "config") && params.json === true) {
                 parts.push("--json");
             }
             return dispatchTool(parts.join(" "), { action: params.action });
         },
     });
+    pi.registerTool({
+        name: "progress_query",
+        label: "Progress Query",
+        description: "查项目进度与 ETA：返回**区间 + 置信度 + 归因 + 阻塞项**（不给单点数字）。" +
+            "口径唯一（scripts/progress-clock.py），与人侧 `/proactive progress` 同源同口径、逐字一致。" +
+            "**只读**：不产生任何对外行为。",
+        parameters: progressQueryParameters,
+        async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+            // **同源**：与人侧 `/proactive progress` 走同一个分派 → 同一份快照 → 逐字一致。
+            return dispatchTool("progress", { capability: "progress-eta" });
+        },
+    });
     pi.registerTool({
         name: "proactive_schedule",
         label: "Proactive Schedule",
@@ -785,8 +821,12 @@ export default function proactiveExtension(pi) {
                         return "activity-history";
                     case "doctor":
                         return "health-diagnose";
+                    case "progress":
+                        return "progress-eta";
                     case "help":
                         return "manual-help";
+                    case "config":
+                        return "config-inspect";
                     default:
                         return "unknown";
                 }
@@ -2184,6 +2224,7 @@ function formatHelp() {
         "  every <时长> <内容>  排期重复",
         "  test                 强制走一次投递链路自检（不受总开关与冷却影响）",
         "  doctor [--json]      只读体检：插件面各面状态 + 判据 + 处置建议（不打扰、不耗额度）",
+        "  progress             项目进度 + ETA：区间 + 置信度 + 归因 + 阻塞项（不给单点数字）",
         "  tell <peer> <内容>    人侧给对端 agent 下指令（--kind ask|task|notify；缺省 ask）",
         "  help                 本页",
         "",

package/build/src/commands.js

@@ -1,10 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { IDLE_ENABLE_HINT, effectiveIdleDetect } from "./idle.js";
 import { DEFAULT_WHEN_MS, SUPPORTED_DURATION_FORMATS, SUPPORTED_WHEN_FORMATS, parseScheduleExpression, } from "./scheduler.js";
-import { resolveAgentDir } from "./config.js";
+import { readConfigReport, resolveAgentDir, undoConfigChange, } from "./config.js";
 import { formatHealthReport, healthToJson } from "./health.js";
 import { formatLineageHistory } from "./lineage.js";
 import { formatPeerDirectory, formatPeerList } from "./peer.js";
+import { readProgressEta } from "./progress-eta.js";
 import { Registry } from "./registry.js";
 const DETECT_LABEL = {
     terminal: "终端输入",
@@ -210,6 +211,59 @@ export function formatScheduleResult(task, now = Date.now(), info = {}) {
 export function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** 配置值 → 人话（长文本截断，避免一屏塞不下）。 */
+function formatConfigValue(value) {
+    if (value === undefined)
+        return "（未设置）";
+    if (typeof value === "string") {
+        if (value.length <= 60)
+            return `"${value}"`;
+        return `"${value.slice(0, 60)}…（共 ${value.length} 字）"`;
+    }
+    if (typeof value === "object") {
+        const text = JSON.stringify(value);
+        return text.length <= 60 ? text : `${text.slice(0, 60)}…`;
+    }
+    return String(value);
+}
+/**
+ * `/proactive config` 的清单（M6）：**全部配置项 + 当前值 + 默认值 + 取值范围 + 一句说明**。
+ *
+ * 为什么当前值取自**文件**（`readConfigReport` 的口径）：文件才是用户写的东西；
+ * 运行期配置在有未知项时会整体回落缺省 → 用它会把「你写的值」显示成「缺省值」（更迷惑）。
+ */
+export function formatConfigReport(report) {
+    const lines = [];
+    lines.push(`配置清单（文件：${report.file}${report.exists ? "" : "（尚不存在 → 全部用缺省）"}）`);
+    const unknown = report.issues.filter((issue) => issue.category === "unknown-key");
+    if (unknown.length > 0) {
+        lines.push("");
+        lines.push(`⚠ 有 ${unknown.length} 个配置项写错了（不会被静默忽略）：`);
+        for (const issue of unknown) {
+            lines.push(`  · 键 "${issue.key}"` + (issue.suggestion === undefined ? "" : ` → 你是不是想写 "${issue.suggestion}"？`));
+        }
+    }
+    const typeIssues = report.issues.filter((issue) => issue.category === "type-mismatch");
+    if (typeIssues.length > 0) {
+        lines.push("");
+        lines.push(`⚠ 有 ${typeIssues.length} 个配置项类型不对（已按缺省值处理）：`);
+        for (const issue of typeIssues)
+            lines.push(`  · ${issue.message}`);
+    }
+    let section = "";
+    for (const item of report.items) {
+        if (item.section !== section) {
+            section = item.section;
+            lines.push("");
+            lines.push(`【${section}】`);
+        }
+        lines.push(`  ${item.path.padEnd(30)}当前：${formatConfigValue(item.current)}   缺省：${formatConfigValue(item.defaultValue)}   取值：${item.range}`);
+        lines.push(`      ${item.description}`);
+    }
+    lines.push("");
+    lines.push("改法：直接改上面的文件（写错的键会被指名，不会静默忽略）；开关类用 /proactive on|off；撤销上一次改动：/proactive config undo。");
+    return lines.join("\n");
+}
 /**
  * human-gated 回执文案（**单一真源**：模型工具面用；命令面不经过这里 —— 命令面由人触发）。
  *
@@ -223,7 +277,9 @@ export function formatHumanGatedNotice(notice) {
 export const SUBCOMMANDS = "status | on | off | test | tasks | cancel <id> | idle on|off | peers [--all|--idle|--name <子串>|--detail <agentId>] | spawn [名字]" +
     " | in <时长> <内容> | at <HH:MM> <内容> | every <时长> <内容> | help" +
     " | history [peer|me] [条数] | doctor [--json]" +
-    " | tell <peer> <内容> [--kind ask|task|notify]";
+    " | progress" +
+    " | tell <peer> <内容> [--kind ask|task|notify]" +
+    " | config [undo] [--json]";
 /** `/proactive status` 末尾的指路行（MANUAL）。 */
 export const HELP_POINTER = "指路：/proactive help 看命令表与最常见故障；详细文档见 <安装目录>/README.md（随包分发）。";
 /**
@@ -321,6 +377,26 @@ export async function dispatchProactiveCommand(args, ctx, opts = {}) {
             const asJson = parts.slice(1).includes("--json");
             return { text: asJson ? healthToJson(report) : formatHealthReport(report), level: "info" };
         }
+        case "progress": {
+            // 进度 + ETA（任务卡 ETA）：**唯一口径**在 scripts/progress-clock.py（src/progress-eta.ts 接线）。
+            // 人侧命令与 AI 侧工具（progress_query）走同一段 → 逐字一致（同一快照）。
+            // 输出 = 区间 + 置信度 + 归因 + 阻塞项；**没有单点 ETA**。
+            const eta = await readProgressEta();
+            return { text: eta.text, level: eta.ok ? "info" : "error" };
+        }
+        case "config": {
+            // M6「配置可查」：全部项 + 当前值 + 缺省值 + 取值范围 + 一句说明；M9 的撤销入口同在此。
+            const action = (parts[1] ?? "").toLowerCase();
+            if (action === "undo") {
+                const result = undoConfigChange();
+                return { text: result.message, level: result.ok ? "info" : "error" };
+            }
+            const report = readConfigReport();
+            if (parts.slice(1).includes("--json")) {
+                return { text: JSON.stringify(report, null, 2), level: "info" };
+            }
+            return { text: formatConfigReport(report), level: "info" };
+        }
         case "on":
         case "off": {
             const on = sub === "on";