TeaQL Agent Kit：用可检查的领域模型约束编码代理的随机性
非确定性人工智能的确定性执行。它提供任务、提示、指南和报告，用于观察编码代理在使用基于 TEAQL 的业务软件时的行为方式。
秒懂
- 它是什么？
- TeaQL Agent Kit 是一个面向编码代理的模型中介 harness，它把需求到代码的流程拆成可检查的 KSML 模型、确定性评估、生成契约和证据链。本文基于仓库文档分析它的机制、运行方式和适用边界。
- 适合谁用？
- TeaQL Agent Kit 适合那些需要审计和复现的团队，尤其是业务软件中操作必须携带身份、意图和审计理由的场景。它不适合追求快速原型或依赖代理自由发挥的团队，因为模型优先的流程强制要求先写 KSML 模型，再走评估和生成，这增加了前期成本。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是代理的不可预测，而不是消除不可预测
编码代理从需求直接跳到代码，这个循环里模型、持久化表面和业务逻辑都在同一时刻被代理发明出来。TeaQL Agent Kit 把这个过程拆开，在意图和实现之间放一个可检查的领域模型。文档用一句话概括目标：不是确定性 AI，而是围绕非确定性 AI 的确定性结构。它针对的读者是那些需要审计软件生产过程的团队，尤其是业务软件中每个写操作都要有理由、每个读操作都要声明用途的场景。代理仍然可能犯错，但错误发生在更小的步骤里，每一步都有迹可循。
五段式 harness：从需求到证据的固定路径
仓库把流程画成一条自上而下的链路。需求先交给代理，代理产出可检查的 KSML 模型，模型进入确定性评估，评估把错误和修复指导返回给代理，同时把验证过的模型交给生成器，生成器产出类型化契约和模型感知辅助，代理在这个契约内实现，最后编译、测试、运行时和政策检查把结果送回代理或模型。文档强调这不是一个代码生成 Skill，而是一个参考实现。关键点是反馈回路：实现缺陷回到代理，模型缺陷回到模型，人工审查者可以异步地给模型和实现提意见。这条路径把代理的角色从发明者改成执行者，它不再同时决定契约、持久化和业务逻辑。
KSML 模型和确定性评估：代理不必背规则
KSML 是仓库引入的中间表示，它把业务意图保存成可检查的工件，代理、工具和人都能查看和修改。评估服务返回错误、警告、建议和当前修复指导，而不是让代理记住一整套规则目录。这个设计的代价是代理依赖外部评估服务，如果服务不可用，流程就卡住。文档没有给出评估服务的内部实现，只说明它存在且是确定性的。golden-example.xml 提供了一个紧凑的语法示例，避免代理加载完整规则目录。这看起来像是一个权衡：用外部服务换规则记忆，但引入了网络和服务的假设。
运行时治理：政策绑定在执行上，而不是提示词里
开发时流程控制怎么做对的事，运行时治理控制做正确的事。文档列出五条：操作携带身份和意图，读声明用途和注释，写声明审计理由，外部能力显式授予，类型化实体图约束变更。这些约束不选择业务政策，而是让应用动作变得有上下文、有边界、可观察、可审计。政策随执行流动，而不是停留在提示词建议里。这意味着生成的 API 本身就带有这些语义，代理无法绕过。但这也意味着运行时依赖 TeaQL 的库，生成的应用不能脱离这个框架独立运行。
运行方式：workspace 源选择和证据文件
仓库提供两个示例配置文件：teaql-workspace.workspace.yaml 和 teaql-workspace.release.yaml。前者把 runtimeSource 设为 workspace，解析七个运行时仓库并记录精确提交和脏状态，用于修改运行时的时候。后者设为 release，要求包版本并拒绝路径覆盖，用于发布包回归。配置文件用 JSON 兼容的 YAML，这样验证器没有第三方依赖。命令是 ./tools/teaql_workspace.py apply --config teaql-workspace.yaml --workspace /path/to/generated-application 和 ./tools/teaql_workspace.py verify --config teaql-workspace.yaml。apply 会在应用工作区写入 .teaql/runtime-source-evidence.json。原生包管理器的覆盖（Maven reactor、Cargo patch、Go workspace、npm workspace、Swift package edit、.NET project reference、Python editable install）仍然归工作区所有，harness 在那些命令运行前验证选定的仓库，生成器不创建也不猜测这些覆盖。
证据链和完成标准：什么算做完
work-complete.md 定义了代理报告完成前必须提供的证据。评估、生成的指导、政策检查、编译、测试和运行时结果形成一条从需求到应用的可追溯证据链。这个设计让完成不再是代理的主观判断，而是有具体产物的状态。文档没有列出证据的具体格式，只说必须包含这些类别。这给使用者的启示是：如果团队已经有自己的完成定义，需要对齐这两套标准。证据链的粒度取决于评估服务和生成器的输出，仓库本身不生成证据，它只是编排这些步骤。
局限性和替代方案：不是所有项目都该用
文档明确说约束不会让代理变得无误，它只是让动作更小、更可观察、更易审查。这是诚实的边界。TeaQL Agent Kit 适合业务软件，尤其是那些需要审计和治理的项目。如果你的项目是探索性的、需求频繁变化的、或者不要求写操作带审计理由，这个 harness 会显得笨重。替代方案是传统的 prompt-to-code 循环，代理直接生成代码和测试，没有中间模型。那种方式速度快，但契约和业务逻辑由代理即兴发明，审查成本转移到代码 review 上。TeaQL 把审查成本前置到模型阶段，用确定性评估代替人工检查规则。两种方式没有绝对优劣，取决于你更愿意在哪个阶段付出成本。
维护成本和许可证
仓库是 MIT 许可证，这意味着你可以自由使用和修改，但需要保留版权声明。维护成本来自几个方面：运行时仓库有七个，runtimeSource 为 workspace 时你需要跟踪它们的提交和脏状态，这本身就是一个维护负担。生成器不创建原生包管理器的覆盖，所以你必须自己维护 Maven、Cargo、Go 等配置。评估服务是外部依赖，它的可用性和版本变化会影响你的流程。文档提到版本化客户端和工具链绑定，但没有给出具体的升级路径。如果 TeaQL 团队停止维护评估服务，你的流程会失去核心反馈环。这是一个单点依赖，采用前需要评估。
编辑结论
TeaQL Agent Kit 适合那些需要审计和复现的团队，尤其是业务软件中操作必须携带身份、意图和审计理由的场景。它不适合追求快速原型或依赖代理自由发挥的团队，因为模型优先的流程强制要求先写 KSML 模型，再走评估和生成，这增加了前期成本。采用前应验证三件事：一是 teaql-workspace.yaml 中 runtimeSource 的选值是否符合你的发布流程，二是评估服务返回的修复指导是否覆盖你的领域规则，三是生成契约在目标语言中的编译和运行证据是否完整。仓库文档明确说约束不会让代理变得无误，它只是让动作更小、更可观察、更易审查。这个判断应当作为你决定是否引入的基准。
社区笔记