pi-ptc-subagents 7.1.0 → 7.3.0

package/docs/routes/create-a-task.md

@@ -5,17 +5,32 @@
 - `pi_task_ptc`：PTC 程序内的 binding，程序里 `tools.pi_task_ptc({...})`
 - `pi_task_codemode`：注册的工具（exposure: codemode，模型不可见），codemode 脚本里 `tools.pi_task_codemode({...})`
 
-参数：`task`（必填，孩子要干的活）、`label`、`wait`、`why`、`agent`、`agentScope`、`model`、`thinkingLevel`、`readOnly`；
+参数：`task`（必填，孩子要干的活）、`label`、`wait`、`why`、`agent`、`agentScope`、`model`、`thinkingLevel`、`readOnly`、`timeoutMs`；
 agent 定义里的 `tools / model / thinkingLevel / childReport` 由 frontmatter 钉住。
 
-返回 handle：`{ taskId, label?, status: "queued" }`。默认不等；撞闸（随闸门落地）返回
-`{ status: "rejected", errorMessage }`，不抛异常。
+返回 handle：`{ taskId, label?, status: "queued" }`。默认不等；撞闸排队等（ADR-0010），
+不抛异常。唯一的拒绝是派发被关（`/ptc off`，ADR-0004）：此时返回
+`{ status: "rejected", errorMessage }`。
 
 任务建成后在任务记录里排队（满员排队不拒绝，ADR-0010），经
 `ptc_task_list / ptc_task_output / ptc_task_stop` 查/停。
 
+任务记录带宿主会话 id（`sessionId`）——按会话筛任务用 `ptc_task_list({ session: "current" })`，
+跨会话的旧记录用 `scope=all` 找。压缩归档（`scope=all`）里的条目也带 `archived: true`。
+
+## 什么时候值得派（判据）
+
+- **值得**：主题多、彼此独立、每个都要读一堆材料——父一个人扛会算错，一份材料一个孩子最划算。
+- **不值得**：材料少、一口气能算完——派发只换 0~8% 准确率，代价是 10 倍上下成本。
+- 实测（facts 题：4 份互不相干的档案各交给一个孩子，n=3）：派发档准确率 100%，不派发 92%。
+  ⚠️ **这 8 个点当方向别当效应量**：不派发档自身在两批之间就晃（bare 89%→97%，而那次代码改动对它零影响），
+  差值与波动同量级。稳的是**机制**：父同时扛 4 个主题的多步计算会算错（实测有一轮一个主题 3 条全错），
+  派发后每个孩子只对一份档案就全对。
+
 ## Briefing 纪律（省 token，派发前自查）
 
+- **task 是孩子的唯一规格**：孩子看不到父会话，也看不到别的孩子。父写错，孩子照办，全链一致地错
+  （实测：有一轮父的任务书写了「用文件里给的值」，孩子交回档案里的原始参数，9 条事实全错）。
 - **给确切路径、命令、决策**：孩子看不到父会话。task 里写死一个路径，省孩子一轮探索
   （每轮探索 = 一次工具调用结果 + 推理 token）。
 - **写明最终消息要带回什么**：孩子只回一次。要什么格式、哪些字段，task 里说清。
@@ -24,3 +39,35 @@ agent 定义里的 `tools / model / thinkingLevel / childReport` 由 frontmatter
 - **同域的活合并给一个串行孩子**：每个孩子都付一份固定 harness 税（系统提示词 +
   项目上下文）。多个重叠的小活拆并行 = 同一份探索被付费多次。
 - **孩子不写报告文件**：交付物就是最终消息（含报告 JSON 块），落盘 .md 是浪费。
