Repository navigation
PiForge v0.10.0
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:复刻打包布局(wrapperindex.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 idazure-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。