# ZCLAW 协作与实现规则

> **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**，专注于提供真实可用的 AI 能力，而不是演示 UI。

## 1. 项目定位

### 1.1 ZCLAW 是什么

ZCLAW 是面向中文用户的 AI Agent 桌面端，核心能力包括：

- **智能对话** - 多模型支持、流式响应、上下文管理
- **自主能力** - 8 个 Hands（浏览器、数据采集、研究、预测等）
- **技能系统** - 可扩展的 SKILL.md 技能定义
- **工作流编排** - 多步骤自动化任务
- **安全审计** - 完整的操作日志和权限控制

### 1.2 决策原则

**任何改动都要问：这对 ZCLAW 有用吗？对 ZCLAW 有影响吗？**

- ✅ 对 ZCLAW 用户有价值的功能 → 优先实现
- ✅ 提升 ZCLAW 稳定性和可用性 → 必须做
- ❌ 只为兼容其他系统的妥协 → 谨慎评估
- ❌ 增加复杂度但无实际价值 → 不做
- ✅解决问题要寻找根因，从源头解决问题。不要为了消除问题而选择折中办法，从而导致系统架构、代码安全性、代码质量出现问题
***

## 2. 项目结构

```text
ZCLAW/
├── crates/                   # Rust Workspace (核心能力)
│   ├── zclaw-types/          # L1: 基础类型 (AgentId, Message, Error)
│   ├── zclaw-memory/         # L2: 存储层 (SQLite, KV, 会话管理)
│   ├── zclaw-runtime/        # L3: 运行时 (LLM驱动, 工具, Agent循环)
│   ├── zclaw-kernel/         # L4: 核心协调 (注册, 调度, 事件, 工作流)
│   ├── zclaw-skills/         # 技能系统 (SKILL.md解析, 执行器)
│   ├── zclaw-hands/          # 自主能力 (Hand/Trigger 注册管理)
│   ├── zclaw-protocols/      # 协议支持 (MCP, A2A)
│   └── zclaw-saas/           # SaaS 后端 (账号, 模型配置, 中转, 配置同步)
├── admin/                    # Next.js 管理后台
├── desktop/                  # Tauri 桌面应用
│   ├── src/
│   │   ├── components/       # React UI 组件 (含 SaaS 集成)
│   │   ├── store/            # Zustand 状态管理 (含 saasStore)
│   │   └── lib/              # 客户端通信 / 工具函数 (含 saas-client)
│   └── src-tauri/            # Tauri Rust 后端 (集成 Kernel)
├── skills/                   # SKILL.md 技能定义
├── hands/                    # HAND.toml 自主能力配置
├── config/                   # TOML 配置文件
├── saas-config.toml          # SaaS 后端配置 (PostgreSQL 连接等)
├── docker-compose.yml        # PostgreSQL 容器配置
├── docs/                     # 架构文档和知识库
└── tests/                    # Vitest 回归测试
```

### 2.1 核心数据流

```text
用户操作 → React UI → Zustand Store → Tauri Commands → zclaw-kernel → LLM/Tools/Skills/Hands
```

### 2.2 技术栈

| 层级   | 技术                    |
| ---- | --------------------- |
| 前端框架 | React 18 + TypeScript |
| 状态管理 | Zustand               |
| 桌面框架 | Tauri 2.x             |
| 样式方案 | Tailwind CSS          |
| 配置格式 | TOML                  |
| 后端核心 | Rust Workspace (9 crates) |
| SaaS 后端 | Axum + PostgreSQL (zclaw-saas) |
| 管理后台 | Next.js (admin/) |

### 2.3 Crate 依赖关系

```text
zclaw-types          (无依赖)
    ↑
zclaw-memory         (→ types)
    ↑
zclaw-runtime        (→ types, memory)
    ↑
zclaw-kernel         (→ types, memory, runtime)
    ↑
zclaw-saas           (→ types, 独立运行于 8080 端口)
    ↑
desktop/src-tauri    (→ kernel, skills, hands, protocols)
```

***

## 3. 工作风格

### 3.1 交付导向

- **先做最高杠杆问题** - 解决用户最痛的点
- **真实能力优先** - 不做假数据占位
- **完整闭环** - 每个功能都要能真正使用

### 3.2 根因优先

遇到问题时，先确认属于哪一类：

1. **协议问题** - API 端点、请求格式、响应解析
2. **状态问题** - Store 更新、组件同步
3. **UI 问题** - 交互逻辑、样式显示
4. **配置问题** - TOML 解析、环境变量
5. **运行时问题** - 服务启动、端口占用

不在根因未明时盲目堆补丁。

### 3.3 闭环工作法

每次改动形成完整闭环：

1. 定位问题 → 2. 建立心智模型 → 3. 最小修复 → 4. 自动验证 → 5. 记录沉淀

***

## 4. 实现规则

### 4.1 通信层

所有与后端的通信必须通过统一的客户端层：

