简而言之: 循环是一个执行单一任务的智能体进程,它在你控制的环境中接收明确定义的输入并产生明确定义的输出。例如,文档同步循环会将某个 CLI 的 README 与其代码进行比较,并在两者出现偏离时创建拉取请求。但循环是否可靠,取决于你能否信任它,因此在构建循环之前,你需要先建立一项值得信赖的检查。在这个三篇系列的第一篇中,你将构建这项检查:通过一项测试和一个 Tessl 验证器检查 CLI 文档的每一次变更。你会看到它在应该失败时失败、在应该通过时通过;到最后,即使尚未将它放入循环中,你也会拥有一项本身就很实用的检查。

问题:智能体交付代码的速度太快,没人能及时处理好围绕代码产生的那些琐事。

你的编码智能体可以在几分钟内交付一项功能,但围绕它的琐事却是另一回事:文档逐渐偏离,测试时好时坏,智能体指令也会过时,而且这些情况整周都在发生。谁能跟上这一切?如果你不确定,那么你已经遇到了本系列要解决的问题。

全靠手动处理无法规模化。你可以时不时让智能体“整理一下”,但如果无法检查它的工作,你只知道它运行过,却不知道它是否真正修复了什么。还有一种更好的方法,叫作循环,本系列将带你逐步构建一个循环。

你将从中获得什么: 在本文中,你将为一个保持 CLI 文档与代码同步的循环构建检查机制。它会对每次变更执行两项检查:一项确定性测试,即运行 CLI 并将其命令与 README 进行比较的标准 Node.js 测试,用于检查脚本能够判断的内容;以及一个 Tessl 验证器,即一条用自然语言编写、由 LLM 对照检查每次变更的规则,用于处理需要判断的内容。这意味着,遗漏文档更新的变更会在你仍处于当前分支时被发现,包括那些测试无法察觉的问题。更棒的是,每个循环都需要这样的检查,因此一旦构建完成,第二部分中的循环就有了可靠的基础。

什么是循环?

在 Tessl 中,循环是一个执行单一任务的智能体进程。它接收明确定义的输入,在容器中运行智能体,并且只授予该任务所需的访问权限和密钥,最后产生明确定义的输出。例如,实现循环会从 Linear 工单中获取规范,运行智能体来构建代码,然后创建拉取请求。随后,审查循环可以检查该拉取请求。把这样的循环串联起来,就形成了工作流。在这里,你将构建一个循环:让 CLI 的 README 与其代码保持同步。本系列完全以实践为主,因此如果你想先了解全貌, 反馈循环工程 介绍了不同类型的循环及其重要性,而 上下文驱动的工厂 则展示了它们如何组合成一个工厂。

检查输出才是最重要的。调度智能体很容易,真正的工作是信任它所做的事情;正是这一点让循环值得运行,而不只是又一个定时任务。

文档偏离非常适合作为第一个循环,因为任务规模小、偏离容易发现,而且结果可以检查。这也正是我们建议的起点:选择一个范围明确的小问题,先手动运行循环,再考虑按计划自动运行。构建完这个循环后,Tessl 文档中还有 更多循环示例 可供你接着尝试。

你将构建什么

在整个系列中,你将构建一个使 CLI 的 README 与其代码保持同步的循环:它会阻止遗漏文档更新的变更,并创建拉取请求来修复任何漏网的偏离。整个过程分为三个部分:

  • 第一部分:检查每一次变更(本文)。 每次变更都必须通过两项检查:一项将 CLI 命令与 README 进行比较的测试,以及一个 Tessl 验证器,用于检查每当命令发生变化时 README 是否也得到更新。
  • 第二部分:每周巡检。 一个由你亲自编写的循环,按计划比较文档与代码,并在两者出现偏离时创建拉取请求。
  • 第三部分:闭合循环。 将检查转化为门禁:在每个拉取请求上运行检查并阻止未通过的变更,然后利用巡检发现的问题进一步强化门禁。

