ClawCraft¶

帝国时代风格的 OpenClaw 系统游戏化操作界面 — 不只是监控面板，而是可交互的 RTS 风格工作台。

产品定位¶

ClawCraft 将 OpenClaw Gateway 的配置、监控、操作能力，以帝国时代/RTS 游戏的视觉语言呈现。用户通过点击建筑、拖拽单位、查看数据流等方式，完成原本需要在命令行或配置文件中操作的工作。

核心理念：用 RTS 界面替代传统 channel 对话和配置工作。

技术栈¶

层级	技术选型	说明
前端框架	React + TypeScript	组件化开发
构建工具	Vite	快速启动，适合迭代
UI 组件	shadcn/ui	现代化组件库
游戏渲染	PixiJS	2D WebGL 渲染引擎
状态管理	Zustand	轻量状态库
后端形态	OpenClaw Gateway Plugin	直接接入 Gateway 事件流
通信协议	SSE + HTTP	实时事件 + REST API
认证	Logto JWT	统一身份认证

演进时间线¶

日期范围	阶段	关键事件	详情
03-10~03-12	立项与 PRD	从像素风网页升级为 RTS 游戏界面，完成概念映射与 PRD v2.0	[[03-10-立项与PRD]]
03-13~03-15	UI 重构与功能覆盖	2D 地图化、围墙系统、建筑网格化、100% 功能覆盖	[[03-13-UI重构与功能覆盖]]
03-16~03-18	部署与认证	测试服迁移、Logto 认证接入、代码重构为 plugin/UI 双目录	[[03-16-部署与认证]]
03-19~03-20	稳定性修复	SSE 死循环根因定位、开发环境 HTTPS 化、v0.9.5 优化	[[03-19-稳定性修复]]
03-21~03-23	多端联调	Clawline 流式输出打通、多服务器隔离、协议层收敛	[[03-21-多端联调]]
03-24~03-31	Portal 演进	从配置工具转向工作台、项目管理门户雏形、主题系统	[[03-24-Portal演进]]
04-01~04-03	项目治理	项目发现系统、curated 保护机制、代码库合并	[[04-01-项目治理]]

关键时刻¶

1. 产品方向定型（03-11）¶

背景：最初方案是做普通"研究项目管理网页"，经历了 Next.js、像素风、React/shadcn 等尝试。

转折：Dad 明确提出目标不是"像素字体网页"，而是真正有游戏感的系统操作界面，要像 Age of Empires / RTS 游戏。

决策： - 放弃 Next.js（构建卡死、响应慢） - 改为 Vite + React + PixiJS - 正式命名为 ClawCraft

影响：这个决策奠定了项目的技术栈和产品方向，后续所有迭代都围绕"游戏化操作界面"展开。

2. OpenClaw 概念映射确定（03-12）¶

问题：OpenClaw 的 Gateway、Agents、Sessions、Channels 等概念如何在 RTS 世界中呈现？

方案（经过 Gemini + GPT-5.4 多轮辩论）： | OpenClaw 概念 | RTS 映射 | |---------------|----------| | Gateway | 王国核心/主城 | | Agents | 领主/指挥官 | | Sessions | 探险者/单位 | | Channels | 港口/使馆 | | Skills | 技能工坊 | | Plugins | 插件工厂 | | Memory | 记忆宝库 | | Models | 模型熔炉 |

价值优先级纠偏：Dad 强调 ClawCraft 不是"监控面板"，而是完整的游戏化操作界面，监控和操作同等重要。

3. SSE 死循环根因定位（03-20）¶

现象：拖拽建筑后界面卡死，SSE 连接数从个位数暴涨到 467。

错误假设： - 误以为是 layout.save 触发 broadcast - 误以为是 Caddy 未正确 flush SSE - 误以为是 token 获取失败导致重连

真正根因： 1. 两层 Caddy 都缺少 flush_interval -1，导致 SSE 被缓冲 2. 前端 useSSE / authFetch 不断调用 getAccessToken() 3. effect 依赖不稳定，连接建立后很快被清理，旧连接 onerror 又触发重连

修复：

flush_interval -1

同时移除开发模式下的 getAccessToken() 调用，稳定 effect 依赖。

经验：SSE 经过反向代理必须显式配置；前后端认证状态必须同步。

4. 从"配置工具"转向"工作台"（03-15~03-16）¶

问题定义：ClawCraft 最大问题是"产出没有承载位置、没有聊天入口、使用过程中创建的内容和产出物没有体现"。

核心转变： - 配置面板：只能配置 OpenClaw 参数 - 工作台：承载工作过程与产出，有交互入口

Workbench 三大功能： 1. 产出物承载 2. 聊天/指令入口 3. 活动与文件可见性

5. 协议层与 UI 层解耦（03-23）¶

背景：Client-Web 出现消息串台、流式输出消失、连接重复等问题。

关键洞察：很多问题不是 React 本身，而是协议事件缺字段： - history.sync 缺少 agentId - text.delta 缺少 agentId - thinking.start 缺少 agentId

架构决策： - 从 Client-Web 抽离 @clawlines/sdk - 协议层与展示层解耦 - 先用 H5 直连环境降维验证协议问题

核心功能清单¶

已实现（v0.9.5）¶

世界视图 - [x] 2D 地图画布（无限滚动、pinch zoom） - [x] 建筑网格化布局（Gateway 3×3、Agent 2×2、Building 3×2） - [x] 数据流连线与粒子动画 - [x] 围墙/砖块编辑系统（刷墙、橡皮擦、Shift 直线） - [x] 建筑拖拽与位置持久化

管理面板 - [x] GatewayPanel：重启、状态监控 - [x] AgentPanel：Agent 管理 - [x] ChannelManager：频道配置、测试 - [x] SkillManager：技能安装/卸载（clawhub 联调） - [x] PluginPanel：插件启用/禁用 - [x] MemoryPanel：记忆查看 - [x] ModelsPanel：模型测试连接 - [x] ToolsPanel：工具分类展示 - [x] CronManager：Cron Job 管理

交互与体验 - [x] 点击建筑打开对应面板 - [x] 右下角统一面板展示 - [x] 移动端长按支持 - [x] 音效系统 - [x] 版本号显示

架构决策记录¶

决策	选择	理由
前端框架	React + Vite	快速迭代，不需要 SSR
渲染引擎	PixiJS	2D 游戏渲染成熟方案
状态管理	Zustand	轻量、适合游戏状态
后端形态	OpenClaw Plugin	直接接入 Gateway 事件流
认证方案	Logto JWT	复用现有认证链路
开发环境	HTTPS 子域名	满足 `Crypto.subtle` 要求
Cron 实现	直接读写 jobs.json	CLI 太慢（5.5s），改为文件操作
建筑布局	Grid + cellSpan	确保内部格线对齐

部署约束¶

⚠️ ClawCraft 绝不能部署到本机，只能部署到远程测试服务器。

生产环境： - 域名：craft.clawlines.net - 服务器：owl (实际解析到 owl) - 部署方式：静态目录 serve（非 Docker）

测试环境： - 域名：craft.dev.dora.restry.cn - 内网反代到 owl

重要路径¶

# 前端源码
workspace-research-craft/project/frontend/

# 后端插件
workspace-research-craft/project/plugin/

# 测试服前端目录
/home/claw/clawcraft/frontend (on owl)

# 测试服 API
proxy-kr-tiger:18851