我用 Coding Agent 干活时最烦的不是它写错代码而是它写对了我却不知道它写了什么。终端一屏一屏滚过的日志、git diff、测试输出像开闸的瀑布一样砸过来。任务跑完之后我脑子里往往只剩一个模糊的结论嗯它好像动了挺多文件但具体动了哪些、为什么动、有没有跑过验证得回终端往死里翻。这种活干了 80%人只消化了 30%的感觉就是标题里说的终端信息损耗。我试过各种办法让 Agent 精简输出、只打印关键行、把日志写到文件里再让我 tail。都不彻底。直到我换了个思路——别让 Agent 在终端里汇报了让它直接产出一份 HTML 报告。浏览器打开的那一刻整个世界都安静了。它不是把日志搬到网页里而是从一开始就把过程和结果分开终端留给过程和异常HTML 留给结论和依据。这篇就聊聊我是怎么做的踩过哪些坑以及怎么把你手头的 Coding Agent 也调教成这个习惯。1. 终端日志的信息损耗到底出在哪先得把问题说清楚不然你会觉得这只是个排版洁癖。信息损耗不是看起来乱而是切切实实地丢掉了关键信息让你的决策质量和速度都受影响。1.1 线性文本天生不适合人眼做结构化检索人眼扫长文本时找关键词靠的是视觉搜索不是逐行精读。终端输出是等宽字体、相近颜色没有字号和层级。当一个 Agent 执行一个复合任务——比如修掉这个 bug 顺便补个测试——它会连续输出几十条命令每条命令的回显又带几十行。500 行日志里可能只有 5 行是关键结论。问题在于这 5 行和噪声长得一模一样都是等宽字体都是同样的灰白色。你可能会说我可以用 CtrlF 搜啊。对但搜的前提是你知道该搜什么词。很多时候你根本不知道 Agent 把测试输出里的FAIL写成了Error还是failed也不知道它把修改的文件列表放在日志中间还是末尾。搜索变成了一场赌博。更麻烦的是这些日志是滚动消失的。终端缓冲区有限Windows 默认的 conhost 历史行数可能只有几千行深耕代码的 Agent 一跑就是几千行输出前面的内容早就被顶出去了。窗口一关整个任务执行过程就像没发生过一样。1.2 Agent 自己也在被长上下文反噬这点很多人没意识到。当 Coding Agent 在对话里输出大段大段的执行日志时这些内容会进入它的上下文窗口。即便你的模型窗口很大但占用的 token 越多留给后续推理的空间就越少越往后越容易忘事或答非所问。我见过一个真实案例让 Agent 连续处理三个文件的重构它每处理完一个文件就把完整 diff 贴在对话里。等处理到第三个文件时它开始重复第一个文件的修改逻辑明显是被早期的大段输出干扰了。把结论和过程写进 HTML 文件Agent 就只需要在回复里引用路径加摘要上下文压力立刻降下来。这是把寄存在对话里变成落盘在文件里对人、对模型、对后续审计都有好处。1.3 信息损耗的三个典型场景我把平时的损耗归纳成三个高频场景你可以对照自己有没有经历过场景现状损耗点让 Agent 重构一个模块终端刷了 200 行编译输出你根本不知道改了哪几个文件更不知道每个文件改了什么让 Agent 修 bug 并跑测试测试结果混在日志中间事后想翻却翻不到因为被命令回显和警告信息淹没了隔天回看 Agent 做了什么终端早关了什么都没留下想复盘只能靠记忆或者重新跑一遍时间成本翻倍这三种情况的共同点Agent 花费了算力和时间产出的信息在抵达你眼睛之前就已经蒸发了。你要么没看见要么看见了一部分要么看见了但没记录。信息损耗的实质就是这条从 Agent 到你之间的通道太窄、太乱、太短命。2. HTML 报告把过程日志变成结果档案理解了问题之后方案其实很直接如果终端这条通道太窄那就换一条宽通道如果终端里的信息太短命那就让它落地成文件。HTML 报告就是我为这个问题选的新通道。2.1 为什么选 HTML 而不是 Markdown很多人第一反应是那让 Agent 输出 Markdown 不就完了。我自己也试过但 Markdown 在终端里依然是纯文本依然是一坨等宽字体损耗问题原封不动。除非你额外装一个渲染插件否则写 Markdown 只是给自己一个心理安慰。HTML 有四个不可替代的优势零依赖渲染任何操作系统、任何浏览器双击就能打开一个排版良好的页面不需要装任何软件。自带语义结构标题、表格、列表、强调、锚点浏览器天然会把这些视觉层级呈现出来人眼扫过去就能快速定位。可内嵌样式和脚本一套 CSS 就能做出专业看板的效果还能内嵌图表库画测试覆盖率、性能对比图。可保存、可归档、可被程序二次解析HTML 文件是纯文本文件可以被脚本读取、索引、汇总Markdown 也可以但 HTML 的表达能力上限高得多。一句话Markdown 是给还想保持轻量的人用的HTML 是给真想解决信息损耗的人用的。既然都让 Agent 写文档了为什么不直接上最完整的形式2.2 报告里应该包含哪几个区块一份好的 Agent 工作报告不是把日志黏贴进去而是重新组织信息。我实践下来下面六个区块基本覆盖了日常开发协作的全部需求任务概况这次任务的目标是什么、最终状态是完成/部分完成/失败、用了多长时间。变更文件清单改了哪些文件每个文件的改动类型新增/修改/删除影响范围。关键实现说明每个文件/模块为什么这么改有没有值得注意的设计取舍。这是 Agent 比人更擅长写的地方因为它记得每次操作的上下文。测试与验证跑了哪些测试命令、通过/失败/跳过多少、关键输出是什么。最好把命令和摘要都贴上。风险与遗留已知问题、未覆盖的边界情况、下一步建议。这一块是给代码审查和后续排期的抓手。复现与启动方式如果这是一个可以运行的改动贴上启动命令如果是要验证的 bug 修复贴上复现步骤。有了这六块一份报告的信息量已经超过一个小时的终端阅读。而且因为结构固定Agent 每次都能稳定输出你可以形成肌肉记忆式的阅读习惯。2.3 一份可以直接抄的模板下面是经过多轮打磨后的一个精简模板我把它放在项目目录下并让 Agent 直接参考这个结构生成报告。你可以直接复制到你的项目里或者让 Agent 参照它写一个更长的版本。!doctype html html langzh-cn head meta charsetutf-8 titleCoding Agent 工作报告 - {{任务标题}}/title style body { font-family: -apple-system, PingFang SC, Microsoft YaHei, sans-serif; max-width: 960px; margin: 32px auto; padding: 0 16px; color: #1a1a1a; line-height: 1.7; } h1 { border-bottom: 2px solid #333; padding-bottom: 8px; } h2 { margin-top: 32px; color: #2c3e50; } .status-done { color: #1a7f37; font-weight: bold; } .status-fail { color: #cf222e; font-weight: bold; } table { border-collapse: collapse; width: 100%; margin: 16px 0; } th, td { border: 1px solid #d0d7de; padding: 8px 12px; text-align: left; } th { background: #f6f8fa; } code { background: #f6f8fa; padding: 2px 4px; border-radius: 4px; } pre { background: #f6f8fa; padding: 12px; border-radius: 6px; overflow-x: auto; } .warning { background: #fff8c5; border-left: 4px solid #e3b341; padding: 8px 12px; margin: 16px 0; } /style /head body h1任务报告{{任务标题}}/h1 p生成时间{{时间}}/p h21. 任务概况/h2 p目标{{一句话描述}}/p p状态span classstatus-{{状态}}{{状态}}/span/p h22. 变更文件清单/h2 table trth文件路径/thth改动类型/thth说明/th/tr trtdsrc/main.py/tdtd修改/tdtd修复了空指针/td/tr /table h23. 关键实现说明/h2 p{{具体设计取舍与原因}}/p h24. 测试与验证/h2 pre{{测试命令与输出摘要}}/pre h25. 风险与遗留/h2 ul li{{风险项}}/li /ul h26. 复现与启动方式/h2 pre{{命令}}/pre /body /html模板里的双大括号就是占位符Agent 拿到后会替换成真实内容。关键点我已经写死在 HTML 结构里了meta charsetutf-8保证中文不乱码内联 CSS 保证没有外部依赖表格和列表让信息层级一目了然。3. 实战接入让 Agent 养成先出报告再收工的习惯方案再好不落地就是空谈。让 Coding Agent 稳定地产出 HTML 报告靠的是三层约束系统提示词、项目约定文件、工作流。缺一层都容易出现偶尔生成、经常忘的毛病。3.1 在系统提示词里加一段汇报规范如果你用的是自带系统提示词或自定义指令的 Agent把下面这段直接加进去【汇报规范】 每次任务完成后必须执行以下步骤 1. 在 .reports/ 目录下生成一份 HTML 报告文件名格式report-YYYYMMDD-HHMM.html。 2. 报告结构按项目内 REPORT_TEMPLATE.html 的六个区块来写。 3. 不要把报告全文复制到聊天回复里只给报告的相对路径和不超过三行的结论摘要。 4. 如果任务失败报告中必须写明失败原因、已尝试的方案、未解决的问题。这段提示词解决三个问题目录统一、命名规范、回复精简。没有这段提示词Agent 会把报告写在根目录、用report.html这种通用名而且会在聊天里再复述一遍报告全文——你只是把终端损耗换成了聊天损耗。3.2 在项目约定文件里固化报告要求很多 Coding Agent 会自动读取项目根目录下的约定文件比如AGENTS.md、CLAUDE.md、RULES.md作为每次任务的上下文。这是比系统提示词更稳定的约束因为它是跟着仓库走的换人、换环境、换 Agent 都还在。在这个文件里加上## 工作汇报要求 - 所有任务完成后在 .reports/ 目录下生成 HTML 报告。 - 报告必须包含任务概况、变更文件清单、关键实现说明、测试与验证、风险与遗留、复现与启动方式。 - 报告禁止使用外部 CSS/JS全部内联。 - 最后一条回复只给报告路径和摘要。写进仓库还有一个好处当 Agent 需要查看历史报告做后续任务时它能直接从.reports/目录里找到前因后果而不是翻早被冲掉的对话记录。这等于给 Agent 也建立了一个长期记忆库。3.3 查看链路本地打开与内置服务预览报告生成后怎么打开最顺手以下是分平台的方式macOSopen .reports/report-20250410-1530.htmlWindowsstart .reports\\report-20250410-1530.htmlLinux 桌面xdg-open .reports/report-20250410-1530.html你也可以让 Agent 启动一个临时的静态服务器这样在浏览器里访问http://localhost:8000/report-...会更接近真实部署环境而且能直接处理报告里的相对链接。命令是python3 -m http.server 8000 --directory .reports我通常会在提示词里允许 Agent 自行调用open/start命令但要注意权限控制——让 Agent 自动打开浏览器可能会触发安全提醒所以大多数时候我更推荐Agent 给出路径我自己点一下。反正双击一个文件也不费事信息损耗比终端小太多了。3.4 让最后一条回复只承载摘要与路径这一步经常被忽略但它才是压死信息损耗的最后一根稻草。很多人设置完报告生成后Agent 依然会在聊天里原样输出大段分析报告变成了摆设。我在提示词里明确要求最后一条回复必须压缩到三行以内。格式固定为任务完成。报告.reports/report-20250410-1530.html 摘要修复了登录接口的空指针更新了 3 个文件新增测试 5 个全部通过。 遗留token 刷新逻辑还有边界情况未覆盖见报告第 5 节。三行信息量刚好知道结果、知道下一步去哪看细节、知道还有什么坑。剩下所有细节都在 HTML 里想深挖就打开浏览器不想深挖就算了。这比在终端里翻十分钟日志不知道强到哪里去了。4. 踩坑实录HTML 报告落地时容易翻车的五个细节方案跑起来之后我踩了不少坑。有些坑是环境导致的有些是 Agent 的自由发挥导致的。把它们写出来你落地的时候能少走弯路。4.1 报告文件被反复覆盖历史版本全没了最早我让 Agent 生成report.html这个固定文件名。结果每次任务结束它都把前一份报告覆盖掉。想回看昨天的改动记录打不开——文件已经是今天的了。解决方案用时间戳命名report-YYYYMMDD-HHMM.html。同时我还会在提示词里加一句保留最近 20 份报告不要主动删除旧的避免 Agent 出于清理的目的顺手把历史报告删了。顺便说一句有些 Agent 会自作主张地只保留一份最新报告因为它觉得这样更干净。你必须在提示词里明确告诉它报告是历史记录不是临时文件。4.2 外部资源路径失效与内联方案最开始我图省事让报告直接引用项目里的style.css或 CDN 上的 Chart.js。结果发现两个问题第一Agent 生成的 HTML 放在.reports/目录相对路径../assets/style.css有时候对、有时候不对取决于它把资源放在了哪里第二一旦断网或换环境CDN 加载不出来整份报告变成光秃秃的 HTML。解决方案在报告规范里强制所有 CSS 和 JS 必须内联进 HTML 文件。也就是style标签直接嵌在head里图表库要么用内联 SVG要么用本地文件绝不用外部 CDN。代价是报告文件体积大一点但换来的是双击就能看、永远不失灵的可靠性。4.3 charset 未声明导致中文乱码这个坑很隐蔽。有些 Agent 生成的 HTML 省略了meta charsetutf-8在默认是 UTF-8 的现代浏览器里没事但在 Windows 中文版默认编码不是 UTF-8 的情况下浏览器会按本地代码页解析中文全部变成乱码。解决方案模板里必须在head第一行写上meta charsetutf-8。我还见过更绝的情况——Agent 把 meta 写在标题后面浏览器在解析到 meta 之前已经按默认编码渲染了一部分内容导致前几个字正常、后面乱码。顺序都不能错。4.4 报告目录污染版本库Agent 会在项目根目录随手生成report.html然后git status里就多了一堆文件。如果不小心提交上去等于把每份开发中间产物都塞进了仓库既占空间又让 code review 变得混乱。解决方案约定统一目录.reports/并在.gitignore里加上.reports/同时在项目约定文件里写明报告只放在 .reports/不准在项目根目录创建任何新的 HTML 文件。这样既能保留本地报告又不会污染提交。4.5 外部脚本的安全与可用性边界这一点容易被忽视。如果 Agent 从网上找一个图表库的 CDN 地址或者在内联脚本里嵌入一些它自己想象的交互代码这份报告作为本地文件打开时还好但如果你把报告发给别人对方浏览器可能会执行这些脚本存在潜在的安全风险。解决方案在报告规范里明确不准使用任何外部脚本不需要交互逻辑静态内容即可。如果确实需要图表用内联 SVG 画不引入 JavaScript。这样报告就是一个纯粹的静态文档没有可执行行为任何环境下打开都是安全的。5. 进阶玩法把报告做成任务驾驶舱当基础的报告流程稳定之后你会发现 HTML 报告的价值远不止替代终端。它完全可以变成一个信息密度更高的任务驾驶舱——把多个维度、多个任务的数据都纳进来让你一眼掌握全局。5.1 用图表直观呈现测试与覆盖率在报告里画条形图或柱状图听起来很复杂实际上用内联 SVG 就能实现。比如让 Agent 读取测试结果后在报告里输出下面的 SVG 条形图svg width300 height120 viewBox0 0 300 120 rect x10 y70 width80 height30 fill#1a7f37/rect text x15 y94 font-size12通过 95/text rect x110 y90 width10 height10 fill#cf222e/rect text x130 y94 font-size12失败 2/text /svg这种内联 SVG 不需要任何外部库打开即渲染还能被屏幕阅读器识别。Agent 在生成报告前只要读取测试输出里的数字就能算出比例把很枯燥的95 passed, 2 failed变成一眼扫过去的图形。5.2 内嵌 diff 与文件变更摘要报告里最热门的区块是变更文件清单。别只写一个文件名列表让 Agent 把每个文件的git diff --stat摘要也放进去pre src/auth.py | 12 ----- tests/test_auth.py | 8 2 files changed, 14 insertions(), 6 deletions(-) /pre有了这个你不用打开 IDE 就能评估改动范围。如果 Agent 给出了具体的说明我更建议它写清楚为什么改而不是改了什么因为在没有上下文时为什么才是代码审查的第一追问。5.3 多任务聚合页与跨天存档当你的 Agent 任务变多之后单份 HTML 报告也会有信息碎片化的问题。这时候可以进阶到汇总页思路每完成一个任务Agent 生成的报告都链接到一个index.html聚合页。聚合页里按日期列出所有已完成任务、各自的结论摘要和报告链接。你只需要打开一个页面就能回顾这周 Agent 做的所有事。这其实形成了一个小型知识库每一次任务的决策、改动、测试、遗留问题都固化在文件里。三天后、三个月后想复盘直接打开.reports/index.html比翻任何聊天记录都靠谱。这个汇总页也可以让 Agent 顺手维护只要在提示词里说每次生成新报告后更新 index.html即可成本几乎为零。用 HTML 报告替代终端汇报之后我自己最大的变化是收到 Agent 的回复时第一反应不再是赶紧看聊天里的输出而是先点开报告路径先看结论再看变更最后才决定要不要打开某个文件深挖。终端我当然还会用但它退回到了实时观察窗口的位置不再是信息归档的终点。最后分享一个我最近才意识到的小技巧报告模板本身也要版本化。我最初把模板放在项目外的某个角落后来统一改为放在项目根目录下REPORT_TEMPLATE.html让 Agent 每次生成报告前都先读一遍模板。这样做的好处是模板里一旦加了新区块或新规范后续所有报告都会自动跟着变化不需要逐个提醒 Agent。这个习惯一旦养成你会发现 Coding Agent 产出的不只是一堆代码改动而是一份份可以回溯、分享、审计的完整工作档案。