1. 为什么终端输出正在拖累你的 Coding Agent 体验用 Claude Code、Codex 这类 Coding Agent 干活的人大概率都经历过同一个场景Agent 在终端里噼里啪啦跑了几十轮工具调用最后甩给你一大坨纯文本。里面有 diff、有测试结果、有文件树、有依赖分析、有性能数据全挤在一个黑底白字的滚动缓冲区里。你想找一句关键结论得往上翻十几屏你想对比两个方案的差异眼睛在两段文本之间来回跳你想把结果发给同事看只能截图或者复制一大段没有格式的文字。这就是我说的信息损耗。Agent 明明已经把所有信息都产出了但因为终端这个载体的表达能力太弱大量结构化信息在呈现这一环被压缩、被淹没、被误读。终端天生只擅长线性文本它不擅长表格、不擅长层级、不擅长颜色语义、不擅长折叠展开。而 Coding Agent 的输出恰恰是高度结构化的——它天然适合用 HTML 来承载。所以这个项目的核心思路很直接让 Coding Agent 把汇报结果写成 HTML 报告而不是往终端里吐纯文本。HTML 能做的事情终端做不了用表格对齐参数对比用颜色区分通过和失败用折叠块收纳长日志用锚点做目录跳转用details标签把细节藏起来只留结论。一份好的 HTML 报告信息密度可以比终端文本高好几倍而阅读成本反而更低。这篇文章适合三类人看。第一类是已经在用 Claude Code、Codex 做日常开发的工程师想让 Agent 的输出更可读第二类是正在搭多智能体协作流程的人需要一套统一的汇报规范第三类是对 Coding Agent 工作流感兴趣、想了解怎么把 Agent 产出产品化的读者。我会从设计思路讲到具体实现包括怎么通过 CLAUDE.md 约束 Agent 的输出格式、HTML 报告该包含哪些模块、怎么打包多个报告、以及我在实操中踩过的坑。2. 整体设计思路把汇报当成一个独立交付物2.1 终端汇报 vs HTML 汇报的本质差异先想清楚一件事为什么终端汇报会损耗信息不是因为终端不好而是因为终端的设计目标是实时交互流不是结构化文档。你在终端里看到的每一行都是按时间顺序追加的它没有章节的概念没有表格的概念没有折叠的概念。当 Agent 输出 500 行内容时这 500 行是平铺的读者必须自己在大脑里重建结构。HTML 汇报则反过来。它的设计目标就是结构化文档天然支持层级、表格、样式、交互。同样 500 行信息用 HTML 组织后读者可以先看目录再跳到关心的章节表格一眼看清对比失败项用红色标出来长日志折叠起来不占地方。信息量没变但认知负荷大幅下降。我做过一个粗略的对比。同一个 Agent 任务让它分别用终端文本和 HTML 报告汇报然后找同事阅读并复述关键结论。终端版本平均要读 3 分钟才能说清重点HTML 版本 40 秒就够了。差距主要来自三点一是 HTML 有视觉层级重点自动凸显二是表格让对比变成扫一眼而不是逐行读三是折叠让读者可以按需深入不必被细节淹没。2.2 为什么选 HTML 而不是 Markdown有人会问Markdown 也能结构化为什么不直接让 Agent 输出 Markdown这个问题我认真想过结论是 Markdown 适合写给人看的文档HTML 适合给人快速消费的报告两者定位不同。Markdown 的短板在于表现力。它没有原生表格样式只能靠渲染器没有颜色语义没有折叠没有锚点跳转的精细控制多个报告之间也没法方便地互相引用。而 HTML 是浏览器原生支持的你双击就能打开不需要任何渲染工具样式、交互、跳转全都自带。对于Agent 跑完任务立刻生成一份可读报告这个场景HTML 的即时可用性完胜。还有一个现实原因Coding Agent 本身对 HTML 的生成能力很强。Claude Code 和 Codex 都能一次性写出结构完整、样式内联的 HTML 文件因为它们见过海量的 HTML 代码。你只要在 CLAUDE.md 里把规范写清楚它就能稳定产出。相比之下让 Agent 生成一个需要特定渲染器才能看的格式反而增加了环境依赖。2.3 核心设计原则自包含、可归档、可对比我在设计这套汇报规范时定了三条硬性原则后面所有细节都围绕它们展开。第一自包含。每份 HTML 报告必须是单文件CSS 内联不依赖任何外部资源不依赖网络。这样你可以把它丢进任何目录、发给任何人、归档到任何地方双击就能看。我见过有人让 Agent 生成引用 CDN 的 HTML结果离线环境打不开或者 CDN 挂了样式全丢这种坑没必要踩。第二可归档。报告要按任务和时间命名放在固定目录下形成可检索的历史记录。Agent 每次跑完任务报告落到reports/目录文件名带上时间戳和任务标识。这样一周后你想回顾上周那个性能优化到底改了什么直接翻目录就行不用去翻终端历史。第三可对比。同一类任务的报告结构要一致这样你可以把两次报告并排看快速发现差异。比如 benchmark 报告每次都包含环境信息、测试项、结果表格、结论四个固定模块那么两次报告一对比哪个指标退化了、哪个用例变慢了一目了然。提示这三条原则里自包含最容易被忽略但它是后面所有便利性的基础。一旦报告依赖外部资源归档和分享就会出问题。3. 核心细节解析一份合格的 Agent HTML 报告长什么样3.1 报告骨架五个必备模块经过多次迭代我把 Agent HTML 报告的骨架固定成五个模块。不是每个任务都需要全部但结构上留好位置Agent 按需填充。第一个模块是任务摘要。放在最顶部用一两句话说明这次任务干了什么、结论是什么。这是给没时间细看的人准备的扫一眼就知道结果。摘要里要包含最关键的数字比如测试通过率 98%比上次提升 3 个百分点。第二个模块是环境与上下文。记录这次任务运行的环境Agent 版本、模型、工作目录、Git 分支、依赖版本。这个模块的价值在于可复现——别人看到你的报告能知道是在什么条件下跑出来的。第三个模块是核心结果。这是报告的主体通常用表格呈现。比如代码审查报告表格列是文件、问题类型、严重程度、行号、建议benchmark 报告表格列是测试项、耗时、内存、对比基线、变化。第四个模块是详细日志或证据。把原始输出、diff、堆栈放在这里用details折叠起来。默认收起需要时展开。这样既保留了完整信息又不干扰主阅读流。第五个模块是结论与后续建议。Agent 基于结果给出的判断和下一步动作。这部分要克制不要写空话只写有信息量的建议。3.2 样式规范内联 CSS 的最小集合既然是自包含单文件CSS 必须内联在style标签里。但不需要写很多一套最小样式集就够用。我通常让 Agent 包含这几类样式基础排版字体、行高、最大宽度、居中。用系统字体栈不引外部字体。表格样式边框、斑马纹、表头加粗、单元格内边距。表格是报告的核心样式要清晰。语义颜色成功用绿色、警告用黄色、失败用红色、信息用蓝色。用 CSS 类实现比如.pass、.fail、.warn。折叠样式details和summary的基础美化让折叠块看起来可点击。代码块样式等宽字体、浅色背景、横向滚动。这套样式大概 60 到 100 行 CSSAgent 一次就能写对。关键是要在 CLAUDE.md 里明确CSS 必须内联不得引用外部资源否则 Agent 有时候会偷懒写link标签。3.3 数据呈现表格优先颜色辅助报告里最忌讳的是大段纯文本描述数据。凡是能表格化的一律表格化。我总结了几条经验对比类数据用表格列是维度、方案 A、方案 B、差异。比如两个依赖版本的对比两个实现的性能对比。列表类数据用表格列是序号、项目、状态、备注。比如检查项清单一眼看清哪些通过哪些没过。时间序列数据用表格加简单条形不要上图表库。图表库会引入外部依赖违背自包含原则。用 CSS 画个简单的条形一个 div 设宽度和背景色就够表达趋势了。颜色只用来表达语义不要用来装饰。绿色通过/改善红色失败/退化黄色警告/需关注灰色中性信息。颜色滥用会让报告变得花哨且难读。3.4 命名与归档让报告可检索报告文件名我建议用这个格式YYYYMMDD-HHMMSS-任务标识.html。比如20250115-143022-benchmark-api.html。时间戳在前保证目录按时间排序任务标识在后方便 grep。归档目录结构建议按任务类型分reports/ benchmark/ code-review/ refactor/ debug/Agent 每次生成报告前先确定任务类型落到对应子目录。这样积累一段时间后你就有了一套按类型组织的历史报告库回顾和对比都很方便。注意不要让 Agent 把报告写到临时目录或系统临时文件夹那些地方会被清理。固定写到项目内的reports/目录并考虑是否加入.gitignore。如果报告包含敏感信息务必不要提交到版本库。4. 实操过程从 CLAUDE.md 约束到报告生成4.1 在 CLAUDE.md 里写死汇报规范Claude Code 和 Codex 都支持通过项目根目录的CLAUDE.md或对应配置文件来约束 Agent 行为。这是整套方案的关键——你不能指望每次口头告诉 Agent给我生成 HTML 报告必须把规范写进配置文件让它成为默认行为。我在 CLAUDE.md 里通常写这么一段## 汇报规范 当完成一个需要多步骤执行的任务后必须生成一份 HTML 报告 而不是仅在终端输出纯文本总结。 报告要求 1. 单文件 HTMLCSS 内联在 style 标签中不得引用任何外部资源 2. 必须包含五个模块任务摘要、环境与上下文、核心结果、详细日志、结论与建议 3. 核心结果必须用表格呈现不得用大段纯文本 4. 详细日志用 details 折叠默认收起 5. 使用语义颜色类.pass .fail .warn .info 6. 报告保存到 reports/任务类型/ 目录文件名格式 YYYYMMDD-HHMMSS-标识.html 7. 生成后在终端只输出报告路径和一句话摘要不要重复报告内容这段规范写清楚后Agent 每次完成任务都会自动生成 HTML 报告终端只留一行路径。信息损耗从源头就降下来了。4.2 让 Agent 生成报告的具体提示词配置文件定的是默认行为但具体任务里你还需要给 Agent 明确的报告要求。我常用的提示词模板是这样的完成上述任务后生成一份 HTML 报告包含 - 任务摘要一句话说明做了什么、结论是什么 - 环境信息工作目录、Git 分支、相关依赖版本 - 结果表格列出所有检查项/测试项包含状态和关键指标 - 详细证据把原始输出和 diff 折叠在 details 里 - 结论建议基于结果给出下一步动作 报告保存到 reports/ 目录文件名带时间戳。这个模板的好处是把五个模块明确列出来Agent 不会漏。实测下来Claude Code 和 Codex 对这个模板的遵循度都很高生成的 HTML 结构完整、样式正确。4.3 一个真实的报告生成案例我拿一个实际的代码审查任务举例。任务是让 Agent 审查一个 Python 模块找出潜在问题。Agent 跑完后生成的 HTML 报告大致是这样的结构顶部是任务摘要审查data_processor.py发现 7 个问题其中 2 个高危、3 个中等、2 个低危。环境模块记录了 Python 版本、依赖版本、审查时间。核心结果是一个表格列是行号、问题类型、严重程度、描述、建议。7 行数据高危用红色标出中等用黄色低危用灰色。详细证据折叠块里放了完整的文件内容和 Agent 的分析过程。结论模块给出建议优先修复第 45 行的空指针风险和第 78 行的资源泄漏其余问题可在下次重构时处理。这份报告在浏览器里打开30 秒就能看完重点需要细节时展开折叠块。如果同样的内容用终端文本输出至少 200 行读起来累得多。4.4 打包多个报告做一个索引页当报告积累多了单个文件翻起来也麻烦。这时候可以让 Agent 生成一个索引页index.html列出所有报告按时间倒序带链接和一句话摘要。索引页同样自包含点击链接跳到对应报告。索引页的生成可以做成一个脚本扫描reports/目录提取每个报告的标题和摘要生成 HTML。也可以让 Agent 每次生成报告后顺手更新索引。我倾向于用脚本因为更稳定不依赖 Agent 每次记得更新。脚本逻辑很简单遍历目录读每个 HTML 的title和摘要区生成一个列表页。用 Python 写大概 30 行。这样你打开reports/index.html就能看到所有历史报告的入口。4.5 参数计算与选择报告大小与折叠粒度这里有个容易被忽略的细节报告不能太大。如果 Agent 把整个代码库的内容都塞进报告文件可能几 MB浏览器打开卡顿。我的经验是单份报告控制在 500KB 以内超过就要考虑拆分或精简。折叠粒度也要控制。不要把每个小细节都单独折叠那样折叠块太多反而乱。我的做法是按证据类型折叠比如完整 diff一个块、原始日志一个块、测试输出一个块。每个块内部可以很长但块的数量控制在 5 个以内。如果报告确实需要包含大量数据比如 benchmark 跑了几百个用例那就把明细数据单独存成 CSV 或 JSONHTML 里只放汇总表格和关键用例明细用链接引用。这样报告保持轻量需要深挖时再去看原始数据。5. 常见问题与排查技巧实录5.1 Agent 不生成 HTML 怎么办最常见的问题是 Agent 忘了生成 HTML还是往终端吐文本。原因通常是 CLAUDE.md 里的规范不够强或者任务提示词里没提。解决办法有两个一是把规范写得更硬用必须不得这种词二是在任务提示词末尾再强调一次生成 HTML 报告。如果还是不行检查一下 Agent 是否读到了 CLAUDE.md。有些情况下 Agent 的工作目录不对读不到配置文件。确认工作目录是项目根目录且 CLAUDE.md 在根目录下。5.2 生成的 HTML 样式错乱样式错乱通常是因为 Agent 引用了外部 CSS或者 CSS 写得不完整。排查方法是打开 HTML 源码看head里有没有link标签。如果有说明违反了自包含原则需要在 CLAUDE.md 里再强调。另一种情况是 CSS 类名和 HTML 里的类名对不上。比如 CSS 里定义了.pass但 HTML 里写的是.success。这种问题让 Agent 自己检查一遍就能发现或者在提示词里明确类名清单。5.3 报告文件太大打不开前面提过报告超过 500KB 就要警惕。如果打不开先看文件大小。太大的话检查是不是把整个代码库或完整日志塞进去了。解决办法是精简只放关键证据明细数据外置。还有一个原因是 Agent 生成了大量重复的样式或脚本。让它把 CSS 合并去掉冗余。5.4 多个报告之间无法对比如果报告结构不一致对比就无从谈起。解决办法是在 CLAUDE.md 里把五个模块的顺序和命名固定死所有报告都按这个结构生成。这样两次报告并排看模块对模块表格对表格差异一目了然。5.5 常见问题速查表问题现象可能原因排查方法解决措施Agent 不生成 HTML规范未写死或提示词未提检查 CLAUDE.md 和任务提示词强化规范用词任务末尾重申样式错乱引用外部 CSS 或类名不匹配查看 HTML 源码 head 部分强调内联明确类名清单文件太大塞入过多原始数据查看文件大小精简证据明细外置报告无法对比结构不统一对比两份报告的模块固定五模块结构折叠块太多折叠粒度过细数折叠块数量按证据类型折叠控制在 5 个内报告丢失写到临时目录检查保存路径固定写到 reports/ 目录5.6 独家避坑技巧第一个技巧让 Agent 在报告里加一个生成时间和Agent 版本。这两个信息在排查问题时非常有用。有一次我发现某份报告的数据不对一看生成时间是 Agent 版本升级前跑的换了版本后结果就正常了。第二个技巧报告里的表格加一列对比基线。这样每次报告都能看出相对上次的变化而不是孤立的一个数字。比如 benchmark 报告耗时 120ms 本身没意义但比基线快 15%就有意义了。第三个技巧用details的open属性控制默认展开。关键证据默认展开次要证据默认收起。这样读者不用点开就能看到最重要的细节。第四个技巧报告里不要放绝对路径。绝对路径包含你的用户名和目录结构分享出去既泄露信息又不可复现。让 Agent 用相对路径。注意如果报告要提交到版本库或分享给外部务必检查是否包含敏感信息比如 API 密钥、内部地址、个人路径。让 Agent 在生成报告前做一次脱敏检查。6. 把汇报规范沉淀成团队资产这套东西用久了最大的价值不是单份报告而是规范本身。当团队里每个人都用同一套 CLAUDE.md 汇报规范Agent 产出的报告就具有一致性可以互相阅读、互相引用、互相归档。新人加入时看几份历史报告就能理解项目在做什么、怎么做的。我建议把汇报规范单独抽成一个文件比如docs/report-spec.md然后在 CLAUDE.md 里引用它。这样规范可以独立演进不用每次都改 CLAUDE.md。规范里写清楚五个模块、样式要求、命名规则、归档路径任何人拿到都能复现。另外可以准备几个报告模板放在templates/目录下。Agent 生成报告时先读模板再填充内容这样结构更稳定。模板不用太复杂一个空骨架加注释就够。最后分享一个我自己的习惯每周花十分钟翻一遍reports/目录看看这周 Agent 都干了什么、结论是什么。这个动作帮我发现了不少被忽略的问题也让我对项目进展有了更清晰的把握。终端里的信息会随滚动消失但归档的 HTML 报告会一直留着这就是把汇报当交付物的意义。