企业官网建设流程全解析

ade-python 是 LandingAI Agentic Document Extraction（ADE）的官方 Python SDK，用于把 PDF 等文档解析成结构化 Markdown 并抽取类型化字段。除了功能本身，这个仓库真正值得学习的是一套工程治理机制：spec-sync 自动化流水线，让 SDK 代码自动跟踪线上 OpenAPI 规范（spec）的每一次变更——规范一变，流水线自动开 PR、跑门禁、发通知，人只需做最后一步审查。

一个真实痛点：SDK 为什么必须跟着规范"走"

SDK 的方法签名、请求参数、响应模型，本质上是 OpenAPI 规范的"翻译件"。API 一改，SDK 就可能：

• 缺少新字段（用户传不进去）
• 类型描述过期（响应反序列化出错）
• 路由不一致（请求打到不存在的 URL，直接 404）

ade-python 团队曾依赖第三方代码生成平台 Stainless 自动完成这件事，但平台被收购后服务 sunset（设计决策记录见 docs/design/stainless-exit-and-v2.md），团队选择自建一条基于开源组件的流水线，核心机制写在 CONTRIBUTING.md 的 "Spec-sync pipeline" 一节。

流水线全景：每小时一次"漂移检测"

整套机制由.github/workflows/spec-sync.yml驱动，每小时运行一次（cron0 * * * *，见 .github/workflows/spec-sync.yml），同时支持手动触发。它跑着两条独立循环：

每一轮循环的流程只有四步，全部由scripts/spec-sync/下的可复用脚本完成：

1. 拉取 + 归一化—— scripts/spec-sync/fetch-normalize.sh 用jq -S对 JSON 按键排序，让"同一份规范 = 逐字节相同"，避免数组顺序抖动造成的"幽灵漂移"。
2. 对比快照—— scripts/spec-sync/check-drift.sh 用退出码区分三种结局：无漂移（0）、检测到漂移（10）、规范源不可用（20，比如 staging 集群未预约返回 404，属预期内静默跳过）。
3. 机械提交—— 漂移确认后，先提交更新后的规范快照，并用datamodel-code-generator重新生成参考模型（scripts/spec-sync/gen-models.sh，产物在 specs/_generated/，仅作为 AI 步骤的输入和人工评审参照，不随包发布）。
4. AI 接线——claude-code-action读取规范 diff，按仓库既有约定补齐资源类、方法、参数类型、测试和文档，作为第二个独立署名提交压入 PR。

💡为什么是"一个 PR、两个提交"？机械提交可以一扫而过，AI 提交则需逐行审查——两个提交天然形成审计边界，也让"代码生成失败"在 AI 运行前就中止。

四道 CI 门禁：AI 写的代码凭什么敢合入

AI 接线提交是"草稿"，真正兜底的是 CI 门禁（.github/workflows/pr-gates.yml）：

• 🔒surface-lock（向后兼容锁）—— scripts/spec-sync/surface-lock.sh 用griffe把当前代码与上一个 release tag对比，任何对"已发布公共 API"的破坏性改动直接失败。基线选 release tag 而非 main 上一个 commit 是刻意设计：已合并但未发布的表面仍可自由修改，只有"已经承诺给用户的"才被锁死。
• 🔒check-v2-paths（路由双向核对）—— scripts/spec-sync/check-v2-paths.sh 双向校验：代码里发的每个 URL 必须存在于 V2 规范快照中；快照里每个/v2/*路由必须被某处真正发送。它拦截的是 AI 的真实事故：某次 AI 把新出现的/v1/classify"翻译"成client.v2.classify，打到了根本不存在的/v2/classify。
• 🔒contract-tests（staging 契约测试）—— 对 staging 环境跑tests/contract真实 API 测试。因为该作业执行的是 AI 编写的代码且持有 staging 密钥，它被放在受保护的spec-sync-contract环境后，必须由人工审阅 diff 后手动放行——密钥只在此之后才暴露。
• 🔒lint / test / typecheck—— 常规静态检查与单元测试，V1 循环的 AI 步骤还被要求自行运行./scripts/format和./scripts/lint修复问题。

人机协作的生命周期：Slack 线程 + 老化提醒

流水线不是一开 PR 就完事，docs/spec-sync-runbook.md 把"人该做什么"写得像值班手册：

几个细节很见功力：所有 Slack 消息在#ade-sdk-pipeline渠道里按线程组织，线程根的ts由 scripts/spec-sync/thread-ts.sh 持久化在 PR 描述里的隐藏注释中，后续事件全部回贴同一线程，避免刷屏；PR 描述还会由 scripts/spec-sync/summarize-pr.sh 让模型基于真实 diff 生成 "What changed" 摘要，且明确规定把 diff 当作数据而非指令，防 prompt 注入。

"staging in, production out"：合并不等于发布

这是整套治理中最有味道的一环：

1. spec-sync 跟踪的是staging规范 → PR 合入main；
2. 合并不触发任何发布，这段空窗就是 QA 窗口——QA 安装合并后的main，对 staging 验证；
3. 等 API 真正上了 production，QA 才手动触发 Release workflow 并选择版本号（patch / minor / major），发布前还要先跑一遍针对生产 API的完整 e2e 套件作为门禁。

换句话说：SDK 代码跟随 staging 快速演进，制品发布则被生产环境死死拽住。哪怕发布失败（红色），由于所有门禁都在打 tag 之前，不会留下任何需要清理的半成品。

密钥设计：一个反直觉的坑

CONTRIBUTING 特别强调：spec-sync 推分支、开 PR 用的SPEC_SYNC_TOKEN绝不能是默认的GITHUB_TOKEN——GitHub 的反递归规则会导致它开出的 PR 不再触发门禁 workflow，所有门禁会静默失效。这类"沉默的坑"正是文档化治理价值的体现。

给 SDK 维护者的启示清单

• ✅规范快照入库（specs/*.json）：让每次 API 变更都变成一个可读的 PR diff，而不是黑盒重生成
• ✅机械生成与 AI 接线分离提交：审计边界清晰，失败可提前中止
• ✅用 CI 门禁代替人工警惕：向后兼容、路由一致性都由脚本机械判定
• ✅人机分工明确：机器负责发现和起草，人负责审查、放行密钥、拍板发布
• ✅把操作手册写进仓库：docs/spec-sync-runbook.md 连"渠道安静了太久可能意味着 staging 没预约"这种隐性知识都写清楚了

这套 spec-sync 流水线的精髓不在于某个脚本，而在于**"规范是事实来源，代码是衍生品，发布是人为决策"** 的三层分离——这正是它能在没有代码生成平台的情况下，让 SDK 始终紧跟 OpenAPI 规范的原因。