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

ClawX Agents 功能迁移到 zn-ai 的更新版计划

1. 背景与本次修正

本版文档基于两条新的约束重新整理：

• 最新 Agents 参考图已经明确，页面信息架构必须回到 ClawX 的列表主视图。
• 开发需求已经明显变化，后续实现必须严格对齐 ClawX Agents 功能，而不是继续延展一版“更强的 Models/Agent 控制台”。

这意味着上一版计划里最重要的一条判断需要作废：

• 上一版曾把 zn-ai 的 /agents 页面导向“列表 + 固定右侧详情”的控制台详情页。
• 这个方向与最新参考图和 ClawX 真实交互不一致，后续不应继续推进。

本轮统一后的基线结论如下：

1. /agents 必须保持独立路由与侧边栏入口，不能再并回 /models。
2. 页面 IA 必须切回 ClawX 的“列表主视图”。
3. Agents 页主内容只保留卡片摘要、刷新、新增和设置入口，不把设置详情常驻在主布局中。
4. Add Agent 必须是独立弹窗，且字段极简，只收：
   • name
   • inheritWorkspace
5. Settings 详情建议改为 modal 或 sheet，而不是主布局双栏右侧 inspector。
6. Channels 继续作为 channel/account 归属绑定的唯一写入口。
7. Models 继续负责 Provider、默认模型、Usage，不承载 Agent 实体管理。
8. Home/Chat/Cron 继续作为 Agents 域的消费页面，不反向定义 Agents 页形态。

一句话总结：

• 当前 zn-ai 已经补上了不少 Agents 基础设施。
• 下一轮的重点不再是“有没有 /agents”，而是“把 /agents 的页面 IA、交互层级和职责边界重新拉回 ClawX”。

2. ClawX 基线：严格对齐什么

2.1 路由入口与页面装配

ClawX 的 Agents 是独立域，不是 Models 的子视图。

基线文件主要集中在：

• ClawX/src/pages/Agents/index.tsx
• ClawX/src/pages/Channels/index.tsx
• ClawX/src/stores/agents.ts
• ClawX/electron/api/routes/agents.ts

它的装配方式很明确：

• 侧边栏有独立 Agents 入口。
• /agents 是独立页面。
• /models 与 /agents 是并列关系，不混用页面职责。

2.2 页面 IA：列表主视图，而不是控制台详情页

ClawX 的 Agents 首页首先是一个列表工作台，不是一个主布局双栏的详情编辑器。

页面骨架应理解为：

1. 顶部标题区
   • Title
   • Subtitle
   • Refresh
   • Add Agent
2. Warning / Error banner
3. Agent card 列表
4. 卡片上的 Settings / Delete 入口
5. 二级弹层
   • AddAgentDialog
   • AgentSettingsModal
   • AgentModelModal

明确不要做的事：

• 不要在页面右侧常驻一个大号设置面板。
• 不要把“选中某个 agent 后右边出现详情”的双栏结构作为主交互。
• 不要把创建、命名、模型、绑定全部平铺到首页主布局。
• 不要让卡片列表承担复杂表单职责。

这也是本轮文档更新里最核心的 IA 修正。

2.3 Add Agent 弹窗：字段与交互

ClawX 的 AddAgentDialog 很克制，创建阶段只做最小信息采集。

建议严格对齐以下字段与交互：

• 标题与简短说明
• name 输入框
  • 必填
  • 非空后才能提交
• inheritWorkspace 开关
  • 含义是“是否继承主 Agent 工作区”
  • 默认保持轻量，不在创建弹窗里叠加更多高级参数
• Cancel
• Save / Create

创建阶段明确不应该出现的字段：

• Provider 选择
• Model override
• Channel binding
• Workspace 路径高级配置

创建成功后的回流建议也对齐 ClawX：

• 关闭弹窗
• 回到列表主视图
• 列表出现新卡片
• 可给 toast，但不要自动把用户带进重型详情页

2.4 Agents 首页卡片：只保留摘要与设置入口

ClawX 的卡片不是“迷你详情页”，而是摘要卡片。

建议卡片层面保留这些信息：

• 头像 / icon
• name
• default badge
• 模型摘要
  • 当前模型
  • 是否继承默认模型
• 频道归属摘要
  • 只展示结果，不提供写操作

建议卡片层面只保留这些动作：

• Settings
• Delete

不建议放在卡片正面的内容：

• 大段 workspace / agentDir / sessionKey 技术细节
• channel/account 绑定下拉
• provider/model 大表单
• 右侧伴随卡片选中状态的持久编辑区