- `desktop/src/lib/gateway-client.ts` - 主要通信客户端
- `desktop/src/lib/tauri-gateway.ts` - Tauri 原生命令

**禁止**在组件内直接创建 WebSocket 或拼装 HTTP 请求。

### 4.2 発能层客户端

````
UI 组件 → 只负责展示和交互
Store   → 负责状态组织和流程编排
Client  → 负责网络通信和```

---



### 4.3 代码规范

**TypeScript:**
- 避免 `any`，优先 `unknown + 类型守卫`
- 外部数据必须做容错解析
- 不假设 API 响应永远只有一种格式

**React:**
- 使用函数组件 + hooks
- 复杂副作用收敛到 store
- 组件保持"展示层"职责

**配置处理:**
- 使用 TOML 解析器
- 支持环境变量插值 `${VAR_NAME}`
- 写回时保持格式一致

---

## 5. UI 完成度标准

### 5.1 允许存在的 UI

- 已接入真实后端能力的 UI
- 明确标注"开发中 / 只读"的 UI
- 有降级方案的 UI

### 5.2 不允许存在的 UI

- 看似可编辑但不会生效的设置
- 展示假状态的面板
- 用 mock 数据掩盖未完成能力

### 5.3 核心功能 UI

| 功能 | 状态 | 说明 |
|------|------|------|
| 聊天界面 | ✅ 完成 | 流式响应、多模型切换 |
| 分身管理 | ✅ 完成 | 创建、配置、切换 Agent |
| 自动化面板 | ✅ 完成 | Hands 触发、参数配置 |
| 技能市场 | 🚧 进行中 | 技能浏览和安装 |
| 工作流编辑 | 🚧 进行中 | Pipeline 工作流编辑器 |

---

## 6. 自主能力系统 (Hands)

ZCLAW 提供 11 个自主能力包：

| Hand | 功能 | 状态 |
|------|------|------|
| Browser | 浏览器自动化 | ✅ 可用 |
| Collector | 数据收集聚合 | ✅ 可用 |
| Researcher | 深度研究 | ✅ 可用 |
| Predictor | 预测分析 | ❌ 已禁用 (enabled=false)，无 Rust 实现 |
| Lead | 销售线索发现 | ❌ 已禁用 (enabled=false)，无 Rust 实现 |
| Clip | 视频处理 | ⚠️ 需 FFmpeg |
| Twitter | Twitter 自动化 | ✅ 可用（12 个 API v2 真实调用，写操作需 OAuth 1.0a） |
| Whiteboard | 白板演示 | ✅ 可用（导出功能开发中，标注 demo） |
| Slideshow | 幻灯片生成 | ✅ 可用 |
| Speech | 语音合成 | ✅ 可用（Browser TTS 前端集成完成） |
| Quiz | 测验生成 | ✅ 可用 |

**触发 Hand 时：**
1. 检查依赖是否满足
2. 收集必要参数
3. 处理 `needs_approval` 状态
4. 记录执行日志

---

## 7. 测试与验证

### 7.1 必测场景

修改以下内容后必须验证：

- 聊天 / 流式响应
- Store 状态更新
- 配置读写
- Hand 触发

### 7.2 验证命令

```bash
# TypeScript 类型检查
pnpm tsc --noEmit

# 单元测试
pnpm vitest run

# 启动开发环境
pnpm start:dev
````

### 7.3 人工验证清单

- [ ] 能否正常连接后端服务
- [ ] 能否发送消息并获得流式响应
- [ ] 模型切换是否生效
- [ ] Hand 触发是否正常执行
- [ ] 配置保存是否持久化

***

## 8. 文档管理

### 8.1 文档结构

```text
docs/
├── features/           # 功能文档
│   ├── README.md       # 功能索引
│   └── */              # 各功能详细文档
├── knowledge-base/     # 技术知识库
│   ├── troubleshooting.md
│   └── *.md
└── archive/            # 归档文档
```

### 8.2 文档更新原则

- **修完就记** - 解决问题后立即更新文档
- **面向未来** - 文档要帮助未来的开发者快速理解
- **中文优先** - 所有面向用户的文档使用中文

### 8.3 完成工作后的文档同步（强制）

每次完成功能实现、架构变更、问题修复后，**必须**同步更新以下文档：

