trae接口文档正式发布需结构化源文件、注入版本元数据、导出多端格式并嵌入发布说明。必须检查openapi.yaml/json存在性，用trae docs inject添加版本与变更标记，通过build/export/pdf生成html/api平台/pdf交付物，最后打git标签锁定快照。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要把Trae生成的接口文档整理成可直接交付给前端、测试或客户使用的正式发布版本，而不是仅用于本地调试的草稿文件。这要求文档结构清晰、字段完整、示例真实、格式统一，并能脱离开发环境独立运行。
确认文档源是否已结构化
先检查当前文档是否来自代码注释、OpenAPI YAML/JSON 或外部平台（如Apifox）同步。若文档是AI零散输出的纯文本，【必须退回上一步补全元数据再生成】，否则后续所有格式化操作都会丢失参数类型、必填标识、状态码等关键信息。
打开 docs/api/ 目录，确认存在 openapi.yaml 或 openapi.json 文件；若只有 README.md 类文档，说明尚未触发 Trae 的结构化提取流程。
用Trae CLI注入发布级元数据
这一步决定文档是否具备“可发布”属性——不是加个标题就行，而是让每个接口都带版本号、变更标记、兼容性说明。
在项目根目录执行：trae docs inject --version 1.3.0 --since v1.2.0 --compatibility breaking
该命令会扫描 Git 提交范围，自动为新增/修改的接口添加 deprecated: false、x-trae-changed: true 等扩展字段，并在文档顶部写入语义化版本头。不加 --since 参数会导致全部接口被标记为“首次发布”，掩盖真实变更范围。
导出为多端就绪格式
方法一：生成静态HTML站点（适合内部交付与离线查阅）
运行 trae docs build --format html --output dist/docs。生成的 index.html 自带搜索、侧边导航、响应式布局，无需服务器即可双击打开。
方法二：导出为Apifox/Yapi可导入的JSON（适合协同平台对接）
执行 trae docs export --format openapi3-json --strict --output docs/api/openapi-v1.3.0.json。【--strict 必须启用】，它会校验所有 $ref 引用是否有效、所有 response schema 是否可解析，失败则中断导出，避免上传后平台报“schema invalid”。
方法三：生成带水印的PDF（适合客户签约交付）
先确保系统已安装 wkhtmltopdf，然后运行：trae docs pdf --source dist/docs/index.html --watermark "CONFIDENTIAL - v1.3.0" --output deliverables/api-docs-v1.3.0.pdf。水印文字会叠加在每页右下角，不可复制不可编辑。
嵌入发布说明并锁定快照
第一步：将本次发布的接口变更摘要写入 CHANGELOG.md 的 Unreleased 区块，格式需严格匹配 Conventional Commits：
- feat(api/users): 新增 /v1/users/{id}/roles 接口，支持角色批量赋权
- fix(api/orders): 修复 GET /v1/orders?status= 时 status 枚举值校验失效问题
第二步：在 docs/api/ 目录下创建 versioned/ 子目录，把 openapi-v1.3.0.json 和 api-docs-v1.3.0.pdf 移入其中。
第三步：执行 git tag -a v1.3.0 -m "Release API docs for 2026-Q2" 并推送：git push origin v1.3.0。标签一旦打上，对应文档快照即视为正式发布态，禁止再修改 versioned/ 下同名文件。
