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

package/daemon/launchd.plist

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  pi-proactive 常驻值班进程（macOS launchd LaunchAgent）。
+
+  **模板文件**：双下划线包裹的大写占位符由 `pi-proactive/tools/daemon-install.sh` 渲染
+  （节点路径 / 值班脚本路径 / agentDir / 稳定身份 / 日志目录）。
+
+  为什么用 launchd 而不是 cron（任务卡 §2①）：
+  - cron 的最小粒度是 1 分钟，且**没有崩溃自愈**；launchd 有 `KeepAlive`（进程退出即拉起）→ 崩溃重启是内建的；
+  - cron 不带环境变量语义（要绕 shell 脚本传身份）；launchd 的 `EnvironmentVariables` 是结构化的；
+  - 日志由 `StandardOutPath` / `StandardErrorPath` 落盘 → 可被巡检读。
+
+  成本硬约束：这里的 `PI_PROACTIVE_DAEMON_DRY_RUN=1` 与配置里的 `enabled=false`（默认）
+  一起保证**装上不等于花钱**。
+-->
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>__LABEL__</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>/bin/bash</string>
+		<string>__RUNNER__</string>
+	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>ThrottleInterval</key>
+	<integer>10</integer>
+	<key>ProcessType</key>
+	<string>Background</string>
+	<key>WorkingDirectory</key>
+	<string>__PKG_ROOT__</string>
+	<key>EnvironmentVariables</key>
+	<dict>
+		<key>PI_PROACTIVE_AGENT_ID</key>
+		<string>__AGENT_ID__</string>
+		<key>PI_PROACTIVE_DAEMON_DRY_RUN</key>
+		<string>1</string>
+	</dict>
+	<key>StandardOutPath</key>
+	<string>__LOG_DIR__/daemon.out.log</string>
+	<key>StandardErrorPath</key>
+	<string>__LOG_DIR__/daemon.err.log</string>
+</dict>
+</plist>

package/daemon/pi-proactive-daemon.service

@@ -0,0 +1,29 @@
+# pi-proactive 常驻值班进程（Linux systemd --user 单元）
+#
+# **模板文件**：双下划线包裹的大写占位符由 `pi-proactive/tools/daemon-install.sh` 渲染
+# （节点路径 / 值班脚本路径 / agentDir / 稳定身份）。
+#
+# 为什么用 systemd --user 而不是 cron（任务卡 §2①）：
+# - `Restart=always` → 崩溃自启是内建的（cron 没有）；
+# - `Environment=` → 稳定身份（`PI_PROACTIVE_AGENT_ID`）跨重启连续；
+# - `KillSignal=SIGTERM` + `TimeoutStopSec` → 停止时给值班进程时间写交班摘要再退出。
+#
+# 成本硬约束：`PI_PROACTIVE_DAEMON_DRY_RUN=1` + 配置里的 `enabled=false`（默认）
+# 一起保证**装上不等于花钱**。
+[Unit]
+Description=pi-proactive 常驻值班进程（7x24 数字员工）
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=/bin/bash __RUNNER__
+WorkingDirectory=__PKG_ROOT__
+Environment=PI_PROACTIVE_AGENT_ID=__AGENT_ID__
+Environment=PI_PROACTIVE_DAEMON_DRY_RUN=1
+Restart=always
+RestartSec=5
+KillSignal=SIGTERM
+TimeoutStopSec=20
+
+[Install]
+WantedBy=default.target

