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/ 主规范
2026-05-06 11:59:19 +08:00
parent 598e2acb7e
commit 5513f0c13d
10 changed files with 589 additions and 147 deletions
--- a/openspec/specs/config-management/spec.md
+++ b/openspec/specs/config-management/spec.md
@@ -8,20 +8,27 @@

 ### Requirement: 使用 YAML 配置文件

-系统 SHALL 使用 YAML 格式的配置文件。
+系统 SHALL 使用 YAML 格式的配置文件，并按入口区分配置文件路径选择能力。

-#### Scenario: 配置文件路径
+#### Scenario: Server 默认配置文件路径

- **WHEN** 应用启动且未指定 `--config` 参数
+- **WHEN** server 应用启动且未指定 `--config` 参数
 - **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
 - **THEN** SHALL 解析 YAML 格式

-#### Scenario: 自定义配置文件路径
+#### Scenario: Server 自定义配置文件路径

- **WHEN** 应用启动且指定 `--config /path/to/custom.yaml`
+- **WHEN** server 应用启动且指定 `--config /path/to/custom.yaml`
 - **THEN** SHALL 从指定路径加载配置文件
 - **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`

+#### Scenario: Desktop 固定配置文件路径
+
+- **WHEN** desktop 应用启动
+- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
+- **THEN** SHALL 解析 YAML 格式
+- **THEN** SHALL NOT 支持通过 `--config` 指定其他配置文件路径
+
 #### Scenario: 配置文件结构

 - **WHEN** 加载配置文件
@@ -30,14 +37,14 @@

 ### Requirement: 自动生成默认配置

-系统 SHALL 在首次使用时自动生成默认配置。
+系统 SHALL 在配置文件不存在时使用默认配置值，不自动创建配置文件。

 #### Scenario: 配置文件不存在

 - **WHEN** 应用启动且配置文件不存在
- **THEN** SHALL 自动创建配置文件
- **THEN** SHALL 写入默认配置值
- **THEN** SHALL 记录日志提示已创建
+- **THEN** SHALL 使用默认配置值
+- **THEN** SHALL NOT 自动创建配置文件
+- **THEN** SHALL NOT 写入默认配置值到磁盘

 #### Scenario: 配置文件已存在

@@ -163,22 +170,36 @@

 ### Requirement: 配置加载流程

-系统 SHALL 实现标准化的配置加载流程。
+系统 SHALL 为 server 和 desktop 实现标准化且入口隔离的配置加载流程。

-#### Scenario: 加载步骤
+#### Scenario: Server 加载步骤

- **WHEN** 应用启动
+- **WHEN** server 应用启动
 - **THEN** SHALL 按以下顺序加载配置：
   1. 解析 CLI 参数（获取 --config 路径）
   2. 初始化配置管理器
   3. 设置默认值
   4. 绑定 CLI 参数
   5. 绑定环境变量
-   6. 读取配置文件（不存在时自动创建）
+   6. 读取配置文件（不存在时使用默认值）
   7. 反序列化到结构体
   8. 验证配置
   9. 打印配置摘要

+#### Scenario: Desktop 加载步骤
+
+- **WHEN** desktop 应用启动
+- **THEN** SHALL 按以下顺序加载配置：
+   1. 初始化配置管理器
+   2. 设置默认值
+   3. 读取默认配置文件 `~/.nex/config.yaml`（不存在时使用默认值）
+   4. 反序列化到结构体
+   5. 验证配置
+   6. 打印配置摘要
+- **THEN** SHALL NOT 解析 CLI 参数
+- **THEN** SHALL NOT 绑定环境变量
+- **THEN** SHALL NOT 允许 CLI 参数覆盖配置文件路径
+
 #### Scenario: 加载失败处理

 - **WHEN** 配置加载过程中发生错误
@@ -188,25 +209,25 @@

 ### Requirement: 配置优先级管理

-系统 SHALL 实现明确的配置优先级机制。
+系统 SHALL 为不同入口实现明确的配置优先级机制。

-#### Scenario: 优先级顺序
+#### Scenario: Server 优先级顺序

- **WHEN** 同一配置项在多个配置源中设置
+- **WHEN** 同一配置项在多个 server 配置源中设置
 - **THEN** SHALL 按以下优先级顺序（从高到低）：
  1. CLI 参数
  2. 环境变量
  3. 配置文件
  4. 默认值

-#### Scenario: CLI 参数最高优先级
+#### Scenario: Server CLI 参数最高优先级

 - **WHEN** 配置文件设置 `server.port: 9826`
 - **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
- **AND** CLI 参数设置 `--server-port 8080`
+- **AND** server CLI 参数设置 `--server-port 8080`
 - **THEN** SHALL 使用 CLI 参数值 8080

-#### Scenario: 环境变量次高优先级
+#### Scenario: Server 环境变量次高优先级

 - **WHEN** 配置文件设置 `server.port: 9826`
 - **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
@@ -227,21 +248,35 @@
 - **AND** 未设置 CLI 参数
 - **THEN** SHALL 使用默认值

-#### Scenario: 部分配置覆盖
+#### Scenario: Server 部分配置覆盖

 - **WHEN** 配置文件设置完整配置
- **AND** CLI 参数仅覆盖部分配置项
+- **AND** server CLI 参数仅覆盖部分配置项
 - **THEN** SHALL 合并所有配置源
 - **THEN** SHALL 使用高优先级源覆盖指定项
 - **THEN** SHALL 保留其他配置源中的未覆盖项

-#### Scenario: 配置项独立覆盖
+#### Scenario: Server 配置项独立覆盖

- **WHEN** 仅通过 CLI 参数设置 `--server-port 9000`
+- **WHEN** 仅通过 server CLI 参数设置 `--server-port 9000`
 - **THEN** SHALL 仅覆盖 server.port 配置项
 - **THEN** SHALL NOT 影响其他配置项
 - **THEN** SHALL 其他配置项使用配置文件或默认值

+#### Scenario: Desktop 优先级顺序
+
+- **WHEN** 同一配置项存在于 desktop 默认配置文件和默认值中
+- **THEN** SHALL 使用 `~/.nex/config.yaml` 中的配置文件值
+- **THEN** SHALL 仅在配置文件未设置该配置项时使用默认值
+
+#### Scenario: Desktop 忽略外部覆盖源
+
+- **WHEN** desktop 启动时存在 `--server-port 9000` 参数
+- **AND** 存在 `NEX_SERVER_PORT=9001` 环境变量
+- **AND** `~/.nex/config.yaml` 设置 `server.port: 9826`
+- **THEN** SHALL 使用配置文件值 9826
+- **THEN** SHALL NOT 使用 CLI 参数或环境变量覆盖配置
+
 #### Scenario: 启动后配置锁定

 - **WHEN** 应用启动完成
@@ -314,67 +349,79 @@

 ### Requirement: CLI 参数配置支持

-系统 SHALL 支持通过命令行参数设置所有配置项。
+server 入口 SHALL 支持通过命令行参数设置所有配置项；desktop 入口 SHALL NOT 将命令行参数作为配置源。

-#### Scenario: 基本参数解析
+#### Scenario: Server 基本参数解析

- **WHEN** 应用启动时传入命令行参数
+- **WHEN** server 应用启动时传入命令行参数
 - **THEN** SHALL 解析所有 CLI 参数
 - **THEN** SHALL 将参数值应用到对应配置项

 #### Scenario: 参数命名规范

- **WHEN** 使用命令行参数
+- **WHEN** server 使用命令行参数
 - **THEN** SHALL 使用 kebab-case 命名（如 `--server-port`）
 - **THEN** SHALL 保持完整的层次结构（如 `--database-max-idle-conns`）
 - **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `--database-max-idle-conns`）

 #### Scenario: 参数类型支持

- **WHEN** 解析不同类型的参数
+- **WHEN** server 解析不同类型的参数
 - **THEN** SHALL 支持 int 类型（如 `--server-port 9000`）
 - **THEN** SHALL 支持 string 类型（如 `--database-path /data/nex.db`）
 - **THEN** SHALL 支持 duration 类型（如 `--server-read-timeout 60s`）
 - **THEN** SHALL 支持 bool 类型（如 `--log-compress`）

-#### Scenario: 完整配置覆盖
+#### Scenario: Server 完整配置覆盖

- **WHEN** 使用服务器相关参数
+- **WHEN** server 使用服务器相关参数
 - **THEN** SHALL 支持 `--server-port`、`--server-read-timeout`、`--server-write-timeout`
- **WHEN** 使用数据库相关参数
+- **WHEN** server 使用数据库相关参数
 - **THEN** SHALL 支持 `--database-driver`、`--database-path`、`--database-host`、`--database-port`、`--database-user`、`--database-password`、`--database-dbname`、`--database-max-idle-conns`、`--database-max-open-conns`、`--database-conn-max-lifetime`
- **WHEN** 使用日志相关参数
+- **WHEN** server 使用日志相关参数
 - **THEN** SHALL 支持 `--log-level`、`--log-path`、`--log-max-size`、`--log-max-backups`、`--log-max-age`、`--log-compress`

-#### Scenario: 参数帮助信息
+#### Scenario: Server 参数帮助信息

- **WHEN** 使用 `--help` 参数
+- **WHEN** server 使用 `--help` 参数
 - **THEN** SHALL 显示所有支持的参数
 - **THEN** SHALL 按功能分组展示参数（服务器、数据库、日志）
 - **THEN** SHALL 显示每个参数的默认值和说明

-#### Scenario: 参数错误处理
+#### Scenario: Server 参数错误处理

- **WHEN** 传入无效的参数值（如 `--server-port abc`）
+- **WHEN** server 传入无效的参数值（如 `--server-port abc`）
 - **THEN** SHALL 返回明确的错误信息，指示参数名称和期望类型
 - **THEN** SHALL NOT 启动应用
- **WHEN** 传入未定义的参数（如 `--unknown-param value`）
+- **WHEN** server 传入未定义的参数（如 `--unknown-param value`）
 - **THEN** SHALL 返回错误信息，指示未知参数名称
 - **THEN** SHALL NOT 启动应用

+#### Scenario: Desktop 忽略配置参数
+
+- **WHEN** desktop 启动时传入 `--server-port 9000`、`--database-path /tmp/test.db` 或 `--config /tmp/custom.yaml`
+- **THEN** SHALL 忽略这些参数
+- **THEN** SHALL 从 `~/.nex/config.yaml` 和默认值加载配置
+
+#### Scenario: Desktop 忽略未知参数
+
+- **WHEN** desktop 启动时传入未知命令行参数
+- **THEN** SHALL NOT 因未知参数导致配置加载失败
+- **THEN** SHALL NOT 将未知参数应用为配置
+
 ### Requirement: 环境变量配置支持

-系统 SHALL 支持通过环境变量设置所有配置项，符合 12-Factor App 原则。
+server 入口 SHALL 支持通过环境变量设置所有配置项，符合 server 部署场景的 12-Factor App 原则；desktop 入口 SHALL NOT 将 `NEX_*` 环境变量作为配置源。

-#### Scenario: 环境变量读取
+#### Scenario: Server 环境变量读取

- **WHEN** 应用启动时存在环境变量
+- **WHEN** server 应用启动时存在环境变量
 - **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
 - **THEN** SHALL 将环境变量值应用到对应配置项

 #### Scenario: 环境变量命名规范

- **WHEN** 使用环境变量配置
+- **WHEN** server 使用环境变量配置
 - **THEN** SHALL 使用 `NEX_` 前缀
 - **THEN** SHALL 使用大写字母和下划线分隔（如 `NEX_SERVER_PORT`）
 - **THEN** SHALL 保持完整层次结构（如 `NEX_DATABASE_MAX_IDLE_CONNS`）
@@ -382,35 +429,41 @@

 #### Scenario: 环境变量类型转换

- **WHEN** 解析不同类型的环境变量
+- **WHEN** server 解析不同类型的环境变量
 - **THEN** SHALL 支持 int 类型（如 `NEX_SERVER_PORT=9000`）
 - **THEN** SHALL 支持 string 类型（如 `NEX_DATABASE_PATH=/data/nex.db`）
 - **THEN** SHALL 支持 duration 类型（如 `NEX_SERVER_READ_TIMEOUT=60s`）
 - **THEN** SHALL 支持 bool 类型（如 `NEX_LOG_COMPRESS=true`）

-#### Scenario: 完整环境变量覆盖
+#### Scenario: Server 完整环境变量覆盖

- **WHEN** 设置服务器相关环境变量
+- **WHEN** server 设置服务器相关环境变量
 - **THEN** SHALL 支持 `NEX_SERVER_PORT`、`NEX_SERVER_READ_TIMEOUT`、`NEX_SERVER_WRITE_TIMEOUT`
- **WHEN** 设置数据库相关环境变量
+- **WHEN** server 设置数据库相关环境变量
 - **THEN** SHALL 支持 `NEX_DATABASE_DRIVER`、`NEX_DATABASE_PATH`、`NEX_DATABASE_HOST`、`NEX_DATABASE_PORT`、`NEX_DATABASE_USER`、`NEX_DATABASE_PASSWORD`、`NEX_DATABASE_DBNAME`、`NEX_DATABASE_MAX_IDLE_CONNS`、`NEX_DATABASE_MAX_OPEN_CONNS`、`NEX_DATABASE_CONN_MAX_LIFETIME`
- **WHEN** 设置日志相关环境变量
+- **WHEN** server 设置日志相关环境变量
 - **THEN** SHALL 支持 `NEX_LOG_LEVEL`、`NEX_LOG_PATH`、`NEX_LOG_MAX_SIZE`、`NEX_LOG_MAX_BACKUPS`、`NEX_LOG_MAX_AGE`、`NEX_LOG_COMPRESS`

-#### Scenario: 12-Factor App 合规
+#### Scenario: Server 12-Factor App 合规

- **WHEN** 应用部署到不同环境
+- **WHEN** server 部署到不同环境
 - **THEN** SHALL 通过环境变量区分环境配置
 - **THEN** SHALL NOT 修改代码或配置文件
- **WHEN** 配置包含敏感信息（如密钥、密码）
+- **WHEN** server 配置包含敏感信息（如密钥、密码）
 - **THEN** SHALL 通过环境变量传递
 - **THEN** SHALL NOT 存储在配置文件中

-#### Scenario: 环境变量错误处理
+#### Scenario: Server 环境变量错误处理

- **WHEN** 环境变量值格式无效（如 `NEX_SERVER_PORT=abc`）
+- **WHEN** server 环境变量值格式无效（如 `NEX_SERVER_PORT=abc`）
 - **THEN** SHALL 返回明确的错误信息，指示环境变量名称和期望类型
 - **THEN** SHALL NOT 启动应用
- **WHEN** 必需配置项既无配置文件也无环境变量
+- **WHEN** server 必需配置项既无配置文件也无环境变量
 - **THEN** SHALL 使用默认值
 - **THEN** SHALL 正常启动应用
+
+#### Scenario: Desktop 忽略环境变量
+
+- **WHEN** desktop 启动时存在 `NEX_SERVER_PORT`、`NEX_DATABASE_PATH`、`NEX_LOG_LEVEL` 或其他 `NEX_*` 环境变量
+- **THEN** SHALL NOT 读取这些环境变量作为配置源
+- **THEN** SHALL 使用 `~/.nex/config.yaml` 和默认值加载配置
--- a/openspec/specs/desktop-app/spec.md
+++ b/openspec/specs/desktop-app/spec.md
@@ -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 包含统一版本号、组件、平台、架构和格式信息。
--- a/openspec/specs/test-coverage/spec.md
+++ b/openspec/specs/test-coverage/spec.md
@@ -37,7 +37,7 @@
 - **THEN** SHALL 验证 LoadConfigFromPath 正确加载默认值
 - **THEN** SHALL 验证 YAML 配置文件正确读取
 - **THEN** SHALL 验证优先级链：CLI 参数 > 环境变量 > YAML 文件 > 默认值
- **THEN** SHALL 验证首次启动自动创建配置文件
+- **THEN** SHALL 验证配置文件缺失时使用默认值，不自动创建配置文件
 - **THEN** SHALL 验证 SaveConfig 后重新 LoadConfig 数据一致

 #### Scenario: 环境变量覆盖验证
@@ -46,11 +46,12 @@
 - **THEN** SHALL 成功加载
 - **THEN** 配置值 SHALL 反映环境变量覆盖

-#### Scenario: 自动创建配置文件验证
+#### Scenario: 配置文件缺失时使用默认值

 - **WHEN** 调用 `LoadConfigFromPath` 并指向不存在的文件路径
 - **THEN** SHALL 成功加载（不返回 `missing configuration for 'configPath'` 错误）
 - **THEN** SHALL 返回默认配置对象
+- **THEN** SHALL NOT 自动创建配置文件

 #### Scenario: handler 错误分支测试

@@ -303,3 +304,50 @@
 - **WHEN** 运行 desktop 专属测试
 - **THEN** SHALL 验证 desktop 模式启动数据库迁移时使用打包迁移资源
 - **THEN** SHALL 验证应用在发布产物环境中可执行迁移而不依赖源码迁移目录
+
+### Requirement: Desktop 配置源隔离测试覆盖
+
+系统 SHALL 为 desktop 配置加载行为建立测试覆盖，验证 desktop 只使用默认配置文件和默认值，不受 CLI 参数或 `NEX_*` 环境变量影响。
+
+#### Scenario: Desktop 配置文件端口生效
+
+- **WHEN** 运行 desktop 配置加载相关测试
+- **THEN** SHALL 验证 `~/.nex/config.yaml` 或等价测试配置文件中的 `server.port` 会进入 desktop 启动配置快照
+- **THEN** SHALL 验证 desktop 端口检测、HTTP 监听地址、浏览器打开地址和托盘端口显示使用同一个配置端口
+
+#### Scenario: Desktop 忽略 CLI 参数
+
+- **WHEN** 测试进程参数包含 `--server-port 9000`、`--database-path /tmp/test.db` 或 `--config /tmp/custom.yaml`
+- **THEN** desktop 配置加载 SHALL 忽略这些参数
+- **THEN** desktop 配置加载 SHALL 使用默认配置文件路径和配置文件值
+
+#### Scenario: Desktop 忽略未知参数
+
+- **WHEN** 测试进程参数包含未知命令行参数
+- **THEN** desktop 配置加载 SHALL 成功或仅因配置文件本身无效而失败
+- **THEN** desktop 配置加载 SHALL NOT 因未知参数返回参数解析错误
+
+#### Scenario: Desktop 忽略环境变量
+
+- **WHEN** 测试环境设置 `NEX_SERVER_PORT`、`NEX_DATABASE_PATH`、`NEX_LOG_LEVEL` 或其他 `NEX_*` 环境变量
+- **THEN** desktop 配置加载 SHALL NOT 使用这些环境变量覆盖配置文件值
+- **THEN** server 配置加载的环境变量覆盖测试 SHALL 继续通过
+
+#### Scenario: Desktop 配置快照不随文件变化自动更新
+
+- **WHEN** desktop 配置已加载为内存中的启动快照
+- **AND** 测试修改配置文件中的 `server.port` 或其他配置项
+- **THEN** 已加载的配置对象 SHALL 保持原值
+- **THEN** 重新启动或重新执行 desktop 配置加载时 SHALL 读取修改后的配置值
+
+#### Scenario: Desktop 无效配置错误提示
+
+- **WHEN** desktop 启动时配置文件存在但 YAML 无法解析或配置验证失败
+- **THEN** 测试 SHALL 验证启动流程返回或显示包含配置路径和失败原因的错误
+- **THEN** 测试 SHALL 验证 desktop 不会静默回退默认配置继续启动
+
+#### Scenario: 配置文件缺失时使用默认值
+
+- **WHEN** 测试配置加载时指定不存在的配置文件路径
+- **THEN** SHALL 返回默认配置值，不自动创建配置文件
+- **THEN** 测试 SHALL 验证配置文件未被创建