# Agent Note: 可读的 XML 工具输出

Status: implemented

[English](2026-07-24-readable-xml-tool-output.md) | 中文

## 问题

面向模型的上下文和工具结果文本可能呈现面向传输的 XML 包装，而不是人们真正需要的信息。上下文生产方不声明呈现意图，而对于回放时拿不到工具定义的调用，仍需要一个保守的回退方案，并且该方案不得重新解释普通文字或不完整的标记。

## 决策

read 工具声明一个通用的完成结果呈现：去除自身的 `<path>`、`<type>` 和 `<content>` 包装，同时保留带行号的内容和尾部信息。这一由工具自身持有的投影一致地作用于所有消费工具呈现意图的 UI。

只有当完整文本恰为一个受支持的 XML 文档时，TUI 才把上下文消息或工具定义不可用的工具结果按 XML 解析。TUI 将元素名和属性渲染为缩进树，保留上下文的来源标签；对于每个工具结果，分别按折叠行数预算限制各顶层子元素的行数和顶层子元素数量；对于格式错误的 XML、混合文本、XML 声明、处理指令、doctype 和注释，则保留原始文本。除非已知工具声明了自己的结果呈现器，否则其原始 XML 仍按字面显示。这一 XML 回退机制仅限 TUI。

## 曾考虑的替代方案

**用正则表达式剥除类 XML 标签。** 已否决：嵌套元素、属性、实体和格式错误的输入都需要真正的解析器；部分转换会让本就有歧义的输出更难检查。

**解析所有通用结果。** 已否决：已知工具拥有自己的呈现契约，静默重新解释它们的字面 XML 会推翻这一决定。

**只显示原始 XML。** 已否决：为模型消费而优化的包装会给终端增加噪音，对文件系统读取和嵌套很深的结构化结果尤其如此。

## 后果

文件系统读取在 TUI 卡片中变得更短，而规范的面向模型内容保持不变。完整的 XML 上下文消息（包括工作区指令提醒）变成可读的树；未知的完整 XML 结果变成可导航的树，折叠时也保留每个子元素的上下文。TUI 新增一个严格 SAX 解析器依赖，并有意不支持那些可能在保守树视图之外隐藏或变换输入的 XML 特性（未定义实体、DOCTYPE、注释、处理指令）。预定义实体和字符引用会被展开，因此解析出的文本和属性值在解析后会为终端输出重新转义：字符引用可能产生对原始源文本转义时从未见过的控制字符。其他 UI 展示原始的通用内容。