iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
c856673936b4589ab12e2140c09be81b4074f075
zclaw_openfang/CLAUDE.md
iven adfd7024df docs(claude): restructure documentation management and add feedback system 
- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections
  - Add docs/ structure with features/ and knowledge-base/ directories
  - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴)
  - Add feature update trigger matrix (新增/修改/完成/问题/反馈)
  - Add documentation quality checklist
- Add §16
2026-03-16 13:54:03 +08:00

12 KiB
Raw Blame History

ZCLAW 协作与实现规则

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

1. 项目目标

ZCLAW 是基于 OpenFang (Rust Agent OS) 的 AI Agent 桌面端，核心价值不是单纯聊天，而是：

  • 真实连接 OpenFang Kernel
  • 真实驱动 Agents / Skills / Hands / Workflows
  • 真实读写 TOML 配置与工作区
  • 真实反映运行时状态与审计日志

判断标准：

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

2. 项目结构

ZClaw/
├── desktop/              # Tauri 桌面应用
│   ├── src/
│   │   ├── components/   # React UI
│   │   ├── store/        # Zustand stores
│   │   └── lib/          # OpenFang client / helpers
│   └── src-tauri/        # Tauri Rust backend
├── skills/               # SKILL.md 技能定义
├── hands/                # HAND.toml 自主能力包
├── config/               # OpenFang TOML 配置
├── docs/                 # 架构、排障、知识库
└── tests/                # Vitest 回归测试

核心数据流：

React UI → Zustand Store → OpenFangClient → OpenFang Kernel → Skills / Hands / Channels

OpenFang vs OpenClaw 关键差异：

方面 OpenClaw OpenFang
语言 TypeScript/Node.js Rust
端口 18789 4200
配置 YAML/JSON TOML
插件 TypeScript SKILL.md + WASM
安全 3 层 16 层纵深防御

3. 工作风格

3.1 交付导向

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

3.2 根因优先

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

3.3 闭环工作法

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

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

