diff --git a/.agents/skills/unidesk-sub2api/SKILL.md b/.agents/skills/unidesk-sub2api/SKILL.md index 794c0b14..01fceee8 100644 --- a/.agents/skills/unidesk-sub2api/SKILL.md +++ b/.agents/skills/unidesk-sub2api/SKILL.md @@ -4,7 +4,7 @@ description: >- UniDesk Sub2API 平台运维技能。用户提到 Sub2API、platform-infra sub2api、Codex pool、统一 API key、 runtime CRUD、精准批量账号操作、临时不可调度、上游错误率、客户可见错误、换号/failover、 模型映射、可用模型探测、利润核算、售价与账号退役情景、FRP 暴露、管理 UI、配置 master ~/.codex、 - 上游账号增删或校验 /v1/models 时使用。 + SuperAPI 企业 skill 上游加载与全量捕获、上游账号增删或校验 /v1/models 时使用。 --- # UniDesk Sub2API @@ -67,6 +67,23 @@ bun scripts/cli.ts platform-infra sub2api codex-pool runtime events --target PK0 - Codex pool、统一 API key、master `~/.codex` 配置、FRP/Caddy 暴露、账号增删都必须走本技能的受控 CLI。 - `api.pikapython.com` 异常先按 YAML target 区分 PK01 local edge/app、k3s FRP target 和账号池调度;用 `status`、`validate`、受控 apply/sync 以及最小 `/v1/responses` smoke 做分层恢复。完整步骤见 [references/troubleshooting.md](references/troubleshooting.md) 和 [references/public-exposure.md](references/public-exposure.md)。 +## SuperAPI 全量捕获验收 + +SuperAPI 全量捕获由 `/root/superapi/config/superapi.yaml` 控制。普通 Codex 客户端不增加 capture id、header、环境变量或专用配置。存储统一使用 UTC 日期和小时分区;查询时区只影响展示。 + +```bash +cd /root/superapi +bun scripts/superapi-cli.ts config validate +bun scripts/superapi-cli.ts l0 probe +bun scripts/superapi-cli.ts capture status +bun scripts/superapi-cli.ts capture list --kind all --time-zone Asia/Shanghai +bun scripts/superapi-cli.ts capture validate +``` + +- `l0 probe` 必须显示 `PROXY_MODULE true`,在 L1 前覆盖代理模块解析。 +- `capture validate` 聚合验证配额、双向 JSONL、UTC 路径、`0700`/`0600` 权限、配置 API Key 脱敏和请求/响应摘要;默认不输出 body。 +- `capture list` 只做渐进披露摘要;只有展示需要才显式指定 IANA 时区。 + ## 何时读取 reference - 部署、状态、target 边界、PK01 host-Docker、k3s target、egress proxy、镜像升级:读 [references/operations.md](references/operations.md)。 diff --git a/docs/MDTODO/details/sub2api-upstream-reliability/R2.7.11_Task_Report.md b/docs/MDTODO/details/sub2api-upstream-reliability/R2.7.11_Task_Report.md new file mode 100644 index 00000000..44ae251c --- /dev/null +++ b/docs/MDTODO/details/sub2api-upstream-reliability/R2.7.11_Task_Report.md @@ -0,0 +1,36 @@ +# R2.7.11 任务报告 + +## 结论 + +本次 `$post-task` 只修复 SuperAPI 全量捕获交付中实际暴露的两个流程缺口,没有修改运行网关行为、YAML 或线上进程: + +- L0 原先未加载 `src/proxy.ts`,代理模块语法错误只能到 L1 native 启动时发现;现在 `l0 probe` 显式实例化代理 metrics,并输出 `PROXY_MODULE true`。 +- 捕获终验原先需要手工组合 JSONL 解析、权限、脱敏、配额和摘要查询;现在新增 `capture validate` 聚合只读验收,默认不输出 body。 + +## 实现 + +SuperAPI 独立流程改进提交:`1e5bdfb chore: consolidate capture validation`,已从实验分支快进到 `/root/superapi` master。该仓库没有 remote,因此提交只保存在本地。 + +`capture validate` 有界读取最新请求和响应记录,验证: + +- 实际占用不超过 YAML `maxDiskBytes`; +- 请求和响应最新 JSONL 存在且可解析; +- 存储路径符合 UTC 日期/小时分区; +- 目录权限为 `0700`,文件权限为 `0600`; +- 最新记录不包含 YAML profile 解析出的 API Key; +- 请求和响应摘要均可由现有渐进披露查询读取; +- 默认不打印 body 或 Secret。 + +`unidesk-sub2api` skill 已增加 SuperAPI 最短验收顺序,明确 UTC 只用于存储、查询时区仅用于展示,普通 Codex 客户端无需 capture 配置。 + +## 验证 + +在 `/root/superapi` master 依次通过: + +- `bun scripts/superapi-cli.ts config validate` +- `bun scripts/superapi-cli.ts l0 probe` +- `bun scripts/superapi-cli.ts capture validate` + +关键结果为 `PROXY_MODULE=true`、`RESULT=PASS`、`QUOTA=true`、双向 `JSONL=true`、`UTC_PATHS=true`、`PERMISSIONS=true`、`API_KEYS_REDACTED=true`、双向 `SUMMARY=true`、`BODY_PRINTED=false`。 + +Skill 使用 `quick_validate.py` 校验通过。线上 SuperAPI 服务未重启,原 PID 和运行流量未受本次只读诊断改进影响。 diff --git a/docs/MDTODO/sub2api-upstream-reliability.md b/docs/MDTODO/sub2api-upstream-reliability.md index b29ec54e..2abee58c 100644 --- a/docs/MDTODO/sub2api-upstream-reliability.md +++ b/docs/MDTODO/sub2api-upstream-reliability.md @@ -222,6 +222,9 @@ 将 SuperAPI 请求捕获改为 YAML 控制的全量模式:客户端无需 capture id 或特殊 header;全量捕获请求和响应,分别按 UTC 日期与小时目录写入 JSONL,合计硬盘滚动上限 4 GiB并删除最旧分区;查询支持指定 IANA 时区并渐进披露摘要,敏感鉴权字段保持脱敏,补 capture status/list 可见性,重复完成 L0、L1 和普通 Codex 客户端真实验收,完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.7.10_Task_Report.md)。 +#### R2.7.11 [completed] + +复盘 SuperAPI 全量捕获交付并修复已暴露的流程缺口:让 L0 实际加载代理模块以提前发现语法错误;新增 `capture validate` 聚合校验配额、JSONL、UTC 分区、权限、敏感值脱敏和请求/响应摘要;将最短验收流程沉淀到 Sub2API skill,不修改运行网关行为,完成任务后将详细报告写入任务报告,完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.7.11_Task_Report.md)。 ### R2.8 [completed] 整理本 MDTODO FILE 的职责层级和编号,并把同一 SUBITEM 下的直接 SUBSUBITEM 一般不超过 20 固化到 mdtodo-edit skill,完成任务后将详细报告写入[任务报告](./details/sub2api-upstream-reliability/R2.8_Task_Report.md)。