[shadyrispy]

接入 AtomGit / GitCode 的 AtomCode 渠道。上游本身就是 OpenAI Chat Completions，转发层不做协议翻译；另含服务端中介的轮询式网页登录，以及把「按需领取免费 CodingPlan」挂进每日签到链。

渠道本体

三条平面各一个域，不混用：

用途	基址	端点
登录代理（OAuth）	https://acs.atomgit.com	/auth/login?provider=atomgit → 轮询 /auth/check?state= → /auth/token?state=；续期 POST /oauth/refresh
CodingPlan REST	https://api.gitcode.com/api/v5	models-v2?plan_type=<Max|Pro|Lite>、status-v2、claim-v2、usage
聊天网关	https://api-ai.gitcode.com/v1	POST /chat/completions

• 网关用 api-ai.gitcode.com，不是官方 CLI 默认的 llm-api.atomgit.com：后者要求一套闭源请求签名（atomcode-codingplan-crypto，开源树里只有一个 unreachable!() 占位）。而网关按 User-Agent 决定要不要签名 —— 同一条有效 bearer、同一个请求体、只改 UA 的判别式实测（2026-10-01，打在 POST /v1/chat/completions）：

    (不带 User-Agent)          -> 200 正常回答
    curl/8.5.0                 -> 200 正常回答
    cpa-jethub-atomcode/0.1.0  -> 200 正常回答
    atomcode/5.2.0             -> 403 {"detail":{"code":"ATOMCODE_SIG_MISSING"}}
    atomcode/5.1.0             -> 403 同上
  

  所以 ADAPTER_USER_AGENT 是功能性常量，endpoints.rs 里有回归断言钉住「不得自称官方客户端」。

• models-v2 每个条目自带的 base_url 指向需要签名的官方网关，只展示不采用。

• 条目里 id 是数字，模型名是 display_model_name（如 glm5.3-flash）。发数字 id 不会报错，网关回 200 + 正文「参数错误」—— 字段取错会伪装成「参数不被接受」。

• 令牌不是 JWT（代理下发不透明随机串，读不到 exp），过期只能由 created_at + expires_in 推。

• 续期轮换：/oauth/refresh 同时下发新 access 与新 refresh，旧 access 立即失效。因此续期做了单飞（键含两个令牌的指纹），且新值非空才覆盖 —— 代理会省略 refresh_token，整包替换等于让账号失去续期能力。

网页登录

授权回调由代理自己在 acs.atomgit.com/callback 终结，不回本机。所以本家没有 loopback 监听、没有回调端口，与 ZCode / OfficeAce 同形（core/login/atomcode.rs）。

supports_web_login() 保持默认 false 是有意的：那三个钩子（build_login_url / exchange_login_code）是给「回调带回一次性 code」那类用的，覆写会让路由层去等一个永远不到达本机的回调（症状是用户授权成功后界面一直挂着）。OfficeAce 同样没有覆写这个位。分派走 api::session::login_start 的按 provider 分支；壳侧只在 allowed_hosts 里显式放行 —— 落进默认分支会拿到 WorkBuddy 的白名单，窗口白屏且日志无痕。

签到：按需领取 CodingPlan

免费套餐是一次性授权，不是每天发额。挂在签到链上，是因为「新账号必须领一次，否则目录为空、什么都调不动」与「套餐到期要能续领」都需要一个逐账号、每天跑一次、带台账的调度。

• 先探测 status-v2：codingplan_free.expires_at 非空或 remaining_days > 0 即有效，直接跳过领取，只回读套餐名与额度窗口，报「套餐有效中，无需领取」（success:false + 说明 —— 报成功会被日志与界面说成「今天签到了」，而其实什么都没发生）。无效才级联。

• 级联 Max → Pro → Lite，停规则照官方 setup.rs:825-918：duplicate:true 停（已持有）、success:true 停（本次发放）、两者皆 false 记文案试下一档、传输或 5xx 整条中止（换档位修不好连接）。

• 判成功不能只看 HTTP 200：响应里带 duplicate 字段，报文是 {"success":false,"duplicate":true,"message":"已领取"}。把它当失败会让级联继续往下试，把用户从 Pro 降到 Lite（官方 client.rs:203-207 写了这条）。判定顺序 duplicate 先于 success，有用例钉住。

  这一处纠正了一份文档的错：cpa-jethub-plugins 的 atomcode README 写「claim-v2 没有幂等标记、重复领取只会再回 success:true」，与源码不符 —— Duplicate 字段就在响应结构里（credits.go:149）。以源码为准。

