docs: stabilization directive + TRUTH document + AI session prompts + dockerignore
- STABILIZATION_DIRECTIVE.md: feature freeze rules, banned actions, priorities - TRUTH.md: single source of truth for system state (crate counts, store counts) - AI_SESSION_PROMPTS.md: three-layer prompt system for AI sessions - Industry agent delivery design spec - Stabilization test suite for regression prevention - Delete stale ISSUE-TRACKER.md - Add .dockerignore for container builds - Add brainstorm session artifacts
This commit is contained in:
iven
159
docs/AI_SESSION_PROMPTS.md
Normal file
159
docs/AI_SESSION_PROMPTS.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# ZCLAW AI 会话提示词模板
|
||||
|
||||
> **用途**: 每次开新的 AI 会话时，根据工作类型选择对应提示词。
|
||||
> 这些提示词设计为让 AI 立刻理解项目状态和约束，避免重复探索。
|
||||
|
||||
---
|
||||
|
||||
## 模板 1: 修复缺陷（最常用）
|
||||
|
||||
```
|
||||
我在 ZCLAW 项目中修复缺陷。项目位于当前工作目录。
|
||||
|
||||
## 约束
|
||||
- 先读 docs/STABILIZATION_DIRECTIVE.md 了解当前优先级
|
||||
- 先读 docs/TRUTH.md 了解系统真实状态
|
||||
- 新增功能冻结，只做修复
|
||||
- 每个修复独立提交
|
||||
- 修复后必须更新 docs/TRUTH.md 中的缺陷状态
|
||||
|
||||
## 当前任务
|
||||
[在此描述要修复的缺陷]
|
||||
|
||||
## 修复流程
|
||||
1. 读相关文件，理解根因
|
||||
2. 最小修复（不重构不优化）
|
||||
3. 验证 cargo check + tsc --noEmit
|
||||
4. 更新 TRUTH.md
|
||||
5. 提交
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 2: 接通断链
|
||||
|
||||
```
|
||||
我在 ZCLAW 项目中接通"写了没接"的功能断链。
|
||||
|
||||
## 约束
|
||||
- 先读 docs/STABILIZATION_DIRECTIVE.md 第 2 节
|
||||
- 先读 docs/TRUTH.md 第 2.3 节，了解哪些功能未接通
|
||||
- 只做前端集成，不新增后端代码
|
||||
- 接通后必须有基本的前端测试
|
||||
- 不引入新的 UI 框架或依赖
|
||||
|
||||
## 当前任务
|
||||
[在此描述要接通的功能]
|
||||
|
||||
## 接通流程
|
||||
1. 读 Rust 端命令签名
|
||||
2. 读前端 lib/ 层是否已有对应调用函数
|
||||
3. 如果有函数但未调用 → 在组件/Store 中接入
|
||||
4. 如果没有函数 → 在 lib/ 层新增，然后在组件/Store 中接入
|
||||
5. 添加基本测试
|
||||
6. 更新 TRUTH.md 将功能从 2.3 移到 2.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 3: 清理死代码
|
||||
|
||||
```
|
||||
我在 ZCLAW 项目中清理死代码。
|
||||
|
||||
## 约束
|
||||
- 先读 docs/STABILIZATION_DIRECTIVE.md 第 3 节
|
||||
- 先读 docs/TRUTH.md 第 4 节，了解已知死代码清单
|
||||
- 删除前必须确认零引用（grep 全 workspace）
|
||||
- 不删除 feature-gated 代码（Director/A2A/WASM），只标注
|
||||
- 不删除有测试的代码
|
||||
|
||||
## 清理流程
|
||||
1. 确认目标文件/目录
|
||||
2. grep 确认零引用
|
||||
3. 删除
|
||||
4. cargo check + tsc --noEmit 验证无破坏
|
||||
5. 更新 TRUTH.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 4: 文档校准
|
||||
|
||||
```
|
||||
我在 ZCLAW 项目中校准文档。
|
||||
|
||||
## 约束
|
||||
- docs/TRUTH.md 是唯一真相源
|
||||
- 其他文档中的数字如果与 TRUTH.md 冲突，修改其他文档
|
||||
- 不新增文档，只修正已有文档
|
||||
- 审计报告类文档（V5~V9）移到 docs/archive/
|
||||
|
||||
## 当前任务
|
||||
[在此描述要校准的文档]
|
||||
|
||||
## 校准流程
|
||||
1. 对比 TRUTH.md 中的实际值
|
||||
2. 找出所有不一致
|
||||
3. 逐一修正
|
||||
4. 不改变文档结构，只改数值和状态
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 5: 新功能设计（稳定化完成后使用）
|
||||
|
||||
```
|
||||
我在 ZCLAW 项目中设计新功能。项目位于当前工作目录。
|
||||
|
||||
## 前提检查
|
||||
- 确认 docs/STABILIZATION_DIRECTIVE.md 的完成标准已全部达标
|
||||
- 如果未达标，先完成稳定化，不要设计新功能
|
||||
|
||||
## 约束
|
||||
- 先读 CLAUDE.md 了解项目定位和决策原则
|
||||
- 先读 docs/TRUTH.md 了解系统现状
|
||||
- 新功能必须对应一个真实用户场景
|
||||
- 必须先规划前端到后端的完整路径，再写代码
|
||||
- 不允许"先写后端再说"的模式
|
||||
|
||||
## 设计流程
|
||||
1. 描述用户场景（谁、在什么情况下、要完成什么）
|
||||
2. 设计前端到后端的完整调用链
|
||||
3. 确认不重复已有功能
|
||||
4. 确认不影响已有功能
|
||||
5. 先写测试，再写实现
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 6: 状态检查（开新会话时快速对齐）
|
||||
|
||||
```
|
||||
请帮我检查 ZCLAW 项目当前状态。
|
||||
|
||||
按以下顺序执行：
|
||||
1. 读 docs/STABILIZATION_DIRECTIVE.md — 了解稳定化进度
|
||||
2. 读 docs/TRUTH.md — 了解系统真实状态
|
||||
3. 检查 P0 缺陷是否已修复（SEC2-P0-01, SEC2-P0-02）
|
||||
4. cargo check --workspace — 验证编译
|
||||
5. pnpm tsc --noEmit — 验证前端类型
|
||||
|
||||
输出：
|
||||
- 稳定化完成百分比
|
||||
- 剩余 P0/P1 缺陷清单
|
||||
- 下一步建议（最多 3 个具体操作）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用建议
|
||||
|
||||
| 场景 | 用哪个模板 |
|
||||
|------|-----------|
|
||||
| 修 bug | 模板 1 |
|
||||
| 接通已有后端能力 | 模板 2 |
|
||||
| 删无用代码 | 模板 3 |
|
||||
| 文档修正 | 模板 4 |
|
||||
| 设计新功能 | 模板 5 |
|
||||
| 每日开工 | 模板 6 |
|
||||
186
docs/STABILIZATION_DIRECTIVE.md
Normal file
186
docs/STABILIZATION_DIRECTIVE.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# ZCLAW 稳定化指令 v1.0
|
||||
|
||||
> **生效日期**: 2026-04-02
|
||||
> **状态**: 强制执行
|
||||
> **目标**: 将系统从"功能堆叠模式"切换到"端到端可用模式"
|
||||
|
||||
---
|
||||
|
||||
## 0. 核心原则
|
||||
|
||||
**新增功能冻结。** 在以下 P0 问题全部修复之前，不接受任何新功能 PR。
|
||||
|
||||
```
|
||||
判断标准：这个改动是否让用户今天就能用上？
|
||||
- 是 → 可以做
|
||||
- 否 → 记录到 backlog，不做
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. P0 紧急修复（阻塞一切）
|
||||
|
||||
| ID | 问题 | 文件 | 修复方案 |
|
||||
|----|------|------|----------|
|
||||
| SEC2-P0-01 | skill_execute 反序列化崩溃 | `desktop/src/lib/kernel-skills.ts:110-114` + `desktop/src-tauri/src/kernel_commands/skill.rs:290-296` | 前端传入真实 agentId/sessionId，或 Rust 端改为 `Option<String>` |
|
||||
| SEC2-P0-02 | TaskTool::default() panic | `crates/zclaw-runtime/src/tool/builtin/task.rs:59` | 移除 `impl Default for TaskTool`，或提供合理默认值 |
|
||||
|
||||
**验收标准**: 用户能在 UI 中执行一个 Skill 且不崩溃。
|
||||
|
||||
---
|
||||
|
||||
## 2. P1 集成修复（接通断链）
|
||||
|
||||
按以下顺序修复，每个修复后立即验证端到端：
|
||||
|
||||
### 2.1 API 路径对齐
|
||||
| ID | 问题 | 修复 |
|
||||
|----|------|------|
|
||||
| SEC2-P1-02 | agent-templates 缺少 /api/v1 前缀 | `saas-client.ts:376,384` 添加前缀 |
|
||||
| V11-P1-01 | trigger_update 参数格式不匹配 | `kernel-triggers.ts:99` 展开嵌套对象 |
|
||||
|
||||
### 2.2 事件监听补全
|
||||
| ID | 问题 | 修复 |
|
||||
|----|------|------|
|
||||
| SEC2-P1-03 | hand-execution-complete 无前端监听 | ChatArea/RightPanel 添加 `listen()` |
|
||||
|
||||
### 2.3 静默错误消除
|
||||
将所有 `let _ =` 错误忽略改为至少 `log::warn!`，逐个评估是否需要用户可见反馈：
|
||||
- HandRun 持久化 (3 处) — **已修复**
|
||||
- FTS 索引更新 — **已修复**
|
||||
- Worker dispatch — **已修复**
|
||||
- Billing key usage — **已修复**（移除冗余 `let _ =`）
|
||||
- Relay SSE error send — **已修复**（改为 if-let + debug log）
|
||||
|
||||
### 2.4 FactStore 实现
|
||||
- 方案 A: `MemoryStore` 实现 `FactStore` trait
|
||||
- 方案 B: 移除 `FactStore` trait，直接用 `MemoryStore` 方法
|
||||
- **已选 B** — 移除死 trait，保留值类型（已修复 SEC2-P1-01）
|
||||
|
||||
---
|
||||
|
||||
## 3. 死代码清理
|
||||
|
||||
### 3.1 删除（确认无引用后）
|
||||
|
||||
| 文件 | 行数 | 状态 |
|
||||
|------|------|------|
|
||||
| `desktop/src/lib/audit-logger.ts` | 170 | **已删除** |
|
||||
| `desktop/src/lib/saas-admin.ts` | 234 | 已在之前清理中删除 |
|
||||
| `desktop/src/lib/gateway-reconnect.ts` | ~100 | **已删除** (零生产引用) |
|
||||
| `admin/` 目录 | ~整目录 | **已删除** (空目录壳) |
|
||||
| `admin-temp-dir/` 目录 | ~整目录 | **已删除** |
|
||||
| `crates/zclaw-channels/` | Cargo.toml only | 已在之前清理中删除 |
|
||||
| `docs/analysis/ISSUE-TRACKER.md` | - | **已删除** |
|
||||
| `.superpowers/plans/` | - | 已不存在 |
|
||||
|
||||
### 3.2 Feature-gate 清理
|
||||
|
||||
| 模块 | 行数 | 处理 |
|
||||
|------|------|------|
|
||||
| Director (multi-agent) | 912 | **已标注** — "gated behind multi-agent feature" |
|
||||
| A2A 协议 | ~400 | **已标注** — feature gate 注释完整 |
|
||||
| WASM runner | ~200 | **已标注** — "Active module — fully implemented" |
|
||||
| OFP capability variants | ~10 | **已修复** — 3 个方法改为穷举匹配，grants() 保留通配符+注释 |
|
||||
|
||||
### 3.3 未连接的 Tauri 命令
|
||||
|
||||
24 个 Tauri 命令无前端调用（经二次审计修正）。不删除 Rust 代码，但：
|
||||
- **已完成**: 171/171 个命令已标注 `// @connected` 或 `// @reserved: 暂无前端集成`
|
||||
- 二次审计修正 19 个误标命令（8+11），当前 147 @connected / 24 @reserved
|
||||
|
||||
---
|
||||
|
||||
## 4. 文档真相校准
|
||||
|
||||
### 4.1 数值修正
|
||||
|
||||
| 指标 | 当前文档值 | 实际值 | 状态 |
|
||||
|------|-----------|--------|------|
|
||||
| Skills | 66/75/77 | **75** | **已校准** (TRUTH.md) |
|
||||
| Hands | 11 | **9 启用 + 2 禁用** | **已校准** (CLAUDE.md) |
|
||||
| Tauri 命令 | 58+/130+ | **171** | **已校准** + 171 个已标注（147 @connected / 24 @reserved） |
|
||||
| SaaS 路由 | 72+ | **93**（含 2 dev-only mock） | **已校准** |
|
||||
| 前端测试 | 1 文件 | **21 文件** | **已校准** (TRUTH.md) |
|
||||
| Zustand Store | 15 | **18** | **已校准** (TRUTH.md) |
|
||||
| Admin V2 页面 | 11 | **13** | **已校准** (TRUTH.md) |
|
||||
|
||||
### 4.2 文档归档
|
||||
|
||||
以下审计报告已从 `docs/` 根目录移除（已归档或已删除）：
|
||||
- COMPREHENSIVE_AUDIT_V5~V9（5 个文件，已被 V10/V11 取代）**已完成**
|
||||
- AUDIT_TRACKER.md **已完成**
|
||||
- VERIFICATION_REPORT.md **已完成**
|
||||
- FEATURE_AUDIT_REPORT.md **已完成**
|
||||
- FRONTEND_INTEGRATION_AUDIT.md **已完成**
|
||||
- DEEP_AUDIT_REPORT.md **已完成**
|
||||
- JOINT_DEBUG_REPORT_V1.md **已完成**
|
||||
- QA_REVIEW_V1.md **已完成**
|
||||
|
||||
### 4.3 ISSUED-TRACKER 重置
|
||||
|
||||
创建新的 `docs/TRUTH.md`，只记录：
|
||||
- 实际可工作的端到端功能清单
|
||||
- 已知缺陷清单（来自 V11 审计）
|
||||
- 每次修复后更新此文件
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端测试底线
|
||||
|
||||
在 P0/P1 修复完成后，为以下关键路径添加最基本测试：
|
||||
|
||||
1. **Skill 执行** — 调用 → 不崩溃 → 返回结果
|
||||
2. **Hand 触发** — emit event → 前端收到通知
|
||||
3. **消息发送** — Store → invoke → 流式响应
|
||||
4. **配置同步** — SaaS pull → Store 更新
|
||||
|
||||
目标：从 1 个测试文件提升到至少覆盖 4 条核心路径。
|
||||
|
||||
---
|
||||
|
||||
## 6. 禁止事项
|
||||
|
||||
在稳定化完成前，以下行为被禁止：
|
||||
|
||||
| 行为 | 原因 |
|
||||
|------|------|
|
||||
| 新增 SaaS API 端点 | 已有 93 个，前端只调用了一部分 |
|
||||
| 新增 SKILL.md 文件 | 已有 75 个，大部分未被调用 |
|
||||
| 新增 Tauri 命令 | 已有 171 个，24 个无前端调用 |
|
||||
| 新增中间件 | 已有 11 层，足够 |
|
||||
| 扩展 Pipeline 模板 | 已有 10 个行业模板 |
|
||||
| 新增 Zustand Store | 已有 18 个 |
|
||||
| 新增 admin 页面 | 已有 11 个 |
|
||||
|
||||
**唯一例外**: 修复 P0/P1 问题需要的新代码。
|
||||
|
||||
---
|
||||
|
||||
## 7. 完成标准
|
||||
|
||||
稳定化阶段完成的定义：
|
||||
|
||||
- [x] P0 全部修复，用户可执行 Skill 不崩溃
|
||||
- [x] P1 集成修复完成，hand-execution-complete 有监听
|
||||
- [x] 死代码清理完成，至少删除 5 个孤立文件
|
||||
- [x] `docs/TRUTH.md` 创建并反映真实状态
|
||||
- [x] 文档数值与代码一致
|
||||
- [x] 前端测试覆盖 4 条核心路径
|
||||
- [x] `cargo check --workspace` 通过 + `pnpm tsc --noEmit` 通过
|
||||
|
||||
达到以上标准后，本指令自动降级为"建议"级别，恢复正常功能开发。
|
||||
|
||||
---
|
||||
|
||||
## 8. 执行节奏
|
||||
|
||||
每个修复独立提交，格式：
|
||||
|
||||
```
|
||||
fix(<scope>): <描述>
|
||||
|
||||
Stabilization: SEC2-P0-01
|
||||
```
|
||||
|
||||
不批量提交。每个修复可独立 revert。
|
||||
166
docs/TRUTH.md
Normal file
166
docs/TRUTH.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# ZCLAW 系统真相文档
|
||||
|
||||
> **更新日期**: 2026-04-02
|
||||
> **数据来源**: V11 全面审计 + 二次审计 + 代码全量扫描
|
||||
> **规则**: 此文档是唯一真相源。所有其他文档如果与此冲突，以此为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 量化指标（已验证）
|
||||
|
||||
| 指标 | 实际值 | 验证方式 |
|
||||
|------|--------|----------|
|
||||
| Rust Crates | 10 个 (编译通过) | `cargo check --workspace` |
|
||||
| Rust 代码行数 | ~66,000 | wc -l |
|
||||
| Rust 单元测试 | 584 个 | `cargo test --workspace` |
|
||||
| Tauri 命令 | 171 个 | grep `#[tauri::command]` + 注释排除 |
|
||||
| **Tauri 命令有前端调用** | **147 个** | @connected 标注（经二次审计修正） |
|
||||
| **Tauri 命令无前端调用** | **24 个** | @reserved 标注 |
|
||||
| SKILL.md 文件 | 75 个 | `ls skills/*.md \| wc -l` |
|
||||
| Hands 启用 | 9 个 | Browser/Collector/Researcher/Clip/Twitter/Whiteboard/Slideshow/Speech/Quiz |
|
||||
| Hands 禁用 | 2 个 | Predictor, Lead |
|
||||
| SaaS API 端点 | 93 个（含 2 个 dev-only mock） | 路由注册全量统计 |
|
||||
| LLM Provider | 8 个 | Kimi/Qwen/DeepSeek/Zhipu/OpenAI/Anthropic/Gemini/Local |
|
||||
| Zustand Store | 18 个 | ls desktop/src/store/ (含 chat/ 子目录) |
|
||||
| React 组件 | ~50 个 | ls desktop/src/components/ |
|
||||
| 前端 TypeScript 测试 | 21 个文件 | 8 单元 + 12 E2E spec + 1 源码内 |
|
||||
| Admin V2 页面 | 13 个 | admin-v2/src/pages/ 全量统计 |
|
||||
| Admin V2 测试 | 322 个 | vitest 统计 |
|
||||
| 中间件层 | 11 层 | 运行时注册 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 端到端可用功能
|
||||
|
||||
以下功能经过代码验证，从前端到后端完整连通：
|
||||
|
||||
### 2.1 确认可用
|
||||
|
||||
| 功能 | 路径 | 验证状态 |
|
||||
|------|------|----------|
|
||||
| 智能对话 | UI → chatStore → Tauri → Kernel → LLM Driver → 流式返回 | ✅ 代码完整 |
|
||||
| Agent 分身管理 | UI → agentStore → Tauri → Kernel | ✅ 代码完整 |
|
||||
| 模型切换 | UI → Settings → config.toml → Kernel | ✅ 代码完整 |
|
||||
| Hand 触发 | UI → handStore → Tauri → Kernel → Hand 执行 | ✅ 代码完整 |
|
||||
| Hand 审批 | UI → approvalStore → Tauri → Kernel | ✅ 代码完整 |
|
||||
| 记忆搜索 | UI → memoryStore → Tauri → Growth → FTS5 | ✅ 代码完整 |
|
||||
| 配置读写 | UI → Settings → config.toml | ✅ 代码完整 |
|
||||
| SaaS 登录/注册 | UI → saasStore → SaaS API → PostgreSQL | ✅ 代码完整 |
|
||||
| SaaS 配置同步 | UI → saasStore → SaaS API → Store 更新 | ✅ 代码完整 |
|
||||
| Admin V2 管理 | admin-v2 → SaaS API → PostgreSQL | ✅ 代码完整 |
|
||||
| 支付集成 | Admin → SaaS → Alipay/WeChat API | ✅ 代码完整 |
|
||||
|
||||
### 2.2 有已知缺陷
|
||||
|
||||
| 功能 | 问题 | 严重度 |
|
||||
|------|------|--------|
|
||||
| Skill 执行 | 前端传空 context → Rust 反序列化失败 | **P0** |
|
||||
| Hand 异步结果 | Rust emit 事件但前端无 listen() | P1 |
|
||||
| Agent 模板 | API 路径缺 /api/v1 前缀 → 404 | P1 |
|
||||
| Trigger 更新 | 参数格式不匹配 → 静默失败 | P1 |
|
||||
|
||||
### 2.3 已实现但未接通前端
|
||||
|
||||
| 功能 | Rust 状态 | 前端状态 |
|
||||
|------|-----------|----------|
|
||||
| Pipeline 执行 | DSL 引擎完整 | 无 invoke 调用 |
|
||||
| Viking 适配 | FTS5 + TF-IDF | 11 个命令无前端调用 |
|
||||
| Classroom | 27 个命令 | 7 个命令无前端调用 |
|
||||
| Browser Hand | 22 个命令 | 部分无前端调用 |
|
||||
| Multi-agent Director | 912 行 (feature-gated) | 未启用 |
|
||||
|
||||
### 2.4 前端孤立 invoke 调用（无 Rust 后端实现）
|
||||
|
||||
以下 5 个前端 `invoke()` 调用在 Rust 端无对应命令，运行时将返回 "command not found"：
|
||||
|
||||
| 命令 | 前端文件 | 说明 |
|
||||
|------|----------|------|
|
||||
| `viking_add_inline` | `viking-client.ts` | 无 Rust 实现，| `viking_server_start` | `viking-client.ts` | Viking 服务器生命周期管理未实现 |
|
||||
| `viking_server_status` | `viking-client.ts` | 同上 |
|
||||
| `viking_server_stop` | `viking-client.ts` | 同上 |
|
||||
| `viking_server_restart` | `viking-client.ts` | 同上 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 已知缺陷清单
|
||||
|
||||
### 3.1 P0 — 必然崩溃
|
||||
|
||||
| ID | 问题 | 状态 |
|
||||
|----|------|------|
|
||||
| SEC2-P0-01 | skill_execute 反序列化崩溃 | **已修复** — kernel-skills.ts 注入真实 agentId/sessionId，workingDir 改为 null |
|
||||
| SEC2-P0-02 | TaskTool::default() panic | **已修复** — 移除 impl Default |
|
||||
|
||||
### 3.2 P1 — 功能失效
|
||||
|
||||
| ID | 问题 | 状态 |
|
||||
|----|------|------|
|
||||
| SEC2-P1-01 | FactStore trait 零实现 | **已修复** — 移除死 trait，保留值类型 |
|
||||
| SEC2-P1-02 | agent-templates 路径错误 | **已修复** — saas-client.ts 已添加 /api/v1 |
|
||||
| SEC2-P1-03 | hand-execution-complete 无监听 | **已修复** — ChatArea 添加 Tauri 事件监听 + streamStore.cancelStream 补全 |
|
||||
| SEC2-P1-04 | InMemoryStorage RwLock unwrap 级联 | **已修复** — 7 处改为 .expect() |
|
||||
| SEC2-P1-05~07 | HandRun 持久化静默忽略 (3处) | **已修复** — tracing::warn! |
|
||||
| SEC2-P1-08 | FTS 索引更新静默失败 | **已修复** — tracing::warn! |
|
||||
| SEC2-P1-09 | Worker dispatch 静默失败 | **已修复** — tracing::warn! |
|
||||
|
||||
### 3.3 P1.5 — 代码质量补充修复
|
||||
|
||||
| ID | 问题 | 状态 |
|
||||
|----|------|------|
|
||||
| SEC2-P1.5-01 | Capability _ => false 通配符 | **已修复** — 3 个方法改为穷举匹配，grants() 保留通配符+注释说明 |
|
||||
| SEC2-P1.5-02 | billing let _ = ... ? 冗余模式 | **已修复** — 移除冗余 let _ = |
|
||||
| SEC2-P1.5-03 | relay SSE 错误路径 send 失败未记录 | **已修复** — 改为 if let Err + tracing::debug! |
|
||||
| SEC2-P1.5-04 | WASM runner 缺少状态注解 | **已修复** — 添加 active module 说明 |
|
||||
| SEC2-P1.5-05 | Tauri 命令无连接状态标注 | **已修复** — 171/171 个命令已标注，经二次审计修正 19 个误标（147 @connected / 24 @reserved） |
|
||||
| SEC2-P1.5-06 | extract_token_usage 静默丢弃解析错误 | **已修复** — 添加 tracing::debug! |
|
||||
| SEC2-P1.5-07 | relay current_key_id 防御性 unwrap | **已修复** — 改为 ok_or_else 返回内部错误 |
|
||||
|
||||
### 3.3 P2 — 代码质量
|
||||
|
||||
| ID | 问题 |
|
||||
|----|------|
|
||||
| SEC2-P2-01~10 | 10 项代码质量问题（详见二次审计） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 死代码清单
|
||||
|
||||
| 文件/目录 | 行数 | 状态 | 建议 |
|
||||
|-----------|------|------|------|
|
||||
| `desktop/src/lib/audit-logger.ts` | 170 | **已删除** | - |
|
||||
| `desktop/src/lib/saas-admin.ts` | 234 | 已在之前清理中删除 | - |
|
||||
| `desktop/src/lib/gateway-reconnect.ts` | ~100 | **已删除** (零生产引用) | - |
|
||||
| `admin/` | 整目录 | **已删除** (空目录壳) | - |
|
||||
| `admin-temp-dir/` | 整目录 | **已删除** | - |
|
||||
| `crates/zclaw-channels/` | Cargo.toml only | 已在之前清理中删除 | - |
|
||||
| `docs/analysis/ISSUE-TRACKER.md` | - | **已删除** | - |
|
||||
| Director multi-agent | 912 | feature-gated off + 已注解 | 保留 |
|
||||
| A2A 协议 | ~400 | feature-gated off + 已注解 | 保留 |
|
||||
| WASM runner | ~200 | **Active module** + 已注解 | 保留 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档漂移记录
|
||||
|
||||
以下文档中的数字已与实际不符，需要校准：
|
||||
|
||||
| 文档 | 过时内容 | 正确值 |
|
||||
|------|----------|--------|
|
||||
| CLAUDE.md (旧版) | "React 18" | React 19 |
|
||||
| CLAUDE.md (旧版) | "Tailwind CSS" | Tailwind 4 |
|
||||
| CLAUDE.md (旧版) | "Next.js (admin/)" | Vite + Ant Design Pro (admin-v2/) |
|
||||
| roadmap.md | Skills: 75 | 76 |
|
||||
| roadmap.md | Tauri 命令: 58+/130+ | 175 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 更新日志
|
||||
|
||||
| 日期 | 更新内容 |
|
||||
|------|----------|
|
||||
| 2026-04-02 | 初始创建，基于 V11 全面审计 + 二次审计数据 |
|
||||
| 2026-04-02 | P0 全部修复 (SEC2-P0-01/02)；P1 全部修复 (SEC2-P1-01~09) |
|
||||
| 2026-04-02 | P1.5 代码质量修复：capability 穷举匹配、SaaS 静默错误、WASM 注解、Tauri 命令标注 |
|
||||
| 2026-04-02 | 深度审计后修正：8 个 Tauri 标注误标、4 处 SaaS let _ = 清理、TRUTH.md 路由数 58→93 |
|
||||
| 2026-04-02 | 二次深度审计：(1) 再修正 11 个 Tauri 标注 (147 connected / 24 reserved = 171) (2) 修正文档数字 SKILL 75/Stores 18/Admin 13 (3) relay extract_token_usage + current_key_id 防御性修复 (4) 记录 5 个前端孤立 invoke 调用 |
|
||||
| 2026-04-02 | 构建验证通过：cargo check ✅ + tsc --noEmit ✅ |
|
||||
@@ -1,363 +0,0 @@
|
||||
# ZCLAW 项目问题跟踪清单
|
||||
|
||||
> **创建日期：** 2026-03-21
|
||||
> **来源：** 深度分析报告 + 头脑风暴会议
|
||||
|
||||
---
|
||||
|
||||
## 一、P0 问题（紧急）
|
||||
|
||||
### Q4: E2E 测试不稳定
|
||||
|
||||
**问题描述：**
|
||||
- 当前 E2E 测试通过率约 80%
|
||||
- 失败原因主要是网络延迟和等待逻辑不当
|
||||
|
||||
**影响：**
|
||||
- 无法准确评估代码质量
|
||||
- 发布风险增加
|
||||
|
||||
**修复建议：**
|
||||
1. 使用 `waitForFunction` 替代固定 `waitForTimeout`
|
||||
2. 增加断言容错处理
|
||||
3. 增加重试机制
|
||||
|
||||
**负责人：** 测试团队
|
||||
**预估工时：** 2-3 人天
|
||||
**状态：** 待处理
|
||||
|
||||
---
|
||||
|
||||
## 二、P1 问题（重要）
|
||||
|
||||
### Q1: gateway-client.ts 过大
|
||||
|
||||
**问题描述：**
|
||||
- 文件大小 65KB
|
||||
- 包含 WebSocket、REST、认证、心跳、流式处理等职责
|
||||
|
||||
**影响：**
|
||||
- 可维护性差
|
||||
- 代码理解困难
|
||||
|
||||
**修复建议：**
|
||||
```
|
||||
gateway/
|
||||
├── index.ts # 统一导出
|
||||
├── client.ts # 核心类（状态、事件）
|
||||
├── websocket.ts # WebSocket 连接管理
|
||||
├── rest.ts # REST API 封装
|
||||
├── auth.ts # 认证逻辑
|
||||
├── stream.ts # 流式响应处理
|
||||
└── types.ts # 类型定义
|
||||
```
|
||||
|
||||
**负责人：** 前端团队
|
||||
**预估工时：** 2-3 人天
|
||||
**状态：** 待处理
|
||||
|
||||
### Q2: localStorage 降级风险
|
||||
|
||||
**问题描述：**
|
||||
- intelligence-client.ts 在非 Tauri 环境使用 localStorage
|
||||
- 可能导致数据丢失或不一致
|
||||
|
||||
**影响：**
|
||||
- 数据安全性降低
|
||||
- 多端数据不同步
|
||||
|
||||
**修复建议：**
|
||||
- 评估后决定是否保留降级逻辑
|
||||
- 如果保留，确保数据一致性
|
||||
|
||||
**负责人：** 前端 + 后端
|
||||
**预估工时：** 1 周
|
||||
**状态：** 待处理
|
||||
|
||||
### Q3: Rust unwrap() 风险
|
||||
|
||||
**问题描述：**
|
||||
- context_builder.rs 多处使用 unwrap()
|
||||
- 可能导致 panic
|
||||
|
||||
**影响：**
|
||||
- 应用稳定性降低
|
||||
- 用户体验受影响
|
||||
|
||||
**修复建议：**
|
||||
```rust
|
||||
// Before
|
||||
*tokens_by_level.get_mut("L0").unwrap() = l0_tokens;
|
||||
|
||||
// After
|
||||
*tokens_by_level.get_mut("L0").expect("L0 level must exist in tokens_by_level") = l0_tokens;
|
||||
```
|
||||
|
||||
**负责人：** 后端团队
|
||||
**预估工时：** 0.5 人天
|
||||
**状态：** 待处理
|
||||
|
||||
### Q5: 聊天记录未加密
|
||||
|
||||
**问题描述：**
|
||||
- SQLite 存储聊天记录未加密
|
||||
- 敏感信息可能泄露
|
||||
|
||||
**影响：**
|
||||
- 用户隐私风险
|
||||
- 合规风险
|
||||
|
||||
**修复建议：**
|
||||
1. 评估 SQLCipher 方案
|
||||
2. 密钥存储在 OS Keyring
|
||||
3. 旧数据平滑迁移
|
||||
|
||||
**负责人：** 后端团队
|
||||
**预估工时：** 1 周
|
||||
**状态：** 待处理
|
||||
|
||||
### Q7: 缺少兼容性测试
|
||||
|
||||
**问题描述：**
|
||||
- 无 ZCLAW 版本兼容性测试
|
||||
- 版本升级可能破坏功能
|
||||
|
||||
**影响：**
|
||||
- 升级风险高
|
||||
- 问题发现滞后
|
||||
|
||||
**修复建议：**
|
||||
1. 建立 ZCLAW 版本矩阵测试
|
||||
2. 自动化兼容性测试套件
|
||||
3. 版本发布前验证
|
||||
|
||||
**负责人：** 测试团队
|
||||
**预估工时：** 1 周
|
||||
**状态：** 待处理
|
||||
|
||||
---
|
||||
|
||||
## 三、P2 问题（中期）
|
||||
|
||||
### Q6: Store re-render 问题
|
||||
|
||||
**问题描述：**
|
||||
- 某些 Store selector 未优化
|
||||
- 大量消息时可能导致性能问题
|
||||
|
||||
**影响：**
|
||||
- UI 响应慢
|
||||
- 用户体验下降
|
||||
|
||||
**修复建议：**
|
||||
1. 使用 Zustand shallow 比较
|
||||
2. React.memo 优化组件
|
||||
3. 减少 Context 使用
|
||||
|
||||
**负责人：** 前端团队
|
||||
**预估工时：** 2-3 人天
|
||||
**状态：** 待处理
|
||||
|
||||
### Q8: 飞书集成不完整
|
||||
|
||||
**问题描述：**
|
||||
- OAuth 流程可能有问题
|
||||
- 消息格式适配不完整
|
||||
|
||||
**影响：**
|
||||
- 用户无法使用飞书
|
||||
- 功能不完整
|
||||
|
||||
**修复建议：**
|
||||
1. 修复 OAuth 流程
|
||||
2. 完善消息接收和发送
|
||||
3. 支持富文本、图片等
|
||||
|
||||
**负责人：** 前端 + 后端
|
||||
**预估工时：** 1 周
|
||||
**状态：** 待处理
|
||||
|
||||
### Q9: 插件市场不完善
|
||||
|
||||
**问题描述：**
|
||||
- 插件市场 UI 和功能不完整
|
||||
- 审核机制缺失
|
||||
|
||||
**影响：**
|
||||
- 第三方开发者参与度低
|
||||
- 生态发展受限
|
||||
|
||||
**修复建议：**
|
||||
1. 完善插件市场 UI
|
||||
2. 定义标准化插件 API
|
||||
3. 建立审核机制
|
||||
|
||||
**负责人：** 前端团队
|
||||
**预估工时：** 1 周
|
||||
**状态：** 待处理
|
||||
|
||||
### Q10: 缺少 i18n 支持
|
||||
|
||||
**问题描述：**
|
||||
- 大量硬编码字符串
|
||||
- 不支持多语言
|
||||
|
||||
**影响：**
|
||||
- 国际用户使用困难
|
||||
- 未来扩展受限
|
||||
|
||||
**修复建议：**
|
||||
1. 引入 react-i18next
|
||||
2. 提取所有字符串
|
||||
3. 完善中英文翻译
|
||||
|
||||
**负责人：** 前端团队
|
||||
**预估工时：** 1-2 周
|
||||
**状态：** 待处理
|
||||
|
||||
---
|
||||
|
||||
## 四、P3 问题（长期）
|
||||
|
||||
### Q11: 知识图谱缺失
|
||||
|
||||
**问题描述：**
|
||||
- 当前记忆系统不支持复杂关系
|
||||
- 无法进行语义推理
|
||||
|
||||
**影响：**
|
||||
- 差异化竞争力弱
|
||||
- 高级功能受限
|
||||
|
||||
**修复建议：**
|
||||
- 长期规划，Phase 3 实施
|
||||
|
||||
**状态：** 规划中
|
||||
|
||||
### Q12: 跨设备同步缺失
|
||||
|
||||
**问题描述：**
|
||||
- 数据仅本地存储
|
||||
- 无法多设备同步
|
||||
|
||||
**影响：**
|
||||
- 用户体验受限
|
||||
- 竞争力下降
|
||||
|
||||
**修复建议：**
|
||||
- 端到端加密同步作为 Pro 功能
|
||||
- 长期规划
|
||||
|
||||
**状态：** 规划中
|
||||
|
||||
---
|
||||
|
||||
## 五、技术债务
|
||||
|
||||
### D1: gatewayStore.ts 残留引用
|
||||
|
||||
**问题描述：**
|
||||
- 部分组件仍直接引用 gatewayStore
|
||||
- 应迁移到领域 Store
|
||||
|
||||
**影响：**
|
||||
- 维护困难
|
||||
- 架构不清晰
|
||||
|
||||
**清理方式：**
|
||||
- 逐步迁移到 useAgentStore, useHandStore 等
|
||||
- 更新导入路径
|
||||
|
||||
**状态：** 进行中
|
||||
|
||||
### D2: 旧版 API 兼容代码
|
||||
|
||||
**问题描述：**
|
||||
- 存在旧版 ZCLAW 兼容代码
|
||||
- 增加体积
|
||||
|
||||
**影响：**
|
||||
- bundle 增大
|
||||
- 维护复杂性
|
||||
|
||||
**清理方式：**
|
||||
- 评估后移除
|
||||
|
||||
**状态：** 待评估
|
||||
|
||||
### D3: v1 归档代码未清理
|
||||
|
||||
**问题描述：**
|
||||
- docs/archive/v1-viking-dead-code/ 存在未清理代码
|
||||
- 可能混淆新开发者
|
||||
|
||||
**影响：**
|
||||
- 代码库不清晰
|
||||
- 新人上手困难
|
||||
|
||||
**清理方式：**
|
||||
- 删除或彻底移入 archive
|
||||
|
||||
**状态：** 待处理
|
||||
|
||||
### D4: 重复的工具函数
|
||||
|
||||
**问题描述：**
|
||||
- 存在相似的工具函数
|
||||
- 可能重复实现
|
||||
|
||||
**影响：**
|
||||
- 维护困难
|
||||
- 体积增加
|
||||
|
||||
**清理方式：**
|
||||
- 提取到统一 utils
|
||||
|
||||
**状态：** 待处理
|
||||
|
||||
### D5: 缺失的 JSDoc
|
||||
|
||||
**问题描述：**
|
||||
- 部分模块缺少文档
|
||||
- 理解困难
|
||||
|
||||
**影响：**
|
||||
- 新人上手慢
|
||||
- 代码维护困难
|
||||
|
||||
**清理方式：**
|
||||
- 补全关键模块 JSDoc
|
||||
|
||||
**状态：** 待处理
|
||||
|
||||
---
|
||||
|
||||
## 六、问题统计
|
||||
|
||||
| 优先级 | 问题数 | 已解决 | 待处理 | 规划中 |
|
||||
|--------|--------|--------|--------|--------|
|
||||
| P0 | 1 | 0 | 1 | 0 |
|
||||
| P1 | 5 | 0 | 5 | 0 |
|
||||
| P2 | 5 | 0 | 5 | 0 |
|
||||
| P3 | 2 | 0 | 0 | 2 |
|
||||
| 债务 | 5 | 0 | 4 | 1 |
|
||||
| **总计** | **18** | **0** | **15** | **3** |
|
||||
|
||||
---
|
||||
|
||||
## 七、修复进度
|
||||
|
||||
| 日期 | 修复问题 | 状态 |
|
||||
|------|----------|------|
|
||||
| - | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 八、验收标准
|
||||
|
||||
每个问题修复后应满足：
|
||||
|
||||
1. ✅ 有对应的测试用例
|
||||
2. ✅ 代码审查通过
|
||||
3. ✅ 文档已更新
|
||||
4. ✅ 无引入新问题
|
||||
@@ -0,0 +1,558 @@
|
||||
# ZCLAW 行业 Agent 交付设计
|
||||
|
||||
> **日期**: 2026-04-03
|
||||
> **状态**: Reviewed (v2 — 修复 12 项审查问题)
|
||||
> **目标**: 让普通中文用户 安装→登录→选行业Agent→开始聊天
|
||||
> **前置条件**: SaaS 后端本地运行（Axum + PostgreSQL），桌面端 Tauri 2.x
|
||||
> **审查修正**: quick_commands 类型对齐、种子数据冲突处理、字段传透路径明确、错误处理补全
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与动机
|
||||
|
||||
ZCLAW 经过 4 个月的迭代，后端能力完整（10 crates、176 Tauri 命令、93 SaaS API、76 Skills、9 Hands），但系统在快速迭代中偏离了"用户可用"的目标。
|
||||
|
||||
核心问题：
|
||||
- **零模板数据**: agent_templates 表为空，OnboardingWizard 只显示"空白 Agent"
|
||||
- **字段未传透**: `createFromTemplate()` 丢失 system_prompt / soul_content / welcome_message / quick_commands / tools / capabilities
|
||||
- **无 Admin 分配机制**: SaaS 管理员无法为账号预分配行业 Agent
|
||||
- **技能无执行入口**: SkillMarket 只能浏览/安装，无法触发
|
||||
- **目标用户错误假设**: 系统设计时假设了"本地模式 + 用户自配 API Key"，实际用户通过 SaaS token 池使用
|
||||
|
||||
### 纠正后的目标
|
||||
|
||||
- 用户: 普通中文用户，不懂技术
|
||||
- 模型: SaaS relay token 池，用户不碰 API Key
|
||||
- 流程: 安装 → 登录 → 选行业Agent(或被分配) → 聊天
|
||||
|
||||
---
|
||||
|
||||
## 2. 行业 Agent 深度模板
|
||||
|
||||
### 2.1 模板数据结构
|
||||
|
||||
每个模板在 `agent_templates` 表中包含以下扩展字段：
|
||||
|
||||
```sql
|
||||
INSERT INTO agent_templates (
|
||||
name, description, category, emoji,
|
||||
system_prompt, soul_content, welcome_message,
|
||||
quick_commands, -- JSONB array: ["解读报告", "症状查询", ...]
|
||||
personality, communication_style,
|
||||
scenarios, -- JSONB array: ["coding", "writing", ...]
|
||||
tools, -- JSONB array: ["Researcher", "Collector", ...]
|
||||
capabilities, -- JSONB array: ["browser", "research", ...]
|
||||
model, -- 首选模型标识，如 "glm-4-flash"
|
||||
visibility, status, version, source_id
|
||||
) VALUES (...);
|
||||
```
|
||||
|
||||
### 2.2 五个行业模板定义
|
||||
|
||||
#### TMPL-01: 医疗健康顾问 🩺
|
||||
|
||||
**system_prompt** (核心角色):
|
||||
```
|
||||
你是「健康顾问」，一个专业的医疗信息辅助助手。
|
||||
|
||||
核心原则：
|
||||
1. 你只能提供健康信息查询和建议，绝对不能做医学诊断
|
||||
2. 你不能开具处方、推荐具体药物剂量或治疗方案
|
||||
3. 所有建议必须基于循证医学原则
|
||||
4. 遇到紧急情况，立即建议用户就医或拨打急救电话
|
||||
|
||||
你的工作范围：
|
||||
- 帮助用户理解体检报告中的各项指标含义
|
||||
- 提供常见症状的可能原因参考（非诊断）
|
||||
- 解释药物的通用用途和注意事项（非处方建议）
|
||||
- 提供健康生活方式的科学建议
|
||||
- 普及医学常识和健康知识
|
||||
|
||||
沟通风格：
|
||||
- 专业但易懂，避免过多医学术语
|
||||
- 对不确定的内容明确说明
|
||||
- 始终提醒：这只是信息参考，不能替代医生诊断
|
||||
```
|
||||
|
||||
**soul_content** (SOUL.md):
|
||||
```
|
||||
# 灵魂文件 - 健康顾问
|
||||
|
||||
## 价值观
|
||||
- 生命安全高于一切
|
||||
- 科学循证，不传播偏方
|
||||
- 尊重患者隐私
|
||||
- 知之为知之，不知为不知
|
||||
|
||||
## 行为准则
|
||||
- 每次回复都提醒"仅供参考，请遵医嘱"
|
||||
- 遇到超出范围的问题主动建议就医
|
||||
- 不评判用户的健康选择
|
||||
- 用最通俗的语言解释复杂概念
|
||||
|
||||
## 禁区
|
||||
- 绝不做诊断（"你可能患了xxx"）
|
||||
- 绝不开处方（"你可以吃xx药"）
|
||||
- 绝不推荐替代正规治疗的方案
|
||||
- 绝不讨论安乐死等敏感话题
|
||||
```
|
||||
|
||||
**welcome_message**: "你好！我是你的健康顾问 🩺 我可以帮你解读体检报告、了解症状可能的原因、查询用药注意事项。请问今天有什么想了解的？"
|
||||
|
||||
**quick_commands**:
|
||||
```json
|
||||
[
|
||||
{"label": "解读报告", "command": "帮我解读一下这份体检报告"},
|
||||
{"label": "症状查询", "command": "我想了解一下这个症状的可能原因"},
|
||||
{"label": "用药禁忌", "command": "查询一下用药注意事项和禁忌"},
|
||||
{"label": "健康建议", "command": "给我一些健康生活方面的建议"}
|
||||
]
|
||||
```
|
||||
|
||||
**tools**: `["Researcher", "Collector"]`
|
||||
**scenarios**: `["report_interpretation", "symptom_query", "medication_info", "health_education"]`
|
||||
**personality**: `"professional_caring"`
|
||||
**communication_style**: `"专业严谨、通俗易懂、始终提醒仅供参考"`
|
||||
|
||||
---
|
||||
|
||||
#### TMPL-02: 制衣行业助手 👔
|
||||
|
||||
**system_prompt**:
|
||||
```
|
||||
你是「制衣助手」，一个专业的服装行业顾问。
|
||||
|
||||
核心能力：
|
||||
- 面料知识：纱支、密度、克重、缩水率、色牢度等指标解读
|
||||
- 工艺流程：裁剪、缝制、整烫、包装各环节优化
|
||||
- 成本核算：面料成本、加工费、辅料、包装全链路
|
||||
- 趋势洞察：流行色、面料趋势、款式方向
|
||||
|
||||
工作范围：
|
||||
- 根据用途推荐面料（季节/场景/价位）
|
||||
- 分析工艺方案的可行性和成本
|
||||
- 对比供应商报价合理性
|
||||
- 提供尺码表、洗水标等标准化建议
|
||||
|
||||
沟通风格：
|
||||
- 直接务实，使用行业术语（会解释含义）
|
||||
- 给出具体数据和对比
|
||||
- 考虑成本效益比
|
||||
```
|
||||
|
||||
**welcome_message**: "你好！我是制衣行业助手 👔 面料选型、工艺建议、成本核算、趋势分析我都能帮忙。请告诉我你目前需要什么帮助？"
|
||||
|
||||
**quick_commands**: `[{"label":"面料对比","command":"帮我对比一下这两种面料的优缺点"},{"label":"工艺建议","command":"这个设计有什么工艺上的建议"},{"label":"成本核算","command":"帮我核算一下这批订单的成本"},{"label":"趋势分析","command":"分析一下当前的面料流行趋势"}]`
|
||||
**tools**: `["Researcher", "Collector", "Whiteboard"]`
|
||||
**personality**: `"pragmatic_efficient"`
|
||||
**communication_style**: `"务实高效、数据说话、善用行业术语"`
|
||||
|
||||
---
|
||||
|
||||
#### TMPL-03: 玩具行业助手 🧸
|
||||
|
||||
**system_prompt**:
|
||||
```
|
||||
你是「玩具助手」，一个懂创意更懂安全的玩具行业顾问。
|
||||
|
||||
核心能力：
|
||||
- 安全合规：EN71（欧盟）、GB6675（中国）、ASTM F963（美国）等全球标准
|
||||
- 产品创意：从概念到产品的完整创意流程
|
||||
- 市场分析：年龄段分析、竞品调研、趋势洞察
|
||||
- IP 授权：热门 IP 合作模式和注意事项
|
||||
|
||||
工作原则：
|
||||
- 安全第一：任何创意必须先过安全关
|
||||
- 合规先行：目标市场的强制性标准必须满足
|
||||
- 创意务实：好看的创意更要能落地生产
|
||||
|
||||
沟通风格：
|
||||
- 活泼有创意但不失专业
|
||||
- 善于用案例说明
|
||||
- 关注安全提示
|
||||
```
|
||||
|
||||
**welcome_message**: "嗨！我是玩具行业助手 🧸 从创意提案到安全合规，从市场调研到竞品分析，我都能帮你。你正在做什么类型的玩具呢？"
|
||||
|
||||
**quick_commands**: `[{"label":"安全合规"," "command":"查询玩具安全合规标准"}, {"label":"创意提案"," "command":"帮我设计一个玩具产品概念"}, {"label":"市场调研"," "command":"分析当前玩具市场趋势"}, {"label":"竞品分析", "command":"对比分析主要竞品"}]
|
||||
```
|
||||
**tools**: `["Researcher", "Collector", "Slideshow"]`
|
||||
**personality**: `"creative_safety_first"`
|
||||
**communication_style**: `"活泼创意、安全优先、案例丰富"`
|
||||
|
||||
---
|
||||
|
||||
#### TMPL-04: 教育辅导助手 📚
|
||||
|
||||
**system_prompt**:
|
||||
```
|
||||
你是「学习伙伴」，一个耐心的教育辅导助手。
|
||||
|
||||
教学理念：
|
||||
- 启发式教学：不直接给答案，引导学生思考
|
||||
- 因材施教：根据学生水平调整讲解深度
|
||||
- 鼓励为主：每一点进步都值得肯定
|
||||
- 知识串联：帮助建立知识间的联系
|
||||
|
||||
工作范围：
|
||||
- 知识点讲解：用通俗语言解释复杂概念
|
||||
- 出题练习：根据知识点生成练习题
|
||||
- 学习计划：制定个性化学习路径
|
||||
- 错题分析：分析错误原因并针对性强化
|
||||
|
||||
沟通风格：
|
||||
- 温和耐心，不催促
|
||||
- 用比喻和类比帮助理解
|
||||
- 适时鼓励和肯定
|
||||
- 允许学生犯错，引导纠正
|
||||
```
|
||||
|
||||
**welcome_message**: "你好呀！我是你的学习伙伴 📚 无论你想学什么，我都可以帮你理解概念、制定学习计划、出练习题。今天想学点什么呢？"
|
||||
|
||||
**quick_commands**: `["讲解概念", "出题练习", "学习计划", "错题分析"]`
|
||||
**tools**: `["Quiz", "Slideshow", "Whiteboard", "Speech"]`
|
||||
**personality**: `"patient_encouraging"`
|
||||
**communication_style**: `"耐心启发、因材施教、鼓励为主"`
|
||||
|
||||
---
|
||||
|
||||
#### TMPL-05: 金融分析助手 📊
|
||||
|
||||
**system_prompt**:
|
||||
```
|
||||
你是「金融助手」，一个数据驱动的金融信息分析助手。
|
||||
|
||||
核心原则：
|
||||
- 数据驱动：所有分析基于公开数据，标明来源
|
||||
- 风险意识：始终提示风险因素
|
||||
- 合规优先：不推荐具体股票、不承诺收益
|
||||
- 信息仅供参考：明确声明非投资建议
|
||||
|
||||
工作范围：
|
||||
- 市场速览：主要指数、板块热点的简要分析
|
||||
- 财报解读：上市公司财务数据解读（非投资建议）
|
||||
- 风险评估：行业/政策/市场风险因素梳理
|
||||
- 行业研究：特定行业的市场规模、竞争格局分析
|
||||
|
||||
沟通风格：
|
||||
- 客观理性，避免情绪化表达
|
||||
- 数据可视化建议（表格/图表）
|
||||
- 风险和机会并重
|
||||
- 每次分析结尾加免责声明
|
||||
```
|
||||
|
||||
**welcome_message**: "你好！我是金融分析助手 📊 市场速览、财报解读、风险评估、行业对比——我可以帮你高效获取和分析金融信息。请注意：我提供的信息仅供参考，不构成投资建议。今天想了解什么？"
|
||||
|
||||
**quick_commands**: `["市场速览", "财报解读", "风险提示", "行业对比"]`
|
||||
**tools**: `["Researcher", "Collector"]`
|
||||
**personality**: `"analytical_cautious"`
|
||||
**communication_style**: `"数据驱动、风险意识、合规优先"`
|
||||
|
||||
---
|
||||
|
||||
## 3. 模板字段传透修复
|
||||
|
||||
### 3.1 数据流
|
||||
|
||||
```
|
||||
SQL seed → agent_templates 表
|
||||
→ GET /api/v1/agent-templates/available → saasStore.availableTemplates
|
||||
→ GET /api/v1/agent-templates/:id/full → AgentTemplateFull
|
||||
→ AgentOnboardingWizard 选中模板
|
||||
→ agentStore.createFromTemplate(fullTemplate)
|
||||
→ gateway-client.createClone(extendedParams)
|
||||
→ Tauri invoke('clone_create', ...)
|
||||
→ Kernel 写入 Agent 配置 + SOUL.md + identity
|
||||
```
|
||||
|
||||
### 3.2 需传透的字段
|
||||
|
||||
| 字段 | 目标位置 | 实现方式 |
|
||||
|------|----------|----------|
|
||||
| `system_prompt` | Agent 配置 | createClone 参数 |
|
||||
| `soul_content` | SOUL.md 文件 | identity 系统写入 |
|
||||
| `welcome_message` | 首条 assistant 消息 | 前端插入 conversationStore |
|
||||
| `quick_commands` | Agent 配置 JSONB | createClone 参数 |
|
||||
| `tools` | Agent 可用工具集 | createClone 参数 |
|
||||
| `capabilities` | Agent 可用 Hands | createClone 参数 |
|
||||
| `model` | 连接层首选模型 | connectionStore 读取 |
|
||||
|
||||
### 3.3 修改文件
|
||||
|
||||
| 文件 | 改动说明 |
|
||||
|------|----------|
|
||||
| `desktop/src/store/agentStore.ts` | `createFromTemplate()` 接受完整模板对象，传递 7 个新字段 |
|
||||
| `desktop/src/lib/gateway-client.ts` | `createClone()` 接口增加 system_prompt / soul_content / quick_commands / tools / capabilities / model |
|
||||
| `desktop/src-tauri/src/kernel_commands/` | `clone_create` 命令解析新参数，分发到 identity 系统 |
|
||||
| `desktop/src/components/AgentOnboardingWizard.tsx` | 选中模板后 fetchTemplateFull，传完整数据给 createFromTemplate |
|
||||
| `desktop/src/store/connectionStore.ts` | relay 模式下优先使用模板指定的 model |
|
||||
| `desktop/src/components/ChatArea.tsx` | 读取当前 Agent 的 quick_commands 渲染快捷按钮 |
|
||||
|
||||
### 3.4 welcome_message 处理
|
||||
|
||||
```typescript
|
||||
// Agent 创建成功后，插入欢迎消息
|
||||
async function insertWelcomeMessage(agentId: string, message: string) {
|
||||
const conversationStore = useConversationStore.getState();
|
||||
conversationStore.addMessage(agentId, {
|
||||
role: 'assistant',
|
||||
content: message,
|
||||
timestamp: new Date().toISOString(),
|
||||
metadata: { type: 'welcome' },
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 quick_commands 类型与 UI
|
||||
|
||||
**类型定义** (对齐现有代码 `saas-types.ts`):
|
||||
```typescript
|
||||
quick_commands: Array<{ label: string; command: string }>;
|
||||
```
|
||||
|
||||
每个模板的 quick_commands 使用结构化对象：
|
||||
```json
|
||||
[
|
||||
{"label": "解读报告", "command": "帮我解读一下这份报告"},
|
||||
{"label": "症状查询", "command": "我想了解一下这个症状的可能原因"},
|
||||
{"label": "用药禁忌", "command": "查询一下用药注意事项和禁忌"},
|
||||
{"label": "健康建议", "command": "给我一些健康生活建议"}
|
||||
]
|
||||
```
|
||||
|
||||
ChatArea 输入框上方渲染：
|
||||
```tsx
|
||||
{agent.quickCommands?.map(cmd => (
|
||||
<button onClick={() => setInput(cmd.command)}>{cmd.label}</button>
|
||||
))}
|
||||
```
|
||||
|
||||
### 3.6 种子数据冲突处理
|
||||
|
||||
**已有种子** (`crates/zclaw-saas/src/db.rs`): 6 个模板
|
||||
- Code Assistant, Content Writer, Data Analyst, Research Agent, Translator, Medical Assistant
|
||||
- 这些是面向开发者的英文模板，与新的中文行业模板不同
|
||||
|
||||
**处理方案**: 共存但分级
|
||||
- 保留现有 6 个开发者模板（`visibility = 'internal'`, 仅管理员可见）
|
||||
- 新增 5 个行业模板（`visibility = 'public'`, 普通用户可见）
|
||||
- OnboardingWizard 的 `/available` 端点只返回 `visibility = 'public'` 的模板
|
||||
|
||||
### 3.7 Tauri 命令传透路径
|
||||
|
||||
完整链路（已验证命令名 `clone_create`）：
|
||||
```
|
||||
gateway-client.ts createClone(params)
|
||||
→ invoke('clone_create', { ...params })
|
||||
→ desktop/src-tauri/src/kernel_commands/lifecycle.rs clone_create()
|
||||
→ Kernel::create_agent(config)
|
||||
→ identity system: write SOUL.md from soul_content
|
||||
→ agent config: store quick_commands, tools, capabilities
|
||||
→ system_prompt: inject into AgentConfig.prompt
|
||||
```
|
||||
|
||||
### 3.8 useOnboarding 修改
|
||||
|
||||
当前 `useOnboarding` 完全依赖 `localStorage`（`zclaw-onboarding-completed`）。
|
||||
|
||||
**修改方案**: 在 `use-onboarding.ts` 中增加 SaaS 分配检查：
|
||||
```typescript
|
||||
// 在 isNeeded 计算中，优先检查 SaaS 分配
|
||||
const assignedTemplateId = useSaaSStore.getState().account?.assigned_template_id;
|
||||
if (assignedTemplateId) {
|
||||
// 有分配模板 → 跳过 onboarding（App.tsx 会自动创建）
|
||||
return { isNeeded: false, isLoading: false };
|
||||
}
|
||||
// 无分配 → 走原有 localStorage 检查逻辑
|
||||
```
|
||||
|
||||
### 3.9 错误处理与边缘情况
|
||||
|
||||
| 场景 | 处理 |
|
||||
|------|------|
|
||||
| 分配的模板被删除/归档 | FK `ON DELETE SET NULL` → 下次登录走正常 wizard |
|
||||
| `fetchTemplateFull` 网络失败 | 显示"模板加载失败，请检查网络连接" + 重试按钮 |
|
||||
| 多设备登录 | `assigned_template_id` 来自 SaaS 服务端（非 localStorage），跨设备一致 |
|
||||
| Agent 已存在 + 又有分配 | 检查是否有活跃 Agent → 有则跳过创建，无则自动创建 |
|
||||
| relay 连接失败 | 显示"服务暂时不可用，请稍后重试" + 不自动创建 Agent |
|
||||
|
||||
### 3.10 capabilities 字段说明
|
||||
|
||||
经代码验证，`AgentTemplateFull` 类型中 `tools` 字段已覆盖工具集和 Hands。
|
||||
**不再单独传 `capabilities`**，统一使用 `tools` 字段。从传透表（3.2）中移除 `capabilities`。
|
||||
|
||||
### 3.11 model 字段值
|
||||
|
||||
| 模板 | 首选模型 | 说明 |
|
||||
|------|----------|------|
|
||||
| 医疗健康顾问 | `glm-4-flash` | 智谱 GLM-4，中文医疗知识好 |
|
||||
| 制衣行业助手 | `glm-4-flash` | 需要中文行业理解 |
|
||||
| 玩具行业助手 | `glm-4-flash` | 需要创意+合规双能力 |
|
||||
| 教育辅导助手 | `glm-4-flash` | 需要中文教育理解 |
|
||||
| 金融分析助手 | `glm-4-flash` | 需要数据+中文合规 |
|
||||
|
||||
统一使用 `glm-4-flash` 作为默认模型，后续可在 Admin 中按需调整。
|
||||
|
||||
---
|
||||
|
||||
## 4. SaaS Admin 行业 Agent 分配
|
||||
|
||||
### 4.1 数据库变更
|
||||
|
||||
```sql
|
||||
-- 新建 migration: xxxx_add_assigned_template_to_accounts.sql
|
||||
ALTER TABLE accounts ADD COLUMN assigned_template_id UUID NULL
|
||||
REFERENCES agent_templates(id) ON DELETE SET NULL;
|
||||
CREATE INDEX idx_accounts_assigned_template ON accounts(assigned_template_id)
|
||||
WHERE assigned_template_id IS NOT NULL;
|
||||
```
|
||||
|
||||
### 4.2 Rust 后端改动
|
||||
|
||||
**auth/types.rs** — `AccountPublic` 增加字段:
|
||||
```rust
|
||||
pub struct AccountPublic {
|
||||
// ... 现有 9 个字段 ...
|
||||
pub assigned_template_id: Option<String>, // 新增
|
||||
}
|
||||
```
|
||||
|
||||
**auth/handlers.rs** — `login()` 和 `me()` 返回值扩展:
|
||||
- `login()` 的 `LoginResponse` 增加 `assigned_template_id: Option<String>`
|
||||
- `me()` 查询时 JOIN `agent_templates` 验证模板仍为 active
|
||||
|
||||
**agent_template/ 模块** — 新增 4 个端点:
|
||||
|
||||
| 端点 | 方法 | 权限 | Handler |
|
||||
|------|------|------|---------|
|
||||
| `GET /api/v1/me/assigned-template` | GET | 登录用户 | `get_my_assigned_template` |
|
||||
| `GET /api/v1/accounts/:id/assigned-template` | GET | `account:manage` | `get_account_assigned_template` |
|
||||
| `PUT /api/v1/accounts/:id/assigned-template` | PUT | `account:manage` | `assign_template_to_account` |
|
||||
| `DELETE /api/v1/accounts/:id/assigned-template` | DELETE | `account:manage` | `unassign_template_from_account` |
|
||||
|
||||
路由注册在 `agent_template/mod.rs` 的 `routes()` 函数中追加。
|
||||
|
||||
### 4.3 前端 Store 改动
|
||||
|
||||
**desktop/src/store/saasStore.ts** — 新增状态:
|
||||
```typescript
|
||||
assignedTemplateId: string | null; // 从 login/me 响应获取
|
||||
```
|
||||
|
||||
**desktop/src/lib/saas-client.ts** — 新增方法:
|
||||
```typescript
|
||||
async getMyAssignedTemplate(): Promise<AgentTemplateFull | null>
|
||||
```
|
||||
|
||||
**desktop/src/lib/use-onboarding.ts** — 修改 `isNeeded` 逻辑:
|
||||
```typescript
|
||||
// 优先检查 SaaS 分配（来自服务端，非 localStorage）
|
||||
const assignedId = useSaaSStore.getState().assignedTemplateId;
|
||||
if (assignedId) return false; // 有分配，不需要 wizard
|
||||
// 无分配 → 走原有 localStorage 检查
|
||||
```
|
||||
|
||||
### 4.4 Admin V2 改动
|
||||
|
||||
账号管理页增加"行业 Agent"列，下拉选择（5 个模板 + "不分配"）。
|
||||
|
||||
### 4.5 桌面端 Onboarding 逻辑
|
||||
|
||||
```typescript
|
||||
// App.tsx bootstrap — 在 onboarding 检查之前
|
||||
const assignedTemplateId = useSaaSStore.getState().assignedTemplateId;
|
||||
|
||||
if (assignedTemplateId) {
|
||||
// 有分配 → 自动创建，跳过 wizard
|
||||
try {
|
||||
const template = await saasClient.fetchTemplateFull(assignedTemplateId);
|
||||
await agentStore.createFromTemplate(template);
|
||||
await insertWelcomeMessage(template.welcome_message);
|
||||
// 不 showOnboarding
|
||||
} catch (err) {
|
||||
log.warn('Auto-create from assigned template failed:', err);
|
||||
setShowOnboarding(true); // 回退到手动 wizard
|
||||
}
|
||||
} else {
|
||||
// 无分配 → 检查 localStorage → 正常 wizard
|
||||
if (onboardingNeeded) {
|
||||
setShowOnboarding(true);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 技能执行入口
|
||||
|
||||
### 5.1 SkillMarket "试用" 按钮
|
||||
|
||||
技能卡片添加"在聊天中试用"按钮，点击后：
|
||||
1. 切换 `mainContentView` 到 'chat'
|
||||
2. 设置 ChatArea 的 input 为技能触发词
|
||||
3. 用户按 Enter 触发
|
||||
|
||||
### 5.2 自动技能匹配（已有）
|
||||
|
||||
`streamStore.searchSkills()` 在发送消息时自动匹配触发词，匹配成功后调用技能。在聊天气泡中显示"使用了技能: xxx"标签。
|
||||
|
||||
### 5.3 Hands 能力边界
|
||||
|
||||
AutomationPanel 根据 Agent 模板的 `tools` 字段过滤展示的 Hands。只展示 Agent 能力范围内的。
|
||||
|
||||
---
|
||||
|
||||
## 6. 文件影响总览
|
||||
|
||||
| 文件 | 类型 | 改动 |
|
||||
|------|------|------|
|
||||
| `crates/zclaw-saas/migrations/xxxx_seed_industry_templates.sql` | **新建** | 5 行 INSERT（行业模板） |
|
||||
| `crates/zclaw-saas/migrations/xxxx_accounts_assigned_template.sql` | **新建** | ALTER TABLE + INDEX |
|
||||
| `crates/zclaw-saas/src/agent_template/handlers.rs` | 修改 | 新增 4 个分配端点 |
|
||||
| `crates/zclaw-saas/src/agent_template/service.rs` | 修改 | 分配 CRUD 逻辑 |
|
||||
| `crates/zclaw-saas/src/agent_template/mod.rs` | 修改 | 路由注册 |
|
||||
| `crates/zclaw-saas/src/auth/handlers.rs` | 修改 | login/me 响应加 assigned_template_id |
|
||||
| `crates/zclaw-saas/src/auth/types.rs` | 修改 | AccountPublic + LoginResponse 加字段 |
|
||||
| `crates/zclaw-saas/src/db.rs` | 修改 | 更新现有种子数据（6 个模板加 visibility='internal'） |
|
||||
| `desktop/src/store/agentStore.ts` | 修改 | createFromTemplate 补全 7 个字段 |
|
||||
| `desktop/src/lib/gateway-client.ts` | 修改 | createClone 接口扩展 |
|
||||
| `desktop/src/lib/saas-client.ts` | 修改 | 新增 getMyAssignedTemplate() |
|
||||
| `desktop/src/lib/saas-types.ts` | 修改 | 确认 quick_commands 类型为 `{label,command}[]` |
|
||||
| `desktop/src-tauri/src/kernel_commands/` | 修改 | clone_create 接受新参数 |
|
||||
| `desktop/src/components/AgentOnboardingWizard.tsx` | 修改 | 模板传透 + 分配判断 |
|
||||
| `desktop/src/components/ChatArea.tsx` | 修改 | quick_commands 快捷按钮 + 技能入口 |
|
||||
| `desktop/src/components/SkillMarket.tsx` | 修改 | "试用"按钮 |
|
||||
| `desktop/src/store/connectionStore.ts` | 修改 | relay 模型选择关联模板 |
|
||||
| `desktop/src/store/saasStore.ts` | 修改 | 存储 assignedTemplateId |
|
||||
| `desktop/src/lib/use-onboarding.ts` | 修改 | 优先检查 SaaS 分配 |
|
||||
| `desktop/src/App.tsx` | 修改 | 分配判断逻辑 |
|
||||
| `admin-v2/src/pages/` | 修改 | 分配模板 UI |
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证方案
|
||||
|
||||
### 场景 1: 自主选择流程
|
||||
1. 运行 `docker compose up -d` 启动 PostgreSQL
|
||||
2. 运行 SaaS 后端 `cargo run -p zclaw-saas`
|
||||
3. 启动桌面端 `pnpm tauri:dev`
|
||||
4. 注册新账号（无分配模板）
|
||||
5. 看到 5 个行业模板选择界面
|
||||
6. 选择"教育辅导" → 填用户信息 → 创建成功
|
||||
7. 看到欢迎语 "你好呀！我是你的学习伙伴 📚"
|
||||
8. quick_commands 显示："讲解概念"、"出题练习"、"学习计划"、"错题分析"
|
||||
9. 发消息 → 收到流式回复
|
||||
10. 进入 SkillMarket → 安装技能 → 点"试用" → 触发词填充到输入框
|
||||
|
||||
### 场景 2: 管理员分配流程
|
||||
1. Admin V2 后台 → 账号管理 → 为测试用户分配"医疗健康顾问"
|
||||
2. 桌面端注销 → 重新登录
|
||||
3. 自动创建医疗 Agent → 显示欢迎语
|
||||
4. quick_commands 显示："解读报告"、"症状查询"、"用药禁忌"、"健康建议"
|
||||
5. 发消息 "解读一下我的血常规报告" → 收到回复
|
||||
|
||||
### 构建验证
|
||||
```bash
|
||||
cargo check --workspace
|
||||
pnpm tsc --noEmit
|
||||
```
|
||||
Reference in New Issue
Block a user