一旦将它作为门禁强制执行,就能阻止新的偏离。巡检会捕获所有绕过门禁的问题,而每一次捕获都会告诉你应在何处收紧门禁。本文将构建图中的第 1 和第 2 个方框,也就是这套检查机制。

前置条件

为了顺利运行所有内容,开始之前你需要准备以下各项。

  • Node.js 和 git。 示例 CLI 没有任何依赖项。
  • Tessl CLI 和一个免费的 Tessl 账户。 使用以下命令安装 CLI: curl -fsSL https://get.tessl.io | sh,然后运行 tessl login。如果你还没有账户,可以在登录时免费注册一个。

如果下文中的任何内容未按预期运行, 验证器文档 中提供了更多详细信息,可帮助你继续操作。

第 1 步:设置示例应用

你需要一个可供检查的对象,因此本系列使用一个名为 tally的微型示例 CLI,你将首先构建它。它没有任何特别之处:只有两个命令和一个 README,刚好足以产生偏离。看到检查正常工作后,你可以(也应该)将同样的设置应用到真实项目中。

设置一个工作目录并跟着操作。在文件夹中创建三个文件。首先是 CLI 本身,它位于 bin/tally.js:

1#!/usr/bin/env node
2
3// Every command the CLI supports, with the description shown in --help
4const commands = {
5  add: 'Add a number to the running total',
6  reset: 'Set the total back to zero',
7};
8
9const [cmd] = process.argv.slice(2);
10
11if (!cmd || cmd === '--help') {
12  // Print usage and the command list
13  console.log('Usage: tally <command>\n\nCommands:');
14  for (const [name, desc] of Object.entries(commands)) console.log(`  ${name.padEnd(8)}${desc}`);
15} else if (!commands[cmd]) {
16  // Reject anything that isn't a known command
17  console.error(`Unknown command: ${cmd}. Run tally --help to see commands.`);
18  process.exit(1);
19}

接下来是在 README.md中描述它的文档。留意最后一行,因为它马上就会成为一个问题:

1# tally
2A tiny CLI that keeps a running total.
3
4## Commands
5- `tally add` adds a number to the running total
6- `tally reset` sets the total back to zero

最后,添加一个 package.json,这样 npm test 就有可运行的内容:

1{ "name": "tally", "type": "module", "bin": { "tally": "bin/tally.js" }, "scripts": { "test": "node --test" } }

将所有内容提交到名为 main的分支,因为稍后你将以它为基准比较变更:

1# Create the repo and commit the three files
2git init && git add -A && git commit -m "start"
3
4# Make sure the branch is called main
5git branch -M main

第 2 步:设置 Tessl

你将在第 4 步编写的验证器通过 Tessl CLI 运行,因此请在仓库中设置 Tessl:

1# Set up Tessl for your coding agents
2tessl init
3
4# Commit the new files
5git add -A && git commit -m "Set up Tessl"

tessl init 会针对你使用的编码智能体完成设置,因此看到 AGENTS.md, CLAUDE.md 和几个 MCP 配置文件出现时不必惊讶。

第 3 步:从确定性检查开始

在动用智能体之前,先检查普通脚本能够检查的所有内容。脚本比 LLM 更快、成本更低,而且每次都会给出相同的答案。“文档中列出的每个命令是否确实存在?”是一个非是即否的问题,因此应该放在测试中。Tessl 自己的 验证器指南 给出了一条简单的经验法则:如果脚本能够检查,就编写测试;如果需要判断,例如某个命令的描述是否仍与其实际行为一致,就编写验证器。

添加 test/docs.test.js。它会运行 CLI 的 --help,然后将其中列出的命令与 README 中的命令进行双向比较,这样既能发现已消失的命令,也能发现一直没人抽空写入文档的命令:

