zn-ai/docs/Gateway-Configuration-Migration-Plan.md

Gateway 配置迁移计划

1. 目标与结论

目标是在 zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx 中新增“网关配置”能力，并尽量复用 ClawX 已验证过的交互与主进程职责拆分。

先给结论：

• ClawX 的网关设置不是单纯一段 UI，而是“设置持久化 + Gateway 生命周期管理 + Host API/IPC + 日志能力 + 调试能力”的完整链路。
• zn-ai 当前已经具备一部分基础能力：/api/gateway/status|health|start|stop|restart、gateway:rpc、gateway:event、config-service、theme-service、updater。
• zn-ai 当前缺少的是“网关设置模型”和“日志/文件夹打开/开发者辅助能力”，因此不能直接把 ClawX 的设置页 JSX 拷过来，必须先补设置域和主进程桥接。
• 推荐采用“两阶段迁移”：
  • Phase 1：先落地面向普通用户的网关设置能力。
  • Phase 2：再补开发者向的代理、令牌、诊断能力。

2. ClawX 功能盘点

2.1 已落地的网关设置功能

ClawX/src/pages/Settings/index.tsx 中的网关设置实际包含以下能力：

1. 公共网关区块

   • 状态徽标
   • 端口展示
   • 重启按钮
   • 日志按钮
   • 自动启动网关开关

2. 开发者扩展区块

   • 代理总开关
   • 代理字段草稿编辑与一次性保存
   • Control UI token 拉取与复制
   • WS 诊断开关
   • 额外的 CLI / Doctor / Telemetry Viewer

2.2 交互特征

• 状态展示依赖 useGatewayStore，不是页面自己轮询。
• gatewayAutoStart 这类简单开关是“切换即持久化”。
• 代理配置是“本地 draft -> dirty 检测 -> save 一次性提交”。
• 日志是“按需读取最近 N 行”，不是预加载。
• Control UI token 是“点击加载后显示”，不是默认常驻拉取。
• 开发者能力全部在 devModeUnlocked 后显示，普通用户默认不暴露。

2.3 主进程职责

ClawX 主进程里与网关设置直接相关的职责有：

