ClawCraft MVP 开发¶

双轨开发策略¶

决策者：bot
时间：2026-03-12 中午到下午

架构拆分¶

bot 将 MVP 拆成两个独立代码包： - plugin：后端，接入 OpenClaw，采集状态、暴露 API/SSE - frontend：前端，RTS 风格世界视图与 HUD

选型理由¶

插件层：负责"OpenClaw 语义 → 世界状态"转换
前端层：负责"世界状态 → 游戏化可视化"渲染
开发便利：支持 Mock 与真实环境切换

技术栈选择¶

前端技术栈¶

PixiJS：世界视图 / 等距实体渲染
Zustand：状态管理
Vite：开发与构建
Web Audio API：程序化音效

端口配置¶

本地开发：
Vite dev server: 18821
Mock server: 18790
测试机部署：
Mock server: 18850
前端访问: 18851

Codex 协助与问题¶

Codex 使用经验¶

bot 同时启动两个 Codex 任务开发 plugin/frontend，遇到问题： 1. 生成了文件但未 commit 2. 任务超时退出 3. 前端关键组件缺失：HUD、World、Controls 目录为空

解决方案¶

手动补全：bot 手动补全核心组件
保留可用部分：保留 Codex 已生成的 store/types/hooks
编译验证：修复 TypeScript 编译错误

经验教训¶

Codex 适合铺骨架，不适合无人监管完成复杂集成
关键路径仍需人工收尾与编译验证
生成代码必须经过实际构建测试

Mock 服务设计¶

双轨验证策略¶

决策者：Dad

Dad 明确要求的"双轨验证"策略： - 本地/前端：mock 快速迭代 UI - 测试机：真实 OpenClaw 环境验证插件与事件流

Mock API 设计¶

前端通过 Vite proxy 指向 mock/OpenClaw API，支持： - 系统状态模拟 - 事件流 SSE - 配置接口模拟 - 操作响应模拟

E2E 验证成功¶

真实数据测试¶

最终在测试机完成真实 OpenClaw 数据 E2E 验证： - 测试结果：7/7 测试通过 - 数据展示：3 个 Agent、8 个 Session（其中 6 个活跃） - 功能验证：前端成功显示真实 OpenClaw 系统状态

测试场景扩展¶

为验证 RTS 风格界面，bot 创建了多个测试场景： - 创建多个 agent - 启动多个 subagent - 模拟 RTS 式活动和状态变化

技术问题与修复¶

组件 API 统一¶

解决 Codex 生成代码中的问题： - 问题：Badge 组件缺 variant prop，Codex 使用了 tone - 解决：统一组件 API，修复 TS 编译错误 - 结果：TypeScript 编译通过，构建成功

部署配置¶

测试机部署时的端口调整： - Mock server 端口从 18790 改为 18850 - 适配测试机开放端口策略 - 通过代理正确转发请求

里程碑意义¶

这次 MVP 开发成功验证了： 1. Plugin 架构可行性：可以通过 Plugin 获取 OpenClaw 完整状态 2. RTS 界面可行性：游戏化界面能够承载复杂系统状态 3. 双轨开发效率：Mock + 真实环境并行开发大幅提升效率 4. Codex 辅助边界：明确了 AI 辅助工具的适用范围和限制

为后续从"只读监控"升级到"可配置操作工作台"奠定了坚实的技术基础。