a8a0751005
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
- known-issues: 新增V2联调测试（17项通过 + 3项待处理 + SSE token修复） - development: 新增完整调试环境文档（Windows/PostgreSQL/端口/账号/启动顺序） - log: 追加V2联调记录
200 lines
5.9 KiB
Markdown
200 lines
5.9 KiB
Markdown
---
|
||
title: 开发规范
|
||
updated: 2026-04-15
|
||
status: active
|
||
tags: [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 客户端
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
# 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` |
|
||
|
||
### 数据库
|
||
|
||
```bash
|
||
# 连接信息
|
||
Host: localhost:5432
|
||
Database: zclaw
|
||
User: postgres
|
||
Password: 123123
|
||
|
||
# 完整 URL
|
||
postgresql://postgres:123123@localhost:5432/zclaw
|
||
```
|
||
|
||
### SaaS 后端启动
|
||
|
||
```bash
|
||
# 设置环境变量（必须）
|
||
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]] 追加记录
|