Files
zclaw_openfang/docs/plans/sequential-churning-wreath-agent-a730f837627aeb203.md
iven 0d4fa96b82
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
refactor: 统一项目名称从OpenFang到ZCLAW
重构所有代码和文档中的项目名称,将OpenFang统一更新为ZCLAW。包括:
- 配置文件中的项目名称
- 代码注释和文档引用
- 环境变量和路径
- 类型定义和接口名称
- 测试用例和模拟数据

同时优化部分代码结构,移除未使用的模块,并更新相关依赖项。
2026-03-27 07:36:03 +08:00

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 自动启动
- [ ] 首次启动流程完整
- [ ] 错误有明确指引
- [ ] 配置持久化
- [ ] 应用更新无状态丢失
- [ ] 用户文档完整