[ops] 记录 LLM provider 校验职责应下沉到 OpenCode serve

[liujuanjuan1984]

背景

当前 #148 / PR #196 为了补齐 deploy 自动化契约，在本仓库的 deploy 主路径里增加了部分 LLM provider 校验：

• scripts/deploy/setup_instance.sh
  • OPENCODE_PROVIDER_ID / OPENCODE_MODEL_ID 成对校验
  • 已知 provider 的 secret 前置校验
• scripts/deploy/run_opencode.sh
  • 已知 provider 的 secret 运行时校验（defense in depth）

这样做在当前阶段是合理的，因为本仓库需要先让 deploy 结果可判定，避免出现“部署脚本成功但 OpenCode 实际无法使用”的半成功状态。

但从更清晰的架构边界看，LLM provider/model/secret 的最终解释权不应长期留在 opencode-a2a-server 的外层 deploy 脚本中，而应尽量下沉到 OpenCode 自身的 serve 启动侧或其原生配置校验入口。

现状复现

当前只要部署脚本声明默认 provider/model，本仓库就需要在 deploy 层维护一部分 provider 规则。

复现路径：

1. 在 deploy 输入中设置：
   • opencode_provider_id=<provider>
   • opencode_model_id=<model>
2. 由本仓库的 deploy 脚本决定：
   • 是否要求对应 provider secret
   • 何时失败
   • 如何向 operator / agent 暴露失败语义

这意味着 provider 语义目前部分落在本仓库，而不是完全由 OpenCode 自身负责。

实际行为

当前行为是：

• 本仓库 deploy 层对已知 provider 做最小必要校验
• 这解决了 deploy 可判定性问题
• 但也带来了架构层面的职责漂移：
  • provider 列表可能随 OpenCode 演进而变化
  • provider 对应 secret 规则本应由 OpenCode 自身定义
  • 外层脚本长期复制这些规则，容易产生漂移和重复维护

期望行为

长期上应收敛为：

• OpenCode 自身提供权威的 provider/model/config 校验能力
• opencode-a2a-server 的 deploy 层只负责：
  • 收集部署参数
  • 调用 OpenCode 的权威校验/启动入口
  • 统一包装 deploy/readiness/exit-code 契约

也就是说：

• deploy 是否可编排，仍属于本仓库
• provider 语义与合法性解释，应尽量属于 OpenCode

建议方向

可以考虑的落地方向：

1. OpenCode serve 启动时直接执行更明确的 provider/model/secret 校验
2. OpenCode 提供单独的配置校验入口，例如：
   • opencode serve --validate-config
   • opencode doctor
   • 或等价的启动前检查接口
3. 本仓库后续改为调用上游权威校验，而不是继续扩展本地 provider 规则表

验收标准

• 明确记录：LLM provider 校验的长期归属应下沉到 OpenCode
• 梳理本仓库当前保留哪些“过渡性最小校验”
• 明确未来当 OpenCode 提供原生校验入口后，本仓库应如何收敛/删除重复逻辑
• 如有必要，再拆分出上游 OpenCode issue/提案

关联

• Relates to [Priority: Med] [Ops] 补齐 deploy 自动化契约：非交互预检、健康验收与参数校验 #148
• Relates to ops: harden deploy automation contracts #196

参考快照

• repo HEAD: da468c8