e790cf171a
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
受 Karpathy LLM Wiki 启发，将分散在 docs/ + memory/ + CLAUDE.md 的项目知识 编译为 8 个结构化 wiki 页面，解决新会话冷启动时上下文浪费问题。 - wiki/index.md: 主索引入口 (~200行)，CLAUDE.md @import 自动加载 - wiki/architecture.md: 系统架构编译 (crate依赖/客户端路由/聊天流/LLM驱动) - wiki/module-status.md: 9个子系统状态 + Hands详情 + 测试覆盖 - wiki/data-flows.md: 6条核心数据流 (聊天/路由/记忆/认证/管家/Pipeline) - wiki/development.md: 开发规范 (闭环工作法/验证命令/提交规范) - wiki/known-issues.md: 缺陷状态 (P0/P1已修复，P2待处理) - wiki/file-map.md: 代码库文件地图 (crates/desktop/admin-v2/docs) - wiki/log.md: Append-only 变更日志 - CLAUDE.md: 添加 @wiki/index.md + §8.3 收尾流程增加 wiki 维护步骤
3.0 KiB
3.0 KiB
title, updated, status, tags
| title | updated | status | tags | ||
|---|---|---|---|---|---|
| 开发规范 | 2026-04-11 | active |
|
开发规范
从 index 导航到此处。完整规范见
CLAUDE.md
闭环工作法（强制）
每次改动必须按顺序完成，不允许跳过：
- 定位问题 — 理解根因，不盲目堆补丁
- 最小修复 — 只改必要的代码
- 自动验证 —
tsc --noEmit/cargo check/vitest run必须通过 - 提交推送 — 按 §11 规范提交，立即
git push - 文档同步 — 检查 TRUTH.md / wiki / CLAUDE.md 是否需要更新
稳定化约束（功能冻结）
| 禁止 | 原因 |
|---|---|
| 新增 SaaS API 端点 | 已有 140 个，前端未全部接通 |
| 新增 SKILL.md | 已有 75 个 |
| 新增 Tauri 命令 | 已有 182 个，70 个孤儿 |
| 新增中间件/Store | 已有 14 层中间件 + 18 个 Store |
| 新增 admin 页面 | 已有 15 页 |
分层职责
UI 组件 → 只负责展示和交互
Store → 负责状态组织和流程编排
Client → 负责网络通信和协议转换
禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过:
desktop/src/lib/gateway-client.ts— 主要通信客户端desktop/src/lib/tauri-gateway.ts— Tauri 原生命令
验证命令
# 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 _ =，改为log::warn!或更高级别 - 输入验证: 系统边界必须验证
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
- 架构变更 → 更新 architecture + data-flows
- 文件结构变化 → 更新 file-map
- 模块状态变化 → 更新 module-status
- 每次更新 → 在 log 追加记录
→ 架构见 architecture → 文件位置见 file-map