OpenAI API 中文文档

本项目已从早期手工维护方式迁移为可自动维护的文档仓库。官方英文 Markdown 同步与可追溯、可增量恢复的中文翻译 PR 流水线均已闭环，当前按核心文档优先级持续积累中文内容。

docs/en/ 是官方英文内容的镜像，不是本项目原创内容。接口行为、价格、限制和安全要求请始终以 OpenAI API 文档 为准。

目录结构

.
├── apps/web/               # Next.js 双语静态站（Vercel）
├── scripts/
│   ├── sync-docs.ts          # 英文文档发现、同步和更新检查
│   ├── translate-docs.ts     # 中文翻译状态和增量计划
│   ├── fetch-coordinator.ts  # 全局限速、重试和熔断
│   ├── docs.config.json      # 来源与网络策略配置
│   └── translation/          # 翻译规划、提示词、术语表和优先级
├── docs/
│   ├── en/                   # 提交到 Git 的官方英文 Markdown 镜像
│   │   ├── api/docs/
│   │   ├── api/reference/
│   │   └── .source-manifest.json
│   ├── zh/                   # 简体中文 Markdown 镜像与翻译 manifest
│   └── legacy/               # 早期手工中文译文及图片归档
└── .github/workflows/
    ├── ci.yml                # PR、main 与手动触发的质量门禁
    ├── sync-docs.yml         # 每天检查并创建官方更新 PR
    └── translate-docs.yml    # 受预算约束的批量自动翻译 PR

英文文件严格按照官网 URL 的路径保存。例如：

https://developers.openai.com/api/docs/quickstart.md
→ docs/en/api/docs/quickstart.md

同步器不会修改 Markdown 正文，因此相对链接保持原有相对关系，外部链接也保留官方原始地址。

使用

需要 Node.js 24 和 pnpm：

pnpm install
pnpm docs:bootstrap
pnpm docs:status
pnpm docs:check
pnpm docs:sync
pnpm translate:status
pnpm translate:check
pnpm translate:plan -- --section guides --match quickstart --limit 10
pnpm translate:simulate -- --match guides/agents/quickstart.md --limit 1

• docs:bootstrap：迁移时从已落盘的 docs/en/ 离线初始化 manifest；不会联网或修改 Markdown。
• docs:status：离线查看已跟踪页面数量和数据量。
• docs:check：联网检查官方内容或本地镜像是否变化，不写文件；有变化时退出码为 1。
• docs:sync：以低并发和全局限速联网同步 Markdown；本轮全部下载成功后才更新文件和 docs/en/.source-manifest.json。

完整同步会拒绝空索引和异常大幅删除。超过自动安全阈值的 prune 必须由维护者使用 --allow-large-prune 明确确认；定时任务不会自动绕过这道保护。

维护细节和筛选参数见 scripts/README.md，文档目录说明见 docs/README.md。

自动更新

GitHub Actions 每天北京时间 00:00 读取官方 llms.txt 索引、运行测试并同步英文 Markdown。只有 docs/en/ 相对 main 实际发生变化时，机器人分支 automation/sync-openai-docs 才会创建或更新 PR；机器人不会直接写入 main。自动 PR 仍须在维护者批准工作流运行后通过 Quality gate，并由维护者审核合并。

中文翻译 Action 在英文变更合入 main 后立即运行，并每天北京时间 01:00 补充执行。它只检出受信任的 main，并从 Settings → Environments → translation-production 读取运行配置。

TRANSLATION_PROVIDER 支持以下键名：

键名	服务	API 地址	Environment secret	模型变量	默认模型
deepseek	DeepSeek	https://api.deepseek.com/v1	DEEPSEEK_API_KEY	DEEPSEEK_MODEL	deepseek-chat
minimax	MiniMax 国际站	https://api.minimax.io/v1	MINIMAX_API_KEY	MINIMAX_MODEL	MiniMax-M3
minimax-cn	MiniMax 国内站（含国内 Token Plan）	https://api.minimaxi.com/v1	MINIMAX_API_KEY	MINIMAX_MODEL	MiniMax-M3

