zclaw_openfang/CLAUDE old.md

ZCLAW 协作与实现规则

目标：把 ZCLAW 做成真实可交付的 OpenClaw 桌面客户端，而不是“看起来能用”的演示 UI。

1. 项目目标

ZCLAW 是基于 OpenClaw 的 AI Agent 桌面端，核心价值不是单纯聊天，而是：

• 真实连接 Gateway
• 真实驱动 Agent / Plugins / Skills
• 真实读写配置与工作区
• 真实反映运行时状态

判断标准：

一个页面或按钮如果没有改变 OpenClaw Runtime 的真实行为 / 真实配置 / 真实路由 / 真实工作区上下文，那它大概率还只是演示态，不算交付完成。

---

2. 项目结构

ZClaw/
├── desktop/              # Tauri 桌面应用
│   ├── src/
│   │   ├── components/   # React UI
│   │   ├── store/        # Zustand stores
│   │   └── lib/          # Gateway client / helpers
│   └── src-tauri/        # Tauri Rust backend
├── src/gateway/          # Node Gateway 侧逻辑
├── plugins/              # OpenClaw 插件
├── skills/               # 自定义技能
├── config/               # 默认配置与 bootstrap 文件
├── docs/                 # 架构、排障、知识库
└── tests/                # Vitest 回归测试

核心数据流：

React UI → Zustand Store → GatewayClient → OpenClaw Gateway → Plugins / Skills / Runtime

---

3. 工作风格

3.1 交付导向

• 先做最高杠杆问题
• 优先恢复真实能力，再考虑局部美化
• 不保留“假数据看起来正常”的占位实现

3.2 根因优先

• 先确认问题属于：
  • 协议错配
  • 状态管理错误
  • UI 没接真实能力
  • 配置解析 / 持久化错误
  • 运行时 / 环境问题
• 不在根因未明时盲目堆补丁

3.3 闭环工作法

每次改动尽量形成完整闭环：

1. 定位问题
2. 建立最小可信心智模型
3. 实现最小有效修复
4. 跑自动化验证
5. 记录知识沉淀

---

4. 解决问题的标准流程

4.1 先看真实协议和真实运行时

当桌面端与 Gateway 行为不一致时：

• 先检查当前 runtime schema / RPC 能力
• 不要只相信旧前端封装或历史调用方式
• 如果源码与实际运行行为冲突，以当前 runtime为准

尤其是以下能力必须以真实 Gateway 为准：

• agent
• models.list
• config.get
• config.apply
• channels.*
• heartbeat.tasks
• ZCLAW 自定义 RPC

4.2 先打通读，再打通写

任何配置类页面都按这个顺序推进：

1. 先确认页面能读取真实配置
2. 再确认页面能显示真实当前值
3. 最后再接保存

禁止直接做“本地 state 假切换”冒充已完成。

4.3 区分“前端概念”和“运行时概念”

如果前端有自己的本地实体，例如：

• clone
• conversation
• temporary model selection

必须明确它是否真的对应 runtime 中的：

• agentId
• sessionKey
• default model

不要把本地 UI 标识直接当成 Gateway runtime 标识发送。

4.4 调试优先顺序

遇到问题时，优先按这个顺序排查：

1. 是否连到了正确的 Gateway
2. 是否握手成功
3. 请求方法名是否正确
4. 请求参数是否符合当前 schema
5. 返回结构是否与前端解析一致
6. 页面是否只是改了本地 state，没有写回 runtime
7. 是否存在旧 fallback / placeholder 掩盖真实错误

---

5. 实现规则

5.1 Gateway 通信

所有与 OpenClaw 的通信必须通过：

• desktop/src/lib/gateway-client.ts

禁止在组件内直接创建 WebSocket 或拼装协议帧。

5.2 状态管理

• UI 负责展示和交互
• Store 负责状态组织、流程编排
• GatewayClient 负责 RPC / 事件流通信
• 配置读写和协议适配逻辑放在 lib/ 助手层

避免把协议细节散落在多个组件里。

5.3 React 组件

• 使用函数组件与 hooks
• 复杂副作用收敛到 store 或 helper
• 组件尽量保持“展示层”职责
• 一个组件里如果同时出现协议拼装、复杂状态机、配置改写逻辑，优先拆分

5.4 TypeScript

• 避免 any
• 优先 unknown + 类型守卫
• 外部返回结构必须做容错解析
• 不要假设 Gateway 响应永远只有一种 shape

5.5 配置处理

对 config.get 返回的 raw：

• 不要假设它一定是严格 JSON
• 先兼容 BOM / 注释 / 宽松对象语法
• 写回时以可被 runtime 接受为优先，必要时输出为标准 JSON

---

6. UI 完成度规则

6.1 允许存在的 UI

• 已接真实能力的 UI
• 明确标注“未实现 / 只读 / 待接入”的 UI

6.2 不允许存在的 UI

• 看似可编辑但不会生效的设置项
• 展示假状态却不对应真实运行时的面板
• 用 mock 数据掩盖未完成能力但不做说明

6.3 AutoClaw 参考策略

参考 HTML 原型时：

• 先提炼高价值结构和缺失能力
• 不机械复刻
• 只实现能带来真实系统收益的部分

---

7. 测试与验证规则

7.1 改动后必须验证

修改以下内容后，必须至少运行相关测试：

• chat / stream
• gateway store
• settings / config
• protocol helpers

优先命令：

pnpm vitest run tests/desktop/chatStore.test.ts tests/desktop/gatewayStore.test.ts tests/desktop/general-settings.test.tsx
pnpm tsc --noEmit

如果新增了独立 helper，应补最小回归测试。

7.2 测试设计原则

• 测根因，不只测表象
• 测协议参数是否正确
• 测状态是否在失败时保持一致
• 测真实边界条件：
  • placeholder agent
  • clone id
  • sessionKey 生命周期
  • 配置 raw 的宽松语法

7.3 人工验证

自动化通过后，关键链路仍应做手工 smoke：

• 能否连接 Gateway
• 能否发送消息并正常流式返回
• 模型切换是否真实生效
• 保存配置后是否真正影响新会话/运行时

---

8. 文档沉淀规则

凡是出现以下情况，应更新 docs/openclaw-knowledge-base.md 或相关文档：

• 新的协议坑
• 新的握手/配置/模型排障结论
• 真实 runtime 与旧实现不一致
• 某个问题的最短排障路径已经明确

原则：修完就记，避免二次踩坑。

---

9. 常见高风险点

• 把前端本地 id 当作 runtime agentId
• 只改 Zustand，不改 Gateway 配置
• 把旧协议字段继续发给新 runtime
• fallback 逻辑覆盖真实错误
• 直接 JSON.parse(config.raw)，忽略宽松配置语法
• 让 UI 显示“已完成”，实际只是 placeholder

---

10. 常用命令

pnpm install
pnpm dev
pnpm build
pnpm setup
pnpm vitest run tests/desktop/chatStore.test.ts tests/desktop/gatewayStore.test.ts tests/desktop/general-settings.test.tsx
pnpm tsc --noEmit

---

11. 参考文档

• docs/architecture-v2.md
• docs/DEVELOPMENT.md
• docs/openclaw-knowledge-base.md
• plugins/zclaw-ui/index.ts
• plugins/zclaw-chinese-models/index.ts

---

12. 提交信息建议

<type>(<scope>): <summary>

示例：

fix(chat): align agent request with current gateway schema
fix(models): persist gateway default model through config.apply
docs(knowledge-base): capture desktop gateway protocol mismatch case

推荐类型：

• feat
• fix
• refactor
• test
• docs
• chore
• perf