maya/Rainytoken
1
0
Fork 0
Code Issues 4 Pull Requests Actions 38 Packages Projects Releases 28 Wiki Activity
571b270cb6
Rainytoken/docs/FEATURE-PLAN.md

11 KiB
Raw Blame History

RainyToken 二开：功能设计（FEATURE-PLAN）

状态：已实现 + 多轮独立审计定稿（v1.0 · 2026-09-11） 依据：用户需求 + 实测调研（Sub2API / Trae / WorkBuddy 三家接口均经真实登录态实测，字段与口径已定稿；见 §5）。

0. 需求清单（用户原话提炼）

  1. 新增供应商：Trae、WorkBuddy（腾讯）、sub2api（自托管）
  2. DeepSeek 支持充值：App 内 WebView 打开官方充值页
  3. 首页仅显示已配置的服务（有凭据就显示）
  4. 新增「API 管理」页：按供应商集中展示/管理已保存的 API Key（含状态、新增/编辑/删除/测试）
  5. 用量单独一页：独立的用量统计页（不塞进 API 管理页）
  6. 约束：任何人都能用 sub2api（配置各自的实例地址+凭据），不只是本机；全程遵守 taste.md（独立审计→同代理复审→通过才收尾；实测优先；凭据仅实测不落码；不擅自提交推送）。

1. 现有扩展点（改前理解结论）

层 文件 新增服务需改动
服务枚举 app/src/main/java/com/rainy/token/domain/service/ServiceType.kt 加枚举项（storageKey 稳定）
服务配置 app/src/main/java/com/rainy/token/domain/service/ServiceConfigProvider.kt 加 config；FetchMethod 视情况扩枚举（如自托管 REST）
凭据模型 app/src/main/java/com/rainy/token/domain/model/Credential.kt 密封类加子类
凭据指纹 data/repository/CredentialRepository.kt（cacheIdentityFingerprint / credentialFingerprint 两处 when） 密封类新增子类后编译器强制补分支（无 else 的 when）
刷新用例 domain/usecase/RefreshBalanceUseCase.kt（硬编码 when(service) + Provider<XxxRepository>） 加分支 + 注入新仓库
DI di/NetworkModule.kt（@Provides） 加 @Provides 显式构造（规避 KSP 2.x 跨文件误报）
凭据表单 ui/settings/CredentialEditScreen.kt + CredentialEditViewModel.kt 为新凭据类型加表单分支
详情卡片 ui/servicedetail/ServiceDetailScreen.kt（when(service) 分卡） 加分支或抽象
图标 ui/components/ServiceIcon.kt 加分支 + drawable
字符串 res/values/strings.xml（en）+ values-b+zh+Hans + values-b+zh+Hant 新增 key 三处同步
导航 ui/RainyTokenNavHost.kt（Compact 单栈 + Expanded 双窗格两套） 新页面两处都要接

2. 功能分期

阶段 P1（不依赖调研，立即做）

  • 首页仅显示已配置：DashboardViewModel.loadFromCache() / refresh() 由 ServiceType.entries.map 改为过滤 state != NOT_CONFIGURED；首页空态给引导文案（空列表 → 提示"请先在设置/API 管理里配置服务"+ 配置入口）。
  • DeepSeek 充值：
    • ServiceConfig 增加 externalUrl（DEEPSEEK = https://platform.deepseek.com/top_up）。
    • 新增通用 WebViewPageScreen（URL 容器，复用 WebViewLoginScreen 的 AndroidView WebView 模式，BackHandler + 进度）。
    • ServiceDetailScreen DS 详情加「充值」按钮 → 路由到 WebView 页；API 管理页同款按钮。
  • API 管理页：新增 ui/account/ApiManagementScreen + ViewModel：列出全部服务（含未配置），各卡片显示图标/名称/状态 chip/Key 掩码/最后验证/操作（编辑→credentialEdit、删除、测试、充值 for DS）。入口：Dashboard 顶栏图标 + 设置页列表项。
  • 用量页（独立）：新增 ui/usage/UsageStatScreen：按配置的服务聚合缓存余额与用量指标（amount/unit/monthlySpent/totalQuota/nextResetAt/extras 摘要），可一键全部刷新；并保留既有用量详情/图表/热力入口作为二级页。入口：Dashboard 顶栏图标。

