pi-ptc-subagents 7.4.0 → 7.5.0

package/dist/index.js

@@ -4058,6 +4058,7 @@ const TOOLS = {
 			"什么时候写程序而不是逐个调工具，看系统提示词 <ptc> 节的路由表。",
 			"程序内可调本会话已启用的同名工具（read / write / edit / grep / find / ls；bash 默认不可用），参数与直接调用该工具完全一致；每次调用返回 Promise，要 await，返回文本结果，失败抛异常。",
 			"程序内还可调 task_records({ scope: \"all\" }) 取任务记录（all 含压缩归档）——要挑很多条时在程序里筛完只 return 要的几条。",
+			"程序内还可调 task_output({ taskId }) 取孩子交回的正文——返回 {text}（孩子的散文，不是原始事件流）；text 空时看 status：还在跑就等一会儿再取，别当没产出；收多份正文时读完只 return 汇总。",
 			"例：const files = await tools.find({ pattern: \"*.py\" }); for (const f of files) await tools.write({ path: f, content: body });"
 		].join("")].join("")
 	},
@@ -4121,10 +4122,9 @@ const ROUTES = [
 		name: "派一个子代理",
 		when: "材料多、主题互不相干、每份都要读一堆材料时派——父一个人扛会算错（实测 92%→100%，n=3）；成本 10 倍上下，一件能算完的活别派",
 		how: {
-			full_ptc: "tools.pi_task_ptc({ task, label? })（程序内）——task 是孩子的唯一规格（写死路径/命令/交付物格式）；要报告就点名 child report 的 JSON 块（summary/findings），别自创报告格式；汇总前核对孩子产出（delivery），零产出就重派别补数",
+			full_ptc: "tools.pi_task_ptc({ task, label? })（程序内）——task 是孩子的唯一规格（写死路径/命令/交付物格式）；要报告就点名 child report 的 JSON 块（summary/findings），别自创报告格式",
 			codemode_ptc: "tools.pi_task_codemode({ task, label? })（脚本内）——task 是孩子的唯一规格（写死路径/命令/交付物格式）；要报告就点名 child report 的 JSON 块（summary/findings），别自创报告格式；汇总前核对孩子产出（delivery），零产出就重派别补数"
 		},
-		fact: "默认不等，立刻返回 handle；任务在任务记录里排队，可经任务面三工具查/停",
 		detail: "docs/routes/create-a-task.md"
 	},
 	{
@@ -4135,7 +4135,6 @@ const ROUTES = [
 			full_ptc: "ptc_run_code({ code, description })",
 			codemode_ptc: "不适用——写程序是 full_ptc 面的编排能力；本面用 codemode 编排、pi_task_codemode 派任务"
 		},
-		fact: "程序内 tools.*；bash 当前不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）；只在本面（full_ptc）注册 PTC 工具",
 		detail: "docs/routes/run-one-program.md"
 	},
 	{
@@ -4146,7 +4145,6 @@ const ROUTES = [
 			full_ptc: "ptc_workflow({ meta, script, args? })",
 			codemode_ptc: "不适用——同 run-one-program：workflow 是 full_ptc 的编排能力"
 		},
-		fact: "script 内可用 workflow.log/phase/parallel/pipeline；只在本面注册",
 		detail: "docs/routes/run-a-phased-workflow.md"
 	},
 	{
@@ -4154,10 +4152,9 @@ const ROUTES = [
 		name: "直接用内置工具",
 		when: "单次调用就够，或每步都要模型判断（写操作、审批敏感）",
 		how: {
-			full_ptc: "程序内 tools.read/grep/find/ls/edit/write；逐个直调走 pi 自己的工具",
+			full_ptc: "程序内可调同名工具；逐个直调走 pi 自己的工具",
 			codemode_ptc: "脚本内 tools.<内置名> 直接调"
 		},
-		fact: "bash 当前不在程序绑定表里（旧 ADR-0040 的 opt-in 尚未接线）",
 		detail: "docs/routes/use-the-built-in-tools.md"
 	},
 	{
@@ -4168,7 +4165,6 @@ const ROUTES = [
 			full_ptc: "孩子的契约：最终消息末尾 fenced JSON（summary/findings/files_touched/usage）；宿主自动解析",
 			codemode_ptc: "同左——契约在孩子的追加提示词里，与 surface 无关"
 		},
-		fact: "reportChannel 恒在四值：tool/prompt-json/none/opted-out；工具通道（ptc_child_report）已是首选",
 		detail: "docs/routes/report-what-you-did.md"
 	},
 	{
@@ -4176,10 +4172,9 @@ const ROUTES = [
 		name: "上网查资料",
 		when: "需要网页搜索、抓页面、页内找内容——判断力在干活的子代理侧",
 		how: {
-			full_ptc: "派子代理（pi_task_ptc），孩子用 web_ds_search（search/open/find 三动作）",
+			full_ptc: "派子代理（pi_task_ptc），孩子用 web_ds_search",
 			codemode_ptc: "同左——搜索只在子代理进程里注册，父会话没有这个工具"
 		},
-		fact: "webDsSearch 开关默认关（fail-closed）；配额每进程计；概览走 snippet 超预算整条丢弃",
 		detail: "docs/routes/reach-the-web.md"
 	},
 	{
@@ -4190,7 +4185,6 @@ const ROUTES = [
 			full_ptc: "ptc_task_list / ptc_task_output / ptc_task_stop（模型直调）——产出里的 delivery 是引擎实测轨迹",
 			codemode_ptc: "同左（模型直调；脚本经结构化返回）——产出里的 delivery 是引擎实测轨迹"
 		},
-		fact: "有任务记录这三个工具才出现在模型面前（ADR-0007）",
 		detail: "docs/routes/manage-a-task.md"
 	}
 ];
@@ -4224,7 +4218,7 @@ function estimateTokens(text) {
 	return Math.ceil(text.length / 2);
 }
 const ROUTE_INDEX_LEAD = {
-	full_ptc: "批量调工具默认先写程序（ptc_run_code）；单次调用或要逐步判断、审批敏感的才直连。派不派子代理自己判断——路由表第一行写了代价。",
+	full_ptc: "批量调工具默认先写程序（ptc_run_code）；单次调用或逐步判断、审批敏感的才直连。派不派子代理自己判断——第一行写了代价。",
 	codemode_ptc: "编排写 codemode 脚本；批量派活经脚本内的 pi_task_codemode；要查/停任务用任务面三工具。派不派自己判断——路由表第一行写了代价。"
 };
 function renderRouteIndex(surface, detailBase, nudge = true) {
@@ -5233,6 +5227,20 @@ function createTaskBinding(door) {
 	};
 }
 const TASK_RECORDS_BINDING_NAME = "task_records";
+const TASK_OUTPUT_BINDING_NAME = "task_output";
+function createTaskOutputBinding(source) {
+	return async (args) => {
+		const raw = args;
+		const taskId = raw?.taskId ?? raw?.task_id;
+		if (typeof taskId !== "string" || taskId === "") return { error: "taskId 必须是非空字符串" };
+		const record = source.registry.get(taskId) ?? await source.readArchivedRecord(taskId);
+		if (!record) return { error: `unknown task id ${taskId}` };
+		return {
+			...await readTaskOutput(source, record),
+			status: record.status
+		};
+	};
+}
 // src/session.ts
 function assemblePtcSession(options = {}) {
 	const registry = new TaskRegistry(options.onTransition);
@@ -5689,6 +5697,7 @@ function createBindingTable(pi, session, getToolContext, env) {
 		if (args?.scope !== "all") return records;
 		return [...records, ...await session.readArchivedRecords()];
 	};
+	table[TASK_OUTPUT_BINDING_NAME] = createTaskOutputBinding(session);
 	return table;
 }
 function registerPtcTools(registerTool, options, surface) {
@@ -5775,4 +5784,4 @@ function registerTaskDoor(registerTool, session, surface) {
 		}
 	});
 }
