openclaw-refactor-docs

OpenClaw 重构文档

概述

当用户给出一个目标 OpenClaw 文档页面，并要求 重写、重构、重新组织、拆分、缩短或改进它时，使用此技能。

本技能基于 technical-documentation：请使用该技能来遵循页面类型、 结构、示例、可发现性和验证方面的要求。本技能还增加了 重构工作流，以避免在进行大规模文档重构时丢失准确行为。

输入

必需：

• 目标文档页面路径，例如 docs/plugins/codex-harness.md。

可选：

• 期望的页面类型，例如主题页面、指南、参考或故障排查。
• 具体目标，例如缩短主页面、将详细信息移至参考页面，或 与当前 CLI 行为保持一致。
• 相关源文件、模式、命令、测试、规范或 PR。

如果目标页面缺失或含义不明确，请在编辑前提出一个简明的问题。否则，继续执行。

工作约定

在既定范围内，将目标页面重构得更有用、更简洁、更全面。

不要将重写视为丢弃行为事实的许可。应保留、 验证、移动或明确停用现有材料。错误的文档比冗长的文档更糟糕。

建议采用以下拆分方式：

• 主题页面或指南页面涵盖 80/20 路径、读者必须做出的决策、安全 设置、最小可靠验证、常见故障和后续链接。
• 参考页面涵盖完整字段、默认值、枚举、限制、优先级 规则、API 契约、局部内部实现和少见的调试细节。
• 故障排查页面从可观察的症状入手，并将其映射到检查项、 原因和修复方法。

工作流

1. 加载文档标准

先阅读 ../technical-documentation/SKILL.md。在重构过程中始终应用其页面类型、样式、 示例、导航和验证方面的指导。

如果可用，运行 pnpm docs:list，然后只阅读目标页面和重构可能 需要的入口点、参考页面或相关页面。

2. 对页面进行分类

编辑前，依据 technical-documentation 确定预期的页面类型。

如果当前页面混用了多种页面类型，请选择主要页面类型，并规划其他内容的去向：

• 将完整的契约移至现有或新的参考页面。
• 将基于症状的内容移至现有或新的故障排查页面。
• 如果狭窄的设置工作流会打断主要路径，则将其移至指南页面。
• 当读者需要这些内容来完成工作流时，在主页面中保留简洁的路由、 决策和安全细节。

3. 保留并审查现有事实

重写前，从旧页面创建一份工作清单。其中应包括：

• 配置字段、标志、命令、斜杠命令、环境变量、默认值、枚举、 可空值和约束。
• 优先级规则、回退行为、上限、限制、速率限制、超时、 生命周期状态、排队行为和兼容性规则。
• 身份验证、权限、审批、沙箱、安全、隐私和破坏性操作 行为。
• 设置要求、受支持的版本、依赖项、操作系统、 凭据和账户要求。
• 错误消息、故障排查症状、诊断和恢复步骤。
• 示例、预期输出、命令路由表和交叉链接。

对于每项事实，选择一种处理方式：

• 保留在重构后的目标页面中。
• 移至指定的现有页面。
• 移至指定的新页面。
• 因当前源码证明其已过时或超出范围而将其删除。

不要根据名称或意图推断默认值、权限、策略、超时行为或安全态势。 请验证这些内容。

4. 查找事实来源

对于每一项与行为密切相关的论断，使用最接近的权威来源：

• 对于配置字段，使用公开模式、插件清单、生成的配置文档或 导出的类型。
• 对于命令和标志，使用 CLI 实现、斜杠命令处理程序、帮助文本和命令测试。
• 对于生命周期、队列、权限、回退、超时和提供商行为，使用运行时源代码和测试。
• 对于 API 和插件接口，使用协议文档、SDK 外观层和契约测试。
• 除非目标纯属概念性内容，否则仅将现有文档作为辅助证据。

如果页面承诺提供参考内容，请将其表格与模式、清单、CLI 帮助、生成的文档或 导出的类型进行比较。缺少公开字段、默认值、优先级规则、上限或副作用都属于 正确性缺陷。

5. 规划迁移内容

将详细信息从目标页面移出时，请在 编辑前记录其 destination：

• 现有页面：注明页面名称和章节。
• 新页面：选择页面类型、slug、标题、前置元数据摘要、 doc-schema-version: 1 和 read_when 提示。
• 目标页面：保留简短摘要，并从读者需要了解详细信息的 position 添加链接。

避免出现重复的事实来源。如果同一契约出现在多个位置，请选择一个规范页面并 链接到该页面。

6. 重写

按以下顺序重写：

1. 让首屏说明读者可以做什么，以及本页为何存在。
2. 将推荐路径放在替代方案之前。
3. 主流程中仅保留决策所需内容和常用操作详细信息。
4. 将详尽表格和冷门详细信息移至计划好的参考页面。
5. 如果简洁的路由表有助于读者选择命令、配置路径、测试框架、插件、提供商或 参考资料，请保留这些表格。
6. 根据可观察到的症状添加故障排查内容，而不是根据内部推测。
7. 链接相关概念、指南、参考资料、诊断工具和相邻工具。

对于重构迁移、创建或实质性重写的每个文档页面，在其 YAML 前置元数据中添加 doc-schema-version: 1。仅将其应用于文档页面文件，而不应用于 docs.json、 术语表 JSON 或其他非页面元数据。如果迁移后的页面由生成器生成，请更新生成器， 使重新生成时保留该标记，而不是手动编辑生成的输出。

除非用户明确要求提供草稿，否则不要留下“TODO”、“TBD”或“参见文档”之类的 占位内容。

7. 比较新旧内容

编辑后，比较新旧页面：

• 确认所有与行为密切相关的事实均已保留、迁移，或在有来源依据的情况下有意删除。
• 检查主页面是否仍从头到尾涵盖 80/20 场景。
• 检查参考页面是否仍详尽涵盖其声称的范围。
• 检查目标页面中的链接能否到达迁移后的详细信息。
• 检查标题是否稳定、可搜索且面向行动。

如果重构有意删除相关内容，请在最终报告中说明其迁移位置或删除原因。

8. 验证

对涉及的范围运行最小且可靠的文档检查：

• pnpm docs:list
• git diff --check -- <touched-files>
• 针对相关文件运行 pnpm exec oxfmt --check --threads=1 <touched-files>
• pnpm docs:check-mdx
• pnpm docs:check-links
• 链接文本、导航、标签或术语表界面发生变化时，运行 pnpm docs:check-i18n-glossary
• 涉及模式、生成的配置文档、API 文档或生成的基线时，运行生成文档检查

尽可能运行页面中的命令和示例。如果无法验证某项与行为密切相关的论断， 请删除该论断、在工作进行中报告中标注不确定性，或询问缺失的来源。

最终报告

报告：

• 目标页面中更改了什么。
• 哪些详细信息被迁移，以及迁移到了哪些目标页面。
• 哪些事实来源检查为与行为密切相关的论断提供了依据。
• 运行了哪些验证，以及哪些验证因无关原因而失败。

不要包含冗长的重写工作日志。仅在存在剩余风险时将其置于开头。