跳到主要内容
AI教程

使用 Abide 在每次编辑时强制执行编码代理规则

了解如何安装 Abide，将其连接到 Claude Code、Codex 或 OpenCode，将仓库指令编译为可执行规则，自动检查编辑内容，审计现有代码，并校准生成的评分标准以实现可靠执行。

AI我搜编辑部阅读约 10 分钟
使用 Abide 在每次编辑时强制执行编码代理规则

Abide 的作用

Abide 强制执行普通代码检查器无法可靠评估的项目专属指令。这些指令可能位于 AGENTS.md 或 CLAUDE.md 等文件中，内容包括诸如使用 Yup，而不是手动验证、不要创建只有一个调用方的辅助函数，或绝不要向用户暴露原始错误等规则。

每次编辑或一个回合完成后，Abide 都会将相关规则和代码差异发送给TypeSafe 的 Jev 决策模型。Jev 返回概率，而不是自由格式的文本。如果该概率表明存在违规，Abide 会告知编码代理违反了哪条规则，并要求它在同一回合中修复代码。

Abide 编码规则强制执行

Jev 看到的是规则和差异，而不是代理的对话。这使 Abide 能够在漫长的编码会话中始终如一地执行相同的检查。根据代码仓库发布的回放基准测试，Jev 中的检查耗时约 300 毫秒；算上 Node 启动时间，完整钩子大约需要 1 秒。

主要功能

  • 自动编辑检查：规则可以在每次代码编辑后立即运行。
  • 回合级检查：需要完整任务差异的规则可以在回合结束时运行一次。
  • 代理集成：Abide 支持 Claude Code、Codex 和 OpenCode。
  • 代码仓库自有规则集：编译后的规则存储在易读且便于提交的 .abide/rubric.json 文件中。
  • 作用域规则：规则可以使用 glob 作用域，使不同问题适用于 API 路由、样式表或其他文件组。
  • 现有代码审计：Abide 可以像评判刚刚编写的文件一样评判现有文件。
  • 校准与调优：它可以根据近期 Git 历史测试规则、禁用无效规则，并帮助重写始终未触发的规则。
  • 失败放行钩子：缺少凭据、网络故障或钩子错误不会阻塞编码会话。
  • 不内置策略：Abide 强制执行从你自己的指令文件中派生的规则，而不是强加预定义规则集。

前置条件

你需要一个包含编码代理指令的代码仓库，以及至少一个受支持的代理：Claude Code、Codex 或 OpenCode。你还需要从 typesafe.ai 获取 TypeSafe API 密钥。或者，Abide 也可以通过 AI_GATEWAY_API_KEY 环境变量使用现有的 Vercel AI Gateway 密钥。

安装并配置 Abide

步骤 1：存储 API 密钥

运行登录命令，并在提示时粘贴你的 TypeSafe 密钥：

npx @coldtea/abide login

Abide 会将密钥存储在 ~/.abide/.env 中，并设置为仅所有者可访问。你也可以将凭据放在代码仓库根目录下的 .env.local 或 .env 中。凭据查找顺序为：先检查环境变量，然后检查代码仓库文件，最后检查 ~/.abide/.env。

如果你使用 Vercel AI Gateway，请设置 AI_GATEWAY_API_KEY，而不是 TypeSafe 密钥。凭据不接受通过命令行标志传入，也不会被记录。

步骤 2：安装代理钩子

在代码仓库中初始化 Abide：

npx @coldtea/abide init

不指定代理名称时，init 会安装到它找到的每个受支持代理中。你也可以明确指定一个集成：

npx @coldtea/abide init claude
npx @coldtea/abide init codex
npx @coldtea/abide init opencode
  • Claude Code：集成会添加到 ~/.claude/settings.json。
  • Codex：集成会添加到 ~/.codex/hooks.json。
  • OpenCode：插件会安装到 ~/.config/opencode/plugins/abide.js。

如果你希望进行代码仓库级安装，让团队成员在检出代码时一并获得，请添加 --project：

npx @coldtea/abide init claude --project

Codex 需要额外完成一次批准步骤。启动 Codex，输入 /hooks，然后接受 Abide 的四个钩子条目。对于每个新钩子，Codex 都会要求完成一次批准。

步骤 3：编译代码仓库规则

正常启动编码代理。在首次会话开始时，Abide 会检查指令文件是否发生变化。随后，代理会将适用的指令编译到 .abide/rubric.json 中，并报告发现的内容。

你也可以在开始新会话前进行编译：

abide compile

如果希望代码仓库中可强制执行的规则集对团队可见且可审查，请提交 .abide/rubric.json。每个判定都会标识该文件中的一条规则，并引用派生出该规则的源指令。

基本用法

让 Abide 自动检查代理编辑

初始化完成后，像往常一样启动 claude、codex 或 opencode。无需单独运行后台服务。假设某条指令规定 API 端点必须使用 Yup，且不得手动验证输入。如果代理编写了手动防护代码，Abide 可能会返回如下消息：