在 Environment secrets 中配置 MINIMAX_API_KEY 或 DEEPSEEK_API_KEY。只有一个 Key 时会自动选择对应供应商；仅有 MiniMax Key 时默认选择国内站 minimax-cn。同时存在两个 Key 时必须在 Environment variables 中设置 TRANSLATION_PROVIDER，值只能是上表中的键名。模型可通过同处的 MINIMAX_MODEL 或 DEEPSEEK_MODEL 切换，无需修改仓库或创建 PR。MiniMax 国内站 Plan 应使用 minimax-cn；国内站与国际站的 Key 和额度按各自接口生效，不应混用。

运行时解析出的实际 provider/model 会进入翻译策略指纹。每轮最多翻译 100 篇页面，每篇不超过 20,000 个源字符，并通过 automation/translate-openai-docs 创建一个 PR。已有翻译 PR 等待审核时不会继续调用模型。自动选择先按 stale/missing 状态维护既有译文，再在同一状态内按 scripts/translation/priority.zh-CN.json 的核心文档顺序处理，未列入清单的页面保持稳定路径排序。术语表中的 preserve 项会在请求前替换为可恢复占位符；单批请求耗尽有限重试后，页面还会基于 checkpoint 额外恢复一次，认证、配置和完整性错误不会盲目重试。

仓库必须在 Settings → Actions → General → Workflow permissions 中启用 Allow GitHub Actions to create and approve pull requests。main 的 Ruleset 可以因此保持空 bypass，并要求所有更新通过 PR 和 Quality gate。PR 标题必须以 [AI] 或 [Human] 标明来源，其中 codex/ 与 automation/ 分支强制使用 [AI] 。

translate:status 离线汇总全部页面的增量状态，translate:check 额外拒绝目标文件缺失、未登记或与 manifest 不一致；translate:plan 按自动队列优先级只读列出下一轮可翻译或阻塞的页面。translate:simulate 使用 Echo/Fake Provider 执行无 key、无写入闭环。translate:run 用于本地精确单篇翻译，translate:auto 为远端按优先级选择最多 100 篇受预算约束的页面；人工润色后用 translate:review 收录目标 SHA 并标记 reviewed。完整翻译设计见 docs/translation-design.md。

人工校对中可复用的固定译法应进入术语表，通用表达要求应进入翻译提示词；只适用于单篇文档的上下文、歧义或官方原文勘误记录在 scripts/translation/review-notes.zh-CN.json。页面级备注会自动加入该页翻译请求和策略 SHA，仅让对应页面进入 stale-policy，不会触发全站重翻。

静态双语文档站

当前仓库同时维护首个可用站点 apps/web。它在构建期读取 source/translation manifest 和磁盘 Markdown，按官方 llms.txt 的分组与顺序生成完整导航：421 篇英文源页面都有稳定静态路由，其中 414 篇直接渲染正文；7 篇超过 1 MB 的事件/资源总表暂时生成轻量说明页，避免单页 HTML 和 Vercel 产物异常膨胀。已有中文译文显示在同路径的 /zh/ 页面，其余中文路径保留原目录位置并引导到本站英文原文。Markdown 中指向 developers.openai.com/api/docs 与 /api/reference 的链接会转换为当前语言的本站路由，外部链接保持明确标识。

pnpm web:dev
pnpm web:typecheck
pnpm web:lint
pnpm web:test
pnpm web:build

站点使用 Next.js 静态导出，Vercel 项目 Root Directory 设置为 apps/web，并在 Root Directory 设置中启用 Include source files outside of the Root Directory in the Build Step，让构建读取仓库根部 docs/。站点无需数据库或运行时服务；生产环境建议设置 NEXT_PUBLIC_SITE_ORIGIN 为正式域名。首页会把 OpenAI 官方开发者文档 明确展示为权威内容源，本项目不冒充官方网站。

首个实现暂留在当前仓库，以便同步、翻译和展示闭环快速演进；代码内部保持内容适配、结构导航、Markdown 渲染和部署配置的边界。出现第二个真实翻译站后，再把通用部分提取为独立包或仓库。演进方案见 docs/static-site-architecture.md。

许可证与内容归属

项目代码见 LICENSE。OpenAI 文档内容及商标权利归其各自权利人所有。