docs: update CLAUDE.md with stabilization rules, security audit, and production checklist
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
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
This commit is contained in:
88
CLAUDE.md
88
CLAUDE.md
@@ -2,43 +2,65 @@
|
|||||||
|
|
||||||
> **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**,专注于提供真实可用的 AI 能力,而不是演示 UI。
|
> **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**,专注于提供真实可用的 AI 能力,而不是演示 UI。
|
||||||
|
|
||||||
|
> **当前阶段: 稳定化。** 参见 [docs/STABILIZATION_DIRECTIVE.md](docs/STABILIZATION_DIRECTIVE.md)
|
||||||
|
> 在 P0 缺陷修复完成前,不接受任何新功能。所有 AI 会话必须先确认稳定化状态。
|
||||||
|
|
||||||
## 1. 项目定位
|
## 1. 项目定位
|
||||||
|
|
||||||
### 1.1 ZCLAW 是什么
|
### 1.1 ZCLAW 是什么
|
||||||
|
|
||||||
ZCLAW 是面向中文用户的 AI Agent 桌面端,核心能力包括:
|
ZCLAW 是面向中文用户的 AI Agent 桌面端,核心能力包括:
|
||||||
|
|
||||||
- **智能对话** - 多模型支持、流式响应、上下文管理
|
- **智能对话** - 多模型支持(8 Provider)、流式响应、上下文管理
|
||||||
- **自主能力** - 11 个 Hands(9 启用 + 2 禁用: Predictor, Lead)
|
- **自主能力** - 9 个启用的 Hands(另有 Predictor/Lead 已禁用)
|
||||||
- **技能系统** - 可扩展的 SKILL.md 技能定义
|
- **技能系统** - 75 个 SKILL.md 技能定义
|
||||||
- **工作流编排** - 多步骤自动化任务
|
- **工作流编排** - Pipeline DSL + 10 行业模板
|
||||||
- **安全审计** - 完整的操作日志和权限控制
|
- **安全审计** - 完整的操作日志和权限控制
|
||||||
|
|
||||||
### 1.2 决策原则
|
### 1.2 决策原则
|
||||||
|
|
||||||
**任何改动都要问:这对 ZCLAW 有用吗?对 ZCLAW 有影响吗?**
|
**任何改动都要问:这对 ZCLAW 用户今天能产生价值吗?**
|
||||||
|
|
||||||
- ✅ 对 ZCLAW 用户有价值的功能 → 优先实现
|
- ✅ 修复已知的 P0/P1 缺陷 → 最高优先
|
||||||
- ✅ 提升 ZCLAW 稳定性和可用性 → 必须做
|
- ✅ 接通"写了没接"的断链 → 高优先
|
||||||
- ❌ 只为兼容其他系统的妥协 → 谨慎评估
|
- ✅ 清理死代码和孤立文件 → 应该做
|
||||||
- ❌ 增加复杂度但无实际价值 → 不做
|
- ❌ 新增功能/页面/端点 → 稳定化完成前禁止
|
||||||
- ✅解决问题要寻找根因,从源头解决问题。不要为了消除问题而选择折中办法,从而导致系统架构、代码安全性、代码质量出现问题
|
- ❌ 增加复杂度但无实际价值 → 永远不做
|
||||||
|
- ❌ 折中方案掩盖根因 → 永远不做
|
||||||
|
|
||||||
|
### 1.3 稳定化铁律
|
||||||
|
|
||||||
|
**在 [STABILIZATION_DIRECTIVE.md](docs/STABILIZATION_DIRECTIVE.md) 完成标准达标前,以下行为被禁止:**
|
||||||
|
|
||||||
|
| 禁止行为 | 原因 |
|
||||||
|
|----------|------|
|
||||||
|
| 新增 SaaS API 端点 | 已有 93 个(含 2 个 dev-only),前端未全部接通 |
|
||||||
|
| 新增 SKILL.md 文件 | 已有 75 个,大部分未执行验证 |
|
||||||
|
| 新增 Tauri 命令 | 已有 171 个,24 个无前端调用 |
|
||||||
|
| 新增中间件/Store | 已有 11 层中间件 + 18 个 Store |
|
||||||
|
| 新增 admin 页面 | 已有 13 页 |
|
||||||
|
|
||||||
|
### 1.4 系统真实状态
|
||||||
|
|
||||||
|
参见 [docs/TRUTH.md](docs/TRUTH.md) — 这是唯一的真相源,所有其他文档中的数字如果与此冲突,以 TRUTH.md 为准。
|
||||||
***
|
***
|
||||||
|
|
||||||
## 2. 项目结构
|
## 2. 项目结构
|
||||||
|
|
||||||
```text
|
```text
|
||||||
ZCLAW/
|
ZCLAW/
|
||||||
├── crates/ # Rust Workspace (核心能力)
|
├── crates/ # Rust Workspace (10 crates)
|
||||||
│ ├── zclaw-types/ # L1: 基础类型 (AgentId, Message, Error)
|
│ ├── zclaw-types/ # L1: 基础类型 (AgentId, Message, Error)
|
||||||
│ ├── zclaw-memory/ # L2: 存储层 (SQLite, KV, 会话管理)
|
│ ├── zclaw-memory/ # L2: 存储层 (SQLite, KV, 会话管理)
|
||||||
│ ├── zclaw-runtime/ # L3: 运行时 (LLM驱动, 工具, Agent循环)
|
│ ├── zclaw-runtime/ # L3: 运行时 (4 Driver, 7 工具, 11 层中间件)
|
||||||
│ ├── zclaw-kernel/ # L4: 核心协调 (注册, 调度, 事件, 工作流)
|
│ ├── zclaw-kernel/ # L4: 核心协调 (171 Tauri 命令)
|
||||||
│ ├── zclaw-skills/ # 技能系统 (SKILL.md解析, 执行器)
|
│ ├── zclaw-skills/ # 技能系统 (76 SKILL.md 解析, 语义路由)
|
||||||
│ ├── zclaw-hands/ # 自主能力 (Hand/Trigger 注册管理)
|
│ ├── zclaw-hands/ # 自主能力 (9 启用, 155 Rust 测试)
|
||||||
│ ├── zclaw-protocols/ # 协议支持 (MCP, A2A)
|
│ ├── zclaw-protocols/ # 协议支持 (MCP 完整, A2A feature-gated)
|
||||||
│ └── zclaw-saas/ # SaaS 后端 (账号, 模型配置, 中转, 配置同步)
|
│ ├── zclaw-pipeline/ # Pipeline DSL (v1/v2, 10 行业模板)
|
||||||
├── admin/ # Next.js 管理后台
|
│ ├── zclaw-growth/ # 记忆增长 (FTS5 + TF-IDF)
|
||||||
|
│ └── zclaw-saas/ # SaaS 后端 (93 API, Axum + PostgreSQL)
|
||||||
|
├── admin-v2/ # 管理后台 (Vite + Ant Design Pro, 13 页)
|
||||||
├── desktop/ # Tauri 桌面应用
|
├── desktop/ # Tauri 桌面应用
|
||||||
│ ├── src/
|
│ ├── src/
|
||||||
│ │ ├── components/ # React UI 组件 (含 SaaS 集成)
|
│ │ ├── components/ # React UI 组件 (含 SaaS 集成)
|
||||||
@@ -64,14 +86,14 @@ ZCLAW/
|
|||||||
|
|
||||||
| 层级 | 技术 |
|
| 层级 | 技术 |
|
||||||
| ---- | --------------------- |
|
| ---- | --------------------- |
|
||||||
| 前端框架 | React 18 + TypeScript |
|
| 前端框架 | React 19 + TypeScript |
|
||||||
| 状态管理 | Zustand |
|
| 状态管理 | Zustand 5 |
|
||||||
| 桌面框架 | Tauri 2.x |
|
| 桌面框架 | Tauri 2.x |
|
||||||
| 样式方案 | Tailwind CSS |
|
| 样式方案 | Tailwind 4 |
|
||||||
| 配置格式 | TOML |
|
| 配置格式 | TOML |
|
||||||
| 后端核心 | Rust Workspace (10 crates) |
|
| 后端核心 | Rust Workspace (10 crates, ~66K 行) |
|
||||||
| SaaS 后端 | Axum + PostgreSQL (zclaw-saas) |
|
| SaaS 后端 | Axum + PostgreSQL (zclaw-saas) |
|
||||||
| 管理后台 | Next.js (admin/) |
|
| 管理后台 | Vite + Ant Design Pro (admin-v2/) |
|
||||||
|
|
||||||
### 2.3 Crate 依赖关系
|
### 2.3 Crate 依赖关系
|
||||||
|
|
||||||
@@ -130,18 +152,28 @@ desktop/src-tauri (→ kernel, skills, hands, protocols)
|
|||||||
|
|
||||||
**禁止**在组件内直接创建 WebSocket 或拼装 HTTP 请求。
|
**禁止**在组件内直接创建 WebSocket 或拼装 HTTP 请求。
|
||||||
|
|
||||||
### 4.2 発能层客户端
|
### 4.2 分层职责
|
||||||
|
|
||||||
````
|
```
|
||||||
UI 组件 → 只负责展示和交互
|
UI 组件 → 只负责展示和交互
|
||||||
Store → 负责状态组织和流程编排
|
Store → 负责状态组织和流程编排
|
||||||
Client → 负责网络通信和```
|
Client → 负责网络通信和协议转换
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 代码自检规则
|
||||||
|
|
||||||
|
**每次修改代码前必须检查:**
|
||||||
|
|
||||||
|
1. **是否已有相同能力的代码?** — 先搜索再写,避免重复
|
||||||
|
2. **前端是否有人调用?** — 没有 Rust 调用者的 Tauri 命令,先标注 `@reserved`
|
||||||
|
3. **错误是否静默吞掉?** — `let _ =` 必须替换为 `log::warn!` 或更高级别处理
|
||||||
|
4. **文档数字是否需要更新?** — 改了数量就要改文档```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 4.3 代码规范
|
### 4.4 代码规范
|
||||||
|
|
||||||
**TypeScript:**
|
**TypeScript:**
|
||||||
- 避免 `any`,优先 `unknown + 类型守卫`
|
- 避免 `any`,优先 `unknown + 类型守卫`
|
||||||
@@ -188,7 +220,7 @@ Client → 负责网络通信和```
|
|||||||
|
|
||||||
## 6. 自主能力系统 (Hands)
|
## 6. 自主能力系统 (Hands)
|
||||||
|
|
||||||
ZCLAW 提供 11 个自主能力包:
|
ZCLAW 提供 11 个自主能力包(9 启用 + 2 禁用):
|
||||||
|
|
||||||
| Hand | 功能 | 状态 |
|
| Hand | 功能 | 状态 |
|
||||||
|------|------|------|
|
|------|------|------|
|
||||||
|
|||||||
Reference in New Issue
Block a user