docs-steward

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs Steward

文档管家

Maintain docs quality, architecture, and framework currency in project-local repositories.

Input:

$ARGUMENTS

— mode keywords, framework names, migration goals, or natural-language docs requests.

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

输入：

$ARGUMENTS

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

Canonical Vocabulary

标准术语库

Use these canonical terms exactly throughout docs-steward outputs.

Term	Meaning	NOT
docs framework	Primary platform rendering docs (Starlight, Docusaurus, Fumadocs, Sphinx, MkDocs)	"site generator" (too broad)
theme layer	Visual and component skin on top of a framework	"framework"
content graph	Navigation + page relationships + generated indexes	"folder list"
init	Non-destructive docs bootstrap in an existing repository	"reinitialize/overwrite"
sync	Regenerate framework artifacts from source docs state	"deploy"
maintain	Read-only health checks for structure, links, drift, and build integrity	"rewrite"
enhance	Improve existing docs clarity, structure, UX, and discoverability	"recreate"
matrix run	Execute workflows for all detected frameworks in one repository	"auto"
migration	Planned transition from one docs framework to another with parity checks	"instant convert"
version refresh	Update reference knowledge to latest stable framework/tool versions	"blind upgrade"
project-local	Skill is installed and used within the current project scope	"global install"

在文档管家的输出中，请严格使用以下标准术语。

术语	含义	禁用表述
docs framework	渲染文档的核心平台（Starlight、Docusaurus、Fumadocs、Sphinx、MkDocs）	"site generator"（范围过广）
theme layer	框架之上的视觉与组件皮肤	"framework"
content graph	导航 + 页面关联 + 生成的索引	"folder list"
init	在现有仓库中进行非破坏性的文档初始化	"reinitialize/overwrite"
sync	根据源文档状态重新生成框架产物	"deploy"
maintain	对结构、链接、偏差及构建完整性进行只读健康检查	"rewrite"
enhance	提升现有文档的清晰度、结构、用户体验及可发现性	"recreate"
matrix run	对仓库中检测到的所有框架执行工作流	"auto"
migration	从一个文档框架到另一个框架的计划性迁移，并进行一致性检查	"instant convert"
version refresh	将参考知识更新至框架/工具的最新稳定版本	"blind upgrade"
project-local	技能在当前项目范围内安装和使用	"global install"

Dispatch Table

调度表

Route

$ARGUMENTS

to mode:

`$ARGUMENTS` pattern	Mode	Start at
(empty) or `auto`	Auto	Mode A
`framework <name> <action>` ( `<action>` ∈ `sync	enhance	maintain
`framework <name>`	Framework-targeted (default action: `maintain` )	Mode B
`init` / `init <name>`	Init	Mode I
`init-sync` / `init-sync <name>`	Init+Sync	Mode I
`sync` / `sync <name>`	Sync	Mode C
`enhance` / `enhance <path>`	Enhance	Mode D
`maintain` / `maintain <name>`	Maintain	Mode E
`research` / `research versions`	Research	Mode F
`matrix`	Matrix	Mode G
`migrate <from> -> <to>`	Migrate	Mode H
`generate api <module>`	Generate	Mode J
`generate adr <decision>`	Generate	Mode J
`generate runbook <process>`	Generate	Mode J
`generate onboard`	Generate	Mode J
`generate glossary`	Generate	Mode J
Natural language: "generate API docs/reference"	Generate	Mode J
Natural language: "create an ADR/decision record"	Generate	Mode J
Natural language: "write a runbook/onboarding guide"	Generate	Mode J
Natural language: "set up `<framework>` docs from scratch and keep it in sync"	Init+Sync	Mode I
Natural language: "docs are stale/broken/outdated"	Maintain	Mode E
Natural language: "improve docs UX/content/nav"	Enhance	Mode D
Natural language: "upgrade latest framework versions"	Research	Mode F
Natural language: "update README", "sync AGENTS.md", "refresh docs instructions"	Auto	Mode A docs-surface route
Requests to build app APIs, skills, or MCP servers	Refuse	Redirect

将

$ARGUMENTS

路由至对应模式：

`$ARGUMENTS` 模式	模式	起始节点
（空）或 `auto`	自动模式	模式A
`framework <name> <action>` （ `<action>` ∈ `sync	enhance	maintain
`framework <name>`	指定框架模式（默认操作： `maintain` ）	模式B
`init` / `init <name>`	初始化模式	模式I
`init-sync` / `init-sync <name>`	初始化+同步模式	模式I
`sync` / `sync <name>`	同步模式	模式C
`enhance` / `enhance <path>`	优化模式	模式D
`maintain` / `maintain <name>`	维护模式	模式E
`research` / `research versions`	调研模式	模式F
`matrix`	矩阵模式	模式G
`migrate <from> -> <to>`	迁移模式	模式H
`generate api <module>`	生成模式	模式J
`generate adr <decision>`	生成模式	模式J
`generate runbook <process>`	生成模式	模式J
`generate onboard`	生成模式	模式J
`generate glossary`	生成模式	模式J
自然语言："generate API docs/reference"	生成模式	模式J
自然语言："create an ADR/decision record"	生成模式	模式J
自然语言："write a runbook/onboarding guide"	生成模式	模式J
自然语言："set up `<framework>` docs from scratch and keep it in sync"	初始化+同步模式	模式I
自然语言："docs are stale/broken/outdated"	维护模式	模式E
自然语言："improve docs UX/content/nav"	优化模式	模式D
自然语言："upgrade latest framework versions"	调研模式	模式F
自然语言："update README", "sync AGENTS.md", "refresh docs instructions"	自动模式	模式A 文档表层路由
构建应用API、技能或MCP服务器的请求	拒绝处理	重定向

Classification-Gating Pattern

分类门控规则

Apply this classification-gating rubric before any mutating mode.

Detect frameworks using
```
references/framework-detection.md
```
.
If one framework is detected, continue with that framework.
If multiple frameworks are detected and user did not specify target, ask user to choose each run (interactive mode).
If no framework signal exists, ask user for docs stack before editing (interactive mode).
If the run is headless/non-interactive, apply the Headless Fallback Contract.

在执行任何会修改内容的模式前，请应用以下分类门控准则：

使用
```
references/framework-detection.md
```
检测框架。
若检测到一个框架，继续针对该框架操作。
若检测到多个框架且用户未指定目标，每次运行时都需询问用户选择（交互模式）。
若未检测到框架信号，编辑前询问用户文档技术栈（交互模式）。
若运行为无头/非交互模式，应用无头 fallback 协议。

Headless Fallback Contract

无头 Fallback 协议

When no clarifying exchange is possible:

If framework target is ambiguous or multiple frameworks are detected without explicit target, run Mode E (Maintain) as a read-only Mode G (Matrix) across detected frameworks.
Only allow mutating auto paths when framework selection is explicit or single-framework high-confidence and trigger category is safe per Mode A.
Process frameworks in deterministic order:
```
starlight/astro
```
,
```
docusaurus
```
,
```
fumadocs
```
,
```
sphinx
```
,
```
mkdocs
```
.
Emit a warning when headless fallback was applied and mutating modes (
```
init
```
,
```
init-sync
```
,
```
sync
```
,
```
enhance
```
,
```
research
```
,
```
migrate
```
) were skipped pending explicit framework selection.
If no framework is detected, return a read-only maintain report with "framework target required" and no edits.

当无法进行澄清沟通时：

若框架目标不明确，或检测到多个框架但未指定明确目标，对所有检测到的框架执行**模式E（维护）作为只读模式G（矩阵）**运行。
仅当框架选择明确或高置信度单框架，且触发类别符合模式A的安全要求时，才允许自动执行修改操作。

按确定顺序处理框架：

starlight/astro

docusaurus

fumadocs

sphinx

mkdocs

。

当应用无头 fallback 且跳过了修改模式（
```
init
```
,
```
init-sync
```
,
```
sync
```
,
```
enhance
```
,
```
research
```
,
```
migrate
```
）等待明确框架选择时，发出警告。
若未检测到框架，返回只读维护报告，提示"framework target required"且不进行任何编辑。

Live Version Research (Required for "latest")

实时版本调研（请求"latest"时必填）

When user requests latest versions (explicitly or implicitly), always refresh version facts before applying changes:

Query package registries (npm/PyPI) with tool-assisted checks.
Update framework reference snapshots in
```
references/*.md
```
.
Record version source and date in the edited reference.
Only then propose dependency or config updates.

Never claim "latest" without evidence from current registry data.

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

通过工具辅助查询包注册表（npm/PyPI）。
更新
```
references/*.md
```
中的框架参考快照。
在编辑后的参考文档中记录版本来源及日期。
之后再提出依赖或配置更新建议。

若无当前注册表数据支持，绝不能声称是"latest"版本。

Mode A: Auto

模式A：自动模式

Default orchestrator mode.

默认编排器模式。

A.1 Trigger categories

A.1 触发类别

Classify detected change signals before choosing a mode:

Content-only: page prose/examples/frontmatter edits without nav/config/build impact.
Structure/config: docs/framework/config/navigation/build-related changes (sidebar/nav trees, framework config, docs build wiring, generated docs artifacts).
Dependency/version: docs framework/theme/plugin dependency or lockfile/version changes.
Docs-surface: project README, nested
```
AGENTS.md
```
, generated docs indexes, or contributor-facing docs that must reflect a docs behavior change.

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

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

A.2 Action path

A.2 操作路径

Detect docs frameworks.
If multiple frameworks, ask which one to operate on this run.
Route by trigger category:
- Content-only -> Mode D (Enhance), then optional Mode E (Maintain) check.
- Structure/config -> Mode C (Sync) + Mode E (Maintain).
- Dependency/version -> Mode F (Research) + Mode C (Sync) + Mode E (Maintain).
- Docs-surface -> Mode C (Sync) when generation/wiring changed, otherwise Mode D (Enhance) + Mode E (Maintain).
If trigger category or intent is unclear, ask one focused clarifying question before edits.

检测文档框架。
若存在多个框架，询问本次运行操作哪个框架。
根据触发类别路由：
- 仅内容变更 -> 模式D（优化），可选后续**模式E（维护）**检查。
- 结构/配置变更 -> 模式C（同步） + 模式E（维护）。
- 依赖/版本变更 -> 模式F（调研） + 模式C（同步） + 模式E（维护）。
- 文档表层变更 -> 若生成/连接逻辑变更则执行模式C（同步），否则执行模式D（优化） + 模式E（维护）。
若触发类别或意图不明确，编辑前先提出一个聚焦的澄清问题。

A.3 Auto-sync safety

A.3 自动同步安全规则

Auto-sync is allowed only when framework target is explicit or single-framework high-confidence.
In headless ambiguous multi-framework runs, preserve read-only fallback (Mode E matrix); do not auto-sync.
If confidence is low, framework signals conflict, or scope is not docs-local, downgrade to Mode E (Maintain).

仅当框架目标明确或高置信度单框架时，允许自动同步。
在无头多框架模糊场景下，保留只读 fallback（模式E矩阵）；不执行自动同步。
若置信度低、框架信号冲突或范围非文档本地，降级为模式E（维护）。

Mode B: Framework-targeted (

framework <name> [<action>]

)

模式B：指定框架模式（

framework <name> [<action>]

）

Supported names:

```
astro
```
/
```
starlight
```
```
docusaurus
```
```
fumadocs
```
```
sphinx
```
```
mkdocs
```

Grammar:

framework <name> [<action>]

, where

<action>

is one of

sync

enhance

maintain

research

, or

migrate

. If

<action>

is omitted, default to

maintain

. Run the mapped mode for the selected framework:

sync

-> Mode C,

enhance

-> Mode D,

maintain

-> Mode E,

research

-> Mode F,

migrate

-> Mode H.

支持的框架名称：

```
astro
```
/
```
starlight
```
```
docusaurus
```
```
fumadocs
```
```
sphinx
```
```
mkdocs
```

语法：

framework <name> [<action>]

，其中

<action>

为

sync

、

enhance

、

maintain

、

research

或

migrate

之一。若省略

<action>

，默认执行

maintain

。为所选框架运行映射模式：

sync

-> 模式C，

enhance

-> 模式D，

maintain

-> 模式E，

research

-> 模式F，

migrate

-> 模式H。

Mode C: Sync

模式C：同步模式

Bring generated docs artifacts into a consistent state.

Verify framework-native advanced component support and rendering paths (Mermaid, code snippets, tables, embeds, tabs/admonitions).

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

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

C.1 Astro + Starlight

Verify Astro config and Starlight integration.
Regenerate docs artifacts with project commands (for this repo:
```
python scripts/docs_sync.py generate
```
).
Build-check docs output.

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

C.2 Docusaurus

Validate
```
docusaurus.config.*
```
, sidebars, and docs route structure.
Rebuild generated docs assets and run build sanity checks.

验证
```
docusaurus.config.*
```
、侧边栏及文档路由结构。
重新构建生成的文档资源并执行构建完整性检查。

C.3 Fumadocs

Validate
```
next.config.*
```
,
```
fumadocs-*
```
package setup, and MDX content tree.
Regenerate indexes/navigation where applicable and run Next build checks.

验证
```
next.config.*
```
、
```
fumadocs-*
```
包设置及MDX内容树。
重新生成相关索引/导航并执行Next构建检查。

C.4 Sphinx

Validate
```
conf.py
```
, extension set, and theme package alignment.
Build with strict warnings enabled for docs quality gates.

验证
```
conf.py
```
、扩展集及主题包一致性。
启用严格警告构建，作为文档质量门控。

C.5 MkDocs

Validate
```
mkdocs.yml
```
, plugin stack, and nav structure.
Run strict build checks and detect plugin drift.

验证
```
mkdocs.yml
```
、插件栈及导航结构。
执行严格构建检查并检测插件偏差。

C.6 Sync output contract

C.6 同步输出协议

Include an "Advanced component render check" summary for Mermaid, code snippets, tables, embeds, and tabs/admonitions.
Note framework-specific support/plugins used and flag unsupported components with safe fallbacks.
Include accessibility notes (diagram text alternatives, labeled code fences, titled embeds, and tab/admonition semantics).

包含“高级组件渲染检查”摘要，覆盖Mermaid、代码片段、表格、嵌入内容及标签页/提示框。
记录使用的框架特定支持/插件，并标记不支持的组件及安全 fallback 方案。
包含可访问性说明（图表文本替代方案、带标签的代码块、带标题的嵌入内容、标签页/提示框语义）。

Mode D: Enhance

模式D：优化模式

Improve docs quality without changing framework identity.

Enhancement targets:

Information architecture (nav clarity, section depth, landing pages)
Writing quality (scannability, examples, API/task orientation)
Internal linking (orphan reduction, related-links strategy)
Visual documentation UX (callouts, tabs, code grouping, admonitions, diagrams, embeds, tables)
Consistency (style, heading depth, frontmatter, metadata)

Ask clarifying questions when enhancement direction is ambiguous ("developer docs", "marketing docs", "API docs", or "tutorial docs").

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

优化目标：

信息架构（导航清晰度、章节深度、着陆页）
写作质量（易读性、示例、API/任务导向）
内部链接（减少孤立页面、相关链接策略）
可视化文档用户体验（提示框、标签页、代码分组、警告框、图表、嵌入内容、表格）
一致性（风格、标题层级、前置元数据、元数据）

当优化方向不明确时，提出澄清问题（如“开发者文档”、“营销文档”、“API文档”或“教程文档”）。

D.1 Advanced component strategy

D.1 高级组件策略

Use advanced components when they materially improve comprehension, not decoration.
Choose framework-native primitives for the active stack and keep syntax/style consistent within each page.
Prefer: Mermaid for flows/architecture, code snippets for implementation steps, tables for comparisons, embeds for canonical demos/media, tabs/admonitions for variants and cautions.
Keep outputs accessible: add plain-language context and text fallback for diagrams, language labels on code blocks, meaningful captions/titles, and avoid color-only or tab-only critical content.
Use
```
references/advanced-components.md
```
for framework-specific syntax patterns and safe fallbacks.

仅当高级组件能切实提升理解度时使用，而非仅作装饰。
为当前技术栈选择框架原生基础组件，并保持每页语法/风格一致。
优先选择：用Mermaid绘制流程/架构图，用代码片段展示实现步骤，用表格进行对比，用嵌入内容展示标准演示/媒体，用标签页/提示框展示变体及注意事项。
确保输出可访问：为图表添加平实语言说明及文本 fallback，为代码块添加语言标签，使用有意义的标题/说明，避免仅依赖颜色或标签页展示关键内容。
使用
```
references/advanced-components.md
```
获取框架特定语法模式及安全 fallback 方案。

D.2 Enhance output contract

D.2 优化输出协议

Summarize which advanced components were added/updated, why they help, and any framework constraints or fallbacks.

总结添加/更新了哪些高级组件、其作用及任何框架约束或 fallback 方案。

Mode E: Maintain

模式E：维护模式

Read-only diagnostics and remediation planning.

Checks:

Broken links and anchor drift
Stale/generated file mismatch
Navigation dead-ends and orphans
Theme/plugin dependency drift
Build warnings/errors
Framework mismatch in mixed repos

Output format:

Critical (must-fix)
Warning (should-fix)
Suggestion (nice-to-have)
Next commands to run

只读诊断及修复规划。

检查项：

失效链接及锚点偏差
陈旧/生成文件不匹配
导航死胡同及孤立页面
主题/插件依赖偏差
构建警告/错误
混合仓库中的框架不匹配

输出格式：

严重（必须修复）
警告（建议修复）
建议（可选优化）
后续执行命令

Mode F: Research

模式F：调研模式

Refresh framework/theme references to latest stable versions and advanced patterns.

Workflow:

Resolve package/version facts for each active framework.
Update reference snapshot sections.
Note migration-relevant deltas (breaking changes, deprecated APIs, config shifts).
Return a concise change summary with confidence and citations/source commands.

将框架/主题参考信息刷新至最新稳定版本及高级模式。

工作流程：

解析每个活跃框架的包/版本信息。
更新参考快照章节。
记录与迁移相关的差异（破坏性变更、废弃API、配置调整）。
返回简洁的变更摘要，包含置信度及引用/源命令。

Mode G: Matrix

模式G：矩阵模式

Execute a controlled run across all detected frameworks in the repository.

Use for:

Monorepos with multiple docs stacks
Parallel migration programs
Framework parity audits

Matrix run output must keep results grouped per framework and include cross-framework conflicts.

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

适用场景：

包含多个文档栈的单体仓库
并行迁移项目
框架一致性审计

矩阵运行输出必须按框架分组展示结果，并包含跨框架冲突信息。

Mode H: Migrate (

migrate <from> -> <to>

)

模式H：迁移模式（

migrate <from> -> <to>

）

Migration is in scope for v1.

Supported paths:

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

Migration phases:

Inventory and parity baseline
Content and nav mapping
Theme/component mapping
Build/test parity checks
Incremental rollout plan

Do not promise one-shot full conversion; prefer staged migration with checkpoints.

迁移功能在v1版本中支持。

支持的迁移路径：

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

迁移阶段：

盘点及一致性基线
内容与导航映射
主题/组件映射
构建/测试一致性检查
增量发布计划

不承诺一键完整转换；优先采用带检查点的分阶段迁移。

Mode I: Init (

init

init <framework>

init-sync

init-sync <framework>

)

模式I：初始化模式（

init

init <framework>

init-sync

init-sync <framework>

）

Bootstrap docs site wiring in an existing repository without destructive rewrites. This mode applies to explicit

init*

commands and implicit "bootstrap docs + keep synced" requests in existing codebases. Load

references/init-sync-existing-repos.md

plus the selected framework reference before edits.

在现有仓库中引导文档站点连接，不进行破坏性重写。此模式适用于明确的

init*

命令，以及现有代码库中隐含的“引导文档+保持同步”请求。编辑前加载

references/init-sync-existing-repos.md

及所选框架参考文档。

I.1 Framework selection behavior

I.1 框架选择行为

If
```
<framework>
```
is provided, target that framework directly.
If no
```
<framework>
```
is provided and exactly one framework is detected, target the detected framework.
If multiple frameworks are detected and no explicit target is provided, ask user to choose; in headless runs, apply the Headless Fallback Contract.
If no framework is detected and no explicit target is provided, ask user to select a supported framework; in headless runs, return read-only Mode E output with "framework target required."

若提供
```
<framework>
```
，直接针对该框架操作。
若未提供
```
<framework>
```
且仅检测到一个框架，针对该检测到的框架操作。
若检测到多个框架且未提供明确目标，询问用户选择；在无头运行中，应用无头 fallback 协议。
若未检测到框架且未提供明确目标，询问用户选择支持的框架；在无头运行中，返回只读模式E输出，提示"framework target required"。

I.2 Non-destructive bootstrap contract

I.2 非破坏性引导协议

Only create missing docs scaffold/config files; do not overwrite existing files by default.
Preflight guard: if target docs root already exists and is non-empty, do not recreate or replace that root; continue in-place with missing-file scaffolding only unless user explicitly requests overwrite.
Preserve existing docs content, navigation, and framework config when present.
If requested framework conflicts with existing docs framework wiring, stop and return maintain findings + conflict summary (use Mode H for migrations).

仅创建缺失的文档脚手架/配置文件；默认不覆盖现有文件。
预检防护：若目标文档根目录已存在且非空，不重新创建或替换该根目录；仅对缺失文件进行脚手架搭建，除非用户明确请求覆盖。
保留现有文档内容、导航及框架配置（若存在）。
若请求的框架与现有文档框架连接冲突，停止操作并返回维护结果+冲突摘要（使用模式H进行迁移）。

I.3 Follow-up flow

I.3 后续流程

```
init
```
: bootstrap, then recommend
```
sync
```
and
```
maintain
```
follow-up.
```
init-sync
```
: bootstrap, then run Mode C (Sync) and Mode E (Maintain) in the same run.
Always report what was created, what was skipped, and why.

```
init
```
：引导完成后，建议后续执行
```
sync
```
及
```
maintain
```
。
```
init-sync
```
：引导完成后，在同一次运行中执行模式C（同步）及模式E（维护）。
始终报告创建了什么、跳过了什么及原因。

Mode J: Generate (

generate <type> [<target>]

)

模式J：生成模式（

generate <type> [<target>]

）

Generate technical documentation from source code. Load

references/generate-mode.md

for detailed procedures, output formats, and script usage.

Sub-modes:

Command	Output	Key Script
`generate api <module>`	API reference with signatures, docstrings, coverage	`api-surface-extractor.py` , `doc-coverage-analyzer.py`
`generate adr <decision>`	MADR-format architecture decision record	`adr-scaffolder.py`
`generate runbook <process>`	Operational runbook with commands from codebase	—
`generate onboard`	New contributor onboarding guide	—
`generate glossary`	Term definitions extracted from code and docs	—

从源代码生成技术文档。加载

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 Workflow

J.1 工作流程

Identify target scope (module path, process name, or whole repo).
Run applicable scripts to extract structured data from source.
Transform extracted data into documentation following the format in
```
references/generate-mode.md
```
.
Present draft for review. Ask clarifying questions if context is ambiguous.
Write output to appropriate location (e.g.,
```
docs/api/
```
,
```
docs/decisions/
```
).

确定目标范围（模块路径、流程名称或整个仓库）。
运行适用脚本从源代码提取结构化数据。
将提取的数据转换为符合
```
references/generate-mode.md
```
格式的文档。
展示草稿供审核。若上下文不明确，提出澄清问题。
将输出写入合适位置（如
```
docs/api/
```
,
```
docs/decisions/
```
）。

J.2 Generate output contract

J.2 生成输出协议

Generated docs must trace to source code (include file paths and line numbers).
Never fabricate API signatures or docstrings; extract or flag as undocumented.
ADRs follow MADR v3 format from
```
data/adr-template.json
```
.
Use docstring format conventions from
```
data/docstring-formats.json
```
matching the project's language and style.

生成的文档必须可追溯至源代码（包含文件路径及行号）。
绝不能编造API签名或文档字符串；仅提取或标记为未文档化。
ADR遵循
```
data/adr-template.json
```
中的MADR v3格式。
使用与项目语言及风格匹配的
```
data/docstring-formats.json
```
中的文档字符串格式约定。

Scope Boundaries

范围边界

In scope: Docs framework operations, non-destructive docs bootstrap, version refresh, build/health diagnostics, quality enhancement, docs migrations, technical documentation generation from code, project README updates, and nested

AGENTS.md

instruction-doc updates when documentation behavior changed.

NOT for:

Creating/editing unrelated product features or backend APIs
Creating or changing skill definitions, agents, or MCP servers (route to
```
skill-creator
```
,
```
agent-conventions
```
, or
```
mcp-creator
```
)
CI/CD redesign outside docs pipeline needs
Non-docs frontend application implementation

包含范围： 文档框架操作、非破坏性文档引导、版本刷新、构建/健康诊断、质量优化、文档迁移、从源代码生成技术文档、项目README更新，以及当文档行为变更时更新嵌套的

AGENTS.md

说明文档。

不包含范围：

创建/编辑无关产品功能或后端API
创建或修改技能定义、Agent或MCP服务器（路由至
```
skill-creator
```
、
```
agent-conventions
```
或
```
mcp-creator
```
）
超出文档流水线需求的CI/CD重新设计
非文档类前端应用实现

Scaling Strategy

扩展策略

Scope	Execution Strategy	Ownership Rule
1 framework and 1-3 docs files	Edit inline, then run framework-specific validation	One agent owns all touched files
1 framework and 4-12 docs files	Batch by docs area: nav/config, generated references, prose pages, README/ `AGENTS.md`	Never assign the same file to multiple workers
2-5 frameworks or 13+ docs files	Use matrix waves in deterministic framework order, then consolidate maintain report	One worker per framework or file batch; merge only after validation
Any migration or version refresh	Plan checkpoint first, then phase edits with rollback notes	Keep source and target docs roots traceable until parity is verified

范围	执行策略	所有权规则
1个框架且1-3个文档文件	在线编辑，然后运行框架特定验证	一个Agent负责所有修改的文件
1个框架且4-12个文档文件	按文档领域分批：导航/配置、生成参考、文本页面、README/ `AGENTS.md`	绝不将同一文件分配给多个工作者
2-5个框架或13+个文档文件	按确定框架顺序使用矩阵波，然后合并维护报告	每个框架或文件批次分配一个工作者；仅在验证后合并
任何迁移或版本刷新	先规划检查点，然后分阶段编辑并记录回滚说明	在验证一致性前，保持源文档根目录与目标文档根目录可追溯

Reference File Index

参考文件索引

Load references on demand; do not load all at once.

File	Content	Load When
`references/framework-detection.md`	Framework signal map, multi-framework routing rules	All modes
`references/advanced-components.md`	Framework-specific Mermaid/codeblocks/tables/embeds patterns with safe fallbacks	sync/enhance
`references/init-sync-existing-repos.md`	Non-destructive framework-aware bootstrap + follow-up sync workflows for existing repos	init/init-sync
`references/astro-starlight.md`	Astro + Starlight advanced setup and checks	framework/sync/maintain/enhance
`references/docusaurus.md`	Docusaurus advanced config and plugin checks	framework/sync/maintain/enhance
`references/fumadocs.md`	Fumadocs + Next advanced setup and checks	framework/sync/maintain/enhance
`references/sphinx.md`	Sphinx + theme matrix (Shibuya/PyData/Furo/Book)	framework/sync/maintain/enhance
`references/mkdocs.md`	MkDocs + Material/plugin stack checks	framework/sync/maintain/enhance
`references/migrations.md`	Migration playbooks and parity templates	migrate/matrix
`references/version-refresh.md`	Latest-version refresh workflow and evidence rules	research + any latest-version request
`references/generate-mode.md`	Generate sub-mode procedures, output formats, script usage	generate
`data/docstring-formats.json`	Docstring format standards per language (Google, NumPy, Sphinx, JSDoc, TSDoc)	generate api
`data/adr-template.json`	MADR v3 template structure and file naming conventions	generate adr

按需加载参考文件；无需一次性加载所有文件。

文件	内容	加载时机
`references/framework-detection.md`	框架信号映射、多框架路由规则	所有模式
`references/advanced-components.md`	框架特定的Mermaid/代码块/表格/嵌入内容模式及安全fallback方案	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`	最新版本刷新工作流及证据规则	research + 任何最新版本请求
`references/generate-mode.md`	生成子模式流程、输出格式、脚本用法	generate
`data/docstring-formats.json`	各语言的文档字符串格式标准（Google、NumPy、Sphinx、JSDoc、TSDoc）	generate api
`data/adr-template.json`	MADR v3模板结构及文件命名约定	generate adr

Validation Contract

验证协议

Completion criteria:

Changed docs surfaces are source-grounded and project-local.
Mutating modes run the relevant framework build, docs generation, or health check.
Maintain mode remains read-only and reports next commands instead of editing.
Skill changes pass these proof commands when applicable:
- ```
python scripts/check.py
```
- ```
python scripts/docs_sync.py
```
  when generated docs surfaces change

完成标准：

修改的文档表层基于源代码且为项目本地。
修改模式运行相关的框架构建、文档生成或健康检查。
维护模式保持只读，报告后续命令而非直接编辑。
技能变更在适用时通过以下验证命令：
- ```
python scripts/check.py
```
- 当生成的文档表层变更时，执行
```
python scripts/docs_sync.py
```

Critical Rules

关键规则

Ask at least one clarifying question before edits when user intent or target framework is ambiguous.
In multi-framework repositories,
```
auto
```
mode must ask which framework to operate on each run unless explicitly overridden.
Never claim "latest" versions without fresh registry-backed evidence and a reference snapshot update.
Keep operations project-local by default; do not assume global install context.
Run framework-appropriate build or validation checks after docs changes.
Maintain mode is read-only: diagnose first, then propose concrete fixes.
Migration mode must be phased and reversible; avoid destructive one-pass rewrites.
Refuse out-of-scope requests and route to the correct specialized skill.
Init mode is non-destructive in existing repos: create missing files only unless user explicitly requests overwrite.
Generate mode must extract from source code; never fabricate signatures, docstrings, or API details.

当用户意图或目标框架不明确时，编辑前至少提出一个澄清问题。
在多框架仓库中，
```
auto
```
模式每次运行时必须询问操作哪个框架，除非明确覆盖。
若无最新注册表支持的证据及参考快照更新，绝不能声称是"latest"版本。
默认保持操作项目本地；不假设全局安装环境。
文档变更后运行框架对应的构建或验证检查。
维护模式为只读：先诊断，再提出具体修复建议。
迁移模式必须分阶段且可回滚；避免破坏性单次重写。
拒绝超出范围的请求并路由至正确的专业技能。
在现有仓库中，初始化模式为非破坏性：仅创建缺失文件，除非用户明确请求覆盖。
生成模式必须从源代码提取内容；绝不能编造签名、文档字符串或API细节。

docs-steward

Original

Translation

Docs Steward

文档管家

Canonical Vocabulary

标准术语库

Dispatch Table

调度表

Classification-Gating Pattern

分类门控规则

Headless Fallback Contract

无头 Fallback 协议

Live Version Research (Required for "latest")

实时版本调研（请求"latest"时必填）

Mode A: Auto

模式A：自动模式

A.1 Trigger categories

A.1 触发类别

A.2 Action path

A.2 操作路径

A.3 Auto-sync safety

A.3 自动同步安全规则

Mode B: Framework-targeted (framework <name> [<action>])

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

Mode C: Sync

模式C：同步模式

C.1 Astro + Starlight

C.1 Astro + Starlight

C.2 Docusaurus

C.2 Docusaurus

C.3 Fumadocs

C.3 Fumadocs

C.4 Sphinx

C.4 Sphinx

C.5 MkDocs

C.5 MkDocs

C.6 Sync output contract

C.6 同步输出协议

Mode D: Enhance

模式D：优化模式

D.1 Advanced component strategy

D.1 高级组件策略

D.2 Enhance output contract

D.2 优化输出协议

Mode E: Maintain

模式E：维护模式

Mode F: Research

模式F：调研模式

Mode G: Matrix

模式G：矩阵模式

Mode H: Migrate (migrate <from> -> <to>)

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

Mode I: Init (init, init <framework>, init-sync, init-sync <framework>)

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

I.1 Framework selection behavior

I.1 框架选择行为

I.2 Non-destructive bootstrap contract

I.2 非破坏性引导协议

I.3 Follow-up flow

I.3 后续流程

Mode J: Generate (generate <type> [<target>])

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

J.1 Workflow

J.1 工作流程

J.2 Generate output contract

J.2 生成输出协议

Scope Boundaries

范围边界

Scaling Strategy

扩展策略

Reference File Index

参考文件索引

Validation Contract

验证协议

Critical Rules

关键规则

Mode B: Framework-targeted (
`framework <name> [<action>]`
)

模式B：指定框架模式（
`framework <name> [<action>]`
）

Mode H: Migrate (
`migrate <from> -> <to>`
)

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

Mode I: Init (
`init`
,
`init <framework>`
,
`init-sync`
,
`init-sync <framework>`
)

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

Mode J: Generate (
`generate <type> [<target>]`
)

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