Skip to content

feat(provider): 接入 OpenAI 兼容模型服务与工具流式协议 - #60

Merged
Qiyuanqiii merged 1 commit into
mainfrom
codex/issue-47-openai-compatible-provider
Aug 14, 2026
Merged

Qiyuanqiii merged 1 commit into
mainfrom
codex/issue-47-openai-compatible-provider

Conversation

@Qiyuanqiii

Copy link
Copy Markdown
Member

背景

解决 #47。

现有工作台已经支持本地模型与 Anthropic-compatible Provider,但 OpenAI Chat Completions 的消息结构、工具调用增量、流式 usage、结束原因和错误协议均有独立语义,不能安全地复用 Anthropic wire adapter。同时,原有诊断结果只能表达较粗的成功或失败,无法稳定区分未配置、认证失败、网络失败、限流、容量不足、模型不存在和协议不兼容。

本 PR 新增独立的 OpenAI 兼容模型接入链路,并继续复用既有 Supervisor、Harness 和工具执行边界;仓库配置不会获得注入端点、请求头或凭据的权限。

主要改动

1. 独立 OpenAI Chat Completions Provider

  • 新增独立 Provider,实现 GET /v1/models 与 POST /v1/chat/completions。
  • 支持普通文本、严格 JSON 模式、原生工具定义和多轮工具结果回送。
  • 将内部 assistant 工具调用映射为 OpenAI tool_calls,并将每个工具结果展开为独立的 role: tool 消息。
  • 流式请求启用 stream_options.include_usage,在收到 [DONE] 后只输出一个包含完整工具调用与 usage 的最终 chunk。
  • 按工具调用 index 聚合交错到达的 id、name 与 arguments 增量;中间 chunk 不暴露半成品工具调用。
  • 严格校验模型标识、usage 合计、finish_reason、UTF-8、SSE 结束状态、工具参数 JSON、重复或稀疏 index 以及流内模型漂移。
  • 允许上游将模型别名解析为具体快照,但对工作台内部继续返回稳定的请求模型引用。

2. Registry、凭据与路由集成

  • 新增 canonical Provider openai 与独立的 openai_compatible kind。
  • 支持 CYBERAGENT_OPENAI_API_KEY、CYBERAGENT_OPENAI_BASE_URL、CYBERAGENT_OPENAI_MODEL。
  • 接入系统凭据存储;控制面只返回配置状态,不返回明文凭据。
  • Provider 注册、模型可用性快照、路由选择和 Registry 原子 reload 全部支持 OpenAI。
  • 外部 OpenAI 兼容模型默认要求 Harness 资格验证;端点、模型或协议策略变化会使旧资格记录失效并 fail closed。
  • Harness 绑定摘要只包含非秘密的协议事实,不包含 API key。

3. 诊断与 Harness 资格结果

  • 新增稳定且不含响应正文的失败原因:not_configured、authentication、network、rate_limit、capacity、model_not_found、protocol_incompatible。
  • 未配置 Provider 的诊断与资格检查会以零网络、零模型调用返回 not_configured,不再先抛出结构性错误。
  • HTTP 404 默认保守归为协议不兼容;只有 OpenAI 标准错误体中的精确 code/type 才归为模型不存在,避免近似字符串误分类。
  • 主动 cancellation 与 deadline 分开处理:主动取消保持取消语义,deadline 才归入网络失败。
  • 修复 Provider 因 context 到期关闭流时的竞态,确保资格检查不会随机在网络失败与协议错误之间漂移。
  • 诊断请求限制为 128 tokens,Harness 每轮限制为 256 tokens,并继续使用固定合成 nonce;资格检查不会执行真实工具。

4. CLI、HTTP、OpenAPI 与 Web 控制面

  • CLI 的 Provider 列表、诊断与资格输出增加 OpenAI kind、transport 与 failure reason。
  • HTTP 视图和 OpenAPI 增加严格枚举,并将凭据 Provider 路径限制为受管 Provider 集合。
  • Web 客户端使用严格运行时解析器,拒绝未知枚举、非字符串枚举和互相矛盾的状态组合。
  • 模型可用性对话框可配置 OpenAI 系统凭据,并展示诊断或资格失败原因。
  • 同步更新生成的 OpenAPI JSON、TypeScript schema、使用说明、架构说明与示例配置。

