pi-proactive

给 Pi 增加「主动」能力：空闲时主动推进或提问、按时间点主动发起任务、多个会话之间对话协作。

本包是 Pi 的一个扩展包（pi-package），加载后提供：

• /proactive 命令面：查看状态、开关主动性、排期任务、取消任务；
• schedule_task / message_agent / list_peers 三个模型工具：模型可以自己排活、给另一个会话发消息、先查清有哪些对端在线/空闲/擅长什么再发（list_peers 只读）；
• 跨进程协作层：同机 Unix socket 实时通道 + 文件邮箱兜底 + 消息去重。

许可与分发（专有）

本软件是专有软件（proprietary），非开源：源码不公开，分发物只含编译后的 JavaScript 产物。

• 许可：package.json 的 license 为 SEE LICENSE IN LICENSE，协议正文 = 本包内的 LICENSE 文件（版权所有 / 仅限内部授权使用 / 禁止再分发 / 禁止反编译与再授权 / 授权期限与联系）。
• 分发物不含任何 .ts 源码：安装包里只有 build/（编译产物）、skills/、README.md、CHANGELOG.md、LICENSE。
• 内部分发走 tarball（tools/release-pack.sh 产出 + sha256）；安装必须先解包再以目录方式装（直装 .tgz 会「显示成功」但宿主加载失败 —— 实测陷阱）。
• 发布前必须跑 bash scripts/ci/publish-preflight.sh --registry <url> --public（检查私有协议 / 零 .ts 源码 / 无内部路径与文档 / 入口在包内）。

安装

方式 A：私有 npm 源（组织 scope，跨机器可用）

pi install npm:pi-proactive

• 当前发布：0.2.0-beta.1（dist-tag beta / latest），integrity sha512-q+fSY0OvPp8BeH1MGWSWqkhoVIjmZbQmd2ry5sPAQsqL8pvAQs0i1VrrAaLvy6Tds1l3fS01yBm/XzTl2bS9mQ==
• 校验下载到的制品是否与发布一致：npm view pi-proactive@0.2.0-beta.1 dist.integrity
• 供应链缺口（如实披露）：本次发布未带 npm provenance（本地发布无法生成；发布工作流模板见 scripts/ci/publish-npm.yml（复制到 .github/workflows/ 后生效，需 GitHub token 的 workflow scope），后续版本将从 CI 发布并自动带 provenance）。

方式 B：本地目录 / tarball（离线或内部试用）

pi install ./pi-proactive          # 本仓库内
bash pi-proactive/tools/release-pack.sh --out ./dist   # 产出**全量交付束**：tarball + sha256 + 交付目录 + zip + manifest，并跑四项自检（新鲜度/内容/校验记录值/zip 一致）
pi install ~/.pi/packages/pi-proactive   # 先解包再按目录装（见下）

宿主会把安装源记成相对路径 → 请把包放在稳定目录里、不要移动它。

# 作为 pi 包安装（写入 ~/.pi/agent/settings.json）
pi install ./pi-proactive

# 本地试用：只加载扩展本体，不写入设置
pi --extension ./pi-proactive/extensions/proactive.ts

宿主自带的包（@earendil-works/pi-coding-agent、@earendil-works/pi-agent-core、typebox）只声明为 peerDependencies（"*"），由宿主提供，不随本包安装（Pi 文档明确：把宿主包放进 dependencies 会产生物理副本、绕过扩展模块映射，导致重复类与重复注册）。

版本约束：本扩展的全部宿主 API 断言只对 @earendil-works/pi-coding-agent 1.3.0 验证过。 package.json 的 engines.pi 写作 >=1.3.0（最低可用版本），但更高版本未验证 —— 升级 pi 后可能出现行为变化，升级后请先重跑 runtime 探针再依赖本插件的自动行为。

5 分钟快速上手（内测版）

24×7 数字员工（常驻形态，默认关闭）

需要一个人不在场也在干活的常驻代理时再开（它会真花你的账号额度）：

# 安装（幂等；macOS 用 launchd，Linux 用 systemd --user）
bash <安装目录>/tools/daemon-install.sh

# 看看它昨晚干了什么 + 有什么等你确认
/proactive doctor

