# sub2api-cn-relay-manager 执行板

日期：2026-05-22
当前 Gate：APPROVED（代码门禁已通过，并且 2026-05-21 已继续收掉 account probe、gateway probe 认证语义和 latest-head `self_service` fresh-host 复验的剩余问题。最新 MiniMax 53hk fresh-host 验收 `artifacts/real-host-acceptance/20260521_191418_remote43_minimax_key_import/21-summary.json`、DeepSeek 2166 `subscription` fresh-host 验收 `artifacts/real-host-acceptance/20260521_201509_remote43_deepseek_key_import/21-summary.json`、以及 latest-head `self_service` 标准 fresh-host 验收 `artifacts/real-host-acceptance/20260521_210403/05-import.json` / `07-access-status.json` 已共同证明：`subscription` 与 `self_service` 主链路都能在真实 fresh host 上闭环到 ready，host `/v1/models` 与 `/v1/chat/completions` 也都真实返回 `HTTP 200`。当前仍存在的 `reconcile=drifted` 只反映共享 fresh-host 环境里的历史残留资源，不阻塞 PRD 首版放行）
目标：实现独立控制面、零侵入宿主、可导入国产模型并具备可运维的导入/回滚/访问闭环。

## 2026-05-22 当前真相

- 当前主目录 `artifacts/real-host-acceptance/` 已只保留最终证据；历史调试样本已迁到 `artifacts/real-host-acceptance-archive/`
- access ready 语义已经收口为：`/v1/models` 命中 `smoke_test_model`，且最小 `POST /v1/chat/completions` smoke 成功；不会再出现 models-only 假 ready
- `subscription` 主链路已通过 latest fresh-host 复验：
  - MiniMax 53hk：`artifacts/real-host-acceptance/20260521_191418_remote43_minimax_key_import/21-summary.json`
  - DeepSeek 2166：`artifacts/real-host-acceptance/20260521_201509_remote43_deepseek_key_import/21-summary.json`
  - Kimi A7M（local host `v0.1.129`）：`artifacts/real-host-acceptance/20260522_122706_local_v0129_kimi_a7m_subscription_freshhost/21-summary.json`
- `self_service` 主链路已通过 latest-head 标准 fresh-host 复验：
  - `artifacts/real-host-acceptance/20260521_210403/05-import.json`
  - `artifacts/real-host-acceptance/20260521_210403/07-access-status.json`
- 官方 provider 验证矩阵当前仍保留一条非阻塞事实：
  - `artifacts/real-host-acceptance/20260521_222212_remote43_minimax-m2-7-official_key_import/21-summary.json` 已证明 official MiniMax 模板链路是通的，但该验证 key 当前命中 upstream `429`
- `reconcile=drifted` 仍可能在 shared fresh-host 上出现，但当前解释是“历史残留资源噪音”，不阻塞 PRD 首版放行
- 调通细节与诊断经验已沉淀到：
  - `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md`
  - `docs/REAL_HOST_ARTIFACT_RETENTION.md`

## 本轮已完成

1. 宿主身份模型统一
   - host 注册时持久化 `auth_type/auth_token`
   - import / reconcile / rollback-provider / access 运行时链路切换为 `host_id` 主键
   - provider status / resources / access status / import-batches 支持 `host_id` 查询维度
2. managed_resources 宿主维度收口
   - 新增迁移 `0004_host_identity_and_managed_resources.sql`
   - `managed_resources` 唯一键提升为 `(host_id, resource_type, host_resource_id)`
   - 仓储与服务查询切换为 host-scoped 语义
3. reconcile run 结果按批次收口
   - 新增迁移 `0006_reconcile_runs_batch_scope.sql`
   - `reconcile_runs` 补充 `batch_id`，batch detail 仅返回本批次 reconcile 记录
4. capability probe 收敛为无副作用探测
   - 不再对真实创建接口发送空 `POST`
