From 4d5e1e1933cb7d541b57f78b60302c381d79eae5 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 15 Jul 2026 09:06:25 +0200 Subject: [PATCH] =?UTF-8?q?docs(sub2api):=20=E5=9B=BA=E5=8C=96=E5=8D=95?= =?UTF-8?q?=E8=B4=A6=E5=8F=B7=E8=B0=83=E4=BC=98=E6=9C=80=E7=9F=AD=E8=B7=AF?= =?UTF-8?q?=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../unidesk-sub2api/references/codex-pool.md | 9 ++++++ .../R2.11_Task_Report.md | 28 +++++++++++++++++++ docs/MDTODO/sub2api-upstream-reliability.md | 3 ++ 3 files changed, 40 insertions(+) create mode 100644 docs/MDTODO/details/sub2api-upstream-reliability/R2.11_Task_Report.md diff --git a/.agents/skills/unidesk-sub2api/references/codex-pool.md b/.agents/skills/unidesk-sub2api/references/codex-pool.md index a3c86904..36d9256b 100644 --- a/.agents/skills/unidesk-sub2api/references/codex-pool.md +++ b/.agents/skills/unidesk-sub2api/references/codex-pool.md @@ -189,6 +189,15 @@ bun scripts/cli.ts platform-infra sub2api codex-pool cleanup-probes --target D60 - 账号人类可读名称使用 `runtime apply --kind account-name --name `： - 只接受单个精确账号 selector，先 dry-run，确认后自动回读名称； - 只更新名称，不携带 credentials、priority、分组、容量、代理、状态或可调度字段。 +- 单账号成本标注与优先级调优使用以下最短路径： + - 已知账号 selector 时，首个诊断入口固定为： + `runtime errors --target --since --group --account `； + - 同一次账号级查询直接读取评分、可归因上游失败率、TTFT、用量、Token、标准 API 计费基数和当前名称成本标注； + - 只有需要确认 priority、capacity、schedulable、proxy 或临时不可调度规则时，才补一次 `runtime get --account `； + - 只有需要跨账号比较时才使用全组 `runtime errors --group `；单账号任务不得先跑全组大报表，再重复账号级查询； + - priority 数值越小越优先。成本只参与人工经济性判断，必须同时考虑可靠性、TTFT、容量、可调度状态和样本置信度，不得按成本自动排序； + - 名称成本标注和 priority 是两个独立 runtime 字段：分别先 dry-run，再顺序 confirm；禁止并发更新同一账号，避免整对象更新互相覆盖； + - 两项 confirm 已各自回读一致后，最后只执行一次 `runtime get` 验收完整状态；不重复 confirm，不用全组查询代替账号回读。 - 模型映射先用 `runtime models --account ...` 获取原生配置与实时上游能力： - 只有实时模型列表或真实模型请求证明支持时才确认写入。 - 禁止把名称相近的模型猜测为别名。 diff --git a/docs/MDTODO/details/sub2api-upstream-reliability/R2.11_Task_Report.md b/docs/MDTODO/details/sub2api-upstream-reliability/R2.11_Task_Report.md new file mode 100644 index 00000000..a7416308 --- /dev/null +++ b/docs/MDTODO/details/sub2api-upstream-reliability/R2.11_Task_Report.md @@ -0,0 +1,28 @@ +# R2.11 任务报告 + +## 改进目标 + +关联 UniDesk #2144，将单账号成本标注与优先级调优从“先全组聚合、再账号下钻”的重复流程收敛为账号级首入口，减少无关数据聚合、输出预算触发和重复查询。 + +## 固化路径 + +Sub2API skill 的账号池权威 reference 已明确： + +- 已知账号 selector 时，首次调用 `runtime errors --target --since --group --account `。 +- 一次读取账号评分、可归因上游失败率、TTFT、用量、Token、标准 API 计费基数和名称成本标注。 +- 仅在需要当前 priority、capacity、schedulable、proxy 或临时不可调度规则时补一次 `runtime get`。 +- 全组查询仅用于跨账号比较；单账号任务不再以全组大报表作为前置。 +- 名称与 priority 分别 dry-run、顺序 confirm，最后一次 `runtime get` 验收，禁止并发更新同一账号。 +- 成本不自动决定 priority，仍需结合可靠性、TTFT、容量、可调度状态和样本置信度人工判断。 + +## 验证 + +- 使用参数化账号级命令完成 1 小时只读 smoke，单次返回评分、失败归因、TTFT、用量、Token 和成本。 +- smoke 未调用独立 usage、profit 或全组大报表，未触发 stdout 预算保护。 +- `quick_validate.py .agents/skills/unidesk-sub2api` 通过。 +- `git diff --check` 通过。 +- 本改进仅修改 skill reference 与 MDTODO，不修改 Sub2API 运行面。 + +## 结论 + +同类单账号调优的必要查询从“全组诊断加账号诊断加 runtime 读取”收敛为“账号诊断，按需补 runtime 读取”；写入和最终验收仍保持受控 dry-run、顺序 confirm 与回读边界。 diff --git a/docs/MDTODO/sub2api-upstream-reliability.md b/docs/MDTODO/sub2api-upstream-reliability.md index 11199d48..e5fda9b4 100644 --- a/docs/MDTODO/sub2api-upstream-reliability.md +++ b/docs/MDTODO/sub2api-upstream-reliability.md @@ -210,6 +210,9 @@ ### R2.10 [completed] 将 `https://sub.yjxm1221.top/` 对应上游账号的人民币采购成本标注调整为 `0.025`，结合 Sub2API 原生近期账号评分、错误率、TTFT、用量和当前 runtime 优先级适当调整优先级；手工账号使用精准 runtime CRUD，变更前 dry-run、确认写入后逐字段回读对账，不修改 Sub2API 源码、版本或外部哨兵，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.10_Task_Report.md)。 +### R2.11 [completed] + +依据 [UniDesk #2144](https://github.com/pikasTech/unidesk/issues/2144) 将单账号成本标注与优先级调优的最短路径固化到 Sub2API skill：账号级 `runtime errors --group --account --since` 作为评分、可靠性、TTFT、用量和成本首入口，仅在读取当前 runtime 字段时补一次 `runtime get`；全组概要只用于跨账号比较，名称和 priority 分别 dry-run、顺序 confirm、最终单次回读，不修改运行面，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.11_Task_Report.md)。 ## R3 [completed] 增加 Sub2API 客户余额精准批量充值 CLI：支持从原生最近24小时用量提取活跃用户并生成每人增加20美元的补偿计划，也支持显式用户ID或账号 selector；默认 dry-run 输出完整账号、用户ID、当前余额、增额和目标余额，写入必须显式 --confirm 并自动回读对账。本轮只实现并验证 dry-run，禁止实际充值，必须等待用户再次明确授权，完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R3_Task_Report.md)。