feat: 区分 server 与 desktop 配置加载入口，取消自动创建配置文件
- config.go 重构：抽取 loadConfig 共享逻辑，新增 LoadServerConfig/LoadDesktopConfig/LoadDesktopConfigAtPath，LoadConfig 保持向后兼容 - setupConfigFile 移除 SafeWriteConfigAs 自动创建逻辑，文件不存在时仅使用默认值 - cmd/desktop 切换为 LoadDesktopConfig，端口/HTTP/浏览器/托盘统一使用 cfg.Server.Port - cmd/server 显式使用 LoadServerConfig 明确入口语义 - 提取 desktop 可测 helper：desktopListenAddr/desktopURL/desktopPortMenuTitle/desktopConfigErrorMessage - 新增测试：desktop 忽略 CLI/env/未知参数、配置快照不变、无效配置文件不静默回退、端口 helper 一致性 - README 区分 server/desktop 配置源，移除首次启动自动创建配置文件描述 - 同步 delta specs 到 openspec/specs/ 主规范
This commit is contained in:
@@ -8,16 +8,18 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
|
||||
|
||||
### Requirement: 桌面应用启动
|
||||
|
||||
系统 SHALL 支持作为桌面应用启动，将后端服务与前端静态资源打包为单一可执行文件。
|
||||
系统 SHALL 支持作为桌面应用启动，将后端服务与前端静态资源打包为单一可执行文件，并使用启动配置中的 `server.port` 作为本次运行端口。
|
||||
|
||||
#### Scenario: 双击启动
|
||||
|
||||
- **WHEN** 用户双击桌面应用可执行文件
|
||||
- **THEN** 系统使用 `gofrs/flock` 尝试获取排他文件锁
|
||||
- **THEN** 系统从 `~/.nex/config.yaml` 和默认值加载启动配置快照
|
||||
- **AND** 系统使用 `gofrs/flock` 尝试获取排他文件锁
|
||||
- **AND** 锁文件路径为系统临时目录下的 `nex-gateway.lock`
|
||||
- **AND** 系统启动后端服务
|
||||
- **AND** 系统使用启动配置中的 `server.port` 启动后端服务
|
||||
- **AND** 未配置 `server.port` 时默认端口为 9826
|
||||
- **AND** 系统托盘图标出现
|
||||
- **AND** 浏览器自动打开 `http://localhost:9826` 显示管理界面
|
||||
- **AND** 浏览器自动打开 `http://localhost:<server.port>` 显示管理界面
|
||||
|
||||
#### Scenario: 单实例检查
|
||||
|
||||
@@ -34,7 +36,7 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
|
||||
|
||||
### Requirement: 系统托盘
|
||||
|
||||
系统 SHALL 提供跨平台系统托盘功能，支持托盘图标和菜单。图标格式 SHALL 根据平台自动选择。
|
||||
系统 SHALL 提供跨平台系统托盘功能，支持托盘图标和菜单。图标格式 SHALL 根据平台自动选择，端口显示 SHALL 使用启动配置中的 `server.port`。
|
||||
|
||||
#### Scenario: 托盘图标显示
|
||||
|
||||
@@ -50,19 +52,19 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
|
||||
- **THEN** 显示托盘菜单
|
||||
- **AND** 菜单包含"打开管理界面"选项
|
||||
- **AND** 菜单包含"状态: 运行中"选项（禁用状态）
|
||||
- **AND** 菜单包含"端口: 9826"选项（禁用状态）
|
||||
- **AND** 菜单包含"端口: <server.port>"选项（禁用状态）
|
||||
- **AND** 菜单包含"退出"选项
|
||||
|
||||
#### Scenario: 打开管理界面
|
||||
|
||||
- **WHEN** 用户点击托盘菜单"打开管理界面"
|
||||
- **THEN** 系统在浏览器中打开 `http://localhost:9826`
|
||||
- **THEN** 系统在浏览器中打开 `http://localhost:<server.port>`
|
||||
|
||||
#### Scenario: 浏览器打开失败
|
||||
|
||||
- **WHEN** 系统无法打开浏览器（浏览器未安装等）
|
||||
- **THEN** 托盘菜单仍可正常使用
|
||||
- **AND** 用户可手动访问 `http://localhost:9826`
|
||||
- **AND** 用户可手动访问 `http://localhost:<server.port>`
|
||||
|
||||
#### Scenario: 退出应用
|
||||
|
||||
@@ -124,19 +126,81 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
|
||||
|
||||
### Requirement: 端口冲突检测
|
||||
|
||||
系统 SHALL 在启动前检测端口是否可用。
|
||||
系统 SHALL 在启动前检测启动配置中的 `server.port` 是否可用。
|
||||
|
||||
#### Scenario: 端口可用
|
||||
#### Scenario: 配置端口可用
|
||||
|
||||
- **WHEN** 端口 9826 未被占用
|
||||
- **WHEN** 启动配置中的 `server.port` 未被占用
|
||||
- **THEN** 服务正常启动
|
||||
|
||||
#### Scenario: 端口被占用
|
||||
#### Scenario: 配置端口被占用
|
||||
|
||||
- **WHEN** 端口 9826 已被其他程序占用
|
||||
- **THEN** 显示错误提示"端口 9826 已被占用"
|
||||
- **WHEN** 启动配置中的 `server.port` 已被其他程序占用
|
||||
- **THEN** 显示错误提示"端口 <server.port> 已被占用"
|
||||
- **AND** 应用退出
|
||||
|
||||
### Requirement: 桌面配置源隔离和启动快照
|
||||
|
||||
desktop SHALL 仅在启动时从默认配置文件 `~/.nex/config.yaml` 和默认值加载运行时配置，并将加载结果作为本次运行的 immutable runtime snapshot。
|
||||
|
||||
#### Scenario: Desktop 仅使用默认配置文件
|
||||
|
||||
- **WHEN** desktop 启动
|
||||
- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
|
||||
- **THEN** SHALL 在配置文件不存在时使用默认值
|
||||
- **THEN** SHALL 使用默认值补齐配置文件未设置的配置项
|
||||
|
||||
#### Scenario: Desktop 不支持 CLI 配置源
|
||||
|
||||
- **WHEN** desktop 启动时传入 `--server-port 9000`、`--database-path /tmp/test.db` 或 `--config /tmp/custom.yaml`
|
||||
- **THEN** SHALL 忽略这些参数
|
||||
- **THEN** SHALL NOT 将这些参数应用到运行时配置
|
||||
- **THEN** SHALL NOT 使用 `--config` 指定的配置文件路径
|
||||
|
||||
#### Scenario: Desktop 不支持环境变量配置源
|
||||
|
||||
- **WHEN** desktop 启动环境中存在 `NEX_SERVER_PORT`、`NEX_DATABASE_PATH`、`NEX_LOG_LEVEL` 或其他 `NEX_*` 环境变量
|
||||
- **THEN** SHALL NOT 将这些环境变量应用到运行时配置
|
||||
- **THEN** SHALL 使用默认配置文件和默认值确定运行时配置
|
||||
|
||||
#### Scenario: Desktop 忽略未知启动参数
|
||||
|
||||
- **WHEN** desktop 启动时传入未知命令行参数
|
||||
- **THEN** SHALL NOT 因未知参数导致配置加载失败
|
||||
- **THEN** SHALL 继续使用默认配置文件和默认值加载配置
|
||||
|
||||
#### Scenario: 配置文件修改仅下次启动生效
|
||||
|
||||
- **WHEN** desktop 已启动并正在处理请求
|
||||
- **AND** 用户修改 `~/.nex/config.yaml` 中的 `server.port`、`database.*`、`log.*` 或 timeout 配置
|
||||
- **THEN** 当前运行中的 desktop SHALL NOT 重新加载配置文件
|
||||
- **THEN** 当前运行中的 HTTP server、数据库连接、日志器和请求处理 SHALL NOT 因配置文件修改而重建或中断
|
||||
- **THEN** 修改后的配置 SHALL 在下一次 desktop 启动时生效
|
||||
|
||||
#### Scenario: 配置文件无效
|
||||
|
||||
- **WHEN** desktop 启动时 `~/.nex/config.yaml` 存在但内容无法解析或验证失败
|
||||
- **THEN** SHALL 显示包含配置文件路径和失败原因的错误提示
|
||||
- **THEN** SHALL 退出应用
|
||||
- **THEN** SHALL NOT 静默回退默认配置继续启动
|
||||
|
||||
### Requirement: Desktop 前端同源 API 访问
|
||||
|
||||
desktop 内嵌前端 SHALL 使用同源相对路径访问后端 API，不主动发现、缓存或覆盖 desktop 端口。
|
||||
|
||||
#### Scenario: 同源 API 请求
|
||||
|
||||
- **WHEN** desktop 浏览器页面打开在 `http://localhost:<server.port>`
|
||||
- **THEN** 前端 SHALL 使用 `/api/*`、`/openai/*` 和 `/anthropic/*` 等相对路径访问同一 origin
|
||||
- **THEN** 前端 SHALL NOT 硬编码 desktop 端口
|
||||
|
||||
#### Scenario: 重启后新端口访问
|
||||
|
||||
- **WHEN** 用户修改配置文件中的 `server.port` 并重启 desktop
|
||||
- **THEN** desktop SHALL 按新端口启动并打开 `http://localhost:<new-port>`
|
||||
- **THEN** 前端 SHALL 继续使用当前 origin 的相对路径访问 API
|
||||
- **THEN** 前端 SHALL NOT 扫描端口、读取本地缓存端口或请求端口发现接口
|
||||
|
||||
### Requirement: 跨平台构建
|
||||
|
||||
系统 SHALL 支持跨平台构建和打包。构建 target SHALL 按平台和架构分离或参数化，中间构建产物文件名 SHALL 保持可区分目标平台和架构，最终桌面发布资产文件名 SHALL 包含统一版本号、组件、平台、架构和格式信息。
|
||||
|
||||
Reference in New Issue
Block a user