zclaw_openfang/docs/plans/sequential-churning-wreath-agent-a730f837627aeb203.md

ZClaw 改进方案:从"前端 UI 演示"升级为"真正的 ZCLAW Runtime 控制界面"

日期: 2026-03-12
状态: 规划中

---

背景分析

当前状态

经过对代码库的深入分析,发现以下关键差距:

1. 分身与 Agent 断层

• 现状: 分身存储在 zclaw-data.json (ZCLAW 自定义格式)
• 问题: 不映射到 ZCLAW 原生 agents.list 配置
• 影响: 聊天时不所有分身共用 main Agent
• 表现: Bootstrap 文件生成了但可能未被 Agent 运行时使用

关键代码位置:

• desktop/src/components/CloneManager.tsx: 分身 CRUD 界面
• desktop/src/store/chatStore.ts: currentAgent 只存前端状态
• plugins/zclaw-ui/index.ts: 分身存储在 zclaw-data.json

2. 设置页是"假状态"

• 现状: 大部分设置只存 localStorage
• 问题: 没有调用 ZCLAW 的 config.get/config.patch/config.apply
• 影响: 用户改了设置而 ZCLAW 运行时行为不变

关键代码位置:

• desktop/src/components/Settings/*.tsx: 所有设置页面
• desktop/src/store/chatStore.ts: currentModel 只存前端状态
• desktop/src/lib/gateway-client.ts: 缺少 config.* RPC 方法

3. 右侧面板数据不真实

• 现状: 部分数据是硬编码默认值
• 问题: 没有显示真实 Agent 的运行时状态
• 影响: 用户看到的是演示数据，- 表现: Bootstrap 文件生成了但可能未被 Agent 运行时使用

---

P0: 最小可行改进 - 让分身真正工作

目标

让分身系统真正映射到 ZCLAW Agent 实例，实现分身隔离（独立 Agent 会话)。

关键任务

1. 实现 Agent 同步机制

• 在 plugins/zclaw-ui/index.ts 中:
  • 添加 zclaw.agents.sync RPC 方法
  • 同步 zclaw-data.json 的分身到 agents.list
  • 为每个分身创建独立 agentDir
• 在 desktop/src/lib/gateway-client.ts 中:
  • 添加 agents.list RPC 方法封装
  • 添加 agent.set RPC 方法封装

2. 修改聊天逻辑

• 在 desktop/src/store/chatStore.ts 中:
  • 添加 currentAgentId 字段
  • 修改 sendMessage 传递 agentId
• 在 desktop/src/components/ChatArea.tsx 中:
  • 聊天时显示当前分身信息

3. Agent 启动流程

• 创建分身时:

  1. 生成 Bootstrap 文件
  2. 同步到 agents.list
  3. 重启 Agent 进程(如果需要)

• 切换分身时:

  1. 加载对应 Agent 的上下文
  2. 切换 agentId

技术挑战

• ZCLAW Agent 进程管理: 隐式依赖 Gateway 的 Agent 启动机制

• 会话隔离: 需要验证 ZCLAW 是否支持 agentId 参数

• 配置同步时机: 何时同步分身配置到 ZCLAW

• 错误处理: Agent 启动失败时的回退策略

验收标准

• 创建分身后能在 ZCLAW 的 agents.list 中看到
• 切换分身后聊天时传递正确的 agentId
• 不同分身的会话完全隔离
• Bootstrap 文件被 Agent 正确加载
• 分身配置修改后 Agent 行为相应变化

---

P1: 设置页 Runtime 化

目标

让设置页真正修改 ZCLAW Runtime 配置。

关键任务

1. GatewayClient 扩展

在 desktop/src/lib/gateway-client.ts 中添加:

async getConfig(path?: string): Promise<any>
async patchConfig(path: string, value: any): Promise<void>
async applyConfig(): Promise<void>

2. 设置页改造

模型与 API:

• 模型选择调用 patchConfig('agents.defaults.model', model)
• 显示当前模型从 getConfig('agents.defaults.model') 获取

MCP 服务:

• 读取: getConfig('mcp')
• 修改: patchConfig('mcp.servers.*')

技能:

• 读取: getConfig('skills')
• 修改: patchConfig('skills.load.extraDirs')

IM 频道:

• 读取: getConfig('channels')
• 修改: patchConfig('channels.*')

工作区:

• 读取: getConfig('agents.defaults.workspace')
• 修改: patchConfig('agents.defaults.workspace')

技术挑战

• 配置路径: ZCLAW 配置是嵌套结构，需要正确处理路径

• 配置验证: 修改前验证配置有效性

• 错误恢复: 配置修改失败时的回滚

• UI 反馈: 配置修改时的加载状态

• 配置缓存: 避免频繁读取配置

验收标准

• 模型选择后聊天时使用新模型

• MCP 开关后工具可用性变化

• 技能添加后 Agent 可调用

• IM 频道配置后能收发消息

• 工作区修改后文件访问范围变化

• 配置修改后重启 Gateway 生效

---

P2: 完整的 Agent 管理系统

目标

实现完整的 Agent 生命周期管理。

关键任务

1. Agent 状态管理

在 desktop/src/store/chatStore.ts 中添加

interface AgentState {
  id: string;
  status: 'idle' | 'running' | 'error';
  lastActive: Date;
  sessionCount: number;
  currentModel: string;
}

2. Agent 监控

在 plugins/zclaw-ui/index.ts 中添加

api.registerGatewayMethod('zclaw.agents.status', ({ respond }) => {
  // 返回所有 Agent 的运行时状态
});

3. 右侧面板增强

在 desktop/src/components/RightPanel.tsx 中

• 显示真实 Agent 状态
• 显示运行时信息(当前任务、 使用的工具等)
• 显示会话历史

技术挑战

• 状态同步: 客户端状态与 Gateway 状态同步
• 性能: 大量 Agent 时的性能
• 错误处理: Agent 状态异常时的 UI 反馈
• 实时更新: 状态变化时的实时推送

验收标准

• Agent 状态实时显示
• 运行时信息准确
• 会话历史可查
• 错误状态有明确提示
• 性能满足要求(100 个 Agent)

---

P3: 产品化封装

目标

提供完整的桌面应用体验。

关键任务

1. Tauri Sidecar 管理

在 desktop/src-tauri/src/gateway.rs 中:

• 管理 Gateway 子进程生命周期
• 自动重启和错误恢复
• 配置管理和持久化

2. 首次启动体验

• 欢迎向导
• Gateway 连接配置
• 默认 Agent 创建
• 工作目录选择

3. 错误诊断

• 连接问题诊断
• 配置错误修复建议
• 日志查看工具

技术挑战

• 进程管理: 跨平台进程管理

• 权限: 文件系统访问权限

• 更新: 应用更新时的状态保持

• 用户体验: 错误时的用户引导

• 文档: 用户文档和帮助

验收标准

• Gateway 自动启动

• 首次启动流程完整

• 错误有明确指引

• 配置持久化

• 应用更新无状态丢失

• 用户文档完整