# 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` 中添加:
```typescript
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` 中添加
```typescript
interface AgentState {
  id: string;
  status: 'idle' | 'running' | 'error';
  lastActive: Date;
  sessionCount: number;
  currentModel: string;
}
```

#### 2. Agent 监控
在 `plugins/zclaw-ui/index.ts` 中添加
```typescript
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 自动启动
- [ ] 首次启动流程完整
- [ ] 错误有明确指引
- [ ] 配置持久化
- [ ] 应用更新无状态丢失

- [ ] 用户文档完整