zclaw_openfang/wiki/development.md

title, updated, status, tags

title	updated	status	tags
开发规范	2026-04-15	active	development conventions

开发规范

从 index 导航到此处。完整规范见 CLAUDE.md

闭环工作法（强制）

每次改动必须按顺序完成，不允许跳过：

1. 定位问题 — 理解根因，不盲目堆补丁
2. 最小修复 — 只改必要的代码
3. 自动验证 — tsc --noEmit / cargo check / vitest run 必须通过
4. 提交推送 — 按 §11 规范提交，立即 git push
5. 文档同步 — 检查 TRUTH.md / wiki / CLAUDE.md 是否需要更新

稳定化约束（功能冻结）

禁止	原因
新增 SaaS API 端点	已有 137 个 .route()，前端未全部接通
新增 SKILL.md	已有 75 个
新增 Tauri 命令	已有 189 个，部分无前端调用
新增中间件	已有 14 层 runtime + 10 层 SaaS HTTP
新增 Store	已有 17 文件 + chat/4 子store
新增 admin 页面	已有 15 页

分层职责

UI 组件 → 只负责展示和交互 (104 个 .tsx/.ts)
Store   → 负责状态组织和流程编排 (17 文件 + 4 子store)
Client  → 负责网络通信和协议转换 (85 个 lib/ 文件)

禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过:

• desktop/src/lib/gateway-client.ts — 主要通信客户端
• desktop/src/lib/tauri-gateway.ts — Tauri 原生命令
• desktop/src/lib/kernel-client.ts — Kernel 客户端
• desktop/src/lib/saas-client.ts — SaaS API 客户端

验证命令

# 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

提交规范

<type>(<scope>): <description>

类型: feat / fix / refactor / docs / test / chore / perf / ci

示例:

• fix(chat): 修复流式响应中断问题
• refactor(store): 统一 Store 数据获取方式

代码规范

TypeScript:

• 避免 any，优先 unknown + 类型守卫
• 外部数据必须做容错解析
• 不假设 API 响应永远只有一种格式

React:

• 函数组件 + hooks
• 复杂副作用收敛到 store
• 组件保持"展示层"职责

Rust:

• 错误处理: 禁止 let _ =，改为 tracing::warn! 或更高级别
• 输入验证: 系统边界必须验证
• 中间件: 实现 AgentMiddleware trait，4 个 hook 点

WebMCP 调试工具

优先使用 WebMCP 而非 DevTools MCP（节省 ~67% token）:

工具	用途
get_zclaw_state	综合状态概览
check_connection	连接状态
send_message	发送聊天消息
get_console_errors	应用错误日志

前提: Chrome 146+ + chrome://flags/#enable-webmcp-testing

调试环境（Windows）

新会话联调必读。ZCLAW 在 Windows 本地开发，不使用 Docker。

环境要求

依赖	说明	验证命令
PostgreSQL 18	Windows 服务，端口 5432	powershell -c "Get-Service postgresql-x64-18"
Node.js + pnpm	前端开发	pnpm --version
Rust nightly	后端编译	cargo --version
Tauri CLI	桌面端开发	pnpm tauri --version

数据库

# 连接信息
Host: localhost:5432
Database: zclaw
User: postgres
Password: 123123

# 完整 URL
postgresql://postgres:123123@localhost:5432/zclaw

SaaS 后端启动

# 设置环境变量（必须）
export ZCLAW_SAAS_DEV=true
export DB_PASSWORD=123123
export ZCLAW_SAAS_JWT_SECRET="zclaw-dev-jwt-secret-for-testing-only-32chars"
export ZCLAW_TOTP_ENCRYPTION_KEY="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
export ZCLAW_ADMIN_USERNAME="admin"
export ZCLAW_ADMIN_PASSWORD="admin123"

# 启动
cargo run -p zclaw-saas

# 验证（注意：health 端点是 /api/health，不是 /api/v1/health）
curl http://localhost:8080/api/health

默认账号

用途	用户名	密码	说明
管理员	admin	admin123	super_admin 角色
SaaS 管理员	admin	admin123	Tauri 桌面端 + Admin V2 共用
Admin V2	admin	admin123	http://localhost:5173

端口分配

服务	端口	URL
SaaS 后端	8080	http://localhost:8080
Admin V2	5173	http://localhost:5173
桌面端 Vite	1420	http://localhost:1420（Tauri 内嵌）

启动顺序

1. 确保 PostgreSQL 运行（Windows 服务自动启动）
2. 启动 SaaS 后端：cargo run -p zclaw-saas（需设置环境变量）
3. 启动桌面端：pnpm desktop 或 pnpm start:dev
4. Admin V2：桌面端启动后自动可用，或单独 cd admin-v2 && pnpm dev

调试工具

工具	用途	说明
Tauri MCP	桌面端内部状态	mcp__tauri-mcp__* 系列工具
Chrome DevTools MCP	Admin V2 页面调试	mcp__chrome-devtools__* 系列工具
WebMCP	桌面端结构化调试	需 Chrome 146+，优先使用
curl	SaaS API 快速验证	注意 admin token 通过 /api/v1/auth/login 获取

注意事项

• Health 端点: /api/health（非 /api/v1/health）
• SaaS 登录: POST /api/v1/auth/login，返回 token 字段
• 模型 API Key: Provider 需在 Admin V2 模型服务页配置并启用 Key，否则聊天 404
• 中转任务清理: Provider Key 禁用后，已创建的中转任务会卡在 "processing"

Wiki 维护（收尾步骤）

完成工作后，检查 wiki/ 是否需要更新：

• 修复 bug → 更新 known-issues
• 架构变更 → 更新对应模块页 + middleware/routing
• 文件结构变化 → 更新 routing Store 列表
• 模块状态变化 → 更新 index 关键数字
• 每次更新 → 在 log 追加记录