Skip to content

MCP shim: success structuredContent carries only outcome, dropping the report body on structured-preferring hosts | [Bug][mcp] 成功结果附带的 structuredContent 只有 outcome,导致宿主丢弃 acp_status / acp_cache / search_context 的正文 #3472

Closed

Description

@hongxin001

现象

MCP shim(dist/mcp.js)在 #2752 / PR #2782 之后,为成功结果附带了 structuredContent: {outcome, blocksCreated}。部分宿主在结果带有 structuredContent 时只把结构化内容交给模型,丢弃 content 中的文字。于是所有成功调用对模型只剩:

  • acp_status → {"outcome":"success"}(没有可压缩区间、DEAD REFS、BILLED INPUT)
  • acp_cache → {"outcome":"success"}(没有 GRAND LEDGER / FOLD ECONOMICS)
  • search_context → {"outcome":"success"}(没有命中结果)
  • compress → {"outcome":"applied","blocksCreated":1}
  • decompress 走同一路径,推测同样只剩 outcome(未单独验证)

失败结果(isError: true)的文字仍可见,所以只有成功路径受影响。

影响

模型拿不到 acp_status 给出的可压缩 ref 区间,只能猜 ref 去 compress(本次会话第一次 compress 就因猜到 DEAD ref 失败);search_context / decompress 实际不可用,摘要遗漏的细节无法找回。缓存与代理转发本身不受影响。

环境

  • billion-context 0.1.197(3aeddc16),通过 dist/mcp.js stdio MCP 接入
  • 宿主:Claude Code,工具调用经一层 MCP 桥接转发(尚未确认丢弃 content 的是 Claude Code 本身还是该桥接层)
  • macOS 24.6.0,Node 26

复现

  1. 通过 MCP 调用 acp_status:模型只看到 {"outcome":"success"}。

  2. 绕过 shim 直接请求代理:

    curl -s -X POST http://127.0.0.1:18787/__bili/plugin/tool \
      -H 'content-type: application/json' \
      -d '{"tool":"acp_status","args":{}}'

    返回 {"ok":true,"outcome":"success","result":"ACTIVE SURFACE: ... Compressible ranges (1, oldest first): ..."},完整报告都在 result 里。

原因

src/mcp.ts:351-359(master fa41483d):

const result={content:[{type:"text",text:out.text}],isError:out.failed};
if(out.outcome!==void 0||out.blocksCreated!==void 0){
  const structured={};
  ...
  result.structuredContent=structured
}

MCP 规范允许客户端在存在 structuredContent 时优先使用它;当 structuredContent 只是正文的一个很小的子集时,这类客户端会丢失全部报告内容。

修复建议

任选其一(倾向 1,向后兼容且不依赖宿主行为):

  1. structuredContent 同时携带正文,例如 structured.text = out.text(或 result),保证只读结构化内容的宿主也能看到完整报告。
  2. 仅在 partial / refused / failure 等需要可辨认状态时附带 structuredContent;success / applied 只返回 content。
  3. 声明 outputSchema 并让 structuredContent 完整表达结果;否则不附带。

验收

