Skip to content

機器可讀規格

一份面向配置的 JSON Schema 和一份面向 API 的 OpenAPI 文件，均由程式碼生成並在 CI 中校驗，使編碼代理無需臆造選項即可配置 Potato。

Potato 在文字文件之外，還發布兩份由程式碼生成、可被機器校驗的契約。 兩者都產自執行中的程式碼，而非手工維護，因此它們描述的是 Potato 實際的行為，而不是某人上次編輯頁面時記得的內容。

如果你要把編碼代理指向 Potato，這兩份加上 llms.txt，是最值得交給它的東西。

製品描述的內容
配置 JSON Schema任務 config.yaml 中每一個有效的鍵、標註類型與顯示類型
OpenAPI 3.1 規格伺服器註冊的每一個 HTTP 端點

配置模式

2.9.0 版本涵蓋 160 個頂層配置鍵、61 種標註類型與 24 種顯示類型，並包含按類型的條件約束，因此一個 constant_sum 方案會在伺服器拒絕它之前，就被告知需要 labels。

把下面這行模式宣告放在任意配置檔案的第一行，編輯器便會在你輸入時即時校驗，VS Code、JetBrains、Zed 與 Helix 均可：

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

Potato 倉庫中隨附的每一份配置都帶有它，配置構建器在每次下載時也會寫入。

在 CI 中：

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

或使用本地校驗器，它還會額外報告未知的鍵：

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

API 規格

449 條路徑、486 個操作，從執行中的 Flask 路由表遍歷得出，而非手工書寫。受配置開關控制的藍圖會被註冊到臨時應用上，以免被無聲遺漏；每個端點的鑑權資訊則通過 AST 掃描還原。

作為對照：此前手寫的參考文件只覆蓋了 84 個端點，而實際註冊的路由超過 400 條。

CI 會在漂移時失敗

兩份製品都會在 CI 中重新生成並作比對。一份可能與程式碼脫節的模式，比沒有模式更糟，因為人們會信任它。

為什麼這件事現在重要

大模型編寫 Potato 配置時最常見的失敗，就是臆造出一個並不存在的 annotation_type。釋出一份編輯器與代理可以離線解析的 JSON Schema，等於從源頭修復了這個問題。

本站自己的配置構建器也建立在同一思路上：配置構建器讀取 Potato 的登錄檔，只能輸出其中存在的鍵，並且有一套測試裝置會把每一份生成的配置送進 validate_cli --strict。

相關內容