• 领到或档位变化后强制刷目录：models-v2 的 plan_available 是相对被问的档位算的，不刷会出现「领到了却看不到新模型」。

额度读数（一并修一处会误拦账号的缺陷）

限额判定走 usage_records::extract_remaining，规则是 unlimited → 判不出；否则 totalLeft；否则 available 一旦出现就当成真实读数。

原先在没有解析出任何窗口时也写 available: 0，于是「这份响应我没读懂」被当成「余额确实为 0」，账号被限制器标成「余额不足 / 已跳过」。dev 库里的记录正是这个形态：available=0 / wallets=[] / error=None（查询成功、一个窗口都没解出来）。现在只在确实解析出窗口时才写 available，subscription 里的 remainQuota / totalQuota 同样收紧；读不到就只回 wallets: []，记录被 usage_records 摘除、不拦账号，余额列留空。

顺带一处取证便利：shape_usage 把上游原文放在归一化结果的 raw 键里，而 account_usage_records.usage 一列就是它，从库里能读到完整 status-v2 原文；另加了一条只记顶层键名与两条额度数组的详细日志。

未做

网关拒绝时不返回错误状态，而是回一条看起来正常的回答：模型不在套餐内或参数不被接受 → 200 + 正文「参数错误」；模型被列出但后端坏了 → 200 + 正文是上游 HTML 报错页。识别与渲染写在 errors.rs（含「模型正常复述这些词时不算失败」的误判护栏），但本仓 SSE 出口目前只有「改 model 名」「丢纯换行分片」两个标志位，没有按帧判错误的钩子，所以还没有调用点。

没接的原因：已知的「200 + 参数错误」是非流式实测，流式形态未测，判据选错会双向出错（把正常答复判成错误，或继续漏判）；照搬 upstream::refusal 那套（整段预读）会让本家所有请求退化成「生成完才下发」。实测还发现套餐正常时这条路走不到 —— 哨兵由模型名驱动（未知模型名 / 后端坏模型），而入口按广告清单校验、未知名字回 400 不转发；temperature:99 这类非法参数被网关静默忽略，不触发哨兵。能触发它的只有「套餐到期或被撤销后仍请求已广告的模型」，或从未领过套餐的账号。

验证

dev（agent2api:dev-3.0.8-3）上逐段跑通：

• 登录：账号落库并启用。
• 领取：点签到 → claimed_at 2026-10-17、status 1、到期 10-24、Lite 档，签到记录 outcome=success。
• 目录：/v1/models 广告 2 条，qwen3.8-27b（262144 上下文）与 glm5.3-flash（512000），都可读图、都会思考。
• 额度：available 200，窗口 200 次 / 5 小时，resetAt 17:18。
• 非流式：200，真回答 + usage（prompt 17 / completion 32 / total 49）。
• 流式：10 帧，content「收到」 → finish_reason "stop" → usage 帧 → [DONE]。
• 记账：requests 三行，provider=atomcode、status 200、token 与上游一致。

后两段是拿 dev 网关 key 自测的，目录那段从 NAS 本机免 key 即可读。顺带一个观测：领取前后目录 3 → 2 条（同一个 Lite 档位），上游的 plan_available 依赖套餐是否已激活，不只是档位。

cargo test -p agent2api-server：基点 beta 4f0040f 同命令实跑 638 passed / 8 ignored，本 PR 699 passed / 8 ignored ⇒ 净增 61 条。

影响面

新家，不改既有各家的转发与选路行为。改动落在这些登记点（供完整性核对）：providers/mod.rs 五处（pub mod / ProviderKind / PROVIDERS / kind_from_id / kind_id）、adapter.rs 两处（adapter_for / implemented_kinds）、catalog.rs、catalog_cache.rs 的 scope、account_store 的 mod.rs 与 store_view.rs 加新模块 atomcode_accounts.rs（公开形态同时摘掉 accessToken 与 refreshToken）、api/accounts.rs 的添加与刷新两个分派、api/session.rs 与 core/login.rs 的登录分派、签到链四处（CHECKIN_PROVIDERS 13→14、PROVIDERS_VERSION 3→4 及增量登记、checkin_for 分支、签到页描述与五语言词典）、ui-islands 三处、壳侧 allowed_hosts、以及图标（官网产品图，归一成 256×256）。

ui/islands/* 与 ui/i18n/** 都是入库产物：改了 i18n-src 要跑 npm --prefix desktop-tauri/i18n run build（该包的繁中依赖 opencc-js，需先 npm ci），否则 frontend-artifacts 会判「产物与源码不同源」。