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 Schema160 個配置鍵、61 種標註類型、24 種顯示類型，以及按類型的條件約束
OpenAPI 3.1449 條路徑、486 個操作
llms.txt經過整理的文件索引

按類型的條件約束比鍵列表更重要：正是它們能在伺服器之前，告訴代理一個 constant_sum 方案需要 labels。

讓規格由程式碼生成

如果你是這個工具的維護者而非使用者，那麼讓這一切成立的關鍵性質是：模式是由伺服器用於校驗的同一批註冊表生成的，並且一旦漂移，CI 就會失敗。

一份手工維護的模式比沒有更糟。它會被信任，而在有人新增了一種類型卻沒更新它的第一時間，它就是錯的。

我們在本站是怎麼做的

本站自己的配置構建器也是這樣構建的。它把 Potato 的登錄檔讀入一份提交進倉庫的規格檔案，按其對映每一個欄位，並丟棄登錄檔中不存在的任何內容。隨後有一套測試裝置，會把每一份生成的配置——每種標註類型一份，外加每一個起步模板——都送進 validate_cli --strict。

這套裝置抓出了真實存在的缺陷：一個並不存在的標註類型、三個缺少必填欄位的方案，以及一個重複的 YAML 鍵，後者會悄悄丟棄已授權使用者列表。僅靠閱讀輸出，這些都看不出來。

延伸閱讀