v5.0.7

AIClient-2-API 发布说明 (v5.0.7)

v5.0.7 是 v5.0.6 之后的 Zed 通道重构与稳定性版本。

本轮完成 Zed 单跳协议感知转换、模型元数据运行时注册表与磁盘缓存，移除 23 个模型的内置硬编码快照；同时修复健康检查空 500、禁用模型泄漏与未知模型被静态白名单误杀等问题。保持现有 API、配置与插件公共契约不变，无需强制迁移。

---

🧠 Zed 单跳协议重构

• 客户端协议直接转换到模型对应的上游原生协议，不再经过 Claude 中枢二次转换。
• 同构协议零转换直通；跨协议路径由 ConverterFactory 统一单跳回转。
• OpenAI Responses、Gemini 与 Anthropic 原生流式事件直接透传，保留 usage、cache token、工具调用与终止原因等原始语义。
• 非流式请求先聚合上游原生事件，再单跳转换为客户端协议，避免中间协议造成的信息丢失。

🗂️ 模型元数据运行时化

• 新增 ZedModelRegistry：每个 Zed 节点独立，按账号隔离模型元数据。
• 远端 cloud.zed.dev/models 成功后整体替换启用模型，并原子落盘到 configs/zed-model-metadata-cache.json。
• 冷启动同步读取最近一次成功快照；文件损坏、版本不匹配或账户切换时安全降级。
• 远端下架或 is_disabled 的模型不再出现在实例元数据与 /v1/models。
• 删除 23 条内置模型硬编码快照，协议路由改为稳定的模型族规则；新增同族模型无需改代码。

🛡️ 稳定性与兼容性修复

• Zed 健康检查：OpenAI Responses 通道实测 max_tokens 低于 16 会返回空 HTTP 500；Zed 健康检查改用最小可用预算 16，Kiro 保持 1，避免有额度节点被误判为不健康。
• 未知模型宽松降级：严格思考档位校验与 max_output_tokens 裁剪仅在权威元数据存在时生效；新增模型/档位不再被本地白名单误杀。
• 类型检查：修复 Zed 重构引入的 request-pipeline TypeScript 类型错误，npm run typecheck 恢复通过。
• Trae 清理：移除 solo_work_lite 节点选项与配置展示，思考模型过滤仅保留包含 extra_high 的通道；已有配置中的该选项会被忽略。

🧪 验证结果

项目	结果
npm run verify	50 suites / 626 tests 全绿
TypeScript / plugins / strict	全部通过
imports / cycles / runtime smoke	全部通过
any 棘轮 / 覆盖率门槛	通过
真实上游全量 E2E	18 个模型 × 11 项核心用例（198 项）全部通过
通用定向契约	6 项全部通过
provider 方言 canary	4 项全部通过
Zed 健康检查	3 个有额度节点 PASSED；3 个账号因 credits 耗尽返回 403（账号状态，非代码问题）

E2E 覆盖

• 18 个模型 × 11 项核心用例：Chat / Responses / Claude 三协议非流式与流式文本、单轮工具调用、多轮工具结果、连续同角色折叠、usage 不变量等。
• 6 项通用定向契约：强制 tool_choice、多模态图片、上游 4xx 细节、三下游协议流式工具生命周期、Responses→Gemini developer/text.format、仅 system/developer 本地 400。
• 4 项 provider 方言 canary：Zed Gemini 工具历史降级、非法 tool id 清洗、Gemini thinking 回退、max_tokens 截断不触发空响应重试。
• 部分模型仅出现文档允许的非阻塞 reasoning/thinking 提示，不影响确定性断言。

质量基线

• DynamicPayload references：1525。
• 总覆盖率：行 33.49% / 分支 33.91% / 函数 37.24%。
• 同步刷新 any 与覆盖率基线，使 CI 门槛与本版本真实状态一致。

📦 兼容性

• 运行要求保持不变：Node.js ^22.18.0 || >=23.6.0。
• 无 API、数据格式或插件公共契约变更。
• 无 provider 增删；Zed 模型能力改为运行时发现，首次启动会自动拉取并缓存。
• Trae solo_work_lite 节点选项已移除；已有配置无需手工删除，但该选项不再生效。

⬆️ 升级建议

• 源码：

  git fetch --tags
  git checkout v5.0.7
  npm install
  npm start