package/daemon/run-daemon.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+
+
+# pi-proactive 常驻助理的**保活监督器**（supervisor）。
+#
+# 角色：**同时**充当两个宿主里的「保活容器」——
+#   ① herdr 宿主：助理跑在 herdr pane 里（纯 headless：无 TUI、不抢 stdin）；
+#   ② 系统宿主：launchd / systemd --user 单元跑的就是这个脚本。
+# 两者**跑的是同一个脚本** → 谁先拿到「值班锁」谁当值班进程，另一个转为待命。
+#
+# 为什么必须这样（形态选型 §2.5）：
+#   - 「用 herdr 工具」≠「有常驻」：herdr server 挂了 / pane 被回收 → 助理就没了；
+#   - 所以：**任何一边的宿主没了，另一边立刻接管**（助理不会随宿主一起消失）；
+#   - 这就是 §2.5 要求的「server 挂 → 助理可判定的降级」——降级目标 = 自带 daemon。
+#
+# 判定（**可判定**，不猜）：
+#   - 心跳新鲜（< STALE_MS）→ 已有实例在值班 → **不重复拉起**（避免双开 → 避免重复打扰）；
+#   - 心跳陈旧/缺失 → 抢 `daemon.lock`（mkdir 原子锁）→ 拿到锁的成为值班进程。
+#
+# 模板文件：双下划线包裹的大写占位符由 `pi-proactive/tools/daemon-install.sh` 渲染。
+set -uo pipefail
+
+NODE_BIN="__NODE__"
+DAEMON_TS="__DAEMON_TS__"
+AGENT_DIR="__AGENT_DIR__"
+AGENT_ID="__AGENT_ID__"
+LOG_DIR="__LOG_DIR__"
+
+export PI_PROACTIVE_AGENT_ID="${AGENT_ID}"
+
+DAEMON_DIR="${AGENT_DIR}/proactive/daemon"
+HEARTBEAT_FILE="${DAEMON_DIR}/heartbeat.json"
+LOCK_DIR="${DAEMON_DIR}/daemon.lock"
+# 心跳周期 5s（src/daemon.ts 的 HEARTBEAT_INTERVAL_MS）→ 20s 还没更新即判定「没在跑」。
+STALE_MS=20000
+
+mkdir -p "${LOG_DIR}" 2>/dev/null || true
+
+# 心跳是否新鲜（= 已经有实例在值班）。
+heartbeat_fresh() {
+	[ -f "${HEARTBEAT_FILE}" ] || return 1
+	local ts now
+	ts="$("${NODE_BIN}" -e '
+const fs=require("fs");
+try{const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));console.log(String(j.ts??""))}catch{console.log("")}' "${HEARTBEAT_FILE}" 2>/dev/null)"
+	[ -n "${ts}" ] || return 1
+	now="$(date +%s000)"
+	[ $(( now - ts )) -lt ${STALE_MS} ]
+}
+
+# 抢值班锁（mkdir 是原子的 → 两个监督器同时启动也只有一个能当值班进程）。
+acquire_lock() {
+	if mkdir "${LOCK_DIR}" 2>/dev/null; then
+		printf '%s' "$$" >"${LOCK_DIR}/pid" 2>/dev/null || true
+		return 0
+	fi
+	# 锁可能是上次崩溃留下的 → 锁里的 pid 不在了就清掉重抢。
+	local owner=""
+	owner="$(cat "${LOCK_DIR}/pid" 2>/dev/null || true)"
+	if [ -n "${owner}" ] && kill -0 "${owner}" 2>/dev/null; then
+		return 1
+	fi
+	rm -rf "${LOCK_DIR}" 2>/dev/null || true
+	if mkdir "${LOCK_DIR}" 2>/dev/null; then
+		printf '%s' "$$" >"${LOCK_DIR}/pid" 2>/dev/null || true
+		return 0
+	fi
+	return 1
+}
+
+while true; do
+	if heartbeat_fresh; then
+		# 已有实例在值班（多半是另一个宿主里的那个）→ 待命，不重复拉起。
+		sleep 3
+		continue
+	fi
+	if acquire_lock; then
+		"${NODE_BIN}" --experimental-strip-types "${DAEMON_TS}" --agent-dir "${AGENT_DIR}" \
+			>>"${LOG_DIR}/daemon.out.log" 2>>"${LOG_DIR}/daemon.err.log"
+		# 值班进程退出 → 释放锁，稍后重试（崩溃自愈）。
+		rm -rf "${LOCK_DIR}" 2>/dev/null || true
+	fi
+	sleep 3
+done

package/package.json

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

package/skills/pi-proactive/SKILL.md

@@ -21,13 +21,15 @@ description: >-
 <!-- BEGIN:GEN tools -->
 | 工具 | 参数 | 作用 | 定义位置 |
 | --- | --- | --- | --- |
-| `schedule_task` | prompt（必填）：任务提示词<br>intent（可选）：投递意图，默认 wake（取值：wake \| interrupt \| queue \| notify）<br>askUser（可选）：触发时是否向用户提问（仅本地）<br>when（可选）：触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601；缺省按 10m 处理 | 预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。when 支持时长（10m）、时刻（18:30）或 ISO 时间；缺省按 10m 处理。 | `pi-proactive/extensions/proactive.ts: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` 从扩展的 `registerTool` 注册项与参数 schema 自动生成，**不要手改**。
@@ -139,25 +141,28 @@ description: >-
 <!-- 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 -->
 
-> 命令面真源 = 实现：上表由 `scripts/gen-doc-tables.sh` 从扩展的 `SUBCOMMANDS` + `switch (sub)` 分派自动生成（**共 16 个命令**），**不要手改**。
+> 命令面真源 = 实现：上表由 `scripts/gen-doc-tables.sh` 从扩展的 `SUBCOMMANDS` + `switch (sub)` 分派自动生成（**共 19 个命令**），**不要手改**。
 
 ## 不要做的事
 

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