5. rollback-provider 风险收敛
   - 改为优先按已记录批次资源 `RollbackStoredResources()` 回滚
   - 缺少已记录资源时拒绝危险删除
6. 文档真相同步
   - 新增 `docs/2026-05-18-PRODUCTION_REMEDIATION_TASK_BOARD.md`
   - 下调 `DEPLOYMENT.md` 中未实现的 `/metrics` / 限流 / 监控承诺
7. current-code remote43 导入链路已补齐 tunnel-aware 验证能力
   - `scripts/import_remote43_provider.sh` 新增 `CRM_HOST_BASE`，允许把“operator 访问 host 地址”和“CRM 进程访问 host 地址”分离
   - 历史 live model-mapping 关键证据保留在：`artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation`
8. current-code remote43 access gate 根因修正已落地
   - subscription access 改为宿主侧闭环：CRM 不再依赖外部预先给定的宿主普通用户 key，而是按 `subscription_users` selector 在宿主创建/查找托管普通用户、登录创建托管 key、回写 allowed_groups / balance、再执行订阅分配
   - account 创建请求现在同步写入 `credentials.model_mapping`，修正 `/v1/models` 读取 account model whitelist 时回退到 GPT 默认集合的问题
   - 新增/更新测试覆盖：`internal/access`、`internal/provision`、`internal/host/sub2api`
9. current-code access ready 语义已提升到 completion 层
   - `/v1/models` 不再单独决定 `subscription_ready/self_service_ready`
   - 只有 `/v1/models` 命中 `smoke_test_model` 且 `/v1/chat/completions` smoke 成功，控制面才会把 access 状态记成 ready
   - access closure / import runtime artifact / reconcile rerun payload 都会持久化 `completion_ok/completion_status/completion_type/completion_preview`
10. current-code remote43 验收脚本已补 upstream API 证据层
   - `scripts/import_remote43_provider.sh` 会直探 provider `base_url` 对应的 upstream `/models` 与 `/chat/completions`
   - 新增 `21-summary.json`，用于把 completion 失败自动分流成 `host_compatibility_gap` 或 `upstream_key_quota_issue`
11. patched CRM external validation 已完成
   - patched CRM 实例下，DeepSeek 与 MiniMax 都已验证“completion smoke 通过时能落成 succeeded/active，失败时不会误记成 ready”
   - `20260521_191418_remote43_minimax_key_import` 与 `20260521_201509_remote43_deepseek_key_import` 已同时证明当前 `subscription` provider 链路可真实闭环
   - `20260521_210403` 已证明 latest-head `self_service` 标准 fresh-host 验收也可闭环到 `self_service_ready / fully_ready`
12. artifact 保留策略已收口
   - 主目录 `artifacts/real-host-acceptance/` 当前只保留最终证据
   - 历史失败/半成功/试错样本已迁到 `artifacts/real-host-acceptance-archive/`
   - 分类规则见：`docs/REAL_HOST_ARTIFACT_RETENTION.md`
13. relay-manager latest-head 已收口 Kimi A7M 两段竞态
   - account test 首次 `403 Forbidden` 已降级为 advisory warning；只要 `/models` 已命中 `smoke_test_model`，不会再把 batch 误判为 blocking failure
   - access closure 对导入后瞬时 `503 / no available accounts` 增加短暂 completion retry，避免宿主异步 probe / account warm-up 窗口把真实可用链路误记成 `broken`
   - `20260522_122706_local_v0129_kimi_a7m_subscription_freshhost` 已证明：在修复后的 relay-manager + patched host 组合下，`kimi-a7m / kimi-k2.6` 可落到 `batch_status=succeeded`、`provider_status=active`、`latest_access_status=subscription_ready`

## 已验证门禁

