一、技能概述
该技能在用户给出目标文档页面并要求重写、重构、重组、拆分、精简或改进时使用。它建立在 openclaw-docs 技能之上——后者负责风格、页面类型、结构、示例、可发现性和验证——而本技能增加了重构所需的工作流，以避免在重大文档重构期间丢失准确的行为描述。
二、核心功能
1. 页面类型分类
在编辑之前，技能会先判断目标页面的预期类型，如果当前页面混合了多种页面类型，则选择主要类型并规划其他材料的去向：
| 页面类型 | 职责 |
|---|---|
| Topic/Guide 页面 | 覆盖 80/20 路径、读者必须做出的决策、安全设置、最小可靠验证、常见故障及链接 |
| Reference 页面 | 覆盖详尽的字段、默认值、枚举、限制、优先级规则、API 契约、内部实现细节和罕见调试信息 |
| Troubleshooting 页面 | 从可观察的症状出发，映射到检查项、原因和修复方案 |
2. 行为事实审计清单
在重写之前，技能会从旧页面创建一个工作清单，包括：
-
配置字段、标志、命令、斜杠命令、环境变量、默认值、枚举、可空值和约束
-
优先级规则、回退行为、上限、限制、速率限制、超时、生命周期状态、队列行为和兼容性规则
-
认证、权限、审批、沙箱、安全、隐私和破坏性操作行为
-
设置要求、支持的版本、依赖项、操作系统、凭证和账户要求
-
错误消息、故障排查症状、诊断和恢复步骤
-
示例、预期输出、命令路由表和交叉链接
对于每条事实，选择以下结果之一：
-
保留在重构后的目标页面中
-
移动到某个特定现有页面
-
移动到某个特定新页面
-
删除（因为当前源码证明其已过时或超出范围）
关键原则：不得从名称或意图推断默认值、权限、策略、超时行为或安全态势——必须验证它们。
3. 真相来源验证
对于每条行为敏感的声明，使用最近的权威来源进行验证：
| 内容类型 | 验证来源 |
|---|---|
| 配置字段 | 公共 Schema、插件 Manifest、生成的配置文档或导出类型 |
| 命令和标志 | CLI 实现、斜杠命令处理器、帮助文本和命令测试 |
| 生命周期、队列、权限等 | 运行时源码和测试 |
| API 和插件表面 | 协议文档、SDK Facades 和契约测试 |
| 现有文档 | 仅作为次要证据，除非目标纯属概念性内容 |
关键原则：如果某个页面承诺提供参考，则必须将其表格与 Schema、Manifest、CLI 帮助、生成文档或导出类型进行比对。缺失的公共字段、默认值、优先级规则、上限或副作用都属于正确性 Bug。
4. 重构顺序
技能按以下顺序进行重写：
-
首屏回答：这个页面能让读者做什么，以及为什么存在这个页面
-
推荐路径优先：将推荐路径放在替代方案之前
-
主流程精简：仅保留决策制定和常见操作细节在主流程中
-
详表移至参考：将详尽的表格和罕见细节移至规划的参考页面
-
保留路由表：当路由表有助于读者选择命令、配置路径、Harness、插件、Provider 或参考时予以保留
-
症状驱动排障：从可观察的症状出发添加故障排查，而非内部猜测
-
链接相关内容：链接相关概念、指南、参考、诊断和相邻工具
禁止在文档中留下 TODO、TBD 或 see docs 等占位符，除非用户明确要求草稿。
5. 验证检查
技能运行以下检查来验证修改：
-
pnpm docs:list -
git diff --check -
pnpm exec oxfmt --check -
pnpm docs:check-mdx -
pnpm docs:check-links -
pnpm docs:check-i18n-glossary（当链接文本、导航、标签或术语表发生变化时） -
当 Schema、生成的配置文档、API 文档或生成基线被修改时，运行生成文档检查
关键原则：尽可能从页面运行命令和示例。如果无法验证某条行为敏感声明，则删除该声明、在报告中标记不确定性，或询问缺失的来源。
三、主要用途
-
重大文档重构
当需要对现有文档页面进行大规模重写、重组或拆分时，确保不会在过程中丢失任何行为事实。 -
文档类型规范化
将混合了多种页面类型（Topic/Guide/Reference/Troubleshooting）的页面拆分为各自独立的页面，每个页面承担明确的职责。 -
文档与源码同步
当 CLI 行为、配置字段或 API 发生变化时，通过源审计确保文档与最新源码保持一致。 -
精简冗长文档
将详尽的技术细节移至参考页面，让主页面聚焦于 80/20 路径和读者决策，提升可读性。 -
故障排查文档化
从可观察的症状出发，系统化地构建故障排查内容，而非基于内部猜测。
四、最终报告要求
技能在完成重构后必须输出报告：
-
目标页面发生了什么变化
-
哪些细节被移动了，以及它们的目标页面
-
哪些真相来源检查支撑了行为敏感的声明
-
运行了哪些验证以及哪些验证失败
五、重要原则
-
不正确文档比冗长文档更糟糕——必须在重构中保留、验证、移动或明确淘汰现有材料。
-
避免重复真相——如果同一契约出现在多个地方，选择一个规范页面并链接到它。
-
Frontmatter 标记：为每个被迁移、创建或实质性重写的文档页面添加
doc-schema-version: 1。 -
生成页面处理：如果迁移的页面是生成的，更新生成器以便在重新生成时保留该标记，而非手动编辑生成输出。
六、总结
OpenClaw Refactor Docs 是一个源审计驱动的文档重构技能，通过强制性的行为事实清单、真相来源验证和系统化的页面类型分类，确保在重大文档重构过程中不丢失任何准确的行为描述。它适用于 OpenClaw 项目需要对现有文档进行大规模重写、重组、拆分或精简的场景，是 openclaw-docs 技能在重构场景下的必要补充。
