# R2.1 任务报告

## 目标

增强 UniDesk Sub2API CLI，优先使用 Sub2API 原生 admin/ops 运维能力诊断全池错误、账号状态、并发和单请求链路，运行日志只补原生索引未提供的策略事件。

## 官方能力依据

对照 `Wei-Shaw/sub2api` 官方仓库提交 `5d1c577cb2c735ca1f1d57533dff1302f6998d91`，确认可复用接口：

- `/api/v1/admin/ops/dashboard/overview`：请求总数、客户可见错误、错误率、上游错误率、健康分。
- `/api/v1/admin/ops/upstream-errors`：账号级上游错误、状态码、request id 和详情。
- `/api/v1/admin/ops/account-availability`：账号可用、限流、过载和错误状态。
- `/api/v1/admin/ops/concurrency`：平台、组和账号并发占用、容量与排队。
- `/api/v1/admin/ops/requests`：成功与错误请求的统一 request-id 视图。
- `/api/v1/admin/ops/system-logs` 及 `/health`：索引日志和 sink 健康状态。

## CLI 改进

- `runtime errors` 增加 `nativeOps`，使用 overview 的完整请求分母计算客户可见错误率，避免把错误记录数当错误率。
- 增加原生账号可用性、组并发、排队和 system-log sink 丢弃/写入失败状态。
- Ops 上游错误改为所有选中账号主动查询，不再要求容器日志先出现对应事件。
- `policyEffectiveness` 关联临时不可调度、failover、选号失败、`forward_failed` 和最终结果；仅按 request id 关联并披露缺失覆盖率。
- 原生 system-log 索引没有策略事件而 overview 存在上游错误时，自动回退 target runtime 日志补事件，并披露 fallback 原因、数量和原生索引计数。
- 全池默认只输出主因排名，账号详情通过 `--account` 下钻；全池和单账号默认输出均保持在 CLI 预算内，`--full` 保留完整分布。
- `trace` 改为 `/ops/requests` 与 `/ops/system-logs` 优先，target runtime 日志只补邻近上下文。
- 修复 PK01 trace 固定读取 k3s Deployment、Docker stderr 业务日志遗漏和原生事件倒序问题。
- `forward_failed` 与 HTTP 200 并存且没有 failover 时，trace 标记为 `degraded`，不再误报普通成功。
- 修正 `No available channel for model` 根因分类和所有 Ops 错误被描述为 HTTP 500 的误导文案。

## 现场验证

- 10 分钟原生 overview 样本曾观测 165 个请求、2 个客户可见错误，错误率 1.21%，上游错误率 3.03%；后续窗口为 189 个请求、1 个客户可见错误，错误率 0.53%，上游错误率 2.65%。这些是滚动窗口快照，不代表长期趋势。
- 原生 concurrency 显示组容量 218，现场占用约 9 至 10，无排队；全池错误不能归因于 Sub2API 组并发耗尽。
- 原生 availability 显示账号 29、30 因 `403 Insufficient account balance` 处于 error；账号 27 在短时冷却窗口可能暂不可用。
- 策略事件样本显示临时不可调度和 failover 均实际发生；部分切号成功，仍存在切号后失败、结果缺失和 `forward_failed + HTTP 200`。
- request `03a94444-ff26-4038-b1b9-67e249ce7f59`：账号 33 返回 524 后切到账号 31，账号 31 返回 502，随后 `account-select-failed/context canceled`，最终客户状态 502。
- request `55d32c6a-09ae-46ac-9a34-3f63934e7f62`：账号 31 出现并发错误但 HTTP 200，没有 failover，trace 正确标记 `degraded`。
- 账号 31 的 10 分钟 Ops 记录同时包含 429 rate-limit 和明确 concurrency 文案；当前并发快照不能替代错误发生时并发，后续只能通过受控对比判断是否需要调整账号并发。
- 原生 system-log sink 健康，无 dropped/write failed；但策略事件查询为零，当前需要 runtime 事件 fallback。

## 验证命令

- `bun --check scripts/src/platform-infra-sub2api-codex/runtime.ts`
- `bun --check scripts/src/platform-infra-sub2api-codex/remote-python-sync.ts`
- `bun --check scripts/src/platform-infra-sub2api-codex/render.ts`
- `bun scripts/cli.ts platform-infra sub2api codex-pool runtime errors --target PK01 --since 10m`
- `bun scripts/cli.ts platform-infra sub2api codex-pool runtime errors --target PK01 --since 10m --account 31`
- `bun scripts/cli.ts platform-infra sub2api codex-pool trace --target PK01 --request-id 03a94444-ff26-4038-b1b9-67e249ce7f59`
- `git diff --check`

## 后续

- R2.2 持续观察新窗口，区分客户可见错误率、上游错误率、成功 failover 和流式 degraded。
- R2.3 调查原生 system-log 索引为何未保留策略事件，并优先推动 Sub2API 原生能力覆盖，减少 runtime 日志 fallback。