正式发布版接口文档需结构清晰、字段完整、示例真实、格式统一，且能脱离开发环境独立运行；必须基于结构化源（如openapi.yaml）并用Trae CLI注入版本、变更标记等元数据，再导出为HTML、OpenAPI JSON或带水印PDF。
☞☞☞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。
