zclaw_openfang/CLAUDE.md

ZCLAW 协作与实现规则

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

当前阶段: 稳定化。 参见 docs/STABILIZATION_DIRECTIVE.md 在 P0 缺陷修复完成前，不接受任何新功能。所有 AI 会话必须先确认稳定化状态。

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 稳定化铁律

在 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 — 这是唯一的真相源，所有其他文档中的数字如果与此冲突，以 TRUTH.md 为准。

---

2. 项目结构

ZCLAW/
├── crates/                   # Rust Workspace (10 crates)
│   ├── zclaw-types/          # L1: 基础类型 (AgentId, Message, Error)
│   ├── zclaw-memory/         # L2: 存储层 (SQLite, KV, 会话管理)
│   ├── 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 集成)
│   │   ├── 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 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 依赖关系

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 验证命令

# 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 完成工作后的收尾流程（强制，不可跳过）

每次完成功能实现、架构变更、问题修复后，必须立即执行以下收尾：

步骤 A：文档同步（代码提交前）

检查以下文档是否需要更新，有变更则立即修改：

1. CLAUDE.md — 项目结构、技术栈、工作流程、命令变化时
2. docs/features/ — 功能状态变化时
3. docs/knowledge-base/ — 新的排查经验或配置说明
4. 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. 常用命令

# 安装依赖
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