第三章 Markdown 与 AI 协作

请 AI 检查一段 Python 代码时，如果任务要求、代码和回答格式全挤在一段话里，边界就不太清楚。用 Markdown 把它们分开，AI 更容易照着处理，我们也方便逐项检查结果。

前两章讲过，Markdown 是纯文本，语法简单，文档结构能被人和程序读懂，也方便跨平台和用 Git 管理。这些特点让它适合写技术文档、课程和知识库，也让它能在 AI 协作里派上用场。

现在很多 AI 工具都会用标题、列表、代码块、表格和引用来组织回答，这些结构常常就是 Markdown。本章从代码检查开始，看看 Markdown 怎样整理输入、接住输出，再进入人与 AI、Agent 和自动化流程的协作。

Markdown 与 AI 协作全链路总览

3.1 AI 输入的结构

AI 处理文本时，拿到的主要是文字和其中的结构，不是人眼看到的页面效果。看下面这段没有分层的文字：

text

Python 入门  Python 是一种编程语言  安装 Python  下载 Python  编写第一个程序  使用 print 输出 Hello World

大意能猜出来，不过标题、说明和步骤混在了一起。改成 Markdown 后：

# Python 入门

Python 是一种编程语言。

## 安装 Python

下载并安装 Python。

## 第一个程序

使用 `print()` 输出内容：

```python
print("Hello World")
```

层次就清楚多了。标题能标出层级：

text

Python 入门
├── 安装 Python
└── 第一个程序

代码围栏则能标明内容类型：

text

Python 是一种编程语言。
→ 普通正文

print("Hello World")
→ Python 代码

几个简单标记，就把文档层级和正文、代码区分开了。

任务结构

把下面这段任务交给 AI：

# 任务

检查下面的 Python 代码。

## 检查要求

1. 检查语法错误；
2. 检查异常处理；
3. 检查变量命名；
4. 给出修改建议。

## 代码

```python
name = input("请输入姓名：")
print("你好" + name)
```

## 输出格式

### 问题

### 修改建议

这些标记各有分工：# 任务点明主题，## 检查要求列出约束，编号列表把要求拆成几件事；Python 代码放在代码围栏中，最后用“输出格式”说明回答该怎么组织。

AI 可能会这样回答：

## 问题

- 代码没有语法错误。输入“小明”时会输出“你好小明”。
- 直接按回车会输出“你好”；是否允许空姓名需要先明确。
- `input()` 在输入流结束时可能抛出 `EOFError`，是否处理取决于运行场景。
- 变量名 `name` 能说明用途，无需为了改名而修改。

## 修改建议

如果要求姓名不能为空，可以增加校验：

```python
name = input("请输入姓名：").strip()
if name:
    print(f"你好{name}")
else:
    print("姓名不能为空")
```

收到回答后，先看它有没有按“问题 / 修改建议”组织，再核对问题和建议是否符合代码实际行为及任务要求。这里还可以分别输入“小明”和空字符串运行修改后的代码，确认结果是否符合预期。如果任务允许空姓名，就不该直接采纳新增的校验。

Markdown 在这里不只是排版，它也给 AI 标出了任务、代码和输出要求各自的位置。

语义信号与注意力锚定：自然语言长难句 vs Markdown 结构化输入

长文定位

内容一长，标题就更有用了。比如：

# FastAPI 教程

## 第一部分 基础

### 安装

### 第一个应用

## 第二部分 路由

### GET 请求

### POST 请求

## 第三部分 数据验证

### Pydantic 模型

### 请求体

标题层级可以把长文整理成这样的结构：

text

FastAPI 教程
├── 第一部分 基础
│   ├── 安装
│   └── 第一个应用
├── 第二部分 路由
│   ├── GET 请求
│   └── POST 请求
└── 第三部分 数据验证
    ├── Pydantic 模型
    └── 请求体

所以我们可以把修改范围说得具体些：

只修改“第二部分路由”，不要修改其他章节。

还可以继续缩小范围：

只修改 ### POST 请求，保留其他标题和内容不变。

标题能帮忙定位，但不能保证 AI 只改了指定部分。收到结果后，还是要对照原文，确认第一、第三部分没有变化。

内容类型

一项 AI 任务里经常混着好几种材料：

任务说明；
背景；
示例；
代码；
数据；
约束条件；
输出格式。

全写成一段话容易看串。用 Markdown 分开写会清楚些：

# 任务

重写下面的课程内容。

## 写作要求

- 保持问题驱动；
- 不删除案例；
- 使用 Python 3.12；
- 不增加第三方库。

