pi-proactive 0.2.0-beta.6 → 0.2.0-beta.7

package/manual/USAGE.html

@@ -0,0 +1,76 @@
+<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>pi-proactive 使用手册</title>
+<style>
+:root{--fg:#1a1a1a;--mut:#666;--bg:#fff;--ac:#2b6cb0;--warn:#b45309;--code:#f6f8fa;--bd:#e5e7eb}
+@media(prefers-color-scheme:dark){:root{--fg:#e6e6e6;--mut:#9aa0a6;--bg:#16181c;--ac:#7fb3e8;--warn:#e0a458;--code:#1f2329;--bd:#2b2f36}}
+body{max-width:860px;margin:0 auto;padding:32px 20px 80px;background:var(--bg);color:var(--fg);
+font:15px/1.75 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}
+h1{font-size:26px;margin:0 0 4px}h2{font-size:19px;margin:34px 0 10px;padding-top:10px;border-top:1px solid var(--bd)}
+h3{font-size:16px;margin:20px 0 6px}.v{color:var(--mut);font-size:13px;margin:0 0 8px}
+code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px}
+code{background:var(--code);padding:1px 5px;border-radius:4px}pre{background:var(--code);padding:12px 14px;border-radius:8px;overflow:auto}
+table{border-collapse:collapse;width:100%;margin:10px 0;font-size:14px}th,td{border:1px solid var(--bd);padding:7px 9px;text-align:left;vertical-align:top}
+th{background:var(--code)}.warn{border-left:3px solid var(--warn);padding-left:12px;margin:12px 0}
+.ok{border-left:3px solid var(--ac);padding-left:12px;margin:12px 0}a{color:var(--ac)}
+</style></head><body>
+<h1>pi-proactive 使用手册</h1>
+<p class="v">版本 0.2.0-beta.7 ｜ 跨项目协作 · 主动触发 · 常驻助理 ｜ 本手册随 npm 包发布</p>
+
+<h2>1. 这是什么</h2>
+<p>pi-proactive 是 Pi Coding Agent 的扩展插件，给它加上四件事：<b>跨进程/跨项目消息协作</b>、<b>空闲主动触发</b>、<b>常驻值班助理</b>、<b>可观测的协作状态</b>。</p>
+<div class="ok"><b>它不做什么：</b>不替你做决策；不自动改你的项目文件；不管理模型额度（那是 provider 侧的事）。</div>
+
+<h2>2. 安装</h2>
+<h3>2.1 宿主实际加载的那一份（推荐）</h3>
+<pre><code>cd ~/.pi/agent/npm &amp;&amp; npm install pi-proactive@latest</code></pre>
+<p class="v">宿主的扩展来自 pi 的<b>包目录</b>，不是全局 npm 目录；用 <code>npm i -g</code> 装到别处不会影响宿主，反而多出第二份副本（宿主会报 duplicate runtime modules）。</p>
+<h3>2.2 全局安装（CLI 用）</h3>
+<pre><code>npm i -g --prefix ~/.npm-global pi-proactive@latest</code></pre>
+<div class="warn"><b>关于 <code>--legacy-peer-deps</code>：</b>只在<b>混合安装目录</b>（该目录里有与本包无关的 peer 冲突）才需要；<b>干净空目录不需要</b>（typebox 已随包 bundled）。</div>
+
+<h2>3. 三条使用入口</h2>
+<table><tr><th>入口</th><th>适合</th><th>怎么用</th></tr>
+<tr><td><b>命令面</b></td><td>你在 pi 会话里手动问</td><td><code>/proactive status</code> · <code>/proactive peers</code> · <code>/proactive doctor</code> · <code>/proactive history</code> · <code>/proactive assistant on|off|status</code></td></tr>
+<tr><td><b>模型工具面</b></td><td>让 agent 自己查、自己协作</td><td><code>list_peers</code> · <code>message_agent</code> · <code>schedule_task</code> · <code>proactive_query</code> · <code>proactive_schedule</code> · <code>proactive_peer</code> · <code>proactive_manage</code></td></tr>
+<tr><td><b>CLI</b></td><td>脚本化 / 监督</td><td><code>pi-proactive --help</code></td></tr></table>
+
+<h2>4. 常驻助理（7×24）</h2>
+<pre><code># 安装常驻（跨平台：macOS launchd · Linux systemd --user · Windows 计划任务）
+node ~/.pi/agent/npm/node_modules/pi-proactive/tools/daemon-install.mjs
+# 卸载（三处零残留：进程 / socket / 任务与目录）
+node ~/.pi/agent/npm/node_modules/pi-proactive/tools/daemon-uninstall.mjs</code></pre>
+<table><tr><th>平台</th><th>机制</th><th>验证</th></tr>
+<tr><td>macOS</td><td>launchd 单元</td><td><code>launchctl print gui/$(id -u)/&lt;label&gt;</code></td></tr>
+<tr><td>Linux</td><td>systemd --user</td><td><code>systemctl --user is-active &lt;label&gt;</code></td></tr>
+<tr><td>Windows</td><td>计划任务（schtasks）</td><td><code>schtasks /Query /TN &lt;name&gt;</code></td></tr></table>
+<div class="warn"><b>注意 agent 根路径：</b>unix socket 路径上限约 100 字节，安装器会自动选一个短路径；<b>手工指定长路径会导致端点建不出来</b>（表现为"看起来没残留"其实是观测失败）。</div>
+
+<h2>5. 怎么读状态（一屏三块）</h2>
+<table><tr><th>块</th><th>回答什么</th><th>在哪看</th></tr>
+<tr><td>在不在</td><td>助理在跑吗（心跳 + 进程存活 + 当前模式：干跑/真跑/被阻塞/预算耗尽）</td><td><code>/proactive status</code> · <code>assistant status</code></td></tr>
+<tr><td>有多少</td><td>对端 peers 的在线/忙碌/离线分布</td><td><code>/proactive peers</code> · <code>list_peers</code></td></tr>
+<tr><td>有没有发生</td><td>主动联系流水（时刻/来源/对象/结果）</td><td><code>/proactive history</code></td></tr></table>
+<div class="ok"><b>干跑（dry-run）必须显式显示</b>：界面显示"在跑"却零动作，等于没干活 —— 判定依据是心跳<b>且</b>模式。</div>
+
+<h2>6. 故障排查（按成因分性）</h2>
+<table><tr><th>现象</th><th>成因</th><th>处置</th></tr>
+<tr><td>429 用量上限</td><td>订阅窗口耗尽（周期性）</td><td><b>排队到窗口重置</b>；不要反复重试</td></tr>
+<tr><td>402 Insufficient Balance</td><td>按量通道余额不足</td><td>需人工处理（花钱决策）</td></tr>
+<tr><td>403 quota</td><td>配额/权限/区域</td><td>人工调整；不要当抖动重试</td></tr>
+<tr><td>连接超时</td><td>位置/网络不可达（本地端点只在局域网内）</td><td>降级到全局可达通道</td></tr>
+<tr><td>配置改了没生效</td><td>未知配置项 → 整份回落默认</td><td>报错会指名键名（CONFIG_UNKNOWN_KEY）；注意拼错会连带关掉空闲触发</td></tr></table>
+
+<h2>7. 开发者向：残留枚举与对拍</h2>
+<pre><code>node tools/enumerate-residue.mjs --agent-dir ~/.pi/agent --scope run,mailbox,agents --json --no-record
+python3 scripts/残留对拍.py A.json B.json --normalize   # 0=一致 4=空对空不给结论 5=有差异</code></pre>
+<p>字段口径与三态定义见仓库 <code>docs/project/cp010-enumeration-contract.md</code>。</p>
+
+<h2>8. 版本与变更</h2>
+<ul>
+<li><b>CHANGELOG</b>：<code>CHANGELOG.md</code>（随包发布）</li>
+<li><b>破坏性变更</b>：<code>BREAKING-CHANGES.md</code>（随包发布；含迁移说明）</li>
+<li><b>使用手册</b>：本文件 <code>manual/USAGE.html</code>（随包发布）</li>
+</ul>
+</body></html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-proactive",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.7",
   "description": "给 Pi 增加主动性：空闲时主动推进或提问、按时间点主动发起任务、多个会话之间对话协作。（专有软件：分发物不含源码，使用条款见包内 LICENSE）",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -33,7 +33,10 @@
     "daemon/",
     "build/cli.mjs",
     "tools/cli.mjs",
-    "daemon/run-daemon.mjs"
+    "daemon/run-daemon.mjs",
+    "app/",
+    "BREAKING-CHANGES.md",
+    "manual/USAGE.html"
   ],
   "pi": {
     "extensions": [