sub2api-cn-relay-manager/docs/REAL_HOST_ARTIFACT_RETENTION.md

# Real-Host Artifact 保留/归档/清理清单

日期：2026-05-22  
项目：`sub2api-cn-relay-manager`

## 用途

本清单用于给 `artifacts/real-host-acceptance/` 下的历史目录做统一分层：

1. 保留为最终证据
2. 归档保留，但日常不必继续关注
3. 可清理的中间试错记录

判断原则：

- 以 `docs/SOURCE_OF_TRUTH.md` 与 `docs/PRODUCTION_CLOSURE_BOARD.md` 的当前真相为准
- 优先看目录内 `21-summary.json`、`05-import.json`、`03-import.body.json`、`07-access-status.json`
- 只把“latest-head / fresh-host / current-code”直接相关的证据放进“最终证据”
- 纯预跑、空目录、只到 preflight、已被后续更完整证据覆盖的目录，放入“可清理”

## Security 分层（新增硬规则）

### A. `safe` artifact（可入库）
满足以下条件时，才允许留在 `artifacts/real-host-acceptance/` 并被文档直接引用：
- 不包含完整 upstream / managed / user API key
- 不包含完整 bearer token
- 不包含 Redis cache key 原文
- 不包含可直接执行的明文 SQL 凭据操作
- headers 已去掉 `Authorization` / `Cookie` / `Set-Cookie` / `x-api-key`
- 身份类字段（user_id / admin_user_id / managed_user_email）已改为 hash 或摘要

### B. `debug` artifact（本地敏感）
以下材料只能作本地短时调试使用，不得视为主证据入库：
- 明文 SQL（例如 subscription access prep 原始语句）
- 带完整 key/token 的 runtime context
- 未脱敏 headers / raw body
- Redis cache key 原文

### C. 解释规则
- 文档中的“最终证据”默认指 `safe` artifact
- 若某目录只能在 `debug` 模式下复现价值，则应迁出主视图或只保留摘要版（例如 `21-summary.json` / `99-semantic-summary.json`）

### D. 历史目录迁移脚本
当历史 `artifacts/real-host-acceptance/` 目录里仍残留旧版敏感材料时，使用：

```bash
python3 scripts/migrate_historical_artifacts.py artifacts/real-host-acceptance
```

默认行为：
- 原地把可安全化文件改写成 `safe` 版本
- 把明文敏感文件移动到 sibling 目录：
  - `artifacts/real-host-acceptance-sensitive/`
- 为旧的 `05-subscription-access-prep.sql` 生成：
  - `05-subscription-access-prep.summary.json`
- 为旧的 `07-redis-targeted-invalidation.txt` 生成：
  - `07-redis-targeted-invalidation.json`

当前脚本会处理的典型历史文件：
- `00-local-key-source.json`
- `01-runtime-context.json`
- `00-context.json`
- `05-subscription-access-prep.sql`
- `07-redis-targeted-invalidation.txt`
- `08-subscription-group-state.json`
- `*.headers.txt`
- `00-managed-key.txt`
- `00-raw-user-key.txt`

脚本不会替你决定“最终证据 / 归档 / 清理”的业务分类；它只负责把旧目录先迁移到可安全审阅的形态。
- 第二轮迁移已补覆盖复杂 JSON 快照：
  - `summary.json`
  - `99-summary.json`
  - `99-semantic-summary.json`
  - `05a-batch-detail-pre-access.json`
  - `07-access-status.json`
  - `10-batch-detail.json`
- 对这类文件，脚本会递归处理常见敏感字段，并额外解析：
  - `DetailsJSON`
  - `details_json`
  - `probe_summary_json`
  这三类 JSON-in-string 字段，先反序列化再脱敏后写回。
- 当前仍需人工关注的残留主要是非标准手工文本快照，例如：
  - `00-managed-key-corrected.txt`
  - 其他不在固定命名集合中的手工 probe 文本
  这些不影响“标准 artifact 已安全化”的结论，但不能直接把主目录视为 100% 无人工遗留。
## 1. 可保留为最终证据

这些目录应长期保留，属于当前 Gate=`APPROVED` 的核心证据。

### 当前主链路最终证据

