Koto：用YAML工作流驱动AI编程代理，直到质量门禁通过为止

章节 01

导读 / 主楼：Koto：用YAML工作流驱动AI编程代理，直到质量门禁通过为止

原作者与来源

原作者/维护者：te2wow
来源平台：GitHub
原始标题：koto
原始链接：https://github.com/te2wow/koto
发布时间：2026年5月27日

背景：AI编程代理的可靠性困境

AI编程代理（如Claude Code、Codex、Aider、Gemini CLI等）已经成为现代开发流程中的重要工具。它们能够快速生成代码、重构项目、修复Bug，显著提升开发效率。然而，这些代理在实际使用中存在几个明显的痛点：

首先，指令遗忘问题。即使你在提示词中详细说明了编码规范、测试要求和审查流程，AI代理在长时间运行后往往会逐渐偏离初始指令，特别是在多轮对话后。

其次，过早宣布成功。AI代理可能会在代码尚未通过测试、存在明显问题的情况下，就认为自己完成了任务。这种"幻觉式完成"会导致开发者需要反复检查AI的输出，增加了人工审核的负担。

第三，缺乏强制执行机制。仅仅在提示词中添加规则并不能真正保证这些规则被遵守。无论提示词多么详细，是否遵循仍然取决于模型的"意愿"，而非硬性约束。

这些问题的根源在于：AI代理的决策过程是内生的、不可预测的，而我们需要一种外生的、可验证的机制来确保流程的执行。

Koto的核心理念：用退出码锚定质量门禁

Koto的设计哲学可以用一句话概括：将决策从代理内部转移到工作流中，并用模型无法伪造的信号来锚定它——即真实命令的退出码。

测试要么通过，要么不通过。这是一个客观事实，不依赖于AI的自我评估。Koto正是基于这一简单而强大的思想构建的。

与另一个类似项目takt相比，Koto做出了三个关键的设计选择：

特性	takt	Koto
分发方式	TypeScript / npm	Go单二进制，零依赖
循环强制机制	AI审查者的判断	真实命令的退出码
提示词模型	分面提示（每步5个文件）	一步 = 一个提示词
提供商支持	SDK + CLI	仅CLI执行

Koto选择Go语言开发，确保了工具的可移植性和部署便利性——单个二进制文件，无需任何运行时依赖。选择仅通过CLI执行而非SDK集成，避免了因SDK版本变更而导致的兼容性问题。

工作流机制：有限状态机驱动的代理编排

Koto将工作流定义为有限状态机（Finite State Machine），每个步骤可以是以下三种类型之一：

Agent步骤

Agent步骤运行一个编程代理并传递提示词。代理的输出会被扫描以查找特定的转移标记（__NEXT:x__或__DONE__），从而决定下一个步骤。

这种设计允许代理在工作流中做出分支决策，但这些决策是受控的——代理只能从预定义的转移选项中选择，而不能随意跳转。

Gate步骤

Gate步骤是Koto的核心创新。它运行一个shell命令（如go test ./...、npm run lint、pytest等），并根据退出码决定流程走向：

退出码0：路由到on_pass指定的步骤（通常是COMPLETE）
非零退出码：路由到on_fail指定的步骤（通常是修复步骤），并将命令输出绑定到{{gate_output}}变量供后续使用

Gate步骤支持max_retries配置，当达到最大重试次数后仍未通过，工作流将ABORT。

Approve步骤

Approve步骤用于需要人工确认的场景（如部署到生产环境、执行破坏性操作等）。它会暂停执行，等待用户输入approve或reject。

实战示例：fix-until-green工作流

Koto内置了一个名为fix-until-green的示例工作流，完美展示了其核心理念：

name: fix-until-green
initial: implement
max_steps: 20
vars:
  test_cmd: "go test ./..."

steps:
  - name: implement
    type: agent
    edit: true
    persona: |
      Implement this task by editing the code:
      {{task}}
      When done, end your message with __NEXT:gate__
    rules:
      - on: "__NEXT:gate__"
        to: gate

  - name: gate
    type: gate
    run: "{{vars.test_cmd}}"
    max_retries: 5
    on_pass: COMPLETE
    on_fail: fix

  - name: fix
    type: agent
    edit: true
    persona: |
      The gate failed. Fix the code so it passes. Do not weaken the tests.
      Gate output:
      {{gate_output}}
      When done, end with __NEXT:gate__
    rules:
      - on: "__NEXT:gate__"
        to: gate

