docs-check-zh-cn

文档检查

运行 OpenHarmony API 文档质量检查，重点关注模板合规性、文档一致性、错误码覆盖情况以及与实现的一致性。输出仅包含问题，不要重复列出已符合要求的内容。

输入收集

尽可能根据用户上下文、当前工作目录和仓库布局推断路径。只有在仍无法找到所需文件时才询问用户。

收集或推断以下输入：

• public API 文档路径，可选，通常位于 /docs 下
• system API 文档路径，可选，通常位于 /docs 下
• 错误码文档路径，可选，通常位于 /docs 下
• API 定义路径，通常位于 /interface 下
• 仓库根路径，仅当无法从当前工作区找到接口实现时需要

默认先从工作区根目录下查找 /docs，再查找 /interface。

如果用户提供的路径以 /docs/... 或 /interface/... 开头，优先将其解释为仓库根目录下的路径，而不是相对于当前模块目录的路径。

如果用户只提供了部分路径，请从已知输入开始，并继续在工作区根目录下的 /docs 和 /interface 中自动发现。请在报告中明确说明未检查的范围。

工作流

按以下顺序执行。

1. 定位文档、接口声明和实现代码。
2. 首先运行 scripts/check_api_doc_consistency.py，完成稳定且可自动化的检查。
3. 阅读相关模板并提取实际写作要求。
4. 手动检查脚本无法可靠检查的问题。
5. 必要时将文档与实现行为交叉核对。
6. 输出一份 Markdown 报告，仅包含问题、影响和修复建议。

默认按以下顺序查找：

1. 用户提供的路径
2. 从当前工作目录逐级向上查找包含 docs 和 interface 的工作区根目录
3. 工作区根目录下的 /docs
4. 工作区根目录下的 /interface
5. 可能包含相关实现的其他源代码目录

如果当前目录是子模块，不要假设当前目录下存在 /docs 或 /interface。请先找到工作区根目录。

模板选择

请按以下优先级使用模板：

1. 仓库内模板
2. 外部文档链接
3. 此技能捆绑的默认模板

仓库内模板路径：

• JS API 模板：/docs/blob/master/zh-cn/contribute/template/native-template.md
• ArkTS 组件 API 模板：/docs/blob/master/zh-cn/contribute/template/ts-template.md
• 错误码模板：/docs/blob/master/zh-cn/contribute/template/errorcodes-template.md

外部链接：

• JS API 模板：https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/template/native-template.md
• ArkTS 组件 API 模板：https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/template/ts-template.md
• 错误码模板：https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/template/errorcodes-template.md

随附的备用模板：

• references/js-template.md
• references/ts-template.md
• references/errorcodes-template.md

先尝试使用仓库内模板。如果该模板不存在，则尝试使用外部链接。如果外部链接仍不可用，则使用 references/ 下的随附模板作为备用方案。请在最终报告中说明实际使用的模板来源。

根据接口类别选择模板：

• 常规 JS API、C API 或面向模块的 API 文档：使用 JS API 模板
• ArkTS 组件接口文档：使用 ArkTS 组件模板
• 错误码文档：使用错误码模板

判断是否属于 ArkTS 组件时，优先考虑接口所属的 Kit：

• 如果接口属于 ArkUI，则视为 ArkTS 组件接口，并使用 ts-template
• 如果接口明显采用 ArkUI 组件语义，例如组件、属性、事件、Builder 或 Modifier 等概念，也视为 ArkTS 组件接口
• 对于非 ArkUI Kit，默认使用常规 API 文档模板，除非现有文档结构明显遵循 ArkTS 组件模板

不要仅凭文件名选择模板。请综合考虑 Kit、接口类型、当前文档结构和 d.ts 内容。

手动审查重点

脚本运行完成后，请重点手动审查以下难以自动处理的方面：

• 文案是否清晰、无歧义，术语是否一致，语言质量是否存在拼写级问题
• 示例是否确实有用、可运行且说明充分
• 文档结构是否真正遵循模板的原则，而不只是表面形式
• 是否充分说明场景、限制、前置条件和故障模式，便于开发者理解
• 每个错误码的文档化原因是否确实涵盖了所有实际触发场景
• 文档是否与实现行为、能力边界和产品变化一致
• ArkTS 组件文档是否充分说明参数、默认值、取值范围和边界行为