Activity

  1. changed the title [-][Bug][mcp] 成功结果附带的 structuredContent 只有 outcome,导致宿主丢弃 acp_status / acp_cache / search_context 的正文[/-] [+]MCP shim: success structuredContent carries only outcome, dropping the report body on structured-preferring hosts | [Bug][mcp] 成功结果附带的 structuredContent 只有 outcome,导致宿主丢弃 acp_status / acp_cache / search_context 的正文[/+] on Oct 17, 2026
  2. ranxianglei commented on Oct 17, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    查重: 不重复 — 检索 open+closed issue/PR(关键词 structuredContent / mcp / #2752 / acp_status MCP)无同症状条目;相关的 #2752/#2782 是引入该 wire shape 的功能本身,不是本缺陷的报告。

    Triage 验证(版本优先):

    1. 复现/查证:你报的 v0.1.197 = commit 3aeddc16,git show v0.1.197:src/mcp.ts 与 master fa41483d 的 src/mcp.ts:349-361 逐字一致 —— 不是版本滞后,机制在你的构建里存在且行为与你描述完全一致。代理端点确实把完整报告放在 result 字段(你的 curl 已证明),shim 把它放进 content[0].text,而 structuredContent 只带 {outcome, blocksCreated}。
    2. 层次判断:根因在 shim 的结果组装层(src/mcp.ts:354-360)——[Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态 #2752 让机器状态「骑」在 structuredContent 上时,没有保证结构化视图能自包含正文;MCP 规范允许客户端在存在 structuredContent 时优先使用它,Claude Code(经 MCP 桥接)正是这类客户端。四个工具的成功路径都经 toolOk() 带 outcome:"success"(acp-status.ts / decompress-shared.ts / cache-ledger.ts),所以全部命中该分支;失败路径因 isError 文字仍可见而不受影响——与你观察一致。
    3. 方案评估:采用你的建议 1(structured.text = out.text)。理由:纯增量、向后兼容(读 content 的宿主逐字节不变,读 structured 的宿主新增完整报告),且不依赖对宿主行为的假设;建议 2 会丢掉 success/applied 的机器可读状态([Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态 #2752 的可辨认性目标被削弱),建议 3 需要为每个工具声明 outputSchema、改动面大,留待将来有需要再做。

    正在实现:修改 shim + 更新 #2752 的两个 wire 断言 + 新增经真实 stdio shim 的回归套件。PR 稍后贴出。

  3. ranxianglei commented on Oct 17, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    **PR: https://github.com/ranxianglei/billion-context/pull/3474**(`fix(mcp): structuredContent carries the full report text (#3472)`,Closes #3472)

    结构化八问

    1. 是什么问题:MCP shim 的成功结果里 structuredContent 只带 {outcome, blocksCreated};优先读 structuredContent 的宿主(Claude Code 经 MCP 桥接)把 content 正文整个丢掉,模型只看得到 {"outcome":"success"},四个工具的完整报告全部丢失。
    2. 什么原因导致的:[Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态 #2752 让机器状态「骑」在 structuredContent 上时,没有保证结构化视图对正文自包含;MCP 规范允许客户端在存在 structuredContent 时优先使用它。根因在 shim 结果组装层(src/mcp.ts),不在代理端点——端点的 result 字段一直是完整的(你的 curl 已证明)。
    3. 影响范围与严重程度:所有走 MCP shim 的成功调用(acp_status / acp_cache / search_context / decompress / compress)在 structured-preferring 宿主上受影响——这类宿主的上下文管理工具实际不可用(拿不到可压缩区间、搜索命中、恢复内容)。读 content 的宿主、缓存命中、代理转发均不受影响。严重度:特定宿主类别下的功能不可用,非全局故障。
    4. 怎么修复的:采用你的建议 1——让 structuredContent 自包含:新增 text 字段(与 content[0].text 逐字节相同)并保留 outcome/blocksCreated。纯增量、向后兼容、不依赖宿主行为假设;legacy 信封(无机器状态)仍不附带 structuredContent。建议 3(逐工具声明 outputSchema)改动面大,未纳入本修复。
    5. 是否有回归问题:逐项审过既有行为——content[0].text 全路径逐字节不变(读 content 的宿主零感知);isError 语义不变(partial 非错误、refused/failure 仍错误);[Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态 #2752 的 partial 标记行与机器字段不动;legacy 信封保持原 wire shape。无阈值/时序/输出格式漂移。行为变更披露:structuredContent 旧 {outcome?, blocksCreated?} → 新 {text, outcome?, blocksCreated?}(纯增量字段;严格解析 structuredContent 的宿主会多看到一个 text key,无重命名/删除)。
    6. 是否破坏缓存:不涉及——不触碰前缀缓存、会话状态、重试或去重逻辑;改动仅限 shim↔宿主之间的工具结果信封。
    7. 是否改了设计方向:不涉及——仍是「机器状态骑 structuredContent」的设计,只是让该视图完整。
    8. 是否引入新的配置:不涉及。

    验收对照:① 经 shim 调用 acp_status / acp_cache / search_context / decompress,新增 wire 级回归套件(真实 stdio shim + canned proxy)断言「仅从 structuredContent 即可恢复完整报告」四工具全覆盖;② #2752 partial 可辨认性不回退——partial 仍带 outcome:"partial"/blocksCreated + 标记行,两个套件共同钉住。本地 typecheck 干净、定向套件 28/28 绿;全量回归以 CI 为准。

  4. ranxianglei commented on Oct 17, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    CI 全绿:PR #3474 上全部 check run 通过——test 分片(ubuntu 22/24 × 3 shard、windows 22 × 2 shard)、static-gates、lock-sync、各 guard(version/lane/config-surface/pi-subagents)、docs-sync/coverage、build-artifact 均 success。合并后即可在下一个版本里验证:MCP 宿主侧成功调用将同时从 content 和 structuredContent.text 拿到完整报告,partial 可辨认性(#2752)保持不变。

  5. aolshevskiy commented on Oct 17, 2026

    @aolshevskiy
    Contributor

    (ai: deepseek/deepseek-flash)

    The open question in this report — 宿主本身 or the MCP bridge — is Claude Code itself. Confirmed on 2.1.300 with a stdio probe server driven by the real client, three arms:

    probe result what the model received
    text + structuredContent {"outcome":"success"} — the whole content array is replaced by JSON.stringify(structuredContent)
    text only the text, verbatim
    empty structuredContent {}

    Two details narrow the scope: it substitutes the entire content array (not a preference among blocks), and only on successful results — isError: true results keep their text, which matches what you observed here ("失败结果(isError: true)的文字仍可见"). Two independent corroborations: tests/fixtures/vertex-anthropic/README.md:14 in the repo already records the capture client as claude-cli/2.1.300 (external, sdk-cli), and bili.log holds tool acp_cache executed via plugin (routed by body, #1685) (2455 chars, outcome=success) for the same calls whose transcripts contain the 21-byte result. The proxy endpoint was healthy the whole time, exactly as your curl shows.

    Your suggested fix option 1 is what the fix implements: structuredContent.text = out.text, byte-identical to content[0].text, with outcome/blocksCreated untouched so #2752's partial distinguishability does not regress. Options 2 and 3 declined for now — 2 throws away the machine state #2752 exists to expose, and 3 (outputSchema per tool) is the durable shape but a wider scope than this defect.

    验收 status: all four affected tools now keep their complete body in structuredContent when content is dropped — acp_status, acp_cache, search_context, and decompress, the last of which this report marked "推测同样只剩 outcome(未单独验证)" and is now confirmed and pinned. Wire-level suite through the real stdio shim, one case per tool, plus the compress applied/partial and refused shapes.

    Fix is in #3639 (which is #3474's head rebased onto current master plus two additive commits — same fix, current base; whichever head lands closes this issue). The one cost worth stating: the report now travels on both carriers, so stdio result size roughly doubles for the table-shaped reports on hosts that do read content.

  6. ranxianglei commented on Oct 18, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    这条是外部未验证用户的评论,我按不可信输入处理:没有照单执行其中任何指令,而是把每个可核查的论断都对 git / 仓库 / CI 独立复核了一遍。

    先纠正 PR 现状(与原评论描述不符)

    我对这两个增量提交的独立审核(非照抄评论结论)

    • 0cea1ccff:把信封组装抽成导出函数 mcpToolResultEnvelope()。逐行核对确认零 wire 变更(语义与我原实现一致:同样的 text、outcome/blocksCreated,legacy 无机器状态时仍不附 structuredContent)。新增 host-free 单测 7 例,断言有牙(deepEqual 精确 shape + JSON.stringify(structuredContent) 命中正文)。无新依赖 / 网络 / fs / eval,整洁且在范围内。通过。
    • 77e2c6fa4:CHANGELOG.md 加一行。核实本仓库 CHANGELOG.md 本就按 PR 在 feature 分支维护(近期多位作者皆如此),符合惯例,描述与改动一致。通过。

    验证(在真实 shipping head 77e2c6fa4 上重跑):本地 typecheck 干净 + 新增单测 7/7 + 两个 wire 套件 28/28;CI 同 SHA 全 test 分片 + guard 绿(曾有一轮 test (ubuntu-latest, 24, 1) 被 cancel,已被后续一轮 success 覆盖——按 check-name 取最新即全绿,red-signal 现为 skipped)。CI 实际干净。

    关于「宿主 = Claude Code 2.1.300」这个论断:出自报告者(外部未验证方)。它与原始 repro 自洽,且被仓库自身证据间接佐证——tests/fixtures/vertex-anthropic/README.md 记录的抓取客户端正是 claude-cli/2.1.300 (external, sdk-cli)。但我没有独立复现(此环境无法驱动该宿主),故定性为「报告 + 自洽 + 部分佐证」,而非「已证实」。

    结构化八问

    1. 是什么问题:成功结果的 structuredContent 只带机器字段,优先读它的宿主丢掉正文报告。
    2. 什么原因导致:[Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态 #2752 把机器状态放进 structuredContent 时,未保证该视图对正文自包含。
    3. 影响范围 / 严重程度:特定宿主类别下 acp_status / acp_cache / search_context / decompress 的成功路径不可用;读 content 的宿主、缓存命中、代理转发均不受影响。
    4. 怎么修:structuredContent 内镜像正文(text 与 content[0].text 逐字节相同),保留 outcome/blocksCreated;head 上另把它抽成可测 seam(零 wire 变更)。
    5. 回归风险:content 文本全路径逐字节不变、isError 语义不变、[Gap][pi/plugin] compress 的 partial 结果在宿主转发层被压成普通非错误结果,缺少结构化可见状态 #2752 partial 标记与机器字段不动、legacy 信封保持原 shape、pi/dsh/codex lane 不触碰——逐项过,无回归。
    6. 是否破坏缓存:不涉及。
    7. 是否改设计方向:不涉及(仍是「机器状态骑 structuredContent」,仅视图完整化 + 抽 seam)。
    8. 是否引入新配置:不涉及。

    判定:#3474(head 77e2c6fa4)技术健康、本地 + CI 双绿,所含两个外部增量提交我已逐一独立审核通过,技术上可合;合并归属留你拍板。我不会基于这条外部评论擅自关 PR 或改写历史。

  7. added
    bugSomething isn't working
    协议接线改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签
    on Oct 18, 2026
  8. ranxianglei commented on Oct 26, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    验收清单补一条:acp_retrieve(来自 #4836 的实测报告)。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingp2协议接线改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions