zclaw_openfang/CLAUDE.md

@wiki/index.md

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 — 这是唯一的真相源，所有其他文档中的数字如果与此冲突，以 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 工具, 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 核心数据流

用户操作 → 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 前端调试优先使用 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 验证命令

# 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 文档结构

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. wiki/ — 编译后知识库维护（按触发规则更新对应页面）：
   • 修复 bug → 更新 wiki/known-issues.md
   • 架构变更 → 更新 wiki/architecture.md + wiki/data-flows.md
   • 文件结构变化 → 更新 wiki/file-map.md
   • 模块状态变化 → 更新 wiki/module-status.md
   • 每次更新 → 在 wiki/log.md 追加一条记录
7. 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

---

13. 当前架构快照

活跃子系统

子系统	状态	最新变更
管家模式 (Butler)	✅ 活跃	04-12 行业配置4行业 + 跨会话连续性 + XML fencing
Hermes 管线	✅ 活跃	04-12 触发信号持久化 + 经验行业维度 + 注入格式优化
Intelligence Heartbeat	✅ 活跃	04-15 统一健康快照 (health_snapshot.rs) + HeartbeatManager 重构 + HealthPanel 前端
聊天流 (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 + 语义路由
中间件链	✅ 稳定	15 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650 — V13注册)

关键架构模式

• Hermes 管线: 4模块闭环 — ExperienceStore(FTS5经验存取) + UserProfiler(结构化用户画像) + NlScheduleParser(中文时间→cron) + TrajectoryRecorder+Compressor(轨迹记录压缩)。通过中间件链+intelligence hooks调用
• 管家模式: 双模式UI (默认简洁/解锁专业) + ButlerRouter 动态行业关键词(4内置+自定义) + XML fencing注入 + 跨会话连续性(痛点回访+经验检索) + 触发信号持久化(VikingStorage) + 冷启动4阶段hook
• 聊天流: 3种实现 → GatewayClient(WebSocket) / KernelClient(Tauri Event) / SaaSRelay(SSE) + 5min超时守护。详见 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-15] Heartbeat 统一健康系统: health_snapshot.rs 统一收集器(LLM连接/记忆/会话/系统资源) + heartbeat.rs HeartbeatManager 重构 + HealthPanel.tsx 前端面板 + Tauri 命令 182→183 + intelligence 模块 15→16 文件 + 删除 intelligence-client/ 9 废弃文件
2. [04-12] 行业配置+管家主动性 全栈 5 Phase: 行业数据模型+4内置配置+ButlerRouter动态关键词+触发信号+Tauri加载+Admin管理页面+跨会话连续性+XML fencing注入格式
3. [04-09] Hermes Intelligence Pipeline 4 Chunk: ExperienceStore+Extractor, UserProfileStore+Profiler, NlScheduleParser, TrajectoryRecorder+Compressor (684 tests, 0 failed)
4. [04-09] 管家模式6交付物完成: ButlerRouter + 冷启动 + 简洁模式UI + 桥测试 + 发布文档
5. [04-07] @reserved 标注 5 个 butler Tauri 命令 + 痛点持久化 SQLite
6. [04-06] 4 个发布前 bug 修复 (身份覆盖/模型配置/agent同步/自动身份)

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 确认可用能力清单，避免重复建设
• 当遇到记忆/上下文相关 → 记住闭环已接通: FTS5+TF-IDF+embedding，不是空壳
• 当遇到管家/Butler → 管家模式是默认模式，ButlerRouter 在中间件链中做关键词分类+system prompt 增强