Repository navigation
PiForge v0.9.1
PiForge v0.9.1
发布日期:以 tag v0.9.1 构建产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。
本版主题:子 Agent 不再两轮被判死
v0.9.0 的运行时审计(docs/optimizations/subagent-runtime-audit.md)用 17 次真实派发量出一件事:
子 Agent 的轮数阀门 off-by-one(used < maxTurns + 默认上限 3)导致第 3 轮就 abort,
内聚模块任务 8/8 被判超轮次取消、已读到的结论被丢弃,主 Agent 只拿到一句 was cancelled;
审计口径成功率 4/17 ≈ 24%。
v0.9.1 只改阀门、结算顺序与失败回包,不动并行架构、不动提示词契约:
- 默认轮数上限 3 → 6,
PIFORGE_SUBAGENT_MAX_TURNS可覆盖(非法值回落默认并写明原因)。 - 判据修成
used <= maxTurns:第maxTurns轮放行,第maxTurns+1轮才拦。 - 结算顺序改为空转 → 上下文 → 轮数:上限(6)刻意高于空转阈值(5),
progress-guard 才轮得到生效(旧顺序下它永远不生效)。 ok:false回包不再是空话:status: need_help+turns N/上限+last_action+reason+
next_steps(重派 / 拆小任务 / 换常驻),主 Agent 能区分"缺上下文"与"真死循环"。- 常驻舰队(herdr)传
maxTurns = null:无硬上限,与一次性子 Agent 共用同一份阀门代码。
同时把 Pi 核心从 1.1.0 升到 1.4.0(接口适配只落在 agent-host/sdk-adapter.ts 与测试),
并接上每周一次的自动升级雷达。
关键数字
| 项 | 数值 | 口径 |
|---|---|---|
| 静态前缀 | 6 640 tok(干净基线 6 240) | npm run measure:prefix;本机存在 ~/.agents/skills(<skills> 段 +1 598 字符 ≈ +400 tok) |
| 声明工具数 | 11 | 同上;shell 默认按需,不进声明集合 |
核心四件套(read/bash/edit/write) |
710 tok | 与 pi CLI 四件套逐字节一致(本轮无回归) |
| 前缀稳定性 | 两轮 prefixHash 一致(922c24df1c72) |
measure:prefix 逐轮对比 |
全常驻配置(PIFORGE_ON_DEMAND_DOMAINS=0) |
7 388 tok | A 组对照,不进默认预算 |
| 单测 | 1 388 项:1 384 通过 / 0 失败 / 4 跳过 | npm test |
6 640 与 v0.9.0 文档里的 6 244 不是回归:后者是清空技能目录后的基线口径,
两者差值与本机<skills>段一致(见docs/measurements/README.md)。
新增
- 子 Agent 输出契约(
agent-host/subagent-prompt.ts,单一事实来源):- 代码改动必须在
patch字段给出可git apply的git diff正文,禁止散文交付;
给不出补丁 →status: "need_help"并说明缺什么。 - JSON 只约束最终回复(
status/conclusion/key_changes/patch/error_trace/next_steps),
工具调用阶段完全自由;这条是防实测过的误读(同时要求结构化 + 干活 → 模型少调工具直接编结论)。 PIFORGE_SUBAGENT_PROMPT=legacy|contract可回退,默认contract;非法值回落 contract 并写明原因。spawn_agent与herdr_*共用同一份规则,只换开场白。
- 代码改动必须在
- 子 Agent 会话隔离(
agent-host/session-isolation.ts):默认仍是SessionManager.inMemory()
(零落盘),新增PIFORGE_SESSION_DIR供需要落盘的实验/工具使用。 - Pi 自动升级雷达(
.github/workflows/pi-auto-upgrade.yml):每周一 02:00 UTC + 手动触发,
复用npm run check:pi-updates(新增--json)判断落后 →npm i -D -E @latest→
build/tsc/lint/sdk-imports/三个受影响的单测 → 全绿才开chore/auto-upgrade-piPR。
只提 PR,不发版;安装包与latest*.yml仍由desktop-packages.yml产出。
变更
- Pi 核心
@earendil-works/pi-*1.1.0 → 1.4.0(精确锁定)。上游 1.4.0 已不再包含
@earendil-works/chord;emitBeforeAgentStart改为接收 trigger 对象
({ messageType, prompt }),该调用只存在于测试,业务代码未直接依赖。 agent-host/sdk-adapter.ts增加fauxToolCall导出:防腐层继续是唯一直接 import
@earendil-works/*的文件(npm run check:sdk-imports已恢复全绿)。- 轮数阀门上限可配置后,
agent-guards.test.ts断言改为"上限必须高于 progress-guard 阈值(5)",
防止后续有人把默认值调回 3 又让空转阀失效。
修复
- 子 Agent 轮数阀门 off-by-one:第
maxTurns轮被误判为超限,实际只有maxTurns-1轮产出。 herdr舰队 Agent 的turns口径少算一轮,已与一次性子 Agent 对齐。- 阀门触发的
need_help正文不再被Cancelled覆盖(那是两条不同的失败路径)。 agent-host/subagents.test.ts曾直接 import@earendil-works/pi-ai,绕过防腐层;现已收回sdk-adapter.ts。
迁移与升级
- 无强制迁移动作:默认前缀、工具声明集合、缓存口径均未变;子 Agent 契约默认即
contract。 - 想回到旧行为:
- 旧轮数上限:
PIFORGE_SUBAGENT_MAX_TURNS=3(不设则默认 6)。 - 旧提示词:
PIFORGE_SUBAGENT_PROMPT=legacy。
- 旧轮数上限:
- 升级方式:Windows 直接运行
PiForge-Setup-0.9.1.exe(覆盖安装,会话与设置在~/.pi与
应用数据目录中保留);或解压 ZIP 免安装使用。macOS / Linux 见 Release 资产。 - 客户端自动更新走已有的 electron-updater 链(
checkForUpdates→downloadUpdate→
quitAndInstall),更新源不随本版变化。
验证
npm run build:agent-host通过(70 条路由生成);npx tsc --noEmit0 错。npm run lint0 error(5 warning,均为既存未使用变量,未在本版引入)。npm run check:sdk-imports:sdk-adapter boundary: OK。npm run check:electron-deps:16 个 electron-updater 运行时包齐备。npm run smoke:prefix-budget退出码 0:默认 6 640 tok / 11 工具 / 核心 710;
shell默认不声明、tool_search("shell"|"memory"|"orchestrator")激活后连续两轮 prefixHash 一致、
前缀棘轮unexpectedChanges=0。npm test1 388 项:1 384 通过、4 项按平台跳过、0 失败。- 受影响用例单独复跑:
desktop-subagent-extension.test.ts1 pass、
desktop-native-runtime.test.ts3 pass、subagents.test.ts8 pass。
已知问题
- 上下文熔断(10k tok)现在是子 Agent 的首个瓶颈:轮数阀门放宽后再跑 8 次真实派发,
工具调用次数从 4–5 次升到 5–9 次(不再提前杀),但下一个卡点变成单轮上下文
11.2k–18.2k tok 触发熔断。本版不动该阈值,留作下一轮优化的起点。 - 子 Agent 成功率未在本版重测:审计的 4/17(≈24%)是旧阀门口径;本版只证明"不再提前杀",
不给新的成功率数字。要新数字需重跑docs/optimizations/subagent-runtime-audit.md里的三条假设实验。 tmp/subagent-audit/里的审计脚本与探针仍未纳入版本库(实验资产,不入发布包)。- 自动升级工作流用
GITHUB_TOKEN推的分支不会触发ci.yml;需要在 PR 上跑 CI 时配置
AUTO_UPGRADE_TOKEN(PAT / App token),否则手动 re-run。
兼容性与已知限制
- 安装包未代码签名:Windows 可能出现 SmartScreen 提示,macOS 可能出现 Gatekeeper 提示(未签名、未公证)。
- Linux
.deb未做 debsig,安装需要 root 授权;自动更新依赖 Release 资产里的latest-linux.yml。 - 看门狗仍是观测与人工介入,不做自动处置。
- 与终端 CLI 同时运行仍共享
~/.pi/agent;同一 session 两端同时写入仍不受支持。