5. 安全与隐私边界

  • OpenAI Provider 不保留 ChatResponse.Raw,也不会将上游错误正文、prompt、tool arguments、私有 reasoning 字段或原始 SSE delta 写入错误、日志、Activity 或 SQLite。
  • 出站请求只使用固定的 Authorization、Content-Type 与 Accept 头;不转发内部 Metadata。
  • 禁止 redirect,端点要求安全的 HTTP(S) 结构;非 loopback HTTP、userinfo、query 和 fragment 均被拒绝。
  • HTTP client 最长超时限制为 60 秒,同时保留测试或调用方提供的更短超时。
  • API key 不进入 Harness digest、OpenAPI、Web 响应或持久化 Provider settings。
  • configs/models.yaml 仍是说明性示例,不成为运行时端点、请求头或凭据来源。

用户与开发者影响

  • 用户可以通过环境变量或系统凭据管理器配置标准 OpenAI 或兼容 Chat Completions 的服务。
  • 未配置 OpenAI 时不会发起网络请求,也不会影响现有 local、Anthropic、DeepSeek 或 MiMo 路由。
  • 新外部模型只有通过合成 Harness 工具调用、工具结果回送、严格 JSON 和流式协议验证后,才可用于需要结构化能力的根模型路径。
  • 对不返回 usage、提前结束 SSE、返回不受支持 finish reason 或工具增量不完整的兼容端点,将明确判定为 protocol_incompatible,避免截断结果进入 Supervisor。

验证

  • go test:internal/llm、internal/modelregistry、internal/application、internal/httpapi、internal/app、internal/credential、internal/desktop、internal/events 全部通过。
  • go vet ./... 通过。
  • OpenAI Provider、Harness deadline 竞态与 Supervisor 两轮工具循环的 race/压力测试通过。
  • 真实 Provider + httptest SSE 的 Supervisor E2E 通过,验证工具调用持久化 ID、独立 role: tool 回送、单次工具执行以及 Session 只提交一对最终消息。
  • Web 全量测试:59 个文件、230 项全部通过;TypeScript typecheck 与 production build 通过。
  • OpenAPI JSON 与 TypeScript schema 重生成一致。
  • 使用一次性 DeepSeek v4 Flash 兼容端点完成 opt-in live smoke:诊断成功,Harness 两轮资格验证成功;未执行真实工具,凭据与临时测试文件均未进入提交。

风险与回滚

  • 新 Provider 只有显式配置后才注册,未配置环境的默认行为不变。
  • OpenAI wire 实现与 Anthropic wire 实现相互独立,可通过移除 OpenAI 配置或回退本提交恢复原行为。
  • 本 PR 对协议采取严格、fail-closed 策略;若某个兼容端点偏离标准,应先明确增加受控兼容策略与测试,而不是放宽全局解析。

Closes #47

新增独立的 OpenAI Chat Completions Provider,实现普通对话、严格 JSON、SSE 流式输出、多工具调用增量聚合、usage 与 finish_reason 校验,以及工具结果的多轮消息映射。

贯通模型注册、系统凭据、诊断、Harness 资格验证、路由预检、CLI、HTTP、OpenAPI 与 Web 控制面;新增稳定且不含响应正文的失败原因分类,并确保未配置 Provider 可以零网络返回诊断结果。

补齐内容隔离、取消与超时分类、404 精确分类、流关闭竞态、端点与超时约束、生成物一致性及 Supervisor 两轮工具循环测试。关联 #47。
@Qiyuanqiii
Qiyuanqiii marked this pull request as ready for review August 14, 2026 07:08
@Qiyuanqiii
Qiyuanqiii merged commit 57b4d1b into main Aug 14, 2026
5 checks passed
@NanaseInori
NanaseInori deleted the codex/issue-47-openai-compatible-provider branch September 16, 2026 09:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(provider): OpenAI-compatible Provider 与工具流式协议

1 participant