zn-ai/docs/ClawX-Channels-Migration-Plan.md

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 现有结构全部打散。