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
重构所有代码和文档中的项目名称,将OpenFang统一更新为ZCLAW。包括: - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构,移除未使用的模块,并更新相关依赖项。
232 lines
6.4 KiB
Markdown
232 lines
6.4 KiB
Markdown
|
|
# 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 自动启动
|
|
- [ ] 首次启动流程完整
|
|
- [ ] 错误有明确指引
|
|
- [ ] 配置持久化
|
|
- [ ] 应用更新无状态丢失
|
|
|
|
- [ ] 用户文档完整
|