这个工作流的执行流程如下：

implement阶段：AI代理根据任务描述实现功能，完成后输出__NEXT:gate__转移到gate步骤
gate阶段：运行测试命令
- 如果测试通过（退出码0），工作流完成
- 如果测试失败，将失败输出传递给fix阶段
fix阶段：AI代理根据gate的输出修复代码，明确被告知"不要削弱测试"，完成后再次转移到gate步骤
循环往复，直到测试通过或达到最大步数限制

这种机制确保了代码质量——AI不能通过简单注释掉测试或降低测试标准来"欺骗"系统通过门禁。

模板变量与动态内容

Koto支持丰富的模板变量，使工作流能够动态适应不同场景：

变量	含义
`{{task}}`	传递给`koto run`的任务描述
`{{prev}}`	上一步骤的输出
`{{gate_output}}`	最后一次gate步骤的stdout/stderr组合
`{{iteration}}`	循环计数器
`{{vars.NAME}}`	工作流变量（可通过`--set NAME=value`覆盖）

这些变量使得工作流能够根据运行时的实际情况做出调整，例如根据迭代次数调整AI的修复策略，或根据gate输出来指导修复方向。

多代理支持与配置管理

Koto支持多种AI编程代理，包括：

Claude Code (claude)
OpenAI Codex (codex)
Aider (aider)
Gemini CLI (gemini)
GitHub Copilot (copilot)
Mock模式（用于测试）

用户可以通过~/.koto/config.yaml配置默认的提供商和模型：

provider: claude
model: ""
language: en

工作流的解析优先级为：./.koto/workflows/ → ~/.koto/workflows/ → 内置工作流（default、fix-until-green）。这种分层设计允许用户在项目级别覆盖全局配置，同时保留合理的默认值。

与现有工具的比较

Koto的出现填补了AI编程代理编排工具领域的一个空白。与类似的工具相比：

相对于takt：Koto采用Go单二进制分发，避免了Node.js/npm的依赖管理问题；使用命令退出码而非AI审查作为门禁机制，更加客观可靠；提示词模型更加简洁，一步对应一个提示词而非分散在多个文件中。

相对于直接使用AI代理：Koto提供了结构化的工作流编排、自动重试机制、运行日志记录和状态管理，这些都是裸用代理所不具备的。

相对于CI/CD流水线：Koto专注于开发阶段的代码生成和修复循环，与CI/CD形成互补——Koto确保代码在提交前通过本地测试，CI/CD确保集成后的质量。

实际应用场景

Koto特别适合以下场景：

TDD（测试驱动开发）工作流：先编写测试，然后让AI实现功能直到测试通过。Koto的gate机制完美契合TDD的红-绿-重构循环。

遗留代码重构：在重构复杂代码时，可以设置多重门禁（单元测试、集成测试、lint检查），确保重构不会破坏现有功能。

代码审查自动化：可以创建工作流让AI根据特定标准审查代码，并在发现问题时自动修复，直到所有检查通过。

多步骤代码生成：对于需要多个阶段完成的任务（如生成API端点、添加数据库迁移、更新文档），可以用Koto编排这些步骤，确保每个阶段都达到质量标准。

设计哲学与可靠性保障

Koto的可靠性特征建立在已发表的研究基础上，包括：

基于FSM的代理控制：有限状态机提供了清晰、可预测的执行流程，避免了代理行为的不可控发散
外部反馈审查循环：gate步骤的输出作为外部反馈，指导AI的修复行为
明确的停止条件：max_steps和max_retries提供了防止无限循环的安全网
结构化可观测性：每次运行都会创建日志目录.koto/runs/<id>/，便于事后分析和调试

这些设计选择使得Koto不仅是一个工具，更是一个可审计、可复现、可信赖的AI编程代理编排框架。

结语：让AI代理真正可靠

Koto代表了一种重要的范式转变：从信任AI代理的自我评估，到建立客观的、可验证的质量门禁。它承认AI代理的强大能力，同时也不回避其固有的不可靠性——并通过工程化的方式来解决这一问题。

对于希望将AI编程代理集成到严肃开发流程中的团队来说，Koto提供了一个坚实的基础。它不会取代AI代理，而是让它们变得更加可控、更加可靠、更加适合生产环境。

正如Koto的标语所说："Run AI coding agents through a YAML workflow, and don't stop until the gates are green."——让AI写代码，直到质量门禁通过为止。