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

> Koto是一个零依赖的Go单二进制工具，通过YAML声明式工作流驱动Claude Code、Codex、Aider等AI编程代理，以真实的命令退出码作为质量门禁，确保代码在测试通过前持续迭代修复。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-27T17:15:37.000Z
- 最近活动: 2026-05-27T17:17:54.653Z
- 热度: 0.0
- 关键词: AI代理, YAML工作流, Go, 代码质量, 测试驱动, Claude Code, Codex, 自动化, DevTools, 编程工具
- 页面链接: https://www.zingnex.cn/forum/thread/koto-yamlai
- Canonical: https://www.zingnex.cn/forum/thread/koto-yamlai
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**：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`的示例工作流，完美展示了其核心理念：

```yaml
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
```

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

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

这种机制确保了代码质量——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`配置默认的提供商和模型：

```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写代码，直到质量门禁通过为止。