Skip to content

PiForge v0.10.0

Choose a tag to compare

@github-actions github-actions released this 25 Oct 05:55
· 129 commits to main since this release
8241cab

PiForge v0.10.0

发布日期:以 tag v0.10.0 的 CI 产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。

本版主题:边界收口。分支、排队、看门狗、文件侧栏的「点了没反应 / 点了要等」逐个拆掉;
Host 侧新增工具执行调度器与 shell 超时硬护栏,「隔壁跑大活,我这连简单任务都卡」不再发生。
默认行为有变的三处(工具超时、单批并行、探索顺序)在下面单独标注。

分支:能看全、能带走结论、不能乱点

  • 「分支」下拉改用完整分支图:会话接口的 tree 只含当前路径,兄弟分叉不在里面,旧实现
    hasBranch() 恒为 false,于是常有「明明分过支却说没有分支」。现在用 getBranches 的 nodes
    建树,行点击切到该节点的 leafId。
  • 多根分支图合成虚拟根(lib/session-branches-view.ts):pi 的 .jsonl 可能被手动编辑或
    跨设备合并出多根结构,渲染层会当成「当前会话没有分支」。现在多根先合成虚拟根再判分支。
  • 切分支时可蒸馏要离开的分支(分支下拉里的开关,默认关,localStorage 记住):开启后切
    分支走 navigateTree(target, { summarize: true }),把离开的那条分支压成一条 branch_summary
    追加到目标节点。探索两条方案时不必把两段对话硬拼进上下文(拼接会打断前缀缓存),也不丢结论。
    冷会话(进程里没有活会话)无法摘要,回 summarySkipped: "not-live",UI 会说明原因。
  • 运行中禁用分支与派生:流式期间 Host 本来就拒绝 fork(.jsonl 可能被追加写)和切分支
    (要移动活会话的叶子),旧前端只在 console 记一笔,点按钮等于没反应。现在按钮直接禁用并给出
    「本轮回复结束后才能…」提示,失败也会弹出中文原因,不再静默。

排队消息:可删、可重排

  • 排队中的消息新增删除按钮(hover 变红),Host 按 revision 出队:前端乐观更新,遇到 revision
    冲突就重拉队列,不会出现「删了还在」或「删错一条」。

看门狗(Watchdog)

  • 介入立即回执:agent.intervene 改成同步受理后立刻 result(),真正的投递走后台。按钮不再
    等当前工具跑完,steer 在 turn 边界落地的延迟不再进 UI 等待链。
  • 长命令真打断:强制跳过时若工具已跑超过 10 s,先 abortBash() 再投递;短命令不打断,
    避免白丢结果。
  • 卡顿只标真正卡住的那一行:看门狗状态是会话级的,旧实现用「整轮 running + 无 result」判定,
    于是同一条消息里早已结束的工具行也被染红并显示红色计时。现在工具调用 id 贯穿
    TurnBlock → ToolCallCard,只有 stuckToolCallIds 命中的行才染红。
  • verdict 向后兼容:旧 Host 不带 verdict 时不渲染结论条,不再出现空壳面板。

文件侧栏不再排在工具后面

文件授权(files.authorize)改走独立 RPC 连接(lib/host-files.ts 自建一条,挂
globalThis.__piforgeFilesHostClient)。旧实现和 agent 事件流共用主连接,单 socket 写队列 FIFO,
工具输出一多,点文件的授权请求就被挤到 15 s 超时之后——表现是「工具跑着点文件没反应」。
双连接实测 40 次交错 RPC 全通;这条约束已写进 AGENTS.md 的踩坑记录,别把它改回主单例。

Host:工具执行调度器(默认开)

同一个 Host 进程里一个会话发 25 个并行工具,shell 输出都压在一条事件循环上收,其它会话的普通
请求只能排队。新增 agent-host/desktop-tool-scheduler-extension.ts,只延后执行,不改参数、
不改结果
:

  • 双闸:全局 heavy 4 / light 12,单会话 heavy 2 / light 6;重型按命令特征分档。
  • 利用 SDK 的 emitToolCall 逐个 await handler + 每调用独立 _beforeToolCall,超额的调用
    停在自己的 tool_call 钩子里排队。
  • 等不到槽位(60 s)就放弃排队照常执行——宁可偶尔超发,不能用调度器把活卡死。
  • 释放点 tool_result;另有 15 min 强制回收(防审批 block / 僵死调用泄漏槽位),
    session_shutdown 清空该会话持有的一切。
  • 排队超过 1.5 s 才在该调用结果尾部追加一句提示,正常结果一个字不改。
  • 注册位置在审批扩展之后:被审批拦下的调用不能先占槽位。
  • codemode / tool_search / 嵌套调用豁免(它们本身就是合并后的批量)。