如果需要展示更多运行时信息，优先放进设置弹层，而不是挤进首页卡片。

2.5 设置详情：建议 modal / sheet，而不是主布局双栏

ClawX 的设置入口是二级层级，不是首页主布局的一部分。

因此在 zn-ai 中更推荐：

• 桌面端使用 modal 或 side sheet
• 移动端使用全屏 sheet / dialog

不推荐继续保留当前这类形态：

• 左侧列表
• 右侧常驻详情 inspector
• 页面刷新或切换 agent 时整块右栏一起抖动

原因有三点：

1. 不符合 ClawX 的交互层级。
2. 会把“列表主视图”错误拉成“详情驱动”页面。
3. 不利于后续继续保持 Cards 摘要化。

Settings 弹层建议承载的内容：

• Identity
  • 名称
  • Agent ID
• Model
  • provider account
  • model ref
  • inherit default model
  • 预览当前 effective provider / model
• Channel binding summary
  • 只读展示当前 channel/account 归属
  • 提供“去 Channels 管理”的入口

如果仍需要二级模型编辑体验，可以继续保留嵌套的 AgentModelModal，但它依然属于弹层体系，而不是首页主布局。

2.6 与 Channels / Models 的职责边界

这是本轮必须写死的边界。

Agents 页负责什么

• Agent 实体列表
• 新建 / 删除 / 重命名
• per-agent model override
• 归属摘要展示
• 设置入口

Agents 页不负责什么

• channel/account 绑定写操作
• provider account CRUD
• 默认 provider 设定
• usage 历史查询主视图

Channels 页负责什么

• channel 级归属
• account 级归属
• binding 写操作唯一入口
• routing fallback 关系说明

Models 页负责什么

• provider account CRUD
• default provider / default model
• provider catalog / vendors
• usage history
• provider 视角的 models snapshot

边界落地后的页面关系应该是：

• Agents 看 Agent 和摘要
• Channels 改归属
• Models 管 Provider

2.7 与 Home / Chat / Cron 的联动

ClawX 的 Agents 不孤立存在，它是多个页面共享的域。

最关键的消费关系如下：

• Home / Chat
  • 当前 Agent 名称
  • 当前 Agent 模型
  • 会话切换与发送路由
• Cron
  • 任务归属 agentId
  • delivery channel / account / target
  • 编辑时展示 Agent 与 delivery 摘要

因此后续实现时要记住：

• Home/Chat/Cron 是 Agents 域的消费者。
• 它们的联动验证很重要。
• 但它们不应该反过来决定 /agents 首页长什么样。

3. zn-ai 当前现状：已经落地的部分与剩余偏差

3.1 已经落地的部分

与上一版文档相比，zn-ai 当前已经不是“Agents 完全缺失”的状态。

已经具备的基础包括：

1. 独立 /agents 路由与侧边栏入口
2. agentsStore
3. 本地 /api/agents
4. 本地 /api/channels/accounts
5. 本地 /api/channels/targets
6. Channels 页的 channel/account 归属写操作
7. Cron 页的：
   • agent
   • channel
   • account
   • target
8. provider runtime sync 与 gateway reload/restart 链路
9. Home 聊天顶部 Agent 切换与发送前模型校验

换句话说：

• “Agents 域基础设施缺失”已经不再是主问题。
• “UI/IA 没有回到 ClawX 基线”才是当前最主要的剩余问题。

3.2 仍然存在的关键偏差

尽管能力已经补了不少，当前 zn-ai 仍然和 ClawX 有几个显著偏差。

偏差 1：页面仍然太像“详情页”

当前实现已经是“列表 + 右侧设置区”的形态，这比最早的 /agents -> /models 已经前进很多，但仍然不是 ClawX 的列表主视图。

需要明确回退：

• 去掉“固定右侧详情”作为主布局
• 恢复“卡片列表 + 设置弹层”

偏差 2：Add Agent 还是 prompt / confirm 式流转

当前实现仍然偏命令式：

• prompt 输名字
• confirm 选 inherit workspace

这不符合 ClawX 的统一弹层体验，也不利于后续继续扩展创建态文案和校验。

偏差 3：Agents 页承担了过多常驻编辑语义

当前页面把：

• identity
• model
• binding summary

长期固定在主布局中展示，导致首页不再是纯列表。

这会让视觉重心从“列表工作台”滑向“控制台详情页”。

偏差 4：需要继续守住 Channels / Models 边界

zn-ai 当前的方向整体是对的：

