eb956d0dce
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
refactor(saas): 重构认证中间件与限流策略
- 登录限流调整为5次/分钟/IP
- 注册限流调整为3次/小时/IP
- GET请求不计入限流
fix(saas): 修复调度器时间戳处理
- 使用NOW()替代文本时间戳
- 兼容TEXT和TIMESTAMPTZ列类型
feat(saas): 实现环境变量插值
- 支持${ENV_VAR}语法解析
- 数据库密码支持环境变量注入
chore: 新增前端管理界面
- 基于React+Ant Design Pro
- 包含路由守卫/错误边界
- 对接58个API端点
docs: 更新安全加固文档
- 新增密钥管理规范
- 记录P0安全项审计结果
- 补充TLS终止说明
test: 完善配置解析单元测试
- 新增环境变量插值测试用例
439 lines
14 KiB
Markdown
439 lines
14 KiB
Markdown
# 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. 安全注意事项
|
||
|
||
</section>
|
||
|
||
< + + 寜### 安全注意事项
|
||
|`
|
||
|--- 不在代码中硬编码密钥`
|
||
| - 敄 操作需要确认
|
||
` - 不在代码中硬编码密V Token/ API |
|
||
| - 保留操作审计日志
|
||
` - 用户输入必须验证` ` - 敄 就环境变量 `ZCLAW_SAAS_DEV` 模式放宽安全限制（开发环境设 `ZCLAW_SAAS_DEV=true`)， + ` - **生产环境 TLS 终止**:
|
||
nginx/caddy 反代向提供 HTTPS**
|
||
|
|
||
| - Cookie `Secure` 标记在生产环境设为 true,开发环境设为 false（仅 臉 TOTP 加密密钥 `ZCLAW_TOTP_ENCRYPTION_KEY` 必须设置（64 字符 hex)
|
||
密钥) |
|
||
| - **Cookie SameSite=Strict** 鰲止 CSRF)` |
|
||
| - Refresh Token 轮换: 退出时，DB 撤销为关联， 旧 token` |
|
||
| + **Rotation 校验已使用 token 是否已撤销` |
|
||
| + **Logout 时撤销 refresh token` |
|
||
| - **TLS**: 生产环境必须使用反向代理 (nginx/caddy) 提供 HTTPS， |
|
||
| - Cookie Secure 标记: 开发环境 false, 生产 true` |
|
||
|
||
| + + | **配置说明** |
|
||
| - saas-config.toml 支持 `${ENV_VAR}` 稡式环境变量插值，如 `${DB_PASSWORD}` |
|
||
| - `ZCLAW_DATABASE_URL` 茉境变量覆盖 |
|
||
优先级最高) |
|
||
| - **Auth**: /api/auth/login` - 5次/分钟/IP (防暴力破解) |
|
||
| - `/api/auth/register` - 3次/小时/IP (防刷注册) |
|
||
| - 公共端点默认 20次/分钟/IP (防滥用) |
|
||
| - JWT 寰钥: `#[cfg(debug_assertions)]` 保护 fallback，release 枋 | ` bail` 拒绝启动` | - TOTP 加密密钥: AES-256-GCM 加密, 支持 SHA-256 崾生 JWT 密钥派生` |
|
||
- Logout 撤销: refresh token 到 DB 栘 UPDATE` |
|
||
| - Cookie: Secure 标志: 开发环境 false, 生产 true
|
||
|
|
||
| + + `SameSite=Strict` + 跨站 CSRF + SSL ( CORS) |
|
||
| + | TLS 终止:: nginx/caddy 反向代理提供 HTTPS`, 或 |
|
||
生产环境日志写入 WAF - | | **TLS 终止说明**: | 反向代理实现 HTTPS， | Axum 服务不负责 TLS 配置、 |
|
||
|
||
`saas-config.toml.example` 更新安全说明 |
|
||
| | 密钥管理 | 甤境变量引用 (`${DB_PASSWORD}` 等) |
|
||
数据库密码) | | TOML 解析支持 `${VAR}` 稡式环境变量插值， | | 通过 `ZCLAW_DATABASE_URL` 猯变量完整覆盖 (优先级最高) |
|
||
|
||
| - JWT fallback key | `#[cfg(debug_assertions)]` 保护 fallback，release 拒绝启动` | - TOTP/API Key 加密: `AES-256-GCM`, 支持 SHA-256 派生 JWT 密钥派生` | - Logout 时撤销 refresh token 到 DB (`used_at IS NULL` 切 `revoked`) + rotation 校验已撤销的旧 token` | - Cookie Secure: 开发环境 false, 生产 true | `SameSite=Strict` + 跨站 CSRF + SSR CORS 白名单 + `X-Request头 + 请求日志 | |
|
||
|
||
| - **TLS**: 生产环境必须使用反向代理 (nginx/caddy) 提供 HTTPS, | - **生产环境日志写入 WAF - | |
|
||
| - **配置说明**: `saas-config.toml` 支持 `${ENV_VAR}` 稡式环境变量插值, | 文件模板已示例已更新 |
|
||
| - `ZCLAW_SAAS_JWT_SECRET` | JWT 签名密钥 (至少 32 字符随机字符串) | | | TOTP 加密密钥 `ZCLAW_TOTP_ENCRYPTION_KEY` | TOTP 加密密钥 (hex 编码, 64 字符) | |
|
||
| | SAAS 配置环境变量 | `ZCLAW_SAAS_DEV` 开发环境 |
|
||
| `ZCLAW_SAAS_DEV=true` 放宽安全限制 (开发环境: | | 公共端点请求限流 |
|
||
| - 公共端点限流 & login/register) | refresh/logout | 默认 | `ZCLAW_SAAS_DEV` 不设置) |
|
||
| | **Cookie**: HttpOnly + Secure + SameSite=Strict + 路径="/api" + "/api/v1/auth" + `Secure` 仅在生产环境为 true |
|
||
|
||
| | **TLS**: 反向代理** 提供 HTTPS 终止** | 反向代理（如 nginx/caddy）配置上游 → [SSL 终止 (`proxy downgrade`) |
|
||
| **Cookie**: Secure 标记仅在开发环境 (`ZCLAW_SAAS_DEV=true`) 设为 false（不强制 HTTPS），生产环境设为 true |
|
||
|
||
| - **环境变量模板**: | | 瘾境命令 |
|
||
| - `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=生产) |
|
||
| - **生产环境清单单** |
|
||
| | nginx/caddy 配置反向代理 + HTTPS |
|
||
| | 确保设置 `ZCLAW_SAAS_DEV=false`（或不设置） |
|
||
| | 启用 CORS 白名单 | | | `cors_origins` 匇向实际域名 |
|
||
| | Cookie Secure=true + HttpOnly=true + SameSite=Strict |
|
||
| - JWT 寋名密钥 >= 32 字符随机字符串 |
|
||
| - 数据库密码通过 `${DB_PASSWORD}` 引用 | |
|
||
|
||
| **部署命令** (参考) |
|
||
| | 设置环境变量: `export DB_PASSWORD=your_password` |
|
||
| | `export ZCLAW_SAAS_JWT_SECRET=$(openssl rand -hex 32)` |
|
||
| | `cp saas-config.toml.example saas-config.toml` |
|
||
| | 编辑 saas-config.toml 填入实际数据库 URL |
|
||
| | `cargo build --release -p zclaw-saas` |
|
||
| | 启动服务: `./zclaw-saas` |- 不在代码中硬编码密钥
|
||
- 用户输入必须验证
|
||
- 敏感操作需要确认
|
||
- 保留操作审计日志
|
||
|