--- name: api2business description: >- Api2Business 开发、配置、部署和运行维护技能。用户要求安装、部署、升级、验证、 排查 Api2Business，或操作账号、评分、上游、成本和经营核算时使用。 --- # Api2Business - 本技能遵循 Skill(cli-spec)。 ## 当前 Sub2API 架构 - 唯一 Sub2API 运行面是 NC01 的 `sub2api-nc01-native`。 - 唯一 Sub2API 业务数据库是 NC01 本地专用 PostgreSQL `127.0.0.1:55432/sub2api`。 - `api.pikapython.com`、`api.hwpod.com` 和 `sub.api2business.com` 只是入口或代理， 不代表数据库 authority。 - 禁止将旧 PK01 或 `NC01-DOCKER` 的数据库地址写入配置、Secret、CLI 参数或示例。 ## Api2Business L1 唯一运行面 - `https://api2business.hwpod.com` 是 Api2Business 唯一 L1 实例、唯一业务入口和唯一验收入口。 - CLI 的唯一 HTTP target 使用该公网地址；不得再配置或交付 `native-api`、`production`、`local` 等并列业务 target。 - 本机监听地址、Docker Compose/native profile 和 worker 内部回环地址只是唯一 L1 实例的实现细节，不构成第二个实例。 - `localhost`、`127.0.0.1` 和嵌入式 CLI 只能用于受控故障诊断或构建检查，不得用于业务结果、截图验收或邮件交付。 - L1 的 API、Web、worker、Temporal、数据库和账本必须由同一 owning 配置和同一公网入口关联；发现数据不一致时先修复入口映射，禁止创建并列实例。 ## 工作区 - 新部署先克隆 `https://github.com/api2business/api2business.git`，再从克隆后的仓库加载本 skill。 - 从当前 Api2Business 仓库根目录执行命令。 - 使用 `config/api2business.yaml` 保存唯一 L1 的运行配置；该文件不得提交。 - 使用 `skills/api2business/scripts/api2business-cli.ts` 执行业务和生命周期操作。 ## 从零部署（Bootstrap） 1. 准备 Git、Bun、PostgreSQL、Temporal 和可访问的 Sub2API 管理面。 2. 克隆仓库并进入工作区： ```bash git clone https://github.com/api2business/api2business.git cd api2business ``` 3. 从克隆后的仓库加载 `skills/api2business/SKILL.md`，再读取 `docs/reference/deployment.md`；不得从其他仓库或运行容器复制部署逻辑。 4. 安装依赖并创建不提交的本机配置： ```bash bun install --frozen-lockfile cp config/api2business.example.yaml config/api2business.yaml ``` 5. 在仓库外准备 Secret 和持久化状态目录： - Secret 文件仅允许 owner 读取； - 配置只保存 `sourceRef`、环境变量名或挂载路径； - PostgreSQL 经营数据、账本、缓存和采样不得写入 Git 工作区。 6. 根据目标环境填写 `config/api2business.yaml`，再执行： ```bash bun skills/api2business/scripts/api2business-cli.ts \ --config config/api2business.yaml \ config validate bun run deploy:validate bun skills/api2business/scripts/api2business-cli.ts \ --config config/api2business.yaml \ native start --component all bun skills/api2business/scripts/api2business-cli.ts \ --config config/api2business.yaml \ native status --component all --json ``` 7. 按“验收”章节完成检查： - 检查登录、主要数据页和至少一个异步作业； - 检查重启后的账本、缓存、采样和作业状态； - 任一步失败时停止在首个断点，不跳过配置或 Secret 校验。 ## 部署 - 先读取 `docs/reference/deployment.md`。 - 确认当前目录是已克隆的 Api2Business Git 工作区，不从运行容器或其他仓库拼装部署资产。 - 根据目标环境选择 Compose、Kubernetes、systemd、托管容器或其他部署方式。 - 不假定特定 CI/CD、代码托管、集群、主机名或网络入口。 - 发布前执行 `bun run deploy:validate`。 - 使用镜像摘要和配置摘要确认运行版本，禁止使用运行容器作为配置真相。 ## Secret - Secret 只保存在仓库外。 - 通过配置中的 `sourceRef`、环境变量、只读文件或外部 Secret 管理器注入。 - 只输出 presence、fingerprint 和有界摘要，不输出值。 ## 生命周期 ```bash bun skills/api2business/scripts/api2business-cli.ts --config config/api2business.yaml native start --component all bun skills/api2business/scripts/api2business-cli.ts --config config/api2business.yaml native status --component all bun skills/api2business/scripts/api2business-cli.ts --config config/api2business.yaml native logs --component all --tail 100 bun skills/api2business/scripts/api2business-cli.ts --config config/api2business.yaml native stop --component all ``` - `native` 是唯一 L1 实例的生命周期入口，实际运行方式由配置选择；生命周期操作不得创建第二个业务实例。 - API 应快速返回作业 ID，长流程由 worker 执行。 - 数据库读取使用应用内排队读取通道，不从外部脚本直接连接业务数据库。 ## 领域操作 - 账号导入、生命周期和空闲探活读取 `references/account-operations.md`。 - 账号导入可用历史参数名 `--rate-multiplier <正整数>` 调整负载因子；该参数在导入 payload 中必须写入 Sub2API 原生 `load_factor`，不得写入计费倍率 `rate_multiplier`。省略时读取 `operations.accountImportDefaults.rateMultiplier`，普通导入与 BugTeam 购买导入共用该字段。 - 普通 OpenAI OAuth 导入若未提供有效的 `credentials.model_mapping`，自动写入当前 OpenAI 模型白名单并排除 `gpt-5.6-luna`；已有显式映射保持不变。 - 已有 OpenAI OAuth 账号可用 `accounts models disable-luna --accounts --confirm --over-api` 通过 Sub2API runtime 批量写入不含 Luna 的模型白名单；命令先校验 全部目标均为 OpenAI OAuth，校验失败时不写入任何账号。 - 该默认限制只作用于普通 OAuth 导入；API-key、Grok OAuth 和 `cutoffTrigger=public-recovery` 的复活导入不套用该策略。 - OAuth 退役计划可用 `--plan-type` 限定账号类型： - 默认 `--selection dead` 选择错误账号；`free`、`plus` 和 `team` 的限流账号也按死亡处理，`k12` 限流账号保留； - 显式 `--selection all` 选择指定单一类型的全部当前账号，且只允许用于整池范围。 - 退役清理边界： - 用户说“清理账号”或“退役账号”时，只允许处理 `platform=openai` 且 `type=oauth` 的账号。 - API-key 账号禁止进入退役结算、删除或清理流程，即使它们属于同一业务池。 - API-key 账号只能通过独立的上游管理流程处理，不得使用 OAuth 生命周期入口替代。 - 对缺少采购成本记录的整池账号，先用 `--scope pool --plan-type --unit-cost-cny ` 显式声明本批结算单价；该模式只支持单一账号类型，并在计划与确认回读中固定成本。 - 退役删除按 `operations.accountLifecycle.deleteBatchSize` 分批调用原生批量接口；单批失败会跳过并继续，终态只以排队回读为准，失败且有剩余账号时复用原计划恢复。 - 上游、评分、优先级、定时稳定性观察和截图报错归因读取 `references/upstream-scheduling.md`。 - API-key 切号模板由 owning YAML 的 `operations.upstreamManagement.templateFiles` 管理： `codex.yaml` 只给 OpenAI，`claude.yaml` 只给 Anthropic；Grok 不套模板。 - 多轮号池优化先读取该参考的“评分、容量与冷却联动评估”： - 分开核对滚动分、固定时间段业务记录、账号容量和会话绑定； - 模板及排序变更必须独立回读运行态，不以工作流成功代替业务恢复。 - 池级质量调查使用 `scores pool-quality --over-api`，该查询只读。 - 账号评分只有一条计算路径。 - `scores get` 只读取账号评分快照，不重新计算。 - `scores rank --calls --over-api` 先按这 N 次刷新同一份快照，再读取刚写入的快照。 - 单账号质量评分将绑定该账号的专用探活样本纳入评分： - 用户请求不足时，用探活补充可靠性、切号和延迟证据； - 探活失败属于该账号的有效质量信号，不得笼统视为评分污染。 - 池级 `scores pool-quality` 仍排除内部 monitor 和 `api2business-probe-*` 探活： - 池分只反映真实用户业务； - 比较账号分与池分时必须同时报告样本范围。 - 优先级计划采用严格线性加权：可靠性、TTFT、证据、探索、余额加分，实际人民币成本扣分；不得使用置信度乘总分、池分与账号分相乘、动态质量反馈或新增硬门槛。 - `scores rank` 对 TTFT 样本不足的账号输出固定 `ttftPriorScore` 与 `latencyEvidence=prior`；`scores priority-plan` 单独输出 `evidenceScore`、成本锚点来源及线性分项。 - 切号质量同时输出原始、已恢复、未恢复和有效切号率；有效率按 `未恢复 + 0.25 × 已恢复` 计入账号评分。 - `scores pool-quality` 输出错误归因完整度；未归属错误只作为池级数据质量事实，不得扣入任一账号。 - 立即刷新池质量样本使用 `scores pool-quality-refresh --over-api`；命令立即返回 workflow ID。 随后用 `workflow status --id --over-api` 回读，再查询 `scores pool-quality --over-api`。 - 充值候选使用 `upstreams recharge-candidates --over-api`。 - 欠费、低余额和查询超时的判定见 `references/upstream-scheduling.md`。 - 充值使用 `upstreams recharge --base-url --recharge-cny --confirm --over-api`；同一规范化 `base_url` 是共享钱包，只记账一次并统一恢复该站点全部 API-key 账号。 - 充值确认后 CLI 立即返回异步 workflow ID，并做一次非阻塞只读状态与账号快照核验；最终一致性使用 `upstreams recharge-status --id --over-api`。 - 核验状态为 `pending`、`snapshot_mismatch` 或 `unavailable` 时，只表示作业未完成或读模型暂未追上，不代表充值失败；必须继续查询原 workflow。 - 充值请求超时重试时必须复用相同的 `--idempotency-key`，禁止生成新 key 重复提交同一笔充值。 - CLI 在提交传输异常时会回显本次幂等键和“结果未知”提示；只有复用该键重试，不能把传输异常当成未提交而生成新键。 - 精确错误链使用 `errors diagnose --request-id --over-api`。 - 按模型定位使用 `errors diagnose --model --limit --top --over-api`。 - 单请求排障使用 `errors inspect --request-id --over-api`。 - 切号是否命中、候选是否耗尽、正文是否缺失，只以 `references/upstream-scheduling.md` 为准。 - 切号模板的匹配、近义短语、热加载、分组口语、同步范围和新增上游收口，只以该参考为准。 - 新增上游省略 `--rate`；占位费率与最终费率回读也只以该参考为准。 - 已有上游改分组使用 `upstreams update --id --groups --confirm --over-api`。 - `--groups` 整表替换全部分组，并重写切号模板。 - 私有探活分组必须列入；隔离后的收回顺序只见 `references/upstream-scheduling.md`。 - 多个同钱包 API Key 只对实际充值动作记一笔充值；创建、模板和探活隔离作业按账号 ID 幂等回读。 - 收入、采购、充值、退款和毛利读取 `references/accounting.md`。 - 手工收入明细使用 `cash ledger --period YYYY-MM --over-api`，汇总使用 `profit daily`。 - BugTeam 客户 API 使用 `bugteam` CLI 命令组，配置中的 `bugTeam.customerToken`、`customerAccount`、`customerPassword` 只能引用仓库外 Secret： - 只读：`bugteam login`、`balance`、`inventory --product --quantity N`、`shelves --product `、`pickup order-status --id `、`recoveries list`。 - 实时成本：`bugteam cost-monitor get --over-api` 读取最新摘要，显式增加 `--include-records` 才展开 6 小时历史；`bugteam cost-monitor sample --over-api` 提交一次采样，并用返回的 workflow ID 查询原作业。 - 订单：`pickup order-create --product --quantity N [--idempotency-key ]`；创建必须 `--confirm`，超时不得重复下单。 - 履约：`pickup download --id --format sub2|cpa --output `、`pickup push --id --hub-id --confirm`、`pickup take --id --confirm`。 - 401 修复：`recoveries claim --id --ticket-stdin --output --confirm`，Ticket 从 stdin 读取，必须复用同一 `--idempotency-key` 进行重试。 - 余额兑换：`redeem --code-stdin --confirm`，CDK 不得出现在 argv、日志或输出中。 - 一键购买导入：先用 `bugteam purchase-import options --over-api` 回读默认值； 再用 `bugteam purchase-import create --quantity N --confirm --over-api` 提交， 并只用 `bugteam purchase-import status --id --over-api` 跟踪原作业。 - 下载和领取只输出路径、字节数、SHA256 与版本摘要，绝不输出账号 JSON、Token 或 Ticket。 - 30d.team 公开兑换找回使用独立的 `bugteam public-recovery` 命令组，不读取或发送 BugTeam 客户 Token： - 健康检查：`bugteam public-recovery health --base-url https://30d.team --card-code-stdin`。 - 401 找回：先不带 `--confirm` 查看计划，再追加 `--confirm` 和 `--mode 401` 执行；兑换码只能经 stdin 输入。 - 状态查询：`bugteam public-recovery status --base-url https://30d.team --card-code-stdin`，只输出脱敏状态，不输出下载 Token。 - 下载：`bugteam public-recovery download --base-url https://30d.team --card-code-stdin --output `；先查询可下载任务，成功后原子写入并返回字节数与 SHA256，已存在目标文件会拒绝覆盖。 - `--base-url` 必须是无凭据、无路径、无查询和无片段的 HTTPS origin；该公开服务与 Api2Business 客户 API、Sub2API 本体均保持边界分离。 - 完整复活作业使用 `start --account-id --confirm` 创建并冻结原 OpenAI OAuth 账号配置，不读取兑换码、不启动 worker；原账号不删除，新复活账号固定按 `¥0.01` 成本导入。 - 后续每次 `continue --id --confirm` 只推进一个阶段；`health`、`reclaim`、`status` 和 `download` 阶段才追加 `--card-code-stdin`。 - 新副本继承冻结的优先级、并发、负载因子、计费倍率、分组、代理、过期暂停、状态和调度开关；`verify` 只核对新副本，任一字段不一致即失败。 - 已有下载文件需要补导入时使用 `import --account-id <原OAuth账号ID> --file --plan-type --confirm`；该入口保留原账号并创建独立复活副本。 - 作业 ID、阶段、错误和脱敏日志保存在 `.state/public-recovery/.json`；使用 `status` 查看摘要，使用 `logs --id --limit N` 查看最近日志。 - 作业失败后使用 `continue --id --confirm` 从失败阶段继续，或使用 `retry --id --stage --confirm` 单步重试；需要公开接口的阶段再次使用 `--card-code-stdin`，兑换码不落盘。 - 完整复活导入显式使用 `cutoffTrigger=public-recovery` 和独立重复导入语义，保留原 OAuth 账号并创建新的复活账号；不会触发 OpenAI OAuth 导入后的 API-key 上游切断。 - 错误聚合与诊断： - `--group` 按错误记录的实际请求分组筛选； - 默认排除内部 monitor 用户和 `api2business-probe-*` 探活流量； - 返回 `groupFilterBasis=request-group` 与 `probeNoiseExcluded=true` 供调用方核对口径。 - 页面普通读取只返回已有缓存，刷新先写缓存再读回： - 普通 GET 只读 `api2business_api_cache`，不重新计算； - 显式刷新请求携带 `x-api2business-refresh: 1`，先重算并写入该缓存，再读出刚写入的响应； - 排队 SQL 的普通读取只返回未过期缓存； - 显式刷新或缓存不存在时先查询并写入读取缓存，再返回这份缓存； - 不把查询结果直接返回给调用方； - 读取不先返回旧缓存，再在后台刷新； - 快照型 API 不叠加第二份通用 HTTP 响应缓存； - 评分表账号余额读取 `usage-cache` 快照，按评分账号 ID 查询，不依赖上游列表 HTTP 缓存是否命中； - API 与 Worker 按稳定快照键共享成功载荷； - 快照成功后原子替换，失败保留上一份成功快照； - 账号评分快照另由 worker 每 5 分钟刷新，进程重启后仍读取持久化快照。 - Sub2API 业务查询统一通过 Api2Business 排队 broker 读取 NC01 本地专用库； CLI、Web、worker 和人工脚本不得直连旧 PK01 数据库。 - 账号级代理默认策略：OAuth 导入、Plus/Team 账号和 API-key 上游默认直连，不绑定 Sub2API Proxy；配置中的 `sourceProxyId: 0`、`proxyId: 0` 表示无代理。 - 只有用户显式选择并且 owning 配置允许时才启用账号级代理；这不影响 NC01 host-Docker 的出网代理配置。 - 账号导入成功后异步触发一次 OAuth 实时成本采样；该采样独立于导入作业，不延长导入终态，失败只作为采样作业失败记录。 - 账号导入成功后不再自动提交 API-key 切断作业；API-key 切断仅保留显式手动入口。 - 手动验证同一采样路径使用 `accounts oauth-runtime-sample --over-api`，返回独立 Temporal workflow ID。 - 上游智商评测： - 提交：`upstreams benchmark --id --model --confirm --over-api`； - 进度与日志：`upstreams benchmark-status --id --over-api`； - 账号历史：`upstreams benchmark-history --id --limit 20 --over-api`； - 评测只复用持久化探活专用 API Key，不读取供应商原始 Key，也不轮换探活 Key。 - 评分与产出分母继续使用 `total_cost`。 - 额度监控的供应商实际支出按逐条销售倍率折回后乘实时有效倍率，唯一公式和缺失处理见 [额度监控](references/quota-monitoring.md)。 - 额度监控的状态、可用比例、钱包合并、刷新轮询和截图验收口径见 [额度监控](references/quota-monitoring.md)，不得在页面或其他文档另建第二套口径。 ## 验收 - 验证 `/health`、Web 登录、主要数据页和至少一个异步作业。 - 页面截图使用正式 CLI 取得临时 session，再交给受控 WebProbe： ```bash bun skills/api2business/scripts/api2business-cli.ts \ --config config/api2business.yaml \ --over-api \ web screenshot \ --profile scores-layout ``` - CLI 通过 `/api/login` 获取 Cookie，并只在内存中传给 WebProbe；WebProbe 不填写登录表单，Cookie 不进入 argv、日志、报告或磁盘。 - 验证重启后账本、缓存、采样和作业状态仍可读取。 - 失败时按配置、Secret、网络、数据库、worker 和外部 API 的顺序定位首个断点。