• 默认 enabled=false + 干跑 → 装了不花钱、不投递任何任务；
• 开启后仍受预算硬上限约束（每小时/每日动作数；token 只做估算）→ 超限自动降级为只观察并记账；
• 不可逆动作绝不自动执行 → 进人工确认队列，早间交班时呈现；
• 形态：macOS launchd（KeepAlive）/ Linux systemd --user（Restart=always）；
• 自愈：崩溃自动重启、幂等认领、半成品不重放；卸载用 tools/daemon-uninstall.sh（幂等、无残留）。

面向第一次拿到内测包的同事，按顺序做这 5 步就能看到插件真的主动一次。

步骤 1｜装什么、装在哪

内测分发物是 tarball + sha256 校验文件（不是 git 仓库路径）：

# 拿到 tarball 后先校验
cd <tarball 所在目录>
shasum -a 256 -c pi-proactive-<版本>.tgz.sha256

# 解包到一个**稳定目录**（内测包与仓库无关，但目录本身别乱挪 —— 见下面的说明）
mkdir -p ~/.pi/packages && tar -xzf pi-proactive-<版本>.tgz -C ~/.pi/packages
mv ~/.pi/packages/package ~/.pi/packages/pi-proactive

# 以 pi 包的形式安装（写入 ~/.pi/agent/settings.json）
pi install ~/.pi/packages/pi-proactive

为什么强调「稳定目录」：pi install 会把安装源记进 settings.json 的 packages， 记的形式是相对 settings.json 所在目录的相对路径（宿主行为，见 docs/packages.md）。 所以只要包目录本身不挪动，仓库怎么移动、改名都不影响； 但如果把包解到 /tmp 这类会被系统清理的位置，装完过一阵就会失效。 建议固定用 ~/.pi/packages/pi-proactive。

也可以直接从源码目录装（开发场景，注意源码目录挪动后要重新 pi install）：

pi install ./pi-proactive            # 相对路径：相对 settings.json 所在目录解析
pi install /abs/path/to/pi-proactive  # 绝对路径：宿主会换算成相对 settings.json 的相对路径

自己打内测包：bash pi-proactive/tools/release-pack.sh --out <产物目录> → 产出 tarball + .sha256 + 交付目录（README / SKILL / ops / onboarding / LICENSE / CHANGELOG / DELIVERY / tools / tgz / sha256）+ zip + manifest.json（逐项 sha256 与大小）；幂等：同输入同字节。 脚本自检四项，任一不符即非零退出：① 交付目录内的 tgz 与本次构建同哈希 ② 包内含 src/peer-spawn.ts 等当前能力文件 ③ .sha256 记录值与实算一致 ④ zip 与交付目录逐项一致。 复验既有交付束（不重新打包）：bash pi-proactive/tools/release-pack.sh --check-only --out <产物目录>。

步骤 2｜怎么确认装上了

pi list          # 列表里应出现 pi-proactive

再开一个会话，执行下面这条命令，有回执就算装上了：

/proactive status

步骤 3｜看一次状态（先看懂再动手）

/proactive status

输出是 7 行「人话 + 机器可读字段」，例如：

主动性：已开启 (enabled=true)
空闲触发：关 (idleTriggerEnabled=false)
空闲检测：关闭 (idleDetect=off)
空闲计时：—（未启用） (idleForMs=1823)
提问超时：2m (askTimeoutMs=120000)
限制：最短间隔 5m (minGapMs=300000) · 每小时上限 6 (maxPerHour=6) · 静默时段 未设置 (quietHours=无)
下次空闲触发：—（空闲触发未开启） (nextTriggerInMs=—)

最后一行会说明为什么触发 / 为什么没触发（排障先看这一行）。

步骤 4｜让它第一次真的主动（两处都要改）

装上后插件默认不打扰（idleTrigger.enabled=false）。要看到第一次主动，需要两个开关：

# (a) 打开空闲触发（内存态：只对当次进程有效，重启后回到配置文件里的设置）
/proactive idle on
#    ↳ 这一步同时会把 idleDetect 从 off 切到 input-only，否则开了也不会真的触发

# (b) 把阈值调小（默认 10 分钟太久，等不到）——改配置文件后重启会话
#     <agent-dir> = $PI_CODING_AGENT_DIR，未设置时是 ~/.pi/agent
cat ~/.pi/agent/proactive/config.json

把 config.json 改成（只改这两处，其余字段保留）：

{
  "idleTrigger": { "enabled": true, "afterMs": 30000 },
  "limits": { "minGapMs": 60000 }
}