4. 解决问题的标准流程

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

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

  • 先检查当前 REST API schema / WebSocket 事件格式
  • 不要只相信旧前端封装或历史调用方式
  • 如果源码与实际运行行为冲突，以当前 OpenFang Kernel为准

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

  • /api/chat (聊天)
  • /api/agents (Agent 管理)
  • /api/hands/* (Hands 触发)
  • /api/workflows/* (工作流)
  • /api/config (TOML 配置)
  • /api/audit/logs (审计日志)
  • WebSocket 事件 (stream, hand, workflow)

4.2 先打通读，再打通写

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

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

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

4.3 区分"前端概念"和"运行时概念"

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

  • agent / clone
  • conversation / session
  • temporary model selection

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

  • agent_id
  • session_id
  • default_model

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

4.4 调试优先顺序

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

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

5. 实现规则

5.1 Gateway 通信

IMPORTANT: 所有与 OpenFang 的通信必须通过：

  • desktop/src/lib/openfang-client.ts (OpenFang)
  • desktop/src/lib/gateway-client.ts (OpenClaw 兼容层)

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

5.2 后端切换

通过环境变量或 localStorage 切换后端：

// 环境变量
const USE_OPENFANG = import.meta.env.VITE_USE_OPENFANG === 'true';

// localStorage
const backendType = localStorage.getItem('zclaw-backend') || 'openclaw';

5.3 状态管理

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

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

5.4 React 组件

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

5.5 TypeScript

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

5.6 配置处理 (TOML)

OpenFang 使用 TOML 配置格式：

# ~/.openfang/config.toml

[server]
host = "127.0.0.1"
port = 4200

[agent]
default_model = "gpt-4"

[[llm.providers]]
name = "openai"
api_key = "${OPENAI_API_KEY}"

对配置的处理：

  • 使用 TOML 解析器，不要手动解析
  • 写回时保持 TOML 格式
  • 支持环境变量插值 ${VAR_NAME}

6. UI 完成度规则

6.1 允许存在的 UI

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

6.2 不允许存在的 UI

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

6.3 OpenFang 新特性 UI

以下 OpenFang 特有功能需要新增 UI：

  • Hands 面板: 触发和管理 7 个自主能力包
  • Workflow 编辑器: 多步骤工作流编排
  • Trigger 管理器: 事件触发器配置
  • 审计日志: Merkle 哈希链审计查看

7. 测试与验证规则

7.1 改动后必须验证

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

  • chat / stream
  • openfang client / 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 测试设计原则

  • 测根因，不只测表象
  • 测协议参数是否正确 (REST endpoint / WebSocket type)
  • 测状态是否在失败时保持一致
  • 测真实边界条件：
    • agent_id 生命周期
    • session_id 作用域
    • TOML 配置语法容错
    • Hand 触发与审批

7.3 人工验证

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

  • 能否连接 OpenFang (端口 4200)
  • 能否发送消息并正常流式返回
  • 模型切换是否真实生效
  • Hand 触发是否正常执行
  • 保存配置后是否真正影响新会话/运行时

8. 文档管理规则

8.1 文档结构

docs/
├── features/                    # 功能全景文档
│   ├── README.md               # 功能索引和优先级矩阵
│   ├── brainstorming-notes.md  # 头脑风暴记录
│   ├── 00-architecture/        # 架构层功能
│   ├── 01-core-features/       # 核心功能
│   ├── 02-intelligence-layer/  # 智能层 (L4 自演化)
│   ├── 03-context-database/    # 上下文数据库
│   ├── 04-skills-ecosystem/    # Skills 生态
│   ├── 05-hands-system/        # Hands 系统
│   └── 06-tauri-backend/       # Tauri 后端
├── knowledge-base/              # 技术知识库
│   ├── openfang-technical-reference.md
│   ├── openfang-websocket-protocol.md
│   └── troubleshooting.md
└── WORK_SUMMARY_*.md            # 工作日志

8.2 功能文档维护规范

何时更新功能文档：

触发条件 更新内容
新增功能 创建新文档，填写设计初衷
功能修改 更新技术设计、预期作用
功能完成 更新实际效果、测试覆盖
发现问题 更新已知问题、风险挑战
用户反馈 更新用户反馈、演化路线

功能文档模板：

# [功能名称]

> **分类**: [架构层/核心功能/智能层/上下文数据库/Skills/Hands/Tauri]
> **优先级**: [P0-决定性 / P1-重要 / P2-增强]
> **成熟度**: [L0-概念 / L1-原型 / L2-可用 / L3-成熟 / L4-生产]
> **最后更新**: YYYY-MM-DD

## 一、功能概述
## 二、设计初衷（问题背景、设计目标、竞品参考、设计约束）
## 三、技术设计（核心接口、数据流、状态管理）
## 四、预期作用（用户价值、系统价值、成功指标）
## 五、实际效果（已实现、测试覆盖、已知问题、用户反馈）
## 六、演化路线（短期/中期/长期）
## 七、头脑风暴笔记（待讨论问题、创意想法、风险挑战）

8.3 知识库更新规则

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

  • 新的协议坑 (REST/WebSocket)
  • 新的握手/配置/模型排障结论
  • 真实 runtime 与旧实现不一致
  • OpenFang 特有问题 (Hands, Workflows, 安全层)
  • 某个问题的最短排障路径已经明确

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

8.4 文档质量检查清单

每次更新文档后，检查：

  • 文件路径引用正确
  • 技术术语统一
  • ICE 评分已更新
  • 成熟度等级已更新
  • 已知问题列表已更新

9. 常见高风险点

  • 把前端本地 id 当作 OpenFang agent_id
  • 只改 Zustand，不改 OpenFang 配置
  • 把 OpenClaw 协议字段发给 OpenFang
  • fallback 逻辑覆盖真实错误
  • 直接手动解析 TOML，忽略格式容错
  • 让 UI 显示"已完成"，实际只是 placeholder
  • 混淆 OpenClaw 端口 (18789) 和 OpenFang 端口 (4200)

10. OpenFang 特有注意事项

10.1 Hands 系统

OpenFang 提供 7 个自主能力包：

Hand 功能 触发方式
Clip 视频处理、竖屏生成 手动/自动
Lead 销售线索发现 定时
Collector 数据收集聚合 定时/事件
Predictor 预测分析 手动
Researcher 深度研究 手动
Twitter Twitter 自动化 定时/事件
Browser 浏览器自动化 手动/工作流

触发 Hand 时必须：

  • 检查 RBAC 权限
  • 处理 needs_approval 状态
  • 记录审计日志

10.2 安全层

OpenFang 有 16 层安全防护，前端需要：

  • 正确处理认证失败 (Ed25519 + JWT)
  • 尊重 RBAC 能力门控
  • 显示审计日志入口
  • 处理速率限制错误

---

## 11. 常用命令

```bash
pnpm install
pnpm dev
pnpm tauri: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

12. 参考文档

  • docs/openfang-technical-reference.md - OpenFang 技术参考
  • docs/openclaw-to-openfang-migration-brainstorm.md - 迁移分析
  • docs/DEVELOPMENT.md - 开发指南
  • skills/ - SKILL.md 技能示例
  • hands/ - HAND.toml 配置示例

13. 提交信息建议

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

示例：

feat(openfang): add OpenFangClient with WebSocket support
feat(hands): add researcher hand trigger UI
fix(chat): align stream events with OpenFang protocol
fix(config): handle TOML format correctly
perf(gateway): optimize connection pooling
docs(knowledge-base): capture OpenFang RBAC permission issues

推荐类型：

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

14. 迁移检查清单

从 OpenClaw 迁移到 OpenFang 时，确保：

  • 端口从 18789 改为 4200
  • 配置格式从 YAML/JSON 改为 TOML
  • WebSocket URL 添加 /ws 路径
  • RPC 方法改为 REST API 或新 WebSocket 协议
  • 插件从 TypeScript 改为 SKILL.md
  • 添加 Hands/Workflow 相关 UI
  • 处理 16 层安全防护的交互

16. 参考文档更新

  • docs/features/README.md - 功能索引和优先级矩阵
  • docs/features/brainstorming-notes.md - 头脑风暴记录
  • docs/knowledge-base/openfang-technical-reference.md - OpenFang 技术参考
  • docs/knowledge-base/openfang-websocket-protocol.md - WebSocket 协议
  • docs/knowledge-base/troubleshooting.md - 排障指南
  • skills/ - SKILL.md 技能定义
  • hands/ - HAND.toml 自主能力包