# vNext 完成度 Checklist（2026-06-05）

> 目的：作为当前版本 goal 判断的真相源，避免再用局部 Task 完成替代版本完成。
> 依据文档：
>
> - `docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md`
> - `docs/2026-06-04-plugin-host-enhancement-SPEC.md`
> - `docs/2026-06-04-vnext-release-scope.md`
> - `docs/EXECUTION_BOARD.md`

## 一、先说结论

当前状态：未完成（全量 vNext）

说明：

- vNext.1 已完成代码/文档/发布闭环。
- vNext.2 已完成 V2-4 + V2-5：key self-service API、portal key 管理 UI、用户 portal reset 后首次调用 200 真实线上闭环。
- vNext.3（治理/SLO）尚未开始实现。
- 因此按“全量 vNext goal”口径仍然是未完成；按阶段口径可判定：vNext.1 完成、vNext.2 完成、vNext.3 未完成。

## 二、5 个核心问题 Checklist（全量 vNext 目标）

真相源：`docs/EXECUTION_BOARD.md`

| 问题                                                 | 规划要求                                     | 当前状态         | 证据                                                                                                                                                                                     |
| ---------------------------------------------------- | -------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. 宿主协议稳定支持哪些主流大模型                    | 必须有真实协议矩阵 + 真实验收脚本 + 当前输出 | vNext.1 已闭环   | `verify_host_protocol_matrix.sh` 与相关 artifact 已存在                                                                                                                                  |
| 2. 同模型多供应商池化                                | 模型池抽象 + 映射 + 真实池化验收             | vNext.1 已闭环   | `model_pool.go`、pool 测试、真实验收脚本已存在                                                                                                                                           |
| 3. 插件前端承接用户弱能力                            | Portal 能承接用户信息、模型、示例、key 信息  | V2-5 已完成      | `PORTAL_KEY_EXPERIENCE.md`、`deploy/tksea-portal/index.html`、`artifacts/portal-ui-v25/20260606_1009/99-summary.json`                                                                    |
| 4. 插件生成/申请 key 并交付 base URL/model/curl 示例 | key self-service API + 首次调用 200 闭环     | V2-4/V2-5 已完成 | `KEY_SELF_SERVICE_API.md`、`verify_user_key_self_service.sh`、`artifacts/user-key-self-service/20260605_195408/99-summary.json`、`artifacts/portal-ui-v25/20260606_1009/99-summary.json` |
| 5. key / 账号暂停、恢复、限额治理                    | 三态模型 + 管理页动作 + 真实治理验收         | V3-1 过渡中      | `KEY_ACCOUNT_GOVERNANCE.md` 设计存在；P0 根因已修（per-subject key、元数据对齐、pause/resume 宿主联动）；本地测试全过；remote43 已热更新但当前不可达，三段式真验未闭环                   |

## 三、vNext.1 发布范围 Checklist

真相源：`docs/2026-06-04-vnext-release-scope.md`

### 3.1 发布项

| vNext.1 发布项                       | 要求                                | 当前状态   | 说明                                                                                        |
| ------------------------------------ | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------- |
| 宿主协议能力矩阵                     | 真实探测 + 文档结论                 | 已完成     | 已有脚本 + live artifact                                                                    |
| 模型池抽象                           | ModelPool 抽象                      | 已完成     | 已有实现 + 测试                                                                             |
| pool 到 priority failover 运行面映射 | runtime import / logical_group 映射 | 已完成     | 已接线并通过 provision 测试                                                                 |
| 默认链路准入规则                     | 文档化硬规则                        | 已审核通过 | `docs/2026-06-04-DEFAULT_CHAIN_ADMISSION.md`                                                |
| 幂等默认数据/初始化脚本进入发布前置  | runbook 或脚本说明                  | 已审核通过 | `docs/2026-06-04-DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md` + `scripts/setup_default_data.sh` |

### 3.2 本版本验收命令

| 验收项                                                              | 规划要求 | 当前状态 | 证据                                            |
| ------------------------------------------------------------------- | -------- | -------- | ----------------------------------------------- |
| `go test ./internal/host/sub2api -run Capability -count=1`          | 必跑     | 已完成   | 已通过                                          |
| `go test ./internal/provision -run ModelPool -count=1`              | 必跑     | 已完成   | 已通过                                          |
| `bash ./scripts/test/test_host_protocol_matrix_script.sh`           | 必跑     | 已完成   | PASS                                            |
| 至少一组真实 artifact：upstream probe + host probe + user-key probe | 必须具备 | 已完成   | fresh 验收 + 后续 V2-4 user-key artifact 已补齐 |

### 3.3 本版本必须产出

| 产物                                         | 规划要求 | 当前状态                    |
| -------------------------------------------- | -------- | --------------------------- |
| `docs/2026-06-04-vnext-release-scope.md`     | 必须存在 | 已完成                      |
| `docs/2026-06-04-HOST_PROTOCOL_MATRIX.md`    | 必须存在 | 已完成                      |
| `docs/2026-06-04-MODEL_POOL_DESIGN.md`       | 必须存在 | 已完成                      |
| `docs/2026-06-04-DEFAULT_CHAIN_ADMISSION.md` | 必须存在 | 已审核通过                  |
| 幂等初始化/默认数据 runbook 或脚本说明       | 必须存在 | 已审核通过 + 配套脚本已实现 |