-export { assemblePtcSession, buildEngineContext, piPtcEntry as default, withDeliveryNote };
+export { assemblePtcSession, buildEngineContext, createTaskOutputBinding, piPtcEntry as default, withDeliveryNote };

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

@@ -16,3 +16,4 @@ pi 面上，搜索能力**只活在被派出的子代理里**（父会话不注
 - 模型可见文本预算 12,000 字符；超了按排名**整条丢弃** + 告知丢了哪些（要哪个用 open 补抓）——不按字符截断
 - 配额每进程计（`searchMaxCalls`，默认 30 次/进程，0 = 不限；只计成功调用）
 - 开关 `webDsSearch`（`~/.pi/agent/ptc.json`）是布尔，**默认关**：开关关 = 工具不存在；开关开但缺凭据 = 注册但调用返回可读错误
+- **开关关着就别派这类任务，也别去改它**：那是用户的配置，不是你的开关——改了等于替用户开了一个有网络出口、按次计费的能力。直接说明「搜索没开，做不到」；用户要的话他会自己开。实测（2026-11-01）：读到「默认关」后去改配置、翻源码找开关位置的会话，比老老实实说做不到的慢 4 倍

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

@@ -7,6 +7,7 @@
 
 - 绑定表 = 内置名单 ∩ 会话活跃工具（`--tools` 收窄的会话不会拿到被滤掉的绑定）
 - `bash` 不在程序绑定表里——旧 ADR-0040 的 opt-in 尚未接线，当前没有任何开关能开它
+- 程序内还能调 `task_records({ scope })` 取任务记录、`task_output({ taskId })` 取孩子交回的正文（归约后的散文）——返回 `{text}`；`text` 空时看 `status`：还在跑（`queued`/`running`/`stopping`）就等一会儿再取，别当没产出
 - 程序返回值是归约后的结果；undefined 返回标记为「无完成值」
 
 默认 2 分钟超时（可经 timeoutMs 调整）。输出超 50 KB 按 pi 截断契约切尾，

package/package.json

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