• Docker：发布工作流在检测到 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN 时会构建并推送 5.0.7 与 latest 镜像；未配置凭据时按现有流程跳过，可稍后手动运行“发布版本与构建 Docker 镜像”工作流。

• Zed 用户：首次启动会自动拉取最新模型元数据并写入本地缓存；如需清空缓存，删除 configs/zed-model-metadata-cache.json 后重启即可。

v5.0.6

AIClient-2-API 发布说明 (v5.0.6)

v5.0.6 是 v5.0.5 之后的稳定性与可维护性升级版本。

本轮完成 P0–P2 后续重构：强化质量门槛和核心链路回归保护，拆分 Zed、Kiro、Provider Pool 与 Pipeline 热点，并继续收敛协议动态类型。保持现有 API、配置及插件调用约定，无需配置迁移。

---

🛡️ 质量门槛与类型安全

• 修复 strict 门槛的假阴性：TypeScript 编译器失败、非 src/ 严格错误及失败的 baseline 更新都会可靠返回非零。
• 主源码与内置插件全面启用 noUnusedLocals，清理无用 import、局部变量、catch 绑定和死代码。
• 公共响应/流联合移除 any catch-all，请求扩展载荷改为 unknown；Claude → OpenAI usage 使用真实 DTO。
• AnyKeyword 收敛至 336；DynamicPayload 引用从 1539 降至 1499 并锁定新基线。

🧩 核心模块重构

• Zed：按 OpenAI、Google、Anthropic 通道拆分请求构建器。
• Kiro：提取请求归一化、工具上下文和 Claude 流内容块状态管理。
• Provider Pool：提取模型过滤/评分选点协作者与三级刷新调度器，保留重初始化后的状态访问契约。
• Pipeline：提取流重试上下文和协议终止事件处理，保持增量流、断开连接与重试收尾语义。
• Zed、Kiro 重构前后 golden 对比零差异；三组跨协议 golden stream 27 项全部通过。

🧪 验证结果

项目	结果
npm run verify	49 suites / 618 tests 全绿
TypeScript strict / noUnusedLocals	0 errors / 0 diagnostics
imports / cycles / any 棘轮 / 覆盖率门槛	全部通过
真实 Node 启动与 /health smoke	通过
clean checkout 覆盖率	行 32.88% / 分支 33.41% / 函数 36.20%
GitHub Actions（Node 22.x / 24.x）	通过

真实上游 E2E

• 18 个模型 × 11 项核心用例 = 198 项全部通过。
• 6 项通用定向契约全部通过：强制 tool_choice、多模态、4xx 错误细节、三下游流式工具生命周期、Responses→Gemini developer/text.format、仅 system/developer 本地 400。
• 4 项 provider 方言 canary 全部通过：Zed Gemini 工具历史、非法 tool id 清洗、Gemini thinking 回退、max_tokens 截断。
• 部分模型仅出现文档允许的非阻塞 reasoning/thinking 提示，不影响确定性断言。

🚀 性能基准

测试模型：openai-custom:glm-5.3；每种模式 20 个请求、并发 3、单请求超时 60 秒。

模式	成功率	总耗时	吞吐量	平均延迟	P50	P90	P95	P99
非流式	20/20（100%）	9388 ms	2.13 req/s	1378.65 ms	1291 ms	1664 ms	1720 ms	2130 ms
流式	20/20（100%）	12153 ms	1.65 req/s	1764.30 ms	1638 ms	2064 ms	2120 ms	2830 ms

延迟包含真实上游网络与模型生成时间，以上数据用于记录当前版本的实测表现，不作为与 v5.0.5 的严格对比基准。

📦 兼容性

• 运行要求保持不变：Node.js ^22.18.0 || >=23.6.0。
• 无 API、配置、数据格式或插件公共契约变更。
• 无 provider 增删；无需配置迁移。

⬆️ 升级建议

• 源码：

  git fetch --tags
  git checkout v5.0.6
  npm install
  npm start

• Docker：本次发布工作流未检测到 Docker Hub 凭据，镜像构建与推送已按现有流程跳过。需要 Docker 部署时，请先在仓库 secrets 中配置 DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN，再手动运行“发布版本与构建 Docker 镜像”工作流。

v5.0.5