实现对齐检查

使用实现代码找出文档中缺失或不正确的内容，例如：

• 功能场景、子场景或功能覆盖不完整
• 缺少概念、原理或使用场景说明，导致开发者无法获得足够背景信息
• 产品、接口或行为变更未同步到文档中
• 缺少环境要求、规范限制、前置条件或故障场景

如果无法在当前仓库中找到实现代码，请暂停此部分，并向用户询问正确的仓库路径。

输出要求

请生成一份 Markdown 报告，并遵守以下规则：

• 不要列出已经符合要求的内容
• 对于每个问题，请注明行号或位置、问题描述、原因或影响、建议的修复方式，并尽可能提供具体措辞
• 如果可以直接提供修订后的文本，请直接给出
• 单独注明未检查的范围、缺失的输入或任何无法确认的内容

建议的问题字段：

• Location
• Issue
• Suggestion
• Proposed Fix

资源使用

仅在需要时读取 references/ 下的文件。默认不要全部加载。如果模板很长，请先搜索相关章节，然后只读取所需部分。

当用户同时提供 d.ts 文件以及 public/system/error Markdown 路径时，请使用 scripts/check_api_doc_consistency.py。该脚本已涵盖重复且可信度较高的检查，包括：

• d.ts 标签提取和 @throws 解析
• public/system 文档的归属检查和链接方向检查
• 对 @syscap、@permission、@atomicservice、@systemapi、仅模型标签、@deprecated 和 @useinstead 的结构化字段检查
• 章节级和文档级错误码覆盖检查
• -sys.md 命名、标题和 Readme-CN.md 条目检查
• system 文档的混合模块说明检查
• 错误码文档中的必需块检查
• 基本版本标记检查，例如模块 since 说明和 <sup>x+</sup> 是否存在
• 页面内和相对 Markdown 链接解析

对于字段类检查，请优先采用脚本结果，而非手动搜索关键词。当前脚本会解析标记式文档字段，例如 系统接口、模型约束 和 需要权限，从而减少无关正文匹配造成的干扰。

对于 @since 的处理，仅从动态 API 文档的角度解释标签：

• @since x 表示动态 API 从版本 x 开始提供
• @since x dynamic 表示动态 API 从版本 x 开始提供
• @since x dynamic&static 表示动态和静态形式均从版本 x 开始提供；对于当前检查器，将 x 作为动态版本
• 当前文档检查器会忽略 @since x static
• @since x dynamiconly 表示该 API 仅支持动态形式，并从版本 x 开始提供
• 当前文档检查器会忽略 @since x staticonly

当前检查中，不要将仅适用于静态形式的版本标签视为文档版本要求。

不要在 SKILL.md 中硬编码会变化的模板措辞。脚本会从 scripts/doc_check_rules.json 读取这些可能变化的字面内容。

当仓库内模板或外部模板发生变化时：

1. 将新模板措辞与 scripts/doc_check_rules.json 进行比较。
2. 如果只更改了预期文本或必需块，请先更新 scripts/doc_check_rules.json。
3. 仅当规则逻辑本身不再有效时，才更新 scripts/check_api_doc_consistency.py。
4. 如果模板文件在本地可用，请使用 --js-template、--ts-template 和 --error-template 运行脚本，以便在配置的规则与当前模板文本不匹配时发出警告。

运行方式如下：

python3 scripts/check_api_doc_consistency.py \
  --api /path/to/file.d.ts \
  --public-doc /path/to/public.md \
  --system-doc /path/to/system.md \
  --error-doc /path/to/error.md \
  --readme-doc /path/to/Readme-CN.md \
  --js-template /path/to/native-template.md \
  --ts-template /path/to/ts-template.md \
  --error-template /path/to/errorcodes-template.md

--readme-doc 为可选参数。若省略，脚本会尝试从 public/system 文档目录推断 Readme-CN.md。 模板参数同样为可选参数，但可以额外检查规则文件是否仍与当前模板措辞一致，并在不一致时发出警告。

将脚本输出视为初步检查结果。除非需要澄清或确认脚本发现的问题，否则不要在报告中手动重复这些低层级规则。将人工审查时间用于检查语义缺漏、说明质量以及实现是否一致。