duanshuwen/zn-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
be8298af2f001158c1d4150fa15f979f595ad3fe
zn-ai/docs/Gateway-Configuration-Migration-Plan.md
duanshuwen dfef9c90a5 feat: add gateway management features and settings 
- Implemented new API routes for handling logs and settings related to the gateway.
- Added a new Gateway section in the General Settings panel to manage gateway status and auto-start options.
- Introduced a state management hook for gateway settings, including status, logs, and auto-start functionality.
- Updated configuration service to include gateway auto-start setting.
- Enhanced internationalization support for new gateway-related messages.
- Refactored existing settings store to accommodate new gateway settings.
- Cleaned up code and improved logging functionality.
2026-04-20 22:22:11 +08:00

434 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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/index.ts`
- 主题服务：`electron/service/theme-service/index.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/index.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/index.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/index.ts`
- `electron/service/logger/index.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 诊断放到第二批。
Reference in New Issue View Git Blame Copy Permalink