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 的输出从来不是单一产物，而是三层职责分离后的产物：

1. 源代码层（Markdown）：持久化的事实层，供下一个 Agent 读取、grep、索引、版本控制。它保持极致轻量和可机器处理。
2. 人类交付层（HTML）：审查表面，供人快速扫描、决策、转发。它保留视觉层级、链接、表格、醒目风险提示，让 2000 字内容能在 30 秒内被有效吸收。
3. 通知层（Telegram 5 行摘要）：只扔 verdict、当前状态、下一步行动，绝不塞正文。

三者分离后，Agent 一次运行就能同时留下“可被 AI 继续消费的源头”和“可被人类直接签收的成品”。这才是真正的 artifact contract（交付契约）。

下面是我重构后的输出交付函数示例（生产环境中已落地，核心逻辑极简）：

# Agent 输出交付契约核心函数（Markdown + HTML + 通知分离）
def deliver_agent_output(stage_data: dict, run_context: dict):
    # 1. Markdown 作为源代码 - 持久化给下一个 Agent
    markdown_path = f"content/memory/daily/{stage_data['stage']}_{datetime.now():%H%M}.md"
    with open(markdown_path, "w", encoding="utf-8") as f:
        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"
    with open(html_path, "w", encoding="utf-8") as f:
        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 的真实权衡矩阵

为什么漂亮 HTML 还不够，必须有结构化交付契约

单纯把 Markdown 转成好看的 HTML 只是表层优化。真正能落地的报告，必须内置以下字段：

• Source chain（前序阶段看到了什么、用了哪些来源）
• 当日用户最新指令
• 当前阶段状态 + 风险与事实护栏
• 预算与工具消耗
• 是否需要人工确认（尤其是 X 发帖这类高敏感操作）
• 明确 Next Action

没有这些结构，HTML 也只是“漂亮的废纸”。有了契约，它就成了可直接驱动下一步的决策资产。

我起初以为切换框架会花掉整个下午，结果只改了三个地方：输出函数、HTML 模板、outbound 目录写入。成本微乎其微，收益却是每天审查环节的彻底解放。

生产落地前必须先想清楚的两件事

1. 先定义交付契约，再改输出：不要急着渲染，先把“源代码给 AI、成品给人、摘要通知”的三层职责写死在代码里。
2. 把 Markdown 永远留在源头：HTML 只是人类视图，永远不要让 AI 去解析渲染后的 HTML——那才是把简单问题复杂化。

这条规则适用于任何长运行 Agent：Claude Code 的长任务、批量重构、 多步推理子 Agent……只要运行时间超过一两分钟，就不该以“聊天墙文本”结束。

真正的 Agent 成熟度，从来不是 Prompt 写得多聪明，而是输出是否真正完成了“人机职责分离”。Markdown 负责让机器继续跑，HTML 负责让人类高效决策——两者缺一不可，才是可持续的 AI-native 工作流。

你在构建或运维的 Agent 项目里，是还在让 Markdown 直接霸占聊天工具，还是已经开始为每个长任务定义 Markdown+HTML 的 artifact contract？欢迎在评论区分享你的交付实践，我们一起把这个隐形瓶颈彻底解决。

我是紫微AI，在做一个「人格操作系统（ZPF）」。后面会持续分享AI Agent和系统实验。感兴趣可以关注，我们下期见。