AIClient-2-API 发布说明 (v5.0.5)

v5.0.5 是 v5.0.4 的 CI / 覆盖率工具链修复版本。

• 移除“本地存在用户插件时覆盖率高于 clean checkout”导致的 CI 门槛误判；
• 覆盖率基线改为在 clean checkout 生成，并分别在 Node.js 22 / 24 下验证；
• 无运行时、API、配置或数据格式变更，可直接从 v5.0.4 升级。

---

🐛 修复

覆盖率门槛在 CI 中误判

src/plugins-user/ 是 gitignored 的本地用户插件目录：

• 本地工作区存在该目录时，Jest 会把其中的文件计入覆盖率；
• CI clean checkout 中不存在该目录，覆盖率的分子/分母与本地不同；
• 结果是同一份代码在本地通过、在 CI 失败。

修复内容：

• Jest collectCoverageFrom 排除 src/plugins-user/**；
• check-coverage 解析 LCOV 时同步跳过该目录；
• 覆盖率基线改为在 clean checkout 生成；
• 新增回归测试，确保用户插件目录不会进入仓库基线。

🧪 验证结果

项目	结果
GitHub Actions CI（Node 22.x / 24.x）	通过
npm run verify	通过
单元测试	44 suites / 593 tests 全绿
TypeScript strict	0 errors
覆盖率门槛	通过
clean checkout 覆盖率	行 30.01% / 分支 31.21% / 函数 33.07%

📦 兼容性

• 无运行时、API、配置或数据格式变更；
• 无 provider 增删；
• 运行要求保持不变：Node.js ^22.18.0 || >=23.6.0。

🚀 升级建议

• 源码：

  git fetch --tags
  git checkout v5.0.5
  npm install
  npm start

• Docker：

  docker pull justlikemaki/aiclient-2-api:5.0.5

• 本次升级不涉及配置迁移；如无 CI/覆盖率需求，运行时代码与 v5.0.4 等价。

v5.0.4

AIClient-2-API 发布说明 (v5.0.4)

v5.0.4 是 v5.0.3 的修复版本，重点修复插件方法 receiver 丢失与覆盖率统计口径错误。

• 插件 init / destroy / authenticate / middleware / hooks 恢复正确的 this 绑定；
• LCOV FNDA 解析 off-by-one 修复，函数覆盖率由 11.39% 校正为 32.65%；
• npm run verify 现在会执行覆盖率门槛，并新增失败路径回归测试。

---

🐛 修复

1. 插件方法 receiver 丢失（兼容性修复）

上一轮重构为了避免 TypeScript 的 “possibly undefined” 告警，把插件方法提取到局部变量后直接调用，导致方法内的 this 不再是插件对象。依赖实例状态的第三方插件可能出现静默失效。

现已改为：

init.call(plugin, config)
destroy.call(plugin)
authenticate.call(plugin, req, res, url, config)
middleware.call(plugin, req, res, url, config)
hook.call(hooks, ...args)

并新增 5 个回归测试，覆盖初始化、销毁、启停、认证、中间件和 hooks。

2. 覆盖率统计 off-by-one（度量修复）

LCOV 的 FNDA: 前缀长度为 5，旧实现从 slice(6) 开始解析，会丢掉 hit count 的第一位：

• FNDA:1,... 被解析成空值 / 0；
• FNDA:10,... 被解析成 0；
• 导致函数覆盖率被系统性低估。

修复后函数覆盖率由 11.39% 校正为 32.65%（293 → 840 covered）。这是统计口径修复，不是测试覆盖率突然提升。

🧪 回归测试

• 新增 FNDA 解析测试：覆盖 0、1、9、10、11、100 等 hit count。
• 新增覆盖率门槛失败路径测试：基线高于实际覆盖率时，脚本必须以非零码退出。
• 新增插件 receiver 测试：确保所有被提取的方法仍以插件对象作为 this。

✅ 验证结果

项目	结果
npm run verify	通过
TypeScript strict	0 errors
any / DynamicPayload 棘轮	OK（340 AST nodes；1 definition / 1539 refs）
单元测试	44 suites / 592 tests 全绿
导入检查 / 循环依赖	136 文件通过 / 0 cycles
运行时 smoke	OK
覆盖率	行 29.84% / 分支 31.09% / 函数 32.65%
全量 E2E	20 个模型，26/26 通过
定向回归 E2E	openai-custom:glm-5.3，11 项核心 + 2 项定向通过

📦 兼容性

• 无 API、配置或数据格式变更；
• 无 provider 增删；
• 运行要求：Node.js ^22.18.0 || >=23.6.0（服务端直接运行 .ts，依赖原生类型擦除）。

🚀 升级建议

• 源码：

  git fetch --tags
  git checkout v5.0.4
  npm install
  npm start

• Docker：

  docker pull justlikemaki/aiclient-2-api:5.0.4

• 升级前请确认 node -v 满足要求，其余无需迁移配置。

v5.0.3

AIClient-2-API 发布说明 (v5.0.3)

v5.0.3 是 v5.0.2 的修复版本，重点修复两个运行时回归，并完成类型债治理的收尾。

• 非号池部署（providerPools 为空）下内容生成请求 500 的问题已修复；
• 5 个模块中自递归 getErrorMessage 导致的 RangeError 已修复；
• any / DynamicPayload 棘轮扩展，第三方依赖类型补齐。

---

🐛 修复

1. 非号池部署请求 500（高优先级）

v5.0.2 的 request-handler 把延迟解析的 apiService 从 undefined 改成了 {}，导致非号池部署跳过 service 解析，最终返回：

HTTP 500: service.generateContent is not a function

修复后恢复传入 null，并在解析后增加空 service 守卫。使用 openai-custom / openaiResponses-custom / claude-custom 的单 Key 部署可直接升级。

2. 自递归 getErrorMessage（高优先级）

request-handler、api-manager、service-manager、plugin-installer、provider-api 中的 5 个 helper 在收到 Error 时会无限递归，抛出：

RangeError: Maximum call stack size exceeded

影响插件市场离线 fallback、provider 健康检查、图片生成等错误路径。现已全部改为返回 error.message。

🧪 回归测试

• 真实 standalone server + 空号池 + 本地假 OpenAI 上游，验证 /v1/chat/completions 返回 200（修复前为 500）。
• 插件市场网络失败时正确回退本地缓存（修复前为 RangeError）。
• 全源码扫描，禁止 getErrorMessage 自递归。

🧹 类型债治理

• 冻结 DynamicPayload 增量：通过 TypeScript AST 统计定义数与引用数并纳入棘轮基线（当前 51 definitions / 1567 references），新增别名或引用会使 CI 失败。
• 补齐第三方依赖类型：busboy 使用 @types/busboy；adm-zip 0.5.x 与 multer 使用本地最小声明（types/adm-zip.d.ts、types/multer.d.ts），移除 types/vendor-modules.d.ts 的整模块 any 声明。
• 按需收敛：在触碰的 event-broadcast / plugin-api 中移除 DynamicPayload，改用 multer.File、Record<string, unknown> 与显式运行时守卫。
• 指标现状：: any / as any 234 / 6；AST AnyKeyword 393（src=331 / types=62），其中 security-hardening.ts 239。

✅ 验证结果

项目	结果
TypeScript strict	0 errors
@ts-nocheck	0 文件 / 0 行
any / DynamicPayload 棘轮	OK（234/6/393；51/1567）
单元测试	32 suites / 497 tests 全绿
导入检查	128 文件通过
运行时 smoke	OK
全量 e2e	20 个模型，26/26 通过

📦 兼容性

• 无 API、配置或数据格式变更；
• 无 provider 增删；
• 运行要求：Node.js >= 22.18.0（服务端直接运行 .ts，依赖原生类型擦除；Node 20 及更早版本无法启动）。

🚀 升级建议

• 源码：

  git fetch --tags
  git checkout v5.0.3
  npm install
  npm start

• Docker：

  docker pull justlikemaki/aiclient-2-api:5.0.3

• 升级前请确认 node -v >= 22.18.0，其余无需迁移配置。

v5.0.2

AIClient-2-API 发布说明 (v5.0.2)

v5.0.2 是 TypeScript 严格化（strict ratchet）重构的收尾版本。

本次重构不做功能变更，重点是把长期存在的隐式协议边界收敛为真实 DTO / 协议类型：
全仓显式 any 从 2279 处降至 234 处（-90%），且仅剩的 234 处全部集中在
security-hardening.ts 的 monkey-patch wrapper 边界，作为受控例外保留。

---

✨ 重构内容

TypeScript 严格化

• strict 模式错误：0
• @ts-nocheck：0 文件 / 0 行
• 显式 any：2279 → 234 annotations，135 → 6 assertions
• 新增 any 棘轮基线（scripts/any-baseline.json），任何文件新增 any 都会导致 CI 失败

Provider 层

• antigravity-core、zed-core、codex-core、claude-kiro、trae-core、openai-core 全部使用真实请求/响应结构与错误边界类型；
• model-capability 能力层、adapter 注册表、provider registry / capabilities / strategies / channel helpers 全部类型化；
• 流式响应、SSE 事件、模型发现、凭据刷新与错误重试路径保持原有运行时行为。

转换器层

• ClaudeConverter、OpenAIConverter、OpenAIResponsesConverter、CodexConverter 的公共入口与内部 payload 全部类型化；
• GeminiConverter 与各 provider strategy 同步收敛；
• 空响应、终止帧、tool_calls 聚合等边界逻辑未做行为变更。

Handlers 与 UI API

• request-pipeline 引入统一的 PipelineError 边界，流式/非流式重试逻辑类型化；
• request-handler、usage-api、oauth-api、update-api、custom-models-api、upload-config-api、config-api、event-broadcast 等 UI API handler 全部使用 IncomingMessage / ServerResponse / DynamicPayload 类型；
• SSE 批量导入、WebSocket 广播、配置扫描与缓存访问路径保持兼容。

Core 与 Services

• config-manager、plugin-manager、plugin-security、master-core、api-manager、service-manager、usage-service、file-lock 等模块完成类型收敛；
• security-hardening.ts 保持受控例外，仅保留 wrapper 所需的动态签名。

---

✅ 验证结果

项目	结果
TypeScript strict	0 errors
@ts-nocheck	0 文件 / 0 行
显式 any	234 annotations / 6 assertions（全部为受控例外）
单元测试	30 suites / 494 tests 全绿
导入检查	128 文件通过
运行时冒烟	OK

---

📦 兼容性

• 无 API、配置或数据格式变更；
• 无 provider 增删，行为与 v5.0.1 保持一致；
• security-hardening.ts 的 wrapper 仍是唯一保留显式 any 的模块，属于有意设计。

🚀 升级建议

• 直接拉取 v5.0.2 镜像或代码即可，无需迁移配置；
• Docker：

  docker pull <dockerhub-username>/aiclient-2-api:5.0.2

• 源码：

  git fetch --tags
  git checkout v5.0.2
  npm install
  npm start

---

📚 相关文档

• 配置分层与优先级
• 跨协议架构
• Provider 适配指南
• E2E 测试说明

v5.0.1

AIClient-2-API 发布说明 (v5.0.1)

v5.0.1 是一个修复版本，解决 v5.0.0 中 WebUI #upload-config 页面空白的问题。

后端配置扫描与 /api/upload-configs 数据本身正常；问题出在前端 provider 注册表合并时遗漏了 3 个 import，导致渲染配置列表时触发 ReferenceError。

---

🐛 修复内容

WebUI #upload-config 空白

• upload-config-manager.js 补回 detectProviderFromPath 导入；
• file-upload.js 补回 getProviderUploadDir 导入；
• modal.js 补回 isOAuthProvider 导入。

修复后：

• 配置列表可正常渲染；
• provider 类型过滤、上传目录识别与 OAuth provider 判断恢复正常；
• 其他 provider 与协议行为不变。

---

✅ 验证结果

项目	结果
单元测试	27 suites / 486 tests
TypeScript checkJs	0 errors
静态语法检查	27 / 27

---

📦 升级建议

• 如果你已使用 v5.0.0 且 WebUI 配置管理页面为空，建议直接升级到 v5.0.1。
• 本次为纯修复版本，无配置或 API 变更。
• 使用 npm 安装依赖：

  npm install

---

📚 相关文档

• 配置分层与优先级
• 跨协议架构
• Provider 适配指南
• E2E 测试说明

v5.0.0

AIClient-2-API 发布说明 (v5.0.0)

v5.0.0 是一次以“收敛与减负”为主的破坏性版本：彻底移除 grok-cli-oauth provider，统一前后端 provider 元数据，启用 src 类型检查与 CI，并重构 E2E 测试体系。

除 Grok CLI 外，其他 provider（Antigravity、Kiro、Codex、OpenAI、Claude、Zed、Trae）的接入方式与协议行为保持不变。

---

⚠️ 破坏性变更

1. 移除 grok-cli-oauth provider

• 删除 Grok CLI core、OAuth、适配器注册、模型清单、号池、用量查询、OAuth/批量导入路由以及前端入口。
• 删除前端 provider 卡片、授权弹窗、路由示例、i18n 与相关配置示例。
• MODEL_PROVIDER.GROK_CLI 常量与 grok-cli-oauth 注册项不再存在。

升级前请处理：

• 删除 configs/grok-cli/ 下的凭据文件；
• 从 configs/provider_pools.json 删除 grok-cli-oauth 节点；
• 清理 model-capability-cache.json、usage-cache.json、model-usage-stats.json 中的 Grok CLI 缓存/统计（可选）。

这些属于 gitignored 运行时数据，本次发布不会自动删除。

2. 工程与测试结构调整

• npm run test:e2e 现在只运行核心矩阵 + 6 项通用定向契约；
• 原 4 项 provider 方言用例改为 npm run test:e2e:providers 显式运行；
• 移除依赖模型采样/质量的 E2E（GPT 采样、DeepSeek consistency、CoT 回放、oneOf、重复多 system 用例），对应逻辑由确定性单测覆盖。

---

🌟 核心改进

1. Provider 元数据单一来源

• 新增 static/app/provider-registry.js：前端 provider 名称、图标、默认模型、目录、OAuth 能力与上传路径统一维护。
• 新增 src/providers/provider-registry.js：后端 provider 类型、协议、健康检查模型、凭据字段、静态模型与动态能力 TTL 统一维护。
• provider-models、model-capability、provider-pool-manager、provider-utils、protocol、service-manager、config-scanner 均改为从注册表派生。
• 新增 provider 或移除 provider 时，不再需要逐文件修改十几份映射表。

2. 类型检查与 CI

• tsconfig.json 纳入 src/**/*.js，开启 checkJs。
• 新增 npm run typecheck，并在 GitHub Actions 中执行 typecheck + 单测。
• 类型检查发现并修复了多个实际缺陷：
  • 生图监控钩子的 prompt 越界引用；
  • api-potluck 缺少 mkdirSync 导入；
  • update-api 的 arrayBuffer() 返回类型错误；
  • header 可能为数组导致 startsWith 崩溃；
  • config-scanner 漏导入注册表函数。
• 11 个大型动态文件暂时使用 @ts-nocheck，后续可逐文件补齐 JSDoc 后移除。

3. P0 工程精简

• 统一使用 npm，删除 pnpm-lock.yaml 与安装脚本中的 pnpm 分支；
• Docker 构建优先 npm ci；
• 移除未使用依赖 ws、supertest、jest-environment-node；
• 删除未引用 favicon0.ico 与一次性迁移脚本；
• 过期评审/设计文档归档到 docs/archive/。

4. 测试体系精简

• 4 个按版本分桶的回归测试合并为 2 个领域文件，126 个历史用例全部保留；
• 通用 E2E 定向契约压缩为 6 项，provider 方言 canary 独立为 4 项 opt-in；
• 定向用例不再硬编码模型，按 /auto/v1/models 的 provider 前缀动态选择；模型下线时自动 skip；
• 动态 provider 静态模型清单压缩为少量冷启动 baseline。

5. 配置文档

• 新增 docs/CONFIG_PRECEDENCE.md，明确 env/config/default 读取顺序、provider 能力优先级、模型列表与 fallback 优先级，并标注历史兼容字段。

---

✅ 验收结果

项目	结果
单元测试	27 suites / 486 tests
TypeScript checkJs	0 errors
静态语法检查	27 / 27
默认 E2E（19 模型）	25 / 25
Provider canary	4 / 4
核心矩阵	19 个模型 × 11 项

E2E 仍有少量非阻塞 [E2E warnings]（部分模型/通道不返回 reasoning block），不影响网关正确性断言。

---

📦 升级建议

1. 升级到 v5.0.0 前，先移除所有 grok-cli-oauth 配置与凭据。
2. 使用 npm 安装依赖：

   npm install

3. 如之前使用 pnpm lockfile，请改用 package-lock.json。
4. 其他 provider 无需修改配置。

---

📚 相关文档

• 配置分层与优先级
• 跨协议架构
• Provider 适配指南
• E2E 测试说明

v4.1.9

AIClient-2-API 发布说明 (v4.1.9)

v4.1.9 是跨协议转译语义、流内错误收尾与 Schema 保真的稳定性版本，无破坏性 API/协议变更。

本版本汇总 v4.1.8 与 v4.1.9 的修复：补齐 Responses → Gemini 的 system/结构化输出/多模态工具回传，收口同协议与跨协议流内错误，增强 Schema Polyfill，并完成 19 个真实模型的最终 E2E 验收。

---

🌟 核心变更

1. Responses → Gemini 语义补齐

• input 内的 system / developer 消息不再降级为 user，统一并入 systemInstruction。
• text.format 的 json_object / json_schema 映射为 Gemini responseMimeType / responseSchema，并复用 Schema Polyfill。
• 多模态 function_call_output 数组归一化为 { content }，图片/文件拆为同轮 inlineData，避免把数组直接塞进 Gemini FunctionResponse.response。
• 只有 instructions / system / developer 而没有 user/assistant turn 的请求本地返回 400，不再把必然被拒绝的空 contents 发往上游。