• Channels 已经承担 binding 写操作
• Agents 已经开始只读展示 binding summary

但文档和实现都要继续避免回摆：

• 不要因为 Agents settings 看起来“顺手”，就再把绑定下拉搬回去
• 不要因为 Agents 能改 model，就把 provider CRUD 一并塞进 Agents

偏差 5：Models Snapshot 仍然不能替代 Agents 页

/api/models 当前仍然更接近“provider account 视角的合成 snapshot”，不是 Agent 域真相。

因此后续文档、QA 和页面说明都应避免混淆：

• Models Snapshot 只能验证 provider 视角
• Agent override 与 Agent 路由应以 /api/agents、Agents 页和 Home/Chat 行为为准

4. 新一轮 sub-agent 数量估算与分工

4.1 推荐并行规模

按当前代码基础判断，下一轮如果目标是“严格对齐 ClawX Agents UI 与职责边界”，推荐按 6 个 sub-agent 并行推进。

这不是为了把任务拆得更碎，而是为了减少 UI / store / local route / cross-page 联动之间的冲突。

但结合 zn-ai 当前已经具备的 /agents 页面骨架、agentsStore、本地 /api/agents、Channels 绑定链路，以及这轮需求已经明显收敛到“参考图驱动的 UI / IA 重构”，本轮实际执行建议按 4 个 sub-agent 推进更合适：

• 1 个负责 Agents 首页 IA 与视觉重构
• 1 个负责 Add Agent / Settings 弹层与文案收口
• 1 个负责 store / backend 能力缺口与回归风险核对
• 1 个负责迁移计划、验收口径和回归说明同步

4.2 推荐分工

