Add unit tests for channel utilities and configure testing environment
- Created a new test file `channels.test.ts` to cover utilities related to channel configurations and targets. - Implemented tests for normalizing and grouping selected channels by type, as well as building channel targets from account data and cron history. - Mocked necessary dependencies to isolate tests and ensure accurate results. - Updated `vite.config.ts` to set up the testing environment with jsdom and enable global variables for tests.
This commit is contained in:
duanshuwen
981
docs/ClawX-Channels-Migration-Plan.md
Normal file
981
docs/ClawX-Channels-Migration-Plan.md
Normal file
@@ -0,0 +1,981 @@
|
||||
# ClawX 消息频道功能迁移到 zn-ai 的开发计划
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
这次迁移的目标不是把 `zn-ai` 当前的 `/channels` 页面做得“更好看”，而是把它从“频道/账号归属管理页”升级成接近 `ClawX` 的完整消息频道控制台。
|
||||
|
||||
期望对齐的能力边界如下：
|
||||
|
||||
1. 渲染层页面结构对齐 `ClawX`
|
||||
- 顶部标题区
|
||||
- `Refresh`
|
||||
- Gateway 健康横幅与 diagnostics
|
||||
- 已配置频道列表
|
||||
- 支持的频道列表
|
||||
- 频道配置弹窗
|
||||
- 删除确认与收敛刷新
|
||||
2. 主进程 / Host API 对齐 `ClawX`
|
||||
- `/api/channels/accounts`
|
||||
- `/api/channels/targets`
|
||||
- `/api/channels/config`
|
||||
- `/api/channels/default-account`
|
||||
- `/api/channels/binding`
|
||||
- `/api/channels/config/enabled`
|
||||
- `/api/channels/credentials/validate`
|
||||
- QR 登录相关接口
|
||||
3. 运行时链路对齐 `ClawX`
|
||||
- 多账号配置
|
||||
- 默认账号切换
|
||||
- gateway reload / restart 策略
|
||||
- runtime health summary
|
||||
- diagnostics snapshot
|
||||
4. 测试基线对齐 `ClawX`
|
||||
- 单测覆盖配置、账号 ID、状态推断
|
||||
- E2E 覆盖绑定、诊断、账号编辑与回归场景
|
||||
|
||||
一句话总结：
|
||||
|
||||
- `zn-ai` 需要从“只会改归属”升级为“可配置、可诊断、可验证、可收敛”的消息频道域。
|
||||
|
||||
## 2. ClawX 基线结论
|
||||
|
||||
## 2.1 页面职责不是“绑定页”，而是“频道控制台”
|
||||
|
||||
`ClawX/src/pages/Channels/index.tsx` 承担的不是单一绑定入口，而是完整控制台：
|
||||
|
||||
- 管理已配置频道与账号
|
||||
- 展示支持的频道目录
|
||||
- 打开配置弹窗
|
||||
- 修改账号到 Agent 的绑定
|
||||
- 删除账号或整条频道配置
|
||||
- 展示 Gateway 健康状态
|
||||
- 复制 / 展开 diagnostics
|
||||
- 在 gateway 重启或 channel-status 事件后做收敛刷新
|
||||
|
||||
这决定了 `zn-ai` 不能继续停留在“表单 + 下拉框”的结构。
|
||||
|
||||
## 2.2 渲染层 IA
|
||||
|
||||
ClawX 的 UI 信息架构可以概括成三层：
|
||||
|
||||
1. 页面层
|
||||
- 标题、副标题、刷新按钮
|
||||
2. 运行态层
|
||||
- gateway warning
|
||||
- gateway degraded / unresponsive banner
|
||||
- diagnostics 操作与展开区
|
||||
3. 资源层
|
||||
- `Configured Channels`
|
||||
- `Supported Channels`
|
||||
- `ChannelConfigModal`
|
||||
|
||||
其中两个关键特征必须保留：
|
||||
|
||||
- “已配置频道”和“支持的频道”是并列区块，不是同一张表的两种状态。
|
||||
- `ChannelConfigModal` 是核心交互入口，不是可有可无的附属表单。
|
||||
|
||||
## 2.3 关键交互流程
|
||||
|
||||
ClawX 的前端交互主线如下：
|
||||
|
||||
1. 页面初次加载时并行拉取 `/api/channels/accounts` 与 `/api/agents`
|
||||
2. `Refresh` 触发 `probe=true` 的强探测拉取
|
||||
3. `gateway:channel-status` 事件到达后节流刷新
|
||||
4. Gateway 状态从非 `running` 变为 `running` 后触发一轮收敛刷新
|
||||
5. 点击“添加账号”后根据频道类型决定是否生成默认 `accountId`
|
||||
6. 配置弹窗内根据 `connectionType` 分为：
|
||||
- `token`
|
||||
- `qr`
|
||||
- `oauth/webhook` 扩展位
|
||||
7. 保存配置后不是立即认为状态稳定，而是继续做延迟回拉
|
||||
8. 删除配置后先本地移除，再补一次延迟拉取，避免旧状态回刷
|
||||
|
||||
这说明 `zn-ai` 迁移时不能只做 API 调用本身，还要迁移“刷新与收敛策略”。
|
||||
|
||||
## 2.4 前端状态模型
|
||||
|
||||
ClawX 页面目前虽然写在单文件里，但隐含了一套很清晰的状态模型：
|
||||
|
||||
- `channelGroups`
|
||||
- `agents`
|
||||
- `gatewayHealth`
|
||||
- `diagnosticsSnapshot`
|
||||
- `selectedChannelType`
|
||||
- `selectedAccountId`
|
||||
- `allowExistingConfig`
|
||||
- `allowEditAccountId`
|
||||
- `existingAccountIds`
|
||||
- `initialConfigValues`
|
||||
- `deleteTarget`
|
||||
- `fetchInFlight`
|
||||
- `queuedFetchOptions`
|
||||
- `convergenceRefreshTimers`
|
||||
|
||||
迁移到 `zn-ai` 时，建议不要继续把这些状态直接堆在页面组件里，而要拆成：
|
||||
|
||||
- `channelsApi`
|
||||
- `useChannelsPageController`
|
||||
- `ChannelConfigModal`
|
||||
- `ChannelDiagnosticsPanel`
|
||||
- `ChannelGroupCard`
|
||||
|
||||
## 2.5 主进程 API 面
|
||||
|
||||
ClawX 的 `electron/api/routes/channels.ts` 是一个“厚路由”，负责：
|
||||
|
||||
- 构建频道账号视图
|
||||
- accountId canonical 校验与 legacy 兼容
|
||||
- 默认账号切换
|
||||
- binding 写入与清理
|
||||
- config 读写
|
||||
- credentials validate
|
||||
- channel enabled 切换
|
||||
- WeChat / WhatsApp 登录流程
|
||||
- target 目录发现
|
||||
- gateway reload / restart 调度
|
||||
|
||||
也就是说，消息频道域在 ClawX 中是“本地 Host API 优先”的能力，而不是依赖远端 API 的薄代理。
|
||||
|
||||
## 2.6 配置持久化模型
|
||||
|
||||
ClawX 的配置核心语义不是“频道只有一条 token”，而是：
|
||||
|
||||
- 一个频道类型可有多个账号
|
||||
- `defaultAccount` 是路由与展示的重要字段
|
||||
- 普通频道使用 `accounts.<accountId>` 多账号结构
|
||||
- 某些 strict-schema channel 仍需扁平写法
|
||||
- 默认账号配置会镜像到 channel 顶层
|
||||
- 旧 flat 结构仍然兼容
|
||||
- 绑定关系与频道配置共享同一份配置语义
|
||||
|
||||
这对 `zn-ai` 的启示是：
|
||||
|
||||
- 需要先定义消息频道的持久化模型，再谈 UI。
|
||||
- 如果只补页面而不补多账号配置模型，后面会反复返工。
|
||||
|
||||
## 2.7 Gateway 与 Diagnostics
|
||||
|
||||
ClawX 的运行态处理有三个关键点：
|
||||
|
||||
1. `channels.status` 不等于“纯连接态”
|
||||
- 会结合 `running`
|
||||
- `lastError`
|
||||
- recent activity
|
||||
- probe 结果
|
||||
2. 并非所有 channel save 都能通过热 reload 收敛
|
||||
- 很多频道命中 `FORCE_RESTART_CHANNELS`
|
||||
3. degraded != stopped
|
||||
- gateway 仍在运行时也可能因为 health timeout 被标成 degraded
|
||||
|
||||
迁移到 `zn-ai` 时，Gateway 状态与频道状态不要混为一谈。
|
||||
|
||||
## 2.8 测试基线
|
||||
|
||||
ClawX 的消息频道测试不是只测接口返回，而是测整条用户链路：
|
||||
|
||||
- unit
|
||||
- channel routes
|
||||
- channel config
|
||||
- channel status
|
||||
- channels page
|
||||
- e2e
|
||||
- binding regression
|
||||
- account ID validation
|
||||
- account persistence
|
||||
- health diagnostics
|
||||
|
||||
这意味着 `zn-ai` 迁移计划必须从一开始就带测试分工，不能把测试留到最后补。
|
||||
|
||||
## 3. zn-ai 当前现状
|
||||
|
||||
## 3.1 已有能力
|
||||
|
||||
`zn-ai` 当前已经具备以下基础：
|
||||
|
||||
1. 独立 `/channels` 路由与侧边栏入口
|
||||
2. 频道页可拉取 `/api/channels/accounts`
|
||||
3. 频道页已支持：
|
||||
- 频道级归属
|
||||
- 账号级归属
|
||||
4. 本地已有：
|
||||
- `/api/channels/accounts`
|
||||
- `/api/channels/targets`
|
||||
- `/api/channels/binding`
|
||||
5. `electron/utils/channels.ts` 已能做：
|
||||
- selected channel 归一化
|
||||
- channel/account 分组
|
||||
- target 候选构建
|
||||
- 与 Cron 历史目标复用
|
||||
6. `agentsStore` 已保存：
|
||||
- `channelOwners`
|
||||
- `channelAccountOwners`
|
||||
7. Agents 页已经把 Channels 视为归属写入口
|
||||
|
||||
## 3.2 当前最大缺口
|
||||
|
||||
相对于 ClawX，`zn-ai` 目前缺少的不是某一个按钮，而是整个消息频道域的“控制面”：
|
||||
|
||||
1. 没有 `supported channels` 目录区
|
||||
2. 没有 `ChannelConfigModal`
|
||||
3. 没有账号新增 / 编辑 / 删除链路
|
||||
4. 没有默认账号切换
|
||||
5. 没有 channel enabled / disabled 语义
|
||||
6. 没有 credentials validate
|
||||
7. 没有 plugin install / QR login 流程
|
||||
8. 没有 Gateway 健康横幅与 diagnostics
|
||||
9. 没有 ClawX 那套收敛刷新机制
|
||||
10. `/api/channels/targets` 仍优先走 upstream，而不是本地闭环
|
||||
|
||||
因此当前 `zn-ai/src/pages/Channels/index.tsx` 更像“归属控制页”，而不是“消息频道控制台”。
|
||||
|
||||
## 3.3 可复用资产
|
||||
|
||||
迁移时不需要全部推倒重来，以下内容建议保留并扩展：
|
||||
|
||||
- `zn-ai/src/pages/Channels/index.tsx`
|
||||
- 现有页面容器
|
||||
- refresh / error / feedback 壳
|
||||
- `zn-ai/electron/api/routes/channels.ts`
|
||||
- 现有 binding 与 catalog 路由骨架
|
||||
- `zn-ai/electron/utils/channels.ts`
|
||||
- 目录归一化
|
||||
- target 候选生成
|
||||
- `zn-ai/electron/utils/agent-config.ts`
|
||||
- `channelOwners`
|
||||
- `channelAccountOwners`
|
||||
- `zn-ai/src/stores/agents.ts`
|
||||
- runtime changed 刷新链路
|
||||
- `zn-ai` 现有 router / sidebar / i18n 基础
|
||||
|
||||
## 4. 迁移原则
|
||||
|
||||
## 4.1 功能对齐 ClawX，存储实现适配 zn-ai
|
||||
|
||||
不建议机械复制 ClawX 的 `~/.openclaw/openclaw.json` 存储方式。
|
||||
|
||||
更适合 `zn-ai` 的方式是：
|
||||
|
||||
1. 交互、API 语义、运行态策略对齐 ClawX
|
||||
2. 底层存储适配 `zn-ai` 当前 `userData` 模式
|
||||
3. 需要兼容 OpenClaw runtime 的字段时，优先采用兼容 schema
|
||||
|
||||
建议方案：
|
||||
|
||||
- 新增 `channels.json` 作为频道配置真相源
|
||||
- `agents.json` 继续保存 Agent 域信息
|
||||
- Phase 1 先保留 `channelOwners` / `channelAccountOwners` 在 `agents.json`
|
||||
- Phase 3 再评估是否合并成统一 `runtime-config.json`
|
||||
|
||||
这样可以先拿到功能对齐，再决定是否做配置域收敛。
|
||||
|
||||
## 4.2 Host API 以本地优先为原则
|
||||
|
||||
消息频道迁移完成后，`zn-ai` 不应该继续把关键频道能力优先转发到 upstream。
|
||||
|
||||
最低要求：
|
||||
|
||||
- `/api/channels/accounts` 本地完成
|
||||
- `/api/channels/targets` 本地完成
|
||||
- `/api/channels/config*` 本地完成
|
||||
- diagnostics 本地完成
|
||||
|
||||
否则 UI 与 runtime 的一致性会很差。
|
||||
|
||||
## 4.3 维持页面职责边界
|
||||
|
||||
迁移后依然保持：
|
||||
|
||||
- `Agents`
|
||||
- 展示摘要
|
||||
- 提供跳转入口
|
||||
- `Channels`
|
||||
- channel/account 配置与绑定唯一写入口
|
||||
- `Cron`
|
||||
- 消费 channel/account/target 目录
|
||||
|
||||
不要把 Channels 的写操作再反向塞回 Agents 页。
|
||||
|
||||
## 5. 推荐的目标文件映射
|
||||
|
||||
| ClawX 参考 | zn-ai 目标 |
|
||||
| --- | --- |
|
||||
| `src/pages/Channels/index.tsx` | `src/pages/Channels/index.tsx` 扩展为控制台 |
|
||||
| `src/components/channels/ChannelConfigModal.tsx` | 新增 `src/components/channels/ChannelConfigModal.tsx` |
|
||||
| `src/types/channel.ts` | 新增 `src/lib/channel-meta.ts` 或扩展 `src/lib/channel-types.ts` |
|
||||
| `electron/api/routes/channels.ts` | 扩展 `electron/api/routes/channels.ts` |
|
||||
| `electron/utils/channel-config.ts` | 新增 `electron/utils/channel-config.ts` |
|
||||
| `electron/utils/channel-status.ts` | 新增 `electron/utils/channel-status.ts` |
|
||||
| `electron/utils/wechat-login.ts` / `whatsapp-login.ts` | 新增 `electron/utils/channel-integrations/*` |
|
||||
| `electron/utils/plugin-install.ts` | 新增 `electron/utils/channel-plugin-install.ts` |
|
||||
| `tests/unit/channels-page.test.tsx` | 新增 `tests/unit/channels-page.test.tsx` |
|
||||
| `tests/e2e/channels-*.spec.ts` | 新增 `tests/e2e/channels-*.spec.ts` |
|
||||
|
||||
## 6. 分阶段迁移计划
|
||||
|
||||
## Phase 0：模型冻结与接口清单
|
||||
|
||||
目标：
|
||||
|
||||
- 先冻结频道域模型，避免 UI 和后端分头实现后再返工。
|
||||
|
||||
交付：
|
||||
|
||||
1. 设计 `channels.json` 结构
|
||||
- channel type
|
||||
- accounts
|
||||
- defaultAccountId
|
||||
- enabled
|
||||
- metadata
|
||||
2. 明确 binding 真相源暂时仍在 `agents.json`
|
||||
3. 明确 channel meta schema
|
||||
- `name`
|
||||
- `description`
|
||||
- `connectionType`
|
||||
- `configFields`
|
||||
- `instructions`
|
||||
- `docsUrl`
|
||||
- `isPlugin`
|
||||
4. 列出本地 Host API 终态清单
|
||||
|
||||
完成标准：
|
||||
|
||||
- 频道配置模型定稿
|
||||
- route 清单定稿
|
||||
- 前后端字段命名定稿
|
||||
|
||||
## Phase 1：后端基础设施对齐
|
||||
|
||||
目标：
|
||||
|
||||
- 先补齐本地配置读写与目录构建，让前端有可依赖的数据面。
|
||||
|
||||
交付：
|
||||
|
||||
1. 新增 `electron/utils/channel-config.ts`
|
||||
2. 扩展 `electron/api/routes/channels.ts`
|
||||
- `GET /api/channels/accounts`
|
||||
- `GET /api/channels/config/:type`
|
||||
- `POST /api/channels/config`
|
||||
- `DELETE /api/channels/config/:type`
|
||||
- `PUT /api/channels/default-account`
|
||||
- `PUT /api/channels/config/enabled`
|
||||
3. 将 `/api/channels/targets` 收回本地优先
|
||||
4. 让 `accounts` 视图同时拼接：
|
||||
- channel config
|
||||
- agent binding
|
||||
- runtime snapshot
|
||||
|
||||
完成标准：
|
||||
|
||||
- `zn-ai` 本地已能维护多账号频道配置
|
||||
- 默认账号切换可用
|
||||
- 无需 upstream 也能拿到 targets
|
||||
|
||||
## Phase 2：运行时与诊断链路对齐
|
||||
|
||||
目标：
|
||||
|
||||
- 把 ClawX 的 runtime 行为补进来，而不是只有配置文件。
|
||||
|
||||
交付：
|
||||
|
||||
1. 新增 `electron/utils/channel-status.ts`
|
||||
2. 增加 credentials validate
|
||||
3. 增加 diagnostics snapshot 与 gateway health summary
|
||||
4. 增加 gateway reload / restart 策略
|
||||
5. 引入 QR / plugin channel 的集成层
|
||||
- WeChat
|
||||
- WhatsApp
|
||||
- 其他 plugin channel 预留
|
||||
6. 在 runtime changed 里补齐：
|
||||
- `channels`
|
||||
- `channel-targets`
|
||||
- `agents`
|
||||
|
||||
完成标准：
|
||||
|
||||
- 配置保存后能正确触发 reload / restart
|
||||
- 页面可感知 degraded / unresponsive
|
||||
- diagnostics 可复制 / 展开
|
||||
|
||||
## Phase 3：前端页面与弹窗对齐
|
||||
|
||||
目标：
|
||||
|
||||
- 把 `zn-ai` 的 `/channels` 从绑定页升级成控制台。
|
||||
|
||||
交付：
|
||||
|
||||
1. 重构 `src/pages/Channels/index.tsx`
|
||||
- 标题区
|
||||
- Refresh
|
||||
- 健康横幅
|
||||
- diagnostics 面板
|
||||
- configured groups
|
||||
- supported channels
|
||||
2. 新增 `src/components/channels/ChannelConfigModal.tsx`
|
||||
- 类型选择
|
||||
- token 配置
|
||||
- QR 流程
|
||||
- accountId 编辑与校验
|
||||
- 预加载已有配置
|
||||
3. 引入前端 channel meta schema
|
||||
4. 引入收敛刷新策略
|
||||
- `gateway:channel-status`
|
||||
- gateway running 过渡
|
||||
- 删除后延迟刷新
|
||||
5. 补消息频道相关 i18n 文案
|
||||
|
||||
完成标准：
|
||||
|
||||
- 视觉结构与 ClawX 接近
|
||||
- 新增 / 编辑 / 删除 / 绑定 / 刷新 / 诊断链路闭环
|
||||
|
||||
## Phase 4：回归测试与联调收口
|
||||
|
||||
目标：
|
||||
|
||||
- 在 parity 接近完成后补齐防回归能力。
|
||||
|
||||
交付：
|
||||
|
||||
1. unit tests
|
||||
- channel routes
|
||||
- channel config
|
||||
- channel status
|
||||
- channels page
|
||||
2. e2e tests
|
||||
- 新增账号默认不自动绑定
|
||||
- 非 canonical accountId 被拦截
|
||||
- 编辑已有账号保持配置值
|
||||
- diagnostics 复制 / 展开 / restart
|
||||
3. 更新迁移文档与 smoke checklist
|
||||
|
||||
完成标准：
|
||||
|
||||
- 关键回归路径有自动化覆盖
|
||||
- 频道页不再依赖人工回归
|
||||
|
||||
## 7. Sub-agent 数量估算与分工建议
|
||||
|
||||
## 7.1 分析阶段建议：3 个 sub-agent
|
||||
|
||||
分析阶段建议 3 个 sub-agent，正好对应这次拆法：
|
||||
|
||||
1. `Renderer Explorer`
|
||||
- 负责 `ClawX` 页面 IA、弹窗、事件收敛与前端测试
|
||||
2. `Main Process Explorer`
|
||||
- 负责 `ClawX` routes、config、gateway、diagnostics、QR / plugin 流程
|
||||
3. `Gap Explorer`
|
||||
- 负责 `zn-ai` 现状、可复用模块与差距评估
|
||||
|
||||
这样能最快把“前端长什么样”“后端怎么跑”“zn-ai 现在到哪一步了”三件事拆开。
|
||||
|
||||
## 7.2 实施阶段建议：5 个 sub-agent（结构性对齐基线）
|
||||
|
||||
真正进入开发阶段，建议 5 个 sub-agent，已经接近并行上限，再多会明显增加冲突成本。
|
||||
|
||||
### Agent 1：Channels 页面壳与 Diagnostics UI
|
||||
|
||||
负责文件：
|
||||
|
||||
- `src/pages/Channels/index.tsx`
|
||||
- `src/components/channels/ChannelDiagnosticsPanel.tsx`
|
||||
- `src/components/channels/ChannelGroupCard.tsx`
|
||||
|
||||
职责：
|
||||
|
||||
- 页面 IA
|
||||
- configured / supported 列表
|
||||
- health banner
|
||||
- diagnostics 展开与复制
|
||||
- 页面级收敛刷新
|
||||
|
||||
### Agent 2：ChannelConfigModal 与前端 schema / i18n
|
||||
|
||||
负责文件：
|
||||
|
||||
- `src/components/channels/ChannelConfigModal.tsx`
|
||||
- `src/components/channels/*`
|
||||
- `src/lib/channel-meta.ts`
|
||||
- `src/lib/channel-types.ts`
|
||||
- `src/i18n/messages.ts` 或新增 locale 文件
|
||||
|
||||
职责：
|
||||
|
||||
- 类型选择
|
||||
- token / QR 表单
|
||||
- accountId 编辑校验
|
||||
- docs / instructions / badge
|
||||
- 文案与 schema 收敛
|
||||
|
||||
### Agent 3：配置持久化与 Host API 核心
|
||||
|
||||
负责文件：
|
||||
|
||||
- `electron/api/routes/channels.ts`
|
||||
- `electron/utils/channel-config.ts`
|
||||
- `electron/utils/agent-config.ts`
|
||||
|
||||
职责：
|
||||
|
||||
- config CRUD
|
||||
- default account
|
||||
- enabled / disabled
|
||||
- binding 与视图拼装
|
||||
- canonical / legacy accountId 处理
|
||||
|
||||
### Agent 4：Runtime / Gateway / Targets / Channel Integrations
|
||||
|
||||
负责文件：
|
||||
|
||||
- `electron/utils/channel-status.ts`
|
||||
- `electron/utils/channels.ts`
|
||||
- `electron/main.ts`
|
||||
- `electron/gateway/**`
|
||||
- `electron/utils/channel-integrations/*`
|
||||
|
||||
职责：
|
||||
|
||||
- local targets
|
||||
- gateway health summary
|
||||
- reload / restart 策略
|
||||
- runtime 事件广播
|
||||
- QR / plugin channel 集成
|
||||
|
||||
### Agent 5：测试与联调收口
|
||||
|
||||
负责文件：
|
||||
|
||||
- `tests/unit/**`
|
||||
- `tests/e2e/**`
|
||||
- `docs/**`
|
||||
|
||||
职责：
|
||||
|
||||
- 建单测 / E2E 基线
|
||||
- 做回归矩阵
|
||||
- 跟进 smoke checklist
|
||||
- 收敛文档和验收口径
|
||||
|
||||
## 7.3 推荐执行顺序
|
||||
|
||||
建议顺序：
|
||||
|
||||
1. Agent 3 与 Agent 4 先行
|
||||
2. Agent 2 在 schema 稳定后进入
|
||||
3. Agent 1 在 API 能返回完整视图后进入
|
||||
4. Agent 5 全程跟进，但在 Phase 3 后集中补全
|
||||
|
||||
原因：
|
||||
|
||||
- 消息频道功能是典型的“后端语义先行”场景。
|
||||
- 如果没有 config 模型、runtime 状态和 targets 本地化，前端很容易做成半成品。
|
||||
|
||||
## 7.4 完全对齐 ClawX 的 sub-agent 数量估算
|
||||
|
||||
如果目标从“结构性对齐”提升到“功能与运行时行为尽量完全对齐 ClawX”，建议按“不包含主控 Codex”的口径重新估算 sub-agent 数量。
|
||||
|
||||
建议口径如下：
|
||||
|
||||
1. 最小编制：`5` 个 sub-agent
|
||||
- 适合完成页面结构、核心 Host API、多账号配置、基础 diagnostics
|
||||
- 风险是 QR / plugin channel、target 目录发现、自动化测试会相互挤压
|
||||
2. 推荐编制：`7` 个 sub-agent
|
||||
- 适合并行推进后端配置、Host API、runtime/gateway、频道集成、前端控制台、弹窗/i18n、测试收口
|
||||
- 这是“期望完全对齐 ClawX”时最均衡的方案
|
||||
3. 峰值编制：`8` 个 sub-agent
|
||||
- 仅建议在 Phase 2 到 Phase 4 短时启用
|
||||
- 用于把“核心 token 类 channel 集成”和“QR / plugin channel 集成”拆成两个独立实施包
|
||||
|
||||
结论：
|
||||
|
||||
- 如果只是完成可演示版本，`5` 个 sub-agent 足够。
|
||||
- 如果目标是尽量完全对齐 `ClawX`，推荐采用 `7` 个 sub-agent。
|
||||
- 如果要求在较短周期内把 connector 细节与测试一起收口，峰值可以提升到 `8` 个 sub-agent，但不建议长期保持。
|
||||
|
||||
## 7.5 完全对齐场景下的推荐分工
|
||||
|
||||
推荐编制：`7` 个 sub-agent + `1` 个主控 Codex。
|
||||
|
||||
主控 Codex 职责：
|
||||
|
||||
- 维护总计划
|
||||
- 冻结接口契约
|
||||
- 处理跨 agent 冲突
|
||||
- 合并阶段成果
|
||||
- 做最终验收与回归判断
|
||||
|
||||
### Agent A：配置模型与持久化 Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `electron/utils/channel-config.ts`
|
||||
- `electron/utils/agent-config.ts` 中与 `channelOwners` / `channelAccountOwners` 交界的部分
|
||||
- `channels.json` 或等价配置模型定义
|
||||
|
||||
核心任务：
|
||||
|
||||
- 定义多账号配置模型
|
||||
- 定义 `defaultAccountId`
|
||||
- 定义 `enabled`
|
||||
- 定义 legacy accountId / canonical accountId 兼容规则
|
||||
- 定义配置读写与删除语义
|
||||
|
||||
交付件：
|
||||
|
||||
- 本地频道配置真相源
|
||||
- config CRUD 基础能力
|
||||
- 配置 schema 文档
|
||||
|
||||
### Agent B：Host API 与视图拼装 Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `electron/api/routes/channels.ts`
|
||||
- `electron/api/router.ts`
|
||||
- `electron/main.ts` 中 Host API 优先级分流逻辑
|
||||
|
||||
核心任务：
|
||||
|
||||
- 扩展 `/api/channels/accounts`
|
||||
- 扩展 `/api/channels/config/:type`
|
||||
- 扩展 `/api/channels/config`
|
||||
- 扩展 `/api/channels/default-account`
|
||||
- 扩展 `/api/channels/config/enabled`
|
||||
- 收回 `/api/channels/targets` 的本地优先权
|
||||
|
||||
交付件：
|
||||
|
||||
- 完整本地 channels Host API
|
||||
- 视图层所需的统一返回结构
|
||||
- upstream fallback 清理方案
|
||||
|
||||
### Agent C：Runtime / Gateway / Diagnostics Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `electron/utils/channel-status.ts`
|
||||
- `electron/gateway/**`
|
||||
- `electron/main.ts`
|
||||
- diagnostics 相关 route / util
|
||||
|
||||
核心任务：
|
||||
|
||||
- 构建 channel runtime status 推断逻辑
|
||||
- 接入 gateway health summary
|
||||
- 定义 reload / restart 策略
|
||||
- 广播 `channels` / `channel-targets` / `agents` runtime event
|
||||
- 提供 diagnostics snapshot
|
||||
|
||||
交付件：
|
||||
|
||||
- 页面可消费的 runtime health 数据
|
||||
- 配置保存后的收敛刷新能力
|
||||
- diagnostics / restart 链路
|
||||
|
||||
### Agent D：频道集成 Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `electron/utils/channel-integrations/*`
|
||||
- `electron/utils/wechat-login.ts`
|
||||
- `electron/utils/whatsapp-login.ts`
|
||||
- `electron/utils/channel-plugin-install.ts`
|
||||
- `electron/utils/channels.ts` 中与远程目录发现相关的逻辑
|
||||
|
||||
核心任务：
|
||||
|
||||
- 对齐 WeChat / WhatsApp 登录流程
|
||||
- 对齐 plugin install / detect 流程
|
||||
- 对齐 credentials validate
|
||||
- 对齐 target 目录发现
|
||||
- 梳理各 channel 的 `connectionType` 与特殊字段规则
|
||||
|
||||
交付件：
|
||||
|
||||
- connector 能力矩阵
|
||||
- QR / plugin channel 接入层
|
||||
- channel-specific validate / target discovery
|
||||
|
||||
说明：
|
||||
|
||||
- 如果进入峰值 `8` 个 sub-agent 模式，优先把 Agent D 拆成两个：
|
||||
- `D1` 负责 Telegram / Discord / Feishu / QQ Bot 等 token 类 channel
|
||||
- `D2` 负责 WeChat / WhatsApp / DingTalk / WeCom 等 QR / plugin 类 channel
|
||||
|
||||
### Agent E：Channels 控制台页面 Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `src/pages/Channels/index.tsx`
|
||||
- `src/components/channels/ChannelDiagnosticsPanel.tsx`
|
||||
- `src/components/channels/ChannelGroupCard.tsx`
|
||||
|
||||
核心任务：
|
||||
|
||||
- 对齐标题区与 refresh
|
||||
- 对齐 configured / supported 双区块
|
||||
- 对齐 health banner
|
||||
- 对齐 diagnostics 展开 / 复制
|
||||
- 对齐删除确认与收敛刷新体验
|
||||
|
||||
交付件：
|
||||
|
||||
- ClawX 风格的频道控制台页面壳
|
||||
- 配置组卡片与账号行展示
|
||||
- diagnostics UI
|
||||
|
||||
### Agent F：ChannelConfigModal / 前端 schema / i18n Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `src/components/channels/ChannelConfigModal.tsx`
|
||||
- `src/components/channels/*`
|
||||
- `src/lib/channel-meta.ts`
|
||||
- `src/lib/channel-types.ts`
|
||||
- `src/i18n/messages.ts` 或拆分 locale 文件
|
||||
|
||||
核心任务：
|
||||
|
||||
- 对齐 channel meta schema
|
||||
- 对齐 `ChannelConfigModal`
|
||||
- 对齐 token / QR / docs / instructions
|
||||
- 对齐 accountId 编辑与校验
|
||||
- 对齐频道名称、badge、文案和提示语
|
||||
|
||||
交付件：
|
||||
|
||||
- 可复用的 channel meta schema
|
||||
- 可测试的配置弹窗
|
||||
- 对齐 ClawX 的文案与交互层
|
||||
|
||||
### Agent G：测试与联调收口 Owner
|
||||
|
||||
负责范围：
|
||||
|
||||
- `tests/unit/**`
|
||||
- `tests/e2e/**`
|
||||
- `docs/**`
|
||||
|
||||
核心任务：
|
||||
|
||||
- 为 route / config / status / page 建立单测
|
||||
- 建立 binding / diagnostics / account validation / persistence 的 E2E
|
||||
- 维护 smoke checklist
|
||||
- 跟踪阶段性回归
|
||||
|
||||
交付件：
|
||||
|
||||
- 自动化回归基线
|
||||
- 联调问题清单
|
||||
- 阶段验收记录
|
||||
|
||||
## 7.6 按波次推进的开发安排
|
||||
|
||||
为了减少冲突，建议按 4 个波次推进，而不是 7 个 sub-agent 同时全量开工。
|
||||
|
||||
### Wave 0：契约冻结
|
||||
|
||||
参与：
|
||||
|
||||
- 主控 Codex
|
||||
- Agent A
|
||||
- Agent B
|
||||
- Agent C
|
||||
|
||||
目标：
|
||||
|
||||
- 冻结 `channels.json` 模型
|
||||
- 冻结 Host API 响应结构
|
||||
- 冻结 runtime event topic
|
||||
- 冻结前端 channel meta schema
|
||||
|
||||
产出：
|
||||
|
||||
- 字段命名表
|
||||
- route contract
|
||||
- runtime contract
|
||||
|
||||
### Wave 1：数据面与本地 Host API
|
||||
|
||||
参与：
|
||||
|
||||
- Agent A
|
||||
- Agent B
|
||||
- Agent C
|
||||
|
||||
目标：
|
||||
|
||||
- 让本地能完整提供 `accounts` / `config` / `default-account` / `enabled` / `targets`
|
||||
- 去掉 `/api/channels/targets` 对 upstream 的优先依赖
|
||||
|
||||
进入下一波条件：
|
||||
|
||||
- 前端已能拿到稳定的 accounts view
|
||||
- target 列表本地可用
|
||||
- default account 读写闭环
|
||||
|
||||
### Wave 2：运行时与 channel 集成
|
||||
|
||||
参与：
|
||||
|
||||
- Agent C
|
||||
- Agent D
|
||||
|
||||
目标：
|
||||
|
||||
- 接通 diagnostics
|
||||
- 接通 reload / restart
|
||||
- 接通 validate
|
||||
- 接通 QR / plugin channel
|
||||
|
||||
进入下一波条件：
|
||||
|
||||
- 配置保存后能触发正确的 runtime 收敛
|
||||
- 至少核心 channel 流程能跑通
|
||||
|
||||
### Wave 3：页面与弹窗对齐
|
||||
|
||||
参与：
|
||||
|
||||
- Agent E
|
||||
- Agent F
|
||||
|
||||
目标：
|
||||
|
||||
- 对齐 ClawX 页面结构
|
||||
- 对齐 `ChannelConfigModal`
|
||||
- 对齐 supported channels 与 configured groups
|
||||
- 对齐删除、刷新、诊断与弹窗交互
|
||||
|
||||
进入下一波条件：
|
||||
|
||||
- 消息频道控制台可端到端演示
|
||||
- 页面层不再依赖临时 mock 字段
|
||||
|
||||
### Wave 4：测试收口与完全对齐验收
|
||||
|
||||
参与：
|
||||
|
||||
- Agent G
|
||||
- 主控 Codex
|
||||
- 视需要回拉 Agent C / D / E / F 修复回归
|
||||
|
||||
目标：
|
||||
|
||||
- 补齐 unit / e2e
|
||||
- 做 channel parity checklist
|
||||
- 收敛剩余差距
|
||||
|
||||
最终验收以两份清单为准：
|
||||
|
||||
1. 功能清单
|
||||
- 是否完全覆盖 ClawX 页面、Host API、diagnostics、runtime、绑定、多账号、默认账号、modal、targets
|
||||
2. channel 清单
|
||||
- 是否覆盖 ClawX 当前支持的 channel 类型与对应连接方式
|
||||
|
||||
## 7.7 并行边界与冲突规避规则
|
||||
|
||||
为了让 sub-agent 真正能推进开发，而不是互相打架，建议明确以下边界：
|
||||
|
||||
1. Agent A 不直接改前端文件
|
||||
2. Agent E / F 不直接改 `electron/api/routes/channels.ts`
|
||||
3. Agent C 不直接改 `ChannelConfigModal`
|
||||
4. Agent G 默认不改生产代码，除非明确接手缺陷修复
|
||||
5. `electron/main.ts` 只允许 Agent B 与 Agent C 协调改动
|
||||
6. `src/lib/channel-types.ts` 只允许 Agent F 主导，其他 agent 通过契约消费
|
||||
7. 如果启用峰值 `8` 个 sub-agent，必须把 D1 / D2 的 channel 列表先写死，避免重复改同一 connector
|
||||
|
||||
## 7.8 当前推进状态（2026-04-18）
|
||||
|
||||
本轮已经按推荐编制的一部分开始落地，当前实际分工与产出如下。
|
||||
|
||||
### 已投入的 sub-agent
|
||||
|
||||
1. 主控 Codex
|
||||
- 负责总装、接口收敛、页面整合、验证与文档回写
|
||||
2. Agent B/C 合流实施
|
||||
- 已完成 `channel-config.ts`、`channels.ts`、`agent-config.ts`、`routes/channels.ts`、`routes/gateway.ts`、`main.ts` 的首轮闭环
|
||||
3. Agent F
|
||||
- 已完成 `src/components/channels/*`、`src/lib/channel-types.ts`、`src/lib/channel-meta.ts`、`src/i18n/messages.ts` 的首轮 schema 与弹窗骨架
|
||||
4. Agent E
|
||||
- 已完成 `src/pages/Channels/index.tsx` 的控制台化改造首版
|
||||
5. Agent G
|
||||
- 已完成 `tests/channels.test.ts`、`vitest` 基础接线与首批 util 测试
|
||||
|
||||
当前等价于已经启用 `5` 个实施向 sub-agent / owner 角色；如果继续追求完全对齐 ClawX，下一轮建议补齐 Agent D，并在测试压力上升时扩展到推荐编制 `7` 个。
|
||||
|
||||
### 当前已完成事项
|
||||
|
||||
1. Wave 1 基本完成
|
||||
- 本地 `channels.json` 配置真相源已经落地
|
||||
- `config/default-account/enabled/delete/targets` 本地 Host API 已闭环
|
||||
- `/api/channels/targets` 已切回本地优先
|
||||
2. Wave 2 部分完成
|
||||
- gateway health summary 已接入
|
||||
- channel status 推断已接入
|
||||
- runtime changed topic 已补到 `channels/channel-targets/agents`
|
||||
3. Wave 3 已启动并形成首版可用页面
|
||||
- `Channels` 页已升级为“支持的频道 + 已配置频道 + 默认账号 + Agent 绑定 + Gateway 健康”的控制台结构
|
||||
- `ChannelConfigModal` 已能承接 channel schema、账号新增、账号编辑和保存
|
||||
- 频道矩阵已从业务占位类型切换为 ClawX channel meta
|
||||
|
||||
### 当前仍未完成的差距
|
||||
|
||||
1. diagnostics snapshot 仍未补齐复制 / 展开面板
|
||||
2. `credentials validate` 尚未补齐
|
||||
3. WeChat / WhatsApp 的 QR 登录事件链路尚未接入
|
||||
4. plugin install / detect 仍未接入
|
||||
5. 页面级单测与 E2E 还缺失
|
||||
6. 删除后的延迟收敛刷新、gateway 运行态过渡探测，仍弱于 ClawX
|
||||
|
||||
### 下一轮 sub-agent 投入建议
|
||||
|
||||
如果继续按“完全对齐 ClawX”推进，建议下一轮这样补齐：
|
||||
|
||||
1. Agent D
|
||||
- 专注 QR / plugin / validate / target discovery
|
||||
2. Agent G
|
||||
- 补 channels page unit test 与 diagnostics / binding / account regression E2E
|
||||
3. 主控 Codex
|
||||
- 继续负责跨层集成，把 diagnostics 面板、延迟收敛刷新和 page controller 拆分补上
|
||||
|
||||
## 8. 关键风险与决策点
|
||||
|
||||
1. `zn-ai` 当前 `/api/channels/targets` 仍有 upstream 优先逻辑
|
||||
- 这是本次迁移必须消除的分叉点
|
||||
2. 是否立即统一 `agents.json` 与 `channels.json`
|
||||
- 建议先分开，Phase 3 再评估是否合并
|
||||
3. plugin / QR channel 是否首批全部上线
|
||||
- 建议先完成架构支持，再按频道类型灰度
|
||||
4. reload 与 restart 边界
|
||||
- 建议一开始保守，优先正确性
|
||||
5. canonical accountId 与 legacy 兼容
|
||||
- 必须在 Phase 1 明确规则，否则 UI 与后端会反复打架
|
||||
6. WeChat / WhatsApp 的状态目录清理
|
||||
- 删除与取消登录要加保护，避免误删
|
||||
|
||||
## 9. 验收标准
|
||||
|
||||
迁移完成后，至少满足以下标准：
|
||||
|
||||
1. `zn-ai` 的 `/channels` 具备 ClawX 同级别页面结构
|
||||
2. 能本地完成频道与账号配置，不依赖 upstream 才能工作
|
||||
3. 支持 default account、多账号配置、binding、targets
|
||||
4. 支持 gateway diagnostics 与 restart
|
||||
5. 关键配置保存后能正确收敛到 runtime 状态
|
||||
6. Agents 页继续只展示摘要，不回收写操作
|
||||
7. 自动化测试覆盖新增账号、校验、诊断、绑定、编辑回归
|
||||
|
||||
## 10. 本轮建议结论
|
||||
|
||||
最合理的推进方式不是“一口气把 ClawX 代码整体搬过来”，而是：
|
||||
|
||||
1. 对齐 ClawX 的交互与 API 语义
|
||||
2. 复用 `zn-ai` 已有的本地 route、agent store、channel utils
|
||||
3. 在 `zn-ai` 内补一个真正的频道配置与运行时域
|
||||
4. 以 `7` 个 sub-agent 作为完全对齐的推荐编制，按波次推进，先后端、再前端、最后测试收口
|
||||
5. 若要压缩周期，可在 Phase 2 到 Phase 4 短时提升到峰值 `8` 个 sub-agent
|
||||
|
||||
这样既能尽量对齐 ClawX，又不会把 `zn-ai` 现有结构全部打散。
|
||||
@@ -12,4 +12,6 @@
|
||||
|
||||
- 继续推进，下一步最值的是补 /api/channels/targets 和 provider runtime sync；这两段补上后，zn-ai 会更接近 ClawX 的完整闭环。估算sub-agent数量，安排sub-agent分工推进开发工作，期望完全对齐ClawX
|
||||
|
||||
- 替我确认真实 UI 操作流和 gateway 行为已经全部跑通。离“完全对齐 ClawX”还差两块更值钱的尾项：真实远端 target discovery，不只是本地候选合成；以及 provider/runtime 变更后的显式前端刷新事件，而不只是主进程侧同步。估算sub-agent数量，安排sub-agent分工推进开发工作，期望完全对齐ClawX。
|
||||
- 替我确认真实 UI 操作流和 gateway 行为已经全部跑通。离“完全对齐 ClawX”还差两块更值钱的尾项：真实远端 target discovery，不只是本地候选合成；以及 provider/runtime 变更后的显式前端刷新事件，而不只是主进程侧同步。估算sub-agent数量，安排sub-agent分工推进开发工作，期望完全对齐ClawX。
|
||||
|
||||
- 在ClwaX项目中深度分析消息频道功能包括渲染层视觉UI、主进程等实现思路，用于迁移到zn-ai项目，输出迁移开发计划到zn-ai/docs目录下，估算sub-agent数量，安排sub-agent分工分析消息频道功能实现思路，期望迁移功能对齐ClawX。
|
||||
Reference in New Issue
Block a user