docs-steward

Docs Steward

在项目本地仓库中维护文档质量、架构和框架时效性。

输入： $ARGUMENTS — 模式关键词、框架名称、迁移目标或自然语言文档请求。

---

规范术语

在 docs-steward 输出中始终准确使用以下规范术语。

术语	含义	非规范用法
docs framework	用于呈现文档的主要平台（Starlight、Docusaurus、Fumadocs、Sphinx、MkDocs）	“站点生成器”（范围过广）
theme layer	叠加在框架之上的视觉样式和组件外观	“框架”
content graph	导航 + 页面关系 + 生成的索引	“文件夹列表”
init	在现有仓库中以非破坏方式引导文档	“重新初始化/覆盖”
sync	根据源文档状态重新生成框架产物	“部署”
maintain	对结构、链接、偏差和构建完整性进行只读健康检查	“重写”
enhance	改进现有文档的清晰度、结构、用户体验和可发现性	“重新创建”
matrix run	在一个仓库中执行所有已检测框架的工作流	“自动”
migration	将一个 docs framework 迁移到另一个框架，并进行一致性检查	“即时转换”
version refresh	将参考知识更新到最新稳定版框架/工具版本	“盲目升级”
project-local	技能在当前项目范围内安装和使用	“全局安装”

---

分派表

将 $ARGUMENTS 路由到对应模式：

