feat: ModelScope Provider 半引导登录与 Token 获取流程 (#433)

[Cai-Tang-www]

1. 背景与目标

1.1 背景

当前用户在配置 ModelScope provider 时，需要自行完成以下路径摸索：

• 登录入口
• 阿里云账号绑定入口
• Token 生成入口
• 回填到 TUI 的具体位置

这会导致首次配置成本高、失败路径不清晰，且容易中途退出。

1.2 目标

在不代替用户执行实名/登录/验证码流程的前提下，提供 ModelScope 半引导流程：

1. 从 /provider 直接进入引导
2. 自动打开指导页/登录页/Token 页
3. 用户手动粘贴 Token 到 TUI
4. 进行最小可用校验并完成 provider 切换
5. 认证失败时自动回退至阿里云绑定页

---

2. 需求映射

• 关联 Issue: 【实现】 ModelScope Provider 半引导登录与 Token 获取流程 #433（已关闭）
• PR: feat: ModelScope Provider 半引导登录与 Token 获取流程 (#433) #434
• 闭环：/provider -> 选择 modelscope -> 半引导 -> token 回填 -> 校验 -> 切换成功

---

3. 方案与实现

3.1 配置层（builtin provider）

新增内置 modelscope provider：

• name: modelscope
• driver: openaicompat
• base_url: https://api-inference.modelscope.cn/v1
• model: Qwen/Qwen2.5-7B-Instruct
• api_key_env: MODELSCOPE_API_KEY

涉及：

• internal/config/provider.go
• internal/config/defaults_test.go
• internal/config/provider_test.go
• internal/config/state/service_test.go

3.2 TUI 交互层（半引导状态机）

在 provider picker 选择 modelscope 时：

• 若已检测到 MODELSCOPE_API_KEY（进程环境或用户环境）=> 保持原有切换行为
• 若未检测到 token => 进入 ModelScope Guide 引导态

引导步骤：

1. 优先打开 ~/.neocode/modelscope-guide.html（不存在则降级到登录页）
2. 打开登录页 https://www.modelscope.cn/
3. 打开 token 页 https://www.modelscope.cn/my/access/token
4. 在 TUI 面板粘贴 token 并提交

校验与回退：

• 提交后执行 provider 选择与模型列表拉取（最小可用校验）
• 若错误包含认证/权限特征（如 401/403/unauthorized/forbidden/认证/实名等）
  • 自动回退并打开阿里云绑定页：https://www.modelscope.cn/my/settings/account

涉及：

• internal/tui/core/app/app.go
• internal/tui/core/app/commands.go
• internal/tui/core/app/update.go
• internal/tui/core/app/view.go
• internal/tui/state/ui_state.go
• 对应测试：update_test.go、view_test.go、state_test.go

3.3 基础能力（跨平台打开资源）

新增统一打开外部资源能力（URL/本地 HTML）：

• Windows: cmd /c start
• macOS: open
• Linux: xdg-open

并包含输入归一化与安全校验：

• 支持 http/https/file URL
• 支持本地绝对/相对文件（自动解析绝对路径）
• 拒绝空输入、目录路径、不存在路径

涉及：

• internal/tui/infra/open_resource.go
• internal/tui/infra/open_resource_test.go

3.4 文档更新

• 新增 ModelScope 引导文档
• 更新 README 与配置文档中的 builtin provider 与环境变量列表

涉及：

• docs/guides/modelscope-provider-setup.md
• docs/guides/configuration.md
• docs/guides/adding-providers.md
• README.md

---

4. 职责边界与安全性

• 未在 TUI 中实现登录/实名自动化，不绕过验证码与实名逻辑
• token 仍由用户手工粘贴
• 不在配置中写入明文 key，仅使用环境变量名
• 保持现有主链路边界，不将厂商差异扩散到 runtime 上层

---

5. 测试与验证

已执行（聚焦本次改动路径）：

• go test ./internal/config -run "ModelScope|DefaultProviders|DefaultProvidersIncludesBuiltinProviders|LoaderRejectsCustomProviderNameConflictingWithBuiltin"
• go test ./internal/config/state -run "ListProviderOptionsUsesCatalogModels"
• go test ./internal/tui/infra -run "OpenResource|NormalizeOpenResourceTarget"
• go test ./internal/tui/core/app -run "ModelScope|UpdatePickerProviderAndModelEnter|RenderPickerProviderAndFileMode"
• go test ./internal/tui/state -run "TestPanelAndPickerConstants"

说明：

• 在当前 Windows 环境下，internal/config 全量中存在历史无关用例偶发权限报错（fsyncDirectory），本 PR 采用定向测试集验证改动闭环。

---

6. 兼容性与回归影响

• 对已有 provider 流程无破坏性变更
• 仅当选择 modelscope 且缺少 token 时进入新引导
• 其他 provider 仍保持原行为

---

7. 回滚策略

若引导流程在特定平台异常，可快速回退：

1. 移除 modelscope guide picker 分支（pickerModelScopeGuide）
2. 保留 builtin provider 定义
3. 恢复到纯手动 token 环境变量配置模式

---

8. Checklist

• 新增 builtin modelscope provider
• /provider 选择后自动进入半引导（缺 token 场景）
• 支持指导页/登录页/token页跳转
• 支持 token 粘贴与最小可用校验
• 认证失败自动回退阿里云绑定页
• 新增跨平台打开资源能力与测试
• 文档更新

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[codecov]

Codecov Report

❌ Patch coverage is 95.02618% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/tui/core/app/update.go	93.22%	13 Missing and 4 partials ⚠️
internal/tui/infra/open_resource.go	97.43%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Cai-Tang-www]

@xgopilot 严格review此次pr

[Cai-Tang-www]

/code 提高测试覆盖率到95

[fennoai]

结果

已按你的要求补测并提升本次 PR 变更覆盖率到 95% 以上，相关提交已推送到当前 PR 分支 feat/modelscope（commit: a50d6fe）。

本次改动

• 新增/补充测试：
• internal/tui/core/app/update_test.go
• internal/tui/core/app/view_test.go
• internal/tui/infra/open_resource_test.go
• 重点覆盖了 ModelScope 半引导状态机分支、提交回滚/错误聚合路径、引导页渲染分支，以及跨平台资源打开与 file:// 解析的边界分支。

验证结果

• go test ./internal/config ./internal/config/state ./internal/tui/core/app ./internal/tui/infra ./internal/tui/state -coverprofile=/tmp/pr.cover.out
• 包覆盖率：
• internal/tui/core/app: 89.5%
• internal/tui/infra: 91.9%
• 基于 origin/main...HEAD 变更行统计（instrumented changed lines）：95.99%

未做事项

• 未改动生产代码逻辑，仅补充测试覆盖。

View job run

[Cai-Tang-www]

/review

[Cai-Tang-www]

/simplify

[fennoai]

完成情况

已按触发评论要求完成：先检查历史评论，再修复值得修复的问题，并使用 code-simplifier agent 做简化复核。

已处理项

1. 读取并评估评论日志中的未解决 review 评论。
2. 修复 internal/tui/core/app/update.go 中状态推进问题：

• 在 handleModelScopeGuideOpenResultMsg 中，改为按 openedTarget 决定是否推进步骤。
• 避免认证失败回退到 modelScopeGuideStepToken 后，打开阿里云绑定页时被错误推进到 PasteToken。

3. 同步调整并增强测试 internal/tui/core/app/update_test.go：

• 覆盖 token -> auth page 不应推进步骤的回归场景。
• 补充成功分支状态字段断言，保证状态机行为可验证。

4. 按要求调用 code-simplifier agent 复核并收敛为当前最小实现。

验证

已执行：

• go test ./internal/tui/core/app -run 'TestHandleModelScopeGuideOpenResultMsgTransitionsAndErrors|TestHandleModelScopeGuideInputStepTransitionsAndEditing|TestHandleModelScopeGuideSubmitResultMsgBranches|TestHandleModelScopeGuideSubmitResultMsgAuthFallback'

提交与推送

• Commit: 1f9993c
• 已推送到分支：fork-pr-434-1776995685

未执行项

• 未额外改动其他历史评论中非本次触发要求的内容。

View job run

[phantom5099]

/review

[fennoai]

完成四轮审查（代码质量、性能、安全、文档一致性）并去重后，发现 1 个需要修复的问题。

[fennoai]

handleModelScopeGuideOpenResultMsg 在 modelScopeGuideStepToken 分支中会无条件推进到 modelScopeGuideStepPasteToken。这会破坏认证失败回退链路：handleModelScopeGuideSubmitResultMsg 在 auth/permission 错误时把步骤设回 modelScopeGuideStepToken 并打开 modelScopeAuthURL，但打开完成后这里会直接跳到“粘贴 Token”。建议按 msg.Target 决定是否推进（仅当成功打开 modelScopeTokenURL 时进入 PasteToken，打开 modelScopeAuthURL 时保持在 Token）。

[Cai-Tang-www]

/simplify

[fennoai]

完成情况

已按触发要求完成：先读取评论日志并处理值得修复的问题，再调用 code-simplifier 做简化。

处理结果

1. 已评估历史未解决 review 评论并修复核心问题。

• 修复点：internal/tui/core/app/update.go
• 行为调整：handleModelScopeGuideOpenResultMsg 在 Token 步骤下仅当打开目标为 modelScopeTokenURL 时才推进到 PasteToken；若打开的是认证绑定页 modelScopeAuthURL，保持在 Token。

2. 已在 code-simplifier 复核后收敛代码。

• 提炼了引导流程中的小型 helper，减少重复分支并保持状态机语义不变。
• 对应测试做了等价简化与补强（包含 auth 页面不推进步骤的回归断言）。

3. 已执行定向测试并通过。

• go test ./internal/tui/core/app -run 'TestHandleModelScopeGuideInputStepTransitionsAndEditing|TestHandleModelScopeGuideOpenResultMsgTransitionsAndErrors|TestModelScopeGuideOpenTarget|TestAdvanceModelScopeGuideStep|TestHandleModelScopeGuideSubmitResultMsgAuthFallback'

提交与推送

• Commit: 681ad26
• 已推送到当前 PR 头分支：Cai-Tang-www:feat/modelscope

未执行项

• 未处理触发指令之外的其他历史评论请求。

View job run