1import { test } from 'node:test';
2import assert from 'node:assert/strict';
3import { readFileSync } from 'node:fs';
4import { execFileSync } from 'node:child_process';
5
6// Commands the README mentions, written as `tally <command>`
7const readme = readFileSync('README.md', 'utf8');
8const documented = [...new Set([...readme.matchAll(/`tally ([a-z-]+)/g)].map((m) => m[1]))];
9
10// Commands the CLI actually lists when you run --help
11const help = execFileSync('node', ['bin/tally.js', '--help'], { encoding: 'utf8' });
12const actual = [...help.matchAll(/^ {2}([a-z-]+)\s/gm)].map((m) => m[1]);
13
14// Sanity check: the README parsing found something
15test('README documents at least one command', () => assert.ok(documented.length > 0));
16
17// No stale docs: nothing in the README that the CLI lacks
18test('every documented command exists in the CLI', () =>
19  assert.deepEqual(documented.filter((c) => !actual.includes(c)), []));
20
21// No missing docs: nothing in the CLI that the README lacks
22test('every CLI command is documented', () =>
23  assert.deepEqual(actual.filter((c) => !documented.includes(c)), []));

运行 npm test ,你应该会看到所有三个测试都通过。请注意,该测试会运行 CLI 并读取其真实的 --help 输出,而不是相信另一份命令说明。这样一来,README 核对的是用户实际看到的内容,而不是另一份可能同样已经过时的说明。

测试无法发现的问题

这个测试无法判断行为。它知道 reset 存在,但完全不知道“将总数重置为零”是否仍然符合 reset 的实际行为。为此,你需要能够阅读和推理的工具,比如 LLM;这正是 Tessl 验证器的用武之地。

第 4 步:添加判断检查

验证器是一条以纯文本编写、存放在仓库中的规则。每次运行时,LLM 评判器都会根据这条规则检查变更,并返回通过或失败,因此它就像是针对脚本无法表达的规则所做的测试。 验证器发布博文 介绍了相关背景,有兴趣可以阅读;这里你将亲自编写一个验证器。它与第 3 步中的测试共同构成两部分检查。

你的规则很简单:如果某项变更涉及一个命令,那么同一项变更也必须更新 README。添加 verifiers/cli-docs-sync.json:

1{
2  "name": "CLI changes update the README",
3  "instruction": "When a change adds, removes, renames or changes the behavior of a tally command, the same change updates README.md so it still describes what the command actually does.",
4  "relevant_when": "The diff changes a command name, its description, or what a command does in bin/tally.js.",
5  "context": "README.md is the only user documentation for the tally CLI; users and agents rely on it.",
6  "scope": "diff",
7  "scope_reason": "Synchronization rule: the README update must ship in the same change as the CLI change.",
8  "checklist": [
9    { "name": "readme-updated", "rule": "If the diff changes a command's name or behavior in bin/tally.js, the diff also changes README.md to describe it. Not applicable if no command changed." },
10    { "name": "readme-matches-behavior", "rule": "For each command the diff changes, README.md's description says what the code in bin/tally.js now does. A README edit that mentions the command but still describes the old behavior fails. Not applicable if no command changed." }
11  ]
12}

重要部分:

  • relevant_when ——验证器何时适用。规则要具体,这样评判器只检查涉及命令的变更。“差异更改了 bin/tally.js 中的一个命令”足够具体;“差异更改了 JavaScript”则会让评判器因每次重构和拼写错误修复而启动。
  • scope ——评判器检查什么。使用 file时,它会逐个文件进行评判,这适合“每个 API 路由都使用共享响应辅助函数”这样的规则。使用 diff时,它会将变更作为一个整体进行评判。这条规则关注的是两个文件是否同步更改,因此需要使用 diff。 验证器文档 介绍了其他选项。

第二个检查项正是需要判断力的地方:脚本可以判断 README 是否发生了更改,但只有能够同时读取这两个文件的工具,才能判断 README 现在的内容是否正确。

然后,通过添加一个 代码块来告诉 Tessl 验证器涵盖哪些文件 verify 代码块来 tessl.json:

1"verify": {
2  "groups": {
3    "docs-sync": {
4      "path": "verifiers/cli-docs-sync.json",
5      "level": "warn",
6      "include": ["bin/**/*.js", "README.md"]
7    }
8  }
9}

重要部分:

  • level - warn 只报告发现的问题,不会阻止任何操作。等你信任它之后,你会将其切换为 error 。
  • include ——此验证器涵盖的文件。它需要同时涵盖 CLI 和 README,以便评判器看到一项变更的两个方面。

对验证器运行 lint 以确保其有效,然后提交这两个文件:

1# Check the verifier file is valid
2tessl change verify lint verifiers/cli-docs-sync.json
3
4# Commit the verifier and the tessl.json change
5git add -A && git commit -m "Add docs-sync verifier"

看看它如何失败

一个你只见过它通过的检查并不能证明任何事情,所以我们来破坏一些测试无法察觉的东西。在一个新分支上,更改 reset 的行为:它现在不再归零,而是恢复上次保存的总数。在 中更新其说明 bin/tally.js,但完全不要改动 README:

1# Start a throwaway branch for the experiment
2git checkout -b drift-test
3
4# Change what reset does, without touching the README
5sed -i.bak 's/Set the total back to zero/Restore the last saved total/' bin/tally.js && rm bin/tally.js.bak
6git commit -am "reset restores the last saved total"
7
8# The test still passes: every command name still matches
9npm test
10
11# Preview what the verifier will judge, then run it for real
12tessl change verify --base main --dry-run --show-files
13tessl change verify --base main

npm test 仍然会通过,因为每个命令名称依然匹配。只有验证器能注意到这一点。

试运行是个很实用的习惯:在你产生任何费用之前,它会准确告诉你哪些内容将被评判,以及会调用评判器多少次。这里它计划只调用一次。随后,实际运行失败,评判器会准确告诉你原因。你会看到你的 docs-sync#cli-docs-sync 验证器被标记为失败,并针对这项变更破坏的每个检查项给出一条发现。这些发现由 LLM 撰写,因此每次运行的措辞都会有所不同,但大意会是: 中的说明 reset 已更改 bin/tally.js,而 README 仍称它会将总数归零。

输出中的几处内容第一次看到时可能会觉得有点奇怪。摘要报告的是警告而不是错误,因为该组的 level 是 warn,以及一个失败的 warn 检查不会阻止拉取请求。它还会显示“0 个匹配文件”,这听起来令人担忧,但其实并非如此: diff 验证器会整体评判这项变更,而不是逐个文件进行评判。

看它通过

现在,在同一个分支上更新 README,然后再次运行:

1# Bring the README in line with the new behavior
2sed -i.bak 's/sets the total back to zero/restores the last saved total/' README.md && rm README.md.bak
3git commit -am "docs: update reset description"
4
5# Both checks should pass now
6tessl change verify --base main
7npm test

这一次,验证器通过了,测试也通过了。现在你知道该检查会在应该失败时失败、在应该通过时通过,而这才是真正信任它的唯一方式。继续之前,先整理一下:

1git checkout main && git branch -D drift-test

这项检查有一个盲点,而且这是有意为之。它检查的是变更,因此无法发现仓库中已经存在的偏离,也无法阻止从未经过它的变更。而这正是循环要解决的问题。

接下来做什么

你已经构建了一项检查:对脚本能够检查的内容使用确定性测试,对需要判断的内容使用验证器。你已经看到它捕捉到测试遗漏的偏离,也看到 README 修复后它不再发出警告,因此你知道它值得信任。即使还没有循环,也值得保留它:把测试和验证器复制到一个你关心的项目中,并将相关路径指向你自己的代码和文档。 include 路径指向你自己的代码和文档。

在第 2 部分中,你将编写第一个循环来弥补这项检查的盲点:每周扫描整个仓库,对照代码检查文档,并在两者出现偏离时创建拉取请求。