• settings store：持久化 gatewayAutoStart、代理、token、devModeUnlocked、telemetryEnabled`
• gatewayManager：网关状态、启停、重启、健康检查、事件广播
• settings routes / IPC：通用设置读写
• gateway routes / IPC：生命周期与 Control UI 信息
• logs routes / IPC：日志读取、日志目录打开
• launch-at-startup：OS 级开机启动
• proxy：Electron 代理应用与 Gateway 重启联动

3. zn-ai 当前现状

3.1 已有能力

zn-ai 目前已经有这些可复用基础：

• 设置页容器：src/pages/Setting/index.tsx
• 通用设置面板：src/pages/Setting/components/GeneralSettingsPanel.tsx
• 全局设置 store：src/stores/settings.ts
• 配置持久化：electron/service/config-service.ts
• 主题服务：electron/service/theme-service.ts
• 更新服务：src/pages/Setting/useSettingUpdateState.ts
• Gateway Host API：
  • GET /api/gateway/status
  • GET /api/gateway/health
  • POST /api/gateway/start
  • POST /api/gateway/stop
  • POST /api/gateway/restart
• Gateway IPC：
  • gateway:rpc
  • gateway:event

3.2 关键差异

和 ClawX 相比，zn-ai 目前存在这些差异：

1. zn-ai 的 GeneralSettingsPanel 还是纯展示组件，没有 gateway props。
2. src/stores/settings.ts 只管理主题/语言/托盘/主色等字段，没有网关设置字段。
3. src/types/runtime.ts 和 ConfigValueMap 没有网关相关 key。
4. config-service 默认配置里没有网关设置默认值。
5. electron/api/router.ts 没有 /api/settings 与 /api/logs 这类本地设置/日志路由。
6. electron/service/logger.ts 负责写日志，但没有对 renderer 暴露“读取最近日志 / 获取日志目录”的能力。
7. electron/preload/index.ts 目前也没有 showItemInFolder 之类 shell 能力。
8. zn-ai/electron/gateway/manager.ts 当前更像 in-process bridge，状态维度只有 connected|disconnected|reconnecting，没有 ClawX 那种 running|starting|stopped|error + port + pid 的完整生命周期视图。

3.3 迁移判断

因此这次迁移不能按“页面复制”推进，而应该按下面的结构推进：

• 先补 zn-ai 的网关设置模型
• 再补主进程读写与日志能力
• 最后在 GeneralSettingsPanel 挂 UI

4. 推荐迁移范围

4.1 Phase 1：建议优先迁移

这些功能优先级最高，且对 GeneralSettingsPanel 最有价值：

1. 网关状态展示
2. 重启按钮
3. 查看日志
4. 自动启动网关开关
5. 基础日志目录打开能力

原因：

• 这几项直接对应用户最常见的“网关是否可用、出问题怎么恢复、去哪看日志”。
• 它们对主进程改造要求相对集中。
• 能在不引入大量开发者专属复杂度的前提下快速产出。

4.2 Phase 2：建议作为增强能力

这些功能建议第二阶段进入：

1. 代理配置
2. Control UI token 拉取与复制
3. WS 诊断开关
4. 开发者模式开关
5. 匿名使用数据开关

原因：

• 代理配置需要联动 Electron session、Gateway 重启，风险高于普通开关。
• token / WS 诊断更偏开发与排障。
• zn-ai 还没有 ClawX 同等级别的 Host API / preload / shell 白名单体系，直接硬迁会增加耦合。

4.3 Phase 3：建议暂不迁移

以下内容不建议一开始放入 GeneralSettingsPanel：

1. OpenClaw CLI 命令展示
2. OpenClaw Doctor
3. Telemetry Viewer

原因：

• 它们和 zn-ai 当前产品主线关联较弱。
• 实现成本明显高于用户价值。
• 会把通用设置页拉成调试控制台，不利于信息密度控制。

5. 功能映射方案

5.1 UI 映射

建议在 GeneralSettingsPanel 的“语言”与“版本更新”之间新增一个 Gateway section。

建议结构：

1. 网关状态卡片

   • 状态文案
   • 当前模式/状态
   • 可选端口展示
   • 重启 按钮
   • 日志 按钮

2. 网关自动启动开关

   • 标题
   • 描述
   • Toggle

3. 可选高级区

   • 仅在后续需要时加入
   • 代理配置、token、诊断开关

5.2 状态层映射

推荐新增一个独立 hook，而不是把所有逻辑塞进 GeneralSettingsPanel：

• src/pages/Setting/useGatewaySettingState.ts

职责：

• 读取 gatewayAutoStart
• 拉取 /api/gateway/status
• 执行 restartGateway()
• 读取日志文本
• 打开日志目录
• 管理本地 loading / error / lastFetchedAt

理由：

• 与现有 useSettingUpdateState.ts 保持模式一致
• 避免 GeneralSettingsPanel 过度膨胀
• 后续接入代理草稿状态更自然

5.3 配置模型映射

建议在 src/types/runtime.ts 和 runtime-shared/lib/constants.ts 统一补齐这些 key：

• gatewayAutoStart
• gatewayProxyEnabled
• gatewayProxyServer
• gatewayProxyHttpServer
• gatewayProxyHttpsServer
• gatewayProxyAllServer
• gatewayProxyBypassRules
• devModeUnlocked
• telemetryEnabled

注意：

• 先只实现 gatewayAutoStart 也可以，但类型层最好一次补齐未来要用的 key，避免下一轮再改类型。
• 若担心一次性改动过大，也可以只先补 gatewayAutoStart，其余在 Phase 2 再补。

6. 主进程改造方案

6.1 配置持久化

需要修改：

• electron/service/config-service.ts
• src/types/runtime.ts
• runtime-shared/lib/constants.ts

目标：

• 给网关配置提供默认值
• 让 renderer 和 main 对同一组 key 有一致类型

6.2 本地设置路由

建议新增：

• electron/api/routes/settings.ts

并在 electron/api/router.ts 注册。

职责：

• GET /api/settings
• PUT /api/settings
• GET /api/settings/:key
• PUT /api/settings/:key

理由：

• 这样 zn-ai 可以和 ClawX 对齐成 “Host API 管理设置 + renderer store 初始化” 的模式。
• 后续代理设置和开发者开关也可以挂在这条线，不必每个设置都手写 IPC。

6.3 日志路由与 shell 能力

建议新增：

• electron/api/routes/logs.ts
• showItemInFolder 或等价 shell handler

至少需要：

• GET /api/logs?tailLines=100
• GET /api/logs/dir

主进程需要给 logger 增补：

• 读取当前/最近日志文件内容
• 返回日志目录

6.4 Gateway 生命周期适配

当前 zn-ai/electron/gateway/manager.ts 状态粒度不足，不一定要完全复制 ClawX，但至少要满足设置页展示。

建议最低改造目标：

• checkHealth() 返回稳定状态快照
• /api/gateway/status 的返回值包含可用于 UI 的状态字段
• 若暂时没有真实 port/pid，UI 层应允许缺省，不要强依赖

建议策略：

• Phase 1 不强求对齐 ClawX 的 running|starting|stopped|error 全状态模型
• 先做 connected/disconnected/reconnecting 的 UI 映射
• 如果后面需要“运行中 / 已停止 / 错误”更细粒度状态，再扩 gatewayManager

7. 实施步骤

Milestone 0：建模

1. 扩展 runtime config key 与类型
2. 扩展 config-service 默认值
3. 统一 renderer/main 的读写入口

Milestone 1：主进程桥接

1. 新增 /api/settings
2. 新增 /api/logs
3. 新增打开日志目录能力
4. 核对 gateway status/restart 路由输出是否满足 UI 需要

Milestone 2：设置状态层

1. 新增 useGatewaySettingState.ts
2. 将 gatewayAutoStart 纳入 settings store 或独立 hook
3. 定义日志读取、重启、状态刷新行为

Milestone 3：渲染层

1. 给 GeneralSettingsPanel 增加 gateway section
2. 在 Setting/index.tsx 注入 gateway state
3. 补齐中英日文案

Milestone 4：增强能力

1. 代理 draft/save 模式
2. token 读取与复制
3. WS 诊断
4. dev mode / telemetry

8. 风险与注意点

1. zn-ai 当前 gateway manager 是 in-process 模式，和 ClawX 的独立进程 Gateway 生命周期不完全同构。
2. ClawX 的 gatewayPort 在设置模型里存在，但主流程未必实际使用；迁移时不要把“端口可编辑”误当成必须功能。
3. zn-ai 现在的 useSettingUpdateState 已经直接使用 get-config/update-config，说明 config key 在多个层定义并不完全一致；这次最好顺手补齐类型债。
4. 若代理功能进入 Phase 1，会额外牵动 Electron session.setProxy、Gateway 重启、网络回归验证，建议放到 Phase 2。
5. 如果没有 showItemInFolder，日志按钮只能先做“查看最近日志”，不能做“打开文件夹”。

9. Sub-agent 数量估算与分工

9.1 调研阶段

本次调研适合 3 个 explorer 并行：

1. ClawX 渲染层网关设置
2. ClawX 主进程 / IPC / 存储 / 日志
3. zn-ai 设置页与现有 Gateway 能力

9.2 开发阶段推荐数量

推荐 4 个 sub-agents 并行开发，不含主协调 agent。

如果要把联调/回归单独拆开，建议扩为 5 个。

9.3 推荐分工

Worker 1：渲染层 Gateway Panel

负责范围：

• src/pages/Setting/components/GeneralSettingsPanel.tsx
• src/pages/Setting/index.tsx
• 可选：src/pages/Setting/components/SectionHeader.tsx
• src/i18n/messages.ts

职责：

• 新增 Gateway section
• 接好状态、按钮、空态、错误态、加载态
• 控制视觉层级，不让设置页变成调试面板

Worker 2：设置模型与状态层

负责范围：

• src/types/runtime.ts
• runtime-shared/lib/constants.ts
• src/stores/settings.ts
• 新增 src/pages/Setting/useGatewaySettingState.ts

职责：

• 补齐 config key 与类型
• 统一 gatewayAutoStart 等字段的读取/写入
• 为渲染层提供稳定 state API

Worker 3：主进程设置/日志桥接

负责范围：

• electron/api/router.ts
• 新增 electron/api/routes/settings.ts
• 新增 electron/api/routes/logs.ts
• electron/service/config-service.ts
• electron/service/logger.ts
• electron/preload/index.ts

职责：

• 暴露本地 settings route
• 暴露 logs route
• 补 shell 打开目录能力
• 打通 renderer <-> main 的配置和日志桥

Worker 4：Gateway 生命周期适配

负责范围：

• electron/gateway/manager.ts
• electron/api/routes/gateway.ts
• electron/main.ts
• 可选：新增更细的 gateway status typing

职责：

• 校准状态返回结构
• 保证 restart/status/health 对设置页可用
• 如果需要，补自动启动策略与更清晰的状态快照

9.4 可选第 5 个 sub-agent

若要提高并行度，可增加一个 QA / Integration worker：

• 回归设置页、更新页、主题、语言、日志
• 检查 config key 兼容性
• 覆盖“无网关 / 重启中 / 读日志失败 / 配置缺省值”场景

10. 建议的开工顺序

建议按以下顺序派发任务：

1. Worker 2 先补类型与设置模型
2. Worker 3 并行补 settings/logs 路由与 logger 能力
3. Worker 4 校准 gateway 状态输出
4. Worker 1 在前 3 者接口稳定后接 UI

这样可以减少渲染层返工。

11. 本轮建议

如果下一步直接进入开发，我建议按以下范围作为第一批提交：

1. gatewayAutoStart
2. gateway 状态展示
3. restart 按钮
4. 日志查看
5. 日志目录打开

把代理、token、WS 诊断放到第二批。