给 Agent 的接入指南

这份词汇表给出什么证据，又不给出什么

entry.definition

这是唯一转述所标来源的字段。每条来源都带编辑检索日期，并链接到 Internet Archive 的固定快照，或者明确写出尚未确认快照。

provenance.editorial

这里逐个列出属于编辑判断的字段：边界、识别特征、适用与慎用、取舍、条件规则、查询前提、词条关系、实现说明和类型扩展。

rules[].strength

这是编辑给出的建议强度，同一条规则的 basis 字段写明它的依据。两者都不是已证实的事实，也不是硬性约束。

provenance.ordered

这个字段在词条文件和清单文件里永远是 false。清单是编辑选择，席位号表示位置，不表示名次。

本站没有做过用户研究，也没有做过完整的辅助技术认证。

你可以取用这些文件

路径里的 locale 取 zh 或 en，词条 ID 在两种语言里相同。每个 JSON 文件都带 X-Robots-Tag: noindex 和 Access-Control-Allow-Origin: *，不进站点地图，所以浏览器里的 Agent 也可以直接取用。本站不提供整站打包下载。

你这样读一个词条文件

外层是包装字段，entry 之下是目录里那一条词条的原样副本，一个字段都不删。

schemaVersion

包装格式的版本号。新增字段走小版本；改名或删除字段走大版本。

kind

文件种类，取 entry、list、entry-index 或 list-index。

page self alternates

这条词条的网页地址、本文件地址，以及两种语言的 JSON 地址。

site

目录版本号、词条总数，以及索引、查询接口、本指南和 llms.txt 的地址。

provenance.sourceBacked

唯一转述来源的那个字段路径。

provenance.editorial

这条词条上属于编辑判断的字段路径，逐个列出。

provenance.scope

证据范围说明：定义参考来源，示例、建议、关系和配方是编辑内容。

provenance.specimenNote

示例界面为原创虚构界面的声明。

provenance.editorialStatus

这条词条的编辑状态。

provenance.sources[]

每条来源一张引用卡片，卡片字段见下一段。

provenance.lists[]

这条词条占了哪些清单的哪些席位。词条不在任何清单里时，这个数组为空。

引用卡片里的 checkedAt 是编辑检索日期，它永远不是存档抓取日期。两者分成不同字段，你不必从一个推另一个。archive.status 有三种取值：

available

有已确认的固定快照。此时 archive.confirmed 为 true，archive.url 是快照地址，archive.capturedAt 是抓取时刻。

pending

已经提交过存档请求，但抓取尚未确认。

unconfirmed

没有已知的抓取。

后两种取值下，archive.confirmed 为 false，archive.url 和 archive.capturedAt 都是 null，只有按日期检索的 archive.lookupUrl 可用。提交过的存档任务不等于已完成的抓取，本站不会把它记成已确认。

你这样读一个清单文件

list 之下是目录里那一份清单的原样副本。seats 是已经解析好的席位，按席位号排序，每个席位直接给出对应词条的名称、类型、网页地址和 JSON 地址。

provenance.ordered provenance.selection

前者永远是 false，后者永远是 editorial。席位号是位置，不是名次。

provenance.seatOrigins

这里解释两种席位来源：来自计划 issue #1 清单账本的席位，和由本仓库编辑判断补上的席位。每个席位的 origin 指向其中之一。

provenance.nominalSize provenance.seatCount provenance.filled

依次是所有清单里最大的席位号、本清单的席位数，以及两者是否相等。没收满的清单保留空缺，不会补齐。

provenance.titleNote

这里说明标题里的“Top”和“趋势”是检索用语，不是采用率或排名统计。

seats[].reason

这句话说明席位覆盖什么，不说明它为什么排在这里。

你这样调用查询接口

查询接口用词法匹配加显式约束，没有语言模型，也没有向量检索。它回答哪些词条匹配、哪些因为缺少事实无法判断、哪些被排除以及原因。

方法是 POST，地址是 /api/query，用 lang 参数选 en 或 zh。省略 lang 时返回中文。请求体是一个 JSON 对象，只接受下面七个字段：

text

检索词，最长 1000 个字符。

type

词条类型，取 visual、layout、interaction、micro、principle、philosophy 或 anti。

intent

意图标识，最长 1000 个字符。

must

示例必须验证过的能力，取 keyboard 或 reduced_motion。

avoid

需要回避的做法，取 modal 或 motion。

facts

布尔事实对象，键取 measurable_progress、known_structure 或 short_field。

mode

取 select 或 audit，其中 audit 只返回反模式。

出现未列出的字段、不支持的取值或非布尔的事实值时，接口返回 400 和一句说明。请求体超过 16 KB 时返回 413。

curl -X POST 'https://designvocabulary.com/api/query?lang=en' \
  -H 'content-type: application/json' \
  -d '{"intent":"track-progress","facts":{"measurable_progress":true}}'

响应带 schemaVersion、locale、engine、mode、scope，以及 matched、unresolved、excluded 三个数组。engine 的值固定是 lexical-with-explicit-constraints。每个候选带 reasons 说明它为什么落在这一组，带 missingFacts 说明还缺哪些事实。

{
  "schemaVersion": "0.1.0",
  "locale": "en",
  "engine": "lexical-with-explicit-constraints",
  "mode": "select",
  "scope": "Capability checks cover the local specimen ...",
  "matched": [{ "id": "determinate-progress", "reasons": ["..."], "missingFacts": [] }],
  "unresolved": [],
  "excluded": []
}

本站有这些限制

• 检索是词法匹配加显式约束，没有语义检索。同义词表由人工维护，覆盖不全。
• 请求体上限 16 KB，超过这个大小返回 413。
• 代码里没有速率限制，也不需要 API key。本站不做遥测，不设账号，不收费。
• 本站不提供整站打包下载。完整覆盖的代价是按索引逐个取用词条文件和清单文件。
• 本仓库目前没有 LICENSE 文件，复用条款尚未确定。本页说明的是怎么取用，不是可以怎么再分发。

这些标识保持稳定

• 词条 ID 在两种语言、所有文件和查询结果里都相同，不会改。
• 包装格式的 schemaVersion 目前是 1.0.0。新增字段走小版本；改名或删除字段走大版本。
• 每条词条自己的 entry.version 记录这条词条内容的版本。
• 目录的 site.catalogSchemaVersion 记录目录格式的版本。

你可以从这些地方继续

• llms.txt：根目录发现文件，列出全部词条和清单在两种语言下的地址。
• entries/index.json：词条目录表，只含标识和链接。
• lists/index.json：清单目录表，只含标识和链接。
• GitHub：本站全部文件都由仓库里的 data/ 生成，生成脚本和检查脚本也在仓库里。
• issue #75：这套接入方式的设计讨论。