209 lines
8.6 KiB
Markdown
209 lines
8.6 KiB
Markdown
# 文档真相索引
|
||
|
||
日期：2026-05-21
|
||
项目：`sub2api-cn-relay-manager`
|
||
|
||
## 当前 Gate 结论
|
||
|
||
当前最新 gate：`APPROVED`
|
||
|
||
当前 gate 升到 `APPROVED` 的原因是：
|
||
1. 代码侧已关闭“只靠 `/v1/models` 就把 access 标成 ready”的假阳性；当前 ready 必须同时通过 `/v1/models` 与 `/v1/chat/completions` smoke
|
||
2. `scripts/import_remote43_provider.sh` 已补上 upstream `/models` 与 `/chat/completions` 直探，并落盘 `21-summary.json` 做根因分类
|
||
3. account `credentials.model_mapping`、channel `model_mapping/model_pricing`、managed key 视角 `/v1/models` 都已有 live 证据
|
||
4. completion-gated 补丁已经在 fresh-host 上重跑验证通过：control plane 会把 completion 失败正确落成 `broken`
|
||
5. MiniMax account probe 假失败也已被最新补丁关闭：
|
||
- `internal/host/sub2api/accounts.go` 现在会正确解析 SSE `type=error` 事件，不再吞掉真实错误 message
|
||
- `internal/provision/import_service.go` 与 reconcile rerun 现在会显式向 `/api/v1/admin/accounts/:id/test` 传 `provider.SmokeTestModel`，不再让宿主默认回退测试 `gpt-5.4`
|
||
- 最新证据：`artifacts/real-host-acceptance/20260521_191418_remote43_minimax_key_import/21-summary.json` 已显示 `batch_status=succeeded`、`provider_status=active`
|
||
6. DeepSeek 2166 与 MiniMax 53hk 两条 `subscription` provider 分支都已完成 latest fresh-host 复验，最新证据分别是 `artifacts/real-host-acceptance/20260521_201509_remote43_deepseek_key_import/21-summary.json` 与 `artifacts/real-host-acceptance/20260521_191418_remote43_minimax_key_import/21-summary.json`
|
||
7. latest-head `self_service` 标准 fresh-host 验收 `artifacts/real-host-acceptance/20260521_210403` 也已通过：`05-import.json` = `succeeded/self_service_ready/active`，`07-access-status.json` = `latest_access_status=fully_ready`
|
||
8. 当前仍存在的 `reconcile=drifted` 仅反映共享 fresh-host 历史残留资源，不阻塞 PRD 首版放行
|
||
|
||
一句话：
|
||
- “模型暴露、completion gate 和 upstream triage 都已进代码”是真
|
||
- “MiniMax 53hk、DeepSeek 2166 的 `subscription` 真实宿主主链路已完全放行”是真
|
||
- “latest-head `self_service` fresh-host 标准验收也已通过”是真
|
||
|
||
## 当前真相文档（按优先级排序）
|
||
|
||
### 1. `docs/EXECUTION_BOARD.md`
|
||
用途：
|
||
- 当前执行状态
|
||
- 最新 gate
|
||
- 剩余阻断
|
||
- 最短 closure path
|
||
|
||
解释规则：
|
||
- 这是“当前执行真相”的第一来源
|
||
- 当其他文档与它冲突时，以它为准
|
||
|
||
### 2. `docs/PRODUCTION_CLOSURE_BOARD.md`
|
||
用途：
|
||
- 当前是否可按 PRD 首版范围放行
|
||
- 哪些是代码门禁，哪些是外部/环境门禁
|
||
- 哪些历史 PASS 不能再直接当当前真相
|
||
|
||
解释规则：
|
||
- 这是“上线收口真相”的第一来源
|
||
- 若与历史评审/历史任务板冲突，以它为准
|
||
|
||
### 3. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
|
||
用途：
|
||
- 真实宿主验收的标准步骤
|
||
- 需要收集哪些 artifact
|
||
- 需要验证哪些层级的证据
|
||
|
||
解释规则：
|
||
- 它定义“怎么验收”
|
||
- 不直接定义当前 gate，当前 gate 仍以上面两份板为准
|
||
|
||
### 4. `docs/PROVIDER_ONBOARDING_PLAYBOOK.md`
|
||
用途：
|
||
- 新增 provider 的稳定操作顺序
|
||
- 宿主版本变更后的重验路径
|
||
- 如何把一次调通沉淀成可复用的 onboarding 流程
|
||
|
||
解释规则：
|
||
- 它定义“后续怎么稳定地继续加 provider / 复验宿主”
|
||
- 不直接决定当前 gate，但决定后续变更能否低风险复用
|
||
|
||
### 5. `docs/PROVIDER_VALIDATION_MATRIX.md`
|
||
用途：
|
||
- 按 provider 维度跟踪“模板是否已就绪 / 官方 key 是否存在 / live 验收是否已完成”
|
||
- 给后续“六小龙 + BAT + 小米等”模型矩阵扩展提供同一口径
|
||
|
||
解释规则：
|
||
- 它不直接改变项目整体 gate
|
||
- 但它是当前 provider 覆盖度和验证进度的第一来源
|
||
|
||
### 6. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md`
|
||
用途：
|
||
- 已调通的细节
|
||
- 高频误判点
|
||
- 推荐诊断顺序
|
||
- 经验性解释
|
||
|
||
解释规则：
|
||
- 它解释“为什么之前会误判、现在应该怎么查”
|
||
- 用来辅助 runbook 和执行板，不单独决定 gate
|
||
|
||
## 次级文档（仍有价值，但必须通过当前真相文档解释）
|
||
|
||
### `docs/PRD.md`
|
||
- 定义 PRD 首版范围
|
||
- 只能回答“目标应该是什么”，不能单独回答“现在是否已完成”
|
||
|
||
### `docs/TDD_PLAN.md`
|
||
- 定义测试设计与实现计划
|
||
- 不能单独代表当前真实验收状态
|
||
|
||
### `docs/DEPLOYMENT.md`
|
||
- 用于部署说明
|
||
- 若与当前执行板冲突，以执行板/收口板为准
|
||
|
||
### `docs/KNOWN_LIMITATIONS.md`
|
||
- 用于记录仍存在的限制
|
||
- 需要通过当前执行板一起理解，避免把旧限制当作已关闭或反过来
|
||
|
||
### `docs/plans/2026-05-12-sub2api-cn-relay-manager-implementation-plan.md`
|
||
- 说明最初实现路径
|
||
- 是设计/计划文档，不是当前状态文档
|
||
|
||
### `docs/2026-05-12-sub2api-cn-relay-manager-solution.md`
|
||
- 说明方案设计与宿主接口认知
|
||
- 可作为背景，但不能直接当当前 gate 依据
|
||
|
||
## 历史快照文档（只可参考，不可作为当前实现真相）
|
||
|
||
### `docs/2026-05-18-PRODUCTION_READINESS_REVIEW.md`
|
||
- 性质：历史审查快照
|
||
- 用途：回看当时发现了哪些系统性问题
|
||
- 禁止用法：不能直接引用其中的 `REJECT / CONDITIONAL_APPROVED` 作为当前 gate
|
||
|
||
### `docs/2026-05-18-PRODUCTION_REMEDIATION_TASK_BOARD.md`
|
||
- 性质：历史整改执行板
|
||
- 用途：回看 2026-05-18 那一轮整改任务是如何收口的
|
||
- 禁止用法：不能直接拿其顶部 gate 文字当当前状态
|
||
|
||
## artifact 解释规则
|
||
|
||
### 当前优先证据
|
||
优先看最新一轮、且与 latest-head / fresh host 对齐的 artifact：
|
||
- `artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation`
|
||
- `artifacts/real-host-acceptance/20260521_191418_remote43_minimax_key_import`
|
||
- `artifacts/real-host-acceptance/20260521_201509_remote43_deepseek_key_import`
|
||
- `artifacts/real-host-acceptance/20260521_210403`
|
||
|
||
说明：
|
||
- 上述 artifact 已包含 patched control plane 的最新 live 证据。
|
||
- 它们证明 current-code 的 `subscription` 与 `self_service` 主链路已经在 fresh host 上闭环通过；其中 `20260521_210403` 还补齐了标准 `reconcile/rollback` 验收链路。
|
||
|
||
### 历史参考证据
|
||
以下可证明某个阶段“曾经打通过”，但不能直接代表当前真相：
|
||
- `artifacts/real-host-acceptance/20260518_redeploy_matrix`
|
||
- `artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service`
|
||
- `artifacts/real-host-acceptance/20260518_reconcile_hostscope_subscription`
|
||
|
||
### 证据解释红线
|
||
1. 不能把 `/api/v1/admin/accounts/:id/models` 与 `/v1/models` 混为一谈
|
||
2. 不能把 `/v1/models = 200` 自动推导成 `/v1/chat/completions = 200`
|
||
3. 不能在未核对在线 CRM 进程版本时，就把 live 现象归因为源码仍有缺陷
|
||
4. 不能把 direct probe artifact 的 401/403 单独当成产品主链路失败；先核对 probe key 语义与脚本参数
|
||
|
||
## 当前执行红线 / 非回归规则
|
||
|
||
1. channel 创建与纠偏必须同时覆盖：
|
||
- `model_mapping`
|
||
- `model_pricing`
|
||
- `restrict_models=true`
|
||
- `billing_model_source=channel_mapped`
|
||
|
||
2. subscription 场景的 gateway probe 语义必须保持：
|
||
- 最终 probe key 是宿主 managed key
|
||
- 不是外部原始 `access_api_key`
|
||
|
||
3. 任何 live 结论都必须先确认：
|
||
- 在线 CRM 进程启动时间
|
||
- 对应 git 提交
|
||
- `PACK_PATH`
|
||
- `CRM_HOST_BASE`
|
||
|
||
4. 真实宿主验收必须分三层落证据：
|
||
- account 视角
|
||
- managed key / 普通用户 `/v1/models` 视角
|
||
- completion smoke 视角
|
||
5. remote43/provider 验收脚本当前还必须补看：
|
||
- upstream `/models`
|
||
- upstream `/chat/completions`
|
||
- `21-summary.json`
|
||
|
||
## 推荐阅读顺序
|
||
|
||
### 想知道“现在到底是什么状态”
|
||
1. `docs/SOURCE_OF_TRUTH.md`
|
||
2. `docs/EXECUTION_BOARD.md`
|
||
3. `docs/PRODUCTION_CLOSURE_BOARD.md`
|
||
|
||
### 想继续做真实宿主验收
|
||
1. `docs/SOURCE_OF_TRUTH.md`
|
||
2. `docs/PROVIDER_ONBOARDING_PLAYBOOK.md`
|
||
3. `docs/PROVIDER_VALIDATION_MATRIX.md`
|
||
4. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
|
||
5. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md`
|
||
6. 再看最新 artifact
|
||
|
||
### 想回顾为什么会演化成现在这样
|
||
1. `docs/SOURCE_OF_TRUTH.md`
|
||
2. `docs/2026-05-18-PRODUCTION_READINESS_REVIEW.md`
|
||
3. `docs/2026-05-18-PRODUCTION_REMEDIATION_TASK_BOARD.md`
|
||
4. 再回到 `docs/EXECUTION_BOARD.md` 看最新真相
|
||
|
||
## 明确禁止的错误读法
|
||
|
||
- ❌ 把历史 review/task board 当当前 gate
|
||
- ❌ 把历史 PASS artifact 当当前 latest-head 真相
|
||
- ❌ 把 `/v1/models` 通过当成 completion 已通过
|
||
- ❌ 把 subscription 场景原始 `access_api_key` 当成最终 probe key
|
||
- ❌ 把 harness 参数错误（`PACK_PATH`、容器目标、probe auth）当成产品源码失败
|