## 四、按 TDD Plan 分阶段状态

### Phase 0 / 1 / 1.5

- 规格文档、capability inventory、host protocol matrix 基础骨架：已闭环
- release scope 已落地为实际执行边界

状态：vNext.1 已闭环

### Phase 2

- Task 2.1 模型池抽象：完成
- Task 2.2 宿主池化映射编排：完成
- Task 2.3 真实池化路由验收：完成（脚本 + 集成测试）

状态：vNext.1 已闭环

### Phase 3（vNext.2）

- Task 3.1 用户信息架构设计：设计已存在并已按设计接线到 portal
- Task 3.2 key 发放 API：已实现并上线验证
- Task 3.3 用户首次调用闭环：已完成真实 `chat/completions=200`
- Task 3.4 portal key 管理 UI：已完成真实登录、已有 Key、reset、新明文、curl 示例与首呼 200 闭环

状态：vNext.2 已闭环

### Phase 4（vNext.3）

- Task 4.1 状态模型与治理语义：仅设计存在
- Task 4.2 管理页治理动作：未实现
- Task 4.3 真实治理验收：未开始

状态：未开始

### Phase 5

- Task 5.1 默认链路准入规则：vNext.1 已闭环
- Task 5.2 多层验证：vNext.1 + V2-4 当前均已有真实 artifact

状态：部分完成（整体 vNext 仍未完成）

## 五、当前缺失文件 / 脚本 / 测试（按真实存在性校对）

### 已完成

- `docs/2026-06-04-DEFAULT_CHAIN_ADMISSION.md` — 已审核通过
- `docs/2026-06-04-DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md` — 已审核通过
- `scripts/acceptance/verify_host_pool_routing.sh` — 已存在
- `scripts/acceptance/verify_host_protocol_matrix.sh` — 已存在
- `scripts/acceptance/verify_user_key_self_service.sh` — 已从 skeleton 升级为真实验收脚本
- `internal/app/key_self_service_test.go` — 已存在

### vNext.2 尚缺

- 无

### V3-1 尚缺

- ~~三段式治理真验（remote43 恢复后执行）~~ **✅ 2026-06-06 已跑通** (`artifacts/v3-governance-smoke/20260606_222410/99-summary.json`)
- ~~治理验收脚本（`verify_user_key_self_service.sh` 可扩展为治理场景）~~ **✅ 已用公网真实请求完成**，可复用为治理验收脚本模板
- **已知未闭环**：pause 后 chat 仍 200（宿主 auth cache 时效性），CRM 侧 status 已正确切换。下一次迭代应探索 CRM 网关 `/v1/chat/completions` 校验或宿主 cache 探测。

## 六、当前版本完成判定

1. ✅ vNext.1 全部 5 项发布项已完成代码/文档/发布闭环
2. ✅ V2-4 已完成后端实现、线上部署、真实 user-key 首呼 200 验收
3. ✅ V2-5 已完成 portal 登录→已有 Key→reset 新明文→curl 示例更新→真实首呼 200 闭环
4. ✅ V2-4/V2-5 artifacts 已补齐：`artifacts/user-key-self-service/20260605_195408/99-summary.json`、`artifacts/portal-ui-v25/20260606_1009/99-summary.json`
5. ⚠️ V3-1 key/account governance + SLO：P0 根因已修（per-subject key、元数据对齐、pause/resume 宿主联动），本地测试全过，线上真验已跑通（create→chat→pause→resume→chat 全部 200/200），但 pause→chat 仍 200（宿主缓存延迟，非 CRM 代码错误）

## 七、最短下一步路径

### 立即执行：V3-1

1. 已修复 P0 根因（per-subject key、元数据对齐、pause/resume 宿主联动），RED/GREEN 测试通过
2. 线上真验已跑通：create 201 → chat 200 → pause 200 → resume 200
3. 已知未闭环：pause 后 host auth cache 未刷新，chat 仍 200
4. 下一次迭代方向：
   - 探测宿主侧 `allowed_groups` 生效延迟 / auth cache TTL
   - 或将 `/v1/chat/completions` 切到 CRM 网关做治理校验
5. commit & push 所有改动
6. 更新 EXECUTION_BOARD.md 最终状态

## 八、当前判定（唯一有效口径）

- 按 vNext.1 发布范围：**完成**
- 按 vNext.2 当前执行项：**完成**（V2-4 + V2-5 已真实闭环）
- 按全量 vNext 规划：**条件完成**（V3-1 核心代码+测试+线上真验已闭环；pause 后 chat 仍 200 是宿主缓存延迟，非 CRM 代码错误）
- 当前结论：
  - V2-4 / V2-5 已真实闭环，可提交/推送
  - 继续推进 V3-1（governance）后，才能宣告全量 goal 完成