Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​
应用现代化计划

​
目标

在不破坏当前工作流或通过大规模重构掩盖风险的前提下，将应用推进到更简洁、更快速、也更易维护的产品状态。工作应以小而可审查的切片落地，并为每个受影响的表面提供证明。

​
原则

  • 除非某个边界确实正在造成变更、性能开销或用户可见的缺陷，否则保持当前架构不变。
  • 对每个问题都优先采用最小的正确修复，然后重复这一过程。
  • 将必需修复与可选优化分离，以便维护者无需等待主观决策也能落地高价值工作。
  • 保持面向插件的行为有文档可查，并确保向后兼容。
  • 在宣称回归已修复之前，先验证已发布行为、依赖契约和测试。
  • 优先改善主用户路径：引导、认证、聊天、提供方设置、插件管理和诊断。

​
第 1 阶段：基线审计

在变更之前先盘点当前应用。
  • 识别最主要的用户工作流及其对应的代码表面。
  • 列出无效的入口、重复设置、含糊的错误状态以及昂贵的渲染路径。
  • 为每个表面记录当前的验证命令。
  • 将问题标记为必需、推荐或可选。
  • 记录需要负责人审查的已知阻塞项，尤其是 API、安全、发布和插件契约变更。
完成定义：
  • 一份带有仓库根目录文件引用的问题清单。
  • 每个问题都包含严重性、负责人表面、预期用户影响以及建议的验证路径。
  • 不要将推测性的清理项混入必需修复中。

​
第 2 阶段：产品与 UX 清理

优先处理可见工作流并消除困惑。
  • 收紧围绕模型认证、网关状态和插件设置的引导文案与空状态。
  • 对于无法执行任何操作的死入口，移除或禁用它们。
  • 在各种响应式宽度下保持重要操作可见，而不是依赖脆弱的布局假设将其隐藏起来。
  • 合并重复的状态语言，让错误只有一个事实来源。
  • 为高级设置添加渐进式披露，同时保持核心设置快速完成。
推荐验证：
  • 对首次运行设置和现有用户启动流程进行手动 happy path 验证。
  • 针对任何路由、配置持久化或状态推导逻辑编写聚焦测试。
  • 对已变更的响应式表面截取浏览器截图。

​
第 3 阶段：前端架构收紧

在不进行大范围重写的前提下提升可维护性。
  • 将重复的 UI 状态转换移动到窄而类型化的辅助函数中。
  • 保持数据获取、持久化和展示职责分离。
  • 优先使用现有的 hooks、stores 和组件模式，而不是引入新的抽象。
  • 只有在能够降低耦合或澄清测试时，才拆分过大的组件。
  • 避免为局部面板交互引入大范围的全局状态。
必需护栏：
  • 不要因为文件拆分而作为副作用改变公开行为。
  • 保持菜单、对话框、标签页和键盘导航的无障碍行为不变。
  • 验证加载、空态、错误态和乐观状态仍能正确渲染。

​
第 4 阶段：性能与可靠性

针对经测量确认的痛点，而不是宽泛的理论优化。
  • 衡量启动、路由切换、大列表和聊天记录的成本。
  • 在性能分析证明确有价值的地方，用缓存的选择器或辅助函数替换重复且昂贵的派生数据。
  • 减少热路径上可避免的网络或文件系统扫描。
  • 在构建模型负载之前，保持 prompt、registry、文件、插件和网络输入的确定性排序。
  • 为热点辅助函数和契约边界添加轻量级回归测试。
完成定义：
  • 每项性能变更都记录基线、预期影响、实际影响和剩余差距。
  • 当可以进行廉价测量时，不要仅凭直觉提交性能修复。

​
第 5 阶段：类型、契约与测试加固

在用户和插件作者所依赖的边界点提升正确性。
  • 用判别联合或封闭代码列表替换宽松的运行时字符串。
  • 使用现有的 schema 辅助工具或 zod 验证外部输入。
  • 围绕插件清单、提供方目录、网关协议消息和配置迁移行为添加契约测试。
  • 将兼容性路径保留在 doctor 或修复流程中，而不是在启动时进行隐藏迁移。
  • 避免仅为测试而耦合插件内部；使用 SDK 外观和已文档化的入口导出。
推荐验证：
  • pnpm check:changed
  • 针对每个变更的边界执行定向测试。
  • 当惰性边界、打包或已发布表面发生变化时执行 pnpm build。

​
第 6 阶段：文档与发布就绪

让面向用户的文档与实际行为保持一致。
  • 随着行为、API、配置、引导或插件变化更新文档。
  • 仅针对用户可见的变化添加 changelog 条目。
  • 保持插件术语面向用户；仅在贡献者确实需要时使用内部包名。
  • 确认发布和安装说明仍与当前命令表面相符。
完成定义：
  • 相关文档与行为变更在同一个分支中更新。
  • 在触及生成文档或 API 漂移检查时，它们能够通过。
  • 交接中说明任何跳过的验证以及跳过原因。

​
推荐的首个切片

从一个范围受限的 Control UI 和引导流程审查开始：
  • 审计首次运行设置、提供方认证准备情况、网关状态和插件设置表面。
  • 移除无效操作并澄清失败状态。
  • 为状态推导和配置持久化添加或更新聚焦测试。
  • 运行 pnpm check:changed。
这能在有限的架构风险下提供较高的用户价值。

​
前端技能更新

使用本节来更新现代化任务中提供的、面向前端的 SKILL.md。如果要将此指导作为仓库本地的 OpenClaw skill，请先创建 .agents/skills/openclaw-frontend/SKILL.md，保留属于目标 skill 的 frontmatter，然后用以下内容添加或替换正文指导。 
# 前端交付标准

在实现或审查面向用户的 React、Next.js、桌面 webview 或应用 UI 工作时使用此 skill。

## 操作规则

- 从现有产品工作流和代码规范出发。
- 优先采用能改善当前用户路径的最小正确修复。
- 在交接中将必需修复与可选润色分开。
- 当需求是应用表面时，不要去构建营销页面。
- 在支持的视口尺寸下保持操作可见且可用。
- 移除无法执行操作的死入口，而不是保留无效控制项。
- 保持加载、空态、错误、成功和权限状态。
- 在添加新的基础原语之前，优先使用现有设计系统组件、hooks、stores 和图标。

## 实现清单

1. 识别主要用户任务以及负责它的组件或路由。
2. 在编辑前阅读本地组件模式。
3. 只修补能解决问题的最窄表面。
4. 为固定格式控件、工具栏、网格和计数器添加响应式约束，避免文本和悬停状态意外改变布局大小。
5. 保持数据加载、状态推导和渲染职责清晰。
6. 当逻辑、持久化、路由、权限或共享辅助函数发生变化时添加测试。
7. 验证主要 happy path 和最相关的边界情况。

## 视觉质量门槛

- 文本在移动端和桌面端都必须能容纳在其容器内。
- 工具栏可以换行，但控件必须始终可达。
- 当图标比文本更清晰时，按钮应使用熟悉的图标。
- 卡片应用于重复项、模态框和带边框的工具，而不是页面的每个部分。
- 避免单调的色彩方案和与操作内容竞争的装饰性背景。
- 密集的产品表面应优化为便于扫描、比较和重复使用。

## 交接格式

报告：

- 变更了什么。
- 用户行为发生了什么变化。
- 已通过的必需验证。
- 跳过了哪些验证以及具体原因。
- 可选的后续工作，并与必需修复清晰分开。