- `gofmt -l .` ✅ 空输出
- `go vet ./...` ✅
- `go test ./...` ✅
- `go test -race ./...` ✅
- `go test -cover ./internal/...` ✅
  - `internal/access`: `80.5%`
  - `internal/host/sub2api`: `78.1%`
  - `internal/pack`: `73.9%`
  - `internal/provision`: `76.3%`
  - `internal/store/sqlite`: `61.4%`
- `go test ./tests/integration/... -count=1` ✅
- `bash ./scripts/test_real_host_scripts.sh` ✅

## 当前保留的最终证据

1. `artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation`
   - 证明 account `credentials.model_mapping` 与 live runtime 对齐

2. `artifacts/real-host-acceptance/20260521_142211_crm18100_deepseek_completion_split`
   - 证明 host completion 失败与 upstream completion 成功可以分离
   - 是 completion 分流逻辑的关键根因证据

3. `artifacts/real-host-acceptance/20260521_191418_remote43_minimax_key_import`
   - MiniMax 53hk `subscription` 最终成功样本
   - `21-summary.json` 已到 `batch_status=succeeded`、`provider_status=active`

4. `artifacts/real-host-acceptance/20260521_201509_remote43_deepseek_key_import`
   - DeepSeek 2166 `subscription` 最终成功样本
   - `21-summary.json` 已到 `batch_status=succeeded`、`provider_status=active`

5. `artifacts/real-host-acceptance/20260521_210403`
   - latest-head `self_service` 标准 fresh-host 验收最终成功样本
   - `05-import.json` = `succeeded/self_service_ready/active`
   - `07-access-status.json` = `latest_access_status=fully_ready`

6. `artifacts/real-host-acceptance/20260521_222212_remote43_minimax-m2-7-official_key_import`
   - official MiniMax 模板 live 样本
   - 模板链路打通，但当前验证 key 命中 upstream `429`

7. `artifacts/real-host-acceptance/20260522_122706_local_v0129_kimi_a7m_subscription_freshhost`
   - latest-head relay-manager 对 patched host `v0.1.129` 的 Kimi A7M `subscription` 最终成功样本
   - `21-summary.json` 已到 `batch_status=succeeded`、`provider_status=active`
   - `account_probe_summary` 明确记录 `probe_advisory=true`、`validation_status=warning`，证明 403 probe race 已被 relay-manager 正确降级

## 剩余项（P2 / 运营前置，不阻塞按 PRD 首版范围上线）

1. 运营前置
   - 真实宿主初始化不会自动创建普通用户；上线前必须显式创建普通用户并留存可复用凭据
   - `self_service` 需要普通用户 key 绑定目标标准 group，且通常还需要可用余额
   - `subscription` 需要 subscription 类型 group + 普通用户订阅分配 + key/group 绑定

2. 结构债务
   - access / reconcile 仍未完全按 implementation plan 拆到独立子模块
   - 当前仍无内置 scheduler/jobs

3. 部署与环境限制
   - 标准多阶段 Dockerfile 在受限网络环境下仍不稳
   - 当前推荐 `scripts/build_local_image.sh` + `Dockerfile.local`

4. official provider 验证矩阵
   - official MiniMax 当前 live 样本已证明模板链路可用，但验证 key 命中 upstream `429`
   - Qwen / GLM / Kimi / Step 等官方 provider 是否通过 live 验收，仍取决于后续官方 key 与 quota

## 当前最短后续路径

1. 若继续扩大 provider 覆盖面，优先按 `docs/PROVIDER_VALIDATION_MATRIX.md` 补官方 key，再做 official live 验收
2. 若继续优化 shared fresh-host 信噪比，对历史残留资源做一次环境清理，降低 `reconcile=drifted` 噪音
3. 若继续产品化，推进 `v2` 的 batch auto-import 设计评审，再开始实现

## v2 规划：Batch Auto-Import（URL + Key）

**当前阶段**：🔨 设计中（核心契约已收口，待按收口版本进入实现）

