AI Agent 输出格式的隐形瓶颈
Markdown 作为源代码够用，但人类审查表面为什么总崩溃？
在生产环境中，一个长运行的 AI Agent 每天执行十几轮 cron 任务，生成 2000 字的详细报告——扫描时间线、聚合关键信息、输出风险与下一步行动。内容完全正确，可当这一切被一股脑塞进 Telegram 时，你却发现自己根本读不下去：重要决策被埋在长墙文本里，上下文切换成本爆炸式上升，一天下来脑力直接见底。团队明明已经用了结构化 Prompt 和总结约束，却依然卡在“输出可读性”这个最不该卡的地方。
我起初也和大多数 Agent 开发者一样，认为 Markdown 就是最佳选择。它简单、diff 友好、token 消耗低、跨 Agent 传递方便，改输出格式纯属多此一举。后来我读到 Thariq 那篇《Using Claude Code: The Unreasonable Effectiveness of HTML》，又刷到 html-anything 这个仓库的标语“Markdown is the draft, HTML is what humans read”，才猛然醒悟：我们一直把 Markdown 当成了终点，却忘了它只是给 AI 读的源代码，而人类真正需要的是可直接消费的交付物。
生活里这就像程序员写完源码后，直接把 .py 文件发给产品经理审阅——代码逻辑没错，但对方根本没法高效理解意图。真正的交付物，永远是渲染后的、结构清晰的界面。
Markdown 与 HTML 的底层职责拆解
Agent 的输出从来不是单一产物，而是三层职责分离后的产物：
- 源代码层（Markdown）：持久化的事实层，供下一个 Agent 读取、grep、索引、版本控制。它保持极致轻量和可机器处理。
- 人类交付层（HTML）：审查表面，供人快速扫描、决策、转发。它保留视觉层级、链接、表格、醒目风险提示，让 2000 字内容能在 30 秒内被有效吸收。
- 通知层（Telegram 5 行摘要）：只扔 verdict、当前状态、下一步行动，绝不塞正文。
三者分离后，Agent 一次运行就能同时留下“可被 AI 继续消费的源头”和“可被人类直接签收的成品”。这才是真正的 artifact contract（交付契约）。
下面是我重构后的输出交付函数示例（生产环境中已落地，核心逻辑极简）：
# Agent 输出交付契约核心函数（Markdown + HTML + 通知分离）defdeliver_agent_output(stage_data:dict,run_context:dict):# 1. Markdown 作为源代码 - 持久化给下一个 Agentmarkdown_path=f"content/memory/daily/{stage_data['stage']}_{datetime.now():%H%M}.md"withopen(markdown_path,"w",encoding="utf-8")asf:f.write(stage_data["full_markdown"])# 包含完整链路、风险、决策依据# 2. HTML 作为人类审查表面 - 渲染后存入 outbound 目录html_content=render_to_html(stage_data,template="agent_report.html",# 包含 source chain、风险高亮、确认按钮等结构user_direction=run_context["today_direction"])html_path=f"gateway/outbound/{stage_data['stage']}.html"withopen(html_path,"w",encoding="utf-8")asf:f.write(html_content)# 3. Telegram 只发极简通知telegram_summary=f""" ✅{stage_data['stage']}完成 状态：{stage_data['verdict']}风险：{len(stage_data['risks'])}项 下一步：{stage_data['next_action']}查看完整报告：{html_path}"""send_telegram(telegram_summary)return{"markdown":markdown_path,"html":html_path}渲染开销实测仅 51ms（22.4KB Markdown 源文件，本地读取 0.016ms，Markdown-to-HTML 转换 50.8ms）。对动辄几分钟的 Agent 任务来说，这几乎是噪声级别。
Markdown-only vs Artifact Contract 的真实权衡矩阵
| 评估维度 | 传统 Markdown-only 输出（塞聊天工具） | 新 Artifact Contract（Markdown+HTML+通知） |
|---|---|---|
| 实测性能与架构参数 | 零额外渲染，token 极省 | 51ms 渲染开销，几乎无感知；持久化更清晰 |
| 长尾风险与潜在技术债 | 人类审查疲劳导致决策遗漏、重复劳动 | 源代码与交付物解耦，长生命周期 Agent 状态可追溯 |
| 开发者心智负担与上手门槛 | 每天盯着墙文本，脑力快速耗尽 | 阅读体验指数级提升，审查变成“签收”而非“苦读” |
为什么漂亮 HTML 还不够，必须有结构化交付契约
单纯把 Markdown 转成好看的 HTML 只是表层优化。真正能落地的报告，必须内置以下字段：
- Source chain（前序阶段看到了什么、用了哪些来源）
- 当日用户最新指令
- 当前阶段状态 + 风险与事实护栏
- 预算与工具消耗
- 是否需要人工确认（尤其是 X 发帖这类高敏感操作）
- 明确 Next Action
没有这些结构，HTML 也只是“漂亮的废纸”。有了契约，它就成了可直接驱动下一步的决策资产。
我起初以为切换框架会花掉整个下午，结果只改了三个地方：输出函数、HTML 模板、outbound 目录写入。成本微乎其微，收益却是每天审查环节的彻底解放。
生产落地前必须先想清楚的两件事
- 先定义交付契约，再改输出：不要急着渲染，先把“源代码给 AI、成品给人、摘要通知”的三层职责写死在代码里。
- 把 Markdown 永远留在源头：HTML 只是人类视图，永远不要让 AI 去解析渲染后的 HTML——那才是把简单问题复杂化。
这条规则适用于任何长运行 Agent：Claude Code 的长任务、批量重构、 多步推理子 Agent……只要运行时间超过一两分钟，就不该以“聊天墙文本”结束。
真正的 Agent 成熟度，从来不是 Prompt 写得多聪明，而是输出是否真正完成了“人机职责分离”。Markdown 负责让机器继续跑，HTML 负责让人类高效决策——两者缺一不可，才是可持续的 AI-native 工作流。
你在构建或运维的 Agent 项目里，是还在让 Markdown 直接霸占聊天工具，还是已经开始为每个长任务定义 Markdown+HTML 的 artifact contract？欢迎在评论区分享你的交付实践，我们一起把这个隐形瓶颈彻底解决。
我是紫微AI，在做一个「人格操作系统（ZPF）」。后面会持续分享AI Agent和系统实验。感兴趣可以关注，我们下期见。