2. 流内错误终态与错误体语义

• 识别 response.failed、event: error、data.error，包括 choices: [] / candidates: [] 形态。
• 转换器无法表达错误帧时返回 502，不再静默返回空 200 流。
• 非流式 HTTP 200 错误体统一转为 502，不再伪装成合法截断。
• 错误帧不再提前污染 hasMessageStop，重试成功后仍能正确补发终止帧。

3. Schema Polyfill 增强

• 补齐 allOf 的 type/enum/items 提升，scalar allOf 不再生成空 properties。
• 支持可空 oneOf、patternProperties、additionalProperties、not、dependentRequired、dependentSchemas、if/then/else。
• 摘要保留子 Schema 的 description，min / maxLength 等内层约束可传递到父摘要。
• 阶段 2 裁剪只统计清洗后可达节点，按真实描述差值回缩；allOf / oneOf / $ref 登记父节点，避免修改不可达分支导致虚减。

4. Antigravity 与 GPT-6 预适配

• Antigravity 过滤 oss 与 -low 模型，模型列表动态刷新恢复正常。
• User-Agent 更新为 CLI 标识。
• Chat → Antigravity 的 thinking gating 覆盖 gpt-*、-thinking、-high、-medium 与 Claude 5.5，GPT-6 预适配补齐。