## 原始内容

> 这里放原文。

## 示例代码

```python
print("Hello")
```

## 输出要求

只输出修改后的 Markdown。

人和 AI 都能看出哪些是要求、原文、示例代码和输出格式。

代码边界

代码也最好和说明分开。比如不使用代码块时：

text

请修改下面代码 print("hello") 不要改变输出

代码一长，就容易和要求混在一起。放进代码块后：

请检查下面的代码：

```python
def hello(name):
    print(f"Hello, {name}")
```

要求：

1. 不改变函数名称；
2. 不增加第三方依赖；
3. 保留当前输出行为。

AI 更容易分清：

text

自然语言要求
↓
代码
↓
约束条件

所以 AI 编程工具里也常用 Markdown 来传递代码和要求。

3.2 AI 输出与内容复用

AI 通常不会把回答全塞进一个大段落，而是用标题、列表和代码块分开组织。比如：

## 原因

1. 第一个原因；
2. 第二个原因；
3. 第三个原因。

## 示例

```python
print("Hello")
```

## 总结

Markdown 非常适合结构化输出。

这样的格式读起来清楚，机器生成也简单：

机器生成的方便性和人类阅读的舒适性。

表达成本

比如输出 HTML 标题，要写：

html

<h2>安装方法</h2>

Markdown 只要：

## 安装方法

列表也是如此。HTML 需要：

html

<ul>
  <li>Python</li>
  <li>Java</li>
  <li>JavaScript</li>
</ul>

换成 Markdown：

- Python
- Java
- JavaScript

内容越多，少写一些标签、层次又清楚的好处越明显。

阅读与复用

AI 给出的内容通常先被人阅读：

text

AI
↓
用户阅读

也可能接着放进文档、项目或网站：

text

AI
↓
复制内容
↓
文档 / 项目 / 网站

Markdown 两边都能接住。比如 AI 输出：

## 安装

执行：

```bash
pip install fastapi
```

聊天界面能显示它；复制到 README.md、交给 VitePress 渲染，或存进 Obsidian，也都能继续用。

AI 结构化输出与多端二次复用流水线

3.3 提示词组织

刚开始用 AI 时，提示词可能会写成一长串：

text

帮我检查下面的课程内容不要删除案例标题保持原样代码使用python3.12不要用第三方库检查是否问题驱动如果不是帮我修改最后给我完整内容

简单任务这样写也许没问题，要求一多，AI 就可能弄不清：

哪个是原文，哪些是要求，哪些内容不能动，最后该怎么输出。Markdown 能把这些部分分开；前面代码检查的例子也是这个思路：

# 任务

检查并完善当前课程章节。

## 修改要求

- 保持问题驱动；
- 保留原有案例；
- 不删除已有图片；
- Python 版本使用 3.12；
- 不增加第三方库。

## 检查重点

1. 内容是否完整；
2. 是否存在知识错误；
3. 是否缺少必要前置条件；
4. 是否存在重复内容。

## 输出要求

只输出修改后的 Markdown。

这么写不只是版面整齐，任务边界也更容易看清。

提示词维护

一句话就能说清的提示词，不用特别排版。复杂任务的提示词可能越积越长，最后成了一份 prompt.md 文档，里面会写：

# 任务说明

## 角色

## 目标

## 输入

## 工作流程

## 规则

## 禁止事项

## 输出格式

## 示例

这时用 Markdown 组织，内容会更容易阅读、修改、复用，也方便用 Git 比较版本或和团队一起维护。

所以不少 AI 项目会把复杂提示词保存在 .md 文件里。

工程化提示词架构：模块化设计与 Git 版本演进

3.4 人机协作与修改边界

以前写作，通常是人直接完成文章：

text

人
↓
文章

现在让 AI 参与后，可能是人先写初稿，AI 修改，再由人接着调整：

text

人
↓
初稿
↓
AI
↓
修改
↓
人
↓
继续调整

也可能反过来，先让 AI 起草，人来修改，再请 AI 润色：

text

AI
↓
生成草稿
↓
人
↓
修改
↓
AI
↓
润色

要在人和 AI 之间来回传内容，Markdown 是一种顺手的格式。

修改范围

比如文章按下面的标题组织：

# 第一章 Python 简介

## 1.1 Python 是什么

## 1.2 Python 的特点

# 第二章 环境安装

## 2.1 Windows

## 2.2 Linux

可以直接告诉 AI：

只完善 ## 1.2 Python 的特点，其他章节保持不变。

标题能充当定位标记，还可以进一步限定：

保留现有标题层级，不新增一级标题。