1. **CLAUDE.md** — 如果涉及项目结构、技术栈、工作流程、命令的变化
2. **docs/features/** — 如果涉及新功能、功能变更、功能状态更新
3. **docs/knowledge-base/** — 如果涉及新知识、故障排查经验、配置说明
4. **saas-config.toml 注释** — 如果涉及 SaaS 配置项变更
5. **CHANGELOG** — 如果涉及对外可见的行为变化

**执行时机：** 代码编译通过且验证成功后，在标记任务完成之前，立即执行文档更新。文档更新是任务完成的必要条件，不是可选步骤。

***

## 9. 常见问题排查

### 9.1 连接问题

1. 检查后端服务是否启动（端口 50051）
2. 检查 Vite 代理配置
3. 检查防火墙设置

### 9.2 状态问题

1. 检查 Store 是否正确订阅
2. 检查组件是否在正确的 Store 获取数据
3. 检查是否有多个 Store 实例

### 9.3 配置问题

1. 检查 TOML 语法
2. 检查环境变量是否设置
3. 检查配置文件路径

***

## 10. 常用命令

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm start:dev

# 仅启动桌面端
pnpm desktop

# 构建生产版本
pnpm build

# 类型检查
pnpm tsc --noEmit

# 运行测试
pnpm vitest run

# 停止所有服务
pnpm start:stop
```

***

## 11. 提交规范

```
<type>(<scope>): <description>
```

**类型:**

- `feat` - 新功能
- `fix` - 修复问题
- `refactor` - 重构
- `docs` - 文档更新
- `test` - 测试相关
- `chore` - 杂项

**示例:**

```
feat(hands): 添加参数预设保存功能
fix(chat): 修复流式响应中断问题
refactor(store): 统一 Store 数据获取方式
```

***


## 12. 安全注意事项

- 不在代码中硬编码密钥
- 用户输入必须验证
- 敏感操作需要确认
- 保留操作审计日志
- 环境变量 `ZCLAW_SAAS_DEV` 模式放宽安全限制（开发环境设 `ZCLAW_SAAS_DEV=true`）

### 认证安全

- **JWT password_version**: 密码修改后自动使所有已签发的 JWT 失效（Claims 含 `pwv`，中间件比对 DB）
- **账户锁定**: 5 次登录失败后锁定 15 分钟
- **邮箱验证**: RFC 5322 正则 + 254 字符长度限制
- **JWT 密钥**: `#[cfg(debug_assertions)]` 保护 fallback，release 模式 `bail` 拒绝启动
- **TOTP 加密密钥**: 生产环境强制独立 `ZCLAW_TOTP_ENCRYPTION_KEY`（64 字符 hex），不从 JWT 密钥派生
- **TOTP/API Key 加密**: AES-256-GCM + 随机 Nonce
- **密码存储**: Argon2id + OsRng 随机盐
- **Refresh Token 轮换**: 单次使用，Logout 时撤销到 DB，rotation 校验已撤销的旧 token

### 网络安全

- **Cookie**: HttpOnly + Secure + SameSite=Strict + 路径作用域
- **Cookie Secure**: 开发环境 false，生产 true
- **CORS**: 生产强制白名单，缺失拒绝启动
- **TLS**: 反向代理（nginx/caddy）提供 HTTPS 终止，Axum 不负责 TLS
- **Docker**: SaaS 端口绑定 `127.0.0.1`，仅通过 nginx 反代访问
- **XFF**: 仅信任配置的代理 IP

### 限流

- `/api/auth/login` — 5次/分钟/IP（防暴力破解）+ 持久化到 PostgreSQL
- `/api/auth/register` — 3次/小时/IP（防刷注册）
- 公共端点默认 20次/分钟/IP（防滥用）

### 前端安全

- **Admin Token**: HttpOnly Cookie 传递，JS 不存储/读取 token
- **Tauri CSP**: 移除 `unsafe-inline` script，`connect-src` 限制为 `http://localhost:*` + `https://*`
- **Pipeline 日志**: Debug 日志截断 + 仅记录 keys 不记录 values

### 环境变量

| 变量 | 用途 |
|------|------|
| `DB_PASSWORD` | 数据库密码 |
| `ZCLAW_DATABASE_URL` | 完整数据库连接 URL（优先级最高） |
| `ZCLAW_SAAS_JWT_SECRET` | JWT 签名密钥 (>= 32 字符) |
| `ZCLAW_TOTP_ENCRYPTION_KEY` | TOTP/API Key 加密密钥 (64 hex) |
| `ZCLAW_ADMIN_USERNAME` | 初始管理员用户名 |
| `ZCLAW_ADMIN_PASSWORD` | 初始管理员密码 |
| `ZCLAW_SAAS_DEV` | 开发模式标志 (true=开发, false=生产) |

`saas-config.toml` 支持 `${ENV_VAR}` 模式环境变量插值。

### 生产环境清单

- [ ] nginx/caddy 配置反向代理 + HTTPS
- [ ] 确保设置 `ZCLAW_SAAS_DEV=false`（或不设置）
- [ ] 启用 CORS 白名单（`cors_origins` 配置实际域名）
- [ ] Cookie Secure=true + HttpOnly=true + SameSite=Strict
- [ ] JWT 签名密钥 >= 32 字符随机字符串
- [ ] `ZCLAW_TOTP_ENCRYPTION_KEY` 独立设置
- [ ] 数据库密码通过 `${DB_PASSWORD}` 引用

### 完整审计报告

参见 `docs/features/SECURITY_PENETRATION_TEST_V1.md`