zclaw_openfang/docs/features/audit-v12/M2-agent-clones.md

模块 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+。