5. 测试与文档

• 单元测试：29 suites / 489 tests 全绿。
• 19 模型全量 E2E：35 / 35 通过，19/19 模型 11/11，16/16 定向用例通过；核心矩阵 209/209。
• 新增 Responses→Gemini developer/text.format 与 system-only 400 定向用例。
• 文档收敛为单一 19 模型复评入口，删除过期的 27 模型 review。

---

✅ 验收结果

项目	结果
单元测试	29 suites / 489 tests
E2E Jest 用例	35 / 35
19 模型核心矩阵	19 / 19 模型 11/11
核心子用例	209 / 209
定向 E2E	16 / 16
收尾异常	0

E2E 运行期间上游存在长尾与空响应波动（Zed Gemini 单模型约 230s；4 个 unary 空响应请求、1 个 stream 空响应请求），均由网关重试或 E2E 透明重试恢复，最终无转译断言失败。

---

⚠️ 已知限制

• 显式 cache_control 仍不可跨协议保留，仅做 cached_tokens → cache_read_input_tokens 计费回填。
• Anthropic 历史 thinking 需要真实签名、官方 Responses reasoning 需要 encrypted_content，跨协议默认跳过；Gemini 目标可通过 CONVERT_REPLAY_COT_SUMMARY=true 回放摘要。
• Gemini 原生签名由 vsig1 虚拟签名替代；严格校验签名的客户端可能不接受非标准格式。
• Schema 中不支持的关键字仍以 description 约束表达，而非结构等价。
• Reasoning 可用性由 Provider/模型/采样决定；Zed Claude/Gemini 与 Antigravity Claude 默认不暴露 thought 文本。