+- **写清两件事：交付物格式 + 报告块**：孩子要同时交「交付物」和「报告」（末尾 JSON 块，或调
+  `ptc_child_report` 工具）。只写交付物格式时，孩子多半不交报告——父就只剩原始产出可读，只能重算。
+  更别写「恰好 N 行」这类排他措辞：孩子会照排他措辞办，把报告丢掉（实测 3/12 孩子中招，
+  父重算被记成幻觉）。
+  **要报告就点名形状**：「最后附上 child report 的 JSON 块（summary / findings / files_touched /
+  usage）」——实测点名形状 4/4 孩子照交；只说「附上报告块」1/4 交；**自己发明一套报告格式更糟**
+  （实测 4/4 不交契约块：孩子照父的格式办，把契约块顶掉了）。
+- **汇总前核对孩子产出**：任务结果里的 `delivery` 是引擎实测的轨迹（它读了哪些文件、有没有报错），
+  不是孩子的自述。孩子零产出（没读材料、无报告、正文空）就**重派它，或明说缺口——别替它补数**：
+  父补的数没有孩子背书，保真度上等于「父说有、孩子没说」。
+
+## 旋钮（用不用你自己判断）
+
+参数都在参数表里。下面是它们的代价——什么时候值得付，由你判断：
+
+- **`why`**（调用方自己的话）：它进孩子的提示词 = 花孩子的 token。孩子从 task 里已经能读懂为什么要干，就别传。
+- **`readOnly: "strict"`**：孩子的工具表压到 read/grep/find/ls（搜索开启时含 web_ds_search）。
+  只需要读的活别给写权限——省 token，也省掉它改坏东西的可能。
+- **`thinkingLevel` / `model`**：孩子的成本项。活简单就给孩子低档位或更便宜的模型。
+- **`wait: false`**（默认）：立刻返回 handle，结果经任务面/通知回来。多个孩子并行时别在第一个上阻塞。
+- **`timeoutMs`**：孩子的运行时长上限（毫秒）。**不传 = 不限**（默认行为）；传了超时就收尸——
+  慢孩子不再一直烧 token，但它的活可能没干完。给了就别再无脑等它。
+- **`projectContext`**：孩子的项目上下文（AGENTS.md/CLAUDE.md）。`auto`（默认）= 照常加载；
+  `none` = 不加载。**none 只关「注入」，不关「知识」**：文件还在工作目录里，孩子需要时会自己去翻
+  （实测 none 臂的孩子照样读到了项目口径）——所以 none 省的是注入那几百字符，
+  **实测输入只差约 15%，不是省一半**。这活只需要孩子读材料/算数、不需要项目约定时传 `none`；
+  要孩子遵守项目规矩就照常传。**另一头也要知道**：auto 注入的是整个项目文件，孩子可能把里面的
+  写码规矩套到答案上（实测 3 轮 4 条错全是「元 → 分」×100 改写）。
+
+台架口径（2026-10-30，pi 1.4.0，facts 题 n=3）：每个孩子付一份固定 harness 税 ≈ 1800 input token；
+端到端比不派发贵 9~12 倍（官方编排 + 本仓派发 8.7×、本仓编排 + 本仓派发 11.6×；env 修复前是 15~22 倍）。
+**派发值得的是准确性，不是省钱**：同样的题，派发档准确率 100%，不派发 92%（差值见上，与波动同量级）。

package/docs/routes/manage-a-task.md

@@ -2,8 +2,80 @@
 
 三个工具，有任务记录才出现在模型面前（ADR-0007：可见性 = 有无记录，不是独立开关）：
 
-- `ptc_task_list()`：在飞的全部 + 最近完成的（默认 10 条）
-- `ptc_task_output({ task_id })`：读一条记录（状态/产出/报告）
+- `ptc_task_list()`：在飞的全部 + 最近完成的任务。响应是对象。
+- `ptc_task_output({ task_id })`：读一条记录。响应是对象。
 - `ptc_task_stop({ task_id, reason? })`：排队中的抽掉（canceled）；在跑的转 stopping
 
-任务记录是派发的唯一痕迹：每次建任务都建记录，前台任务也一样。
+任务记录是派发的唯一痕迹：每次建任务都建记录，等不等也一样建。
+
+终态记录热存留最近 500 条（决策 29），被挤出的进压缩存档（默认留 30 天，
+`archiveEnabled: false` 则直接删），凭精确 task id 经 `ptc_task_output` 仍读得到。
+
+## ptc_task_list
+
+参数：
+
+- `scope`：`recent`（默认，只热存）/ `all`（连压缩归档一起列，更全也更慢）
+- `limit`：取多少条（默认 50，上限 200）
+- `status`：只看某个状态（七个状态之一）
+- `session`：`current` = 本会话，或给一个会话 id
+
+响应：
+
+```json
+{
+  "scope": "recent",
+  "total": 520,
+  "tasks": [
+    {
+      "id": "5d90e136…",
+      "status": "succeeded",
+      "label": "口径汇总",
+      "finishedAt": 1758000123456,
+      "task": "读 AGENTS.md 并汇总六个包的对外口径",
+      "summary": "六个包口径一致"
+    }
+  ]
+}
+```
+
+- `total` = 候选总数。它比 `tasks.length` 大，说明还有更早的记录没列出来。
+- 每条字段各自封顶（task 80 字、summary 100 字、label 120 字）。响应按字节预算逐条裁剪，超预算就停——返回的永远是合法 JSON（不会砍成半截 JSON）。
+- `scope=all` 时归档条目带 `archived: true`。
+- `session` 筛选时条目回显 `sessionId`。老记录没有这个字段，不匹配任何会话。
+
+## ptc_task_output
+
+参数：`task_id`（一条任务记录 id）。
+
+响应 = 那条记录 + 归约层：
+
+- `text`：孩子的散文答案。**交付物是这段正文**，报告只是摘要。正文从事件流现算，不另存一份。
+- 没有正文时给 `output`（原始事件流尾部，50KB 截断，砍头留尾）+ `guidance`（分层引导：先看报告，完整原文在 `outputPath`）。
+- `report`：孩子交的报告（`summary` + `findings`）。孩子没交报告时，这个键整个不存在。
+- `outputPath`：原始事件流的路径。
+
+registry 里记不住的 id 会回落压缩归档（TTL 窗口内仍可解，标 `archived: true`）。
+
+## 程序内检索
+
+`ptc_run_code` 的程序内可调 `tools.task_records({ scope: "all" })`：拿全部任务记录（含压缩归档）。
+
+机械扫描在宿主做，筛选与归约在程序里做。程序只 `return` 要的几条，其余不进上下文。
+
+正则跑在运行格里，运行格有 terminate 兜底；宿主本身没有隔离——病态正则要在程序里跑，别在宿主里跑。
+
+## 交付核对（delivery）
+
+任务记录与产出里带 `delivery`：**引擎从孩子的进程事件流抽的实测轨迹**，不是孩子的自述。
+
+- `tools`——孩子实际调用了哪些工具、各几次
+- `paths`——它实际碰过的路径（去重，按出现顺序）
+- `errors`——工具执行失败次数
+- `textChars`——孩子最终正文长度（0 = 空交）
+
+另有一行人话 `deliveryNote`，是同一份事实的渲染版。怎么用：
+
+- 结论声称来自某份材料 ⇒ 对一下 `paths` 里有没有那份：**没有 ⇒ 这条结论没有依据**
+- `paths` 空 + 报告 0 条 + 正文 0 字 ⇒ 这孩子零产出：**重派它，或明说缺口，别替它补数**
+- `errors` > 0 ⇒ 它撞过错（路径不对、读不到），先看错在哪再决定重派还是改任务书