• afterMs: 30000 = 空闲 30 秒就够触发（默认 600000 = 10 分钟）；
• minGapMs: 60000 = 两次主动之间至少隔 1 分钟（默认 300000 = 5 分钟）—— 不调它，即使阈值到了也会被冷却挡掉（判定说明会显示「冷却中」）。

改完重启会话，再 /proactive status，看 nextTriggerInMs 在往下走 → 到了就会主动推进一次。 想立刻自检链路，可以用 /proactive test（强制投递，绕过冷却与频率上限）。

步骤 5｜怎么关掉

/proactive off        # 关闭主动性总开关（已落盘，重启后仍生效；已排期任务保留）
/proactive idle off   # 只关空闲触发（内存态）

/proactive on 可以再打开。彻底卸载见下面「卸载与回滚」。

典型场景脚本（可直接复制）

在 Pi 会话里直接粘贴命令；# 开头是注释，可以一起粘。

场景 1｜空闲时主动汇报进度（最常用）

# 打开空闲触发并把阈值压到 30 秒（内存态部分 + 配置文件部分见「步骤 4」）
/proactive idle on

配置里设：

{
  "idleTrigger": {
    "enabled": true,
    "afterMs": 30000,
    "intent": "wake",
    "prompt": "用户已空闲，请用一句话汇报当前进度，并给出下一步建议。"
  },
  "limits": { "minGapMs": 60000, "maxPerHour": 6 }
}

效果：用户停手 30 秒后，插件自己起一轮，把这段提示词投给模型，模型回一句话。 恢复安静：/proactive idle off。

场景 2｜定时提醒（喝水 / 站起来 / 收工）

/proactive in 30m 起来活动一下，喝口水
/proactive at 18:30 该收工了，保存一下今天的进度
/proactive every 2h 看一下构建有没有挂

• in <时长> <内容>：时长后触发一次（30s / 10m / 2h / 1d / 纯数字按秒）；
• at <HH:MM> <内容>：到当天该时刻触发（已过则顺延到明天）；
• every <时长> <内容>：按间隔重复。

查任务 / 取消：

/proactive tasks              # 看 id、排期类型、相对到期、intent、归属、开关
/proactive cancel <id>        # 取消（id 从上一条里抄）

⚠️ 定时任务与主动触发共用同一个冷却闸门：默认 minGapMs=300000（5 分钟）， 到点投递可能顺延最多约 5 分钟。要准点，把 limits.minGapMs 调小。

场景 3｜跨会话提问与回复（两个会话之间）

会话 A（发起方）直接跟模型说：

用 message_agent 工具给会话 "builder" 发一条 kind="ask" 的消息：
标题「进度同步」，正文「你那边跑到哪一步了？还剩什么没做完？」。

会话 B（对端）会收到提问，模型回答后自动回送一条 reply（携带原 correlationId）。

• 手工点名也可以：在会话 A 里执行 /proactive peers 看在线 peer 的名字与 agentId；
• 对端必须也装了本插件，否则消息不会被消费；
• 对端离线也能发：消息落盘到对端邮箱，等对方以同一 sessionId 重启后取回 —— 这种情况下回执是 queued（已落盘、尚未送达，不是「已送达」）。

场景 4｜让模型自己排活（schedule_task 工具）

跟模型说：

帮我把「每 30 分钟检查一次 CI」排成一个重复任务，用 schedule_task 工具，when 传 30m。

模型会调用 schedule_task 真正落库（进任务表、进程退出后仍在），到期由调度器投递。

场景 5｜只看不改（值班/观察模式）

/proactive status             # 总览 + 为什么触发/为什么没触发
/proactive tasks              # 待触发任务
/proactive peers              # 在线 peer、心跳、当前任务

只读这三条不会产生任何投递动作。

卸载与回滚

停用（推荐先做这步）

/proactive off        # 主动性总开关关闭（已落盘）；已排期任务保留在任务表里

彻底卸载（三步）

# 1) 卸包
pi remove <安装时用的包路径或包名>
#    或直接编辑 ~/.pi/agent/settings.json 的 "packages" 数组，删掉 pi-proactive 那一项

# 2) 删运行期数据目录（可选，但这是「彻底」）
#    数据目录 = <agent-dir>/proactive/
#    <agent-dir> = $PI_CODING_AGENT_DIR，未设置时是 ~/.pi/agent
rm -rf ~/.pi/agent/proactive          # 先确认路径！别手抖删错目录

