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