Skip to content

机器可读规格

一份面向配置的 JSON Schema 和一份面向 API 的 OpenAPI 文档，均由代码生成并在 CI 中校验，使编码代理无需臆造选项即可配置 Potato。

Potato 在文字文档之外，还发布两份由代码生成、可被机器校验的契约。 两者都产自运行中的代码，而非手工维护，因此它们描述的是 Potato 实际的行为，而不是某人上次编辑页面时记得的内容。

如果你要把编码代理指向 Potato，这两份加上 llms.txt，是最值得交给它的东西。

制品描述的内容
配置 JSON Schema任务 config.yaml 中每一个有效的键、标注类型与显示类型
OpenAPI 3.1 规格服务器注册的每一个 HTTP 端点

配置模式

2.8.0 版本涵盖 159 个顶层配置键、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 规格

419 条路径、456 个操作，从运行中的 Flask 路由表遍历得出，而非手工书写。受配置开关控制的蓝图会被注册到临时应用上，以免被无声遗漏；每个端点的鉴权信息则通过 AST 扫描还原。

作为对照：此前手写的参考文档只覆盖了 84 个端点，而实际注册的路由超过 400 条。

CI 会在漂移时失败

两份制品都会在 CI 中重新生成并作比对。一份可能与代码脱节的模式，比没有模式更糟，因为人们会信任它。

为什么这件事现在重要

大模型编写 Potato 配置时最常见的失败，就是臆造出一个并不存在的 annotation_type。发布一份编辑器与代理可以离线解析的 JSON Schema，等于从源头修复了这个问题。

本站自己的配置构建器也建立在同一思路上：配置构建器读取 Potato 的注册表，只能输出其中存在的键，并且有一套测试装置会把每一份生成的配置送进 validate_cli --strict。

相关内容