或者只改其中一节的正文和代码：

只允许修改 ## 2.2 Linux 下的正文和代码。

按标题说范围，比描述 Word 文档的页码、段落更方便自动处理。不过标题只是线索，并不能保证 AI 没碰其他地方。拿到结果后，仍要检查 ## 1.2 Python 的特点 之外的内容。

人机协作双螺旋与修改边界隔离（Scope Guard）

文档结构

假如课程要求每章都有这些部分：

# 章节标题

## 学习目标

## 问题场景

## 知识讲解

## 案例

## 小结

## 练习

就可以要求 AI 修改时：

不能删除任何二级标题，只允许完善标题下面的内容。

这样一来，Markdown 标题既组织了文章，也说明了修改边界。批量处理时尤其方便；如果要求保留所有二级标题，改完还得逐项核对，光写进提示词里不够。

中间格式

一份内容可能要经过好几个环节，例如：

text

原始资料
   ↓
AI 整理
   ↓
Markdown
   ↓
人工修改
   ↓
AI 审查
   ↓
Markdown
   ↓
网站发布

Markdown 可以留在中间，等内容定下来后再发布到 VitePress：

text

AI
↓
chapter01.md
↓
VitePress
↓
课程网站

也可以交给 Pandoc 导出 Word：

text

AI
↓
report.md
↓
Pandoc
↓
report.docx

Markdown 不一定是最终交付格式，也可以作为内容生产流程里的中间层。

3.5 自动化与 Agent 协作

假设课程项目里有这些文件：

text

course/
├── chapter01.md
├── chapter02.md
├── chapter03.md
├── chapter04.md
└── chapter05.md

可以让程序按章节把文件交给 AI 审查、修改，再核对标题、代码和改动范围：

text

chapter01.md
      ↓
AI 审查
      ↓
生成修改建议
      ↓
AI 修改
      ↓
核对标题、代码和改动范围
      ↓
保存

chapter02.md
      ↓
重复流程

Markdown 是文本，程序按文件读取并传给 AI 很方便。一个简化的处理过程是：

text

读取文件
↓
发送给 AI
↓
获取 Markdown
↓
检查结果
↓
保存文件

过程中不用解析 Word 的复杂排版。

Agent 工作规则

普通聊天 AI 通常是问一句、答一句：

text

用户
↓
AI
↓
回答

Agent 则会围绕一个目标连续工作：

text

目标
↓
读取资料
↓
分析
↓
调用工具
↓
修改文件
↓
检查结果
↓
继续执行

Agent 工作时需要保存输入材料、任务说明、工作记录、中间结果、最终报告和规则。Markdown 都能装下这些内容。例如，Agent 可以读取项目中的 AGENTS.md，里面写明：

# 项目规则

## Python

使用 Python 3.12。

## 文档

所有课程使用 Markdown。

## 修改要求

- 不删除现有案例；
- 不改变标题层级；
- 修改后检查代码。

Agent 就能把这些内容当作长期工作规则。

Agent 交接格式

让一个 Agent 审查课程时，可以要求它把结果整理成固定格式：

# 审查结果

## 内容问题

- 问题 1
- 问题 2

## 代码问题

- 问题 1

## 修改建议

1. 建议一
2. 建议二

另一个 Agent 随后读取这份 Markdown：

text

审查 Agent
    ↓
suggestion.md
    ↓
修改 Agent

这样 Markdown 不只给人看，也能约定 Agent 之间怎样交接信息。后续程序如果依赖固定字段，仍要检查标题和内容是否符合约定。

知识库检索

很多 AI 系统会使用 RAG，也就是检索增强生成。

可以简单理解为：

text

大量文档
   ↓
搜索相关内容
   ↓
提供给 AI
   ↓
AI 回答

知识库如果用 Markdown 保存：

text

knowledge/
├── python.md
├── fastapi.md
├── flask.md
└── docker.md

程序就能按标题或章节切分内容，也能提取代码和链接、建立索引。比如：

## FastAPI 路由

这里介绍路由。

## FastAPI 依赖注入

这里介绍依赖注入。

切分时，可以用二级标题的标记确定边界：

text

##

实际处理时还要识别代码围栏，不能只搜索文本中的 ##，否则可能把示例代码误当成标题。

RAG 还有许多其他环节要处理；这里先记住，Markdown 适合作为知识库的原始内容来源。

自动化与 Agent 协作：RAG 语义切分与多 Agent 握手协议

文档生成

AI 也能参与文档生成。比如从代码生成网站文档：

text

