doc-map-source

# Doc Map Source

基于现有文档大纲批量创建任务，将技术文档深化为精确映射底层源码实现的单文件技术报告。

## 使用方式

```
/batch 根据大纲 <path/to/site-directory.md>，逐个页面创建任务，目前已经有了 <path/to/existing-report.md>。输出到 <docs/.report/>。
```

## 上下文

从用户输入或上下文抽取以下变量：
- **大纲文件**：包含文档站点目录结构的 Markdown 文件（如 `site-directory.md`）
- **已有报告**：已完成的参考报告路径（可选，用于对齐风格和质量标准）
- **输出目录**：默认为 `docs/.report/`，以 `<num>-<name>.md` 命名
- **源码根目录**：项目主源码目录（如 `rust/`、`src/`、`packages/` 等）
- **核心模块/包**：需要重点调研的 crate、package 或子目录名称列表

## 工作流程

### 1. 解析大纲

读取大纲文件，提取所有待撰写的页面 URL、标题和顺序编号。跳过已有报告的页面。

### 2. 逐个页面创建研究任务

对每个未完成的页面，执行以下两人研究团队任务。

---

## 队员 A：文档撰写者

**任务**：将目标页面文档深化为一份**单文件**技术报告，标题和 `##` 必须与原文文档一致，直接映射到当前项目的源码实现。

**输出要求**：
- **必须是单个文件**：`docs/.report/<num>-<name>.md`
- **严禁拆分为多个章节文件**
- 使用 `/doc-coauthoring` 技能结构化撰写
- **严格基于原文 ToC 深化**，为每个主要章节增加 `###` 子节，深入解释对应的源码实现细节；**不要重新组织成新的文章结构**

**源码映射要求**：
- 部署 3~4 个子代理调研目标项目源码，聚焦核心模块/包
- 所有源码链接必须指向仓库内文件，格式为：`[file.ext](/<source-root>/<module>/path/to/file.ext#LXX-LYY)`
- **链接必须使用 `#LXX-LYY` 行号锚点**，且行号必须精确，确保点击后可以直接跳转到源码对应位置
- 不要使用相对路径链接（如 `../src/`），必须使用仓库根目录的绝对路径形式

---

## 队员 B：批判性审校者

**任务**：以开源社区可交付标准，对 `docs/.report/<num>-<name>.md` 进行多轮严格审校。

**审校重点**：
1. **技术准确性**：每个技术描述必须与源码事实一致
2. **链接可验证性**：所有源码链接必须可点击且行号正确
3. **单文件完整性**：检查是否出现多余的 `.md` 拆分文件
4. **架构描述**：特别注意函数调用链、职责归属、配置/文件名等容易误植的细节

**工作流程**：
- 使用 `sed -n` 或等效方式直接抽查 4 个以上关键锚点，验证行号未漂移
- 发现错误后，立即在 `REVIEW.md`（与报告同目录）中记录问题级别（Blocker/Warning/Nit）、原文、修正方案
- Blocker 和 Warning 必须在文档中同步修正
- 行号漂移、路径错误、源码字符串引用不一致等问题应零容忍
- 审校结束后更新 `REVIEW.md` 结论，明确修正总数和最终评定

---

## 注意事项

- 如果已有报告存在，以其质量为基准对齐后续输出
- 审校者应在每轮审校后向撰写者反馈，确认修正后再进入下一轮
- 不要直接交付存在 Blocker 或 Warning 的文档