iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3927c92fa82d7b5a158a11e9c3c3264918a1200f
zclaw_openfang/wiki/development.md
iven b3f97d6525
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): 全量代码验证驱动更新 — 10页基于实际扫描非文档推测 
关键数字修正:
- Rust 74.5K行(原66K), Tauri命令 183(原182), SaaS路由 121
- 前端组件 104, lib/ 85文件, Store 17+4子store
- TODO/FIXME 仅 8 个(前端4+Rust4)

内容增强:
- 中间件完整14层注册清单含注册条件和优先级分类
- Store完整目录结构, Pipeline完整目录树
- Hands测试分布, Memory 16个Tauri命令列表
- 管家模式: 关键词路由→语义路由(TF-IDF)修正
- 代码健康度指标新增
2026-04-11 01:05:15 +08:00

3.3 KiB
Raw Blame History

title, updated, status, tags
title updated status tags
开发规范 2026-04-11 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 端点 已有 121 个 .route()，前端未全部接通
新增 SKILL.md 已有 75 个
新增 Tauri 命令 已有 183 个，部分无前端调用
新增中间件 已有 14 层
新增 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 追加记录