[SAKURA-CAT]

Summary

本次变更将 SwanLab 配置从模块导入期加载调整为按需加载：import swanlab 不再构造 Settings，因此非法环境变量、损坏的 YAML 或不可用路径不会阻断基础包导入。

配置会在 swanlab.init()、swanlab.login()、swanlab.Api() 等实际需要配置的入口通过 create_settings() 加载和校验。配置错误仍会在首次消费配置时抛出；修复环境变量或配置文件后，可在同一进程中重新调用，无需重启。

Changes

延迟加载配置

• 移除模块导入期创建的全局 Settings 实例。
• 新增 create_settings()，每次创建独立配置快照，并按既有优先级读取 env、YAML、Secret 和 .netrc。
• 新增内部全局配置存储，仅保存 swanlab.merge_settings() 和进程内登录产生的覆盖项；后续配置快照会继承这些覆盖。

调用方适配

• init、login、sync、Public API、CLI logout 和 deprecated dashboard 改为在实际使用时创建配置快照。
• merge_settings() 改为更新全局配置快照，保持多次调用的累积语义。
• 登录成功后保存当前进程的 host 与凭据配置，供后续 init、Api 和 sync 使用。
• dashboard 的 host/port 默认值改为命令执行时解析，避免 Click 模块导入期触发配置加载。

配置校验

• dashboard port 增加 1..65535 范围校验，同时覆盖旧版和嵌套环境变量。
• 保持既有配置源优先级、嵌套配置合并和 self-hosted 凭据匹配规则。

Behavior

• 非法 SWANLAB_MODE、SWANLAB_LOGDIR、旧版嵌套环境变量或损坏的 swanlab.yaml 不再导致 import swanlab 失败。
• create_settings() 或其他配置消费入口仍会抛出对应的 ValidationError、YAML 解析错误或路径错误。
• 修复配置后再次调用可以正常工作，不会保留失败状态。
• swanlab.merge_settings() 的覆盖会应用于后续创建的配置快照。

Testing

uv run pytest tests/unit/sdk/internal/settings/test_settings.py tests/unit/sdk/internal/settings/test_settings_integration.py tests/unit/sdk/cmd/test_merge_settings.py tests/unit/sdk/cmd/login/test_login_e2e.py tests/unit/sdk/cmd/init/test_init_e2e.py tests/unit/api/test_api.py
# 197 passed

uv run ruff check .
# All checks passed

uv run --extra dashboard basedpyright
# 0 errors, 0 warnings, 0 notes

uv run pytest
# 1604 passed, 21 skipped

GitHub Actions 已覆盖并通过 macOS、Ubuntu、Windows 以及 Python 3.9-3.14。

[ShaohonChen]

我review了半天SDK代码，居然发现你们已经在分支fix这个问题了hhh

我想能不能考虑对于错误的环境变量，选择忽视而非直接报错。这个只是讨论，好处在于对于部分“环境变量复杂”的生产环境SDK能展现出强大的兼容性。而对于事后行为不一致的场景，也可以通过warning分析回来。

从产品侧来说：其实只要数据上报了，对于SwanLab来说后续通过移动、前端改名等方案都可以把实验转换成想要的形式，一般来说这种方案确实对于用户来说更兼容。可以考虑下。

@SAKURA-CAT @Nexisato @Zeyi-Lin

[ShaohonChen]

我在本地还准备了一个专门忽略“”的方案 ，但是实在太不优雅了。我就不提了。

[SAKURA-CAT]

我review了半天SDK代码，居然发现你们已经在分支fix这个问题了hhh

我想能不能考虑对于错误的环境变量，选择忽视而非直接报错。这个只是讨论，好处在于对于部分“环境变量复杂”的生产环境SDK能展现出强大的兼容性。而对于事后行为不一致的场景，也可以通过warning分析回来。

从产品侧来说：其实只要数据上报了，对于SwanLab来说后续通过移动、前端改名等方案都可以把实验转换成想要的形式，一般来说这种方案确实对于用户来说更兼容。可以考虑下。

@SAKURA-CAT @Nexisato @Zeyi-Lin

我研究一下吧

[SAKURA-CAT]

审核结论: 通过

由于当前账号是 PR 作者，GitHub 不允许自审 APPROVE，因此以 COMMENT 提交通过结论。

本次 PR 解决的问题

将 Settings 从模块导入期加载改为按需创建配置快照，避免非法环境变量或配置文件阻断 import swanlab，同时保留首次消费配置时的校验行为。

审核范围

• 公共 API 与类型兼容: 检查 SDK 导出、Settings 类型及调用方迁移；无对外兼容性 finding
• Run 生命周期与运行时: 检查 init、login、sync 的配置创建与合并顺序
• Record、Core 与传输: 未直接修改；检查 sync 配置传递未引入链路回归
• 配置、认证、API 与 CLI: 检查配置源优先级、全局快照、.netrc、host 与凭据传播
• 媒体、集成与插件: 未直接修改；验证 disabled 与相关生命周期测试
• Protobuf、构建与依赖: 未修改 Proto、构建配置或依赖
• 安全、性能与跨平台兼容: Actions 覆盖 macOS、Ubuntu、Windows 和 Python 3.9-3.14
• 测试与验证: 相关测试、Ruff、basedpyright、完整 pytest 及 PR Actions 均通过

未挂行发现

无。Settings debug 日志中的凭据脱敏属于既有独立问题，已另行记录为 #1726，不作为本 PR finding。

验证

• 相关测试：197 passed
• uv run ruff check .：通过
• uv run --extra dashboard basedpyright：0 errors, 0 warnings
• uv run pytest：1604 passed, 21 skipped
• PR Actions：19 个矩阵任务全部通过