框架选择
Kailash 栈分为三层抽象：原子件、引擎与代理。从适配你问题的最高层开始；只有当更高层无法表达所需模式时，才下沉到更低层。
- 从引擎开始。 DataFlowEngine、NexusEngine、PactEngine。它们跨越全部原子件进行组合，并自动处理治理、中间件与数据分级。
- 需要自主执行时引入代理。 单一受治理代理使用 Delegate；多代理编排使用 GovernedSupervisor。
- 当引擎无法表达相应模式时下沉到原子件。 WorkflowBuilder、BaseAgent、Signature。这些是原始构建块，不带组合层。
- 存在可用框架时，绝不自写等价的原始代码。 若在拼接 SQL 字符串，请改用 DataFlow；若在编写 HTTP 处理函数，请改用 Nexus；若在为代理编写 if-else 路由，请改用 Kaizen。
| 需求 | 推荐使用 | 层级 |
|---|---|---|
| 存储与查询数据并纳入治理 | DataFlowEngine | 引擎 |
| 无需工作流开销的快速 CRUD | DataFlow Express（db.express） | 引擎 |
| 同时部署为 API、CLI 与 MCP | NexusEngine | 引擎 |
| 评估治理约束 | PactEngine | 引擎 |
| 运行单个自主代理 | Delegate | 代理 |
| 协调多个受治理代理 | GovernedSupervisor | 代理 |
| 用节点自定义工作流 | WorkflowBuilder | 原子件 |
| 自定义代理类型 | BaseAgent + Signature | 原子件 |
| 自定义约束逻辑 | 直接使用 GovernanceEngine | 原子件 |
何时使用引擎
Section titled “何时使用引擎”对大多数项目而言，引擎都是合适的起点。它们跨越全部原子件组合，并自动强制执行治理。
DataFlowEngine 适用于存在数据模型的场景。定义一个 Python dataclass，即可得到受治理的 CRUD 操作、迁移与查询监控，支持 PostgreSQL、MySQL、SQLite 与 MongoDB。当不需要工作流组合时，Express 路径（db.express.create、db.express.list）可提供 0.27ms 的 CRUD 响应。
NexusEngine 适用于部署场景。同一份代码可走三个通道（REST API、CLI、MCP 服务器）。企业预设通过一行配置即可启用 CSRF、审计日志、限流与安全响应头。无论工作流内部使用哪种原子件，中间件都按统一方式生效。
PactEngine 适用于需要组织治理的场景。D/T/R 寻址、约束包络、成本跟踪。作为每个代理和引擎所对接的信任平面门面，默认失败即拒绝：未知状态一律否决。
何时使用代理
Section titled “何时使用代理”代理位于治理线之下。它们借助大语言模型进行推理与行动，但每一个动作都会经由治理线之上的引擎进行验证。
Delegate 适用于单个在约束包络内自主推理的代理。采用 TAOD 循环：Think（规划）、Act（调用工具）、Observe（读取结果）、Decide（继续或停止）。治理闸门在每次动作执行前进行检查。
GovernedSupervisor 适用于多个在治理约束下协同工作的代理。七个子系统分别负责问责、预算、许可、级联、失职、绕过与审计。渐进式披露：Layer 1 仅需三行代码。
from kaizen_agents import GovernedSupervisor
# Layer 1：三行代码supervisor = GovernedSupervisor(agents=[agent_a, agent_b])result = await supervisor.run(task="Analyze Q4 revenue trends")何时下沉到原子件
Section titled “何时下沉到原子件”原子件是构建块。当引擎层无法表达特定模式时才使用它们。
WorkflowBuilder 适用于需要自定义拓扑的场景，超出 DataFlowEngine 自动生成节点的覆盖范围。可手动连接节点、添加条件分支、实现收敛式循环模式。
BaseAgent + Signature 适用于 Delegate 的 TAOD 循环不匹配你代理架构的场景。可构建具备独立推理循环、工具选择策略或输出结构的自定义代理。
直接使用 GovernanceEngine 适用于 PactEngine 门面未暴露所需约束求值能力的场景。这类需求并不多见；大多数项目使用 PactEngine 或 GovernedSupervisor 即可。
治理线在实务中的含义
Section titled “治理线在实务中的含义”治理线不仅仅是示意图中的一条线，而是代码中的架构边界。
线之上（引擎与原子件）：确定性。相同输入得到相同输出。不调用大语言模型，不存在判断或概率。一个约束包络每次求值结果相同，一次 DataFlow 查询返回结果相同，一次 Nexus 部署施加的中间件相同。
线之下（代理）：自主性。大语言模型进行推理，不同运行之间计划可能有所差异。但代理所执行的每一个动作都会穿过治理闸门回到线之上。非确定性被约束其中，而强制执行保持确定。
这就是治理线的价值：它将「可证明」与「必须信任」区分开。线之上可确定性地审计；线之下则由审计轨迹记录发生了什么，但推理本身是概率性的。整个栈的设计目标即在于：必须确定的部分（约束强制、预算上限、数据分级、审计轨迹）位于线之上，而从灵活性中获益的部分（规划、工具选择、自然语言交互）位于线之下。