lionad-morotar/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 的文档