1. 项目概述：为什么我们需要一个“AI原生”的文档格式？
如果你最近在折腾大语言模型应用，特别是RAG或者智能体，那你肯定遇到过这个头疼的问题：怎么把那些五花八门的文档——网页、PDF、Word、甚至内部Wiki——喂给AI，才能让它真正“理解”内容，而不是只做简单的文本匹配？
传统的做法是把所有东西都转成纯文本。结果呢？文档的标题、作者、发布时间这些元数据丢了；文档之间的引用、父子关系这些结构信息也丢了；你更没法告诉AI：“嘿，看到这段内容时，你应该优先总结它”或者“这部分内容跟另一个文档是父子关系”。最后，你的RAG系统检索出来的内容可能相关，但缺乏上下文，导致AI生成的回答要么泛泛而谈，要么干脆跑偏。
这就是MAGI要解决的问题。MAGI，全称Markdown for Agent Guidance & Instruction，你可以把它理解为一个“增强版”的Markdown。它的核心思想很简单：在保持Markdown人类可读性的基础上，嵌入一套专门给AI“看”的结构化指令和元数据。这样一来，一份.mda文件，人类读起来是篇正常的文章，但AI处理器解析后，却能获得远超纯文本的丰富上下文和明确的操作指南。
我最初接触MAGI是在为一个客户构建企业知识库的RAG系统时。他们的技术文档相互引用关系复杂，且不同章节对AI处理的需求不同（有些需要总结，有些需要提取实体）。用传统方法效果很差。尝试MAGI后，我们成功地将文档的“灵魂”——它的元数据、内部指令和外部关系——都保留了下来，检索准确率和回答质量有了肉眼可见的提升。下面，我就结合自己的实战经验，带你彻底搞懂MAGI，并手把手教你如何用它来升级你的AI应用。
2. MAGI核心组件深度解析：不止是Markdown
MAGI的魅力在于它的“可叠加性”。它基于标准Markdown，增加了三个可选的增强组件。你可以只用其中一个，也可以组合使用，非常灵活。我们来逐一拆解。
2.1 YAML Front Matter：给文档一张“身份证”
Front Matter，即文档头部的元数据块，用三个连字符---包裹。这是文档的“身份证”和“简历”，让AI第一眼就知道这份文档是谁、关于什么、何时出生。
为什么需要它？在传统RAG中，一篇名为《2024年Q3产品规划》的文档，被向量化后，“2024”、“Q3”、“规划”这些词会散落在高维空间里。但如果Front Matter里明确标注了title: “2024年Q3产品规划”、purpose: “internal-plan”、created-date: “2024-06-01”，AI在检索时就可以利用这些结构化字段进行精准过滤，比如“给我找所有2024年创建的内部规划文档”，这比全文搜索要可靠得多。
关键字段实战解读：
| 字段 | 我的填写心得与实战意义 |
|---|---|
doc-id | 这是最重要的字段，必须全局唯一。我强烈推荐使用UUID v4。不要用自增ID或标题，因为标题可能重复，而UUID能保证即使文档被移动、重命名，其身份标识不变。这是构建文档知识图谱的基石。 |
title/description | 不要写得太冗长。description应是一句话摘要，用于在检索结果列表中快速预览。好的描述能极大提升AI对文档主旨的判断准确率。 |
tags/entities | tags用于分类（如[“api”, “v2”, “deprecated”]），entities用于标注文档中出现的具体实体名（如[“UserService”, “OAuth 2.0”, “Jane Doe”]）。在构建行业知识库时，预先定义好实体标签体系，能方便后续做实体链接和关系挖掘。 |
created-date/updated-date | 务必使用ISO 8601格式（如2024-06-01T15:30:00Z）。这保证了时间的可排序、可计算。在检索时，你可以轻松实现“优先返回最近更新的文档”这样的逻辑。 |
relationships | 这里可以预先声明本文档与其它文档存在关系（如[“Extends Markdown”, “Cited by RFC-123”]），是对下文“关系型脚注”的一个高层提示。 |
注意：Front Matter是可选的。对于简单的笔记，你可以完全不写。但对于希望被AI深度处理的正式文档，花几分钟填写完整的Front Matter，回报是巨大的。
2.2ai-script代码块：在文档中嵌入“AI遥控器”
这是MAGI最“魔法”的部分。你可以在文档的任何位置插入一个标记为ai-script的代码块，里面用JSON格式写明你希望AI对这部分（或全文）内容执行什么操作。
它解决了什么痛点？想象一下，你有一份冗长的会议纪要。你希望AI能自动总结行动项，并以JSON格式输出。在没有MAGI之前，你需要在应用代码里写死这些提示词，或者通过复杂的上下文拼接来传递指令。而有了ai-script，你可以把指令直接“写”在会议纪要文档里：
...会议讨论内容... ```ai-script { "script-id": "extract-action-items-001", "prompt": "仔细阅读上述会议纪要，提取所有明确的行动项（Action Items）。每个行动项需包含：负责人、任务描述、截止日期（如果提及）。", "priority": "high", "auto-run": true, "output-format": "json", "output-schema": { "type": "array", "items": { "type": "object", "properties": { "owner": {"type": "string"}, "task": {"type": "string"}, "dueDate": {"type": "string", "format": "date"} } } } } ```当你的AI应用加载这份文档时，解析到auto-run: true且priority: high的脚本，就可以自动触发一个LLM调用，执行提取任务，并将结构化的结果返回给你的系统。
核心字段实战指南：
prompt: 指令本身。要具体、明确。比起“总结一下”，更好的写法是“用不超过100字总结上文的技术原理部分，面向新手程序员”。system-prompt: 这是设定AI角色的绝佳位置。例如，"你是一位经验丰富的安全审计员，请以严格的标准检查以下代码。"output-schema:强烈推荐使用。它定义了输出数据的JSON结构，能强制LLM返回格式规整的数据，极大简化后端处理逻辑。结合像 OpenAI 的 JSON Mode 或 Anthropic 的 Structured Outputs 功能，效果极佳。interactive-type: 设为"button"或"inputbox"时，这个脚本块在前端可以渲染成一个交互式组件。例如，在文档阅读界面，用户可以看到一个“总结本页”的按钮，点击后才触发LLM调用，这适合对实时性要求不高或需要用户确认的场景。
心得：
ai-script块将“处理逻辑”从应用程序代码转移到了文档内部。这带来了巨大的灵活性：文档作者可以随时更新处理指令，而无需重新部署应用程序。但也要注意安全，避免在文档中嵌入敏感或消耗大量资源的指令。
2.3 关系型脚注：构建文档间的“高速公路”
标准Markdown脚注用于补充说明，而MAGI将其升级为定义文档间显式、类型化关系的工具。这是构建高质量知识图谱的关键。
传统方法 vs MAGI方法：
- 传统：文档A中提到“详见文档B”。AI只能通过语义相似度猜测它们有关系。
- MAGI：文档A中直接写明
[^ref1]，并在脚注中定义{"rel-type": "parent", "doc-id": "UUID-of-B"}。AI 100%确定它们是父子关系。
实战应用场景：
- 版本管理：新文档是旧文档的更新版（
rel-type: “extends”）。 - 合规溯源：技术方案文档引用了一条安全标准（
rel-type: “complies-with”）。 - 辩论记录：文档B的观点反驳了文档A（
rel-type: “contradicts”）。 - 知识体系：一篇总览文章下有多篇子主题文章（
rel-type: “parent”/“child”）。
定义关系时的技巧：
本文所述方案基于Smith等人的基础理论[^foundation]，并引用了最新的性能测试报告[^benchmark]。 [^foundation]: { "rel-type": "extends", "doc-id": "a1b2c3d4-...", "rel-desc": "本方案的理论基础来源于此文档", "rel-strength": 0.9, "context": { "section": "理论基础", "relevance": "核心" } } [^benchmark]: { "rel-type": "cites", "doc-id": "e5f6g7h8-...", "rel-desc": "引用了其中的图3数据作为对比", "bi-directional": false }rel-strength: 可以量化关系的强度，在知识图谱计算边权重时非常有用。bi-directional: 设为false表示这是单向引用。设为true时，处理工具可以尝试在目标文档中也自动生成一个反向关系（如cited-by），但这通常需要工具链支持。
3. 从零开始：创建与处理MAGI文件的完整流程
理解了核心概念，我们来看看如何在实际项目中玩转MAGI。整个过程可以分为“创作侧”和“消费侧”。
3.1 创作侧：如何生成你的第一份.mda文件
你有几种方式可以创建MAGI文件：
1. 手动编写（适用于新文档）：就像写Markdown一样，只是多了几个部分。我建议的流程是：
- 先用
uuidgen（Mac/Linux）或在线工具生成一个doc-id。 - 填写Front Matter框架。
- 编写主体内容。
- 在需要AI介入的地方插入
ai-script块。 - 在引用其他文档的地方，使用关系型脚注。
2. 使用url2mda工具转换现有网页（快速入门）：这是体验MAGI最快的方式。官方提供了url2mda.sno.ai在线服务，你也可以自行部署其开源Worker。
自行部署url2mda的详细步骤：
# 1. 克隆仓库 git clone https://github.com/sno-ai/magi-markdown.git cd magi-markdown # 2. 安装依赖 (项目使用 pnpm) pnpm install # 3. 配置 Cloudflare 环境 # 首先登录 Cloudflare: npx wrangler login # 然后创建一个KV命名空间用于缓存（可选但推荐，能提升重复转换速度） npx wrangler kv:namespace create MAGI_CACHE # 命令会输出一个 namespace_id，复制它。 # 4. 修改配置文件 # 编辑 `wrangler.toml` 文件： # - 填入你的 `account_id`（在Cloudflare Workers仪表盘查看） # - 将上一步的 namespace_id 填入 `kv_namespaces` 下的 `id` 字段。 # - 如果你有OpenAI等AI服务的API密钥，并希望启用llmFilter功能，可以在此配置绑定。 # 5. 部署 pnpm deploy部署成功后，你会获得一个*.workers.dev的域名。接下来就可以通过API调用它了。
3. 批量转换现有文档仓库：对于已有的Markdown文档库，可以编写脚本进行批量“MAGI化”。脚本需要做以下几件事：
- 为每个没有
doc-id的文件生成UUID并添加到Front Matter。 - 分析文档间的链接（如
[[其他文档]]或[链接文本](other-doc.md)），将其转换为MAGI关系型脚注。这需要你维护一个从文件路径到doc-id的映射。 - （可选）根据内容分析，自动插入一些通用的
ai-script块，比如摘要生成。
3.2 消费侧：如何解析并利用MAGI文件
一个“MAGI感知”的处理器，其工作流程如下：
# 伪代码示例：一个简单的MAGI解析器逻辑 def process_magi_file(file_path): content = read_file(file_path) # 1. 解析Front Matter front_matter, body = extract_front_matter(content) # 使用如python-frontmatter库 doc_id = front_matter.get('doc-id') title = front_matter.get('title', 'Untitled') # ... 提取其他元数据，存入你的文档数据库 # 2. 分离AI指令与人类可读内容 human_content, ai_scripts = extract_ai_scripts(body) # `human_content` 是移除了```ai-script```块的纯净Markdown，用于展示给用户。 # `ai_scripts` 是一个包含所有JSON指令对象的列表。 # 3. 解析关系型脚注 footnotes, cleaned_content = parse_footnotes(human_content) # `footnotes` 是一个字典，key是脚注标签（如`^ref1`），value是解析后的JSON。 # `cleaned_content` 是移除了JSON脚注但保留普通脚注标记的文本，用于渲染。 # 4. 构建知识图谱边 relationships = [] for ref_id, rel_data in footnotes.items(): if isinstance(rel_data, dict) and 'doc-id' in rel_data: relationships.append({ 'source_doc_id': doc_id, 'target_doc_id': rel_data['doc-id'], 'rel_type': rel_data.get('rel-type', 'related'), 'metadata': rel_data }) # 将relationships存入图数据库（如Neo4j）或关系型数据库的特殊表。 # 5. 处理AI脚本（可选，按需执行） for script in ai_scripts: if script.get('auto-run') or triggered_by_user: # 调用对应的LLM API，传入prompt、system-prompt、parameters等 llm_result = call_llm_api(script) # 结果可以缓存，或直接返回给前端，或触发后续工作流 process_llm_result(script['script-id'], llm_result) return { 'doc_id': doc_id, 'metadata': front_matter, 'human_content': cleaned_content, 'ai_scripts': ai_scripts, 'relationships': relationships }在RAG系统中的集成：
- 索引阶段：除了将
human_content文本切片做向量化嵌入外，一定要将front_matter中的关键字段（title,tags,entities,purpose等）作为元数据（metadata）存入向量数据库。这样在检索时可以进行高效的元数据过滤。 - 检索阶段：当检索到一篇文档时，通过它的
doc-id去知识图谱中查找其relationships，将关联文档（如父文档、引用文档）的ID或内容片段也作为上下文一并送给LLM，这能极大提升回答的准确性和深度。 - 生成阶段：可以将当前文档中
priority: high的ai-script指令（如“请以FAQ形式输出”）作为系统提示的一部分，来指导LLM的最终输出格式和风格。
4. 实战进阶：MAGI在复杂场景中的应用与避坑指南
掌握了基础，我们来看几个高级用例和实践中一定会遇到的坑。
4.1 用例一：构建动态更新的产品手册
场景：你的API文档有几十个接口，每次更新都需手动修改多个地方。MAGI方案：
- 为每个API端点创建一个
.mda文件，Front Matter中tags: ["api", "v1"]。 - 在描述“请求参数”的章节后，插入一个
ai-script块，指令为：“根据上文的参数表格，生成一个Pythonrequests库的调用代码示例。”auto-run: false,interactive-type: “button”，这样用户可以在文档页上点击“生成示例代码”实时获取。 - 当某个接口被弃用，在新接口文档中，通过关系型脚注指明
rel-type: “replaces”，并链接到旧接口的doc-id。 - 编写一个后台作业，定期扫描所有
tags包含”api”的文档，执行其中auto-run: true的脚本（如检查链接有效性、同步示例代码），实现文档部分内容的自动维护。
4.2 用例二：多智能体协作的营销内容生产
场景：一篇营销博客需要经过文案、SEO优化、合规审查三个环节。MAGI方案：创建一篇博客草稿.mda文件，其中嵌入三个ai-script块：
- 文案优化块：
prompt: “将以下草稿润色为吸引眼球的营销文案，语气活泼。”provider: “openai”model-name: “gpt-4” - SEO块：
prompt: “分析以下文本，建议5个核心关键词和meta description。”output-format: “json” - 合规块：
prompt: “检查以下文案中是否存在夸大宣传、绝对化用语等合规风险。”system-prompt: “你是一名严格的法务审核员。”
你的工作流引擎可以依次将草稿和对应指令发送给不同的专用AI Agent（或调用不同模型的同一个Agent），收集结果，并自动生成一份包含初稿、优化文案、SEO建议和合规报告的综合文档。
4.3 常见问题与排查技巧实录
Q1: 我的现有Markdown渲染器（如Typora、VS Code预览）会怎么显示MAGI文件？A1: 它们会把Front Matter显示为顶部的代码块，把ai-script块显示为普通代码块，脚注按普通脚注渲染。完全不会破坏可读性。这是MAGI设计的精妙之处：向后兼容。
Q2:doc-id使用UUID，在文档重命名或移动后如何保持链接不失效？A2: 这正是UUID的优势。你的内部引用系统（如知识图谱）应基于doc-id而非文件路径。文件存储位置变化时，只需更新文件路径到doc-id的索引映射即可，所有通过doc-id建立的关系都不会断裂。
Q3:ai-script里的指令会被恶意利用吗？比如插入一个无限循环的指令。A3: 会。因此，在解析和执行ai-script时必须有安全沙箱和权限控制。生产环境中，我建议：
- 对
auto-run: true的脚本进行审核或限制白名单。 - 对脚本可调用的模型、最大token数、可用参数进行限制。
- 考虑使用独立的、有资源限制的队列来处理AI脚本任务。
Q4: 关系型脚注的维护会不会很麻烦？A4: 初期手动维护确实有成本。建议开发或使用工具来自动化：
- 链接提取器：扫描文档中的普通Markdown链接或双链语法，提示用户将其转换为MAGI关系脚注。
- 图谱可视化工具：展示当前文档的关系网络，方便查漏补缺。
- 批量导入：从已有的目录结构、数据库关系或项目管理工具（如Jira Epic-Story链接）中批量生成关系数据。
Q5: 如何说服团队接受这个新格式？A5: 从痛点切入，小范围试点。不要一开始就要求把所有文档转成MAGI。可以：
- 选择团队最头疼的、AI处理效果最差的某类文档（如复杂的产品需求文档）。
- 将其转换为MAGI格式，重点完善其Front Matter和核心关系。
- 在团队的RAG或问答机器人中对比展示处理效果的提升（例如，回答准确率从60%提升到85%）。
- 用事实和数据推动采纳。同时，强调它“渐进增强”的特性：不对现有工作流造成破坏。
MAGI不是一个要颠覆一切的新标准，而是一个务实的“增强补丁”。它尊重Markdown的简洁哲学，只是悄悄地为AI时代加了几行“注释”。从我实际项目的反馈来看，一旦开发者和内容创作者理解了“一份文档，两种消费”的便利性，就很难再回去了。它让文档从静态的“记录”变成了动态的、可交互的“智能资产”。
