可视化界面重构¶

建筑网格化布局¶

布局问题¶

决策者：Dad
时间：2026-03-14 晚间

Dad 要求建筑不要堆叠，改为有间隔的长方形/正方形有序布局。

技术方案¶

决策者：bot

采用统一 gridPos helper 重构 buildings 布局： - 等距投影适配：使建筑在等距视角下更规整 - 网格统一：建筑与 agents 使用同一套布局算法 - 间距优化：避免视觉上的重叠和拥挤

问题根因¶

等距投影视角下，原先 4+3 网格与 agent 布局错位，造成： - 视觉不整齐 - 点击区域混乱 - 整体观感不佳

解决效果¶

建筑布局规整有序
视觉层次清晰
操作体验提升

点击交互重构¶

交互模式变更¶

决策者：Dad

要求改变交互模式：

"右键显示的功能，应改为点击每个模块直接打开对应效果"

实现策略¶

决策者：bot

取消"点击建筑后显示通用 UnitCard"的旧逻辑，改为 building → specific panel：

技术流程重构¶

检查点击流：selectEntity → bindEntityEvents → App.tsx
增加专用处理：WorldCanvas 增加 onBuildingClick
应用层路由：App.tsx 新增 handleBuildingClick
屏蔽通用卡片：UnitCard 对 building selection 做兜底屏蔽

映射关系¶

频道港口 → ChannelManager
技能工坊 → SkillManager  
插件工厂 → GovernancePanel.plugins
模型熔炉 → GovernancePanel.models
工具库 → GovernancePanel.tools
记忆宝库 → 独立面板
领主档案 → 独立面板

设计理念¶

建筑本身就是 OpenClaw 模块入口，直达面板比通用卡片更符合"模块化控制台"心智。

面板展示方式重构¶

弹窗改内嵌¶

决策者：Dad

要求不要弹窗，改为右下角展示对应面板。

技术架构调整¶

决策者：bot

状态管理统一¶

用 activePanel 替代多个 showXxx 布尔状态：

// 之前：多个布尔状态
const [showChannelManager, setShowChannelManager] = useState(false);
const [showSkillManager, setShowSkillManager] = useState(false);
// ...

// 之后：统一面板状态
const [activePanel, setActivePanel] = useState<PanelType | null>(null);

容器设计¶

共享右下角 slot：所有面板使用同一个显示区域
统一容器：引入 PanelShell 类似的容器思路
模式兼容：各面板增加 inline prop，保留 modal 兼容

问题修复¶

原有 5 个面板都是 fixed inset-0 弹窗，遮挡地图，不适合持续操作。

批量替换后需要补齐接口： - 手工补齐各 panel props interface 的 inline 属性 - 清理重复字段定义

最终效果¶

7 个建筑面板全部改为右下角内嵌显示
地图无遮挡，交互更像 RTS/dashboard
支持同时查看地图和面板内容

治理面板拆分¶

问题识别¶

决策者：Dad

点击 Gateway 显示治理面板，但插件/模型等不应混在一个大面板里。

拆分策略¶

决策者：bot

功能模块分离¶

将原来的"大杂烩"治理面板拆分为专门的功能面板： - Gateway → 系统总览面板 - 插件工厂 → 专门的插件管理面板 - 模型熔炉 → 专门的模型配置面板 - 工具库 → 专门的工具管理面板

工具库缺失补充¶

发现 GovernancePanel 只有 overview/agents/channels/models/plugins，缺少 tools tab。

解决方案：新增 ToolsTab，数据直接读取 buildings state。

围墙编辑功能¶

功能定位¶

为 ClawCraft 增加围墙编辑功能，让用户能够： - 定义区域：通过围墙划分功能区域 - 视觉分区：增强地图的可读性 - 布局规划：支持更复杂的王国布局

UX 迭代¶

时间：2026-03-15 凌晨

进行围墙工具的用户体验和性能优化： - 工具响应性：提升绘制工具的响应速度 - 视觉反馈：改进绘制过程中的视觉提示 - 操作直觉：让围墙编辑更符合用户直觉

架构演进意义¶

模块化设计确立¶

这次重构确立了 ClawCraft 的核心设计原则： - 专用面板：每个功能模块对应专门的管理界面 - 直达操作：减少中间层级，提升操作效率 - 视觉统一：保持整体界面的一致性和美观度

用户体验哲学¶

从技术展示工具转向用户产品： - 操作直观：点击建筑直达功能，符合直觉 - 界面整洁：避免弹窗遮挡，保持操作连续性 - 功能聚焦：每个面板专注特定功能，避免混乱

可扩展性基础¶

为后续功能扩展奠定了架构基础： - 标准化流程：建筑 → 面板的标准模式 - 组件复用：面板组件的标准化设计 - 状态管理：统一的面板状态管理机制

这次重构标志着 ClawCraft 从概念验证阶段进入产品化阶段，为后续的深度功能开发打下了坚实的基础。