adfd7024df
- 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
486 lines
12 KiB
Markdown
486 lines
12 KiB
Markdown
# ZCLAW 协作与实现规则
|
||
|
||
> 目标：把 ZCLAW 做成**真实可交付**的 OpenFang 桌面客户端，而不是"看起来能用"的演示 UI。
|
||
|
||
## 1. 项目目标
|
||
|
||
ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面端，核心价值不是单纯聊天，而是：
|
||
|
||
- 真实连接 OpenFang Kernel
|
||
- 真实驱动 Agents / Skills / Hands / Workflows
|
||
- 真实读写 TOML 配置与工作区
|
||
- 真实反映运行时状态与审计日志
|
||
|
||
判断标准：
|
||
|
||
> 一个页面或按钮如果**没有改变 OpenFang Runtime 的真实行为 / 真实配置 / 真实路由 / 真实工作区上下文**，那它大概率还只是演示态，不算交付完成。
|
||
|
||
---
|
||
|
||
## 2. 项目结构
|
||
|
||
```text
|
||
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 回归测试
|
||
```
|
||
|
||
核心数据流：
|
||
|
||
```text
|
||
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 切换后端：
|
||
|
||
```typescript
|
||
// 环境变量
|
||
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** 配置格式：
|
||
|
||
```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
|
||
|
||
优先命令：
|
||
|
||
```bash
|
||
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 文档结构
|
||
|
||
```text
|
||
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 功能文档维护规范
|
||
|
||
**何时更新功能文档**：
|
||
|
||
| 触发条件 | 更新内容 |
|
||
|---------|---------|
|
||
| 新增功能 | 创建新文档，填写设计初衷 |
|
||
| 功能修改 | 更新技术设计、预期作用 |
|
||
| 功能完成 | 更新实际效果、测试覆盖 |
|
||
| 发现问题 | 更新已知问题、风险挑战 |
|
||
| 用户反馈 | 更新用户反馈、演化路线 |
|
||
|
||
**功能文档模板**：
|
||
|
||
```markdown
|
||
# [功能名称]
|
||
|
||
> **分类**: [架构层/核心功能/智能层/上下文数据库/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. 提交信息建议
|
||
|
||
```text
|
||
<type>(<scope>): <summary>
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
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 自主能力包
|