体验优化与配置修复¶

文档与代码清理¶

决策者：Dad
时间：2026-03-13 早晨

清理要求¶

Dad 明确要求： - 只保留最新 PRD - 清理历史研究日志 - 代码去垃圾，只保留最新版本

清理效果¶

bot 执行后达成的效果： - 体积优化：代码从约 300MB 降到 680KB - 构建验证：确保清理后构建仍然通过 - 维护性提升：避免旧版本误导后续开发

价值意义¶

降低后续维护成本
提升开发环境启动速度
减少版本混乱和技术债务

移动端交互改造¶

问题识别¶

Dad 指出手机上右键操作不便，需要改为更适合移动端的交互方式。

解决方案：长按替代右键¶

bot 实现的技术方案：

主容器长按检测¶

在主容器增加 pointerdown / pointerup 计时：

// 长按检测逻辑
let pressTimer;
const onPointerDown = () => {
  pressTimer = setTimeout(() => {
    // 触发长按事件
  }, 500);
};
const onPointerUp = () => {
  clearTimeout(pressTimer);
};

PixiJS 实体长按支持¶

在 PixiJS entity 绑定中增加移动端长按支持，确保游戏内元素也能响应长按操作。

配套修复¶

tsconfig 路径修正：从指向旧 src/ 改为正确路径
依赖补充：安装 @types/node

结果验证¶

前后端编译通过
移动端可用性显著提升
交互体验更加统一

频道配置问题修复¶

问题现象¶

Dad 发现测试机明明配置了 Mattermost 频道，但界面没有显示。

根因分析¶

bot 深入分析后发现的技术问题：

配置读取问题¶

Mattermost 频道配置：位于 channels 配置下
plugin 代码问题：只检查 plugins.entries
状态初始化问题：channelStatuses Map 只定义和读取，从未 .set() 填充

代码逻辑缺陷¶

// 问题：只定义了 Map，但从未填充
const channelStatuses = new Map();

// 修复：在初始化时填充频道状态
function initializeChannelStatus(config) {
  if (config.channels) {
    Object.keys(config.channels).forEach(channelKey => {
      channelStatuses.set(channelKey, 'active');
    });
  }
}

解决方案¶

配置读取修复：从 openclaw.json 的 channels 配置读取并初始化频道状态
前端显示增强：ResourceBar 增加频道数量显示，不仅显示 SSE 连接状态

修复结果¶

mattermost 频道被正确检测和显示
重启后频道状态正确恢复
界面显示与实际配置保持一致

地图初始化增强¶

产品需求修正¶

决策者：Dad

Dad 指出重要产品问题：

"安装好 ClawCraft 后，地图初始态必须展示 OpenClaw 的核心模块"

问题分析¶

当前地图只显示一个 gateway，不符合"完整 OpenClaw 王国"的预期。

目标状态¶

安装后应展示： - skills：技能模块 - plugins：插件模块 - channels：频道模块 - tools：工具模块 - memory：记忆模块 - agents：代理模块

目标是像一个"小国家"的初始状态，而不是空地图。

技术实现：建筑化映射¶

bot 开始实现"建筑化"映射：

后端数据结构¶

interface KingdomBuilding {
  id: string;
  type: 'skill' | 'plugin' | 'channel' | 'tool' | 'memory' | 'agent';
  name: string;
  status: 'active' | 'inactive' | 'error';
  position: { x: number; y: number };
}

状态管理增强¶

getWorldState 扩展：增加 buildings 数据
启动时初始化：读取 config，初始化 agents/buildings
动态刷新：状态变化时触发 refreshBuildings

前端同步改造¶

Zustand store 扩展：增加 buildings 状态
setFullState 支持：支持 buildings 数据更新
WorldCanvas 渲染：渲染 building 实体
UnitCard 集成：支持点击 building 查看详情

技术架构意义¶

抽象层建立¶

这次优化建立了重要的抽象映射： 抽象配置项 → 地图建筑/设施

这个映射为后续所有配置可视化功能奠定了基础架构。

初始化策略¶

确立了 ClawCraft 的初始化原则： - 完整展示：启动时展示完整的 OpenClaw 生态 - 状态同步：确保界面状态与实际配置一致 - 动态更新：配置变更时实时更新界面

用户体验改进¶

移动端友好：支持移动端操作
视觉完整性：初始界面展示系统完整性
配置可见性：让隐藏的配置问题变得可见

这次体验优化标志着 ClawCraft 从技术验证工具向实用产品的重要进步。