sub2api-cn-relay-manager/docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md

Plugin Host Enhancement vNext TDD Plan

For Hermes: 先完成宿主能力探测与规格收口，再开始实现。任何“支持某模型/某池化/某治理能力”的结论都必须有真实验收脚本与当前输出。

Goal: 把“宿主协议兼容、同模型多供应商池化、用户前端承接、自助 key 发放、key/账号治理”拆成可执行任务，且每一阶段都能独立验收。

Architecture: 采用“先探测、再抽象、后接入”的路线。先在 internal/host/sub2api 建 capability inventory，再在 internal/provision / internal/access 建模型池与 key 治理语义，最后把用户能力落到 deploy/tksea-portal/ 与必要的插件 API。

Tech Stack: Go 1.22, SQLite, static portal HTML/CSS/JS, existing acceptance scripts, sub2api host adapter.

---

Phase 0 — 真相收口与基线

Task 0.1: 固化 vNext 规格文档

Objective: 把用户提到的五类问题写成正式 spec，避免后续实现方向漂移。

Files:

• Create: docs/2026-06-04-plugin-host-enhancement-SPEC.md
• Create: docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md
• Modify: docs/EXECUTION_BOARD.md

Verify:

• git diff -- docs/2026-06-04-plugin-host-enhancement-SPEC.md docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md docs/EXECUTION_BOARD.md
• 预期：三个文档均存在，且 execution board 明确把它们列为当前 vNext 真相源。

Task 0.2: 建立 capability evidence 目录规范

Objective: 为后续宿主探测建立统一证据目录与命名规范。

Files:

• Create: artifacts/host-capability/README.md
• Create: scripts/acceptance/verify_host_protocol_matrix.sh
• Create: scripts/acceptance/verify_host_pool_routing.sh
• Create: scripts/acceptance/verify_user_key_self_service.sh

Acceptance:

• 三个脚本至少先具备 usage/help、环境变量检查、输出目录创建逻辑
• artifacts/host-capability/README.md 说明每个脚本产出的 JSON / log / summary 结构

Verify:

• bash ./scripts/acceptance/verify_host_protocol_matrix.sh --help
• bash ./scripts/acceptance/verify_host_pool_routing.sh --help
• bash ./scripts/acceptance/verify_user_key_self_service.sh --help

---

Phase 1 — 宿主协议能力探测

Task 1.1: 建 capability model

Objective: 在代码里表达“某宿主 / 某线路 / 某模型”支持什么协议与当前健康状态。

Files:

• Create: internal/host/sub2api/capability_inventory.go
• Create: internal/host/sub2api/capability_inventory_test.go
• Modify: internal/host/sub2api/ 相关 adapter 文件（按实际需要）

Acceptance:

• 支持记录：model, provider, protocol_family, support_level, evidence_ref, last_probe_status
• 支持分类：supported-direct / supported-with-plugin-adapter / unsupported-by-host / upstream-unhealthy

Verify:

• go test ./internal/host/sub2api -run Capability -count=1

Task 1.2: 真实协议矩阵探测脚本

Objective: 用真实上游和宿主入口生成能力矩阵，不再靠口头判断。

Files:

• Modify: scripts/acceptance/verify_host_protocol_matrix.sh
• Create: docs/host-capability-matrix-template.md

Acceptance:

• 能输出按模型/协议/上游分类的 summary JSON
• 至少覆盖 GPT / DeepSeek / MiniMax / Kimi / GLM
• 显式记录 chat=200、models-only、429、403、协议不兼容等状态

Verify:

• bash ./scripts/acceptance/verify_host_protocol_matrix.sh
• 预期：生成 artifacts/host-capability/<timestamp>/protocol-matrix-summary.json

Task 1.3: 形成宿主协议矩阵结论文档

Objective: 把脚本结果沉淀成可读设计结论，说明哪些模型必须插件补偿。

Files:

• Create: docs/2026-06-xx-HOST_PROTOCOL_MATRIX.md
• Modify: docs/EXECUTION_BOARD.md

Acceptance:

• 每条结论都引用 artifact 路径
• Kimi 的结论必须区分“上游过载”和“宿主协议转换不足”

Verify:

• 文档人工回读 + artifact 路径存在校验

---

Phase 1.5 — vNext.1 范围收紧与发布边界

Task 1.5.1: 固化 release scope

Objective: 在继续实现前冻结 vNext.1 / vNext.2 / vNext.3 边界，禁止范围混跑。

Files:

• Create: docs/2026-06-04-vnext-release-scope.md
• Modify: docs/2026-06-04-plugin-host-enhancement-SPEC.md
• Modify: docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md
• Modify: docs/EXECUTION_BOARD.md

Acceptance:

• 明确 vNext.1 只做能力矩阵 + 模型池 + 默认链路准入 + 幂等初始化前置
• key 自助 / 治理 / SLO 明确降级为后续版本
• execution board 明确“审核通过前不继续实现”

Verify:

• git diff -- docs/2026-06-04-vnext-release-scope.md docs/2026-06-04-plugin-host-enhancement-SPEC.md docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md docs/EXECUTION_BOARD.md

Phase 2 — 同模型多供应商池化

Task 2.1: 设计模型池抽象

Objective: 不再把一个逻辑模型等同于一条 provider 线路，而是抽象为 route pool。

Files:

• Create: docs/2026-06-xx-MODEL_POOL_DESIGN.md
• Create: internal/provision/model_pool.go
• Create: internal/provision/model_pool_test.go

Acceptance:

• 一个逻辑模型可对应多个候选 route
• route 具备 priority、schedulable、cooldown、disable reason、supported models
• active pool 默认硬排除 HostReady=false 与 Schedulable=false
• SupportsResponses 判断不得被其他模型 advisory 污染
• 文档用词明确为 priority failover，不承诺完整负载均衡池化

Verify:

• go test ./internal/provision -run ModelPool -count=1

Task 2.2: 宿主池化映射编排

Objective: 明确如何用现有宿主 group/channel/account 能力表达模型池。

Files:

• Modify: internal/provision/import_service.go
• Modify: internal/provision/runtime_import_service.go
• Modify: internal/provision/*_test.go

Acceptance:

• 导入逻辑可以为同组配置多 channel / 多 account 候选
• 不把宿主 schema 的偶然细节泄漏到 portal UI

Verify:

• go test ./internal/provision -count=1
• go test ./tests/integration/... -count=1

Task 2.3: 真实池化路由验收

Objective: 证明同一个分组内两个供应商能服务同一模型，并在失败时切换。

Files:

• Modify: scripts/acceptance/verify_host_pool_routing.sh
• Create: tests/integration/pool_routing_test.go

Acceptance:

• 至少一组模型完成“双供应商同模型名”验收
• 证明人工暂停 / 自动失败后不会继续命中坏线路

Verify:

• bash ./scripts/acceptance/verify_host_pool_routing.sh
• go test ./tests/integration/... -run PoolRouting -count=1

---

Phase 2 之后（后续版本，仅设计占位，当前不进入实现）

以下 phase 保留为后续版本设计占位，当前审核目标不是继续实现，而是先冻结边界：

• vNext.2：用户前端承接与自助 key
• vNext.3：治理与 SLO

Phase 3 — 用户前端承接与自助 key

Task 3.1: 用户信息架构设计

Objective: 定义用户 portal 该展示什么，而不是继续停留在目录页。

Files:

• Create: docs/2026-06-xx-PORTAL_KEY_EXPERIENCE.md
• Modify: deploy/tksea-portal/index.html
• Modify: deploy/tksea-portal/portal.js
• Modify: deploy/tksea-portal/portal.css

Acceptance:

• 页面原型至少覆盖：key 列表、key 状态、分组、模型、使用示例、复制按钮
• 明确“仅首次显示明文 key”的交互

Verify:

• bash ./scripts/test/test_tksea_portal_assets.sh
• bash ./scripts/test/verify_frontend_smoke.sh

Task 3.2: 插件侧 key 发放 API 设计

Objective: 明确 key 是如何申请、回显、绑定分组与展示示例的。

Files:

• Create: docs/2026-06-xx-KEY_SELF_SERVICE_API.md
• Modify: internal/app/ 相关 handler / service / repo 文件（按实现需要）
• Create: internal/app/key_self_service_test.go

Acceptance:

• 返回：key 明文（首次）、base URL、模型列表、group、状态、限额
• 不把宿主 secret 二次暴露到无权限场景

Verify:

• go test ./internal/app -run KeySelfService -count=1
• 前端若接入动作，再跑：bash ./scripts/acceptance/verify_provider_admin_actions.sh

Task 3.3: 用户首次调用闭环

Objective: 用户拿到 key 后，不需要看聊天记录就能完成首次 200 调用。

Files:

• Modify: deploy/tksea-portal/index.html
• Modify: deploy/tksea-portal/portal.js
• Modify: scripts/acceptance/verify_user_key_self_service.sh

Acceptance:

• 页面能展示 curl 示例
• 脚本能验证“登录/申请 key/复制示例/调用 200”整条链路

Verify:

• bash ./scripts/acceptance/verify_user_key_self_service.sh

---

Phase 4 — key / 账号暂停与限额治理

Task 4.1: 状态模型与治理语义

Objective: 给 key / account 的暂停、恢复、限额建立统一语义。

Files:

• Create: docs/2026-06-xx-KEY_ACCOUNT_GOVERNANCE.md
• Create: internal/access/key_policy.go
• Create: internal/access/key_policy_test.go

Acceptance:

• 支持 admin_status / health_status / quota_status 三态模型：
  • admin_status = active / paused / disabled / retired
  • health_status = healthy / degraded / unhealthy / unknown
  • quota_status = ok / exhausted / limited / unknown
• 支持至少一种限额方式先落地（建议先做请求次数或额度上限）

Verify:

• go test ./internal/access -run KeyPolicy -count=1

Task 4.2: 管理页治理动作

Objective: 让管理员能在 portal/admin 中操作 key/账号状态。

Files:

• Modify: deploy/tksea-portal/accounts.html
• Modify: deploy/tksea-portal/providers.html
• Modify: deploy/tksea-portal/admin-common.js
• Modify: deploy/tksea-portal/admin-common.css

Acceptance:

• 可见暂停/恢复按钮、限额信息、原因说明
• 操作后页面状态即时刷新

Verify:

• bash ./scripts/test/test_tksea_portal_assets.sh
• bash ./scripts/test/verify_frontend_smoke.sh
• bash ./scripts/acceptance/verify_provider_admin_actions.sh

Task 4.3: 真实治理验收

Objective: 验证暂停 key / 暂停账号 / 超限都能反映到用户调用结果。

Files:

• Create: scripts/acceptance/verify_key_governance.sh
• Create: tests/integration/key_governance_test.go

Acceptance:

• 暂停 key 后用户调用失败且原因清晰
• 恢复后重新 200
• 账号暂停后池路由切到其他健康线路或给出正确失败原因

Verify:

• bash ./scripts/acceptance/verify_key_governance.sh
• go test ./tests/integration/... -run KeyGovernance -count=1

---

Phase 5 — 发布准入

Task 5.1: 默认链路准入规则

Objective: 把“哪些模型池可以进入默认消费链路 / consumer default chain”写成硬规则，并明确 OpenClaw 写入仅属于 consumer acceptance，不属于本项目发布完成条件。

Files:

• Modify: docs/EXECUTION_BOARD.md
• Create: docs/2026-06-xx-DEFAULT_CHAIN_ADMISSION.md

Acceptance:

• 只有真实用户 chat=200 的模型池能进入默认链路
• 明确禁止以 /v1/models=200 或 admin 创建成功充当发布依据

Verify:

• 文档回读 + 实际 artifact 引用存在

Task 5.2: 最终多层验证

Objective: 实施前/发布前必须统一跑完整门禁。

Verify Commands:

• gofmt -l .
• go vet ./...
• go test -cover ./internal/...
• go test ./tests/integration/... -count=1
• bash ./scripts/test/test_tksea_portal_assets.sh
• bash ./scripts/test/verify_frontend_smoke.sh
• bash ./scripts/acceptance/verify_provider_admin_actions.sh
• bash ./scripts/acceptance/verify_host_protocol_matrix.sh
• bash ./scripts/acceptance/verify_host_pool_routing.sh
• bash ./scripts/acceptance/verify_user_key_self_service.sh
• bash ./scripts/acceptance/verify_key_governance.sh

---

风险清单

1. 宿主对某些模型协议并不真正兼容，只是 /v1/models 暴露成功
2. Kimi/GLM 类模型可能需要插件侧额外适配层，但当前仓库未必已有对应抽象
3. 若宿主没有稳定 key 治理 API，插件需先做“控制面约束 + 前端提示”的降级方案
4. 前端接管过多能力时，必须防止文档/页面承诺超出宿主真实行为

最短闭环路径

1. 先做协议矩阵探测
2. 再做模型池抽象
3. 然后做 key 自助发放与用户首次调用闭环
4. 最后做治理动作与默认链路准入

本轮计划交付物

已写入：

• docs/2026-06-04-plugin-host-enhancement-SPEC.md
• docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md

待后续实现时必须同步：

• docs/EXECUTION_BOARD.md
• 对应 acceptance scripts
• 对应 integration tests