Skip to content

如何让编码代理来写你的标注配置

大模型编写配置时最常见的失败，是臆造出一个并不存在的选项。一份 JSON Schema 加一个校验器，能把这种运行期意外变成编辑器里的报错。

大模型编写标注配置时最常见的失败，是臆造出一个并不存在的选项。 模型产出了看似合理的内容，服务器要么忽略这个未知的键、要么拒绝整个文件，而错误会在几分钟后以"没人配置过的行为"这种形式浮现。一份机器可读的模式，把这个失败提前到了书写的那一刻。

加上模式声明行

在配置文件顶部加一行：

yaml
# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json

这会在 VS Code、JetBrains 系列 IDE、Zed 与 Helix 中开启实时校验。一个臆造出来的 annotation_type 会在你输入时被标下划线，而补全会给出真实存在的那些。

Potato 在每一份示例配置中都带上这一行，其配置构建器在每次下载时也会写入。

在 CI 中校验

bash
check-jsonschema --schemafile \
  https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json \
  config.yaml

这份 JSON Schema 对未知的键刻意保持宽松，因为服务器对它们只给出警告，而更严格的模式会拒绝掉本可工作的配置。因此请把它与项目自带的校验器配合使用，后者会报告这些键：

bash
python -m potato.validate_cli --strict config.yaml

--strict 会把未知的键视为致命错误。正是它能抓出像 annotaton_type 这样的拼写错误，而宽松的模式会默默接受。

把规格交给代理

如果你要把 Claude Code、Codex 或 Cursor 指向某个工具，生成出来的规格比散文式文档更有价值，因为它们描述的是代码今天的实际行为，而不是某人记得的内容：

制品覆盖内容
配置 JSON Schema159 个配置键、61 种标注类型、24 种显示类型，以及按类型的条件约束
OpenAPI 3.1419 条路径、456 个操作
llms.txt经过整理的文档索引

按类型的条件约束比键列表更重要：正是它们能在服务器之前，告诉代理一个 constant_sum 方案需要 labels。

让规格由代码生成

如果你是这个工具的维护者而非使用者，那么让这一切成立的关键性质是：模式是由服务器用于校验的同一批注册表生成的，并且一旦漂移，CI 就会失败。

一份手工维护的模式比没有更糟。它会被信任，而在有人新增了一种类型却没更新它的第一时间，它就是错的。

我们在本站是怎么做的

本站自己的配置构建器也是这样构建的。它把 Potato 的注册表读入一份提交进仓库的规格文件，按其映射每一个字段，并丢弃注册表中不存在的任何内容。随后有一套测试装置，会把每一份生成的配置——每种标注类型一份，外加每一个起步模板——都送进 validate_cli --strict。

这套装置抓出了真实存在的缺陷：一个并不存在的标注类型、三个缺少必填字段的方案，以及一个重复的 YAML 键，后者会悄悄丢弃已授权用户列表。仅靠阅读输出，这些都看不出来。

延伸阅读