# 3) 确认
pi list                                # 列表里不应再有 pi-proactive

数据目录在哪、删了会丢什么

数据目录：<agent-dir>/proactive/（默认 ~/.pi/agent/proactive/），目录权限 0700、文件 0600。 删掉它 = 删掉本机全部运行期数据：

只想静音、不想丢数据：只做 /proactive off，不要删数据目录。

回滚到旧版本

# 1) 备份当前数据（回滚前必做）
cp -a ~/.pi/agent/proactive ~/.pi/agent/proactive.bak.$(date +%s)

# 2) 装回旧版
pi install <旧版本包目录>

# 3) 重启会话，用 /proactive status 确认读到的是旧版配置

# 4) 若旧版读不懂新版数据（新版写了旧版不认识的落盘版本号）→ 恢复备份
#    rm -rf ~/.pi/agent/proactive
#    cp -a ~/.pi/agent/proactive.bak.<时间戳> ~/.pi/agent/proactive

当前落盘格式版本是 v1，没有 version 字段的文件按 v1 读（升级不丢数据）， 所以在版本号不变的前提下，回滚不需要动数据。

反馈渠道（内测）

报给谁：直接报给发给你这个 tarball 的同学（内测发包人）；也可以在本仓库开 issue 记录。

请一并带上这三样（缺一样都很难复现）：

1. 版本：pi-proactive 的版本号（tarball 文件名里就有，如 0.2.0-beta.1）；
2. /proactive status 的完整输出（它含 enabled / idleDetect / minGapMs / maxPerHour / quietHours / nextTriggerInMs 与「为什么触发/为什么没触发」的判定说明）；
3. 宿主版本：pi --version（本扩展的宿主 API 断言只对 pi 1.3.0 做过验证）。

再附上（有则更好）：复现步骤、期望 vs 实际、插件 stderr 里带 [proactive] 前缀的日志片段、 <agent-dir>/proactive/ 下相关文件（如 tasks.json、某个信封）。

内测边界（先知道这些，免得误判）

这是内测版，以下四条是当前已知边界，不是待修的 bug 清单：

1. 跨机行为未验证 —— 跨主机（共享目录 / NFS）只有落盘排队（约一个轮询周期，秒级）， 掉线或过期都可能导致消息不被处理。内测期请限定同机使用。
2. 无鉴权 —— 威胁模型是「同 UID 可信」：同 UID 的任意进程可以往邮箱写文件并冒用 from。 本插件不是安全边界，不要用它防御同机其它进程。
3. TUI 完整链路未验证 —— 真人按键下的「提问 → 回答 → 回填」完整闭环只做了部分场景抽验 （见 docs/review/tui-smoke.md 自述的 7 项未验证项）；rpc / json / print 等非交互模式的降级行为有实测。
4. 定时投递可能被 5 分钟冷却顺延 —— 排期任务与主动触发共用同一个冷却闸门 （默认 limits.minGapMs=300000），到点投递可能晚约 5 分钟。要准点就调小 minGapMs。

其它未验证项（长时驻留 > 10 分钟、every 的小时级节拍、跨模型家族独立复验等） 见下方「能力边界与限制」一节，那里是逐条如实列出的完整清单。

命令（Usage）

Usage: /proactive <子命令>。下表逐条对应实现里实际注册的分支（src/commands.ts 的命令处理 switch），未列出的子命令会被拒绝并提示可用清单。

命令面真源 = 实现：下表由 scripts/gen-doc-tables.sh 从 pi-proactive/src/commands.ts 的 SUBCOMMANDS ＋ switch (sub) 的 case 分派自动生成（共 16 个命令），不要手改； 要改命令面请改实现，然后跑 bash scripts/gen-doc-tables.sh --apply（门禁 scripts/check-doc-tables.sh 校验）。

排期命令的排期结果会当场回执（任务 id、相对到期、绝对到期），任务落盘在任务表里，进程退出后仍在， 下次启动继续按表调度。

注：/proactive quiet 不是命令（输入会被拒绝；静默时段是配置项 limits.quietHours）； /proactive notify 不是命令（notify 是消息语义 kind:"notify"，由模型工具 message_agent 承载， 人侧给对端下指令用 /proactive tell）；/proactive history [peer|me] [条数] 已实现。 各命令的行为细节（落盘 / 内存态、参数怎么写、失败怎么提示）见下方「典型场景脚本」「配置」「排障」三节。

