# 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 诊断放到第二批。