- `20260521_191418_remote43_minimax_key_import`
  - `subscription` 主链路最终成功样本
  - `21-summary.json` 已到 `batch_status=succeeded`、`provider_status=active`
  - host `/v1/chat/completions` 与 upstream `/chat/completions` 都是 `200`

- `20260521_201509_remote43_deepseek_key_import`
  - `subscription` 主链路最终成功样本
  - `21-summary.json` 已到 `batch_status=succeeded`、`provider_status=active`
  - host `/v1/chat/completions` 与 upstream `/chat/completions` 都是 `200`

- `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`

### 当前根因/能力校准证据

- `20260520_222713_crm18100_live_model_mapping_validation`
  - 证明 `model_mapping` 真实落盘与 live runtime 一致
  - 属于“为什么不再回退 GPT 默认模型”的关键证据

- `20260521_142211_crm18100_deepseek_completion_split`
  - 证明 host completion 失败与 upstream completion 成功可以分离
  - 是 `host_compatibility_gap` 与 `upstream_key_quota_issue` 分流逻辑的重要根因样本

- `20260521_222212_remote43_minimax-m2-7-official_key_import`
  - 官方 MiniMax 模板的真实 live 样本
  - 不是通过样本，但它是“模板链路通、上游 quota/429 阻断”的最终证据
  - 对后续官方 provider 验收矩阵有持续价值

## 2. 可归档但不必继续关注

这些目录有参考价值，但已经不是当前真相的第一证据。建议保留压缩包或移到归档区，不需要日常留在主视图里。

### 早期 OpenAI / host-scope 里程碑样本

- `20260517_openai_platform_fix_retest`
- `20260518_reconcile_hostscope_self_service`
- `20260518_reconcile_hostscope_subscription`
- `20260518_redeploy_matrix`
- `20260521_210306`

说明：

- 这些目录证明过某一阶段的 self-service / subscription / host-scope 语义曾经打通
- 但都已被 `20260521_191418_*`、`20260521_201509_*`、`20260521_210403` 覆盖

### 已定位问题、但已被后续最终修复覆盖的关键失败样本

- `20260520_173133_remote43_deepseek_key_import`
- `20260520_203533_remote43_deepseek_key_import`
- `20260520_203818_remote43_deepseek_key_import`
- `20260520_203913_remote43_minimax_key_import`
- `20260521_011544_remote43_minimax_key_import`
- `20260521_011717_remote43_deepseek_key_import`
- `20260521_064109_remote43_minimax_key_import`
- `20260521_064203_remote43_deepseek_key_import`
- `20260521_064403_remote43_deepseek_key_import`
- `20260521_064454_remote43_minimax_key_import`
- `20260521_110159_remote43_deepseek_key_import`
- `20260521_110229_remote43_minimax_key_import`
- `20260521_172436_remote43_deepseek_key_import`
- `20260521_172437_remote43_minimax_key_import`
- `20260521_172646_remote43_minimax_key_import`
- `20260521_172709_remote43_deepseek_key_import`
- `20260521_182844_remote43_minimax_key_import`
- `20260521_190809_remote43_minimax_key_import`
- `20260521_191026_remote43_minimax_key_import`
- `20260521_200932_remote43_deepseek_key_import`

说明：

- 这些目录记录了“模型列表成功但 completion 失败”“quota 问题”“probe 假失败”“ready 语义修正前后”的完整演进
- 若后续要回顾 debug 过程，它们有价值
- 但对当前上线结论已不是必需证据

### 旧版 full-flow 但已失败/半成功的早期验收目录

- `20260517192934_openai_group_bound_closure`
- `20260517_062209_fixed`
- `20260517_080506_post_fix`
- `20260517_081533_post_decode_fix`
- `20260517_082153_post_account_type_fix`
- `20260517_104007_subscription_after_fix`
- `20260517_104113_subscription_skip_rollback`
- `20260517_live_openai_retest`
- `20260517_live_openai_subscription_retest`
- `20260517_openai_group_balance_retest`
- `20260517_openai_keep_scene`
- `20260518_redeploy_self_service`
- `20260518_redeploy_self_service_keep`
- `20260518_self_service_reaccept_v6`
- `20260518_subscription_reaccept_v6`
- `20260519_self_service_reaccept_current`
- `20260521_202654`
- `20260521_203020`
- `20260521_203229`
- `auto_a5f5185f_minimax_self_service`

