Repository navigation
Releases
PiForge v0.12.1
PiForge v0.12.1 — 计划模式不再重发上下文
发布日期:2026-11-13
上一个公开版本是 v0.12.0。本次只有两条修复,都跟「计划模式」有关:一条是钱(前缀缓存不再被
plan 切换清空),一条是体验(输入框上方的进度卡片第一次真的会出现)。
亮点
切 plan 不再烧掉整段缓存
以前切到 / 切出 plan 模式,会同时改动两样东西 —— system prompt 里的计划段落、以及工具声明数组。
两者都在请求最前面,任何一字节变化都会让之后的整段历史作废,下一次请求按全价重发。
长会话里这一下就是几万到十几万 token,界面上会弹「前缀已失效,本次请求将重发 ≈N tok」。
现在:工具声明只跟工具预设走,与模式无关;计划段落改成尾部一条 display:false 的上下文消息。
plan 与执行模式的前缀字节完全一致,来回切换只多一条尾部消息。
计划进度卡片第一次真的会出现
输入框上方的步骤卡片此前在真实会话里一次也不会渲染:会话里记录的工具调用块是
{id, name, arguments},而折叠进度的函数只认 {toolCallId, toolName, input} —— 字段名对不上,
永远折叠出空。现在两种形状都认。顺带修好「工具调用统计」里全部落进 unknown 的同一个毛病。
plan 工具不再被存根
工具数量多时,扩展工具只保留名字不注入完整定义。plan 若被存根,模型拿不到参数说明就不会调用,
卡片也就永远空着。现在它和 tool_search、desktop_use_tool 一样恒常驻。
行为变化(请注意)
- plan 模式下模型能看到 write / edit / MCP / 插件工具的 schema,实际调用会被执行期拦下,
返回理由为Plan mode: planning only。 - 这是刻意的取舍:只要声明随模式变化,切换就必然重发上下文;用「看不见」换「不重发」,
在长会话里省下的是真金白银。 - plan 的只读语义、批准流程、卡片位置与交互都没有变。
安装提示
三端安装包仍未签名,与 v0.12.0 相同:
- Windows:SmartScreen 会拦,选「更多信息 → 仍要运行」。
- macOS:Gatekeeper 会拦,右键 → 打开,或执行 xattr -dr com.apple.quarantine。
- Linux:.deb 未签名,需 sudo dpkg -i(AppImage 直接运行)。
PiForge v0.12.0
PiForge v0.12.0 — 项目归用户管 · 数字与开关说真话
发布日期:2026-11-04
本次把 v0.11.3、v0.11.4 两次未公开发布的版本一并带上线(上一个公开版本是 v0.11.2),
再加上新的开发护栏与完整的 README / 发布说明重写。
亮点
项目归你自己管
左栏项目行悬停 ⋯ 或右键 → 「重命名项目」/「从侧栏移除」。
- 只改左栏显示名与可见性,磁盘目录与会话归属都不动;
- 只写一条本地偏好(
pi-sidebar-projects-v1),不删会话、不碰目录; - 以后用「新建项目」选回同一目录即自动恢复显示;改成空或改回文件夹原名 = 恢复默认。
用量先说真话
- 费用只报真实
usage累计,去掉流式阶段的估算叠加:没收到usage就不显示数字。 - 实时用量按会话隔离,别的会话在跑不再累加到当前这条用量条。
- 千以上缩写:< 1000 精确整数,≥ 1000 一位小数(
2.9K/69.8K),≥ 999,950 进位1.0M。 - 流式事件按帧合并、工具卡秒表 tick 局部化、打字 / 切会话 / 切面板的重渲染剪枝。
注入开关先说默认
- AGENTS.md / CLAUDE.md 注入:可按「跟随全局 / 开 / 关」三态控制,全局 + 项目级都可设,默认开。
- HANDOFF.md 接续注入:项目根或
docs/下的 HANDOFF.md 可注入系统提示词,默认关。 - 压缩摘要:固定中文、更简洁,默认只接管摘要正文。
看门狗看得懂长活
- 停滞阈值默认 20s → 90s,且 90s 就是最低档(运行期传更小的值会被钳住),上限仍 10min。
- 下拉预设改为 90 / 120 / 300 / 600 秒;扫描周期仍 5s、连续 2 次超阈值升级,即默认约 100s
无有效进展才亮红灯。 - 依然零 Token、零 prompt 注入:只在程序层看有没有有效进展。
Pi 核心 1.5.0
- 三个
@earendil-works/pi-*包精确锁定到1.5.0(传递依赖新增pi-schema)。 - 上游工具参数校验改由
pi-schema执行;PiForge 的工具全是普通 JSON Schema,
唯一适配是 MCPclientRegistration类型放宽到"auto" | "dcr" | "cimd"。
开发体验
dev:electron新增前置护栏:out/比源码旧时直接报错并提示npm run build:static,
不再让你对着旧 UI 调半天。PIFORGE_SKIP_STATIC_FRESHNESS=1可降级为警告。- 调用预算从「次数」改成「批次」:简单 1 批 / 普通 2–3 批 / 调研 3–4 批,单批并行 ≤ 12;
到顶先交付可验证结论,剩余待办留给下一轮。
默认行为变化(升级必读)
| 项目 | v0.11.2 | v0.12.0 |
|---|---|---|
| 看门狗停滞阈值 | 默认 20s,最低 5s | 默认 90s,最低 90s(预设 90/120/300/600s) |
| 新会话思考等级 | low | medium(均衡) |
| 点窗口关闭 | 静默隐藏 | 询问「最小化到托盘 / 退出程序」,可记住 |
| 项目名 / 可见性 | 固定 | 可重命名、可从侧栏移除 |
| 用量显示 | 含流式估算 | 只报真实 usage;千以上缩写 |
| 上下文文件注入 | 固定开启 | 可关(默认开),全局 + 项目三态 |
| HANDOFF.md 注入 | 无 | 可选,默认关 |
不变的:三进程边界、零内部端口、文件先授权再 IO、codemode 默认 only、主题与三栏布局。
安装与兼容
- 安装包由 CI 构建:Windows NSIS(含 ZIP)、macOS Universal DMG + ZIP、Linux
.deb,
并对每个平台执行打包后的启动冒烟。 - Windows 安装包未代码签名,可能出现 SmartScreen 提示。
- macOS 安装包未签名、未公证,首次打开可能出现 Gatekeeper 提示。
- Linux
.deb未做 debsig:自动更新通过dpkg -i/apt --allow-unauthenticated安装,
需要 root 授权;下载完整性由latest-linux.yml的 SHA512 校验,漏传该文件则收不到自动更新。 - 自动更新走 electron-updater 既有链路(检查 → 确认 → 下载 → 重启安装),更新源在构建期固定。
- 与终端 CLI 同时运行仍共享
~/.pi/agent;同一 session 两端同时写入仍不受支持。
验证
npm run lint→ 0 error / 8 warning(既有的未使用变量与 hook 依赖告警)。NODE_OPTIONS=--max-old-space-size=6144 npx tsc --noEmit→ 通过。npm test→ 1599 项,1595 通过 / 0 失败 / 4 跳过。- 三平台打包在
.github/workflows/desktop-packages.yml内完成,含smoke-packaged-layout、
smoke-packaged-static、smoke-packaged-standalone三层冒烟。
逐条变更见仓库内 CHANGELOG.md。
PiForge v0.11.2
v0.11.2 — 会话按时间分桶
侧栏会话改成按时间收纳:今天 / 昨天 / 过去 7 天按天,12 个月内按自然月,更早按自然年。
折叠头上的数字就是点开后的真实条数,点开不会空——因为它来自同一份已经加载到内存的数据。
改动
- 首屏一次取满 200 条(服务端单次上限),分页不再驱动滚动加载。
- 重写时间分桶:取消「更早」垃圾桶,月 / 年维度可读。
- 计数只数根会话,分支子会话不重复计。
- 默认只展开今天 / 昨天;其余桶收起,点开是纯状态变更。
- 删掉自动加载暂停、滚动哨兵、每项目「显示全部」。
已知边界
- 首屏冷启动约 400ms(200 条会话元数据首次解析),缓存命中后 23ms。
- 会话总数超过一页时,底部「加载更早的会话」不带数字:服务端
total含临时会话,数字会是假的。
验证
npx tsc --noEmit · npm run lint · 相关单测 27/27。
PiForge v0.11.1
PiForge v0.11.1
发布日期:以 tag v0.11.1 的 CI 产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。
本版是 0.11.0 之上的修 bug + 一个新开关,没有改调用预算与工具默认值:贴图不再卡主线程、
工具卡秒表不再一直跳、事件流断了会明说,另加一个默认关闭的「项目隔离」。
版本口径:
v0.11.0的 tag 打在release/v0.11.0分支上,main的package.json
还停在 0.10.0。本版把v0.11.0合并回来(调用预算、工具开销压缩、codemode 变更全都在),
再做 0.11.1 的四处改动 —— 从 0.11.0 升级你会拿到同样内容再加下面这些,不会退回 0.10.0。
贴图不再卡住输入框
截图贴进输入框时明显停顿,来源是三处都在主线程干的活:
- 缩放:以前把 4K 原图
drawImage进 1568px canvas(几十到上百毫秒同步)。现在用
createImageBitmap(file, { resizeWidth, resizeHeight, resizeQuality: "high" }),解码 + 重采样跑在
工作线程,主线程只搬一张已经缩好的小图(lib/image-attachment.ts)。 - 编码:剪贴板截图都是
image/png、名字也不含 screenshot,以前一律重编码 PNG(1.5MP PNG 编码又要
一两百毫秒)。现在 24×24 抽样探测 alpha,只有真透明才走 PNG,其余 JPEG(0.92);GIF/SVG 原样发送。 - 预览:贴图条的 56px 缩略图以前直接挂原图 object URL(要解码整张 4K)。现在额外生成 160px 缩略图
(previewUrl),大图查看器改用降采样整图的fullUrl;ImageBitmap显式close()。
交互侧:粘贴后先同步出现「处理中」占位,多图串行处理、每张让出一帧;处理中 canSend 为 false,
避免 Enter 把还没转换完的图默默丢掉;移除/发送/卸载时两个 object URL 一并 revoke。
工具卡秒表以 tool_execution_end 为准
工具卡耗时完成即冻结,不再跟着「最新一次调用」继续数(lib/tool-clock.ts + components/Transcript.tsx)。
同时修掉 DevEnvironmentConfig 里同一模式的计时残留。
事件流断了不再假装在思考
以前的失败形态是:连接断了,界面停在「PiForge 正在思考…」,用户不点停止就看不到已经产出的内容。
新增 hooks/agent-session/stream-health.ts(纯函数,可单测)区分三种故障:
reconnecting:连接反复失败,可重试;failed:重连耗尽;stalled:连上了但 30 s 没有任何真实增量(服务端缓冲 / 订阅没接上)。
界面用 components/StreamHealthBanner.tsx 明确告知,而不是让用户猜。
新开关:项目隔离(默认关)
常规设置 → 运行 →「项目隔离」。开启后一个项目只能读写自己目录内的文件,别的项目一律
AccessDenied;关着的时候行为与以前完全一致(所有会话 cwd 都放行)。
- 策略仍在 Host:
agent-host/allowed-roots.ts的authorizePath(target, op, scope?)多一道检查,
隔离开启时路径必须落在「当前项目」(scope优先,其次 Next 上报的 activeScope)内;
拿不到当前项目就 fail-closed,不会退化成「全世界可读」。 - 当前项目来源:
Workbench在活动会话 cwd 变化时 POST/api/files/scope→ Hostfiles.setScope
(contract/methods.ts已声明)。file-index/git/statusline/processes各自把 cwd 当 scope 传。 - 开关有 2 s 缓存,改完几秒内生效。
- 已知边界:开启后 worktree/scratch 目录(在项目外)与
~/.pi/**这类路径会被拒,
需要跑 worktree 协作时先关掉。
验证
| 项 | 命令 | 结果 |
|---|---|---|
| 类型检查 | NODE_OPTIONS=--max-old-space-size=6144 npx tsc --noEmit |
exit 0 |
| 项目隔离 | node --test agent-host/project-isolation.test.ts |
4/4(默认关不受影响 / 跨项目拒 / 无范围 fail-closed / activeScope 兜底) |
| 既有授权与设置 | node --test agent-host/allowed-roots.test.ts lib/desktop-settings.test.ts |
16/16 |
| 图片处理 | node --test lib/image-attachment.test.ts |
8/8(纯函数部分;主线程耗时需真机体验) |
| Lint | npx eslint <改动文件> |
0 error |
未在本版覆盖:打包版贴图端到端耗时没有做自动化采样(只保证主线程不再有全尺寸绘制与 PNG 编码);
三平台产物以 CI 为准。
产物
NSIS + ZIP + latest.yml(含 SHA-256)、Linux deb、macOS universal dmg/zip 由
desktop-packages.yml 在 push v0.11.1 tag 后于 CI 构建,本地不重复构建。
Windows 安装包未代码签名,SmartScreen 会提示「未知发布者」;macOS 包未签名未公证,首次打开需
右键 → 打开(或 xattr -dr com.apple.quarantine);Linux deb 未做 debsig,安装时需 root 授权,
完整性由 latest-linux.yml 的 SHA512 校验。
迁移与升级
- 从 0.11.0 / 0.10.0 升级都无需迁移:会话与设置分别在
~/.pi与%APPDATA%\piforge。 - 新开关默认关;只有主动打开「项目隔离」才会改变文件访问范围。
PiForge v0.11.0
PiForge v0.11.0
发布日期:以 tag v0.11.0 的 CI 产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。
本版主题:把「卡住」变成看得见的数字。调用预算第一次写死(每用户轮 <8 次工具调用、第 4 次
中途自检),工具固定开销整体压缩(输出预算 4k→24k 字符、默认超时 120s→45s);codemode 恢复逐条
声明工具并能在脚本执行期间看到进度;界面侧修掉「点了没反应 / 一上翻就被拽回 / 工具卡一直跳秒」;
度量与冒烟脚本不再静默挂死(这是本版工程量最大的一块)。
默认行为变了五处,见文末「默认行为变没变」。
调用预算:每用户轮 <8 次工具调用
- 提示词拆成两条(
agent-host/prompts/output-style.ts的BATCHING_RULES):「调用预算(写死)」
与「中途自检」。简单任务 ≤4 次、普通 ≤8 次、调研 ≤10 次;禁用du -sh与全量grep -r;
重型命令显式timeout 30;大量输出先用head/uniq摘要。仍是静态常量,只进一次前缀。 - 执行侧兜底(
agent-host/desktop-tool-guard-extension.ts):新增TURN_BUDGET
(softLimit: 4/hardLimit: 8)与createTurnBudgetTracker()。第 4 次调用的结果尾部追加自检
提醒,第 8 次起追加停止探测并要求先交付结论;before_agent_start复位计数,codemode 的嵌套调用
不重复计数;与原有的并行提醒合并追加,不互相覆盖。 - 目标很直白:把「一轮问十几遍」压回 PAD 水平,调用次数与墙钟时间都被这两条同时约束。
工具固定开销压缩
- 输出预算(
agent-host/tool-output-budget.ts):默认 4000 → 24000 字符(≈6000 tokens),
400 行兜底;超限时只留前 9000 + 后 9000 字符,截断提示补一句「需要全部内容请一次取完」。read
的 4000 / 3000 / 1000 档位不跟着默认值缩放(否则 read 会从 120 行变成 720 行);已截断文本
二次裁剪直接返回(幂等)。 - 超时默认值(tool-guard):普通 120 → 45 s,重型 900 → 300 s,上限 600 → 300 s。
- 调度器配额(
agent-host/desktop-tool-scheduler-extension.ts):全局重型 4 → 6,单会话重型
2 → 4;轻量档(全局 12 / 会话 6)不变。上一版 4/2 在「隔壁开一个打包」时排得太久。 - 以上默认值全部仍由
PIFORGE_TOOL_OUTPUT_CHARS/PIFORGE_TOOL_TIMEOUT_*/PIFORGE_SCHED_*
覆盖,A/B 臂不受影响。
codemode
- 池上限可配(
agent-host/codemode-worker-pool.ts):设置页 >PI_CODEMODE_MAX_WORKERS> SDK
默认 2,范围 1–8。Host 启动与设置变更各打一行生效日志;SDK 每条脚本重读 env,改完下一条立即生效。 - 默认模式
only→on(lib/desktop-settings.ts):工具恢复逐条声明给模型,脚本仍是首选路径;
显式写过only的老用户不受影响。 - 脚本内进度回传(
lib/codemode-progress.ts+agent-host/desktop-codemode-observer-extension.ts):
SDK 的tool_execution_update.details.calls在渲染层是空content,长脚本执行期间界面一片静止。
现在折成一行(bash ✓1.2s · read … · edit ✗0.3s,>5 条截断成… +N)走既有 liveOutput 通道;
脚本超时/取消时由观察扩展推断并打一行worker still exiting, slot held (pool=N)(文案写明
inferred,不假装是实时队列探针)。 scripts/hotfix/hotfix-codemode.ps1/.sh:打包版 codemode-worker 热修复脚本。
界面
- 工具卡耗时完成即冻结(新增
lib/tool-clock.ts):秒表起点存在模块级Map(键为toolCallId),
组件重挂载或历史分页不再从头计时;有 result 就停脉冲点、停运行态边框、停 200 ms 秒表;完成值优先
用 pi 记录的durationMs,旧会话用自测起止差兜底;历史加载的卡片没有起点,不会凭空显示巨大耗时。
4 个单测覆盖。 - 标签切换 / 侧栏会话点击改为同步提交:
setActiveKey与commitTabs原来包在startTransition
里,流式输出期间持续产生的紧急更新会不断打断它,表现就是「点了没有任何反应」且无报错。 - 上翻不再被自动贴底拽回:
wheel/pointerdown接管监听的 deps 原本是[],首屏 loading/空态
时滚动容器还没挂载,early return 后再也不会重绑;取消平滑滚动改用scrollTo({behavior:'instant'}),
写同名scrollTop取消不掉 smooth 动画。 - 介入提示不再冒充用户提问:统一加
[系统提示]前缀(contract/intervention-marker.ts),
Transcript识别后渲染成灰色系统卡片、隐藏分支/派生、不进回合导航刻度。
会话侧栏
- 首屏为每个项目补一条最新会话(
lib/session-reader.ts):近期会话按 mtime 全项目混排,首屏 20 条
常常全属于同一个项目,其余项目分组于是完全不出现(看着像升级后历史项目被清空)。现在额外给每个会话
目录补上它自己最新的一条(只读该条 header),并返回nextOffset游标;前端追加改用游标而非已渲染
条数,补齐项不会把中间会话跳过。
度量 / 冒烟脚本:不再静默挂死
这一块是本版的主要工程量。上一版开始,measure:* / smoke:* 在特定环境下会零输出挂死,
表现为「bash 卡住」,排查成本极高;本版逐层拆掉了。
- 等帧有硬期限(
scripts/measure-prefix.mjs):每次等响应帧默认 60 s 超时,不再无限静默等待。 - host 一死立即失败:
createClient(endpoint, hostChild)监听子进程exit/error与 socket
close/error,挂起的 waiter 全部立即 reject;socket close 比 child exit 先到时,最多等
HOST_EXIT_GRACE_MS = 700 ms把退出码并进错误(总耗时仍 ≤2 s),「崩了」和「被关掉了」分得开。 - stdin 护栏只写一处(新增
scripts/lib/host-spawn.mjs):hostChildEnv()在合并调用方 env
之前写死PIFORGE_HOST_STDIN_CONTROL=0,spawnNodeHost()统一 spawn node 版 host。12 个脚本
改走工厂,删掉各自手写的...process.env与护栏(上一版逐脚本手写,两次事故:duplicateenv:
覆盖前半段,端点与 token 全丢,host 直接 EADDRINUSE)。 smoke:prefix-budget每步可见:每步打一行开始/结束(含耗时),超过
PIFORGE_SMOKE_STEP_TIMEOUT_MS(默认 300 s)杀掉整棵进程树并以 124 退出;Windows 上
taskkill /F /T,避免 measure-prefix 被杀而 host 子进程留存。- 修
codemode-worker-pool测试的环境依赖:applyCodemodeWorkerPool不传 env 时按模块加载快照解析,
在带PI_CODEMODE_MAX_WORKERS=2的 Host 子进程里必红,改为显式传env: {}。
默认行为变没变
变了,五处:
- codemode 默认
on(v0.9.4 默认only):工具逐条声明回模型。显式写过only的配置不受影响。 - 不显式传
timeout的 shell 调用会在 45 s(重型 300 s)被打断,比上一版的 120 s / 900 s 更紧。
常驻进程、全量打包请显式传timeout。 - 工具输出预算 4000 → 24000 字符:截断变少,但单条结果更占上下文(
read档位不变)。 - 每用户轮工具调用软上限 4 / 硬上限 8:第 4 次起结果尾部带自检提醒,第 8 次起带「先交付结论」。
这两条是结果尾部追加的文本,不拦截调用。 - 调度器重型配额放宽到全局 6 / 单会话 4(轻量档不变)。
开关怎么用
- 输出预算:
PIFORGE_TOOL_OUTPUT_CHARS(500–200000,默认 24000)。 - 超时护栏:
PIFORGE_TOOL_GUARD=0整体关闭;阈值走PIFORGE_TOOL_TIMEOUT_SECONDS/
PIFORGE_TOOL_TIMEOUT_HEAVY_SECONDS/PIFORGE_TOOL_TIMEOUT_MAX_SECONDS/PIFORGE_TOOL_MAX_PARALLEL。 - 调度器:
PIFORGE_TOOL_SCHEDULER=0关闭;配额走PIFORGE_SCHED_GLOBAL_HEAVY/
PIFORGE_SCHED_GLOBAL_LIGHT/PIFORGE_SCHED_SESSION_HEAVY/PIFORGE_SCHED_SESSION_LIGHT/
PIFORGE_SCHED_MAX_WAIT_MS/PIFORGE_SCHED_QUEUE_HINT_MS/PIFORGE_SCHED_MAX_HOLD_MS。 - codemode:设置页「扩展与 MCP → Codemode」切
on/only;worker 池上限在同一处设置(1–8),
优先级 设置页 >PI_CODEMODE_MAX_WORKERS> 2。 - 调试日志:
PIFORGE_DEBUG_TOOL_GUARD=1、PIFORGE_DEBUG_TOOL_SCHEDULER=1。 - 冒烟/度量脚本的超时:
PIFORGE_SMOKE_STEP_TIMEOUT_MS(默认 300000)。
已知限制
- 调度器与工具预算只在 Host 侧生效;直接跑 pi CLI 不继承这些默认值。
- codemode 的 worker 槽位在脚本超时后要能等到 worker 真正退出才释放,我们只能推断并打日志,
没有队列状态接口(不 patchnode_modules)。 - 每用户轮的调用预算是提示词 + 结果尾部提醒,不是硬拦截:模型仍可能越过 8 次,只是会被明确要求收尾。
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。
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 两端同时写入仍不受支持。
PiForge v0.9.0
PiForge v0.9.0
发布日期:以 tag v0.9.0 构建产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。
本版主题:卡住看得见,介入点一下
v0.9.0 新增无进展看门狗(Watchdog)与人工介入:监控完全在程序层(内存状态机 + 定时器),
不产生任何 LLM 请求,也不往 system prompt / 对话历史里写任何字节。任务卡住时右侧「系统监控」
面板亮灯,你可以点一下 Skip(强制跳过)、发一句 极简询问(禁止跑工具、限 20 字),
或发起 深度诊断。所有介入指令都走既有的 steer / 排队 / prompt 通路,没有新增的模型直连。
配套:用量条常驻输入框下方;窄窗口(≤1080px)侧栏改为浮层;图片灯箱的复制/大图显示修好。
本版同时首次发出 v0.8.3 的省钱改造(工具 23 → 12、按需工具域、结果去重、缓存保活);
v0.8.3 未单独发布。
关键数字(与前版一致,无回归)
| 项 | 数值 | 口径 |
|---|---|---|
| 静态前缀 | 6 244 tok(记录型复测 6 240) | 记录型 provider,可复现 |
| 声明工具数 | 12(全常驻)/ 11(默认 shell 按需) |
measure:prefix |
核心四件套(read/bash/edit/write) |
710 tok | 与 pi CLI 四件套逐字节一致 |
| 稳定段缓存命中率 | 99.5%(记录型)/ 97.98%(真实 deepseek 30 轮) | 两个口径不可混读 |
| 自动压缩 | 关闭(本版也没有新增任何自动压缩) | agent-host/rpc-manager.test.ts |
| 看门狗 Token 开销 | 0(不调模型、不写 prompt) | 代码边界 + 通知走内存队列 |
新增
- 无进展看门狗:默认开启,20s 无有效进展判疑似卡顿(连续 3 次扫描升级
stalled,
单工具超阈当次升级),退避提醒 30s / 60s / 120s,之后标failed(只标界面,不干预模型)。
两把尺子:lastActivityAt(成功且不重复的动作 / 正文增量)与lastLivenessAt(活的迹象);
并发按toolCallId逐个建档。 - 人工介入(HITL):
Skip/极简询问(默认)/深度诊断;Host 侧守卫:同动作冷却 3s、
单任务上限 5 次、无活跃任务直接拒绝。 - 右侧「系统监控」面板:心跳、逐工具计时、疑似阻塞点、退避通知、JSON 详情、停滞阈值热切换
(15/30/60/90 秒,只写内存);会话列表 / 标签栏 / 工具卡三处只读状态灯。 - 用量条:Token、缓存命中、上下文占用、上游额度常驻输入框下方,点开仍是「用量与额度」弹窗。
- 窄视口浮层侧栏:视口 ≤ 1080px 时左右栏变浮层并默认收起,聊天区独占宽度。
变更
- 上游额度只请求一次(输入框用量条拉取,底栏复用同一份快照)。
- 思考档位菜单 3 → 4 档(
auto/high/medium/low),不再按模型能力过滤;
不支持的档位由后端收敛,老会话持久化值仍正常回显。 - 会话状态灯优先级:看门狗红(停滞)> 运行中蓝 > 等待操作琥珀 > 后台完成绿。
修复
- 图片灯箱「复制」此前永远失败:
clipboard.write只接受image/png,现在先重绘成 PNG。 - 灯箱优先显示原图(
previewUrl),不再用发给模型的降采样图(长边 1568)当大图。 - 灯箱右键菜单
Esc先关菜单;工具栏在 Electron 窗口拖拽条下让位。
迁移与升级
- 无强制迁移动作,默认前缀、工具声明、命中率均未变。
- 想完全回到 v0.8.2 行为:
PIFORGE_WATCHDOG=0(不建定时器、不记状态、watchdog.status
只回{enabled:false})+PIFORGE_ON_DEMAND_DOMAINS=0(全部工具常驻,前缀 6 988)。 - 按需工具域优先级不变:环境变量
PIFORGE_ON_DEMAND_DOMAINS> 设置项onDemandDomains>
默认shell;=1仍是memory+orchestrator按需的历史别名,不是「全按需」。 - 升级方式:Windows 直接运行
PiForge-Setup-0.9.0.exe(覆盖安装,会话与设置在~/.pi与
应用数据目录中保留);或解压 ZIP 免安装使用。macOS / Linux 见 Release 资产。 - 不在本版:工作区中未提交的自动更新(
electron/app-update*、useAppUpdater、
AppUpdateRow)与流式合帧(hooks/agent-session/frame-coalescer.ts)仍是 WIP,未进入 v0.9.0。
验证
npx tsc --noEmit0 错;npm run lint0 error(4 warning)。npm run smoke:prefix-budget退出码 0:默认 6 240 tok / 11 工具 / 核心 710,3 轮 cacheRead 命中 99.5%。
前缀与环境有关:~/.agents/skills存在时<skills>段进 system prompt(本机 +1 598 字符 ≈ +400 tok,
即 6 640),属环境差异;基线取清空技能目录后的口径。npm run smoke:agent-host:含watchdog.status(默认阈值 20s)、watchdog.task、
agent.intervene(非法 action 与会话不存在都必须拒绝)三类断言。npm test1 253 项:1 248 通过、3 项按平台跳过,2 项失败见下方「已知问题」。
已知问题
npm test有 2 项失败,均位于未跟踪的 WIP 测试文件,与 v0.9.0 无关:electron/auto-update-controller.test.ts:import 少.ts后缀(ERR_MODULE_NOT_FOUND);lib/agent-host-client.test.ts:等待一个尚未实现的 Host 握手重试。
- 这两项在本次发布整理动手前同样失败(同一份代码跑出同一结果),不是本版引入;
修它们必须改 WIP 代码,本版禁止,故保留原状并在此披露。
兼容性与已知限制
- 安装包未代码签名:Windows 可能出现 SmartScreen 提示,macOS 可能出现 Gatekeeper 提示。
- 看门狗是观测与人工介入,不做自动处置:自动跳过 / 自动杀进程仍在路线图上(见 README)。
- 介入指令会进入对话历史(那是你自己的指令),看门狗自动通知不会(只留在界面队列里)。
- 与终端 CLI 同时运行仍共享
~/.pi/agent;同一 session 两端同时写入仍不受支持。
PiForge v0.8.2
PiForge v0.8.2
发布日期:以 tag v0.8.2 构建产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。
本版主题:让成本可见 · 让子 Agent 真能干活 · 让长会话不卡
1. 上下文可视化:从"感觉快满了"到"看得见"
- 新增
agent-host/context-budget.ts(纯函数):把用量换算成相对硬顶的比例与等级(观察 60% / 临界 85% / 越顶),前端只负责上色。 - 对话底栏新增 14px 环形指示器:环走满 = 贴到硬顶,变红 = 已越顶并脉冲;精确数字收进 tooltip 与
aria-label,压缩进行中环会转。 - 硬顶常量单一来源仍是
agent-host/compaction-plan.ts,展示层不另立阈值。
2. 子 Agent:授权、超时、休眠一次收口
- 新增
agent-host/tool-grants.ts:默认继承父 Agent 的activeTools,bash / read / write / edit运行时存在即强制保留;父 Agent 显式tools: [...]时取并集放宽;递归与 UI 副作用工具(spawn_agent、herdr_*、orchestrator_*、受管进程、浏览器)永不下放;请求了运行时没有的工具立刻抛PERMISSION_MISSING,第一轮就讲清楚,不允许空转到熔断。 - 授权只读
pi.getAllTools()全量注册表,绝不读工具存根目录:存根开启不影响提权,子 Agent 的工具集也不会回写父 Agent 的声明,前缀缓存保持字节级稳定。 - 舰队单轮超时默认 5 分钟(原 15 分钟),可被调用方覆盖并夹在 1s–30min,到点
abort+ 强制终止,不留 zombie。 - 空闲 5 分钟自动休眠(60s 扫一次):
MAX_FLEET=4的槽位不再被挂机会话吃掉;herdr_spawn支持"完成即退出"的一次性任务。
3. 输出风格:只砍水分,不砍推理
- 新增
agent-host/prompts/output-style.ts:纯静态常量、禁止任何动态插值(prompt 缓存按前缀命中,混进时间戳/路径就整段失效)。先要求深入思考,最终输出禁客套、禁复述问题、改代码只给 diff、非明确要求不展开长文。 agent-host/desktop-output-style-extension.ts以幂等方式并入 system prompt(已有则跳过)。
4. 长会话不再卡:三个 Worker + 两处缓存 + 一次清理
lib/jsonl-worker.ts:>1MB 会话文件整体进worker_threads(源码内联,standalone 不用多带文件),失败/超时一律回落内联解析。lib/git-status-worker.ts:git rev-parse+git status进 worker(20s 超时),主线程只做 cwd 相对路径换算。lib/session-scan-worker.ts:会话索引扫描与分页同理,首屏不等扫盘。lib/transcript-turn-cache.ts:轮次对象按「消息引用同一 且 工具结果引用同一」缓存,流式期间不再每帧全量重渲(修掉turn 173 rendered 777 times)。lib/chat-scroll-memory.ts:display:none下量不出高度时沿用最后已知滚动位置,切回标签不再跳回第一条消息。lib/session-scope.ts+hooks/useSessionScope.ts:挂在会话上的setInterval/ResizeObserver/setTimeout(对账、贴底滚动、自动标题、乐观刷新)全部登记,切会话或关标签一次性disposeSession()。
5. 会话列表分页
- 首屏 20 条,滚动到底每次追加 10 条;索引 TTL 10s,扫描并发 8、
SessionInfo读取并发 4、缓存上限 400。 - 刷新按已加载深度重取(
loadedDepthRef),修掉"项目分组消失又出现"的跳动。 - 空闲预取下一批(并发 1、2s 超时);行内标记"已在标签页打开";一轮任务结束只补一次列表刷新(1.2s 节流)。
6. 技能面板
- 技能带
scope: global | project与来源agents | pi | package | other,项目级.pi/skills与用户级~/.agents/skills分开呈现。 - 修掉 Git Bash / msys2 下
HOME=/c/Users/x导致 Windows 拼出的目录不存在、用户级技能整批丢失的问题(调用期间对齐真实家目录,带串行锁)。 - 关键词自动分类(设计 / 前端 / 后端 / 测试 / 文档 / 发布 / 工作流 / 元技能 / 其它)+ 一句话概述;手动分类存
localStorage,不污染SKILL.md;扫描结果 5s 缓存。
7. 图片
- 贴图先在本地缩到视觉模型 1568px 长边上限(
createImageBitmap+OffscreenCanvas走合成线程):模型看到的信息一致,上传体积与计费 token 降 4~10 倍;任一环节不可用即回退原始读取。 - 缩放注记只给模型看,渲染前剥除,用户不会再看到自己"没说过的话"。
- 对话与工具输出里的图片点开即灯箱:缩放 / 平移 / 旋转 / 下载 / 复制 / 翻页,键盘
+ - R。
8. 回执、归属与状态栏
- 任务结束卡片:只有"忙 → 空闲"这一跳才算跑完,附最后一条回复摘要(1200 字符截断);后台标签保留绿点直到切回。
- Agents 归属:右侧面板按
项目 › 会话分组,排序session > project > other,运行中置顶;数据全走既有 SSE(subagents/fleet),零轮询。 - 状态栏让位:引擎健康点与 pi 核心版本迁入标题栏「系统状态」弹层(弹层不打开就不查上游版本);额度/余额改为右侧固定宽度区,数字变化不再拉宽整行;金额按 3 位有效数字显示(
0.001034不再被降级成<0.0001)。
验证
npx tsc --noEmit→ 0 errornpm run lint→ 0 error(3 条既有 warning:docs/assets/liquid-orb.js×2、middleware.ts×1)npm test→ 1091 项 / 1088 通过 / 0 失败 / 3 项按平台跳过- CI:本版 PR 触发 lint · typecheck · test 与三平台矩阵
兼容性与已知限制
- Windows x64 安装包未代码签名,首次运行可能触发 SmartScreen 提示。
- 子 Agent 工具授权默认放宽到核心写工具(
bash/read/write/edit),安全检查从"只读洁癖"改为"父 Agent 显式收窄";编排与 UI 副作用工具仍严格不下放。 - 3 项跳过测试为平台条件跳过,非功能缺陷。
PiForge v0.8.1
PiForge v0.8.1
发布日期:以 tag v0.8.1 构建产出为准(Windows NSIS + ZIP,Linux deb,macOS universal)。
本版主题:多 Agent 透明化 · 手动舰队 · Token 省钱阀门
1. Agents 面板实时同步
- 新增
fleet全局事件主题(Host 广播 +/api/fleet/eventsSSE),Agents 面板同时消费subagents与fleet两条流,不再依赖轮询。 - 修复「主对话已经在跑 Agent,右侧面板却是空的」:
spawn_agent/herdr_spawn曾因工具存根被隐藏,模型根本调不到。现在两者与tool_search/desktop_use_tool一起常驻声明。 - 列表运行中置顶、本会话派生的优先;SSE 断线才降级为轮询,并在面板上明示。
2. 手动派驻常驻舰队 Agent
- 面板新增「+ 新建 / 加载 Agent」:名称、System Prompt、只读工具权限(read/grep/find/ls),或从 JSON 配置导入(单条 / 数组 /
{profiles:[]})。 - 配置持久化到
<agentDir>/fleet/agents.json(原子写、坏文件降级为空、单条损坏不影响其它),重启自动回显。 - 唤醒只建会话、不跑首轮(不烧 token);卡片内可直接下发消息(底层
herdr_message),并区分「临时子 Agent / 舰队 Agent」。 - 新增 RPC:
fleet.list / save / delete / import / wake / message。
3. Agent 省钱阀门(硬闸)
agent-host/agent-guards.ts,subagents 与 herdr 两个 runner 共用:
| 阀门 | 阈值 | 行为 |
|---|---|---|
| 轮数上限 | 3 轮 | 第 4 轮直接拒绝,提示汇总后新建 Agent |
| 强制摘要 | 1200 字符 | 回给主 Agent 只有结论 + 关键要点,原始输出留在面板 |
| 上下文熔断 | 10k tokens / 轮 | 立刻中断并标记熔断,之后拒绝新指令 |
4. 其它
- README 重写:架构三条边界、多 Agent 对照、Token 经济与实测节省数据、命令与发布流程。
- 终端默认不再强制跟随滚动(仅在用户停留在底部时跟随)。
- 状态栏工具徽章配色细化;启动页切换新版 logo。
验证
npx tsc --noEmit→ 0 errornpm run lint→ 0 error(3 条既有 warning)npm test→ 1026 项 / 1023 通过 / 0 失败 / 3 项按平台跳过npm run build:agent-host+npm run smoke:agent-host→ OK- CI:
lint · typecheck · test、test (windows)、test (macOS)、build (next.js)全绿
兼容性与已知限制
- Windows x64 安装包未代码签名,首次运行可能触发 SmartScreen 提示。
electron/process-tree.test.ts在全量并发下偶发超时,单独运行可通过(系统负载敏感,非功能缺陷)。- 舰队 Agent 仍限定只读工具;写文件/跑命令请交给主 Agent 或编排 Worker。