Anthropic 工程师这个做法最近在技术社区里讨论度不低同样是把一份资料交给 AI 处理他们不优先用 Markdown而是选择把内容结构化到 HTML 里再交给模型。乍一看像“倒退”毕竟 Markdown 写作体验轻、语法简单、diff 也友好但仔细拆解就会发现这个选择背后是 AI 工作流里很实际的问题模型能不能正确理解文档边界、能不能稳定定位到某一块内容、能不能按你的意图在长文档里做局部修改。这篇文章不聊玄学直接从这几个方面展开Markdown 和 HTML 在“给 AI 读取”这个场景下到底差在哪为什么 Anthropic 团队在 Claude 相关工具链里更倾向用 HTML 作为中间格式如何把 Markdown 工程化转成 HTML再接入 Claude API批量转换、Token 开销、上下文窗口这些工程细节怎么处理常见报错和排查思路。内容适合正在做 Agent、做 RAG、做文档自动化的开发者。如果你只是偶尔让 AI 帮忙润色一段话那 Markdown 完全够用但如果你想构建一套“AI 能稳定操作长文档”的流水线这篇文章可以直接收藏。1. 核心差异速览Markdown 与 HTML 在 AI 工作流中的定位先给结论Markdown 是给人看的轻量写作格式HTML 是给浏览器和程序解析的结构化文档格式。当工作流里出现“AI 需要理解文档结构、精确修改某个模块、把文档渲染成最终页面”这类需求时HTML 的语义化能力是 Markdown 难以替代的。能力项MarkdownHTML语法复杂度低上手快中高标签多文档结构表达靠#、-、等符号层级有限标签语义丰富可表达嵌套、列表、区块、导航、页脚机器可解析性需要转换器转成 AST 或 HTML原生就是 DOM 树解析成本低渲染确定性不同平台渲染有差异浏览器渲染统一局部精确定位需要额外约定锚点借助id、class、># 产品说明 ## 安装方式 ### Windows 1. 下载安装包 2. 双击运行 ### macOS 1. 打开终端 2. 执行安装脚本 ## 配置说明 | 参数 | 默认值 | 说明 | | --- | --- | --- | | port | 8080 | 服务端口 | | debug | false | 是否开启调试 |这份文档包含标题、列表、代码块、表格结构类型足够。接下来要做的是把 Markdown 转成 HTML再交给模型处理。4. Markdown 转 HTML 的工程做法4.1 使用 Pandoc 命令行转换Pandoc 是文档转换领域非常常用的工具支持几乎所有常见格式互转。# 安装 pandoc 后执行 pandoc input.md -o output.html --standalone --metadata title产品说明--standalone会生成完整 HTML 文档包含html、head、body骨架--metadata title会把标题写入title。如果不想生成完整页面只要正文片段pandoc input.md -o output.html这时输出的是不带html骨架的 HTML 片段适合直接嵌到页面里或作为 API 请求的一部分。4.2 使用 Python-Markdown 脚本转换Python 生态里最常用的是markdown库支持扩展能处理表格、代码块、目录。pip install markdown转换脚本import markdown with open(input.md, r, encodingutf-8) as f: text f.read() html_body markdown.markdown( text, extensions[ tables, fenced_code, toc, sane_lists, ], ) html_doc f!DOCTYPE html html langzh-CN head meta charsetutf-8 title产品说明/title /head body {html_body} /body /html with open(output.html, w, encodingutf-8) as f: f.write(html_doc) print(转换完成:, len(html_body), 字符)这个脚本把 Markdown 转成了带完整骨架的 HTML并且启用了表格、围栏代码块、目录扩展。后续要做的就是把这个html_doc作为上下文发给模型。4.3 使用 Node.js markdown-it如果技术栈以 Node.js 为主markdown-it是主流选择。npm install markdown-itconst MarkdownIt require(markdown-it); const fs require(fs); const md new MarkdownIt({ html: true, linkify: true, typographer: true, }); const source fs.readFileSync(input.md, utf-8); const result md.render(source); const htmlDoc !DOCTYPE html html langzh-CN head meta charsetutf-8 title产品说明/title /head body ${result} /body /html; fs.writeFileSync(output.html, htmlDoc, utf-8); console.log(转换完成);4.4 直接用模型完成格式转换如果你的 Markdown 文档结构比较复杂或者希望转换后的 HTML 更贴合某个设计规范也可以让模型直接完成转换。请把下面的 Markdown 转换成语义化 HTML要求 1. 使用 HTML5 语义标签 2. 表格使用 thead/tbody 结构 3. 在标题区域添加 id 属性方便锚点定位 【Markdown 内容】 ...在这里粘贴 Markdown 原始内容...这种方式生成结果更定制化但也更依赖模型能力并且 Token 开销会更大。工程上更稳妥的做法是先用 Pandoc 做基础转换再用模型做结构调整。5. 为什么 HTML 比 Markdown 更适合 AI 读取5.1 标签就是显式上下文Markdown 里表达“这是一段导航”靠的是文字本身模型必须根据内容推测结构。HTML 的nav、header、main、aside、footer直接告诉模型每个区块的角色。对长文档来说这种显式上下文可以显著降低模型的理解成本。举个例子同一个“安装方式”章节Markdown 写法## 安装方式 在开始安装之前请先检查系统环境。HTML 写法section idinstallation classchapter h2安装方式/h2 p在开始安装之前请先检查系统环境。/p /section模型在解析 HTML 时可以通过section idinstallation快速定位之后如果要修改安装方式里的注意事项可以直接指定“修改 id 为 installation 的 section 里的 p 标签内容”。这在 Agent 工作流里非常实用。5.2 局部精确修改能力更强用 Claude API 做文档修改时如果文档是 Markdown模型很容易多改或者漏改。因为 Markdown 的结构表达太弱比如一个列表项到底属于哪个二级标题下面模型需要看上下文才能确定。而在 HTML 里一个区块的边界是section标签明确包裹的模型可以精确定位。配合 HTML 的>article>pip install anthropic6.2 发送 HTML 文档给 Claudeimport anthropic client anthropic.Anthropic( api_keyYOUR_API_KEY, ) html_doc open(output.html, r, encodingutf-8).read() message client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens2000, system你是一个文档工程助手。你会收到一份 HTML 文档。 请按照用户要求修改文档只返回修改后的 HTML不要输出多余解释。, messages[ { role: user, content: [ { type: text, text: ( 请把下面 HTML 文档中的【安装方式】章节里的 Windows 安装步骤 从‘双击运行’改为‘右键选择以管理员身份运行’。 返回完整 HTML。\n\n f{html_doc} ), } ], } ], ) print(message.content[0].text)要点说明system提示词里明确要求“只返回修改后的 HTML”减少模型输出额外内容的概率。html_doc直接拼接进用户消息让模型同时看到修改指令和文档上下文。如果文档很长可以分段发送但要注意上下文窗口限制。超时和重试建议在客户端做比如timeout300失败后指数退避重试。6.3 如果不是 Anthropic API使用通用 HTTP 调用工程上你可能会接到 OpenAI、通义、Moonshot 等厂商的 API结构类似。下面是一个通用请求模板import requests url https://YOUR_LLM_API/v1/chat/completions headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json, } payload { model: your-model-name, messages: [ { role: system, content: 你是文档工程助手。请严格按用户要求处理 HTML 文档只输出修改后的结果。 }, { role: user, content: 请把下面 HTML 中 id 为 installation 的 section 删掉\n\n html_doc } ], temperature: 0.2, } response requests.post(url, headersheaders, jsonpayload, timeout300) response.raise_for_status() print(response.json()[choices][0][message][content])注意不同厂商的请求体结构不完全一样实际调用前先看对应 API 文档。7. 批量任务设计Markdown 批量转 HTML 并调用模型实际生产环境里不会只处理一份文档。批量处理是工程落地必须考虑的环节。这里给一套可复用的 Python 批量任务框架。7.1 批量转换 Markdown 为 HTMLimport glob import os import logging import markdown logging.basicConfig( levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s, ) INPUT_DIR ./docs/md OUTPUT_DIR ./docs/html os.makedirs(OUTPUT_DIR, exist_okTrue) md_files glob.glob(os.path.join(INPUT_DIR, *.md)) for md_file in md_files: try: base_name os.path.basename(md_file).replace(.md, ) with open(md_file, r, encodingutf-8) as f: text f.read() html_body markdown.markdown( text, extensions[tables, fenced_code, toc], ) html_doc f!DOCTYPE html html langzh-CN head meta charsetutf-8 title{base_name}/title /head body {html_body} /body /html output_file os.path.join(OUTPUT_DIR, f{base_name}.html) with open(output_file, w, encodingutf-8) as f: f.write(html_doc) logging.info(转换成功: %s, output_file) except Exception as e: logging.error(转换失败: %s, 错误: %s, md_file, e)这个脚本有日志、有异常处理、有目录隔离可以直接作为批处理基础版。7.2 批量调用模型做文档修改更复杂的场景是把每个 HTML 文档发给模型让它按规则修改再保存结果。import anthropic import logging import time client anthropic.Anthropic(api_keyYOUR_API_KEY) MODIFY_RULES 对每一份 HTML 文档执行以下操作 1. 检查是否包含 table如果有给所有表格添加 classdata-table 2. 将所有 h2 标签前添加 div classsection-divider/div 3. 删除所有 id 为 deprecated 的节点 def process_one_file(html_path): with open(html_path, r, encodingutf-8) as f: html_doc f.read() message client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens4000, system你是文档批处理引擎严格按照规则修改 HTML 并返回完整 HTML。, messages[ { role: user, content: f{MODIFY_RULES}\n\n{html_doc}, } ], timeout300, ) return message.content[0].text html_files glob.glob(./docs/html/*.html) for html_file in html_files: for attempt in range(3): try: result process_one_file(html_file) with open(html_file .processed, w, encodingutf-8) as f: f.write(result) logging.info(处理成功: %s, html_file) break except Exception as e: logging.error(处理失败: %s, 第 %d 次尝试, 错误: %s, html_file, attempt 1, e) time.sleep(2 ** attempt)这个流程里加了失败重试机制前两次失败后指数退避再试。处理结果写为.html.processed避免覆盖原始文件方便对比。max_tokens设置足够大防止长文档输出被截断。7.3 生产环境建议生产环境的批量任务建议再加一层环节做法任务队列用 Redis/RabbitMQ 或数据库表记录任务状态幂等处理每个文档用 hash 或文档 ID 标记避免重复处理结果校验处理后检查 HTML 标签是否闭合、关键 id 是否存在限流给 API 请求设置 QPS 上限避免触发限流人工抽检按比例抽检模型修改结果尤其是高风险文档8. 资源占用与性能观察Token 和上下文窗口8.1 Token 对比同样的正文内容HTML 因为多出大量标签Token 数通常比 Markdown 多 20% 到 40%。这个估算在不同模型分词器下会有差异精确值需要实际测试。如果你的 API 按 Token 计费批量任务前要做成本评估。可以在 Python 中快速统计字符数和发送前后的 Token 数import anthropic client anthropic.Anthropic(api_keyYOUR_API_KEY) def count_tokens(text): try: response client.messages.count_tokens( modelclaude-3-5-sonnet-latest, messages[{role: user, content: text}], ) return response.input_tokens except Exception as e: print(Token 统计失败:, e) return None markdown_text open(input.md, encodingutf-8).read() html_text open(output.html, encodingutf-8).read() print(Markdown Token:, count_tokens(markdown_text)) print(HTML Token:, count_tokens(html_text))注意count_tokens接口是否可用、参数格式以你实际使用的 SDK 版本文档为准。8.2 对上下文窗口的影响Claude 系列模型目前支持很大的上下文窗口但“支持大窗口”不代表“应该把大窗口塞满”。窗口越长推理成本越高输出延迟越大。实际项目里建议如果文档超过上下文窗口的一半就做分段处理。只发送模型完成任务所需的最小切片而不是整个 HTML 文档。用 HTML 的标签做切片边界例如按section或article切块。长文档场景下先让模型生成文档目录和结构摘要再按需取具体章节。8.3 性能观察清单观察指标观察方法优化方向首 Token 延迟API 返回时间缩短文档长度、减小 max_tokens总响应时间整体耗时分批处理、减少重试次数Token 超限异常信息中出现 context 超限分段发送、精简文档输出截断结果不完整增大 max_tokens重复处理任务重复执行增加任务状态标记9. 常见问题与排查方法问题现象可能原因排查方式解决方案HTML 转换后中文乱码编码不是 UTF-8检查文件编码统一用encodingutf-8读写模型返回内容不是 HTMLsystem 提示词约束不足查看返回内容开头system 明确要求“只返回 HTML”返回结果被截断max_tokens 不够检查输出 token 数调大 max_tokens 或分章节处理API 报 429 限流请求频率过高查看响应头 Retry-After降低并发、加退避重试上下文超出限制文档太长查看异常信息中的 token 数按section切片后分段发送模型修改了错误区域文档结构不清晰检查 HTML 语义标签添加id和>from html.parser import HTMLParser BLOCK_TAGS {script, iframe, object, embed, link} class Sanitizer(HTMLParser): def __init__(self): super().__init__() self.cleaned_parts [] self.depth 0 def handle_starttag(self, tag, attrs): if tag.lower() in BLOCK_TAGS: return attr_str .join( f{k}{v} for k, v in attrs if not k.lower().startswith(on) ) self.cleaned_parts.append(f{tag} {attr_str}.strip()) def handle_endtag(self, tag): if tag.lower() in BLOCK_TAGS: return self.cleaned_parts.append(f/{tag}) def handle_data(self, data): self.cleaned_parts.append(data)这个过滤器去掉了事件属性和外链资源标签。生产环境可以用更成熟的bleach、defusedxml等库。10.4 合规与授权只有你拥有版权或有明确授权的内容才能交给模型处理和修改。涉及用户数据时要确保符合隐私合规要求。生成的可视化页面如果用于商用需要复核文案、图片、字体版权。不要让模型在公开资料之外自行补充未经验证的事实。11. 总结值得上手验证的路径最后给一套可以直接落地的最小验证路径准备一份结构完整的 Markdown 文档。用 Pandoc 或 Python-Markdown 转成 HTML。用 Claude API 发送修改指令让它修改某个section里的内容。对比修改前后结果看模型是否准确定位、是否保持了文档结构。如果验证通过再把这个流程封装成批量任务。最容易踩的坑有两个一是文档太长导致上下文窗口超限二是 system 提示词没有明确“只返回 HTML”导致模型输出一堆解释文本。开始写代码前先定好模板和提示词效率会高很多。对你当前的项目来说不必急着把所有文档都改成 HTML。先挑一份最受影响的、最需要精确修改的长文档做实验用数据和效果说服自己。如果发现模型对 HTML 的理解确实更稳定再把这套流程沉淀成工具链后续接入 RAG、Agent、自动化发布都会顺畅得多。