说明：

- 这些目录大多是完整流程快照，包含导入、access、provider-status、reconcile、rollback
- 虽然最终失败或半成功，但对复盘“问题怎么一步步收口”仍有价值

## 3. 可以清理掉的中间试错记录

这些目录主要是：

- 空目录
- 只到 create-host / preflight / runtime-context
- 明显被后续同主题目录完全覆盖
- 手工临时试验目录，且已有更完整自动化目录替代

### 空目录或只有极少预跑内容

- `20260516_170617`
- `20260517_000027`
- `20260518_redeploy_subscription_keep`
- `20260519_111543_remote43_local_minimax_key_import`
- `20260521_195330_remote43_deepseek_key_import`
- `20260521_221921_remote43_minimax-m2-7-official_key_import`

### 仅 preflight / install-pack / preview，未形成有效验收结论

- `20260516_155350`
- `20260516_170410`
- `20260516_170421`
- `20260516_170607`
- `20260516_170725`
- `20260516_171131`
- `20260517_000418`
- `20260517_061947_postfix`
- `20260517_062722_after_account_fix`
- `20260517_102113_subscription_probe`
- `20260517_live_openai_subscription_nokey`
- `20260520_115443_remote43_deepseek_key_import`
- `20260520_115505_remote43_deepseek_key_import`
- `20260520_115549_remote43_deepseek_key_import`
- `20260520_123159_remote43_deepseek_key_import`
- `20260520_172725_remote43_deepseek_key_import`
- `20260520_173010_remote43_deepseek_key_import`
- `20260520_184240_remote43_deepseek_key_import`
- `20260520_185332_remote43_deepseek_key_import`
- `20260520_194731_remote43_deepseek_key_import`
- `20260520_194818_remote43_deepseek_key_import`
- `20260520_194946_remote43_deepseek_key_import`
- `20260520_195110_remote43_deepseek_key_import`
- `20260521_011452_remote43_minimax_key_import`
- `20260521_171701_remote43_deepseek_key_import`
- `20260521_172212_remote43_deepseek_key_import`
- `20260521_172213_remote43_minimax_key_import`
- `20260521_172337_remote43_deepseek_key_import`
- `20260521_172338_remote43_minimax_key_import`
- `20260521_182744_remote43_minimax_key_import`
- `20260521_190534_remote43_minimax_key_import`
- `20260521_190941_remote43_minimax_key_import`
- `20260521_195348_remote43_deepseek_key_import`
- `20260521_195413_remote43_deepseek_key_import`
- `20260521_195635_remote43_deepseek_key_import`
- `20260521_200014_remote43_deepseek_key_import`
- `20260521_200217_remote43_deepseek_key_import`
- `20260521_200733_remote43_deepseek_key_import`
- `20260521_204702`
- `20260521_221940_remote43_minimax-m2-7-official_key_import`
- `20260521_222052_remote43_minimax-m2-7-official_key_import`
- `auto_4431135c_openai_subscription`

### 手工临时 reaccept 目录，已被后续自动化 remote43 目录覆盖

- `20260520_115732_remote43_deepseek_manual_reaccept`
- `20260520_115820_remote43_deepseek_manual_reaccept`
- `20260520_120656_remote43_deepseek_manual_reaccept`
- `20260520_120819_host18080_deepseek_manual_reaccept`
- `20260520_121447_host18091_deepseek_manual_reaccept`
- `20260520_121640_host18091_deepseek_manual_reaccept`
- `20260520_121936_crm18092_host18091_deepseek_manual_reaccept`

## 建议执行方式

### 低风险做法

1. 先保留“最终证据”原样不动
2. 把“可归档”目录打包移动到归档区，例如：
   - `artifacts/real-host-acceptance-archive/`
3. 把“可清理”目录删除

### 不建议的做法

- 不要只按时间删除最新之前的所有目录
- 不要删除 `20260521_191418_remote43_minimax_key_import`
- 不要删除 `20260521_201509_remote43_deepseek_key_import`
- 不要删除 `20260521_210403`
- 不要删除 `20260520_222713_crm18100_live_model_mapping_validation`
- 不要删除 `20260521_142211_crm18100_deepseek_completion_split`
- 不要删除 `20260521_222212_remote43_minimax-m2-7-official_key_import`