---

📦 升级建议

• 建议直接升级到 v4.1.9；无破坏性配置/API 变更。
• 使用 Responses → Gemini 结构化输出时，请确认客户端传入标准 text.format。
• 如依赖历史 CoT 回放，请按目标 Provider 的签名能力选择是否开启 CONVERT_REPLAY_COT_SUMMARY。

---

📚 相关文档

• 跨协议转译复评（19 模型全量 E2E · 2026-10-23）
• 跨协议架构
• 流式转换设计
• Provider 适配指南

v4.1.7

AIClient-2-API 发布说明 (v4.1.7)

v4.1.7 是跨协议转译重试与流式收尾的稳定性修复版本，无破坏性 API/协议变更。

本版本修复了空响应重试路径上的两个 P1 缺陷、两个 P2 契约问题，并完成 27 个真实模型的最终 E2E 验收。

---

🌟 核心变更

1. 修复 Responses 下游兜底收尾卡死（P1）

• streamRequestId 声明提升到 try 外，修复 finally 兜底分支中的 ReferenceError。
• 兜底收尾失败时强制 res.end()，避免客户端永久等待读超时。
• 新增跨重试帧共享的 streamState.hasMessageStop：内层重试帧已经发送 message_stop / response.completed 时，外层帧不再重复补发终止事件。

效果：此前 openai-custom:glm-5.3 在空响应重试后可能卡住约 180s；修复后该用例耗时从 195.2s 降至 15.4s。

2. 修复空响应/凭证切换重试的流状态泄漏（P1）

• BaseConverter 新增 resetStreamState() 契约。
• 各 Converter 只清理流式状态，保留请求级工具名映射与 custom tool 登记。
• pipeline 在每次尝试开始、空响应重试、凭证切换重试前清理上游 Converter 的流式状态。
• 重试上下文固定 requestId 与共享 streamState，保证内层/外层帧使用同一份会话状态。

效果：重试流不再缺少 message_start / response.created 等生命周期首帧。

3. 统一终端空内容截断识别（P2）

新增 extractTerminalFinishReason() / isTerminalEmptyFinishReason()，覆盖：

协议	终态示例
OpenAI Chat	length、content_filter
Anthropic Messages	max_tokens、refusal
OpenAI Responses / Codex	max_output_tokens、incomplete
Gemini	MAX_TOKENS、SAFETY 等安全终态

合法截断不再被当作空响应重试最多 5 次并最终 502。

4. 修复 Responses → Gemini 工具 ID 配对（P2）

functionCall、functionResponse、callIdToName 统一使用 item.call_id || item.id，保证多轮工具历史中的调用与结果使用同一个 ID。

5. 文档与测试清理

• 新增 tests/v4-1-6-regressions.test.js，覆盖 9 个 P1/P2 回归场景。
• 清理过时的跨协议评估/优化文档；当前评估入口收敛为 docs/CROSS_PROTOCOL_REVIEW_V4_1_7.md。
• 清理 E2E 测试中未使用的 addQuotaFailure 别名。

---

✅ 验证结果

单元测试

Test Suites: 29 passed, 29 total
Tests:       463 passed, 463 total

最终 27 模型 E2E

• 模型来源：GET /auto/v1/models 动态发现，共 27 个模型
• 参数：reasoning_effort=high（Claude 使用 thinking.budget_tokens=20000）
• 结果：39 / 39 通过；27/27 模型核心用例 11/11；12/12 定向用例通过

指标	结果
E2E Jest 用例	39 / 39
27 模型核心矩阵	27 / 27 模型 11/11
定向 E2E	12 / 12
streamRequestId is not defined	0 次
openai-custom:glm-5.3 耗时	15.4s（修复前 195.2s）
核心矩阵总耗时	991.6s（修复前 1,215.6s）

---

🔧 升级说明

• 本版本无破坏性 API 变更，客户端无需修改请求格式。
• 升级后请重启网关进程，使新的重试/收尾逻辑生效。
• Docker 镜像标签：4.1.7、latest。

---

📚 相关文档

• 跨协议转译复评（v4.1.6 基线 + v4.1.7 修复验收）
• 跨协议架构
• 流式转换设计
• Provider 适配指南