模型工具

模型工具面真源 = 实现：上表由 scripts/gen-doc-tables.sh 从 pi-proactive/extensions/proactive.ts 的 pi.registerTool({ name: … }) 注册项与参数 schema 自动生成（共 7 个模型工具），不要手改； 表中参数即真实 schema。下面三个小节是逐个工具的展开说明。

schedule_task

预约一个稍后触发的任务（真正落库到任务表，到点由调度器投递）。

返回：details.created === true 时带 taskId / dueAt / schedule；参数非法或任务表未初始化时 details.created === false 并带 error 文案。

list_peers

只读查询对端目录：谁在线、谁空闲、谁擅长什么、有多少在途请求。

• 参数：name（名字子串）｜status（online/idle/busy/offline）｜capability（能力标签）｜includeOffline（默认只给在线）
• 返回：名字 / agentId / 在场状态 / 心跳多久前 / 能力标签 / 在途任务数 / 传输方式
• 为什么要先查：对端离线时打扰它不合适；多个对端同名时 message_agent 会因歧义直接报错 → list_peers 会把候选列给你

message_agent

给另一个正在运行的 agent 会话发消息（跨进程协作）。

返回 details.status，共 8 种，语义严格区分：

queued 不是「已送达」。 它有两种语义：对端离线待上线（消息落在对端邮箱，对方以同一 sessionId 重启后取回）与对端在线但本轮未投递（原因随附）。两种情况下对端都尚未收到。

kind:"ask" 时，对端模型回答后会自动回送一条 kind:"reply"（携带原 correlationId、继承 threadId）。

同一线程的往返上限 = 4 轮（只计已完成的 reply；未获回答的提问不占额度；投递失败的回信不虚增计数）—— 达到上限后不再回信，并必须通知请求方（该通知走 socket 优先 + 邮箱兜底：离线请求方也能收到——落盘到其邮箱、待其上线后取回；去重粒度＝(线程, 请求方)，同一线程同一请求方只通知一次；见下方残余限制①）。

配置

配置文件：<agent-dir>/proactive/config.json （<agent-dir> = $PI_CODING_AGENT_DIR，未设置时为 ~/.pi/agent）

{
  "enabled": true,
  "idleDetect": "off",
  "askTimeoutMs": 120000,
  "idleTrigger": {
    "enabled": false,
    "afterMs": 600000,
    "intent": "wake",
    "askUser": false,
    "prompt": ""
  },
  "limits": {
    "minGapMs": 300000,
    "maxPerHour": 6,
    "quietHours": { "from": "22:00", "to": "08:00" }
  },
  "peerWatch": {
    "enabled": false,
    "afterIdleMs": 600000
  }
}

配置面真源 = 实现：上表由 scripts/gen-doc-tables.sh 从 pi-proactive/src/config.ts 的 defaultConfig() / mergeConfig() / loadConfig() 自动生成，不要手改； 键集合、默认值与定义位置都以生成表为准。

配置文件缺失或损坏时回退到默认值，不会抛错。

运行时产生的状态目录（都在 <agent-dir>/proactive/ 下）：

配置外置（提示词 / agent 定义）

配置里篇幅会长、要人工编辑的内容（提示词、agent 角色说明、rubric、模板）改用独立文件维护， 配置文件只留标量与引用。布尔开关 / 数字阈值 / 短枚举不要外置——那只会把「看一眼配置」变成「跳目录猜」。

目录约定（相对 config.json 所在目录，即 <agent-dir>/proactive/）：

prompts/<ref>.md    # 提示词
agents/<ref>.md     # agent 定义

引用写法：

{
  "idleTrigger": { "promptRef": "idle-probe" },
  "contentRefs": { "reviewer": { "agentRef": "example-reviewer" } }
}

• promptRef → prompts/<ref>.md；agentRef → agents/<ref>.md；
• 文件可选带 front-matter（--- 包裹的 key: value 块），其余部分是正文；
• 优先级：同层仍有内联 prompt（旧配置）时内联优先，并给一次性提示（ref 不生效）；
• 失败即报错：文件不存在 / 空文件 / 格式错 / 路径越界（../）→ 加载失败并指名 ref 与路径， 不会静默回退默认值；
• 解析后的路径必须留在配置根目录内（越界路径与指向外部的符号链接都拒绝）；
• 内容单次读入快照（外部程序同时改文件也不会读到半截内容）。

