iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
27b98cae6f5f05c3ca66b9f06f1fa0a69072e3c9
zclaw_openfang/wiki/development.md
iven 27b98cae6f
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
docs: wiki 全量更新 — 2026-04-14 代码验证驱动 
关键数字修正:
- Rust 77K行(274 .rs)、Tauri 189命令、SaaS 137 routes
- Admin V2 17页、SaaS 16模块(含industry)、@reserved 22
- SQL 20迁移/42表、TODO/FIXME 4个、dead_code 16

内容更新:
- known-issues: V13-GAP 全部标记已修复 + 三端联调测试结果
- middleware: 14层 runtime + 10层 SaaS HTTP 完整清单
- saas: industry模块、路由模块13个、数据表42个
- routing: Store含industryStore、21个Store文件
- butler: 行业配置接入ButlerPanel、4内置行业
- log: 三端联调+V13修复记录追加
2026-04-14 22:15:53 +08:00

3.3 KiB
Raw Blame History

title, updated, status, tags
title updated status tags
开发规范 2026-04-14 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

Wiki 维护（收尾步骤）

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

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