# Gateway 升级说明

适用范围：`@rcodex-lab/gateway`

## 升级前确认

- 现有数据目录已经保留
- 账号、密码、token 和可访问目录配置已确认
- Node.js 版本为 22 或更高
- 当前用户已有可用的 ChatGPT 登录、API Key 或 Provider 凭据

## 标准升级步骤

普通用户默认使用 npm 部署：

```bash
npm install -g @rcodex-lab/gateway
rcodex-gateway setup
rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status
```

如果已经安装过 Gateway，升级时执行：

```bash
rcodex-gateway service update
```

该命令在当前 Gateway 所在的 npm 目录更新包，成功后使用新版 CLI 刷新服务定义、重启并显示最终状态。npm 更新失败时不会停止现有服务，也不会自动使用 sudo。

常用服务命令：

```bash
rcodex-gateway service install
rcodex-gateway service start
rcodex-gateway service status
rcodex-gateway service restart
rcodex-gateway service update
rcodex-gateway service stop
rcodex-gateway service uninstall
```

首次安装时需要执行 `service install`。升级后建议再次执行，以便覆盖为当前版本的任务或服务定义；该操作不会覆盖 `gateway.env` 和数据目录。Windows 使用当前用户计划任务，macOS 使用 LaunchAgent，Linux 使用 user-level systemd。这样 Gateway 能继续读取当前用户的 Codex CLI 登录态。

Windows 新安装默认使用 `%LOCALAPPDATA%\rCodex\Gateway\gateway.env`；已有 `C:\ProgramData\rCodex\Gateway\gateway.env` 会继续复用。Windows 计划任务在当前用户登录后无窗口运行，不要求管理员权限或 Windows 账户密码，关闭执行安装命令的终端不会停止 Gateway。升级后必须重新执行 `service install`，以覆盖旧任务定义并移除旧 PowerShell 启动文件；该操作不会覆盖配置和数据。`service start` 会验证后台 PID 和 `/healthz`，`service status` 会显示运行模式、任务、进程、HTTP 健康状态及日志路径。

Gateway npm 包会同时安装官方 `@openai/codex` 运行时，不再要求单独全局安装 Codex CLI。旧 `gateway.env` 中的默认值 `CODEX_COMMAND=codex`，以及指向 VS Code `openai.chatgpt-*` 扩展版本目录的历史 Codex 路径，都会自动使用内置版本；其他显式自定义命令继续保留。内置运行时不会自动完成账号或 Provider 认证。

需要临时调试时，也可以继续使用 `rcodex-gateway start` 在当前终端前台运行；关闭终端后前台进程会停止。如果没有安装后台服务，升级后停止旧的前台进程，再重新执行 `rcodex-gateway start`。

## 这次版本需要注意什么

`1.4.39` 是 Gateway 小版本更新，App 继续兼容 `1.4.38`。升级后，历史会话会在启动恢复阶段自动补全缺失或已失效的 Provider 绑定；Console 同时获得更稳定的会话历史增量加载、模块化资源和初始化流程。

- 统一 Agent 时间线独立于旧事件历史持久化，首次兼容迁移最多读取最近 `2000` 条事件，后续分页单页最多 `200` 项。
- 单次内容读取最多 `256 KiB`；单个大内容对象最多保留 `16 MiB`，单会话完整对象配额为 `64 MiB` 和 `256` 个，超过边界后压缩最旧的已完成对象。
- Provider 配置最多 `64` 个，单个 Provider 的模型、PI 工具和 DeepSeek 插件最多各 `256` 项；模型探测保持 `5s` 超时和单 Provider 单飞。
- PI Agent 改为按需安装，不再成为 Gateway 启动硬依赖；Provider 配置、模型目录和运行时状态按实例隔离。
- Console 可见时间线窗口保持最多 `2000` 项，超长内容展开视图最多保留 `2 MiB`，避免单个长会话持续抬高页面内存。
- Console 任务提示音单次最多 `3` 组短生命周期音频节点，最长约 `1.05s`，不新增轮询、网络请求或历史扫描。
- 历史会话 Provider 补全只扫描会话元数据，同运行时首个可用 Provider 在启动迁移内复用，批量更新仅触发一次持久化；不会读取事件归档，也不会改变会话排序时间。
- Console 主程序拆分为按职责维护的独立模块，保留单入口加载顺序；初始化依赖在事件绑定前完成，避免缩减主文件后出现按钮无响应或页面状态缺失。