工程师转向 AI 工程时通常会先看模型 API、Prompt 模板、RAG 框架和 Agent 编排却容易忽略一个贯穿所有环节的基础技能Markdown。它既是轻量级文档语言也是 AI 模型输入输出中最常见的结构化文本格式。这套课程A Markdown Curriculum for Engineers Moving into AI Engineering的目的是把 Markdown 从“能写笔记”提升到“能支撑 AI 工程工作流”适合后端、前端、测试和算法背景的工程师。下面按一条可执行的路线展开先理解价值再搭环境、练语法、写渲染脚本最后把 Markdown 接进提示词、RAG 分块和流式输出。1. 为什么 AI 工程要先建立 Markdown 基础1.1 Markdown 在 AI 工程中不只是文档格式很多人把 Markdown 当成“写字用的标记语言”但在 AI 工程里它同时承担三个角色。第一它是人类阅读层。模型输出、技术文档、调试记录都靠 Markdown 的结构让人快速定位信息。第二它是机器解析层。标题层级、列表、代码块、表格都可以被脚本解析成结构化数据这是 RAG 知识库分块的重要依据。第三它是模型沟通层。给 LLM 的提示词如果用 Markdown 组织模型更容易区分“任务指令”“上下文材料”“输出格式”回答的结构也更稳定。所以AI 工程师写 Markdown 不是在写文档而是在设计一种模型和人都能理解的信息结构。这也是为什么很多 AI 应用的前后端协议里模型返回的正文格式默认就是 Markdown。前端拿到后直接渲染后端拿到后按标题切块测试人员拿到后可以对比输出结构。1.2 工程师转型 AI 工程需要补哪几层 Markdown 能力转型 AI 工程时Markdown 的知识不是一条直线而是至少五层能力层要解决的问题典型内容基础语法层能不能写出结构稳定的文本标题、列表、引用、代码块、表格、链接、图片扩展语法层能不能表达更多语义任务列表、脚注、删除线、公式、文本绘图工具链层能不能高效编辑和预览VSCode 插件、Typora、Chrome 阅读、导出工具工程化层能不能安全、可维护地渲染markdownlint、HTML 消毒、统一构建脚本AI 场景层能不能服务模型工作流提示词模板、RAG 分块、SSE 流式输出、评测集传统工程师大多停留在第一层和第二层少数人用过 Typora 或 VSCode 预览但很少接触工程化和 AI 场景层。这套课程的主线就是补齐后三层让 Markdown 真正进入 AI 工程的开发链路。1.3 这套课程的学习主线学习主线不是“背语法”而是围绕一个目标从零搭建一套能够处理 Markdown 的 AI 工程脚手架。其中包括一个本地知识库目录、一组 VSCode 配置、一个把 Markdown 安全渲染成 HTML 的脚本、一份结构化的提示词模板以及一个能处理 SSE 流式输出 Markdown 的前端片段。完成这条主线后你会自然具备排查 Markdown 渲染问题的能力也会知道为什么本地预览正常、生产环境却样式错乱。2. 环境准备建立可复现的 Markdown 学习环境2.1 基础工具推荐与选择逻辑学习阶段不需要一次性安装很多工具。建议先选一条主路径VSCode 负责编辑和预览Python 或 Node 负责渲染脚本Pandoc 负责格式转换。这样可以覆盖学习、开发、交付三个场景。工具用途建议VSCode编辑、预览、代码高亮安装 Markdown All in One 和 Markdown Preview EnhancedTypora本地快速阅读和写作适合做阅读器不适合作为团队唯一渲染标准Chrome 扩展阅读本地 Markdown 文件上传或加载本地文件时注意文件访问权限Python markdown 库服务端渲染 Markdown配合 bleach 做安全过滤Pandoc转 Word、HTML、PDF适合交付场景markdownlint检查 Markdown 规范VSCode 插件或命令行均可选择工具时有个原则编辑器可以自由但团队必须统一“渲染器”。同一个 Markdown 文件在 Typora 和 GitHub 上的显示细节可能不同所以生产环境要确定一个权威渲染器其他工具只负责编辑和预览。2.2 创建 AI 工程课程目录结构先建立一个最小项目目录后续所有练习都沉淀在这个仓库里。mkdir -p ai-engineering-curriculum/{docs,scripts,templates,resources} cd ai-engineering-curriculum git init目录含义如下docs存放 Markdown 文档作为 RAG 和渲染实验素材。scripts存放 Markdown 渲染、校验、转换脚本。templates存放提示词模板和文档模板。resources存放图片、数据样本、输出结果。在docs下创建一个README.md先写入课程说明。这个文件既是学习入口也是后续渲染脚本的输入样例。2.3 VSCode 配置与插件在.vscode/settings.json中写入以下配置{ editor.formatOnSave: true, [markdown]: { editor.defaultFormatter: yzhang.markdown-all-in-one, editor.wordWrap: on }, markdownlint.config: { MD013: false, MD033: true } }这里有几个关键点editor.wordWrap: on让长行自动换行避免表格和代码块被横向滚动条打断。MD013关闭每行最大长度限制因为 AI 生成的 Markdown 经常有长链接和长表格。MD033开启内联 HTML 检查因为默认情况下 Markdown 允许写 HTML但在 AI 渲染场景里这可能带来安全风险。安装插件后在 VSCode 中打开README.md按CtrlShiftV打开预览。预览正常后再安装一个扩展命令用于格式化表格。若插件没有生效先检查右下角语言模式是否被识别为Markdown然后执行Developer: Reload Window重新加载。3. 用 30 分钟掌握 AI 工程最常用的 Markdown 语法3.1 最小语法集AI 工程中真正高频的语法比很多人想的要少。先掌握下面这些足够覆盖 80% 的文档和模型输出场景。# 一级标题 ## 二级标题 一段普通文本。这是**加粗**这是*斜体*。 - 列表项一 - 列表项二 1. 第一步 2. 第二步 引用提示。 python print(hello)参数类型说明modelstring模型名称temperaturefloat采样温度链接文本这段内容涉及标题、强调、无序列表、有序列表、引用、代码块、表格、链接、图片。学习时要注意H1 在一个文件里最好只出现一次H2 是章节级别H3 是子章节。AI 模型在生成 Markdown 时通常会遵守这个层级但偶尔会跳级比如从 H2 直接跳到 H4这种输出在解析时会造成文档结构混乱。 ### 3.2 AI 工程中的 Markdown 书写规范 为了让自己写的文档能被模型和脚本稳定解析建议建立一条简单书写规范。 | 规则 | 原因 | 错误例子 | 推荐写法 | | --- | --- | --- | --- | | 一个文件只保留一个 H1 | 便于 RAG 按标题切片 | 四个 H1 混在一起 | H1 作为文档标题 | | 标题层级不要跳级 | 避免目录树断裂 | H2 直接到 H4 | 按 H1-H2-H3 降级 | | 代码块必须声明语言 | 便于代码高亮和构建 | 空代码块 | python | | 表格前后保留空行 | 避免解析器把表格当成普通段落 | 表格紧跟段落 | 表格前空一行 | | 图片使用相对路径 | 仓库迁移后图片仍然可用 | C:\pic.png | ./resources/pic.png | 这些规则不是形式主义。RAG 切块时经常按标题决定块边界文档结构越规范切出来的块就越完整。表格前后没有空行很容易导致表格被解析为普通文本进而影响后续向量化。 ### 3.3 换行、表格复制和图片路径三个高频问题 第一个高频问题是换行。Markdown 中的单个换行在大多数渲染器里会被当成空格只有空行才能真正分段。AI 模型输出时经常连续输出许多行而不加空行前端渲染后就会合成一整段。解决办法是让模型在输出规范里明确“段落之间使用空行”或者在流式渲染时先做段落归一化。 第二个高频问题是表格复制。把 Markdown 表格从网页复制到 Excel 时列结构经常丢失因为 Markdown 表格本身不是 CSV 或 HTML不同编辑器对复制内容的处理逻辑不同。如果确实需要把数据提供给用户下载建议服务端生成 CSV 或 Excel 文件不要把 Markdown 表格当作数据交换格式。 第三个高频问题是图片路径。Markdown 中图片路径如果是本地绝对路径换到其他环境就会失效。团队协作时使用 ./resources/xxx.png 这种仓库内相对路径或使用对象存储 URL。生产环境还要考虑图片域名是否允许被渲染页面访问否则会出现本地正常、线上图片裂开的现象。 ## 4. 最小可运行案例把课程笔记发布为 HTML ### 4.1 使用 Python 将 Markdown 渲染为 HTML 进入工程化阶段时第一步不是写业务代码而是写一个能复用的 Markdown 渲染脚本。下面的代码用 Python 把 docs/README.md 渲染成 HTML。 先准备依赖 bash pip install markdown bleach创建scripts/render.pyfrom pathlib import Path import markdown import bleach ALLOWED_TAGS [ p, h1, h2, h3, h4, pre, code, blockquote, ul, ol, li, strong, em, a, img, table, thead, tbody, tr, th, td, ] ALLOWED_ATTRS { a: [href, title], img: [src, alt, title], } def render_md(md_text: str) - str: html markdown.markdown( md_text, extensions[extra, tables, fenced_code, codehilite], ) return bleach.clean( html, tagsALLOWED_TAGS, attributesALLOWED_ATTRS, stripFalse, ) src Path(docs/README.md) out Path(docs/readme.html) html render_md(src.read_text(encodingutf-8)) out.write_text(html, encodingutf-8) print(f[INFO] 读取 Markdown: {src}) print(f[INFO] 渲染完成: {out})运行python scripts/render.py正常输出[INFO] 读取 Markdown: docs/README.md [INFO] 渲染完成: docs/readme.html这段代码里有两个关键设计。第一extensions启用了表格、围栏代码块和代码高亮这些都是 AI 工程中最常用的 Markdown 扩展。第二渲染后的 HTML 没有直接写入页面而是经过bleach.clean过滤。这样做的原因是Markdown 语法本身允许嵌入 HTMLAI 模型返回的内容如果包含script或onerror不过滤就可能造成 XSS。4.2 增加安全过滤和样式如果团队使用 Node.js可以用marked加DOMPurify实现等价逻辑npm i marked dompurify前端片段import { marked } from marked; import DOMPurify from dompurify; const mdText await fetch(/docs/readme.md).then(r r.text()); const unsafeHtml marked.parse(mdText); const safeHtml DOMPurify.sanitize(unsafeHtml); document.querySelector(#content).innerHTML safeHtml;需要注意marked的旧版本和部分配置项会保留原始 HTML所以一定要在innerHTML之前执行DOMPurify.sanitize。本地预览时可以只写markdown.markdown但生产环境必须加入消毒步骤。4.3 验证输出验证时不要只看浏览器是否显示“正常”。推荐检查三个点。第一打开docs/readme.html检查标题层级是否和 Markdown 一致。第二在浏览器开发者工具里查看img标签的文件路径确认图片能加载。第三在 Markdown 中故意写入一段img srcx onerroralert(1)重新运行脚本确认页面没有执行脚本。注意只验证程序能启动不算完成。至少要把输入、输出和安全分支都验证一遍才算真正的可复现案例。5. AI 工程中的 Markdown 工作流从提示词到模型输出5.1 用 Markdown 组织提示词和系统约束AI 工程里最常见的 Markdown 用法不是写日志而是写提示词模板。结构化的 Markdown 提示词能让模型更清楚任务边界。下面是一个可复用的模板骨架建议放在templates/prompt_template.md# 任务 你是一名 AI 工程文档助手。 ## 输入材料 {{input}} ## 输出要求 - 使用 Markdown 输出 - 结构为概述 / 关键概念 / 示例 / 注意事项 - 示例代码必须声明语言 - 禁止编造参数 ## 示例输出 ## 概述 ...这套结构的价值在于## 输入材料和## 输出要求把上下文和约束分开了。模型在处理长文本时更容易遵循这种显式分区。实际使用时后端把{{input}}替换成用户问题或检索到的文档片段再连同模板一起发给模型。5.2 RAG 和语料处理中的 Markdown 分块策略RAG 知识库经常需要把 Markdown 文档切成适合向量化的文本块。如果按固定字符数硬切很容易把表格、代码块或列表从中间切断。更好的策略是先按标题层级切分。下面是一段示意代码说明按标题切分的基本思路def split_markdown_by_headings(md_text: str) - list[dict]: chunks [] current_title intro current_lines [] for line in md_text.splitlines(): if line.startswith(#) and current_lines: chunks.append({ title: current_title, text: \n.join(current_lines).strip(), }) current_title line.lstrip(#).strip() current_lines [] current_lines.append(line) if current_lines: chunks.append({ title: current_title, text: \n.join(current_lines).strip(), }) return chunks切块时把标题作为元数据保存查询时可以根据标题缩小检索范围。如果知识库里的文档不是严格的 Markdown而是模型生成的半结构化文本还要先做换行、标题跳级和列表缩进归一化。切分后可以用一个脚本统计每段是否出现“未关闭的代码块”防止向量化时把残缺代码块写入数据库。5.3 SSE 流式输出 Markdown 的渲染链路大模型接口通常是一边生成一边返回文本前端希望像打字机一样逐个字符显示。这个过程中SSEServer-Sent Events配合 Markdown 渲染器是常见方案。服务端返回示例event: message data: {delta: ## 概述\n\n} event: message data: {delta: Markdown 是} event: done data: [DONE]前端接收流并逐步渲染const res await fetch(/api/chat, { headers: { Accept: text/event-stream } }); const reader res.body.getReader(); const decoder new TextDecoder(utf-8); let md ; while (true) { const { value, done } await reader.read(); if (done) break; md decoder.decode(value, { stream: true }); const safeHtml DOMPurify.sanitize(marked.parse(md)); document.querySelector(#content).innerHTML safeHtml; }这里有一个常见误区流式渲染时md会在一段时间里包含“未写完的代码块”或“未完成的表格”直接传给marked解析页面可能出现闪烁。工程上可以做一些容错一是用一个防抖函数每隔 100 到 200 毫秒渲染一次二是在渲染前把不完整的代码块标记为“代码块渲染中”避免临时解析成普通文本三是最终结果到达后再基于完整的md字符串渲染一次。6. 把 Markdown 变成可交付成果Word、PPT、HTML 与工作流6.1 用 Pandoc 转 Word 和 HTML当 AI 生成的内容需要交付给业务方评审时Word 仍然是常见格式。Pandoc 可以把 Markdown 转成 docx、html、pdf 等pandoc docs/README.md -o docs/README.docx pandoc docs/README.md -s -o docs/README.html在转换前要先确认本地是否安装了 Pandoc。没有安装的情况下可以使用官方 Docker 镜像docker run --rm -v $(pwd):/data pandoc/core README.md -o README.docx用 Pandoc 转 Word 时表格会转换成 Word 原生表格代码块会以带样式的段落形式出现。如果文件里包含大量自定义扩展语法Pandoc 可能不支持所以在团队内部应控制 Markdown 扩展语法的使用范围。6.2 用 Marp 从 Markdown 生成 PPT技术方案评审、培训分享经常需要 PPT。Marp 可以直接用 Markdown 生成幻灯片适合把已写好的技术文档转成演示稿。先安装并生成npx marp-team/marp-clilatest docs/slides.md -o dist/slides.htmlslides.md中使用---分隔幻灯片# 第一页 - Markdown 基础 - AI 工程工作流 --- # 第二页 ## 流式渲染 模型返回 Markdown前端逐步渲染。生成后打开dist/slides.html检查分页效果。需要导出 PDF 或图片时再根据 Marp 文档调整输出格式。6.3 平台兼容性飞书、小程序和 Chrome 阅读同样的 Markdown 文件在不同平台的解析结果可能不同。飞书文档支持导入 Markdown但对高级扩展语法支持有限。如果原始文档依赖特定编辑器插件导入飞书后可能出现表格错位或流程图丢失。这里要注意标准 Markdown 本身没有流程图语法团队如果要写图表必须约定一种受控的文本绘图语法并确认所有目标平台都支持否则建议导出为图片再插入文档。小程序场景更特殊。小程序没有浏览器那样的 DOM 和innerHTML不能直接把 Markdown 字符串塞进页面。常见做法有两种在小程序端使用 Markdown 解析器把 Markdown 转成节点数组再用rich-text组件的nodes渲染。在服务端先把 Markdown 渲染成纯小程序可用 HTML并做样式隔离。如果只是本地阅读Chrome 阅读本地 Markdown 比较直接但需要处理本地文件访问权限。打开 HTML、MD 文件时如果出现空白先检查浏览器是否允许访问file://本地资源路径中是否有中文或空格。7. 常见问题排查一条从现象到根因的链路7.1 现象到根因对照表Markdown 相关故障很容易被误判为“网络问题”或“模型问题”。实际上多数问题集中在输入、解析器、过滤链路和显示层。问题现象常见原因检查方式处理建议预览正常发布后没有换行源文件只有单个换行无空行查看 Markdown 源码统一使用空行分段表格复制到 Excel 后错列Markdown 表格不是 CSV 格式复制后粘贴到纯文本编辑器导出 CSV 或 Excel 文件VSCode 插件不生效文件被识别为其他语言查看右下角语言模式切换为 Markdown 后重新加载双击第二个 Markdown 文件无反应编辑器单实例或文件关联异常检查进程是否存在重新关联文件打开方式模型输出里的 HTML 脚本被执行未对渲染结果做消毒查看页面 HTML 源码增加 bleach/DOMPurify 过滤流式输出时代码块闪烁在完整代码块到达前已渲染查看控制台日志加防抖和代码块状态标记飞书导入后表格异常平台不支持扩展语法用干净 Markdown 测试限制扩展语法或转图片7.2 从输入到显示的四步排查法遇到 Markdown 问题时不要直接改前端代码按下面顺序排查。第一步检查输入。把 Markdown 源文件放到独立的 Markdown 查看器中确认原始结构是否正确。第二步检查解析器。确认是否使用了团队统一的渲染器扩展配置是否一致。第三步检查过滤链路。如果渲染后要经过bleach或DOMPurify检查白名单是否把必要的标签裁掉。第四步检查显示层。确认浏览器、小程序、飞书等目标平台是否支持输出 HTML。这个顺序能快速缩小问题范围。比如“本地预览正常飞书导入格式乱”问题大概率在第二步和第四步而不是模型输出错误。再比如“AI 返回的内容在前端被截断”通常不是 Markdown 解析问题而是流式输出的增量拼包逻辑有问题要检查 SSE 的data解析是否遗漏了空行。8. 最佳实践与 30 天学习路径8.1 学习环境与生产环境的差异本地用 Typora 预览和生产环境渲染 AI 输出要求完全不同。本地尽量直观生产必须安全、稳定、可监控。场景要求推荐做法本地学习快速预览Typora、VSCode Preview团队文档统一格式仓库内 Markdown markdownlint生产 AI 渲染安全隔离服务端渲染 HTML 消毒对外交付格式兼容Pandoc 转 Word/PDF生产环境额外要考虑日志和监控。每次渲染请求应该记录模型返回的 Markdown 长度、渲染耗时、是否命中安全过滤规则。出现离谱的 HTML 内容时要能通过日志定位到具体模型返回。若使用自定义渲染服务还要加上超时和限流避免恶意用户用超大 Markdown 拖垮内存。8.2 Markdown 工程化最佳实践可以根据团队情况采纳以下清单每个 Markdown 文件都使用固定的 front matter 结构例如title、tags、status。只使用团队约定的 Markdown 子集新语法要经过评审再启用。Markdown 源文件纳入 Git 管理避免只维护导出后的 Word 或 HTML。在 CI 中执行markdownlint格式问题在合并前暴露。对外发布 HTML 前使用统一构建脚本不手工复制粘贴。所有用户内容和模型生成内容渲染成 HTML 前必须做白名单过滤。RAG 分块时优先按标题切分不按固定字符数盲切。8.3 30 天学习路径把课程拆成四周每周都有一个可提交的成果周次主题完成标志第 1 周语法与工具链建立本地仓库配置 VSCode 预览通过 markdownlint第 2 周渲染与安全用 Python/Node 写 Markdown 渲染脚本并完成消毒第 3 周提示词与 RAG准备提示词模板实现按标题切分 Markdown第 4 周流式输出与交付完成 SSE 流式渲染示例用 Pandoc/Marp 导出成果每周末做一个自测确认以下能力是否掌握能在 Markdown 中正确使用标题层级和代码块。能解释单个换行与空行分段的不同。能配置 VSCode Markdown 预览插件。能编写脚本将 Markdown 安全渲染成 HTML。能说明在流式渲染时为什么要防抖和处理不完整代码块。能设计一份结构化提示词模板并说明各分区的作用。这套课程最终检验标准不是记住多少语法而是能否把 Markdown 放回 AI 工程链路从文档、提示词、分块、渲染到交付每一个环节都能用统一标准撑起来。建议今天先完成第 1 周任务在本地仓库提交第一个.md文件。后续调试模型输出时你会慢慢发现当初为 Markdown 打下的基础是 AI 工程里最容易复用的工程资产。