{"_id":"@aihubmix/ai-vendor-specs","_rev":"4-d038240204817e050087160563add084","name":"@aihubmix/ai-vendor-specs","dist-tags":{"latest":"1.20260615.0"},"versions":{"0.1.0":{"name":"@aihubmix/ai-vendor-specs","version":"0.1.0","keywords":["ai","openai","anthropic","claude","gemini","cohere","vertex","azure","bedrock","xai","grok","openapi","openapi-3","discovery","api-specs","llm","ai-gateway"],"license":"MIT","_id":"@aihubmix/ai-vendor-specs@0.1.0","maintainers":[{"name":"chenxue","email":"450907240@qq.com"}],"homepage":"https://github.com/AIhubmix/ai-vendor-specs#readme","bugs":{"url":"https://github.com/AIhubmix/ai-vendor-specs/issues"},"dist":{"shasum":"2c06a31ef7d6fc20f07cfd55051eb9e0eb2944cb","tarball":"https://registry.npmjs.org/@aihubmix/ai-vendor-specs/-/ai-vendor-specs-0.1.0.tgz","fileCount":33,"integrity":"sha512-32njD7dXdZCHgUIhZm3i5VTg/g9NlfWsewSmE5VJaRCt9TIyZfBCVgVtcjHVa85npt0cfU7AHZRor7OHBFjjZQ==","signatures":[{"sig":"MEQCIHkxl1iL6oCwR9fKPmIs3JDh8Ngo6pacosDs8o6a9IhcAiAJzxwD8OwpBRuBkxLFRtMLG2uvfbrsrwBUNJubWqbufg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aihubmix%2fai-vendor-specs@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":10173402},"main":"scripts/overlay/apply.js","engines":{"node":">=18"},"exports":{".":"./scripts/overlay/apply.js","./notify":"./scripts/notify.js","./manifest":"./manifest.json","./upstream/*":"./upstream/*","./package.json":"./package.json","./manifest.json":"./manifest.json","./overlay/apply":"./scripts/overlay/apply.js"},"gitHead":"f91e96e21fb333ae2c9f3322f0ade2e536cac6d0","scripts":{"sync":"bash scripts/sync-all.sh","drift":"node scripts/check-drift.js","resolve":"node scripts/overlay/apply.js","manifest":"node scripts/build-manifest.js","validate":"bash scripts/validate-all.sh","build-site":"node scripts/build-site.js"},"_npmUser":{"name":"chenxue","email":"450907240@qq.com"},"repository":{"url":"git+https://github.com/AIhubmix/ai-vendor-specs.git","type":"git"},"_npmVersion":"10.9.8","description":"Curated official OpenAPI / Discovery specifications for major AI providers, with overlay support for OpenAI-compatible vendors and daily upstream sync with drift detection.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"js-yaml":"^4.1.0"},"_hasShrinkwrap":false,"devDependencies":{"@apidevtools/swagger-cli":"^4.0.4"},"_npmOperationalInternal":{"tmp":"tmp/ai-vendor-specs_0.1.0_1779635951770_0.6960269377055426","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aihubmix/ai-vendor-specs","version":"0.1.1","keywords":["ai","openai","anthropic","claude","gemini","cohere","vertex","azure","bedrock","xai","grok","openapi","openapi-3","discovery","api-specs","llm","ai-gateway"],"license":"MIT","_id":"@aihubmix/ai-vendor-specs@0.1.1","maintainers":[{"name":"chenxue","email":"450907240@qq.com"}],"homepage":"https://github.com/AIhubmix/ai-vendor-specs#readme","bugs":{"url":"https://github.com/AIhubmix/ai-vendor-specs/issues"},"dist":{"shasum":"e31fb66767c770127236245125a83bdb68a7ae19","tarball":"https://registry.npmjs.org/@aihubmix/ai-vendor-specs/-/ai-vendor-specs-0.1.1.tgz","fileCount":33,"integrity":"sha512-lZJ1MYSU4gw0Yp0//XFoBsQ5zqDMDeP13k9oUkXQXIzE7fInCRzIGPjTGZEHULuwNrt2AqnxJXBp6+PM9lV62A==","signatures":[{"sig":"MEQCIEkXULt7JfmF3wC6A6/cwHY5EGWnTKf13x1szCLTxObnAiBRwO6wKw188lmLxka4bkyQDqLeQZUTlkHORnmKvpMeKA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aihubmix%2fai-vendor-specs@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":10201556},"main":"scripts/overlay/apply.js","engines":{"node":">=18"},"exports":{".":"./scripts/overlay/apply.js","./notify":"./scripts/notify.js","./manifest":"./manifest.json","./upstream/*":"./upstream/*","./package.json":"./package.json","./manifest.json":"./manifest.json","./overlay/apply":"./scripts/overlay/apply.js"},"gitHead":"00ab67b55d97577f41860e178d5454dfa5b9e5db","scripts":{"sync":"bash scripts/sync-all.sh","drift":"node scripts/check-drift.js","resolve":"node scripts/overlay/apply.js","manifest":"node scripts/build-manifest.js","validate":"bash scripts/validate-all.sh","build-site":"node scripts/build-site.js"},"_npmUser":{"name":"chenxue","email":"450907240@qq.com"},"repository":{"url":"git+https://github.com/AIhubmix/ai-vendor-specs.git","type":"git"},"_npmVersion":"10.9.8","description":"Curated official OpenAPI / Discovery specifications for major AI providers, with overlay support for OpenAI-compatible vendors and daily upstream sync with drift detection.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"js-yaml":"^4.1.0"},"_hasShrinkwrap":false,"devDependencies":{"@apidevtools/swagger-cli":"^4.0.4"},"_npmOperationalInternal":{"tmp":"tmp/ai-vendor-specs_0.1.1_1780301486901_0.33900081593733233","host":"s3://npm-registry-packages-npm-production"}},"1.20260603.0":{"name":"@aihubmix/ai-vendor-specs","version":"1.20260603.0","keywords":["ai","openai","anthropic","claude","gemini","cohere","vertex","azure","bedrock","xai","grok","openapi","openapi-3","discovery","api-specs","llm","ai-gateway"],"license":"MIT","_id":"@aihubmix/ai-vendor-specs@1.20260603.0","maintainers":[{"name":"chenxue","email":"450907240@qq.com"}],"homepage":"https://github.com/AIhubmix/ai-vendor-specs#readme","bugs":{"url":"https://github.com/AIhubmix/ai-vendor-specs/issues"},"dist":{"shasum":"28a90392050a29b21e4e2e8cfbf20b849551223c","tarball":"https://registry.npmjs.org/@aihubmix/ai-vendor-specs/-/ai-vendor-specs-1.20260603.0.tgz","fileCount":77,"integrity":"sha512-eSok8aQ4NzbZtLnbW85s3yKBeOUnWh5iY1iQcg66qWO2KVYjJMD4saPpOzDs0XC0y6v2BvgyjybPExpibzY4uw==","signatures":[{"sig":"MEUCIEpExduOG/tMzzjLVtrf3rV7aBIIunbNY7mT6A4yN3tVAiEA3MF+S3pGURBzbmIeike/sJmYIsReBiWSftot6ifXUkw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aihubmix%2fai-vendor-specs@1.20260603.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":12014728},"main":"scripts/overlay/apply.js","engines":{"node":">=18"},"exports":{".":"./scripts/overlay/apply.js","./notify":"./scripts/notify.js","./manifest":"./manifest.json","./upstream/*":"./upstream/*","./package.json":"./package.json","./manifest.json":"./manifest.json","./overlay/apply":"./scripts/overlay/apply.js"},"gitHead":"785d943400eee432beedf66268ea03ae946f2ee6","scripts":{"sync":"bash scripts/sync-all.sh","drift":"node scripts/check-drift.js","report":"node scripts/report-changes.js","resolve":"node scripts/overlay/apply.js","manifest":"node scripts/build-manifest.js","validate":"bash scripts/validate-all.sh","build-site":"node scripts/build-site.js","detect-release":"node scripts/detect-release.js"},"_npmUser":{"name":"chenxue","email":"450907240@qq.com"},"repository":{"url":"git+https://github.com/AIhubmix/ai-vendor-specs.git","type":"git"},"_npmVersion":"10.9.8","description":"Curated official OpenAPI / Discovery specifications for major AI providers, with overlay support for OpenAI-compatible vendors and daily upstream sync with drift detection.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"js-yaml":"^4.1.0"},"_hasShrinkwrap":false,"devDependencies":{"@apidevtools/swagger-cli":"^4.0.4"},"_npmOperationalInternal":{"tmp":"tmp/ai-vendor-specs_1.20260603.0_1780475461138_0.5426258710472356","host":"s3://npm-registry-packages-npm-production"}},"1.20260615.0":{"name":"@aihubmix/ai-vendor-specs","version":"1.20260615.0","description":"Curated official OpenAPI / Discovery specifications for major AI providers, with overlay support for OpenAI-compatible vendors and daily upstream sync with drift detection.","main":"scripts/overlay/apply.js","exports":{".":"./scripts/overlay/apply.js","./manifest":"./manifest.json","./manifest.json":"./manifest.json","./overlay/apply":"./scripts/overlay/apply.js","./notify":"./scripts/notify.js","./upstream/*":"./upstream/*","./package.json":"./package.json"},"scripts":{"sync":"bash scripts/sync-all.sh","validate":"bash scripts/validate-all.sh","manifest":"node scripts/build-manifest.js","drift":"node scripts/check-drift.js","detect-release":"node scripts/detect-release.js","resolve":"node scripts/overlay/apply.js","build-site":"node scripts/build-site.js","report":"node scripts/report-changes.js"},"keywords":["ai","openai","anthropic","claude","gemini","cohere","vertex","azure","bedrock","xai","grok","openapi","openapi-3","discovery","api-specs","llm","ai-gateway"],"repository":{"type":"git","url":"git+https://github.com/AIhubmix/ai-vendor-specs.git"},"homepage":"https://github.com/AIhubmix/ai-vendor-specs#readme","bugs":{"url":"https://github.com/AIhubmix/ai-vendor-specs/issues"},"license":"MIT","engines":{"node":">=18"},"dependencies":{"js-yaml":"^4.1.0"},"devDependencies":{"@apidevtools/swagger-cli":"^4.0.4"},"_id":"@aihubmix/ai-vendor-specs@1.20260615.0","gitHead":"29d9a39c576339a7930dc621e4e7ccaef3d5dffb","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-ttmLO9LWTebt/bR5ZlNxuEWfRkuOqUSAhVJC/q5PHJmQ1K9rO+xjQPrEm4G3yPWGBDkkIkPcGsDXjGkvVB7qBQ==","shasum":"82c1492727f32aabe788ae6c264bf959c73e8db3","tarball":"https://registry.npmjs.org/@aihubmix/ai-vendor-specs/-/ai-vendor-specs-1.20260615.0.tgz","fileCount":77,"unpackedSize":12240376,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID4kgnGYfj6VYaNYuCPr/J0WMmEW8eNVmbuGo6sAL2E5AiBLb55dRvGSdZUbS1GLnivGZv4GnxKwwA8/614zzJ+SrQ=="}]},"_npmUser":{"name":"chenxue","email":"450907240@qq.com"},"directories":{},"maintainers":[{"name":"chenxue","email":"450907240@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-vendor-specs_1.20260615.0_1781603871942_0.21862836055348356"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-24T15:19:11.620Z","modified":"2026-06-16T09:57:52.287Z","0.1.0":"2026-05-24T15:19:11.982Z","0.1.1":"2026-06-01T08:11:27.087Z","1.20260603.0":"2026-06-03T08:31:01.354Z","1.20260615.0":"2026-06-16T09:57:52.139Z"},"bugs":{"url":"https://github.com/AIhubmix/ai-vendor-specs/issues"},"license":"MIT","homepage":"https://github.com/AIhubmix/ai-vendor-specs#readme","keywords":["ai","openai","anthropic","claude","gemini","cohere","vertex","azure","bedrock","xai","grok","openapi","openapi-3","discovery","api-specs","llm","ai-gateway"],"repository":{"type":"git","url":"git+https://github.com/AIhubmix/ai-vendor-specs.git"},"description":"Curated official OpenAPI / Discovery specifications for major AI providers, with overlay support for OpenAI-compatible vendors and daily upstream sync with drift detection.","maintainers":[{"name":"chenxue","email":"450907240@qq.com"}],"readme":"# ai-vendor-specs\n\n> 主流 AI 厂商官方 OpenAPI / Discovery 规范的汇集库,每日自动同步上游 + 漂移检测。\n\n**语言**: [English](./README.md) · 简体中文 · [日本語](./README.ja.md)\n\n**🌐 在线浏览 spec**: [aihubmix.github.io/ai-vendor-specs](https://aihubmix.github.io/ai-vendor-specs/) —— 每个上游 spec 都用 Redoc 渲染,带 protocol 筛选 tab。\n\n`ai-vendor-specs` 把各主流 AI 厂商(OpenAI、Anthropic、Cohere、Google、Microsoft,以及一众 OpenAI 兼容厂商)发布的官方 API 规范统一收纳到一处,以一致的数据结构供下游消费:SDK 生成器、网关、文档站、契约测试、IDE 智能提示、AI agent 工具注册表等。\n\n对于没有机器可读 spec 的变体(如 AWS Bedrock 上的 Claude、Groq 等 OpenAI 兼容厂商),用紧凑的 overlay 文件声明差异,在 resolve 阶段合成完整 spec。仓库本身**不存储任何派生产物**,每一个字节都可追溯到上游官方来源。\n\n---\n\n## 当前覆盖\n\n| 协议 | provider | 类型 | 上游来源 |\n|---|---|---|---|\n| openai | official | spec | [openai/openai-openapi](https://github.com/openai/openai-openapi)(Stainless) |\n| openai | azure | spec | [Azure/azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable) · 钉版 `2024-10-21` |\n| openai | azure-preview | spec | [Azure/azure-rest-api-specs preview](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview) · 钉版 `2025-04-01-preview` |\n| openai | deepseek | overlay | [api-docs.deepseek.com](https://api-docs.deepseek.com/) |\n| openai | groq | overlay | [console.groq.com/docs](https://console.groq.com/docs/api-reference) |\n| openai | together | overlay | [docs.together.ai](https://docs.together.ai/reference/chat-completions) |\n| openai | xai | overlay | [docs.x.ai](https://docs.x.ai/docs/api-reference) |\n| anthropic | official | spec | [anthropics/anthropic-sdk-python `.stats.yml`](https://github.com/anthropics/anthropic-sdk-python/blob/main/.stats.yml) → Stainless |\n| anthropic | bedrock | overlay | [AWS Bedrock InvokeModel 文档](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) |\n| cohere | official | spec | [cohere-ai/cohere-developer-experience](https://github.com/cohere-ai/cohere-developer-experience) |\n| gemini | official | spec | [Google AI Discovery](https://ai.google.dev/api/rest)(`generativelanguage.googleapis.com`) |\n| vertex | official | spec | [Google Cloud Discovery](https://cloud.google.com/vertex-ai/docs/reference/rest)(`aiplatform.googleapis.com`) |\n| openai | cerebras | spec | [cerebras-cloud-sdk-python `.stats.yml`](https://github.com/Cerebras/cerebras-cloud-sdk-python/blob/main/.stats.yml) → Stainless |\n| openai | deepinfra | spec | [api.deepinfra.com/openapi.json](https://api.deepinfra.com/openapi.json) |\n| openai | siliconflow | spec | [docs.siliconflow.cn](https://docs.siliconflow.cn/cn/api-reference/openapi.yaml)(硅基流动) |\n| openai | moonshot | spec | [platform.moonshot.cn/docs/openapi.json](https://platform.moonshot.cn/docs/openapi.json)(月之暗面 Kimi) |\n| zhipu | official | spec | [docs.z.ai/openapi.json](https://docs.z.ai/openapi.json)(Z.AI / 智谱 GLM) |\n| mistral | official | spec | [mistralai/platform-docs-public](https://github.com/mistralai/platform-docs-public/blob/main/openapi.yaml) |\n| perplexity | official | spec | [docs.perplexity.ai/openapi.json](https://docs.perplexity.ai/openapi.json) |\n| ideogram | official | spec | [developer.ideogram.ai/openapi.yaml](https://developer.ideogram.ai/openapi.yaml) |\n| jina | official | spec | [api.jina.ai/openapi.json](https://api.jina.ai/openapi.json) |\n| flux | official | spec | [api.bfl.ai/openapi.json](https://api.bfl.ai/openapi.json)(Black Forest Labs) |\n| openai | bytedance | overlay | [火山方舟 Ark](https://www.volcengine.com/docs/82379)(豆包) |\n| openai | sophnet | overlay | [SophNet](https://www.sophnet.com/docs/component/API.html) |\n| openai | baidu | overlay | [百度千帆](https://cloud.baidu.com/doc/qianfan/s/Hmh4suq26)(文心 ERNIE) |\n| openai | chutes | overlay | [Chutes](https://chutes.ai/llms-full.txt) |\n| openai | alibaba | overlay | [阿里云百炼 / 通义千问](https://www.alibabacloud.com/help/en/model-studio/compatibility-of-openai-with-dashscope) |\n| openai | yi | overlay | [零一万物 01.AI](https://platform.lingyiwanwu.com/docs) |\n| openai | stepfun | overlay | [阶跃星辰 StepFun](https://platform.stepfun.com/docs) |\n| openai | nvidia | overlay | [NVIDIA NIM](https://docs.nvidia.com/nim/large-language-models/latest/reference/api-reference.html) |\n| openai | minimax | overlay | [MiniMax 海螺](https://platform.minimaxi.com/docs/api-reference/text-chat-openai.md) |\n| openai | baichuan | overlay | [百川智能](https://platform.baichuan-ai.com/docs/api) |\n| openai | xiaomi | overlay | [小米 MiMo](https://platform.xiaomimimo.com/docs/en-US/api/chat/openai-api) |\n| openai | daocloud | overlay | [DaoCloud d.run](https://docs.daocloud.io/en/hydra/api-call/) |\n\n完整上游 URL、同步方式和版本钉死细节见 [`docs/SOURCES.md`](./docs/SOURCES.zh-CN.md)。\n\n---\n\n## 工作机制\n\nai-vendor-specs 是一层薄薄的数据层,职责单一:保存每个上游 AI 厂商 API 真相的机器可读拷贝(可审计、可追溯),用统一的 URI 协议对外暴露。\n\n```\n┌─── 12+ 个上游厂商 ────────────────────────────────────────────┐\n│   OpenAI / Azure OpenAI / Anthropic / Cohere / Google /        │\n│   xAI / DeepSeek / Groq / Together / AWS Bedrock               │\n└────────────────────────────┬──────────────────────────────────┘\n                             │ 每日 cron 同步(机器可读 spec)\n                             │ overlay 文件声明差异(无 spec 的)\n                             ▼\n┌─── ai-vendor-specs(本仓库)────────────────────────────────────┐\n│                                                                │\n│   upstream/<protocol>/<provider>/                              │\n│     openapi.{yml,json} | discovery.json     ← spec(自动同步)  │\n│     overlay.yml                              ← overlay(手维护)│\n│                                                                │\n│   manifest.json   ← 所有条目的发现入口                          │\n│   resolver lib    ← 把 base + overlay 合成完整 spec             │\n│   drift detector  ← 上游版本变动 / overlay 过期 / 同步失败时报警│\n└────────────────────────────┬──────────────────────────────────┘\n                             │ npm / PyPI / submodule / raw / CDN\n                             ▼\n       ┌─────────────────────┼─────────────────────┐\n       ▼                     ▼                     ▼\n  SDK 生成器              网关 / proxy           文档站\n  契约测试                AI agent 工具          IDE 智能提示\n```\n\n### 这个仓库做什么\n\n- ✅ 每日自动同步每个上游的机器可读 OpenAPI / Discovery 规范,hash 跟踪\n- ✅ 对没有公开机器可读 spec 的上游(AWS Bedrock、OpenAI 兼容厂商:xAI / DeepSeek / Groq / Together 等),用 overlay 文件声明差异\n- ✅ 维护顶层 `manifest.json` 作为所有消费方的发现入口\n- ✅ 漂移检测——版本变动、overlay 过期、同步失败——在消费方踩坑前预警\n\n### 这个仓库**不**做什么\n\n- ❌ 生成派生产物(合成 spec、SDK、契约 fixture)——那是消费方自己的选择\n- ❌ 记录消费方业务字段——数据保持中性的上游真相\n\n判断口诀:**\"这描述的是上游真实存在的东西吗?\"** 是 → 放这里。否 → 放消费方。\n\n架构细节(kind 分类、overlay 语法、metadata schema)见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.zh-CN.md)。\n\n---\n\n## 安装\n\n### npm\n\n```bash\nnpm install @aihubmix/ai-vendor-specs\n```\n\n### git submodule\n\n```bash\ngit submodule add https://github.com/AIhubmix/ai-vendor-specs.git ai-vendor-specs\ngit submodule update --init --remote ai-vendor-specs\n```\n\n### pip\n\n```bash\npip install ai-vendor-specs\n```\n\nPython 包共享同一份上游数据,提供只读 API。overlay 合成目前仅 JavaScript 版可用;详见下方 [Python 使用](#python-1)。\n\n### 直接下载(无需运行时)\n\n```bash\n# raw GitHub\ncurl https://raw.githubusercontent.com/AIhubmix/ai-vendor-specs/main/upstream/openai/official/openapi.yml\n\n# jsDelivr CDN\ncurl https://cdn.jsdelivr.net/gh/AIhubmix/ai-vendor-specs@main/upstream/openai/official/openapi.yml\n```\n\n---\n\n## 使用\n\n### 加载任意上游 spec\n\n```js\nconst { loadSpec } = require('@aihubmix/ai-vendor-specs');\n\n// spec 类条目:直接读文件\nconst openai = loadSpec('avs://openai/official');\n\n// overlay 类条目:自动合成 base + overlay\nconst bedrock = loadSpec('avs://anthropic/bedrock');\nconst xai     = loadSpec('avs://openai/xai');\n\n// 通过 JSON Pointer 取具体 schema\nconst cacheControl = loadSpec(\n  'avs://anthropic/official#/components/schemas/CacheControlEphemeral'\n);\n```\n\n### 发现可用上游\n\n```js\nconst manifest = require('@aihubmix/ai-vendor-specs/manifest.json');\n\nfor (const [key, entry] of Object.entries(manifest.upstream)) {\n  console.log(key, entry.kind, entry.rawUrl);\n}\n```\n\n或不通过运行时直接拉:\n\n```bash\ncurl https://cdn.jsdelivr.net/gh/AIhubmix/ai-vendor-specs@main/manifest.json\n```\n\n### Python\n\n```python\nimport ai_vendor_specs as avs\n\n# 厂商目录\nmanifest = avs.load_manifest()\nfor vendor in avs.list_vendors():\n    print(vendor['key'], vendor['kind'])\n\n# 单条查询\nxai = avs.get_vendor('openai', 'xai')\n\n# 原始 spec 文件路径(overlay 类条目返回 overlay.yml,\n# 合成需要 JavaScript 版 resolver,Python 合成器在路线图)\nspec_path = avs.load_spec_path('openai', 'official')\n```\n\n---\n\n## 典型场景\n\n### 1. 合成网关 / proxy 自家 spec\n拉上游骨架,叠加自家 overlay 产出对外 spec。\n\n```js\nconst { loadSpec, applyOverlay } = require('@aihubmix/ai-vendor-specs');\nconst base = loadSpec('avs://openai/official');\nconst final = applyOverlay(base, myGatewayOverlay);  // overlay = 自家认证、错误体等\n```\n\n### 2. SDK / 类型生成\n丢给任意 OpenAPI codegen,每日同步保证类型不滞后。\n\n```bash\nnpx openapi-typescript node_modules/@aihubmix/ai-vendor-specs/upstream/openai/official/openapi.yml \\\n  -o src/types/openai.d.ts\n```\n\n### 3. 契约测试(对照上游真相)\n断言上游承诺的字段是否真的出现。\n\n```js\nconst spec = loadSpec('avs://openai/official');\nconst required = spec.components.schemas.CreateChatCompletionResponse.required;\nrequired.forEach(f => expect(actual[f]).not.toBeUndefined());\n```\n\n(测自家网关响应该用自家 spec;这里只检查\"上游悄悄改了字段没\"。)\n\n### 4. 文档站展示上游\n从 `node_modules/` 直接读原始文件喂给 Redoc / Swagger UI。本项目的 [doc site](https://aihubmix.github.io/ai-vendor-specs/) 就是这么搭的。\n\n### 5. Discovery → OpenAPI 转换\nGemini / Vertex 走 Google Discovery。如果工具链只吃 OpenAPI,用 [gnostic](https://github.com/google/gnostic):\n\n```bash\ngnostic upstream/gemini/official/discovery.json --openapi-out=gemini.yml\n```\n\n### 6. AI agent 工具注册表\n遍历 `paths`/`operations` 直接生成函数调用 schema,适配 LangChain / MCP 等 agent 框架。spec 自带 `operationId`、参数 schema、请求体形状,一一映射成工具描述符。\n\n---\n\n## `avs://` URI 协议\n\n所有上游引用统一使用同一套 URI:\n\n```\navs://<protocol>/<provider>[#<JSON-Pointer>]\n```\n\n| 示例 | 解析为 |\n|---|---|\n| `avs://openai/official` | OpenAI 整份 OpenAPI spec |\n| `avs://anthropic/bedrock` | Bedrock 合成后的完整 spec(base + overlay) |\n| `avs://anthropic/official#/components/schemas/Message` | Anthropic spec 里某个 schema |\n| `avs://gemini/official` | Gemini 的 Google Discovery 文档 |\n\nResolver 按以下顺序定位数据根目录:\n\n1. 环境变量 `AVS_ROOT`(显式覆盖)\n2. 当前工作目录(在仓库自身内运行时)\n3. `node_modules/@aihubmix/ai-vendor-specs/`(npm 安装)\n4. 同级 `ai-vendor-specs/` 目录(git submodule)\n\n写 overlay 或消费方代码时无需关心当前在哪一种部署模式下。\n\n---\n\n## 文档\n\n| 文档 | 读者 | 内容 |\n|---|---|---|\n| [在线文档站](https://aihubmix.github.io/ai-vendor-specs/) | 浏览者 | 每个上游 spec 的 Redoc 视图,带 protocol 筛选 tab |\n| [架构设计](./docs/ARCHITECTURE.zh-CN.md) | 所有人 | 设计、kind 分类、metadata schema、overlay 语法 |\n| [上游来源](./docs/SOURCES.zh-CN.md) | 审计者 | 各厂商上游 URL 和同步方式 |\n| [贡献指南](./CONTRIBUTING.md) | 贡献者 | 加新厂商、本地开发、drift、webhook |\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.zh-CN.md"}