示例：pi-proactive/agents/example-reviewer.md —— 复制到 <agent-dir>/proactive/agents/ 后 即可被上面的 agentRef 引用。

<agent-dir>/proactive/agents/ 下同时存在两种东西：对端注册表 agents/<agentId>.json 与外置 agent 定义 agents/<ref>.md —— 按扩展名区分，互不覆盖。

空闲判定基线（按实测修订）

空闲判定现在用**「最近任何活动」**做基线：用户输入 + 代理活动（模型回合起止 / 工具调用 / 助手消息落定）都会把计时归零。 代理在干活时不再被当成「用户离开了」。

• 两条基线：lastUserActivityAt（只有用户输入刷新；idleDetect 三档的差异只决定用户输入是否计入）+ 「最近任何活动」（判定用）。
• 触发前必须确认代理已交回控制权：回合进行中 / 工具链未结束时判定原因为「代理正在忙」，不触发。
• 插件自己投递的主动消息不刷新任何基线 —— 否则插件会被自己的动作无限推迟下一次触发（自锁）。
• 阈值维持 10 分钟（afterMs=600000）+ 5 分钟冷却（minGapMs=300000）。

实测数字（日志级测量；同一份会话日志数据集、同一 10 分钟阈值；来源：pi-proactive/docs/idle-ground-truth.md）：

表述纪律：在日志级测量下，工作期误触发率由 20.07% 降到 3.01%；这不等于「误触发率已消除」。

这份测量不能证明什么（如实披露）：

1. 不能证明「用户离开了」—— 只能证明「用户没有交互」；用户可能在读屏幕（与离开在日志里同形）。
2. 不能证明某个阈值对某个用户 / 场景最优 —— 结论只在「单用户 · 重度 agentic 编码」场景内成立。
3. 不能证明「打扰率 = 20.07%」等于用户被打扰的真实概率 —— 护栏、频率上限与投递成功率未建模。
4. 不能证明新基线「一定更好」—— 漏报率从 55.07% 升到 68.77%（更少被叫醒，换更少打错时机）。
5. 不能评估 terminal 档 —— 终端按键在会话日志里不可见。
6. 不能替代真人实验 —— 这是日志级（实现级 / 测试级）证据，不是现场级证据。

能力边界与限制（如实披露）

