HeiCode 浏览器登录流程（客户端 ↔ Manager）

本文给出 Heicode 客户端通过浏览器完成 Manager 登录的端到端流程，并说明字段、错误模型与扩展点。当前实现以 loopback 直接回 token 为主，OAuth2 + PKCE 已在客户端预留。

代码位置：

客户端：cc-haha/src/server/api/heicode-auth.ts

服务端：heicode/controller/heicode_oauth.go、heicode/router/heicode-router.go

一、设计目标

用户启动 Heicode 客户端 → 看到登录卡片 → 点击「浏览器登录」
浏览器跳到 Manager 控制台，完成账号登录
Manager 颁发 / 复用一条专用 Token，回跳客户端 loopback 地址
客户端落地 Token，激活 Provider，自动拉模型列表

整体不要求平台事先支持完整 OAuth2，loopback + token 即可工作；后续可平滑切换到 Authorization Code + PKCE。

二、参与方与端点

端点	谁实现	用途
`POST /api/heicode-auth/oauth/start`	客户端本地服务	生成 `state` / PKCE，返回 authorize URL
`GET /heicode/oauth/authorize`	Manager（heicode）	校验 loopback、引导登录、回跳 token
`GET /heicode/oauth/session`	Manager（heicode）	给「请先登录」过渡页轮询登录态
`GET /api/heicode-auth/oauth/callback`	客户端本地服务	接收 token / code，落地并激活

三、当前实现（loopback + token 直回）

sequenceDiagram
  autonumber
  participant U as 用户
  participant C as Heicode 客户端<br/>(本地 HTTP 服务)
  participant B as 浏览器
  participant M as Heicode Manager<br/>(heicode)

  U->>C: 点击「浏览器登录」
  C->>C: 生成 state / PKCE 并写入会话
  C-->>B: 返回 authorize URL
  B->>M: GET /heicode/oauth/authorize?state=...&redirect_uri=...&provider_id=...
  alt 用户未登录
    M-->>B: 渲染过渡页（链接到 /login）
    loop 每 1.5s
      B->>M: GET /heicode/oauth/session
      M-->>B: { logged_in }
    end
    B->>M: 重新请求 authorize
  end
  M->>M: 校验 loopback redirect_uri
  M->>M: 取或新建名为 "HeiCode" 的 Token
  M-->>B: 302 redirect_uri?state=...&token=sk-XXXX
  B->>C: GET /api/heicode-auth/oauth/callback?token=...&state=...
  C->>C: 校验 state、激活 Provider、拉模型
  C-->>B: 返回成功页（用户可关闭浏览器）

关键校验

state 与 redirect_uri 必填，redirect_uri 必须是 loopback 主机：127.0.0.1 / localhost / ::1
客户端会话过期（默认 5 分钟）后回调直接判失败
客户端默认从 ?token= / ?access_token= / ?apiKey= / ?apikey= 任一字段读取 Token

字段表

名称	在	说明
`state`	URL query	客户端生成的不可猜测随机串，回跳时校验
`redirect_uri`	URL query	必须是 loopback；Manager 会拒绝其它主机
`provider_id`	URL query	`taijiaicloud` / `clawdrouter`；用于客户端识别落到哪个 provider
`token`	回跳 query	Manager 颁发的 HeiCode 专用 Token，前缀 `sk-`
`code` / `code_verifier`	标准 OAuth	当前 loopback 模式不使用；启用 PKCE 时必需
`code_challenge` / `code_challenge_method`	URL query	启用 PKCE 时由客户端附带，方法固定 `S256`
`client_id` / `scope`	URL query	启用 PKCE 时附带，分别来自客户端环境变量

四、扩展形态：标准 OAuth2 + PKCE

当平台具备 token 端点后，仅需在客户端配置环境变量即可启用：

变量	用途
`HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL`	自定义 authorize 端点
`HEICODE_<PROVIDER>_OAUTH_TOKEN_URL`	code → access_token 交换端点
`HEICODE_<PROVIDER>_OAUTH_CLIENT_ID`	OAuth Client ID（启用 PKCE 时必需）
`HEICODE_<PROVIDER>_OAUTH_SCOPE`	申请的 scope，例如 `models:read,messages:write`

详见 [../onboarding/env-variables.md](../onboarding/env-variables.md)。

sequenceDiagram
  participant C as 客户端
  participant B as 浏览器
  participant P as 平台 Authorize
  participant T as 平台 Token

  C->>B: authorize URL?response_type=code&client_id&...&code_challenge
  B->>P: 用户登录授权
  P-->>B: 302 redirect_uri?code=&state=
  B->>C: callback?code=&state=
  C->>T: POST /token { grant_type=authorization_code, code, code_verifier, ... }
  T-->>C: { access_token }
  C->>C: 激活 Provider 并拉模型

五、错误模型

触发	HTTP / 行为	客户端展示
`state` / `redirect_uri` 缺失	Manager 400	浏览器停留报错
`redirect_uri` 非 loopback	Manager 400 `redirect_uri must be a loopback address`	检查客户端配置
用户未登录	Manager 渲染过渡页并轮询 session	浏览器停留并自动跳转
客户端会话过期	客户端 callback 返回错误页	提示「登录会话已过期，请回到 HeiCode 重试」
平台未配置 token 端点但只回了 code	客户端 callback 错误页	提示「平台未配置 token 交换端点」
Provider 模型校验失败	客户端 400	拉模型异常或返回空集

六、与 Agnet API 设计的衔接

这里的 Token 用于 Heicode 客户端调 Manager；Manager 调 Agnet 时应使用服务间令牌或受控委托令牌，具体以 ../saas-manager-agnet-architecture-plan.md 为准
跨链路追踪建议在 Manager 调 Agnet 时附带 X-Heicode-Correlation-Id 与本登录会话关联