用途:在 docker/docs 仓库中,对某个文档主题或 GitHub issue 做彻底调研,产出明确的修复计划,目标是找出确切文件、文件内的具体名称目标,以及修复所需的已核实内容。调研质量决定写作质量,含糊调研导致大范围改动,精确调研得到最小改动。
主要能力与流程:
- 收集上下文。若输入是 GitHub issue 编号,用 gh issue view <number> --repo docker/docs --json number,title,body,labels,comments 获取;否则依据提供的描述、URL、问题或对话上下文确定要调查的主题、功能或页面。
- 定位受影响文件。用 issue 中的 URL 或主题检索 content/,注意 URL 转文件路径时的 /manuals 前缀映射;逐个读取候选文件的相关小节,确认其中确实包含所报告的问题。
- 检查可编辑归属。编辑前确认文件可在本地编辑:_vendor/ 为只读(经 Hugo modules vendored)、data/cli/ 为只读(由上游 YAML 生成)、content/reference/cli/ 为只读(由 data/cli/ 生成);content/ 中其余内容可编辑。若修复需上游改动,需指出上游仓库并标注为超出范围。
- 查找相关内容:链接到受影响内容的页面、页面引用的 content/includes/ 文件、同一章节描述同一功能的相邻页面。
- 核实事实:若 issue 对功能行为提出事实性主张,需验证(跟踪外链、阅读上游源码、查发布说明);不得基于未核实的主张规划修复;若修复需替换 URL 且该 URL 无法验证(如网络限制),应作为阻塞项报告而非猜测。
- 必要时检查线上站点,对 URL 或渲染问题抓取 https://docs.docker.com/<path>/。
- 报告发现:汇总需改的文件、各文件中的具体问题、应做的修复及约束,为后续写作步骤提供直接上下文。
限制与注意:报告需具体到文件、章节或元素及已核实内容(例如指出在 compose/networking.md 的 “Custom networks” 小节删除关于 driver_opts 被忽略的说明,因为该问题已在 Compose 2.24 修复)。不要创建独立的调研文件,发现仅保留在对话上下文中供写作步骤使用。