阶段 P2（依赖三方调研回报，统一落地）

  • Trae（调研已回，2026-09-11）：
    • 取数凭据 = Cloud-IDE-JWT（RS256 JWT，~14 天有效期），请求头 Authorization: Cloud-IDE-JWT <jwt>；CN 需 X-User-Region: CN + X-Device-Id + 插件 UA；缺 device 绑定会触发 1001/9074 风控。
    • 用户获取方式：浏览器登录 Trae 后从 DevTools Network / 授权回调链接复制 JWT（走 traework2api 同款 /authorization 回调粘贴流程）。
    • 核心端点：
      • CN 积分池：POST https://api.trae.cn/trae/api/v2/pay/ide_user_ent_usage（user_entitlement_pack_list[].entitlement_base_info.quota.credits_limit − usage.credits_amount）
      • CN 套餐状态：POST https://api.trae.cn/trae/api/v1/pay/ide_user_pay_status
      • 兑换 token：POST https://api.trae.com.cn/cloudide/api/v3/trae/oauth/ExchangeToken
      • Intl：https://grow-normal.trae.ai/trae/api/v1/pay/ide_user_ent_usage 等（v1）
    • 参考实现：Sliverkiss/traework2api · mmqz/cpa-multi-plugins · diegosouzapw/OmniRoute（trae.ts）
    • 凭据模型：Credential.TraeCredential(jwt, region)（简化为单字段 JWT + 地区优化显示）。
  • WorkBuddy（腾讯）（调研已回，2026-09-11）：
    • 产品=腾讯 AI 办公 Agent（workbuddy.qq.com → 301 → www.codebuddy.cn/work/），与 CodeBuddy 共用积分(Credits)体系；无公开 API。
    • 取数 = OAuth Bearer token 流程（非 cookie）：设备授权 POST https://copilot.tencent.com/v2/plugin/auth/state?platform=CLI → 微信/QQ 扫码 → GET .../v2/plugin/auth/token?state= 拿 accessToken/refreshToken → 保活刷新 POST .../v2/plugin/auth/token/refresh（头 X-Refresh-Token）。
    • 余额接口：POST https://www.codebuddy.cn/v2/billing/meter/get-user-resource，Authorization: Bearer <accessToken>，体含 "ProductCode":"p_tcaca"，响应 Accounts[].CycleCapacityRemain/Used/Size 累加得可用/已用/总额。
    • 凭据模型：复用 Codex 的 OAuth 模式（accessToken/refreshToken），新增 Credential.WorkBuddyCredential（含 refresh）。细节待真实账号实测回填。
    • 参考实现：Sliverkiss/workbuddy2api · mmqz/cpa-multi-plugins（billing.go）。
  • Sub2API（自托管，任人可用）（调研已回，2026-09-11，源码实读：research-sub2api，HEAD cdb5cfaf）：
    • 各上游订阅 = 后台「账号(Accounts)」，管理 API 全部在 {实例}/api/v1/admin/*，与对外 OpenAI 网关分离。
    • 认证：POST {base}/api/v1/auth/login（{"email","password"}；可被 TOTP-2FA / 验证码 / backend-mode 拦；返 access_token/refresh_token）；或 x-api-key: <admin-api-key>（免登录）。新版有合规 423 闸门：未 accept 时 /admin/* 全 423，需先 POST /api/v1/admin/compliance/accept。
    • 查询序列（最小）：GET /admin/accounts（列表/详情）→ POST /admin/accounts/usage/batch（source=passive，不打上游、带缓存，适合 App 轮询）→ 按平台打 openai|grok|cn-providers/.../quota|balance（实时余额）。
    • 字段以 optional 防御式解析（项目近每日发版、响应字段多变）。
    • 凭据模型：Credential.Sub2ApiCredential(baseUrl, email, password, apiKey?)；ServiceConfig 需支持自定义 baseUrl（FetchMethod.SELF_HOSTED_REST）。
  • 新服务的表单/测试/详情卡/图标/字符串全链路补齐；三者的取数接口都用真实凭据实测后再定稿字段映射。

3. 关键设计决策

  1. “有凭据就显示”：以 CredentialStatus.State != NOT_CONFIGURED 为准（任一凭据存在即算配置），不要求最近验证成功（用户已选）。
  2. 充值交互：App 内 WebView（用户已选）；WebView 内完成登录+充值，返回键退出页面。
  3. 用量页判据：展示已配置服务的缓存用量（无网也可见）；未配置服务不展示。
  4. API 管理与用量分离：API 页只管 Key/凭据；用量单独一页（用户已选）。
  5. 凭据安全：任何新凭据只进 SecureStorage，指纹化展示；新子类强制补 CredentialRepository 指纹分支。
  6. 实测优先：新供应商接口以调研/实测回报为准回填，不臆造字段。

4. 测试与审计计划

  • P1 每完成一块：.\gradlew.bat :app:assembleDebug（CI=true）编译验证。
  • 代码修改后用独立 subagent 审计（无阻断 + 无 UX 问题），修复后同 subagent 复审，通过才收尾（taste.md 强制）。
  • 不开 Commit/Push（user 未授权）。
  • 新供应商接口回填后，用真实凭据实测（仅验证，不落码）。

5. 实施状态（2026 goal round 4）

  • ✅ P1a 首页仅显示已配置（含空态引导）——独立审计 + 同代理复审通过
  • ✅ P1b DeepSeek 充值（App 内 WebView）——审计修复 + 复审通过
  • ✅ P1c API 管理页（集中管理/测试/删除/DS 充值入口）——[A] 修复确认 + 复审通过
  • ✅ P1d 用量统计页（独立页面，含失败计数/防闪/extras 过滤三修）——随 P2 审计确认生效
  • ✅ P2 数据/领域层：TraeRepository / WorkBuddyRepository / Sub2ApiRepository + 凭据子类
    • 指纹双 when + ServiceType/Config(FetchMethod.SELF_HOSTED_REST)/RefreshBalanceUseCase/NetworkModule —— 独立审计无阻断；F1–F4 已修（缓存身份稳定化 / 负数钳制+数值放宽 / 423 透传 / Sub2Api 掩码改实例基址），F1–F4 复审通过
  • ✅ P2 专用凭据表单（Trae JWT+区域 / WorkBuddy tokens / Sub2API 实例+认证二选一）三语
  • ✅ Sub2API 实测（xxcsn.site，goal round 4）：确认【普通用户用 sk- API Key + GET /v1/usage】即可查余额/用量（无需管理员）。 仓库从 admin 方向重写为用户级（Bearer sk- → /v1/usage，404 兜底 /api/v1/usage；remaining/balance/unit/isValid/usage.total.cost/model_stats/daily_usage 实测校准；login email/password 备选）； 独立审计通过（无阻断）+ 同代理复审通过；3 条建议已落实（desc 用户级文案/acceptCompliance KDoc/清导入）
  • ✅ 全量最终审计（55682c88）：无[阻断]、可收尾；建议1（delete 清理表单字段）已修并复审通过；建议2（test 双击竞态）评估不改；提示项（gradle 本地开关/AGP 补丁、充值 WebView 无会话持久化）已记录。
  • ✅ Trae / WorkBuddy 实测校准（goal round 5，经用户授权用 logged-in 浏览器调官方接口，全程不落凭据）：
    • Trae：POST api.trae.cn/trae/api/v2/pay/ide_user_ent_usage 仅 Authorization:Cloud-IDE-JWT(+Content-Type) 即 200； 权威口径 usage_summary.total_amount-consumed_amount；pack 用 display_desc/credits_limit(-1=∞)/usage.credits_amount； → TraeRepository 重写（去 X-Device-Id/Region 头、usage_summary 优先、包级兜底）
    • WorkBuddy：POST www.workbuddy.cn/billing/meter/get-user-resource-summary → data.Packages； → WorkBuddyRepository 重写（主端点 workbuddy.cn + codebuddy.cn 兜底、refresh 轮换保留）
  • ✅ 两仓库实测校准独立审计（924f04e0）：通过（无阻断）；5 项建议落实（unit 定案 Credits 且生效化/空体 EMPTY_BODY/无数据 ParseError/清未用 import/语义保留）+ 同代理复审通过；微观察②（单包明细单位）修复后再次确认通过 —— Trae 与 WorkBuddy 实测校准正式定稿
  • ✅ 收尾（goal round 5）：三家新供应商（Sub2API/Trae/WorkBuddy)全部实测校准+审计+复审定稿； 原始二开目标 ①-④ 全部达成且审计闭环；assembleDebug/assembleRelease 均绿； 未提交未推送（用户授权前保持工作区本地状态）