442ec0eeef
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
混合矩阵式审计：10 个功能模块 × 五维检查清单 - 项目整体健康度: 76/100 - 2 个 P0 (M4 双数据库 + 反思引擎 LLM 未接入) - 15 个 P1 (跨 M2/M3/M4/M5/M6/M7/M11) - 三类断链模式: 写了没接/接了不对/双实现未统一 - 三阶段修复路线图: P0(2-3天) → P1(5-7天) → P2(5-7天)
150 lines
8.9 KiB
Markdown
150 lines
8.9 KiB
Markdown
# 模块 M2 Agent 分身 审计报告
|
||
|
||
> **审计版本**: V12
|
||
> **审计日期**: 2026-04-04
|
||
> **审计范围**: Agent 创建/切换/配置/删除 → agentStore → Kernel → SQLite
|
||
|
||
---
|
||
|
||
## 1. 模块概况
|
||
|
||
### 功能描述
|
||
多 Agent 创建/配置/管理，每个 Agent 拥有独立的身份、技能和配置，SQLite 持久化。
|
||
|
||
### 涉及文件清单
|
||
|
||
**前端**
|
||
- Store: `desktop/src/store/agentStore.ts`, `desktop/src/store/chat/conversationStore.ts`
|
||
- Client: `desktop/src/lib/kernel-agent.ts`, `desktop/src/lib/gateway-api.ts`
|
||
- 类型: `desktop/src/lib/kernel-types.ts`
|
||
- UI: `desktop/src/components/AgentSelector.tsx`
|
||
|
||
**后端 (Rust)**
|
||
- Tauri 命令: `desktop/src-tauri/src/kernel_commands/agent.rs`
|
||
- Kernel 业务: `crates/zclaw-kernel/src/kernel/agents.rs`
|
||
- Registry: `crates/zclaw-kernel/src/registry.rs`
|
||
- SQLite 存储: `crates/zclaw-memory/src/store.rs`
|
||
- Schema: `crates/zclaw-memory/src/schema.rs`
|
||
- 类型: `crates/zclaw-types/src/agent.rs`, `crates/zclaw-types/src/config.rs`
|
||
|
||
### 调用链路图
|
||
|
||
```
|
||
用户操作 (创建/切换/配置/删除 Agent)
|
||
→ agentStore.createClone(opts) / updateClone() / deleteClone()
|
||
→ getClient().createClone() / updateClone() / deleteClone()
|
||
├─ [Kernel 模式] kernel-agent.ts → invoke('agent_create/update/delete')
|
||
│ → Rust: agent_create/update/delete → kernel.spawn/kill/update_agent()
|
||
│ → agents.rs: 验证 → MemoryStore.save_agent() → Registry 注册/移除
|
||
│ → store.rs: INSERT/UPDATE/DELETE agents 表 (SQLite)
|
||
│
|
||
└─ [Gateway 模式] gateway-api.ts → REST POST/PUT/DELETE /api/agents
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 五维检查结果
|
||
|
||
### 2.1 链路完整性
|
||
|
||
| 链路 | 起点 | 终点 | 状态 | 备注 |
|
||
|------|------|------|------|------|
|
||
| 创建 Agent (Kernel) | agentStore.createClone() | store.rs INSERT | ⚠️ **字段丢失** | kernel-agent.ts 只传 3 字段，丢 7 个人格字段 |
|
||
| 创建 Agent (Gateway) | agentStore.createClone() | gateway-api.ts POST | ✅ 连通 | 传完整 TOML manifest |
|
||
| 列举 Agent | agentStore.loadClones() | Registry → SQLite | ✅ 连通 | |
|
||
| 更新 Agent | agentStore.updateClone() | store.rs UPDATE | ⚠️ **字段丢失** | 同创建，仅 7 字段可更新 |
|
||
| 删除 Agent | agentStore.deleteClone() | store.rs DELETE | ✅ 连通 | SQLite 外键级联删除 sessions |
|
||
| 切换 Agent | conversationStore.setCurrentAgent() | conversationStore state | ⚠️ **不通知 Kernel** | defaultAgentId 不更新 |
|
||
| 从模板创建 | agentStore.createFromTemplate() | SaaS + Kernel | ⚠️ **metadata 更新可能静默失败** | |
|
||
|
||
### 2.2 参数/类型一致性
|
||
|
||
| 接口 | 前端传递字段 | 后端期望字段 | 一致性 | 备注 |
|
||
|------|------------|------------|--------|------|
|
||
| agent_create request | name, description, model | agent_id, name, description, model, system_prompt, max_tokens, temperature, provider, ... | ❌ **不完整** | 前端丢 7+ 字段 |
|
||
| AgentInfo 返回 | id, name, description?, state, model?, provider? | id, name, description, model, provider, state, message_count, created_at, updated_at | ❌ **字段丢失** | 前端缺 message_count/created_at/updated_at |
|
||
| agent_update updates | name, description, systemPrompt, model, provider, maxTokens, temperature | 同左 (7 字段) | ✅ 一致 | 但缺 emoji/personality 等 |
|
||
| 默认 provider | kernel-agent.ts: `'openai'` | agent.rs: `'anthropic'` | ❌ **不一致** | JS 层覆盖所以不影响运行 |
|
||
|
||
### 2.3 边界与错误处理
|
||
|
||
| 场景 | 输入 | 预期行为 | 实际行为 | 级别 |
|
||
|------|------|---------|---------|------|
|
||
| 创建同名 Agent | 相同 name | 警告或拒绝 | ✅ 允许创建，无唯一约束 | P3 |
|
||
| 删除正在使用的 Agent | 当前 active agent | 阻止或警告 | ❌ 直接删除，不检查活跃状态 | P2 |
|
||
| 空名称创建 | name="" | 拒绝 | ❌ 允许，无验证 | P2 |
|
||
| temperature 越界 | 5.0 | 拒绝或 clamp | ❌ 无范围验证 | P2 |
|
||
| 切换 Agent 时流式进行中 | 中途切换 | 取消流再切换 | ❌ 流继续，消息可能追到错误对话 | P2 |
|
||
| 删除后 selectedAgent 引用 | 删除当前选中 | 清空选择 | ❌ conversationStore.currentAgent 可能指向已删除 Agent | P2 |
|
||
| 模板创建 metadata 失败 | updateClone 抛错 | 回滚或提示 | ⚠️ 仅 warn 日志，Agent 已创建但配置不完整 | P2 |
|
||
|
||
### 2.4 状态管理
|
||
|
||
| Store | 状态机完整性 | 持久化 | 竞态风险 |
|
||
|-------|------------|--------|---------|
|
||
| agentStore | ⚠️ 共享 isLoading，无操作级状态 | ❌ 无持久化 | ⚠️ 并发操作共享 isLoading |
|
||
| conversationStore (Agent 相关) | ✅ currentAgent/agentList | ✅ IndexedDB | ⚠️ 切换 Agent 不取消流 |
|
||
|
||
### 2.5 安全与资源
|
||
|
||
| 检查项 | 状态 | 说明 |
|
||
|--------|------|------|
|
||
| agent_id 格式验证 | ✅ | validate_agent_id 使用 UUID 格式 + validate_identifier |
|
||
| agent_import 大小限制 | ✅ | validate_string_length 限制 1MB |
|
||
| API Key 不存储在 Agent 配置 | ✅ | AgentConfig 仅存 env var 名 |
|
||
| 删除级联 | ⚠️ | 依赖 SQLite PRAGMA foreign_keys 启用 |
|
||
|
||
---
|
||
|
||
## 3. 问题清单
|
||
|
||
| ID | 描述 | 文件:行号 | 级别 | 修复建议 | 验证方法 |
|
||
|----|------|----------|------|---------|---------|
|
||
| M2-01 | **[P1] KernelClient createClone 字段丢失** — 仅传 name/description/model 3 字段，丢失 emoji/personality/communicationStyle/notes/nickname/scenarios/workspace 等 7+ 字段 | `kernel-agent.ts:74-97` | **P1** | 扩展 CreateAgentRequest 和 kernel-agent.ts 传递全部字段 | 通过 Kernel 创建 Agent 后检查 SQLite config 列 |
|
||
| M2-02 | **[P1] 两条通路创建逻辑严重不对等** — Gateway 构建完整 TOML manifest，Kernel 仅 3 字段 | `gateway-api.ts:60-106` vs `kernel-agent.ts:74-97` | **P1** | 统一两条通路的字段映射 | 分别用两种模式创建 Agent 对比结果 |
|
||
| M2-03 | AgentInfo 缺 message_count/created_at/updated_at | `kernel-types.ts:22-29` | P2 | 扩展前端 AgentInfo 类型 | 加载 Agent 列表检查字段 |
|
||
| M2-04 | updateClone 缺少人格/工作空间字段 | `kernel-agent.ts:109-134`, `agent.rs:50-61` | P2 | 扩展 AgentUpdateRequest | 更新 Agent 的 emoji/personality 验证生效 |
|
||
| M2-05 | 删除 Agent 不检查是否正在使用 | `agent.rs:143-160` | P2 | 检查活跃 session/流状态 | 删除正在聊天的 Agent |
|
||
| M2-06 | Agent 切换不通知 Kernel defaultAgentId | `conversationStore.ts:249-303` | P2 | 切换时调用 client.setDefaultAgentId() | 切换后发消息检查 agentId |
|
||
| M2-07 | 切换 Agent 不取消进行中的流 | `conversationStore.ts:249-303` | P2 | 切换前检查并 cancelStream | 流式中切换 Agent 验证 |
|
||
| M2-08 | 创建/更新无参数验证（空名/温度范围） | `agent.rs:70-104` | P2 | 添加 name 非空、temperature [0,2]、max_tokens >0 | 传入空名/异常温度 |
|
||
| M2-09 | 删除后 selectedAgent 可能指向已删除 Agent | `agentStore.ts` | P2 | 删除后自动切换到第一个可用 Agent | 删除当前选中 Agent |
|
||
| M2-10 | SQLite 外键级联依赖 PRAGMA foreign_keys | `schema.rs:22-24` | P2 | 确认初始化时执行 PRAGMA foreign_keys = ON | 检查 schema.rs 初始化代码 |
|
||
| M2-11 | 默认 provider/model 前后端不一致 | `kernel-agent.ts:39-43` vs `agent.rs:15-18` | P3 | 统一默认值为 config.rs 中的值 | 不传 provider 检查实际使用 |
|
||
| M2-12 | agentStore 共享 isLoading 无操作级状态 | `agentStore.ts` | P3 | 改为 per-operation loading | 同时触发 load + create |
|
||
| M2-13 | Agent 列表变更不自动同步 conversationStore | `agentStore.ts` | P3 | CRUD 后触发 conversationStore.syncAgents() | 创建 Agent 后检查选择器 |
|
||
| M2-14 | system_prompt 双重持久化可能不一致 | `agentStore.ts:218-235` | P3 | 明确单一数据源 | 分别更新两处检查同步 |
|
||
|
||
---
|
||
|
||
## 4. 改进建议
|
||
|
||
### 短期修复（按优先级）
|
||
|
||
1. **[P1]** 扩展 `kernel-agent.ts` 的 `createClone()` 传递全部字段（对齐 gateway-api.ts）
|
||
2. **[P1]** 扩展 `CreateAgentRequest` struct 支持人格字段
|
||
3. **[P2]** 添加 Agent CRUD 参数验证
|
||
4. **[P2]** Agent 切换时同步 defaultAgentId + 取消流
|
||
|
||
### 长期架构建议
|
||
|
||
- 统一 Kernel 和 Gateway 两条通路的 Agent 创建逻辑
|
||
- 为 agentStore 添加 per-operation 状态机
|
||
- 明确 system_prompt 的单一数据源（AgentConfig vs Identity 文件）
|
||
|
||
---
|
||
|
||
## 5. 健康度评分
|
||
|
||
| 维度 | 评分 | 说明 |
|
||
|------|------|------|
|
||
| 链路完整性 | **65/100** | Kernel 创建/更新通路字段丢失是核心断链 |
|
||
| 参数一致性 | **70/100** | 类型基本匹配但字段覆盖不完整 |
|
||
| 边界处理 | **55/100** | 缺少参数验证、删除不检查活跃状态、切换不取消流 |
|
||
| 状态管理 | **60/100** | 缺操作级状态、跨 Store 同步不完整 |
|
||
| 安全资源 | **85/100** | ID 验证完善，主要风险在级联删除 |
|
||
|
||
**综合健康度: 67/100**
|
||
|
||
两个 P1 级断链（Kernel 创建字段丢失 + 双通路不对等）是此模块的核心问题。修复后预计可提升至 85+。
|