package/docs/routes/reach-the-web.md

@@ -1,6 +1,9 @@
-# 上网查资料（web_ds_search，ADR-0001–0049）
+# 上网查资料（web_ds_search · 搜索域）
 
-搜索能力**只活在被派出的子代理里**（父会话不注册这个工具）——「这条来源靠不靠谱」的判断力在干活的子代理侧。
+pi 面上，搜索能力**只活在被派出的子代理里**（父会话不注册这个工具）——「这条来源靠不靠谱」的判断力在干活的子代理侧。
+
+> Kimi 面（`ptc-tools` 插件）例外：`web_ds_search` 模型可直接调用，配额按 MCP server
+> 进程计（默认 30 次），DeepSeek key 走 env → Kimi Code `config.toml` 两级解析。
 
 三动作：
 

package/docs/routes/run-one-program.md

@@ -1,11 +1,13 @@
 # 批量调工具的一段程序（ptc_run_code）
 
 `ptc_run_code({ code, description, timeoutMs? })`：code 是 TypeScript 程序体，
-支持顶层 await 与 return。程序内 `tools.<name>(args)` 调工具：
+支持顶层 await 与 return。程序跑在 **vm 运行格**里：唯一的出口是 `tools.*`（与直调
+同一条工具管线），没有 `process` / `fetch` / 动态 `import`（v7.0.0 起，ADR-0019，
+用过它们的旧代码会断）。程序内 `tools.<name>(args)` 调工具：
 
 - 绑定表 = 内置名单 ∩ 会话活跃工具（`--tools` 收窄的会话不会拿到被滤掉的绑定）
-- `bash` 不在默认表里，需 opt-in 授权（旧 ADR-0040）
+- `bash` 不在程序绑定表里——旧 ADR-0040 的 opt-in 尚未接线，当前没有任何开关能开它
 - 程序返回值是归约后的结果；undefined 返回标记为「无完成值」
 
-默认 2 分钟超时（可经 timeoutMs 下调，上限 10 分钟）。输出超 50 KB 按 pi 截断契约切尾，
+默认 2 分钟超时（可经 timeoutMs 调整）。输出超 50 KB 按 pi 截断契约切尾，
 全文写在临时文件、路径进尾注。

package/docs/routes/use-the-built-in-tools.md

@@ -3,5 +3,6 @@
 单次调用、或每步都需要模型判断的场景（写操作、审批敏感），不要写程序，直接调。
 
 - PTC 程序内：`tools.read / grep / find / ls / edit / write`（绑定表收窄规则见 run-one-program）
-- `bash` 需 opt-in：embedder 的 optIns 参数或 `~/.pi/agent/ptc.json` 的 optInBindings，处处 fail-closed
-- 程序外的逐个直调走 pi 自己的工具调用管线
+- `bash` 不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）——程序里跑 shell 没有路子
+- 程序外的逐个直调走 pi 自己的工具调用管线；注意 pi 内置工具**没有 cwd 囚禁**：
+  strict 只是工具白名单收窄，绝对路径可读工作区外任何可读文件——白名单 ≠ 沙箱

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ptc-subagents",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "Programmable tool calling (PTC) and subagent fan-out for pi",
   "keywords": [
     "pi",