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

This commit is contained in:
iven
2026-04-03 00:29:21 +08:00
parent d8e2954d73
commit 5a5a4b322d

View File

@@ -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 个 Hands9 启用 + 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 | 功能 | 状态 |
|------|------|------| |------|------|------|