用途：将 API 参考文档更新为生产环境最新的 OpenAPI 规范。API 文档由 docusaurus-plugin-openapi-docs 依据 OpenAPI 规范生成，整体流程为下载最新 openapi.json、替换本地规范文件、重新生成 API 文档页面。
主要文件位置：OpenAPI 规范源文件在 docs/docs/reference/openapi.json；生成的 API 文档在 docs/docs/reference/api/*.api.mdx；生成的侧边栏在 docs/docs/reference/api/sidebar.ts；Docusaurus 配置在 docs/docusaurus.config.ts。
使用方式：在 docs 目录执行包装脚本。默认从生产（线上云 API）获取：pnpm update-api-docs；显式线上：pnpm update-api-docs:live；从本地运行的 API 获取（http://localhost/api/openapi.json）：pnpm update-api-docs:local；从指定本地文件获取：pnpm update-api-docs:file /path/to/openapi.json。脚本会写入 docs/docs/reference/openapi.json，然后依次运行 npm run clean-api-docs -- agenta 与 npm run gen-api-docs -- agenta，其中 agenta 是 docusaurus.config.ts 中定义的 OpenAPI 配置 ID。
依赖与验证：全新克隆或未安装依赖时，先在 docs 目录执行 npm install。生成内容包括每个端点的 .api.mdx 文件、API 分类的 .tag.mdx 文件以及 sidebar.ts。可选启动开发服务器预览：npm run start，然后访问 http://localhost:5000/docs/reference/api 验证渲染。
提交建议：首次提交写明 docs(api): update OpenAPI spec from production，并包含 openapi.json、* .api.mdx、* .tag.mdx 与 sidebar.ts 等变更文件。
限制与排错：clean 与 generate 命令需要配置 ID，缺失会报 missing required argument 'id'；出现 docusaurus: not found 时需先在 docs 目录运行 npm install；关于 onBrokenMarkdownLinks 的弃用警告是已知警告，可忽略，将在未来 Docusaurus v4 迁移中处理。OpenAPI 插件在 docs/docusaurus.config.ts 中配置，包含 id、docsPluginId、specPath、outputDir、downloadUrl 及按 tag 分组的 sidebar 选项。其他平台、收费与使用效果暂未提供。