Skip to content

fix: propagate compress outcome/blocksCreated through host forwarding lanes (#2752) - #2782

Merged
ranxianglei merged 4 commits into
masterfrom
2026-10-11_forward-partial-outcome
Oct 12, 2026
Merged

ranxianglei merged 4 commits into
masterfrom
2026-10-11_forward-partial-outcome

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2752

问题

#1875/PR #2116 让 endpoint 返回机器可读的 outcome / blocksCreated,但两个转发器(src/agent/shared.ts 与 src/mcp.ts 各自的 forwardTool)把它压成 {text, failed}:partial 与 applied 在宿主侧形状完全相同,模型与分析工具只能靠解析自然语言区分「全部应用」和「部分应用」。大回执里 partial 很容易被读成完整完成。

修法(机制层面)

  • 两个转发器防御式解析 outcome(仅接受已知枚举值)与 blocksCreated(仅非负整数),垃圾值降级为 absent——旧 envelope 保持原有形状,不从脏数据推断新行为。
  • partial 文本标记:仅当 outcome === "partial" 时在 text 末尾追加一行 [acp-result: PARTIAL — N block(s) created; some requested range(s) were NOT folded. Retry ONLY the failed range(s) listed above; do not re-fold the ranges that were applied.]。applied/refused/failure envelope 逐字节不变(有回归测试钉住)。字符串型通道(dsh-native/dsh-acp/opencode V1/V2/acp-command)无需改码——它们读 out.text,标记自动到位。
  • MCP shim:状态同时走 MCP spec 的 structuredContent 字段({outcome?, blocksCreated?},仅在字段存在时发出);isError 语义不变。
  • pi 通道:走 pi 的 details 元数据通道(session-manager.d.ts:91 官方注释:"Use details for extension-specific metadata (not sent to LLM)")——成功与失败分支都携带,分析工具可分类每一次调用;旧 pi 宿主忽略未知字段。

行为变更披露(old → new)

面 old new
plugin/MCP 宿主可见的 partial 回执正文 首行 [Compressed … → N block(s), … saved.] + per-range Errors/Skipped 同上,末尾多一行 [acp-result: PARTIAL …]
applied / refused / failure 回执 原样 逐字节不变(测试钉住)
MCP tools/call 响应 {content, isError} 新增可选 structuredContent(spec 字段,老客户端忽略)
pi session JSONL 中 bili 工具结果 无 details 新增 details:{outcome?,blocksCreated?}(不发给 LLM)
isError / throw 语义 failure/refused→error 不变;partial 仍非错误,但现在可辨认

不改变 ok 传输语义、不回滚已应用块、不改成整批原子提交、不引入新的成功推断(blocksCreated == 请求范围数 不作为判据;refold 场景两者不等价)。幂等/重叠跳过(refused with reason)继续走 isError 且 reason 保留在正文。

config surface

无新增配置项/env/CLI flag。无 kernel/ 触碰。无版本 bump。

测试

新增 tests/issue2752-forward-partial-outcome.test.ts(22 个用例,真实共享转发路径):

  • shared.forwardTool vs canned http proxy:applied / partial / partial-no-count / refused / 幂等跳过(failure) / legacy 无 outcome / malformed outcome(["PARTIAL","Applied",42,null,{}]) / malformed blocksCreated(["3",-1,1.5,null,[]]) / ok:false 硬错误仍 throw
  • mcp.forwardTool:同契约四态
  • pi 宿主 e2e(createBiliPlugin("pi") + manifest):isError/details/text 逐分支配对
  • MCP wire 级(spawn 真实 shim,stdio JSON-RPC):structuredContent 在线上响应中确实存在;legacy envelope 无该字段
  • 一成功一失败(partial)、全成功(applied)、全拒绝(refused)、仅幂等跳过(failure)分别覆盖

定向验证全绿:#2752 套件 22/22;issue1875+issue2204+host-native-caller 29/29;plugin-agent 69/69;mcp-native-thread(真 shim stdio e2e)8/8;typecheck 干净;build 通过。全局回归交 CI。

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-11_forward-partial-outcome (e92f44d)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3125-pr.2782.0af8b23

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2782.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,开始对本 PR(#2782 → Closes #2752)做合并前核验:拉分支核对代码、审既有行为回归面、查 CI 状态。完成后按八问体例回复结论。

ework-agent added 2 commits October 11, 2026 20:18
… lanes (#2752)

The endpoint already reports machine-readable outcome/blocksCreated
(#1875), but both forwarders collapsed it to {text, failed}: a partial
fold rendered identically to a full apply on every host lane.

- agent/shared.ts + mcp.ts: parse outcome/blocksCreated defensively
  (known enum values / non-negative integers only; garbage degrades to
  absent); append one explicit PARTIAL note line to text ONLY when
  outcome is partial — applied/refused/failure envelopes keep their
  exact historical bytes
- mcp shim: expose the state as MCP structuredContent alongside content
  (additive spec field; older clients ignore it); isError unchanged
- pi lane: ride pi's details metadata channel (persisted with the
  session, not sent to the LLM) on both success and error branches
- string-only lanes (dsh/opencode V1/V2/acp-command) need no change:
  they read out.text, which now carries the partial marker
@ranxianglei
ranxianglei force-pushed the 2026-10-11_forward-partial-outcome branch from e5da77b to 2ab8530 Compare October 11, 2026 12:23
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 合前验证完成(代码审查 + CI 诊断 + 修复已推送)。CI 正在新 head 2ab8530d8 上重跑,全绿后可合。

验证了什么

① 原 issue 方向(#2752):成立。#1875/PR#2116 让 endpoint 返回机器可读 outcome/blocksCreated,但两个转发器把它压成 {text, failed}——partial 与 applied 宿主侧形状相同。修法打的是机制层(防御式解析 + partial 显式标记),不是症状补丁;方向对。

② 回归清点(diff 触碰路径的既有行为,逐项):

  • applied / refused / failure / legacy(无 outcome)回执正文:逐字节不变(测试钉住,我逐行核对过:新增分支仅在 outcome==="partial" 时触发);
  • isError/throw 语义:failure/refused→error 不变;partial 仍非错误(现在可辨认);
  • proxy 模式(纯客户端):compress 工具调用是临时的、不走 forwardTool 路径,不受影响;plugin 模式拿到标记 = 本 PR 的有意变更;
  • 字符串通道消费者审计(shared.forwardTool 全部 8 个调用点:pi.ts ×3、dsh-acp.ts、opencode-v2.ts ×2、dsh-native.ts ×2、opencode-acp-command.ts、opencode-native.ts):只读 .text/.failed,结构兼容,标记经 text 自动到位;
  • MCP:tools/call 响应新增可选 structuredContent(spec 字段,老客户端忽略);全仓 grep 确认无任何 outputSchema 声明 → 无 spec 冲突;legacy envelope 不发出该字段(mcp.ts:359 条件发射);
  • pi:outcomeDetailsOf 在 outcome/blocksCreated 均缺省时返回 undefined(pi.ts:535)→ legacy 结果字节级保持原形状;旧 pi 宿主忽略未知 details 字段;
  • 缓存/持久化格式/上游 wire 协议/kernel/:无触碰;无 config surface 变更;
  • 副作用(已披露):toolOk() 统一打 outcome:"success" → 非 compress 工具回执也会携带 details:{outcome:"success"} / MCP structuredContent{outcome:"success"},PR 披露表已覆盖;external-summary-compress 也走同一 outcome 通道,其 partial 回执同样获得 PARTIAL 标记(措辞贴合,outcome-driven 设计下自洽)。

③ 代码审查:防御式解析正确——仅已知枚举值/有限非负整数存活,垃圾值降级为 absent,不从脏数据推断新行为;failed 映射新旧版本对所有输入可证等价;PARTIAL 标记单一来源(partialOutcomeNote,partialOutcomeNote(blocksCreated?) 缺计数时省略计数子句),两个转发器不重复定义。

④ 测试有效性:有牙。22 个用例用真实 HTTP canned proxy 驱动真实转发路径(不是 mock 被测函数);malformed 矩阵覆盖 outcome ["PARTIAL","Applied",42,null,{ }] 与 blocksCreated ["3",-1,1.5,null,[]];MCP wire 级 spawn 真实 shim(stdio JSON-RPC)断言 structuredContent 确实在线上响应中;pi 通道走 createBiliPlugin("pi") + fake extension API 的 e2e 配对断言(isError/details/text 逐分支配对);字节稳定性断言直接钉住回归面。

⑤ diff 整洁度:5 个文件全部与本 PR 目的相关;无空行/重排噪音;无 lockfile churn(本地 npm install 产生的 package-lock.json 漂移已还原,未入提交)。

CI 红了的原因(已诊断并修掉)

unused-exports guard 报 1 处:INTERNAL_ONLY src/proxy-tool-result.ts: CompressOutcomeKind —— PR 把这个类型提为 export,但文件外无人引用(仅被同文件的 ToolOutcomeKind 使用)。guard 红按 ci.yml 设计级联跳过整个 test job(所有 guard 是 test 的前置),所以 CI 表面是「一个红 + 一个 skip」,实际根因就这一行。本地 worktree 复现确认。

已推送到 PR 分支的两个动作:

  1. rebase 到最新 master 4387bcfb0(原 base 43c1b57de 落后约 90 个提交;两侧文件零重叠,确认过,rebase 无冲突);
  2. 新 commit 2ab8530d8:fix: drop unused export of CompressOutcomeKind (unused-export gate)——去掉一个 export 关键字,独立标注提交。

rebase 后 head 的本地定向验证:unused-export gate clean;#2752 套件 22/22 绿;typecheck 干净。全局回归交 CI(正在跑)。

结构化八问

  1. 是什么问题:宿主侧转发器把 endpoint 的机器可读 outcome/blocksCreated 压成二元 {text, failed},partial 与 applied 不可区分,大回执里 partial 易被读成完整完成。
  2. 什么原因导致的:转发层只透传 failed 位、未透传业务结果字段——Plugin tool endpoint reports ok:true when the kernel refuses a fold range #1875 引入机器可读字段时的能力缺口,非逻辑 bug。
  3. 影响范围与严重程度:所有 plugin/MCP 宿主(pi/opencode/dsh/MCP-shell 客户端)的 compress 回执可读性;特定条件下(partial 真实发生时)模型可能误判完成而漏重试或误重试;无数据丢失、无功能损坏。
  4. 怎么修复的:防御式解析(垃圾降级 absent)+ 仅 partial 追加显式 [acp-result: PARTIAL …] 标记行;状态同时经 MCP structuredContent 与 pi details 元数据通道透传,不改任何既有字段的字节。
  5. 是否有回归问题:未发现。applied/refused/failure/legacy 逐字节不变(测试钉住);isError/throw 语义不变;proxy 模式不走该路径;8 个消费点只读 .text/.failed。唯一可见漂移是 toolOk() 的 success 标签外溢到非 compress 回执(已披露,属本 PR 设计的自然结果)。
  6. 是否破坏缓存:不涉及——缓存/重试/增量游标/去重键策略零改动。
  7. 是否改了设计方向:不涉及——机制留在转发层;endpoint 契约、ok 传输语义、幂等/重叠跳过行为均未变,未引入新成功推断。
  8. 是否引入了新的配置:不涉及——无新 env/config/CLI flag。

判定

代码面已就绪:rebase 至最新 master + guard 修复后,本地定向验证全绿。等 CI 在新 head 2ab8530d8 全绿。本 PR 涉及宿主可见回执形状变更,按 §7.4 必须人工合并——CI 绿后请自行合并:#2782

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 进展更新:guard 全绿(含修好的 unused-exports),ubuntu 两条 test leg(22/24)全绿;windows-latest 两条 test leg(22/24)红。

初步排查(平台托管的 check 不暴露日志,API 无 output/logs_url,以下为代码侧证据):

已推空提交 e8c33b5f6(零 diff,仅重触发流水线)在新 head 上重跑;若 windows leg 复现同位置失败,说明是确定性问题,我会拿具体失败用例继续定位。有结果即报。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 最终结论(拿到日志实证了):windows 红腿与本 PR 无关——是 master 新 storage proof 套件在 Windows 上的环境性 flake。

证据(下载了两轮失败 leg 的完整 Actions 日志)

两轮 windows 失败均为 6359 tests / 6336 pass / 1 fail / 22 skip,唯一失败都在 tests/storage-engine-proofs.test.ts,且两轮挂的是不同用例:

  • 第一轮 win-22(job 114470642641):corrupt index.db degrades to legacy-only (#2771) — EBUSY: resource busy or locked, unlink ...\bili-engproof-corrupt-*\index.db(unlinkSync→rimrafSync);
  • 第二轮 win-24(job 114475410964):full-mode restart is invisible on the chat wire — EPERM, Permission denied ... golden-chat-*(rmSync,tests/tmp-rm.ts:23 ← golden-storage-drive.ts:559)。

同一失效域(Windows 文件锁撞上 cleanup),实例不同、非确定性——与今日刚合入的 54f21d3(close index.db handles before rmrf — Windows EBUSY)同族;那个修复覆盖了 open 阶段句柄,这两例残留在 cleanup 阶段。

本 PR 的 22 个新用例在 Windows runner 上全部通过(四个 suite 逐个 ✔,含 spawn 真 shim 的 stdio wire 级测试);ubuntu ×2 全绿;其余 24 checks(guards + e2e lanes)两轮全绿。

处置

判定

代码面无回归、无缓存/配置/wire 上游变更(八问见上条回复),CI 唯一红灯为无关环境性 flake 且有日志实证。可合:按 §7.4 宿主可见回执形状变更须人工合并,请自行合并 #2782 ;若分支保护要求 CI 形式全绿,点一次 re-run failed jobs 即可(或等 #2799 修复后自然转绿)。

@ranxianglei
ranxianglei merged commit 467b0f6 into master Oct 12, 2026
28 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.316-master.467b0f6 (rolling master tag).

npm install -g billion-context@0.0.316-master.467b0f6  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

ranxianglei pushed a commit to YunzhouLi-hub/billion-context that referenced this pull request Oct 12, 2026
…2816)

tests/issue2752-forward-partial-outcome.test.ts (added by c81be81, merged via ranxianglei#2782) spawns the real MCP shim over stdio but was never registered in the ranxianglei#2816 tripwire, so every test job died at startup before running a single test since 467b0f6. Concurrency review for c=4: all HTTP servers bind listen(0) dynamic ports; the spawned shim is killed in afterEach; BILI_MCP_PROXY/BILI_CONVERSATION_ID are passed in the child env at spawn time; src/mcp.ts itself binds no port and writes no state. Registered after review per the tripwire contract.
ranxianglei pushed a commit that referenced this pull request Oct 12, 2026
ranxianglei pushed a commit that referenced this pull request Oct 12, 2026
… events (#2901)

#2637's fail-fast tiering gated version/kernel/pi-subagents/lane-guard with 'if: pull_request' on the assumption that skipped needs count as satisfied. That is not what GitHub Actions does: a needed job skipped via if blocks its dependents, so since bc6e327 every master push, release-branch push and workflow_dispatch showed test+static-gates = skipped — master's own CI never ran the suite (the blind spot through which #2782's unregistered spawner shipped undetected; #2896/#2901). Remove the four event gates so all eight needs run on every event. The guards are inert by construction on non-PR events: their checks are three-dot diffs against origin/master (empty on a push to master), and version-guard/kernel-guard fall back from GITHUB_HEAD_REF to GITHUB_REF so *_release-v*, bugfix-release/* and *_release-kernel-v* branches keep their exemptions. PR flow is unchanged (GITHUB_HEAD_REF takes precedence). Behavior change: non-PR runs execute the full test + static-gates matrix again (pre-#2637 behavior restored) plus four ~10s zero-dep guard jobs.
ranxianglei pushed a commit that referenced this pull request Oct 12, 2026
… events (#2901)

#2637's fail-fast tiering gated version/kernel/pi-subagents/lane-guard with 'if: pull_request' on the assumption that skipped needs count as satisfied. That is not what GitHub Actions does: a needed job skipped via if blocks its dependents, so since bc6e327 every master push, release-branch push and workflow_dispatch showed test+static-gates = skipped — master's own CI never ran the suite (the blind spot through which #2782's unregistered spawner shipped undetected; #2896/#2901). Remove the four event gates so all eight needs run on every event. The guards are inert by construction on non-PR events: their checks are three-dot diffs against origin/master (empty on a push to master), and version-guard/kernel-guard fall back from GITHUB_HEAD_REF to GITHUB_REF so *_release-v*, bugfix-release/* and *_release-kernel-v* branches keep their exemptions. PR flow is unchanged (GITHUB_HEAD_REF takes precedence). Behavior change: non-PR runs execute the full test + static-gates matrix again (pre-#2637 behavior restored) plus four ~10s zero-dep guard jobs.
@github-actions github-actions Bot mentioned this pull request Oct 13, 2026
@ranxianglei
ranxianglei deleted the 2026-10-11_forward-partial-outcome branch October 15, 2026 05:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态

1 participant