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
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
480 lines
9.8 KiB
Markdown
480 lines
9.8 KiB
Markdown
# ZCLAW 功能 -> ZCLAW 子系统落地路线图
|
||
|
||
**日期**: 2026-03-12
|
||
**依据**: `docs/zclaw-deep-dive.md`
|
||
**目标**: 把 ZCLAW 从“像 ZCLAW 的桌面 UI”推进为“真正围绕 ZCLAW Runtime 的 Tauri 封装层”。
|
||
|
||
---
|
||
|
||
## 一、总原则
|
||
|
||
后续所有功能都按同一条映射链设计与验收：
|
||
|
||
> ZCLAW 功能 -> ZCLAW 子系统 -> 真实配置/文件/路由/运行时行为 -> 前端展示与操作
|
||
|
||
如果一个功能改完后：
|
||
|
||
- 没有改变 ZCLAW 的真实配置
|
||
- 没有改变 Agent 的真实身份/工作区/边界
|
||
- 没有改变 Channel / Heartbeat / Skills / MCP / Gateway 的真实行为
|
||
|
||
那它仍然只是 UI 占位，不算真正落地。
|
||
|
||
---
|
||
|
||
## 二、路线图总览
|
||
|
||
| 阶段 | 主题 | 目标 | 结果 |
|
||
|---|---|---|---|
|
||
| **R0** | Gateway 协议与连接 | 让 ZCLAW 成为一个可稳定连上 ZCLAW Gateway 的控制端 | `连接/重连/状态/错误` 可用 |
|
||
| **R1** | Agent 模型收敛 | 把 `分身/快速配置/右侧 Agent 面板` 收敛成真实 Agent Profile | `Clone -> Agent Profile` |
|
||
| **R2** | 配置控制面板化 | 把设置页从“本地状态”收敛为 ZCLAW 配置编辑器 | `config/get/patch/apply` |
|
||
| **R3** | Workspace / Bootstrap 文件 | 让 Agent 身份、人格、用户上下文落到 workspace 文件 | `IDENTITY/SOUL/USER/AGENTS` |
|
||
| **R4** | Channels / Bindings | 让 IM 页面真正管理渠道输入与路由 | `channels + bindings` |
|
||
| **R5** | Heartbeat / 定时任务 | 把“定时任务页”升级为 Heartbeat 控制台 | `heartbeat + HEARTBEAT.md` |
|
||
| **R6** | Skills / MCP | 让技能与工具能力成为真实可管理能力面 | `skills + mcp` |
|
||
| **R7** | 产品化壳层 | 完成 Tauri sidecar、安装、诊断、迁移与回归体系 | 可交付桌面产品 |
|
||
|
||
---
|
||
|
||
## 三、功能 -> ZCLAW 子系统映射
|
||
|
||
## 1. Gateway 连接
|
||
|
||
### 对应子系统
|
||
|
||
- `Gateway WebSocket Protocol`
|
||
- `device auth`
|
||
- `pairing`
|
||
- `scopes`
|
||
- `auth.token / auth.deviceToken`
|
||
|
||
### ZCLAW 当前功能
|
||
|
||
- 设置页里的 Gateway URL
|
||
- 右侧连接状态卡片
|
||
- 自动连接逻辑
|
||
|
||
### 应落地到
|
||
|
||
- `desktop/src/lib/gateway-client.ts`
|
||
- 协议握手适配
|
||
- 正确错误码展示
|
||
- 后续可补 `pairing required / token drift / device auth` 诊断提示
|
||
|
||
### 验收标准
|
||
|
||
- 能稳定连接本地 ZCLAW Gateway
|
||
- 状态能从 `disconnected -> connecting -> handshaking -> connected`
|
||
- 错误能区分：
|
||
- token 问题
|
||
- device auth 问题
|
||
- mode/client id 问题
|
||
- pairing 问题
|
||
|
||
### 优先级
|
||
|
||
- **最高**
|
||
|
||
---
|
||
|
||
## 2. 分身 / 快速配置 / 右侧 Agent 区域
|
||
|
||
### 对应子系统
|
||
|
||
- `agents.list[]`
|
||
- `workspace / agentDir`
|
||
- `IDENTITY.md`
|
||
- `SOUL.md`
|
||
- `USER.md`
|
||
- `AGENTS.md`
|
||
|
||
### ZCLAW 当前功能
|
||
|
||
- 左侧分身列表
|
||
- 快速配置弹层
|
||
- 右侧 `Agent` 标签页
|
||
|
||
### 正确语义
|
||
|
||
- **分身 = Agent 实例**
|
||
- **快速配置 = 新建 / 更新 Agent Profile**
|
||
- **右侧 Agent 区域 = 当前 Agent 的身份与上下文可视化**
|
||
|
||
### 应落地到
|
||
|
||
- 插件层：`zclaw-ui` 中的 Agent Profile RPC
|
||
- 数据层：从 `CloneConfig` 升级为 `AgentProfile`
|
||
- 前端层：`CloneManager / RightPanel / chatStore`
|
||
- 工作区层：为每个 Agent 生成/更新 bootstrap 文件
|
||
|
||
### 验收标准
|
||
|
||
- 创建 Agent 后，左侧、聊天头部、右侧 Agent 面板一致
|
||
- Agent 的身份字段有统一来源
|
||
- 不再依赖单纯前端本地 fallback agent
|
||
|
||
### 优先级
|
||
|
||
- **最高**
|
||
|
||
---
|
||
|
||
## 3. 工作区设置
|
||
|
||
### 对应子系统
|
||
|
||
- `agents.defaults.workspace`
|
||
- `agents.list[].workspace`
|
||
- `sandbox`
|
||
- `tools allow/deny`
|
||
- bootstrap files
|
||
|
||
### ZCLAW 当前功能
|
||
|
||
- 工作目录
|
||
- 文件限制
|
||
- 自动保存上下文
|
||
- 文件监听
|
||
|
||
### 正确语义
|
||
|
||
工作区不是 UI 里的一个路径输入框，而是：
|
||
|
||
- Agent 的上下文根目录
|
||
- bootstrap 文件所在位置
|
||
- 文件访问边界
|
||
- 工具执行边界的基础
|
||
|
||
### 应落地到
|
||
|
||
- `config.patch/apply`
|
||
- workspace info RPC
|
||
- Agent 级与 defaults 级区分
|
||
|
||
### 验收标准
|
||
|
||
- 改动工作区后，ZCLAW 配置能真实更新
|
||
- 右侧 Agent 面板能展示当前 Agent 的工作目录与边界
|
||
|
||
### 优先级
|
||
|
||
- **高**
|
||
|
||
---
|
||
|
||
## 4. IM 频道页
|
||
|
||
### 对应子系统
|
||
|
||
- `channels.*`
|
||
- `channels.<channel>.accounts`
|
||
- `bindings`
|
||
- mention / allowlist / route target
|
||
|
||
### 正确语义
|
||
|
||
IM 页不是“集成列表”，而是：
|
||
|
||
- 管理消息从哪里进入系统
|
||
- 管理这些消息如何路由到哪个 Agent
|
||
|
||
### 应落地到
|
||
|
||
- `channels.list/status` + 插件探测
|
||
- 后续补 `bindings` 可视化
|
||
- 账号级与渠道级配置区分
|
||
|
||
### 验收标准
|
||
|
||
- 至少能看清当前有哪些 channel/account
|
||
- 至少能表达“这个输入源会进入哪个 Agent”
|
||
|
||
### 优先级
|
||
|
||
- **高**
|
||
|
||
---
|
||
|
||
## 5. 定时任务页
|
||
|
||
### 对应子系统
|
||
|
||
- `agents.defaults.heartbeat`
|
||
- `agents.list[].heartbeat`
|
||
- `HEARTBEAT.md`
|
||
|
||
### 正确语义
|
||
|
||
不是单纯 cron 列表，而是：
|
||
|
||
- 哪些 Agent 会被定期唤醒
|
||
- 唤醒后看什么
|
||
- 没事时如何 ack
|
||
- 结果发去哪里
|
||
|
||
### 应落地到
|
||
|
||
- `heartbeat.tasks` 读取
|
||
- heartbeat 配置编辑
|
||
- `HEARTBEAT.md` 管理入口
|
||
|
||
### 验收标准
|
||
|
||
- UI 中明确 Heartbeat 是 Agent turn，不是普通定时脚本
|
||
|
||
### 优先级
|
||
|
||
- **中高**
|
||
|
||
---
|
||
|
||
## 6. 技能页
|
||
|
||
### 对应子系统
|
||
|
||
- `skills`
|
||
- `SKILL.md`
|
||
- extra skill dirs
|
||
|
||
### 正确语义
|
||
|
||
技能页的目标是：
|
||
|
||
- 告诉用户 Agent 会做什么
|
||
- 告诉用户这些能力从哪些 skill 目录和手册里来
|
||
|
||
### 应落地到
|
||
|
||
- 真实技能目录扫描
|
||
- `zclaw skills list/info/check` 对应能力
|
||
- extraDirs 与当前 Agent 能力面关联
|
||
|
||
### 验收标准
|
||
|
||
- 不只是维护一个字符串数组
|
||
- 能看到技能来源与状态
|
||
|
||
### 优先级
|
||
|
||
- **中高**
|
||
|
||
---
|
||
|
||
## 7. MCP 服务页
|
||
|
||
### 对应子系统
|
||
|
||
- MCP / RPC adapters / 外部工具能力面
|
||
|
||
### 正确语义
|
||
|
||
不是前端模板收藏，而是：
|
||
|
||
- Agent 当前能调用哪些外部能力
|
||
- 这些能力如何被配置、启用与管理
|
||
|
||
### 优先级
|
||
|
||
- **中高**
|
||
|
||
---
|
||
|
||
## 8. 用量统计 / 会话 / 系统信息
|
||
|
||
### 对应子系统
|
||
|
||
- sessions
|
||
- usage
|
||
- plugin status
|
||
- gateway health
|
||
|
||
### 目标
|
||
|
||
- 提供可观察性
|
||
- 让用户知道 Agent 是否真的在运行、运行了多少、谁在消耗成本
|
||
|
||
### 优先级
|
||
|
||
- **中**
|
||
|
||
---
|
||
|
||
## 四、阶段化执行方案
|
||
|
||
## Phase A：把“分身系统”收敛成 Agent Profile 层
|
||
|
||
### 目标
|
||
|
||
先把最接近用户感知的核心链路做对：
|
||
|
||
- 左侧分身
|
||
- 快速配置
|
||
- 右侧 Agent 面板
|
||
- 聊天头部 Agent 名称
|
||
|
||
### 具体动作
|
||
|
||
1. 引入统一 `AgentProfile` 类型
|
||
2. 插件层 `CloneConfig` 升级为更完整 profile
|
||
3. store 层把 `clones` 视为 `agentProfiles`
|
||
4. `chatStore.currentAgent` 不再自带孤立 fallback 逻辑
|
||
5. quick config 默认值与 workspace/profile 字段打通
|
||
|
||
### 阶段验收
|
||
|
||
- 创建出来的 Agent，在所有 UI 位置是一致实体
|
||
- 刷新后仍能从持久化数据恢复
|
||
|
||
---
|
||
|
||
## Phase B：让 Quick Config 不再只是 JSON 临时缓存
|
||
|
||
### 目标
|
||
|
||
把 quick config 从：
|
||
|
||
- `zclaw.config.quick` 的一份附加偏好
|
||
|
||
收敛到：
|
||
|
||
- Agent 创建向导 / 最近一次 Agent 草稿
|
||
|
||
### 具体动作
|
||
|
||
1. 区分 `quickConfigDraft` 与 `agentProfiles`
|
||
2. 保存快速配置时，不再误导成“系统总配置”
|
||
3. 后续为 bootstrap 文件生成预留字段映射
|
||
|
||
### 阶段验收
|
||
|
||
- quick config 有清晰职责
|
||
- 不和真实 Agent Profile 混淆
|
||
|
||
---
|
||
|
||
## Phase C：把 Agent Profile 继续落到 workspace/bootstrap 文件
|
||
|
||
### 目标
|
||
|
||
让 Agent 的身份不是只活在 `zclaw-data.json` 里。
|
||
|
||
### 具体动作
|
||
|
||
1. 为 Agent 生成独立 workspace 或 profile 目录
|
||
2. 写入/更新：
|
||
- `IDENTITY.md`
|
||
- `USER.md`
|
||
- `SOUL.md`
|
||
- `AGENTS.md`
|
||
3. 让右侧 Agent 面板字段与这些文件的内容有映射关系
|
||
|
||
### 阶段验收
|
||
|
||
- Agent 真正拥有可审计、可读、可迁移的文本身份
|
||
|
||
---
|
||
|
||
## Phase D：设置页全面收敛为 ZCLAW 配置控制台
|
||
|
||
### 目标
|
||
|
||
把现有 Settings 页从 local state 管理升级为：
|
||
|
||
- ZCLAW config 编辑器
|
||
- Gateway runtime 控制台
|
||
|
||
### 关键动作
|
||
|
||
- 优先用 `config.get / patch / apply`
|
||
- 区分：
|
||
- defaults
|
||
- per-agent
|
||
- per-channel/account
|
||
|
||
---
|
||
|
||
## 五、当前代码库的立即修正项
|
||
|
||
## 1. 数据模型不一致
|
||
|
||
当前前端 `Clone` 已经包含：
|
||
|
||
- `workspaceDir`
|
||
- `restrictFiles`
|
||
- `privacyOptIn`
|
||
- `userName`
|
||
- `userRole`
|
||
|
||
但插件层 `CloneConfig` 仍未完整持久化这些字段。
|
||
|
||
### 立即动作
|
||
|
||
- 插件层升级 `CloneConfig`
|
||
- `create/update/list` 全链路透传这些字段
|
||
|
||
## 2. `chatStore` 与 `gatewayStore` 双重 Agent 模型并存
|
||
|
||
当前问题：
|
||
|
||
- `chatStore.agents/currentAgent` 仍是 UI 型实体
|
||
- `gatewayStore.clones` 是更接近真实 profile 的实体
|
||
|
||
### 立即动作
|
||
|
||
- 让 `currentAgent` 选择依赖真实 profile id
|
||
- 补一个从 profile 派生 chat agent 的适配层
|
||
|
||
## 3. quickConfig 语义仍不清晰
|
||
|
||
### 立即动作
|
||
|
||
- 在代码与文档中明确：
|
||
- 它是草稿 / 最近一次快速配置输入
|
||
- 它不是 Agent 全量真源
|
||
|
||
---
|
||
|
||
## 六、下一步开发顺序
|
||
|
||
### 立即执行
|
||
|
||
1. **修 Agent Profile 数据模型一致性**
|
||
2. **收敛 Quick Config 与 Agent Profile 的职责边界**
|
||
3. **让右侧 Agent 面板只读真实 profile 数据**
|
||
|
||
### 之后执行
|
||
|
||
4. Gateway 协议继续收口
|
||
5. Workspace / bootstrap 文件生成
|
||
6. IM / Heartbeat / Skills / MCP 分页逐个真实化
|
||
|
||
---
|
||
|
||
## 七、完成定义
|
||
|
||
当下面这些条件满足时，才能认为 ZCLAW 已经真正开始 ZCLAW 化：
|
||
|
||
- 分身不再只是 UI 列表，而是 Agent 实体
|
||
- 快速配置不再只是表单，而是 Agent 创建向导
|
||
- 右侧 Agent 面板展示真实 Agent Profile
|
||
- 设置页改的是 ZCLAW 真实运行配置
|
||
- Heartbeat / Channels / Skills / MCP 不再是占位页
|
||
- Gateway 连接协议稳定可诊断
|
||
|
||
---
|
||
|
||
## 八、本轮执行建议
|
||
|
||
本轮优先做：
|
||
|
||
- **Agent Profile 统一模型**
|
||
- **插件层持久化字段补齐**
|
||
- **前端选择/展示逻辑收敛**
|
||
|
||
原因：
|
||
|
||
- 这条链最贴近用户感知
|
||
- 能直接验证 `zclaw-deep-dive.md` 的核心判断
|
||
- 也是后续 workspace/bootstrap/channel/binding 的前置基础
|