12因子Agent原则
构建可靠、可扩展、可维护的LLM应用的核心工程原则。
证据显示仓库主要是一个原则性指南，没有实际代码或运行时行为。因此，所有信任标准均未得到满足：没有最小权限、用户确认、数据流透明、敏感数据处理、依赖安全、外部影响、回滚或来源归属的证据。扣分：这些方面完全缺失。
自一致性：README 中列出的 12 个因素与内容文件一致，但未提供完整内容，因此仅部分支持。依赖可用性：未提供依赖信息。失败消息：测试文件显示 CLI 对错误输入有清晰的错误消息，但未提供实际代码，因此仅部分支持。扣分：依赖可用性缺失，失败消息仅从测试推断。
受众和场景：README 明确针对构建生产级 LLM 应用的开发者，并提供了多种场景。能力边界：指南讨论了框架的局限性，但未明确说明自身边界。触发精度：未涉及。环境适配：提到 TypeScript 和 Python，但未提供具体环境要求。扣分：触发精度缺失，能力边界和环境适配仅部分覆盖。
信息架构：README 提供了清晰的结构和导航。安装说明：未提供。命名稳定性：因素名称一致，但未提供版本信息。示例和 FAQ：提供了示例和链接，但未提供 FAQ。已知限制：讨论了框架的局限性，但未明确说明自身限制。许可证：提供了 Apache 2.0 和 CC BY-SA 4.0。版本控制和变更日志：未提供。维护责任：列出了贡献者，但未明确维护者。扣分：安装说明、版本控制、变更日志缺失，其他部分仅部分覆盖。
输出可用性：指南提供了可操作的见解，但未提供实际代码或工具。边际价值：提供了独特的视角，但未提供实现。成本效益：未提供成本分析。扣分：输出可用性和成本效益仅部分支持，边际价值有支持但未量化。
声明可追溯性：README 中的声明部分有链接支持，但未提供完整证据。跨来源佐证：未提供。事实与推断分离：指南区分了个人经验和一般原则，但未明确标注。扣分：跨来源佐证缺失，其他部分仅部分支持。
- 仓库主要是原则性指南，没有实际代码或可执行产品，因此无法评估运行时行为。
- 未提供安装说明、版本控制或变更日志，可能影响可维护性。
- 依赖安全、数据流透明等信任方面完全缺失，需谨慎对待。
这个 Agent 能做什么，适合哪些场景？
12-Factor Agents 是一套指导原则，参考了经典的 12-Factor App 方法论，用于构建适合生产环境使用的 LLM 应用。仓库包含 12 个核心原则的详细内容，涵盖自然语言到工具调用、提示词管理、上下文窗口控制、工具结构化输出、状态统一、暂停/恢复、人工介入、控制流、错误压缩、小型专注 Agent、多端触发以及无状态 reducer 等主题。此外，还提供了“简要软件历史”和“附录 13：预取上下文”等补充章节。项目以 CC BY-SA 4.0 授权内容，Apache 2.0 授权代码，欢迎社区贡献。该指南强调将 Agent 构建中的模块化概念融入现有产品，而非全面采用框架。
该仓库主要提供一份分章节的指南（Markdown 格式），详细阐述 12 个原则，每个原则都包含具体的设计模式、代码示例（主要使用 TypeScript）以及架构建议。例如，Factor 1 阐述如何将自然语言指令转化为工具调用；Factor 2 强调提示词的自有与版本管理；Factor 3 讨论如何拥有和控制上下文窗口；Factor 4 指出工具只是结构化输出；Factor 5 提议统一执行状态和业务状态；Factor 6 建议使用简单 API 实现启动/暂停/恢复；Factor 7 讨论使用工具调用来联系人类；Factor 8 强调自有控制流；Factor 9 建议将错误压缩到上下文中；Factor 10 提倡小而专注的 Agent；Factor 11 讨论从任何地方触发，满足用户所在；Factor 12 建议将 Agent 设计为无状态 reducer。仓库不包含可执行代码，而是纯粹的知识性内容，为 LLM 应用架构提供指导。
- 技术创始人或工程师正在设计一个生产级 Agent，希望避免常见框架的陷阱，可以参考这些原则来架构自己的系统。
- 团队已经在使用某个 Agent 框架，但发现难以调试或扩展，可以借鉴这些原则来调整或替换框架。
- 开发者希望将 LLM 功能集成到现有产品中，可以参考如何模块化地融入 Agent 概念，而不是全盘重构。
- 架构师在规划 LLM 应用的执行状态管理，可以学习如何统一执行状态和业务状态，提高可靠性。
- 工程师需要设计长时间运行的任务处理机制，可以参考第 6 条原则的启动/暂停/恢复模式，以及第 12 条的无状态 reducer 设计。
- 团队希望让 Agent 与人工协作，可参考第 7 条原则，通过工具调用联系人类，实现人机协同。
这个 Agent 有哪些优点和局限？
- 提供了可操作的设计模式，而非抽象理论，每个原则都有详细的解释和代码示例。
- 强调模块化，而非全盘采用框架，使现有产品可以逐步集成 LLM 功能。
- 独立于特定框架或语言，以 TypeScript 示例为主，但适用于任何编程语言。
- 社区驱动，欢迎贡献和反馈，持续演进。
- 仓库是纯文档，不含任何可直接运行的代码或工具，需要读者自行实现。
- 没有具体的代码库或 API 供集成，需要自行将原则转化为实际代码。
- 未提及 MCP 等现代标准，可能不完全覆盖所有生态。
- 示例主要使用 TypeScript，可能对 Python 开发者不够友好，尽管中提到同样适用于 Python。
如何安装或部署这个 Agent？
该仓库是知识库，非软件包，无需安装。可直接通过浏览器访问 GitHub 页面阅读。
如何使用这个 Agent？
使用方式：直接在 GitHub 仓库浏览 content/ 目录下的各个 factor 文件，或使用 README 中的视觉导航链接。也可以克隆仓库到本地查看。