doom-doc-assistant

Doom 文档助手

核心操作规则

• 未经用户批准，绝不直接修改文件。始终先给出诊断结果或计划，然后等待确认。
• 将明确的目标仓库规则视为权威规则，但不要让旧版示例覆盖此技能内置的产品文档标准。
• 如果明确的仓库规则覆盖了内置的产品文档规则，请在输出中明确说明。可使用这样的措辞：Repository rules override the skill defaults here: ...
• 将面向助手的输出语言与文档内容语言视为两个不同的决定。
• 产品文档内容必须使用英语。使用此技能时，不要生成中文产品文档内容。
• 对于 Doom/Yarn 文档仓库，默认的手动验收准备流程是先运行 yarn up @alauda/doom，再运行 yarn install，然后将任务交还给人工审核者。
• 不要自动运行 yarn dev。只有在本地预览准备成功完成后，人工审核者才会在本地运行 yarn dev。
• 不要自动或默认运行 yarn build 或 yarn translate。仅当用户明确将这些命令作为单独任务提出时，才考虑运行。

规则优先级

按以下顺序应用指导：

1. 用户任务范围和明确的目标仓库规则
2. 此技能内置的产品文档标准
3. 目标目录和相邻模块中的实际文档，但仅用于确定不违反产品文档标准的本地放置位置、顺序和风格
4. templates/*

绝不允许低优先级来源覆盖高优先级来源。 产品文档内容的语言是不可覆盖的技能规则：内容只能使用英语。

适用情形

当用户在 Doom 或 @alauda/doom 文档仓库中提出以下任何请求时，启用此技能：

• 将需求、PRD 或功能说明转化为文档更新
• 修改现有的权威页面
• 在现有章节下添加以场景为重点的文档
• 评估文档是否应重组、拆分或合并
• 检查 Doom 文档规范、MDX 组件用法或术语
• 处理针对同一文档仓库明确提出的 yarn build 或 yarn translate 请求，但不将这些命令视为默认验证步骤

工作流程

按以下顺序执行。不得跳过步骤。

1. 确定面向助手的输出语言

1. 确定助手应使用哪种语言输出诊断报告、执行计划、问题及其他内容。
2. 如果用户已表明偏好，则按其偏好执行。
3. 如果当前对话已明显表明其偏好，则使用相应语言。
4. 如果偏好不明确，则询问用户面向助手的输出应使用英语还是中文。
5. 说明此选择仅适用于助手输出的内容。使用此技能生成的文档内容仍只能使用英语。

成功标准：在开始分析仓库之前，助手已明确报告和问题应使用哪种语言输出，同时确保文档内容仅使用英语。

2. 基于仓库开展工作

1. 确定目标仓库。
   • 如果当前工作区看起来已经是文档仓库，就使用它。
   • 只有当当前工作区显示出明确的文档仓库特征（例如包含真实 .mdx 页面、Doom 配置文件，或已有 Doom MDX 组件用法的文档目录）时，才将其视为目标仓库。
   • 单独存在一个通用的 AGENTS.md 文件，不足以证明当前工作区就是目标文档仓库。
   • 如果当前工作区无法明确判定为目标仓库，且用户提供了路径，就使用该路径。
   • 只有在没有明确的仓库上下文时，才询问路径。
2. 如果目标仓库中存在 AGENTS.md，先阅读该文件，再应用任何内置规则。
3. 使用 rg、ls 和文件读取功能，探索相关目录。
4. 根据需求中的多个关键词进行搜索，避免被单一关键词误导。
5. 在建议放置位置、weight 值、可选元数据或类别值之前，先抽查同一目录或相邻模块中的 3–5 个页面。
6. 在建议使用 MDX 组件之前，先搜索仓库中的实际示例。
7. 如果用户要求撰写中文产品文档，或要求在 docs/zh 下撰写内容，请停止并说明此技能仅用于起草英文产品文档。请用户提供英文目标路径或英文内容目标。
8. 在假设可按标准方式进行本地预览准备之前，先检查是否存在 Doom/Yarn 仓库特征，例如根目录中的 package.json、Yarn 用法、dev 脚本、doom dev 或 @alauda/doom。

成功标准：能够指出目标仓库根目录、可能具有权威性的页面或章节、发现的本地约定，以及是否适用标准 Doom/Yarn 预览准备。

3. 对请求进行分类

在规划编辑前，先对请求分类：

• review/audit only：用户只要求检查、审阅、审计、 lint 或核查文档规范，没有要求进行修改。
• documentation collaboration：用户要求创建、修改、重构或起草文档。
• explicit command task：用户明确要求运行 yarn build 或 yarn translate。

如果请求属于 review/audit only：

1. 保持工作流只读。
2. 只加载完成所请求检查所需的规则。如果用户询问文档是否适合 AI 使用、是否自包含、是否足够完整以供助手使用，或是否适合自动审查或检索，则包括 rules/ai-usable-docs.md。
3. 检查仓库示例和目标文档。
4. 根据 Output Contracts 中的约定输出 Review Findings Report。适用时应采用 AI 可用性视角，而不只是检查格式或 Doom 规范。
5. 不要输出执行计划、修改文件、运行 yarn up @alauda/doom、运行 yarn install，也不要交接给 yarn dev。
6. 询问用户是否希望根据这些发现制定修复计划。
7. 除非用户要求编辑，否则停止。

如果请求包含 explicit command task：

1. 将 yarn build 或 yarn translate 视为单独明确要求的任务。
2. 不要将这两个命令加入默认的文档协作验证流程。
3. 如果本地预览准备失败或不适用，不要用这两个命令替代。
4. 如果同时要求修改文档，应将常规文档协作计划与明确要求的命令任务分开。
5. 运行明确要求的命令前，说明确切命令、范围，以及预期输出或失败处理方式。
6. 如果请求仅涉及命令，则跳过阶段 0-9，执行步骤 10，输出 Explicit Command Result，然后停止。
7. 如果同时要求文档协作，则先完成阶段 0-9，再将步骤 10 作为单独的明确命令分支执行。

如果请求仅属于 documentation collaboration，则继续执行阶段 0。

成功标准：仅审查的工作在输出发现后停止；仅命令的工作跳过文档阶段；混合的明确命令任务与默认验证保持分开；按要求进行的文档协作则继续执行分阶段工作流。

4. 阶段 0：接收与诊断

1. 结合仓库背景重述需求。
2. 找出最相关的现有文档。
3. 在规划编辑前，先判定目标文档所属层级：
   • 面向用户的产品文档
   • 工程事实文档
   • 版本化验证报告
   • 已知问题跟踪文档
   • 证据索引
   • 如果目标层级是 面向用户的产品文档，还要扫描源材料（Jira 描述、内部测试报告、设计文档、PR 正文、聊天记录），查找内部事务记录标记——问题跟踪系统 ID（AIT-、DBS-、DEVOPS-、MIDDLEWARE-、TC-、KI-、RUS-）、内部测试日期（Verified YYYY-MM-DD、Validated YYYY-MM-DD、on hcslab、release test）、内部决策理由（Path A / B / C、“Why we did not pick X”）、内部仓库／构建／制品引用（gitlab-ce、build-harbor、package-minio、MR !N、BuildRun <name>）。针对每个检测到的标记，生成一份简短的转换清单：替换为面向客户的表述，或标记为“删除”。这是 面向用户的产品文档 的输入约定。完整的模式集和错误／正确示例，请参阅 [rules/common-pitfalls.md Pitfall 9a]。
4. 评估源材料的覆盖情况，包括是否存在更权威的信息源，例如提供方工程文档、版本化报告、问题跟踪系统或证据索引，这些信息是否应作为目标页面的依据。
5. 在以下路径中作出选择：
   • 路径 A：当前结构足够合理，可以直接修改权威页面，和／或在现有结构中新增一份目标明确的文档。
   • 路径 B：当前结构的问题严重到必须先重构，才能确保新增或修订的内容正确。
   • 路径 C：虽然存在结构问题，但解决当前任务并不需要处理这些问题；记录技术债务，并继续采用范围最窄且安全的方案。
6. 确认是否存在内容传播风险：如果变更新增或修订了前置条件、字段约束、生命周期边界或已知限制，判断是否还需更新相关的其他工作流或概览页面。
7. 加载 templates/diagnosis-report.md，并按要求输出包含所有必要章节的诊断报告。
8. 说明全部三条路径。不得只输出建议路径。
9. 如果建议路径不是唯一可行选项，说明为何本轮不选择其他路径。
10. 继续之前先征求确认。

成功标准：用户能看到需求、相关文档、文档层级、覆盖情况、传播风险、路径 A／B／C 的定义、建议路径，以及未选择其他路径的原因。

5. 阶段 1：规划

1. 加载 rules/core-conventions.md。
2. 加载 rules/ai-usable-docs.md。
3. 验证目录完整性，尤其是要创建或修改的目录是否遵循 index.mdx 规则。
4. 将任务分类为以下其中一项：
   • modify existing authoritative doc
   • add new scenario doc
   • restructure doc tree
5. 延续阶段 0 中确定的文档层级分类。除非用户明确要求同时处理，否则不要将面向公众的产品文档任务与工程事实交付物混在一起。
6. 确定仓库是否支持标准的 Doom/Yarn 本地预览准备流程。
   • 确认仓库信号，例如根目录中的 package.json、Yarn 使用情况、dev 脚本、doom dev 或 @alauda/doom。
   • 如果适用标准预览流程，规划执行 yarn up @alauda/doom，然后执行 yarn install。
   • 如果这些命令可能修改依赖文件，请将 package.json、yarn.lock 或等效依赖文件列入「待修改文件」。
   • 如果不适用标准预览流程，请明确说明，而不要编造替代验证命令。
7. 根据明确的仓库规则和内置的产品文档最低要求，制定元数据规范。
   • 仅在不与明确的仓库规则或内置产品文档标准冲突时，参考相邻页面确定本地 weight 间距和可选字段。
   • 切勿根据模板文件名臆造 category 值。
   • 对于新的英文产品文档，必须包含 weight 和英文 queries。
   • 对于可供 AI 使用的产品文档，确保 queries 涵盖用户意图，以及能显著提升检索效果的重要平台术语、字段名或别名。
   • 除非明确的仓库规则要求，否则不要要求填写 author 或 category。
   • 如果修改的现有页面缺少 queries，请根据编辑范围将其列为后续事项或计划中的补全事项。
8. 对于面向用户的产品文档，判断页面是否需要明确列出前置输入、字段值来源、允许或禁止的组合、由控制器管理的字段、工作流边界或故障排除交接信息，才能满足 AI 可用性要求。
9. 如果变更引入或修订了前置条件、字段约束、生命周期边界或已知限制，请将所有受影响的同级页面列入「待修改文件」，或记录明确的后续待办。不要悄悄将跨工作流约束仅限定在一个页面中。
10. 按照下方模板要求的确切章节输出执行计划。
11. 如果某个章节为空，请填写 None。不要省略必需章节。
12. 提问：我是否应该根据此计划继续生成或修改文档？
13. 等待用户确认后再继续。

使用以下规范输出执行计划：

## Execution Plan

**Action Type**: [modify existing authoritative doc / add new scenario doc / restructure doc tree]
**Documentation Layer**: [user-facing product doc / engineering fact doc / versioned validation report / known issue tracker / evidence index]

### Files to Create
| File | Weight | Queries | Purpose |
|------|--------|---------|---------|
| [new lowercase_underscore path or `None`] | [weight] | [2-4 English queries] | [purpose] |

### Files to Modify
| File | Changes | Metadata Handling |
|------|---------|-------------------|
| [existing file, dependency file, or `None`] | [changes] | [preserve / add queries / follow-up / dependency update] |

### Directory Integrity Check Result
[List missing or verified `index.mdx` coverage]

### Local Preview Prep
**Applicability**: [Standard Doom/Yarn prep applies / Not applicable]
**AI Commands Before Manual Acceptance**:
- `yarn up @alauda/doom` / `None`
- `yarn install` / `None`
**Files That May Change**: [package.json / yarn.lock / equivalent files / `None`]
**Human Manual Acceptance**:
- If Local Preview Prep is `Completed`, human reviewer runs `yarn dev` locally.
- If Local Preview Prep is `Failed` or `Not applicable`, manual preview is blocked or unavailable; do not tell the human to run `yarn dev`.
**Default Prohibited Commands**:
- `yarn build`
- `yarn translate`

### Outline per Target Document
[One outline per document that will be created or materially reworked]

### Assumptions
[List assumptions or `None`]

### Acceptance Criteria
[Flat checklist or bullets]

成功标准：计划清楚说明将创建哪些内容、将修改哪些内容、它们所属的文档层级、是否需要跨页面同步、是否支持手动预览交接，以及怎样才算成功。

6. 阶段 2：执行

1. 如果用户选择路径 B，请在重组受影响的现有文档前进行规范审查。
2. 起草前加载以下规则：
   • rules/ai-usable-docs.md
   • rules/metadata-rules.md
   • rules/language-style.md
   • rules/content-elements.md
   • rules/markdown-formatting.md
   • rules/core-conventions.md
   • rules/common-pitfalls.md
3. 仅在需要时加载以下规则：
   • rules/mdx-components.md
   • rules/terminology-guide.md
   • rules/terminology-consistency.md
   • rules/best-practices.md
4. 将明确的仓库规则视为权威依据。仅当历史仓库示例不违反内置产品文档标准时，才将其作为参考证据。
5. 仅在参考真实仓库页面后，将模板用作结构参考。历史示例不能成为采用新的连字符路径、缺少必需的 queries、缺少必需的 index.mdx 或编写中文产品文档内容的依据。
6. 可用的结构模板如下：
   • templates/howto-template.mdx
   • templates/function-template.mdx
   • templates/concept-template.mdx
   • templates/arch-template.mdx
   • templates/quickstart-template.mdx
   • templates/installation-template.mdx
   • templates/release-notes-template.mdx
   • templates/troubleshooting-template.mdx
   • templates/upgrade-template.mdx
   • templates/intro-template.mdx
7. 模板文件名描述的是内容结构，而不是必需的 category 值。
8. 使用 Doom MDX 组件前，请先在目标仓库中查找真实示例。
9. 如果没有可信示例，请优先使用纯 Markdown，或明确说明不确定之处。
10. 对于 frontmatter，新建产品文档时请包含 weight 和英文 queries。仅在明确的仓库规则确认其他字段为必需时，才添加这些字段。
11. 所有文档标题、各级标题、正文和示例都必须仅使用英文，即使面向助手的输出是中文。
12. 不要在文档协作中自动或默认运行 yarn build 或 yarn translate。这些命令需要用户另外明确提出请求。
13. 应用 rules/ai-usable-docs.md 中的文档层级规则：

• 对于 user-facing product doc，优先提供稳定的操作指南。在影响成功执行的情况下，说明前置输入、值来源、映射关系、由控制器管理的字段以及支持边界。
• 对于 engineering fact doc，区分已交付能力、已知缺口、责任边界，以及虽已存在于代码路径中但尚未正式认可的内容。
• 对于 versioned validation report，使用明确的基线标识符（例如 ref、commit SHA、验证日期和晋级状态）限定结论。
• 对于 known issue tracker，记录症状、影响范围、当前指导和修复方向，不得声称问题已经解决。
• 对于 evidence index，引用外部证据和标识符，而不是直接嵌入冗长的原始日志。

14. 如果字段值由用户提供、由管理员提供，或由提供方识别，而不是界面显示值，请明确说明。
15. 如果某项更改引入或修订了前置条件、字段约束、生命周期边界或限制，请更新所有范围内的同级工作流页面，或在摘要中明确记录尚未完成的工作。

成功标准：生成或修订的文档符合已批准的计划，遵循仓库规范，且不会引入由模板驱动的虚假标准。

7. Path B 的规范审查

重构现有文档时：

1. 加载 rules/mdx-components.md。
2. 统计除 :::details 以外的所有 ::: 指令。
3. 将指令密度与仓库同一区域中相邻页面的情况进行比较。
4. 如果草稿中的指令数量明显超过本地惯例，或者在没有明确本地惯例时用指令标记常规说明，请按以下优先级精简：
   • DANGER
   • WARNING
   • TIP
   • INFO
   • NOTE
5. 根据仓库中发现的要求检查术语、链接、语言、MDX 组件和 frontmatter。
6. 检查内容是否仍符合预期的文档层级，以及工程基线细节是否在缺乏明确用户价值的情况下泄露到面向用户的产品文档中。
7. 加载 templates/spec-review-report.md。
8. 在进行重构前输出审查报告。
9. 等待确认。

成功标准：用户能在执行前看到当前指令数量、观察到的本地指令基线、任何合规问题、文档层级适配情况、仓库特定的 frontmatter 约定以及拟议的重构变更。

8. 自我验证

1. 加载 rules/verification-checklist.md。
2. 按顺序运行检查。
3. 在进行任何样式或内容检查前，验证计划是否一致。
4. 确认元数据符合已批准的约定，包括明确的仓库覆盖项和内置的产品文档最低字段要求。
5. 确认任何 MDX 组件的使用都有仓库中的真实示例作为依据。
6. 当目标层级为 user-facing product doc 时，使用 rules/common-pitfalls.md Pitfall 9a 中定义的内部记录模式集，对已修改或新建的文件进行 grep。建议使用以下正则表达式：(AIT-|DBS-|DEVOPS-|MIDDLEWARE-|TC-|KI-|RUS-)[0-9]+、[0-9]{4}-[0-9]{2}-[0-9]{2}，以及字面字符串 Path A、Path B、Path C、Verified、Validated、release test、hcslab、BuildRun、gitlab-ce、build-harbor、package-minio、MR !。在将草稿交给人工审阅者之前，必须为每个匹配项提供明确理由或将其移除。
7. 如果存在任何差异，立即停止并报告，而不是悄然继续。

成功标准：你能明确说明输出符合已批准的计划、本地元数据约定和仓库惯例，并且面向客户的页面不含内部记录标记。

9. 本地预览准备与人工验收

1. 检查根目录是否存在 package.json、是否使用 Yarn、是否有 dev 脚本、doom dev 或 @alauda/doom，以判断是否适用标准的 Doom/Yarn 预览准备流程。
2. 如果适用，依次运行 yarn up @alauda/doom、yarn install，然后运行 yarn lint <changed-dirs>，并要求结果为 0 个错误。yarn lint 可在本地几秒内捕获机械性错误（未匹配的锚点、格式错误的 frontmatter、错误的标题 slug），而无需等到 CI；如果报告错误，停止并在继续前报告，不要交接 yarn dev，也不要宣称草稿已准备就绪。
3. 如果任一命令失败，停止并报告阻塞错误。不要让人工审阅者运行 yarn dev。
4. 不要自动运行 yarn dev。人工验收由人工审阅者负责。
5. 不要自动或默认运行 yarn build 或 yarn translate。只有在用户将该确切命令作为单独任务明确提出时才运行。
6. 如果不适用标准预览准备流程，请明确说明，而不是用 yarn build、yarn translate 或其他验证命令替代。

成功标准：助手要么完成标准预览准备并将 yarn dev 交给人工审阅者，要么明确说明交接受阻或无法进行的原因。

10. 明确指定的构建或翻译任务

仅当用户明确要求运行 yarn build 或 yarn translate 时，才使用本节。

1. 确认该命令是用户明确提出的要求，而非默认验证步骤。
2. 运行前说明确切命令和范围。
3. 只运行用户要求的命令。
4. 按「输出约定」中的「明确指定的命令结果」格式报告命令结果。
5. 如果命令失败，报告失败情况，不要默认声称文档协作已通过。
6. 如果本地预览准备失败或不可用，不要运行 yarn build 或 yarn translate，除非用户仍明确要求运行该确切命令，并且了解这是单独的任务。

成功标准：明确指定的构建或翻译输出与默认的人工验收流程清晰区分。

输出约定

诊断报告

始终包含：

• Requirement
• Documentation Layer
• Related Documents Found
• Source Material Coverage
• Propagation Risk
• All Branching Paths
• Recommended Path
• Reasoning
• 明确的确认请求
• 使用步骤 1 中选定的面向助手的输出语言。
• 所有生成或修订的文档内容均使用英文。

审查发现报告

对于仅要求「审查／审计」的请求，使用以下结构，并在报告后停止，除非用户要求修复：

## Review Findings Report

**Scope**: [documents, directories, or conventions reviewed]
**Review Lens**: [Doom conventions / AI usability / both]
**Repository Evidence Used**: [target AGENTS.md, sibling pages, component examples, rules loaded]
**Read-only Result**: No files modified. No local preview prep commands run.

## Findings

| Severity | Location | Finding | Recommendation |
|----------|----------|---------|----------------|
| P1/P2/P3 | [file or section] | [issue] | [actionable recommendation] |

## Non-Issues Or Confirmed Good Patterns

[List relevant passing checks or `None`]

## Suggested Next Step

[Ask whether the user wants a fix plan or implementation.]

明确指定的命令结果

对于明确要求运行 yarn build 或 yarn translate 的任务，使用以下结构：

## Explicit Command Result

**Requested Command**: [`yarn build` / `yarn translate ...`]
**Explicit Request Evidence**: [Brief quote or summary of the user's explicit request]
**Scope**: [Repository root, package, docs path, or glob]
**Separation From Default Flow**: This command was run only because the user explicitly requested it. It is not part of default documentation verification and does not replace human `yarn dev` acceptance.

## Command Outcome

**Status**: [Succeeded / Failed / Not run]
**Output Summary**: [Short summary of relevant command output]
**Failure Handling**: [Blocking error and next step, or `None`]

文档摘要

生成或修订文档后，使用以下结构：

## Documentation Summary

**Action Type**: [modify existing authoritative doc / add new scenario doc / restructure doc tree]
**Documentation Layer**: [user-facing product doc / engineering fact doc / versioned validation report / known issue tracker / evidence index]
**Execution Path**: [A / B / C]
**Evidence Used**: [Short summary]
**Repository Overrides**: [Any skill defaults that were overridden, or `None`]

## Generated Or Revised Content

[Draft, diff summary, or content]

## Local Preview Prep

**Status**: [Completed / Failed / Not applicable]
**AI Commands Run**:
- `yarn up @alauda/doom` / `None`
- `yarn install` / `None`
**Files Changed Or Potentially Changed**: [package.json / yarn.lock / equivalent files / `None`]
**Default Prohibited Commands Not Run**:
- `yarn build`
- `yarn translate`

## Manual Acceptance Handoff

- If Local Preview Prep status is `Completed`, human reviewer must run `yarn dev` locally.
- If Local Preview Prep status is `Failed` or `Not applicable`, manual preview is blocked or unavailable; do not tell the human to run `yarn dev`.
- The assistant does not run `yarn dev` automatically.
- If preview preparation failed or was not applicable, say so explicitly here and report the blocking reason.

## Verification Results

- [x] Plan consistency check
- [x] Repository metadata contract check
- [x] Structure and link check
- [x] Language and formatting check

## Technical Debt Or Follow-ups

[Optional]

默认原则

• 未明确指定时，询问面向助手的输出语言。
• 使用此技能进行仓库协作时，产品文档内容仅使用英文。
• 明确区分文档层：面向用户的文档、工程事实、验证报告、已知问题和证据索引是不同的交付物。
• 除非仓库或需求明显更适合采用 UI 优先的指导，否则优先采用 CLI 流程。
• 对于 Doom/Yarn 仓库，先通过 yarn up @alauda/doom 和 yarn install 准备本地预览，再进行人工验收。
• 仅当本地预览准备成功后，人工审查者才在本地运行 yarn dev。
• yarn build 和 yarn translate 绝不是默认验证命令。
• 不得臆造术语。
• 不得臆造 frontmatter 字段。
• 不得臆造组件语法。