---
title: 开发规范
updated: 2026-04-14
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`

## Wiki 维护（收尾步骤）

完成工作后，检查 wiki/ 是否需要更新：
- 修复 bug → 更新 [[known-issues]]
- 架构变更 → 更新对应模块页 + [[middleware]]/[[routing]]
- 文件结构变化 → 更新 [[routing]] Store 列表
- 模块状态变化 → 更新 [[index]] 关键数字
- 每次更新 → 在 [[log]] 追加记录