Appearance
OpenClaw 应用现代化计划提供了一条渐进、可验证的改造路径：从基线审计开始，逐步完成产品体验清理、前端架构收紧、性能优化、类型与测试强化，最后对齐文档与发布流程。每个阶段都有明确的完成定义和验证方式，前端交付标准则进一步为 React、Next.js 及桌面 WebView 的 UI 工作提供可操作的 checklist 与视觉质量门禁。
OpenClaw 应用现代化计划与前端交付标准
目标
在不对当前工作流造成破坏、也不通过大范围重构隐藏风险的前提下，推动应用变得更干净、更快、更易维护。所有工作应以小、可审查的切片落地，并且每个触及的层面都要有验证证据。
原则
- 除非边界被证明正在引起变更摩擦、性能成本或用户可见的 bug，否则保留当前架构。
- 对每个问题优先选择最小的正确补丁，然后重复。
- 将必需的修复与可选的优化分开，使维护者无需等待主观决策就能落地高价值工作。
- 保持面向插件的行为文档化且向后兼容。
- 在声称回归已修复之前，验证已发布的行为、依赖契约和测试。
- 优先改善主要用户路径：初始配置、认证、聊天、Provider 设置、插件管理和诊断。
第一阶段：基线审计
在修改之前盘点当前应用状态。
- 识别最重要的用户工作流及其所属的代码表面。
- 列出失效的交互元素、重复设置、不清晰的错误状态以及昂贵的渲染路径。
- 记录每个表面的当前验证命令。
- 将问题标记为必需、推荐或可选。
- 记录需要负责人审查的已知阻塞项，特别是 API、安全、发布和插件契约变更。
完成定义：
- 一份问题列表，包含仓库根目录的文件引用。
- 每个问题标注严重性、所属表面、预期用户影响以及建议的验证路径。
- 不得将推测性的清理项混入必需修复。
第二阶段：产品与 UX 清理
优先处理可见的工作流，消除混乱。
- 精简初始配置文案和模型认证、网关状态、插件设置相关的空状态提示。
- 删除或禁用无法执行操作的失效交互元素。
- 保持重要操作在不同响应式宽度下可见，避免脆弱的布局假设将其隐藏。
- 合并重复的状态描述语言，使错误信息有唯一真相源。
- 对高级设置采用渐进式披露，同时保持核心配置流程快速。
推荐验证方法：
- 首次运行设置和现有用户启动的手动快乐路径。
- 对路由、配置持久化或状态推导逻辑进行针对性测试。
- 对发生变化的响应式表面进行浏览器截图。
第三阶段：前端架构收紧
不进行全面重写，提升可维护性。
- 将重复的 UI 状态转换迁移到窄类型的辅助函数中。
- 保持数据获取、持久化和呈现职责分离。
- 优先使用现有的 hooks、store 和组件模式，而非引入新的抽象。
- 仅当能够降低耦合度或明确测试边界时，才拆分过大的组件。
- 避免为局部面板交互引入宽泛的全局状态。
强制性护栏：
- 不得因文件拆分而改变公开行为作为副作用。
- 保持菜单、对话框、标签页和键盘导航的无障碍行为完整。
- 验证加载态、空态、错误态和乐观状态仍然正确渲染。
第四阶段：性能与可靠性
针对可测量的痛点，而非理论上的广泛优化。
- 测量启动、路由切换、大列表和聊天记录的耗时。
- 当性能剖析证明有价值时，用记忆化选择器或缓存辅助函数替换重复的高成本派生数据。
- 减少热路径上不必要的网络或文件系统扫描。
- 在模型负载构建之前，确保 prompt、注册表、文件、插件和网络输入的确定性顺序。
- 为核心辅助函数和契约边界添加轻量级回归测试。
完成定义：
- 每个性能变更记录基线、预期影响、实际影响和剩余差距。
- 当低成本测量可用时，不得仅凭直觉提交性能补丁。
第五阶段：类型、契约与测试强化
在用户和插件作者依赖的边界点上提升正确性。
- 用特化联合类型或封闭代码列表替代松散的运行时字符串。
- 使用现有 schema 辅助函数或 zod 验证外部输入。
- 针对插件清单、Provider 目录、网关协议消息和配置迁移行为添加契约测试。
- 将兼容性路径保留在 doctor 或修复流程中，而不是在启动时进行隐藏迁移。
- 避免测试与插件内部实现耦合；使用 SDK 外观和文档化的导出。
推荐验证方法：
- 运行
pnpm check:changed - 对每个变更边界进行针对性测试。
- 当惰性边界、打包或公开表面变更时，运行
pnpm build
第六阶段：文档与发布就绪
使面向用户的文档与行为保持一致。
- 随行为、API、配置、初始配置或插件变更更新文档。
- 仅在用户可见的变更中添加 changelog 条目。
- 保持插件术语面向用户；仅在贡献者需要时才使用内部包名。
- 确认发布和安装指令仍然与当前命令集匹配。
完成定义：
- 相关文档在与行为变更相同的分支中更新。
- 当触及生成文档或 API 漂移检查时，它们必须通过。
- 交接时说明跳过的任何验证及其具体原因。
推荐首个切片
从一个范围可控的 Control UI 和初始配置优化开始：
- 审计首次运行设置、Provider 认证就绪状态、网关状态和插件设置表面。
- 移除失效操作，明确失败状态。
- 添加或更新针对状态推导和配置持久化的针对性测试。
- 运行
pnpm check:changed
这能在有限的架构风险下提供高用户价值。
前端交付标准
如果采用这份指导作为仓库本地的 OpenClaw 技能，请先创建 .agents/skills/openclaw-frontend/SKILL.md，保留该目标技能应有的 frontmatter，然后将正文指导替换为以下内容。
markdown
# Frontend Delivery Standards
Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.
## Operating rules
- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
new primitives.
## Implementation checklist
1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
change.
7. Verify the main happy path and the most relevant edge case.
## Visual quality gates
- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
use.
## Handoff format
Report:
- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.常见问题
这个现代化计划是否要求一次性完成所有阶段？
不。计划设计为可选顺序切块落地，每个阶段都有独立的完成定义和验证方法。推荐从第一阶段基线审计开始，但实际上可以跳过或合并阶段，只要每个修补的层面都有验证。
前端交付标准适用于哪些 UI 组件？
适用于所有面向用户的 React、Next.js、桌面 WebView 或应用 UI 工作，包括主界面、Control UI、配置面板和插件外部表面。不适用于独立的营销页面或与产品工作流无关的页面。
如何验证现代化改造是否成功？
每个阶段都有自己的验证方法：第一阶段完成定义要求问题列表和验证路径；第二阶段推荐手动快乐路径和浏览器截图；第四阶段要求每个性能变更记录基线‑预期‑实际差距；第五阶段要求运行 pnpm check:changed（如果适用）。所有变更应附带可重复的验证步骤。