用n8n + Claude构建PMO自动化：从理想到生产的坑

用 n8n + Claude 构建 PMO 自动化：从理想到生产的坑

三个月前，我在一张白纸上画了一个很美的图：n8n 居中调度，Claude 负责智能决策，Notion 存储项目状态，Slack 推送通知。整个 PMO 自动化流程看起来行云流水，应该两周搞定。实际上，我花了将近两个月，踩了足够多可以写成文章的坑。这篇文章不是教你怎么做，而是告诉你我是怎么搞砸又修好的。

第一个坑：把 Environment Variables 当 Credentials 用

刚开始搭 n8n 的时候，我的习惯是所有 API Key 塞进 .env 文件，然后用 {{ $env.NOTION_API_KEY }} 这样的表达式直接引用。这在开发环境跑得很顺，直到我把 workflow 导出分享给另一个同事，他跑起来什么都是空的。原因很简单：n8n 导出的 JSON 不包含环境变量的值，接收方需要自己配同名变量。这不是 bug，是设计，但没人告诉你这件事。

更深的问题来了：我在 Synapse 体系里有将近十几条 workflow，分别用了不同风格的凭证管理。有的用 env，有的用 n8n 内置的 Credentials 节点，有的干脆把 key 硬编码在 HTTP Request 节点里（是的，我知道，别说了）。这导致每次 workflow 出问题，排查第一步都是”这个节点的认证是哪种方式”。最终我做了一个统一化决策：所有外部服务凭证一律迁移到 n8n 的 Credentials 管理系统，env 只存非敏感的配置项，比如环境标识、超时时间。这个决策让我重写了大概 60% 的节点配置，但之后的维护成本下降明显。

第二个坑：Notion API 的速率限制不是你以为的那样

Notion API 官方文档写的是”每秒 3 个请求”的速率限制。我以为这意味着我只要在 n8n 里加个 0.4 秒的延迟节点就够了。然而在实际的 PMO 自动化流程里，一次项目状态同步会触发批量的 Page 更新，每个 Page 又可能触发 Block 的嵌套读写。真实情况是：你不会撞 3 req/s 的上限，你会撞”同一个 Workspace 下并发修改同一个 Database”的隐性限制，错误码 409，没有明确的 retry-after 头。

我的解法是在 n8n 里引入了一个显式的队列化 subworkflow：所有 Notion 写操作先进入一个 staging 队列，由一个单线程的 executor workflow 按序处理，失败自动 retry 最多三次，超出则写 Dead Letter Queue 并告警。这套结构增加了 workflow 的复杂度，但让整个系统从”偶尔静默丢失更新”变成了”失败可见且可重试”。这个差距在 PMO 场景里是关键的——你不能允许项目状态更新静默失败。

第三个坑：E2E 测试没有验收标准

最让我抓狂的不是技术问题，是测试问题。n8n 的 workflow 测试很难系统化：你可以手动触发单个 workflow，可以看执行日志，但很难定义”这个 PMO 流程端到端是否正确运行”的机器可验证标准。

我在早期犯了一个错误：用”workflow 没有报错”作为通过标准。这导致我上线了一批能跑但输出错误的 workflow——比如 Claude 返回的结构化 JSON 格式变了，下游解析节点没有更新，数据默默地被丢掉了，没有任何错误。后来我建立了一套基于”状态断言”的验收标准：每条核心流程执行完毕后，必须有一个专门的 Verifier 节点去检查目标系统的状态是否符合预期，而不只是检查执行过程有没有抛出异常。比如”任务创建流程”的验收标准是：Notion 里存在对应 Page，Page 的 Status 字段是 “In Progress”，Slack 里发出了通知，且 Claude 的分析结果被正确存储到了 Page 的指定 property 里。四个断言，全部通过才算 PASS。

关于 Claude 在这套系统里的实际位置

值得单独说一下：Claude 在这套 PMO 自动化里不是万能的指挥官，而是一个专门处理”非结构化→结构化”转换的节点。具体来说，它负责：把自然语言的任务描述解析成带 priority/owner/deadline 字段的 JSON；把多条进度更新归纳成一段摘要；以及在任务状态异常时生成可读的告警说明。把 Claude 的职责边界限定在这里，而不是让它”决定下一步怎么做”，是整个系统稳定性的关键。AI 做判断，规则做路由，这个分工在实际工程里比”让 AI 全权处理”要可靠得多。

可复用的原则

如果要从这次经历里提炼几条可以直接用的原则：第一，凭证管理从第一天就要统一化，事后迁移的成本是预防成本的五倍。第二，所有调用外部 API 的节点都要假设它会失败，设计 retry 和 dead letter 是必须的，不是可选的。第三，E2E 测试的验收标准要基于目标系统状态，而不是执行过程是否无异常。第四，AI 组件的职责要显式边界化，它应该是一个确定性节点，而不是一个黑盒决策者。

如果你在构建 AI 工程团队，欢迎参考我们开源的 Synapse 框架——它是我们把上述这些坑系统化之后沉淀出的 Multi-Agent 运营体系，包含 Harness 控制层、执行链设计和跨会话状态管理，可以直接 fork 作为你自己团队的起点。