# 第一阶段 · 模块一 · 第七节：MagicDocs 自动文档
什么是 MagicDocs？Claude Code 如何自动维护文档？文档更新是如何触发的？MagicDocs 的工作流程是什么？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 服务层（services/） │
│ │
│ MagicDocs ← 本节 │
│ ├── 自动文档检测 │
│ ├── 后台子代理更新 │
│ └── 文档版本管理 │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/services/MagicDocs/magicDocs.ts` 第 1-7 行
/**
* Magic Docs automatically maintains markdown documentation files marked with special headers.
* When a file with "# MAGIC DOC: [title]" is read, it runs periodically in the background
* using a forked subagent to update the document with new learnings from the conversation.
*/
MagicDocs 是一个自动文档维护系统，它允许开发者通过特殊标记来声明文档，并由 Claude Code 在后台自动更新。
┌─────────────────────────────────────────────────────────────────────┐
│ MagicDocs 核心思想 │
│ │
│ 1. 声明式文档：开发者标记文档位置 │
│ 2. 自动维护：Claude Code 后台更新 │
│ 3. 学习积累：对话中的新知识写入文档 │
│ 4. 子代理执行：不干扰主对话流程 │
└─────────────────────────────────────────────────────────────────────┘
问 1：MagicDocs 和普通注释有什么区别？
// 普通注释：
// - 手动编写，容易过时
// - 需要人工维护
// - 注释和代码容易失去同步
// MagicDocs：
// - 自动更新，无需人工干预
// - 基于对话内容更新
// - 保持文档和代码同步
源码位置：`magicDocs.ts` 第 25-27 行
// Magic Doc header pattern: # MAGIC DOC: [title]
const MAGIC_DOC_HEADER_PATTERN = /^#\s*MAGIC\s+DOC:\s*(.+)$/im
// Pattern to match italics on the line immediately after the header
const ITALICS_PATTERN = /^[_*](.+?)[_*]\s*$/m
# MAGIC DOC: 项目架构文档
_本文档由 Claude Code 自动维护，更新于每次重要对话后_
## 功能模块
本文档记录了项目的核心功能模块...
标记规则：
┌─────────────────────────────────────────────────────────────────────┐
│ 1. 必须以 # MAGIC DOC: 开头（不区分大小写） │
│ 2. 标题后必须跟斜体内容作为指令 │
│ 3. 文件必须是 Markdown 格式 │
│ 4. 文档路径必须被 Claude Code 读取过 │
└─────────────────────────────────────────────────────────────────────┘
问 1：为什么使用斜体作为指令格式？
// 选择斜体的原因：
// 1. 视觉区分度高
// - 斜体在 Markdown 中易于识别
// - 不会干扰文档的主要内容
// 2. 语法简洁
// - _text_ 或 *text* 都支持
// - 不会与代码块混淆
// 3. 语义清晰
// - 斜体表示"说明"或"注释"
// - 符合指令的语义预期
源码位置：`magicDocs.ts` 第 52-75 行
export function detectMagicDocHeader(
content: string,
): { title: string; instructions?: string } | null {
const match = content.match(MAGIC_DOC_HEADER_PATTERN)
if (!match || !match[1]) {
return null
}
const title = match[1].trim()
// Look for italics on the next line
const nextLineMatch = afterHeader.match(/^\s*\n(?:\s*\n)?(.+?)(?:\n|$)/)
if (nextLineMatch && nextLineMatch[1]) {
const italicsMatch = nextLine.match(ITALICS_PATTERN)
if (italicsMatch && italicsMatch[1]) {
return { title, instructions: italicsMatch[1].trim() }
}
}
return { title }
}
检测流程：
1. 正则匹配 MAGIC DOC 标记
↓
2. 提取标题内容
↓
3. 查找下一行的斜体内容
↓
4. 返回 { title, instructions }
问 1：检测失败的原因有哪些？
// 检测失败的常见原因：
// 1. 标记格式错误
// - 缺少 # 前缀
// - 拼写错误：MAGIC DOC vs MAGICDOC
// 2. 标题格式错误
// - # MAGIC DOC:后面没有内容
// - 标题包含非法字符
// 3. 缺少斜体指令
// - 斜体内容不在标题后第一行
// - 斜体格式不正确
源码位置：`magicDocs.ts` 第 85-92 行
const trackedMagicDocs = new Map<string, MagicDocInfo>()
export function registerMagicDoc(filePath: string): void {
if (!trackedMagicDocs.has(filePath)) {
trackedMagicDocs.set(filePath, { path: filePath })
}
}
interface MagicDocInfo {
path: string // 文件路径
title: string // 文档标题
instructions?: string // 更新指令
lastUpdate?: Date // 最后更新时间
version: number // 文档版本号
}
┌─────────────────────────────────────────────────────────────────────┐
│ 文档跟踪生命周期 │
│ │
│ 读取文件 → 检测标记 → 注册跟踪 → 后台更新 → 版本管理 │
│ │
│ 1. 读取：文件被读取时触发检测 │
│ 2. 检测：验证是否为 MagicDoc │
│ 3. 注册：加入跟踪列表 │
│ 4. 更新：后台子代理定期更新 │
│ 5. 版本：维护文档版本历史 │
└─────────────────────────────────────────────────────────────────────┘
问 1：为什么要跟踪文档？
// 跟踪的目的：
// 1. 避免重复更新
// - 同一文档不需要同时更新
// - 控制更新频率
// 2. 管理更新状态
// - 记录最后更新时间
// - 控制并发更新
// 3. 版本管理
// - 追踪文档变化
// - 支持回滚操作
// MagicDocs 使用子代理进行后台更新
// 更新流程：
async function updateMagicDoc(filePath: string) {
// 1. 启动子代理
const subagent = await spawnSubagent({
task: 'update-documentation',
context: { filePath }
})
// 2. 子代理分析对话内容
const learnings = await subagent.analyzeLearnings()
// 3. 更新文档
await subagent.updateDocument(learnings)
}
更新触发条件：
┌─────────────────────────────────────────────────────────────────────┐
│ 触发条件 │
│ │
│ 1. 文件被读取后 5 分钟 │
│ 2. 对话中有新的相关知识点 │
│ 3. 子代理空闲时 │
│ 4. 用户主动请求更新 │
└─────────────────────────────────────────────────────────────────────┘
// 更新策略：智能合并
// 1. 分析新增内容
// - 从对话中提取新知识点
// - 识别文档已有内容
// 2. 冲突处理
// - 新内容覆盖旧内容
// - 保留用户手动编辑的部分
// 3. 格式保持
// - 保持原有 Markdown 格式
// - 只更新指定区域
问 1：更新会破坏用户编辑的内容吗？
// 更新安全性：
// 1. 增量更新
// - 只更新 MAGIC DOC 标记的区域
// - 不会修改其他内容
// 2. 保留用户编辑
// - 非标记区域不受影响
// - 用户可以在标记外自由编辑
// 3. 版本备份
// - 更新前自动备份
// - 支持手动回滚
# MAGIC DOC: 项目架构文档
_本文档记录项目的整体架构和模块关系，自动更新于每次架构变更后_
## 模块关系
| 模块 | 职责 | 依赖 |
|------|------|------|
| auth | 认证授权 | db |
| api | API 路由 | auth, db |
| worker | 后台任务 | queue, db |
// 使用 MagicDocs 维护 API 文档
// 当新的 API 端点创建时，自动更新文档
# MAGIC DOC: 技术决策记录
_记录所有重要的技术决策及其原因_
## ADR-001: 选择 TypeScript
原因：静态类型检查提高了代码质量...
答案：
// 适用场景：
// 1. 快速迭代的项目
// - 代码变化频繁
// - 文档容易过时
// 2. 知识积累型项目
// - 需要记录决策过程
// - 团队知识传承
// 3. 自动化运维
// - 基础设施文档
// - 部署流程文档
// 不适用场景：
// 1. 静态文档
// - 不经常变化的文档
// - 人工审核要求高
// 2. 敏感内容
// - 包含机密信息
// - 不适合自动更新
答案：
// 确保质量的方法：
// 1. 指令明确
// - 在斜体内容中指定更新规则
// - 例如：_仅更新接口描述，不修改代码示例_
// 2. 版本审查
// - 定期检查自动更新的内容
// - 人工审核关键变更
// 3. 回滚机制
// - 保留历史版本
// - 支持快速回滚
// 4. 增量更新
// - 小步更新，避免大范围修改
// - 便于定位问题
答案：
// 传统文档生成工具（如 JSDoc、Swagger）：
// 优点：
// - 从代码注释自动生成
// - 与代码同步
// 缺点：
// - 需要在代码中添加注释
// - 主要生成 API 文档
// - 无法记录设计决策
// MagicDocs：
// 优点：
// - 不需要修改代码
// - 记录设计决策和上下文
// - 基于对话内容更新
// - 更灵活的应用场景
// 缺点：
// - 需要特殊标记
// - 更新时机依赖对话
| 资源 | 说明 |
| `src/services/MagicDocs/magicDocs.ts` | MagicDocs 核心实现 |
| `src/agents/SubAgent.ts` | 子代理实现 |
| 子代理系统 | 后台任务执行 |
下一节我们将进入 Bridge 远程控制：
- 设备桥接机制
- 远程会话同步
- 跨设备状态管理
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*