iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3e5d64484e07a5d09f1966f4f1a9673f68648c06
zclaw_openfang/CLAUDE.md
iven eb956d0dce
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
feat: 新增管理后台前端项目及安全加固 
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: 完善配置解析单元测试
- 新增环境变量插值测试用例
2026-03-31 00:11:33 +08:00

14 KiB
Raw Blame History

ZCLAW 协作与实现规则

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

1. 项目定位

1.1 ZCLAW 是什么

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

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

1.2 决策原则

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

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

2. 项目结构

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 核心数据流

用户操作 → 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 依赖关系

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 文档结构

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. 常用命令

# 安装依赖
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. 安全注意事项

< + + 寜### 安全注意事项 | |--- 不在代码中硬编码密钥 | - 敄 操作需要确认 - 不在代码中硬编码密V Token/ API | | - 保留操作审计日志 - 用户输入必须验证 - 敄 就环境变量 ZCLAW_SAAS_DEV 模式放宽安全限制（开发环境设 ZCLAW_SAAS_DEV=true)， + - **生产环境 TLS 终止**: nginx/caddy 反代向提供 HTTPS** | | - CookieSecure标记在生产环境设为 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 |- 不在代码中硬编码密钥

  • 用户输入必须验证
  • 敏感操作需要确认
  • 保留操作审计日志