• 对端必须加载本插件，跨会话 / 跨进程协作才成立。对方没装插件 → 消息永远不会被消费。
• 跨机器只有落盘排队（~1s），没有实时通道。 同机走 Unix socket 直连；跨机（共享目录 / NFS） 只能靠文件邮箱轮询，延迟约一个轮询周期（秒级），且不可靠（掉线、过期都可能导致消息不被处理）。
• 对端正在流式输出时收到 reply，只会多出一个 turn（turn_start），不会多出一个新的 agent_start。 reply 以 deliverAs:"followUp" 注入同一个 agent run；对端空闲时收到 reply 才走 triggerTurn:true 起新 run， 那时才出现新的 agent_start。按「agent_start 计数」判定「被唤起了几轮」的监控 / 验收脚本会因此误判。
• 跨会话 / 跨进程协作要求双方都加载本插件。
• agentId = <name>#<host>#<sessionId>（name = 工作目录 basename，host = 主机名， sessionId = 宿主会话 id）：会话稳定（同一会话跨进程重启地址不变）、会话间唯一 （不同会话不会互相投递）。宿主未提供会话 id 时退回 <name>#<host>#<pid>（进程级唯一， 能力退化但不报错）；PI_PROACTIVE_AGENT_ID 可显式覆盖。
• 离线投递：对端优雅退出 → 注册表保留条目并标 offline → 发送方仍可解析 → 消息落盘到对方邮箱 → 对方以同一 sessionId 重启后取回。只有从未注册过的纯名字 才返回 error（无法确定邮箱目录，不得谎称已排队）。
• 空闲触发默认关闭（idleTrigger.enabled=false），不显式打开前不会打扰用户。
• 残余限制（如实列出，不掩盖）： ① 达线程轮次上限的通知走 socket 优先 + 邮箱兜底 —— 离线请求方也能收到（落盘到其邮箱、待其上线后取回），但不是实时；去重粒度＝(线程, 请求方)（同一线程同一请求方只通知一次，不同请求方各自都被交代）； ② 注入标记串会出现在模型可见正文与转录里（用于精确识别「本插件自己注入的消息」，代价是正文多一串标记）； ③ 旧的 scope:"session" 任务（无 ownerSessionId）在进程重启后不再匹配 —— 归属退回按 ownerAgentId 判定，而旧任务里的 ownerAgentId 是旧的 pid 形态、与当前的会话形态 agentId 不一致 → 这些旧任务不再被投递； ④ socket 路径过长会退化（macOS 上限约 104 字符）→ 退化为文件邮箱落盘排队（延迟变大，功能不中断）； ⑤ 注册表条目永不删除 —— 优雅退出只标 offline 不删文件 → agents/ 目录会缓慢积压； ⑥ TUI 完整链路（提问 → 回答 → 回填）未验证 —— pty 档只做了部分场景抽验，完整链路未跑通（见 docs/review/tui-smoke.md 的 7 项未验证）； ⑦ 跨家族独立复验未做（本机只有 minimax 一个模型家族）； ⑧ 跨机行为未验证（仅落盘排队 ~1s）； ⑨ >10 分钟长时驻留未验证 —— 实测中每个宿主生命周期 ≤ 4 分钟，长驻下的资源 / 孤儿进程 / 内存行为未观测； ⑩ every 的小时级节拍未验证 —— 短时实测节拍正常，小时级是否漂移未观测； ⑪ 默认 /proactive idle on 只切到 input-only 档 —— TUI 下不订阅终端输入（attachTerminalInput 只在 terminal 档调用）→ 敲键本身不刷新空闲基线（基线只在宿主发出 input 事件时刷新）；需要按终端输入判定空闲，请把配置 idleDetect 设为 terminal； ⑫ 定时投递可能因与主动触发共享冷却而被顺延（最多约 5 分钟） —— 默认 minGapMs=300000（5 分钟），排期任务与主动触发共用同一个冷却闸门（Guard.check() 返回 defer → 任务的 dueAt 顺延）；需要准点投递请调小 minGapMs。
• 威胁模型 = 同 UID 可信。 同 UID 进程之间没有认证，信封里的 from 是自声明字段 —— 本插件不是安全边界，不要用它防御同机其它进程。
• 护栏按 agent 作用域计数。 每个 agent 进程各有一份护栏状态 ⇒ N 个 agent ⇒ N × 单 agent 上限， 不是全局上界。
• 适用版本 pi 1.3.0。 全部宿主 API 断言只对 @earendil-works/pi-coding-agent 1.3.0 验证过； 更高版本未验证。
• TUI 档 pty 仅抽验部分场景（docs/review/tui-smoke.md：该报告自述不构成验收结论、并列 7 项未验证，其基线早于提问路径重写 → 需重跑才算数）；rpc / json / print 等非交互模式的降级行为已实测。
• 跨进程端到端实测（V-03）已完成（docs/review/cross-process-e2e.md：两个真实 Pi 宿主 + 真实模型回合）。 ⚠️ 该基线早于「agentId 会话稳定化」与 M5c 修复轮 → 合并态已复测部分场景（核心闭环与达上限通知，见 docs/review/final-acceptance.md §7.5/§8），原 11 场景在合并态的逐条复测未做。
• 协作接线层（M5c）独立验收首轮判「不通过」，修复轮已合入，第三轮独立复验已出结论：有条件通过（S-1S-8 全关、P-1P-7 全关；仍有 3 项 Minor 残余与若干未验证项，见 docs/review/m5c-reverify-3.md） → 该层不得称已验收通过。
• /proactive on|off 已落盘（原子写 <agent-dir>/proactive/config.json 的 enabled 字段），重启后仍生效；/proactive idle on|off 不落盘，仅当次进程内有效（重启后回到配置文件里的设置）。

排障

先看插件日志（stderr，日志前缀 [proactive]），再看状态：/proactive status 会直接给出 「为什么触发 / 为什么没触发」的判定说明。

团队级排障与看门狗告警语义见 docs/team/WATCHDOG-RUNBOOK.md（告警类别与处置责任人）、 未验证项台账见 docs/team/iteration-backlog.md。

里程碑边界