Skip to content

PiForge v0.9.1

Choose a tag to compare

@github-actions github-actions released this 24 Oct 09:58
· 185 commits to main since this release
315f408

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-pi PR。
    只提 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 --noEmit 0 错。
  • npm run lint 0 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 test 1 388 项:1 384 通过、4 项按平台跳过、0 失败。
  • 受影响用例单独复跑:desktop-subagent-extension.test.ts 1 pass、
    desktop-native-runtime.test.ts 3 pass、subagents.test.ts 8 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 两端同时写入仍不受支持。