📌 项目地址：humanlayer/12-factor-agents | ⭐ 20,631 颗星 | 🔧 TypeScript | 📜 未标注
我跑过所有主流Agent框架：CrewAI、LangChain、smolagents、LangGraph、Griptape。和YC内外的创始人聊了两年多，发现一个冷酷的事实——没有一家面向真实客户的生产团队在用这些框架。他们在自己写代码，只在关键节点插入LLM调用。
这不是观点，是上百次对话和代码审查后的总结。我在HumanLayer（humanlayer.dev）做LLM工具，在YouTube和Substack上持续分享Agent构建经验。这些经历让我认同Dex在12-Factor Agents里说的：大部分自称“AI Agent”的产品并不agentic，本质是确定性软件加LLM点缀。
但这个项目没有止步于吐槽。它系统性地提出了12条工程原则，试图回答：“什么原则能构建LLM软件，使其可靠到可以交给生产客户？”
我读完了每个factor的markdown文件（在content/目录下），结合自己的工程实践，给你拆解一下到底值不值得照做。
一条反常识的观察
Dex指出，Anthropic那篇著名的Agent文章（“给你一个prompt、一包工具、循环直到达成目标”）给很多人灌输了错误心智模型。生产需要的Agent是可预测、可熔断、可调试的，LLM是概率性调用点，不是控制循环的主体。框架之所以在生产中不受欢迎，是因为它们把控制权交给了黑盒循环，一旦LLM输出偏移，整个Agent就迷路。
这个观察和我自己的经验一致。我们在HumanLayer早期也试过LangGraph，但很快就切成了自己写的状态机+LLM函数调用。状态转移是确定的代码，LLM只在特定节点产生输出，出错时能快速熔断到人工兜底。
12条原则，哪几条最致命
每条factor都有独立的markdown文件（content/factor-01.md等）。我挑两个我最在意的给你解剖。
Factor 3：控制你的上下文窗口
上下文爆炸和有效信息稀释是LLM应用最常见的崩溃原因。Dex的做法是“Own your context window”——由代码控制放什么、不放什么、按什么顺序、总量多少。这需要设置硬token上限，超过就截断或替换。优先级的判断交给工程逻辑，而不是让模型自己决定忽略什么。
这条原则很多人听过但做不到。我见过太多项目直接把整个对话历史塞给模型，然后用“请忽略不相关的信息”来祈祷。Dex的建议是：在代码中显式声明每条信息的优先级和保留策略。比如，系统指令固定占20%的token预算，最近的用户消息占40%，历史摘要占20%，外部工具返回占20%。超出就截断或降级。
注意：模型处理长上下文的能力越来越强（Claude 3.5处理100K tokens很稳），但信息稀释依然是工程问题。切得好不好、优先级排得对不对，跟模型的能力无关。这条原则是工程责任。
Factor 10：小型聚焦Agent
单个Agent只做一件事。输入输出格式可验证（用Zod或JSON Schema），有独立的熔断和超时，日志结构统一，方便按Agent筛选排查。Dex说，即使未来模型更聪明，这些原则仍然成立——因为可测试、可观测、可熔断是模型能力替代不了的工程属性。
他直接回应了一个典型质疑：“LLM越来越强，这些原则还有必要吗？”答案很干脆：模型再聪明，错误补救依然靠代码。模型输出格式不对，你能定位到具体哪个Agent出问题，而不是在全链路日志里大海捞针。
我补充一点：小型聚焦Agent还有一个好处——你可以独立替换模型或者prompt策越，而不影响其他Agent。这在A/B测试场景下非常实用。
那其他9条呢？我快速排个优先级
READEME中的完整列表我没有全部读到（每个factor都有内容），但从README提到的链接和讨论（factor-10包含“what if LLMs get smarter”的讨论，factor-3指向上下文窗口）可以推断出整体框架。按我的经验，对生产团队最重要的几个：
- Factor 2：可观测性（每个LLM调用都记录输入输出、耗时、token用量、是否触发熔断）
- Factor 5：人工兜底（当Agent不确定时，必须能无中断地转给人类）
- Factor 7：全周期测试（不仅仅是单元测试，还包括对真实LLM调用的集成测试和混沌工程）
- Factor 11：渐进式交付（先给内部用，再给beta用户，最后100%生产）
其他原则比如Factor 1（单一职责）、Factor 4（显式依赖注入）、Factor 6（状态外置）等，都是经典分布式系统原则，搬到LLM上下文中依然成立，但创新性不如3和10。
这个项目最大的价值在哪里
不是原则本身——每一条单独拿出来都算不上颠覆性。真正的价值在于把分散的工程智慧整理成可对照的清单。当你面对一个LLM应用崩溃时，可以快速过一遍12条，找出哪个环节缺失。
比如：Agent跑飞了？检查Factor 3（上下文是否泄漏了无用信息）、Factor 10（Agent是否承担了过多职责）、Factor 2（是否有日志定位到具体失败点）。这种结构化排查，比对着空白的错误栈瞎猜高效得多。
一个必须强调的坑
README里提到了一个脚手架命令：npx/uvx create-12-factor-agent。但这个命令在讨论阶段（GitHub Discussion #61），用法未稳定，不要在生产项目里依赖它。我在写这篇文章时试了一下，发现安装路径和参数还在设计中。如果你想快速生成符合12因子原则的Agent骨架，先读文档再决定是否使用，或者直接手动实现。
不必把Agent当成特殊系统
加熔断、加监控、加超时、加人工兜底——每个后端工程师都懂，但一到LLM项目就容易觉得“智能”两个字可以绕过这些。12-Factor Agents回归了分布式系统的基础原则，只是把LLM当成一个特殊外围服务来对待。
这个项目已经有20631个star，说明很多人认同这个方向。但认同和落地之间有距离。我的建议：先挑你当前最痛的那条原则（是上下文爆炸还是无法调试？）打开对应的factor markdown文件读，然后动手改。比装一个新框架有用得多。
我看了下讨论区，Dex也在征集contributor。如果你在生产中踩过LLM相关的坑，不妨去提个PR，把实际案例补充进原则文档。