【实现】 ModelScope Provider 半引导登录与 Token 获取流程

[Cai-Tang-www]

关联 RFC / 架构

• 提案/架构 issue：无（本 issue 作为首版落地执行单，后续如需抽象再补上游 RFC）
• 当前问题：
  • 用户在 /provider 选择 modelscope 后，需要自行理解登录、阿里云认证、Token 获取路径，转化成本高。
  • 现有流程缺少“可回退的引导状态机”，失败时用户容易卡住。

目标问题

• 在不代替用户完成实名/登录的前提下，提供“半引导自动化”：
  • 先打开本地/内置 HTML 指导页。
  • 按步骤打开 ModelScope 登录页与目标页面。
  • 根据状态自动跳转 Token 页或阿里云认证页。
  • 最终由用户手动复制 Token 回填到 TUI Provider 输入框。
• 保持职责边界：TUI -> Gateway -> Runtime -> Provider/Tools，不在 TUI 直接写业务流程。

实现设计（How）

• 交互入口：
  • 在 /provider 选择 modelscope 后，进入 ModelScope 绑定向导（Wizard 状态）。
• 流程状态机（Runtime 管理）：
  • INIT：展示说明，优先打开 HTML 指导页。
  • OPEN_LOGIN：打开 https://www.modelscope.cn/（或指定登录页）。
  • CHECK_AUTH：检测是否完成阿里云授权（通过页面引导按钮 + 可选后端状态检查）。
  • OPEN_TOKEN：打开 https://www.modelscope.cn/my/access/token。
  • WAIT_PASTE_TOKEN：提示用户粘贴 Token 到 TUI 输入框。
  • VERIFY_TOKEN：调用 provider 轻量校验接口（或最小探测请求）。
  • DONE / FAILED：成功落盘或给出可恢复的失败原因。
• 失败回退策略：
  • 任一步失败都回到“当前步骤 + 下一步动作”提示，不清空用户已完成步骤。
  • 若检测未授权，则自动引导到 https://www.modelscope.cn/my/settings/account。
• 工具与边界：
  • 打开浏览器动作通过统一工具层执行（internal/tools），Runtime 仅编排。
  • TUI 只渲染状态与输入，不直接调用网页/HTTP 逻辑。
• 配置与扩展：
  • 新增 provider 向导配置项（可选）：guide_html_path、login_url、auth_url、token_url。
  • 允许后续复用到其他 provider（OpenAI/Anthropic 等）。

影响模块

• internal/tui：增加向导视图与 token 回填交互（纯展示+事件输入）。
• internal/runtime：增加 ModelScope 向导状态机、事件派发、失败回退。
• internal/tools：新增/复用“打开 URL”工具能力。
• internal/provider：增加 token 最小校验逻辑（不泄露厂商细节到上层）。
• internal/config：可选新增向导 URL/HTML 配置项。
• docs/：补充 ModelScope Provider 绑定向导文档与故障排查。

边界与非目标

• 非目标：
  • 不自动填写账号密码。
  • 不绕过验证码、实名、阿里云认证流程。
  • 不抓取浏览器 Cookie 或代用户创建 Token。
• 安全约束：
  • Token 仅由用户手工粘贴。
  • 配置不保存明文密钥，仅保存环境变量名或安全存储引用。

任务拆解

• 设计并实现 Runtime 向导状态机与事件协议（含失败回退）。
• TUI 增加 ModelScope 绑定向导页面与 token 输入回填。
• 工具层接入“打开 URL/打开本地 HTML”能力并统一错误包装。
• Provider 增加 token 探测校验接口（最小可用验证）。
• Config 增加可选向导参数并完成校验与默认值处理。
• 文档补齐：用户操作手册、失败场景排查、隐私与安全说明。

测试与验证（Done）

• 正常路径：选择 provider -> 打开指导页 -> 登录/认证 -> 打开 token 页 -> 粘贴 token -> 校验成功。
• 边界条件：
  • 指导页不存在/不可打开。
  • 用户中途关闭浏览器或跳过步骤。
  • 用户粘贴空 token/格式错误 token。
• 异常分支：
  • URL 打开失败、工具超时、校验接口超时/401/429。
  • 未完成阿里云授权时自动回退到认证引导。
• 回归验证：不影响既有 provider 手动配置流程。

验收标准

• 用户在首次配置 ModelScope 时，无需自行摸索链接路径即可完成配置。
• 整体流程可中断、可恢复，失败时有明确下一步。
• 不违反模块边界，不引入明文密钥存储。

风险与回滚

• 风险：
  • ModelScope 页面路径或交互文案变更导致引导失效。
  • 不同平台打开浏览器行为差异（Windows/macOS/Linux）。
• 回滚方案：
  • 提供 manual 模式开关，随时退回“纯文档 + 手动输入 token”。
  • 保留原有 provider 手工配置入口，不阻断主链路。

[Cai-Tang-www]

Implemented in #434

[Cai-Tang-www]

db66283acf07a1e277d49c9b528b32fb619b0e08https://github.com/1024XEngineer/neo-code/pull/434 from Cai-Tang-www/feat/modelscope