shell 超时硬护栏(默认开,默认行为变了)

pi 的 bash / powershell timeout 是可选项且无默认值,模型不传就永不超时。实测一次 25 个
并行调用里有条长驻调用把整批挂到 300 s。新增 agent-host/desktop-tool-guard-extension.ts:

  • tool_call 阶段就地补 event.input.timeout:普通命令 120 s、重型命令 900 s,上限 600 s / 900 s。
  • 非法值('300' / 0 / NaN)修成默认值,而不是让 pi 抛错。
  • 单批并行 > 8 时,仅在首个超限调用的结果尾部追加一句建议(每批一次,不 block、不丢工作)。
  • 仅当错误本身是 timeout:<秒> 时追加一句改法,原正文完整保留。

影响:不显式传 timeout 的长任务(常驻进程、测速、全量打包)会在 120 s(重型 900 s)被
打断。需要更长就显式传 timeout,或用 PIFORGE_TOOL_TIMEOUT_SECONDS /
PIFORGE_TOOL_TIMEOUT_HEAVY_SECONDS / PIFORGE_TOOL_TIMEOUT_MAX_SECONDS 调整,整体关掉用
PIFORGE_TOOL_GUARD=0。

提示词:批量预算再收一档

  • BATCHING_RULES 增补「同一批并行 ≤ 8」「重型命令单独跑并显式传 timeout」。
  • 探索改成先 rg -l 拿文件名,再定向 read(并进既有第 1 条,不增加行数)。
  • 仍是纯静态常量,无插值,一次前缀(+26 字符),缓存安全。

度量工具

  • npm run measure:prefix -- --summary 只打决策要用的 ≤10 行(每 runtime 一行 turns/sys/tools/
    prefix/body + 前缀是否稳定、两 runtime 差值、缓存命中率、前缀审计),完整报告仍走
    --json / --dump。

升级说明

  • 托盘 / 自动更新:按常规 electron-updater 链路检查 → 下载 → 任务结束后重启安装。
  • 安装包未代码签名,Windows SmartScreen 与 macOS Gatekeeper 会提示,属预期。
  • Linux .deb 通过 DebUpdater 更新,安装时需要 root 授权;完整性由 latest-linux.yml 的
    SHA512 校验。

修复:打包版 Host 不加载用户扩展