**文档**：`docs/2026-05-21-BATCH_AUTO_IMPORT_SPEC.md`（需求规格）
**TDD 计划**：`docs/2026-05-21-BATCH_AUTO_IMPORT_TDD_PLAN.md`（实现路径，已确认开放问题）
**技术架构**：`docs/2026-05-22-BATCH_AUTO_IMPORT_V2_ARCHITECTURE.md`（运行态状态库、结果页、API、页面字段布局）
**Migration 草案**：`docs/2026-05-22-BATCH_AUTO_IMPORT_V2_MIGRATION_DRAFT.md`（SQLite 新表、索引、lease/retry 字段、legacy link）
**API Schema 细稿**：`docs/2026-05-22-BATCH_AUTO_IMPORT_V2_API_SCHEMAS.md`（run/item 响应结构、筛选参数、badge 文案、错误语义）

**本轮设计收敛**：
- 已把真实验收中的三类高频问题写入 v2 方案：
  - 添加模型时的模型名归一化与纠错
  - 第三方国产模型的兼容能力画像（`/responses`、`/chat/completions`、Anthropic compatible、stream/tools）
  - 添加账号后的异步确认窗口（首次 `403` probe race、首次 `503 no available accounts` warm-up）
- 已补充两类产品化能力到 v2：
  - run / item 状态持久化、retry 轨迹、控制面重启后的历史结果查看
  - 批次列表页 / 批次详情页，用于查看模型纠错结果、账号状态、provider warning 与最终 access 状态
- 当前 v2 的目标已从“同步导入成功”升级为“导入 + 异步确认 + 最终闭环验真”
- 已按 review 收口最关键的 4 个冲突：
  - 统一 canonical contract：`run_id/item_id/provider_id/run.state/confirmation_status/access_status`
  - 补齐 `subscription` / `self_service` 的输入契约
  - 明确 V2 唯一状态源为 `import_runs/import_run_items/import_run_item_events`
  - 明确 `ConfirmationWorker + lease + next_retry_at` 的异步确认执行机制
- 其余 review 问题也已同步收口：
  - capability 从 upstream 总画像升级为 transport + model profiles
  - 结果页字段、状态库存储字段、retry/event trail 已统一
  - OpenAPI 已补齐 `/api/batch-import/runs*`，legacy `/api/import-batches/*` 降级为 v1/legacy
  - 已补充重复导入自动复用策略：按 `provider_id + api_key_fingerprint + canonical_model_family` 判断 `reused / patch_only / replace`
  - 已补充同模型别名归一化契约：例如 `kimi 2.6 / kimi-2.6 / kimi-k2.6` 可归并到同一模型家族并快速复用
  - 已补充多账号重复导入与弃用账号再启用策略：active 账号提示“重复已启用”，disabled/deprecated 账号显示原状态并走 `reactivated` 快速启用路径

**当前剩余项**：
- [x] 按收口后的 canonical contract 输出数据库 migration 草案
- [x] 补齐 run/item API response schema 细稿
- [~] 按收口后的 OpenAPI、migration、projection 字段开始实现
  - 已落地 `0007_batch_import_runs.sql` / `0008_batch_import_run_events.sql`
  - 已补 `internal/store/sqlite` 下 run/item/event repo 骨架，并完成 migration ledger 测试同步
- [ ] 进入实现前再做一次实现前审阅，确认没有新增分叉

**实现前 Gate**：文档级 review 问题已收口，当前可以进入“按文档写 migration / 接口 / worker”的实现准备阶段

---

## 禁止错误结论

- ❌ 历史失败 artifact ≠ 当前 latest-head 仍失败
- ❌ capability probe 无副作用 ≠ 所有宿主版本都已真实兼容
- ❌ rollback-provider 已改安全路径 ≠ 历史脏资源自动消失
- ❌ `HTTP 200` ≠ 宿主初始化会自动准备普通用户/订阅/余额；这些仍是显式运营前置