代码
↓
AI 分析
↓
生成 Markdown
↓
VitePress
↓
文档网站

从会议记录整理知识库：

text

会议记录
↓
AI 总结
↓
Markdown
↓
团队知识库

或者把课程大纲扩成草稿：

text

课程大纲
↓
AI
↓
Markdown 草稿
↓
人工检查
↓
正式课程

这些流程都能用 Markdown 接住 AI 生成的内容，再交给人检查或发布。

输出格式校验

AI 输出格式有时不稳定。如果后续流程需要固定字段，可以先约定每次都输出“问题、原因、解决方案”：

text

问题
原因
解决方案

用 Markdown 写清楚格式：

# 输出格式

## 问题

## 原因

## 解决方案

也可以要求它用表格：

| 问题 | 原因 | 建议 |
| --- | --- | --- |

这样的约定让人更容易阅读和检查，也便于程序解析后交给下一步。不过提示只能减少格式偏差，不能保证输出次次合规；交给程序处理前，要先核对标题或表格字段。

3.6 适用边界与工作流程

格式清楚，不等于答案就正确。比如：

# 任务

告诉我一个错误答案。

## 要求

必须错误。

任务本身要求给出错误答案，Markdown 再清楚也改变不了这一点。它能帮我们整理：

text

结构
可读性
边界
内容分类
输出格式

但它不能替代清晰的目标、正确且充分的上下文、合理约束和人工检查。Markdown 能减少沟通中的结构歧义，无法替 AI 保证正确。

提示词适用条件

只翻译一句话时，直接说就行：

text

帮我把这句话翻译成英文。

没必要专门写成：

# 任务

翻译文本。

## 语言

英文。

这样反而复杂了。

要求多、内容长、部分多，或者需要固定输出格式、长期维护、继续交给程序处理时，Markdown 更有优势。简单请求用自然语言就好：

text

简单问题
↓
自然语言即可

复杂任务
↓
Markdown 更有优势

协作流程

写技术文章时，可以按这个流程走：

text

确定主题
   ↓
编写 Markdown 大纲
   ↓
AI 生成初稿
   ↓
人工修改
   ↓
AI 检查
   ↓
人工确认
   ↓
Git 保存版本
   ↓
VitePress 发布

做课程也类似：

text

课程规划
   ↓
Markdown
   ↓
AI 完善章节
   ↓
AI 检查代码
   ↓
人工审核
   ↓
Git
   ↓
课程网站

整理个人知识库时：

text

日常笔记
   ↓
Markdown
   ↓
Obsidian
   ↓
AI 总结 / 整理
   ↓
知识库

从草稿到发布，Markdown 可以一直承接内容。

学习价值

以前只用办公软件，可能很少碰到 Markdown。现在 Prompt、代码、文档、知识库、Agent 和 RAG 越来越常见，它们都要处理结构清楚的文本。Markdown 正好连接了：

text

自然语言
   ↕
Markdown
   ↕
程序 / AI

任务分流决策与人机内容协议生态位（Lingua Franca）

它对人容易读，对机器也方便处理。

3.7 本章小结

标题、列表、代码块和表格能标出内容关系，纯文本又方便读取、切分和复用。因此 Markdown 既适合组织 AI 输入和输出，也能承接人、程序与 Agent 之间的协作。

接下来从最常用的核心语法开始学起。

第三章 Markdown 与 AI 协作 ​

3.1 AI 输入的结构 ​

任务结构 ​

长文定位 ​

内容类型 ​

代码边界 ​

3.2 AI 输出与内容复用 ​

表达成本 ​

阅读与复用 ​

3.3 提示词组织 ​

提示词维护 ​

3.4 人机协作与修改边界 ​

修改范围 ​

文档结构 ​

中间格式 ​

3.5 自动化与 Agent 协作 ​

Agent 工作规则 ​

Agent 交接格式 ​

知识库检索 ​

文档生成 ​

输出格式校验 ​

3.6 适用边界与工作流程 ​

提示词适用条件 ​

协作流程 ​

学习价值 ​

3.7 本章小结 ​

第三章 Markdown 与 AI 协作

3.1 AI 输入的结构

任务结构

长文定位

内容类型

代码边界

3.2 AI 输出与内容复用

表达成本

阅读与复用

3.3 提示词组织

提示词维护

3.4 人机协作与修改边界

修改范围

文档结构

中间格式

3.5 自动化与 Agent 协作

Agent 工作规则

Agent 交接格式

知识库检索

文档生成

输出格式校验

3.6 适用边界与工作流程

提示词适用条件

协作流程

学习价值

3.7 本章小结