v0.9.2 起打包版优先跑单文件 Host bundle(agent-host/bundle/host.mjs,冷启动 3.1 s → 0.7 s)。
但 esbuild 打包时没有声明 Pi SDK 依赖的 PI_BUNDLED_NODE 常量,SDK 因此以为自己在跑
未打包的 dist 树,按 import.meta.url(打包后就是 bundle 自己)算 alias 去 import
~/.pi/agent/extensions/*,加载失败被吞成 session 级报错。

表现:Host 正常就绪、RPC 全通、会话能建能订阅,但用户自己的扩展一条都不生效
(session_start 钩子不跑、ctx.ui.* 不弹、自定义工具与命令消失)。v0.9.2–v0.10.0 的打包版
都是这个状态;非打包的 npm run dev / npm run dev:electron 不受影响。

修复与护栏:

  • scripts/bundle-agent-host.mjs 增加 define: { PI_BUNDLED_NODE: "true" },走 SDK 预设的
    embedded 路径(jiti/static + 虚拟模块)。bundle 体积 15.3 MB → 14.6 MB。
  • 新增 npm run smoke:extension-ui-bundled:复刻打包布局(wrapper index.js → ./host.mjs)
    跑一遍 Extension UI Bridge 冒烟,删除 define 会直接红。已接入 CI。
  • npm run dist / npm run pack 现在也跑 smoke-packaged-standalone。之前只有 macOS 的
    dist:mac 跑它,所以同一个 bug 在 Windows / Linux 的流水线上一直是绿的。

基线内容(上游 pi-agent-desktop v0.10.0 → v0.11.0)

本仓库基线是上游 pi-agent-desktop@v0.11.0,PiForge 不发 0.11.0。上游 v0.10.0 / v0.11.0
的说明合并到这里(原先的 docs/releases/v0.11.0.md 已并入本文件),版本号仍按 PiForge 自己的
0.10.0 走。

升级(上游 v0.10.0,2026-10-12)

  • Pi SDK 升级至 1.1.0:@earendil-works/pi-ai、pi-coding-agent、pi-mcp 从 0.99.1 跨大版本
    升到 1.1.0。依次跨越 1.0.0 / 1.0.x / 1.1.0,带来 Codemode 提示词降约 40% token、codemode 图像
    生成、MCP 项目级 override、pi.registerToolRenderer()、MCP OAuth 全链路可取消与请求超时、
    工具执行时长 durationMs、Claude Haiku 5.5 等上游改进。
  • 漏洞修复随上游落地:1.1.0 钉 brace-expansion@5.0.12,修复上游标记的
    GHSA-q2hr-2g5m-vwhr 等漏洞。

修复(上游 v0.10.0)

  • Azure Provider 改名适配:上游 1.0.3 将 provider id 从 azure-openai-responses 改为 azure,
    模型配置界面的 Azure 条目图标 key 同步更新。既有配置需要手动迁移:auth.json、
    models.json.providers 中的 provider key,以及 settings.json 的 defaultProvider、
    enabledModels 中的 provider 模式、modelThinkingLevels 中的 provider/model key 都改用
    azure。API id azure-openai-responses 与环境变量 AZURE_OPENAI_* 不变;旧 Azure 会话恢复时
    可能回退到其他模型,原提示词缓存不能复用,请确认当前模型后再继续。
  • MCP 凭据边界:拒绝项目 mcp.json 直接引用模型 provider 凭据;全局 auth.provider 必须使用
    HTTPS(仅 loopback HTTP 例外)。配置加载与保存均执行检查。
  • MCP 项目覆盖:项目只修改 enabled、exposure、toolExposure 时保留全局连接和认证配置;
    配置界面与运行时使用同一合并结果,原生 /mcp 保留覆盖文件来源。
  • 编辑项目覆盖时保留全局认证及后续连接更新的继承关系;被拒绝的配置仍显示错误状态,支持编辑修正
    或删除。

安全依赖更新(上游 v0.10.0)

  • Next.js 与 eslint-config-next 更新到 16.3.8,Sharp 更新到 0.35.5,并刷新 http-cache-semantics、
    source-map-js 的修复版本。
  • 将间接依赖 KaTeX 统一为 0.18.2,避免旧依赖范围继续安装受影响版本。
  • 上游 v0.11.0 的依赖审计:5 项 high、8 项 moderate、0 项 critical,属既有 ESLint 与 Electron
    打包工具链告警,未做跨主版本降级或强制依赖修复。

侧边栏更新(上游 v0.11.0,2026-10-16)

  • 文件夹式项目导航:项目以可折叠的文件夹呈现,会话归属与分叉层级更清晰;优化行间距、选中
    状态、悬停操作和资源管理器区域。
  • 三种项目排序方式:默认按项目名称自然排序,可从顶部排序菜单切换为「最近活跃」或「手动排序」。
    最近活跃按项目内最新会话时间排列。
  • 拖拽项目排序:上下拖动项目文件夹即可调整顺序,放下后自动进入手动排序并保存。长列表支持边缘
    自动滚动,搜索期间暂停拖拽。拖拽只调整显示顺序,不移动磁盘目录,不改变项目内会话排序及分叉归属。
  • 更连贯的交互动画:完善文件夹展开收起、拖动预览、列表让位和落位反馈;支持键盘上下重排、
    Escape 取消,并遵循系统「减少动态效果」设置。
  • 同步中英文界面文案,排序菜单仅保留名称、最近活跃和手动排序三个选项。

修复(上游 v0.11.0)

  • 重命名或删除会话失败时展示服务端返回的具体错误;响应缺失或无效时回退到通用错误提示。

兼容性与已知限制(上游)

  • 上游 v0.10.0 为跨 1.0 大版本升级,除 Azure 图标外还适配了新增 MCP 认证与项目覆盖规则。类型检查
    不能单独证明运行时兼容,相关边界已用隔离配置和真实 SDK 回归测试验证。详见
    docs/research/pi-core-upgrade-2026-10-11.md。
  • 与终端 CLI 同时运行仍共享 ~/.pi/agent 目录;同一 session 两端同时写入仍不受支持。
  • 相关上游改动:侧边栏与排序 PR #60。