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 实现、斜杠命令处理程序、帮助文本和命令测试用于命令和标志。
• 运行时源码和测试用于生命周期、队列、权限、回退、超时和提供程序行为。
• 协议文档、SDK 外观和合约测试用于 API 和插件接口。
• 现有文档仅作为次要证据，除非目标完全是概念性的。

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

5. 规划移动的材料

将细节移出目标页面时，在编辑前记录目标位置：

• 现有页面：命名页面和章节。
• 新页面：选择页面类型、slug、标题、前言摘要、doc-schema-version: 1 和 read_when 提示。
• 目标页面：在读者需要更深入细节的地方保留简短的摘要和链接。

避免重复的真相。如果同一合约出现在多个地方，选择一个规范的页面并链接到它。

6. 重写

按以下顺序重写：

1. 在首页回答读者能做什么以及为什么存在此页面。
2. 将推荐路径放在替代方案之前。
3. 仅保留决策制定和常见的操作细节在主流程中。
4. 将详尽的表格和罕见细节移动到计划中的参考页面。
5. 保留简洁的路由表，当它们帮助读者选择命令、配置路径、工作台、插件、提供程序或参考资料时。
6. 从可观察的症状添加故障排除，而不是内部猜测。
7. 链接相关的概念、指南、参考资料、诊断和相邻工具。

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

除非用户明确要求草稿，否则不要留下占位符，例如 "TODO"、"TBD" 或 "see docs"。

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 文档或生成的基线被修改时，运行生成的文档检查

尽可能运行页面中的命令和示例。如果您无法验证某个行为敏感的主张，请删除该主张，在进展报告中标记不确定性，或询问缺失的来源。

最终报告

报告：

• 目标页面发生了哪些变化。
• 哪些细节被移动以及它们的目标页面。
• 哪些真相来源检查支持了行为敏感的主张。
• 进行了哪些验证以及出于无关原因失败的内容。

不要包含冗长的重写日志。只有在存在风险时才优先列出剩余风险。