iven/erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化ERP平台底座项目结构

Browse Source 
- 添加基础crate结构(erp-core, erp-common)
- 实现核心模块trait和事件总线
- 配置Docker开发环境(PostgreSQL+Redis)
- 添加Tauri桌面端基础框架
- 设置CI/CD工作流
- 编写项目协作规范文档(CLAUDE.md)
This commit is contained in:
iven
2026-04-10 23:40:38 +08:00
commit eb856b1d73
32 changed files with 8049 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

583
CLAUDE-1.md Normal file
View File

@@ -0,0 +1,583 @@
# ZCLAW 协作与实现规则
> **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**，专注于提供真实可用的 AI 能力，而不是演示 UI。
> **当前阶段: 发布前管家模式实施。** 稳定化基线已达成，管家模式6交付物已完成。
## 1. 项目定位
### 1.1 ZCLAW 是什么
ZCLAW 是面向中文用户的 AI Agent 桌面端，核心能力包括：
- **智能对话** - 多模型支持（8 Provider）、流式响应、上下文管理
- **自主能力** - 9 个启用的 Hands（另有 Predictor/Lead 已禁用）
- **技能系统** - 75 个 SKILL.md 技能定义
- **工作流编排** - Pipeline DSL + 10 行业模板
- **安全审计** - 完整的操作日志和权限控制
### 1.2 决策原则
**任何改动都要问：这对 ZCLAW 用户今天能产生价值吗？**
- ✅ 修复已知的 P0/P1 缺陷 → 最高优先
- ✅ 接通"写了没接"的断链 → 高优先
- ✅ 清理死代码和孤立文件 → 应该做
- ❌ 新增功能/页面/端点 → 稳定化完成前禁止
- ❌ 增加复杂度但无实际价值 → 永远不做
- ❌ 折中方案掩盖根因 → 永远不做
### 1.3 稳定化铁律
**稳定化基线达成后仍需遵守以下约束：**
| 禁止行为 | 原因 |
|----------|------|
| 新增 SaaS API 端点 | 已有 140 个（含 2 个 dev-only），前端未全部接通 |
| 新增 SKILL.md 文件 | 已有 75 个，大部分未执行验证 |
| 新增 Tauri 命令 | 已有 189 个，70 个无前端调用且无 @reserved |
| 新增中间件/Store | 已有 13 层中间件 + 18 个 Store |
| 新增 admin 页面 | 已有 15 页 |
### 1.4 系统真实状态
参见 [docs/TRUTH.md](docs/TRUTH.md) — 这是唯一的真相源，所有其他文档中的数字如果与此冲突，以 TRUTH.md 为准。
***
## 2. 项目结构
```text
ZCLAW/
├── crates/ # Rust Workspace (10 crates)
│ ├── zclaw-types/ # L1: 基础类型 (AgentId, Message, Error)
│ ├── zclaw-memory/ # L2: 存储层 (SQLite, KV, 会话管理)
│ ├── zclaw-runtime/ # L3: 运行时 (4 Driver, 7 工具, 12 层中间件)
│ ├── zclaw-kernel/ # L4: 核心协调 (182 Tauri 命令)
│ ├── zclaw-skills/ # 技能系统 (75 SKILL.md 解析, 语义路由)
│ ├── zclaw-hands/ # 自主能力 (9 启用, 106 Rust 测试)
│ ├── zclaw-protocols/ # 协议支持 (MCP 完整, A2A feature-gated)
│ ├── zclaw-pipeline/ # Pipeline DSL (v1/v2, 10 行业模板)
│ ├── zclaw-growth/ # 记忆增长 (FTS5 + TF-IDF)
│ └── zclaw-saas/ # SaaS 后端 (130 API, Axum + PostgreSQL)
├── admin-v2/ # 管理后台 (Vite + Ant Design Pro, 13 页)
├── 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 19 + TypeScript |
| 状态管理 | Zustand 5 |
| 桌面框架 | Tauri 2.x |
| 样式方案 | Tailwind 4 |
| 配置格式 | TOML |
| 后端核心 | Rust Workspace (10 crates, ~66K 行) |
| SaaS 后端 | Axum + PostgreSQL (zclaw-saas) |
| 管理后台 | Vite + Ant Design Pro (admin-v2/) |
### 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. **自动验证** — `tsc --noEmit` / `cargo check` / `vitest run` 必须通过
4. **提交推送** — 按 §11 规范提交，**立即 `git push`**，不积压
5. **文档同步** — 按 §8.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 代码自检规则
**每次修改代码前必须检查：**
1. **是否已有相同能力的代码？** — 先搜索再写，避免重复
2. **前端是否有人调用？** — 没有 Rust 调用者的 Tauri 命令，先标注 `@reserved`
3. **错误是否静默吞掉？** — `let _ =` 必须替换为 `log::warn!` 或更高级别处理
4. **文档数字是否需要更新？** — 改了数量就要改文档```
---
### 4.4 代码规范
**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 个自主能力包（9 启用 + 2 禁用）：
| 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 前端调试优先使用 WebMCP
ZCLAW 注册了 WebMCP 结构化调试工具（`desktop/src/lib/webmcp-tools.ts`），AI 代理可直接查询应用状态而无需 DOM 截图。
**原则：能用 WebMCP 工具完成的调试，优先使用 WebMCP 而非 DevTools MCP（`take_snapshot`/`evaluate_script`），以减少约 67% 的 token 消耗。**
已注册的 WebMCP 工具：
| 工具名 | 用途 |
|--------|------|
| `get_zclaw_state` | 综合状态概览（连接、登录、流式、模型） |
| `check_connection` | 连接状态检查 |
| `send_message` | 发送聊天消息 |
| `cancel_stream` | 取消当前流式响应 |
| `get_streaming_state` | 流式响应详细状态 |
| `list_conversations` | 列出最近对话 |
| `get_current_conversation` | 获取当前对话完整消息 |
| `switch_conversation` | 切换到指定对话 |
| `get_token_usage` | Token 用量统计 |
| `get_offline_queue` | 离线消息队列 |
| `get_saas_account` | SaaS 账户和订阅信息 |
| `get_available_models` | 可用 LLM 模型列表 |
| `get_current_agent` | 当前 Agent 详情 |
| `list_agents` | 所有 Agent 列表 |
| `get_console_errors` | 应用日志中的错误 |
**使用前提**：Chrome 146+ 并启用 `chrome://flags/#enable-webmcp-testing`。仅在开发模式注册。
**何时仍需 DevTools MCP**：UI 布局/样式问题、点击交互、截图对比、网络请求检查。
### 7.3 验证命令
```bash
# TypeScript 类型检查
pnpm tsc --noEmit
# 前端单元测试
cd desktop && pnpm vitest run
# Rust 全量测试（排除 SaaS）
cargo test --workspace --exclude zclaw-saas
# SaaS 集成测试（需要 PostgreSQL）
export TEST_DATABASE_URL="postgresql://postgres:123123@localhost:5432/zclaw"
cargo test -p zclaw-saas -- --test-threads=1
# 启动开发环境
pnpm start:dev
````
### 7.4 人工验证清单
- [ ] 能否正常连接后端服务
- [ ] 能否发送消息并获得流式响应
- [ ] 模型切换是否生效
- [ ] Hand 触发是否正常执行
- [ ] 配置保存是否持久化
***
## 8. 文档管理
### 8.1 文档结构
```text
docs/
├── features/ # 功能文档
│ ├── README.md # 功能索引
│ └── */ # 各功能详细文档
├── knowledge-base/ # 技术知识库
│ ├── troubleshooting.md
│ └── *.md
└── archive/ # 归档文档
```
### 8.2 文档更新原则
- **修完就记** - 解决问题后立即更新文档
- **面向未来** - 文档要帮助未来的开发者快速理解
- **中文优先** - 所有面向用户的文档使用中文
### 8.3 完成工作后的收尾流程（强制，不可跳过）
每次完成功能实现、架构变更、问题修复后，**必须立即执行以下收尾**：
#### 步骤 A：文档同步（代码提交前）
检查以下文档是否需要更新，有变更则立即修改：
1. **CLAUDE.md** — 项目结构、技术栈、工作流程、命令变化时
2. **CLAUDE.md §13 架构快照** — 涉及子系统变更时，更新 `<!-- ARCH-SNAPSHOT-START/END -->` 标记区域（可执行 `/sync-arch` 技能自动分析）
3. **docs/ARCHITECTURE_BRIEF.md** — 架构决策或关键组件变更时
4. **docs/features/** — 功能状态变化时
5. **docs/knowledge-base/** — 新的排查经验或配置说明
6. **docs/TRUTH.md** — 数字（命令数、Store 数、crates 数等）变化时
#### 步骤 B：提交（按逻辑分组）
```
代码变更 → 一个或多个逻辑提交
文档变更 → 独立提交（如果和代码分开更清晰）
```
#### 步骤 C：推送（立即）
```
git push
```
**不允许积压。** 每次完成一个独立工作单元后立即推送。不要留到"最后一起推"。
**判断标准：** 如果工作目录有未提交文件，说明收尾流程没完成。
***
## 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`
***
<!-- ARCH-SNAPSHOT-START -->
<!-- 此区域由 auto-sync 自动更新，请勿手动编辑。更新时间: 2026-04-09 -->
## 13. 当前架构快照
### 活跃子系统
| 子系统 | 状态 | 最新变更 |
|--------|------|----------|
| 管家模式 (Butler) | ✅ 活跃 | 04-09 ButlerRouter + 双模式UI + 痛点持久化 + 冷启动 |
| Hermes 管线 | ✅ 活跃 | 04-09 4 Chunk: 自我改进+用户建模+NL Cron+轨迹压缩 (684 tests) |
| 聊天流 (ChatStream) | ✅ 稳定 | 04-02 ChatStore 拆分为 4 Store (stream/conversation/message/chat) |
| 记忆管道 (Memory) | ✅ 稳定 | 04-02 闭环修复: 对话→提取→FTS5+TF-IDF→检索→注入 |
| SaaS 认证 (Auth) | ✅ 稳定 | Token池 RPM/TPM 轮换 + JWT password_version 失效机制 |
| Pipeline DSL | ✅ 稳定 | 04-01 17 个 YAML 模板 + DAG 执行器 |
| Hands 系统 | ✅ 稳定 | 9 启用 (Browser/Collector/Researcher/Twitter/Whiteboard/Slideshow/Speech/Quiz/Clip) |
| 技能系统 (Skills) | ✅ 稳定 | 75 个 SKILL.md + 语义路由 |
| 中间件链 | ✅ 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) |
### 关键架构模式
- **Hermes 管线**: 4模块闭环 — ExperienceStore(FTS5经验存取) + UserProfiler(结构化用户画像) + NlScheduleParser(中文时间→cron) + TrajectoryRecorder+Compressor(轨迹记录压缩)。通过中间件链+intelligence hooks调用
- **管家模式**: 双模式UI (默认简洁/解锁专业) + ButlerRouter 4域关键词分类 (healthcare/data_report/policy/meeting) + 冷启动4阶段hook (idle→greeting→waiting→completed) + 痛点双写 (内存Vec+SQLite)
- **聊天流**: 3种实现 → GatewayClient(WebSocket) / KernelClient(Tauri Event) / SaaSRelay(SSE) + 5min超时守护。详见 [ARCHITECTURE_BRIEF.md](docs/ARCHITECTURE_BRIEF.md)
- **客户端路由**: `getClient()` 4分支决策树 → Admin路由 / SaaS Relay(可降级到本地) / Local Kernel / External Gateway
- **SaaS 认证**: JWT→OS keyring 存储 + HttpOnly cookie + Token池 RPM/TPM 限流轮换 + SaaS unreachable 自动降级
- **记忆闭环**: 对话→extraction_adapter→FTS5全文+TF-IDF权重→检索→注入系统提示
- **LLM 驱动**: 4 Rust Driver (Anthropic/OpenAI/Gemini/Local) + 国内兼容 (DeepSeek/Qwen/Moonshot 通过 base_url)
### 最近变更
1. [04-09] Hermes Intelligence Pipeline 4 Chunk: ExperienceStore+Extractor, UserProfileStore+Profiler, NlScheduleParser, TrajectoryRecorder+Compressor (684 tests, 0 failed)
2. [04-09] 管家模式6交付物完成: ButlerRouter + 冷启动 + 简洁模式UI + 桥测试 + 发布文档
3. [04-08] 侧边栏 AnimatePresence bug + TopBar 重复 Z 修复 + 发布评估报告
3. [04-07] @reserved 标注 5 个 butler Tauri 命令 + 痛点持久化 SQLite
4. [04-06] 4 个发布前 bug 修复 (身份覆盖/模型配置/agent同步/自动身份)
<!-- ARCH-SNAPSHOT-END -->
<!-- ANTI-PATTERN-START -->
<!-- 此区域由 auto-sync 自动更新，请勿手动编辑。更新时间: 2026-04-09 -->
## 14. AI 协作注意事项
### 反模式警告
- ❌ **不要**建议新增 SaaS API 端点 — 已有 140 个，稳定化约束禁止新增
- ❌ **不要**忽略管家模式 — 已上线且为默认模式，所有聊天经过 ButlerRouter
- ❌ **不要**假设 Tauri 直连 LLM — 实际通过 SaaS Token 池中转，SaaS unreachable 时降级到本地 Kernel
- ❌ **不要**建议从零实现已有能力 — 先查 Hand(9个)/Skill(75个)/Pipeline(17模板) 现有库
- ❌ **不要**在 CLAUDE.md 以外创建项目级配置或规则文件 — 单一入口原则
### 场景化指令
- 当遇到**聊天相关** → 记住有 3 种 ChatStream 实现，先用 `getClient()` 判断当前路由模式
- 当遇到**认证相关** → 记住 Tauri 模式用 OS keyring 存 JWT，SaaS 模式用 HttpOnly cookie
- 当遇到**新功能建议** → 先查 [TRUTH.md](docs/TRUTH.md) 确认可用能力清单，避免重复建设
- 当遇到**记忆/上下文相关** → 记住闭环已接通: FTS5+TF-IDF+embedding，不是空壳
- 当遇到**管家/Butler** → 管家模式是默认模式，ButlerRouter 在中间件链中做关键词分类+system prompt 增强
<!-- ANTI-PATTERN-END -->