如果你每天都要跟 Claude、GPT 这类大模型打交道大概率已经习惯了写 Markdown。写提示词、整理知识库、维护 README几乎默认选 Markdown。轻量、易读、版本控制友好这些优点让 Markdown 看起来是“AI 时代必备技能”。但最近一个关于 Anthropic 工程师工作方式讨论正在把这些默认值撬开一角他们与 AI 协作时开始弃用 Markdown改用 HTML。很多人第一反应是这不是倒退吗HTML 那么冗长到处是尖括号写起来不仅啰嗦阅读体验也远不如 Markdown 清爽。这恰恰是问题的切入点。当文档唯一的读者是人类时Markdown 的简洁是极大的优点但当文档还要同时被 AI 模型解析、切分、检索、提炼时沟通效率的天平会悄然变化。这篇文章会从工程视角拆解这个选择背后的逻辑讲清楚三件事第一Markdown 在复杂 AI 工作流里到底卡在哪里第二HTML 为什么在某些场景下比 Markdown 更适合当 AI 的输入格式第三如果你想在项目里尝试这个思路该怎么做、有哪些坑。读完你会得到一个判断工具而不是一个“非黑即白”的结论。1. 这篇文章真正要解决的问题先说一个让你有代入感的场景。你负责的公司知识库用的是 Markdown里面有产品说明、接口文档、运营规范总量几百篇。你把这些文档喂给 RAG 应用希望能得到一个内部问答机器人。结果上线后你发现机器人经常答非所问尤其是涉及表格、嵌套列表、多级标题的时候。再举一个场景。你在开发一个 Agent让大模型根据一份需求文档生成测试用例。为了追求准确你在 System Prompt 里把整份 Markdown 文档原样塞进去。模型确实读到了内容但生成的测试用例漏掉了表格中最后三行数据而且对字段约束的理解完全错误。你反复调整提示词效果依然不稳定。这些问题的根源往往不是模型不够聪明而是你交给模型的文档格式在结构表达上先天不足。Markdown 擅长表达“这是一段文字那是一个标题”但不擅长表达“这两列数据有对应关系”“这五个节点属于同一个分组”“这块内容只能选择枚举值之一”。当上下文复杂度上升时模型需要从文本里“猜测”结构猜错就是信息丢失。这正是 Anthropic 工程师改选 HTML 的核心原因在 AI 工作流里文档格式不再只是个人偏好而是一个工程变量。格式选择直接影响模型的解析准确率、提示词稳定性和下游任务表现。本文要解决的就是这个问题——帮你判断什么时候该放弃 Markdown 转而使用 HTML以及怎么转型。2. Markdown 的贡献与“足够好”陷阱Markdown 本身是一项非常成功的发明。它用极简的语法解决了纯文本排版问题让写作者专注于内容而不是格式。正因为轻量它迅速成为开源社区、技术博客、产品文档的事实标准。GitHub 的 README、Vue 的文档站、Python 的官方教程你几乎找不到一个技术项目完全不用 Markdown。但 Markdown 有一个隐含的定位它最初是设计给人类快速写作用的而不是设计给机器精确解析用的。这个定位在“简单文档”里毫无问题一旦文档复杂度上升就开始出现裂缝。第一个裂缝是表格。Markdown 的表格语法来自 GFMGitHub Flavored Markdown它只能表达最简单的二维表格有表头、有行、有列但不能合并单元格不能让一个单元格跨两行也不能精确控制对齐。如果单元格内容里恰好有竖线|你就必须转义否则表格结构直接破坏。看一个实际例子| 字段 | 类型 | 说明 | | ---------- | ------ | ------------------------------ | | user_id | string | 用户唯一标识 | | 操作 | log | 记录用户点击格式 a\|b\|c |当内容里出现|时你不得不写\|。这还能忍。真正难受的是如果你想把“操作日志”这几个字合并到两列Markdown 根本没有语法支持。你只能拆成两个单元格然后让 AI 自己去猜它们的视觉关系。第二个裂缝是方言分裂。CommonMark、GFM、GitLab Flavored Markdown、Pandoc 扩展不同平台对 Markdown 的解析规则并不完全一致。同一篇文档在 GitHub 上渲染是对的换一个渲染器可能就错位。这对人类阅读影响不大但对 AI 解析来说任何一个解析差异都可能导致结构判断错误。第三个裂缝是结构表达力不足。Markdown 只有标题、列表、表格、引用、代码块这几类有限语法。它表达不了“这个列表项属于那个分组的子项”这种语义也无法描述 UI 原型、数据模型、接口字段之间的复杂关系。当你要给 AI 提供完整上下文时这些丢失的结构信息很重要。这引出一个关键判断Markdown 的“足够好”只适用于文档结构简单的场景。一旦文档进入“复杂结构”区间它的简洁就变成了负担。你省下的语法成本会在模型解析、上下文检索、下游任务错误中加倍偿还。3. HTML 为什么更适合作为 AI 的上下文格式要理解 Anthropic 工程师为什么转向 HTML必须先理解 AI 读取文档的方式。大模型本质上是一个模式识别器它的训练语料覆盖了大量互联网 HTML 内容。对模型而言HTML 的标签本身就是语义信号table表示表格tr表示行td表示单元格ul表示无序列表。模型不需要推测它直接能“看到”结构。HTML 的标签即语义特性解决了 Markdown 最棘手的问题。比如前面那个 Markdown 表格表达不了的合并单元格HTML 可以非常自然地写出来table thead tr th字段/th th类型/th th说明/th /tr /thead tbody tr tduser_id/td tdstring/td td用户唯一标识/td /tr tr td colspan2操作日志合并单元格/td td记录用户点击行为格式如 a|b|c/td /tr /tbody /table这段 HTML 里colspan2明确告诉模型“这个单元格占两列”不需要任何视觉推理。Markdown 做不到这一点。再往下看HTML 的 DOM 结构天然是一棵层级树。html包含bodybody包含main和sectionsection又包含h2和table。这个层级关系对模型来说就是文档的骨架。RAG 系统在切分文档时可以顺着section边界切块而不是把纯文本从中间硬切导致语义被拦腰截断。还有一个容易被忽略的点HTML 的渲染是可靠的。你写一个table只要语法正确任何浏览器渲染结果都一致。但 Markdown 在不同平台上的渲染可能不同。对追求稳定性的 AI 工作流来说渲染差异是一种看不见的噪音。当然HTML 不是没有缺点。它冗长、可读性差、不适合快速记录。写一篇短笔记Markdown 十秒钟搞定HTML 可能要先写骨架、加闭合标签。所以它的优势集中在“机器解析”这个维度上而不是“人类速记”这个维度。我的判断是HTML 和 Markdown 不是替代关系而是适用场景不同。Markdown 是人与人的沟通格式HTML 是人与模型、模型与模型之间的结构化上下文格式。Anthropic 工程师的调整本质上是在文档的上游和下游都增加了“机器读者”之后主动换了一种更利于机器理解的表达语言。4. Anthropic 工程师改选 HTML 的场景拆解既然确定了“HTML 更适合做 AI 上下文”那 Anthropic 工程师具体在哪些场景里使用它呢从工程逻辑上推测有三类场景收益最明显。第一类是复杂规格文档。产品需求、API 规范、协议定义这类文档天然包含大量表格、字段映射、枚举值、嵌套结构。过去用 Markdown 写也能看但模型阅读时经常丢失字段之间的对应关系。改用 HTML 后字段定义用dl描述枚举值用ul列举表格用table呈现模型对“哪个字段对应哪个类型、有哪些可选值”的理解准确率会显著提高。第二类是给 AI 的长上下文输入。在 Claude 这类大模型的使用场景中上下文窗口虽然越来越大但塞满有噪音的文本仍然会稀释模型注意力。只要你把一个结构清晰的 HTML 文档包裹在明确的标签里模型往往能更快定位关键信息。例如你可以这样写提示词请阅读以下 HTML 格式的需求文档完成三个任务 1. 概括产品必须实现的四个核心模块 2. 找出表格中优先级为 P0 的需求数量 3. 提出两个我可能遗漏的边界情况 doc !DOCTYPE html html langzh-CN head meta charsetUTF-8 title结算中心改版需求/title /head body main section h2需求概述/h2 p用户希望在结算页查看每笔订单的明细并支持导出账单。/p /section section h2核心模块/h2 ul li订单列表/li li账单导出/li li金额汇总/li li优惠明细/li /ul /section section h2优先级表格/h2 table thead tr th模块/th th优先级/th th说明/th /tr /thead tbody tr td订单列表/td tdP0/td td影响核心交易流程/td /tr tr td账单导出/td tdP1/td td方便用户留存凭证/td /tr /tbody /table /section /main /body /html /doc这段提示词没有使用任何特殊技巧只是把文档换成了 HTML。但模型在解析时能明确知道table就是表格每一行是一组数据而不是从 Markdown 的竖线堆里推断结构。第三类是 UI 原型与前端协作。HTML 可以直接在浏览器里渲染团队评审时不需要安装额外插件。模型也能根据标签和 CSS 类名理解布局意图比如nav是导航区button是交互控件。当 AI 需要生成前端代码时给它一个 HTML 原型作为输入它的输出质量往往比给一张截图或一段 Markdown 描述更稳定。需要强调的是这不是说 Anthropic 工程师所有文档都改用 HTML。更可能的情况是他们对“机器消费者”占比高的文档主动升级了格式。闲聊、便签、快速记录这类内容没有人会用 HTML 自讨苦吃。这个判断也符合工程常识格式选择跟着消费端走。5. 格式选型什么时候该用 HTML什么时候继续用 Markdown对多数开发者来说最关心的问题是我的项目要不要跟着换答案不是一刀切。你需要先判断文档的“读者结构”。我用四个问题帮自己做判断文档是给人快速阅读的还是给 AI 解析后做下游任务的文档中表格、嵌套、枚举、层级关系多不多文档会不会被 RAG 系统切块切块后结构是否还能保持团队是否依赖 Markdown 的轻量协作流程如果四个问题的答案都偏向“结构复杂、机器消费为主”那 HTML 就值得尝试。反之如果文档只是给人看或者结构非常简单Markdown 依然是最优解。用一个表格对比更直观判断维度建议用 Markdown建议用 HTML文档读者人类为主AI 模型、RAG、Agent 消费为主结构复杂度标题 段落 简单列表表格、嵌套、合并单元格、多级关系表格要求简单二维表需要合并单元格、复杂对齐渲染环境版本库、聊天框、博客浏览器、前端页面、上下文工具协作方式多人快速编辑、diff 友好需要语义结构稳定、自动化处理典型示例README、代码注释、会议纪要需求文档、API 规范、数据模型、UI 原型在真实项目里我比较推荐“混合使用”而不是“全面替换”日常草稿、代码注释、讨论记录继续用 Markdown因为它们是人类写作的起点但一旦文档进入正式流转比如要进入知识库、要作为 AI 上下文、要接入 Agent 任务就把它们转成 HTML 后再消费。有一个落地思路很实用在仓库里维护 Markdown 源文件构建时自动转换成 HTML。这样既保留了 Markdown 的书写效率又让最终消费方拿到的是结构化 HTML。下面我会给一个最小示例。6. 从 Markdown 迁移到 HTML 的最小落地示例如果你决定尝试不要手动把所有 Markdown 重写成 HTML那太耗时也没必要。更聪明的做法是建立一条自动转换流水线。6.1 用 Pandoc 快速转换单个文件Pandoc 是目前最通用的文档格式转换工具支持 Markdown 转 HTML对表格、代码块、链接等语法的兼容性很好。pandoc docs/checkout.md -s -o docs/checkout.html如果系统还没有安装Debian/Ubuntu 可以这样安装sudo apt-get update sudo apt-get install -y pandoc转换出来的 HTML 是完整的独立页面可以直接在浏览器打开也可以作为后续提示词的输入。参数-s表示生成 standalone 文档会带html、head、body骨架。6.2 用 Python 脚本批量转换整个知识库当你有几十甚至上百篇 Markdown 文档时建议写一个批量脚本。这里使用 Python 的markdown库它支持tables、fenced_code、toc等常用扩展。# 文件convert_md_to_html.py import pathlib import markdown src_dir pathlib.Path(docs/markdown) dist_dir pathlib.Path(docs/html) dist_dir.mkdir(exist_okTrue) for md_file in src_dir.glob(*.md): text md_file.read_text(encodingutf-8) body markdown.markdown( text, extensions[tables, fenced_code, toc], ) html_doc f!DOCTYPE html html langzh-CN head meta charsetUTF-8 title{md_file.stem}/title /head body {body} /body /html out_file dist_dir.joinpath(md_file.stem .html) out_file.write_text(html_doc, encodingutf-8) print(f已生成: {md_file.name} - {out_file.name})运行前先安装依赖pip install markdown然后执行python convert_md_to_html.py脚本会把docs/markdown下所有.md文件转换成docs/html下的.html文件。核心逻辑就是把 Markdown 文本交给markdown.markdown()处理再用统一的 HTML 模板包裹起来。6.3 为 AI 工作流设计标准 HTML 模板如果你要频繁把文档喂给 AI建议提前设计一套标准模板让团队所有文档都使用统一的语义结构。下面是一个适合作为“需求文档 AI 上下文”的模板骨架!DOCTYPE html html langzh-CN head meta charsetUTF-8 title文档标题/title /head body main section aria-labelledbyoverview h1 idoverview需求概述/h1 p用两到三句话描述文档要解决的问题。/p /section section aria-labelledbyfields h2 idfields核心字段定义/h2 table thead tr th字段名/th th类型/th th必填/th th说明/th /tr /thead tbody tr tdorder_id/td tdstring/td td是/td td订单号全局唯一/td /tr tr tdamount/td tdnumber/td td是/td td订单金额单位分/td /tr /tbody /table /section section aria-labelledbyrules h2 idrules业务规则/h2 ul li金额必须大于 0/li li订单状态为已支付时才允许退款/li li每次退款必须记录操作人/li /ul /section /main /body /html这个模板的优点是语义化标签加上aria-labelledby关联标题让模型在解析时能理解每个section对应哪个标题。实际使用时你可以先跑通最小流程再逐步扩展模板。7. 常见问题与排查思路切换到 HTML 的过程中你大概率会遇到一些问题。下面是我整理的高频问题和排查路径问题现象可能原因排查方式解决方案HTML 反而让 AI 回复变得冗长提示词没有限制输出格式检查提示词是否要求“只输出结论”在提示词里明确约束输出格式如“只输出 Markdown 列表”转换后的 HTML 样式丢失没有引入 CSS打开文件检查是否有style标签是专注语义结构还是视觉样式AI 消费场景只需要语义结构大段 HTML 消耗过多 Token文档过大、一次性塞入上下文查看上下文窗口占用情况按section切分分段喂给模型浏览器打开出现乱码文件编码不是 UTF-8检查源文件编码统一 UTF-8并在head中声明charsetAI 生成的 HTML 里出现脚本模型被诱导输出不安全的代码检查所有script内容渲染前清洗脚本不要直接 innerHTML 注入Git diff 可读性差HTML 文件被压缩成单行查看格式化工具是否生效使用 Prettier 等工具格式化后再提交表格转换后结构错乱源 Markdown 表格本身不规范检查是否有多余竖线或缺失对齐先修正 Markdown 表格语法再转换其中最容易踩的是“Token 消耗”和“安全风险”。HTML 有大量闭合标签同样的内容比 Markdown 占用更多 token。这在短文档里无所谓但几千词的规格文档会明显增加成本。解决办法不是放弃 HTML而是给文档分块、按需投喂不要让模型每次读整篇。安全风险主要出现在渲染环节。当 AI 生成 HTML 片段或者你从不可信来源拿到 HTML 时里面可能包含script或事件属性。如果这些内容被直接插入页面可能引发跨站脚本攻击。无论这个 HTML 是 AI 生成还是人工写的渲染前都要做过滤和转义。8. 最佳实践与工程建议从 Markdown 切换到 HTML不是一个“换扩展名”的简单操作它涉及文档生产、存储、消费三个环节的调整。以下几个建议可以帮助你平稳落地。8.1 先小范围试点不要全面迁移选一个“高频使用 结构复杂”的文档类型比如接口规范或测试用例模板先转换后观察 AI 输出的变化。跑通后再逐步扩大到知识库、Agent 上下文。如果一开始就把所有文档转成 HTML团队协作习惯会被打乱还会增加不必要的负担。8.2 模板先行统一文档骨架团队里使用统一的 HTML 模板会让后续自动化处理轻松很多。模板里固定header、main、section的位置所有文档都遵守“标题 段落 表格 列表”的组合规则。这样无论是人眼阅读还是模型解析都能快速定位信息。8.3 保留 Markdown 源文件构建时转换这是我最推荐的一种工作流。开发者在本地用 Markdown 写草稿提交到仓库CI 构建阶段用 Pandoc 或 Python 脚本自动转换成 HTML下游的 RAG、Agent、知识库只消费 HTML 结果。这个方案兼顾了写作效率和机器可读性。8.4 建立安全渲染边界凡是渲染 HTML 的地方都要明确一个原则默认不安全。对 AI 生成的 HTML用专业的 HTML 清理库做清洗移除script、iframe、on*事件属性再插入页面。如果只是给模型当文本上下文不涉及渲染那安全性风险会低很多。8.5 对上下文做分块管理HTML 适合结构化但不等于“越大越好”。上下文窗口有上限模型注意力也有限。一个折中方案把文档按section切块给每个块加一个id提示词里只引用当前任务需要的块。这样既保留了 HTML 的结构优势又不会让无关内容稀释模型的注意力。8.6 把格式选择写进团队规范如果你的团队正在开发 Agent 或知识库产品建议把“格式选型”写进工程规范。规定哪些文档必须用 HTML哪些可以用 Markdown以及转换工具链是什么。格式选型不是个人偏好而是产品质量的一部分。9. 总结与后续学习方向回到最初的问题Anthropic 工程师为什么放弃 Markdown 改用 HTML 跟 AI 工作不是 Markdown 错了而是场景变了。Markdown 依然是人类写作效率最高的格式之一它的轻量和易读性无可替代。但当文档要交给 AI 解析、切分、检索时HTML 的标签即语义和天然层级结构让机器理解更稳定、更精确。这种选择背后是文档消费端的变化也是 AI 工作流走向工程化的必然结果。如果你想动手实践建议从一篇结构最复杂的文档开始转成 HTML观察模型在总结、抽取、问答任务上的表现。对比一下同样是“把文档喂给模型”Markdown 和 HTML 到底哪个让你少改几轮提示词。这个实验成本很低但结论很可能颠覆你习惯的“Markdown 万能”认知。下一步值得深入的方向有三个一是 RAG 文档切分策略结合 HTML 的语义标签设计更合理的切块规则二是结构化提示词工程学会用 XML 标签或 HTML 块组织上下文减少模型的自由发挥三是 Agent 的工具设计当一个 Agent 需要消费长文档时怎么利用 DOM 结构完成精准抽取而不是整段复制。这些都是 AI 应用层工程师接下来真正要面对的工程问题。格式选择这件事本质上是你是否愿意为“机器可理解性”多付一点写作成本。在 AI 成为重要读者的今天这笔成本越来越值得付。