Abide：此编辑似乎违反了本仓库说明中的一条规则。
- 规则 "api-validation-uses-yup"，来自 ~/.codex/AGENTS.md 第 65 行：
  "编写 API 端点时，不要手动编写输入验证。
  使用 Yup（提供清晰的验证消息），并在 API 处理程序中提前返回"。
  (0.86)
请立即修复 apps/web/src/pages/api/logout.ts，然后继续执行任务。

代理会收到修复请求，并可在继续之前修复该违规。使用 OpenCode 时，编辑违规会附加到工具结果中。一次轮次级违规会在该轮次结束后生成一条后续消息。

手动检查未提交的更改

使用 check，以钩子相同的方式评估当前未提交的更改：

abide check

如果希望缩小检查范围，也可以提供路径：

abide check apps/web/src/pages/api/

审计现有代码

audit 命令会将现有文件视为刚刚创建的文件进行评估。在已建立的仓库中采用 Abide 时，这很有用：

abide audit src/

输出包括按规则汇总的结果，以及按文件组织的列表。README 报告称，在一个真实的 Next.js 应用中审计 33 个 API 路由大约耗时 12 秒，成本约为一美分，不过实际结果取决于仓库和规则。

查看规则活动

运行 report 命令，查看你的规则、哪些规则已触发，以及哪些规则从未触发：

abide report

如需机器可读的输出，请添加 --json。check、audit、bench 和 calibrate 也支持 JSON 输出。

了解规则时机和判定结果

每条编译后的规则都会在以下两个阶段之一运行：

  • 编辑阶段：在单次编辑后运行，并评估该代码块。
  • 轮次阶段：在轮次结束时运行一次，将完整差异与轮次开始时记录的快照进行比较。

对于无法仅从第一次编辑中回答的问题，轮次级评估非常重要，例如代理是否添加了用户未要求的功能。在轮次结束时，Abide 还会将编辑阶段规则应用于通过 shell 命令创建的更改。

判定结果分为以下概率区间：

  • 0.8 或更高：系统会要求代理修复违规。
  • 0.5 至低于 0.8：会显示提示，但不会要求代理修复。
  • 低于 0.5：不显示任何内容。

高级工作流

根据 Git 历史校准规则

措辞不佳的规则可能会在许多无关更改上得到中等分数，却始终无法产生有用结果。校准命令会根据仓库 Git 历史中近期真实的代码块，评估每条规则：

abide calibrate

Abide 在此过程中使用最近的 20 个代码块，并可以关闭表现不佳的规则。在团队中依赖新编译的评估标准之前，请先检查结果。

调整从未触发的规则

识别出无效规则后，使用 tune 让代理重写这些规则：

abide tune

由于每个评估标准条目都会引用其源指令，因此可以将存疑的判定结果追溯到产生该结果的措辞。改进底层指令通常会使相应检查更加清晰。

重放之前的代理会话

使用 replay，评估受支持代理中的历史会话：

abide replay claude
abide replay codex
abide replay opencode

这可以帮助你根据已经完成的工作评估评估标准，而不必等待未来的违规。

测量本地延迟和开销

运行基准测试命令，测量本机上的性能和成本：

abide bench

仓库报告称，检查其 13 条规则大约使用 1,000 到 1,600 个输入 token，每次检查成本约为 $0.00004 到 $0.00007，在 Jev 中耗时约 300 毫秒。这些数据是直接针对 TypeSafe 测量的，可能会有所变化，因此本地基准测试更适合作为你当前配置的参考。

使用作用域保持问题相关

.abide/rubric.json 中的规则可以包含基于 glob 的作用域。当某条指令仅适用于特定文件时，请使用这些作用域。例如，验证规则可以归属于 API 路由，而样式规则应限制在样式表中。缩小作用域可以减少无关判定，并使判定结果更易于理解。

隐私和失败行为

更改的代码行会使用你自己的密钥发送给 TypeSafe，并且每次调用都会请求零数据保留。README 声明，这些数据不会发送到由 Abide 运营的服务器。

Abide 的钩子经过设计，不会中断代理会话。钩子路径会成功退出，使用硬截止时间，并且只输出主机所需的内容。如果没有可用密钥或网络不可用，编辑会在不进行检查的情况下继续。未执行的检查会写入 .abide/events.jsonl，而 abide report 会将其计入统计结果。

卸载 Abide

从已安装 Abide 的每个代理中移除 Abide：

abide uninstall

若只移除一个集成，请指定代理名称：

abide uninstall codex

移除项目级安装时，请添加 --project。卸载只会移除 Abide 自身的条目。在你手动删除之前，它会保留评估标准文件和 ~/.abide/.env。

结语

Abide 将自然语言编写的仓库指令转化为贯穿整个 AI 编码会话运行的检查。安装适当的钩子，编译并审查 .abide/rubric.json，然后通过自动检查、审计、报告、校准和调优，确保规则持续有效。最终，它为传统代码检查工具无法表达的约定提供了一个轻量级的强制执行层。