$ARGUMENTS 模式	模式	从以下模式开始
（空）或 auto	Auto	模式 A
framework <name> <action>（<action> ∈ `sync	enhance	maintain
framework <name>	Framework-targeted（默认操作：maintain）	模式 B
init / init <name>	Init	模式 I
init-sync / init-sync <name>	Init+Sync	模式 I
sync / sync <name>	Sync	模式 C
enhance / enhance <path>	Enhance	模式 D
maintain / maintain <name>	Maintain	模式 E
research / research versions	Research	模式 F
matrix	Matrix	模式 G
migrate <from> -> <to>	Migrate	模式 H
generate api <module>	Generate	模式 J
generate adr <decision>	Generate	模式 J
generate runbook <process>	Generate	模式 J
generate onboard	Generate	模式 J
generate glossary	Generate	模式 J
自然语言：“generate API docs/reference”	Generate	模式 J
自然语言：“create an ADR/decision record”	Generate	模式 J
自然语言：“write a runbook/onboarding guide”	Generate	模式 J
自然语言：“set up <framework> docs from scratch and keep it in sync”	Init+Sync	模式 I
自然语言：“docs are stale/broken/outdated”	Maintain	模式 E
自然语言：“improve docs UX/content/nav”	Enhance	模式 D
自然语言：“upgrade latest framework versions”	Research	模式 F
自然语言：“update README”、“sync AGENTS.md”、“refresh docs instructions”	Auto	模式 A 文档表面路由
构建应用 API、技能或 MCP 服务的请求	拒绝	重定向

分类门控模式

在任何会修改内容的模式运行前，应用此分类门控规则。

1. 使用 references/framework-detection.md 检测框架。
2. 如果检测到一个框架，则继续使用该框架。
3. 如果检测到多个框架，且用户未指定目标，则每次运行都询问用户选择（交互模式）。
4. 如果没有框架信号，则在编辑前询问用户使用的文档技术栈（交互模式）。
5. 如果运行处于无头/非交互模式，则应用无头回退约定。

无头回退契约

无法进行澄清对话时：

1. 如果框架目标不明确，或检测到多个框架但未明确指定目标，则以只读的 Mode G (Matrix) 方式运行 Mode E (Maintain)，检查所有检测到的框架。
2. 只有在框架选择明确，或高置信度地检测到单一框架，且触发类别符合 Mode A 安全要求时，才允许执行会产生变更的自动路径。
3. 按确定性顺序处理框架：starlight/astro、docusaurus、fumadocs、sphinx、mkdocs。
4. 应用无头回退后，发出警告，说明在等待明确选择框架期间，已跳过会产生变更的模式（init、init-sync、sync、enhance、research、migrate）。
5. 如果未检测到任何框架，则返回只读的维护报告，注明“framework target required”，且不进行任何编辑。

---

实时版本研究（请求“最新”版本时必需）

当用户明确或隐含地请求最新版本时，应用变更前务必刷新版本信息：

1. 使用工具辅助检查查询软件包注册表（npm/PyPI）。
2. 更新 references/*.md 中的框架参考快照。
3. 在编辑后的参考文件中记录版本来源和日期。
4. 然后才提出依赖项或配置更新建议。

没有当前注册表数据作为依据时，绝不要声称是“最新”版本。

---

Mode A：自动

默认的编排器模式。

A.1 触发类别

选择模式前，先对检测到的变更信号进行分类：

• 仅内容： 页面文案／示例／frontmatter 编辑，不影响导航／配置／构建。
• 结构／配置： 文档／框架／配置／导航／构建相关变更（侧边栏／导航树、框架配置、文档构建接线、生成的文档产物）。
• 依赖项／版本： 文档框架／主题／插件依赖项或锁文件／版本变更。
• 文档表面： 项目 README、嵌套的 AGENTS.md、生成的文档索引，或必须反映文档行为变更的贡献者文档。

A.2 操作路径

1. 检测文档框架。
2. 如果存在多个框架，询问本次要操作哪个框架。
3. 按触发类别分流：
   • 仅内容 -> Mode D (Enhance)，然后可选执行 Mode E (Maintain) 检查。
   • 结构／配置 -> Mode C (Sync) + Mode E (Maintain)。
   • 依赖项／版本 -> Mode F (Research) + Mode C (Sync) + Mode E (Maintain)。
   • 文档表面 -> 如果生成／接线发生变更，则执行 Mode C (Sync)；否则执行 Mode D (Enhance) + Mode E (Maintain)。
4. 如果触发类别或意图不明确，则在编辑前提出一个有针对性的澄清问题。

A.3 自动同步安全要求

1. 只有在框架目标明确，或高置信度地检测到单一框架时，才允许自动同步。
2. 在无头且目标不明确的多框架运行中，保留只读回退（Mode E 矩阵）；不要自动同步。
3. 如果置信度较低、框架信号冲突，或范围不局限于文档，则降级为 Mode E (Maintain)。

---

Mode B：指定框架（framework <name> [<action>]）

支持的名称：

• astro / starlight
• docusaurus
• fumadocs
• sphinx
• mkdocs

语法：framework <name> [<action>]，其中 <action> 可以是 sync、enhance、maintain、research 或 migrate。 如果省略 <action>，则默认为 maintain。 对所选框架运行映射的模式：sync -> Mode C、enhance -> Mode D、maintain -> Mode E、research -> Mode F、migrate -> Mode H。

---

Mode C：同步

使生成的文档产物保持一致。

• 验证对框架原生高级组件及其渲染方式的支持（Mermaid、代码片段、表格、嵌入内容、标签页／提示框）。

C.1 Astro + Starlight

• 验证 Astro 配置和 Starlight 集成。
• 使用项目命令重新生成文档产物（本仓库使用：python scripts/docs_sync.py generate）。
• 对文档输出执行构建检查。

C.2 Docusaurus

• 验证 docusaurus.config.*、侧边栏和文档路由结构。
• 重新构建生成的文档资源，并执行构建健全性检查。

C.3 Fumadocs

• 验证 next.config.*、fumadocs-* 包配置和 MDX 内容树。
• 在适用情况下重新生成索引和导航，并运行 Next 构建检查。

C.4 Sphinx

• 验证 conf.py、扩展集和主题包是否匹配。
• 启用严格警告进行构建，以满足文档质量门禁要求。

C.5 MkDocs

• 验证 mkdocs.yml、插件栈和导航结构。
• 运行严格构建检查并检测插件变动。

C.6 同步输出规范

• 提供“高级组件渲染检查”摘要，涵盖 Mermaid、代码片段、表格、嵌入内容以及标签页／提示框。
• 说明所用的框架专属支持／插件，并标记不受支持的组件及其安全回退方案。
• 提供无障碍说明（图表文本替代内容、有标签的代码围栏、有标题的嵌入内容，以及标签页／提示框语义）。

---

模式 D：增强

在不改变框架身份的前提下提升文档质量。

增强目标：

• 信息架构（导航清晰度、章节深度、落地页）
• 写作质量（易于浏览、示例、API／任务导向）
• 内部链接（减少孤立页面、相关链接策略）
• 文档视觉体验（提示框、标签页、代码分组、告示框、图表、嵌入内容、表格）
• 一致性（风格、标题层级、frontmatter、元数据）

如果增强方向不明确（“开发者文档”“营销文档”“API 文档”或“教程文档”），请提出澄清问题。

D.1 高级组件策略

• 仅在高级组件能实质性提升理解时使用，避免仅用于装饰。
• 为当前技术栈选择框架原生的基本组件，并在每个页面中保持语法和风格一致。
• 优先使用：Mermaid 绘制流程／架构图，代码片段展示实施步骤，表格进行比较，嵌入内容呈现权威演示／媒体，标签页／提示框呈现不同方案和注意事项。
• 保持输出无障碍：为图表添加通俗易懂的上下文和文本回退，为代码块标注语言，提供有意义的说明／标题，并避免仅靠颜色或标签页呈现关键信息。
• 使用 references/advanced-components.md 查阅框架专属语法模式和安全回退方案。

D.2 增强输出规范

• 总结新增／更新了哪些高级组件、它们的作用，以及框架限制或回退方案。

---

模式 E：维护

只读诊断和修复规划。

检查项：

1. 失效链接和锚点偏移
2. 过时／生成文件不匹配
3. 导航死胡同和孤立页面
4. 主题／插件依赖变动
5. 构建警告／错误
6. 混合代码库中的框架不匹配

输出格式：

• 严重问题（必须修复）
• 警告（应当修复）
• 建议（可选优化）
• 后续要运行的命令

---

模式 F：研究

将框架／主题参考资料更新至最新稳定版本和高级模式。

工作流：

1. 确认各个启用框架的包／版本信息。
2. 更新参考快照章节。
3. 注明与迁移相关的变化（破坏性变更、弃用的 API、配置调整）。
4. 返回简洁的变更摘要，并附上置信度和引用／来源命令。

---

模式 G：矩阵

在代码库中对所有检测到的框架执行受控运行。

适用场景：

• 使用多个文档技术栈的单体代码库
• 并行迁移项目
• 框架一致性审计

矩阵运行的输出必须按框架分组，并包含跨框架冲突。

---

模式 H：迁移（migrate <from> -> <to>）

迁移纳入 v1 范围。

支持的路径：

• Docusaurus -> Fumadocs
• Sphinx -> MkDocs
• Sphinx -> Starlight
• MkDocs -> Docusaurus

迁移阶段：

1. 清点内容并建立一致性基线
2. 映射内容和导航
3. 映射主题／组件
4. 构建／测试一致性检查
5. 制定渐进式上线计划

不要承诺一次性完成全部转换；优先采用分阶段迁移并设置检查点。

---

模式 I：初始化（init、init <framework>、init-sync、init-sync <framework>）

在现有代码库中搭建文档站点配置，不进行破坏性重写。 此模式适用于明确的 init* 命令，以及在现有代码库中提出的“搭建文档并保持同步”请求。 编辑前，请加载 references/init-sync-existing-repos.md 和所选框架的参考文档。

I.1 框架选择行为

1. 如果提供了 <framework>，则直接以该框架为目标。
2. 如果未提供 <framework>，且只检测到一个框架，则以检测到的框架为目标。
3. 如果检测到多个框架，且未明确指定目标，则询问用户选择；在无头运行中，应用 Headless Fallback Contract。
4. 如果未检测到框架，且未明确指定目标，则请用户选择受支持的框架；在无头运行中，返回只读的模式 E 输出，并注明“需要指定框架目标”。

I.2 非破坏性搭建约定

• 仅创建缺失的文档脚手架／配置文件；默认不覆盖现有文件。
• 预检保护：如果目标文档根目录已存在且非空，不要重新创建或替换该目录；除非用户明确要求覆盖，否则只在原目录中补建缺失文件。
• 存在现有文档内容、导航和框架配置时，应予以保留。
• 如果请求的框架与现有文档框架配置冲突，则停止并返回维护发现和冲突摘要（迁移请使用模式 H）。

I.3 后续流程

• init：完成搭建后，建议后续执行 sync 和 maintain。
• init-sync：完成搭建后，在同一次运行中执行模式 C（同步）和模式 E（维护）。
• 始终报告创建了哪些内容、跳过了哪些内容，以及原因。

---

模式 J：生成（generate <type> [<target>]）

根据源代码生成技术文档。详细流程、输出格式和脚本用法请加载 references/generate-mode.md。

子模式：

命令	输出	关键脚本
generate api <module>	包含签名、文档字符串和覆盖率的 API 参考文档	api-surface-extractor.py、doc-coverage-analyzer.py
generate adr <decision>	MADR 格式的架构决策记录	adr-scaffolder.py
generate runbook <process>	包含代码库中命令的运维手册	—
generate onboard	新贡献者入门指南	—
generate glossary	从代码和文档中提取的术语定义	—

J.1 工作流

1. 确定目标范围（模块路径、流程名称或整个代码库）。
2. 运行适用脚本，从源代码中提取结构化数据。
3. 按照 references/generate-mode.md 中的格式，将提取的数据整理为文档。
4. 提交草稿供审阅。如果上下文含糊不清，请提出澄清问题。
5. 将输出写入合适的位置（例如 docs/api/、docs/decisions/）。

J.2 生成输出约定

• 生成的文档必须能够追溯到源代码（包含文件路径和行号）。
• 绝不编造 API 签名或文档字符串；应从源代码中提取，或标记为未记录。
• ADR 遵循 data/adr-template.json 中的 MADR v3 格式。
• 根据项目使用的语言和风格，采用 data/docstring-formats.json 中的文档字符串格式约定。

---

范围边界

**范围内：**文档框架操作、非破坏性文档搭建、版本更新、构建／健康诊断、质量改进、文档迁移、根据代码生成技术文档、项目 README 更新，以及在文档行为发生变化时更新嵌套的 AGENTS.md 指令文档。

不适用于：

• 创建／编辑无关的产品功能或后端 API
• 创建或更改技能定义、Agent 或 MCP 服务（转交给 skill-creator、agent-conventions 或 mcp-creator）
• 文档流水线需求之外的 CI/CD 重新设计
• 非文档类前端应用实现

---

扩展策略

范围	执行策略	归属规则
1 个框架和 1-3 个文档文件	直接编辑，然后运行框架专属验证	由一个 Agent 负责所有已修改的文件
1 个框架和 4-12 个文档文件	按文档区域分批：导航/配置、生成的参考文档、正文页面、README/AGENTS.md	切勿将同一个文件分配给多个工作者
2-5 个框架或 13 个以上文档文件	按确定的框架顺序分轮执行矩阵任务，然后汇总维护报告	每个框架或文件批次由一名工作者负责；仅在验证后合并
任何迁移或版本刷新	先设置计划检查点，再分阶段编辑并记录回滚说明	在确认一致性之前，保持源文档根目录和目标文档根目录可追踪

---

参考文件索引

按需加载参考文件；不要一次全部加载。

文件	内容	加载时机
references/framework-detection.md	框架信号映射、多框架路由规则	所有模式
references/advanced-components.md	各框架的 Mermaid/代码块/表格/嵌入模式及安全回退方案	sync/enhance
references/init-sync-existing-repos.md	面向现有仓库的非破坏性、框架感知型引导和后续同步工作流	init/init-sync
references/astro-starlight.md	Astro + Starlight 高级设置和检查	framework/sync/maintain/enhance
references/docusaurus.md	Docusaurus 高级配置和插件检查	framework/sync/maintain/enhance
references/fumadocs.md	Fumadocs + Next 高级设置和检查	framework/sync/maintain/enhance
references/sphinx.md	Sphinx + 主题矩阵（Shibuya/PyData/Furo/Book）	framework/sync/maintain/enhance
references/mkdocs.md	MkDocs + Material/插件栈检查	framework/sync/maintain/enhance
references/migrations.md	迁移手册和一致性模板	migrate/matrix
references/version-refresh.md	最新版本刷新工作流和证据规则	调研 + 任何最新版本请求
references/generate-mode.md	Generate 子模式流程、输出格式、脚本用法	generate
data/docstring-formats.json	各语言的文档字符串格式标准（Google、NumPy、Sphinx、JSDoc、TSDoc）	generate api
data/adr-template.json	MADR v3 模板结构和文件命名约定	generate adr

---

验证约定

完成标准：

1. 已修改的文档内容有源代码依据，且仅限于项目本地。
2. 修改模式运行相关的框架构建、文档生成或健康检查。
3. Maintain 模式保持只读，并报告后续命令，而不进行编辑。
4. 在适用情况下，技能变更须通过以下验证命令：
   • python scripts/check.py
   • 如果生成的文档内容发生变化，则运行 python scripts/docs_sync.py

---

关键规则

1. 用户意图或目标框架不明确时，编辑前至少提出一个澄清问题。
2. 在多框架仓库中，除非用户明确指定，否则每次运行时 auto 模式都必须询问要操作哪个框架。
3. 没有最新的、由注册表支持的证据和参考快照更新时，绝不声称版本是“最新”。
4. 默认仅在项目本地执行操作；不要假定存在全局安装环境。
5. 文档变更后运行适用于该框架的构建或验证检查。
6. Maintain 模式为只读：先诊断，再提出具体修复方案。
7. Migration 模式必须分阶段进行且可逆；避免一次性进行破坏性重写。
8. 拒绝超出范围的请求，并将其转交给正确的专用技能。
9. 对现有仓库执行 Init 模式时不得造成破坏：除非用户明确要求覆盖，否则仅创建缺失文件。
10. Generate 模式必须从源代码提取内容；绝不编造签名、文档字符串或 API 详情。