sub-agent	写入范围	目标
1	src/pages/Agents/**, src/router/**, src/components/layout/**	把 /agents 页面 IA 调回列表主视图，保证入口、标题区、刷新、新增和卡片层对齐 ClawX
2	src/pages/Agents/**	重做 Add Agent 弹窗，以及 Settings modal/sheet、Agent model modal 的交互层级
3	src/stores/agents.ts, shared agent types, 页面数据拼装逻辑	收口 Agents 页面所需字段，确保卡片摘要、设置详情、只读 binding summary 的数据来源稳定
4	electron/api/routes/agents.ts, runtime sync 相关实现, agent-config	校验 create / rename / model override / delete 的 runtime sync、reload、restart 语义是否与 UI 新交互一致
5	src/pages/Channels/**, src/pages/Models/**, src/pages/Home/**, src/pages/Cron/**	守住 Channels/Models/Home/Cron 的职责边界，避免 Agents IA 回正后引入新耦合
6	docs/**, smoke tests, regression notes	更新迁移文档、手工冒烟路径、验收标准和回归清单

4.3 资源不足时的降配方案

如果并行资源不足，可以降到 4 个 sub-agent，但不要把下面两类工作混在一个人身上：

• 首页 IA 重构
• runtime / route / sync 硬逻辑

推荐合并方式：

• 1 + 2
• 5 + 6

4.4 本轮实际执行分工

结合当前会话的资源与改动范围，本轮按 4 个 sub-agent 推进：

sub-agent	本轮职责	产出
A	参考图与 ClawX IA 差异分析	列表主视图、卡片字段、弹层层级修正建议
B	backend / store 能力核对	确认 createAgent(inheritWorkspace)、rename、model override、delete 是否足够支撑新 UI
C	迁移计划文档更新	把“控制台详情页”基线修正为“ClawX 列表主视图”
D	i18n 与页面文案收口	让标题、副标题、添加弹窗和设置语义贴近参考图与 ClawX 心智

5. 分阶段实施建议

本轮建议不再按“从零搭 Agents 域”的顺序推进，而改成“在已落地能力上收口 UI 和边界”。

5.1 阶段 0：冻结新基线

目标：

• 明确上一版“控制台详情页 / 双栏布局”判断失效
• 团队统一采用 ClawX 列表主视图基线

产出：

• 更新后的本计划文档
• 统一的页面 IA 草图
• 明确的职责边界

验收标准：

• 团队确认 /agents 首页不做固定右侧详情栏
• 团队确认 Add Agent 只收最小字段
• 团队确认 Channels / Models / Agents 三页边界

预计工作量：

• 0.5 天

5.2 阶段 1：把首页 IA 从双栏拉回列表主视图

目标：

• 先把首页结构改对，再谈细节

建议改动：

• 首页只保留：
  • title
  • subtitle
  • refresh
  • add
  • banner
  • card list
• 去掉常驻右侧 inspector

验收标准：

• /agents 首屏看起来就是列表主视图
• 即使不打开任何设置，也能完整浏览所有 Agent 卡片

预计工作量：

• 0.5 ~ 1 天

5.3 阶段 2：补齐 Add Agent 弹窗与设置弹层

目标：

• 把所有二级编辑交互收进 overlay 层

建议改动：

• Add Agent dialog
  • name
  • inheritWorkspace
• Agent settings modal / sheet
  • identity
  • model
  • binding summary
• Agent model modal
  • provider + model ref

验收标准：

• 创建、重命名、模型覆盖都不再依赖首页双栏
• 桌面和窄屏下的弹层层级都清晰

预计工作量：

• 1 ~ 1.5 天

5.4 阶段 3：收口首页卡片摘要

目标：

• 让首页卡片真正回到摘要视角

建议改动：

• 卡片只保留必要摘要
• workspace / agentDir / sessionKey 等技术细节尽量移入设置层
• hover 动作保持轻量

验收标准：

• 卡片读起来像 ClawX
• 首页不出现重型编辑表单

预计工作量：

• 0.5 天

5.5 阶段 4：守住 Channels / Models / Agents 边界

目标：

• 在 UI 回正后，避免功能重新耦合

建议改动：

• Agents settings 里的绑定区继续只读
• “Manage bindings” 统一跳转 Channels
• Models 保持 provider / default / usage，不接 Agent CRUD
• 默认模型语义留在 Models，Agent override 语义留在 Agents

验收标准：

• 团队对“去哪改什么”没有歧义
• QA 能明确知道每类问题该在哪页验证

预计工作量：

• 0.5 天

5.6 阶段 5：联动与回归验证

目标：

• 验证 UI 改造没有破坏现有 Agents 域能力

重点验证链路：

1. Agents 创建后，Home/Chat 能看到新 Agent
2. Agent model override 更新后，Home 发送仍可走通
3. Channels 绑定变更后，Agents settings 摘要能反映
4. Cron 里 agent/channel/account/target 仍然可用
5. /api/channels/targets 与手工输入兜底都正常
6. 删除 Agent 后 reload/restart 行为仍稳定

预计工作量：

• 1 天

6. 风险清单

风险	描述	应对
旧判断残留	团队继续沿用“右侧详情栏”思路实现后续 UI	在阶段 0 明确作废旧 IA 结论，并把弹层方案写死
Add Agent 范围膨胀	创建弹窗被不断塞入 provider/model/channel 字段	规定创建阶段只收 name + inheritWorkspace
绑定边界回摆	因为 settings 层已有 binding summary，顺手加下拉写操作	Agents 只读展示，Channels 保持唯一写入口
Models 语义漂移	Provider CRUD 再次被拉进 Agents	Models 专注 provider/default/usage，不承载 Agent 实体管理
runtime sync 假通过	UI 保存成功，但真实 runtime 文件或 gateway 状态没同步	回归必须覆盖 create / update model / delete 三类动作
Cron targets 体验退化	因为 UI 改造误伤 target 自动加载与手输兜底	把 /api/channels/targets 与手工输入都纳入冒烟清单

7. 验收重点

严格对齐 ClawX 时，验收不要只看“功能能不能点”，还要看“页面是不是回到了正确的形态”。

本轮建议把下面几条列为强验收项：

1. /agents 首页是否是列表主视图，而不是双栏详情页
2. Add Agent 是否是正式弹窗，而不是 prompt / confirm
3. 首页卡片是否只保留摘要与设置入口
4. Settings 是否是 modal / sheet，而不是主布局常驻
5. Agents 是否只读展示 binding summary，并把写操作引导到 Channels
6. Models 是否仍然只负责 provider/default/usage
7. Home / Cron 是否继续消费同一份 Agents 域数据

8. 最终建议

当前 zn-ai 已经把独立 /agents、agentsStore、本地 routes、runtime sync、Channels/Cron 联动这些“底座”补得差不多了。

所以下一轮不要再把重心放在“有没有 Agents 能力”，而要放在下面四件事：

1. 把 /agents 的页面 IA 严格拉回 ClawX
2. 把 Add Agent 与 Settings 改成标准弹层体系
3. 把 Agents / Channels / Models 的职责边界写死并落实到 UI
4. 用 Home / Cron / targets / runtime sync 做真实闭环回归

如果这四件事做对，zn-ai 的 Agents 才会从“功能拼装完成”真正进入“体验与职责都对齐 ClawX”的阶段。