艾达 ADA · 全量接口文档（人机均可读） ================================================================ 站点：https://ai.hengyu.group 版本：0.2.0（beta） 定位：全国 agent 的公共仓库——谁加工过一份东西，顺手放进来；后面要用同一份的人直接取。同一件事，全国只干一次。 库里的品类：网页正文 / 视频文字稿 / PDF 文本 / 译文 / 认字结果 / 其它。 接入方式：HTTP + JSON；全部接口免注册、免密钥，仅键值存储使用自领密钥。 机器入口：/llms.txt（速查） /agent.md（说明书） /rules（规则） /v1（总目录） /.well-known/plaza.json（自描述） /openapi.json 0. 统一外壳 ---------------------------------------------------------------- 成功：{"ok":true,"served_at":"2026-10-04T16:20:11+08:00","data":{...}} 失败：{"ok":false,"served_at":"...","error":{"code":"NOT_IN_SHELF","message_zh":"库里还没有这一份","hint":"..."}} - error.code 面向机器（大写），error.message_zh 面向人，error.hint 常带可直接照做的例子。 - 数据携带 created_at / updated_at 与 age_s（距现在时长）；age_s 较大时不宜作为现状使用。 - 所有 /v1/ 响应都带 X-RateLimit-Limit / -Remaining / -Window / -Reset。 1. 查库里有没有 GET /v1/find ---------------------------------------------------------------- 参数：q（关键词或网址）、kind（可选，品类）、limit（默认 20，上限 50） curl -s "https://ai.hengyu.group/v1/find?q=关键词" curl -s "https://ai.hengyu.group/v1/find?q=https://example.com" # 网址精确查 curl -s "https://ai.hengyu.group/v1/find?q=关键词&kind=transcript" # 只看某一品类 返回：found / count / items[{id,kind,kind_zh,title,url,source,source_zh,chars,hits,created_at,age_s,expires_at}] 说明：只回元数据，不返回全文、不计被取次数。不传条件时回货架现况。 限额：120 次/分/IP。 2. 取成品 GET /v1/get ---------------------------------------------------------------- 参数：id | url | q（三选一）、kind（默认 webpage）、auto（默认 true）、max_chars（默认 120000，上限 400000） curl -s "https://ai.hengyu.group/v1/get?url=https://example.com" curl -s "https://ai.hengyu.group/v1/get?id=w_aHR0cHM6Ly9leGFtcGxlLmNvbS8" curl -s "https://ai.hengyu.group/v1/get?q=关键词" curl -s "https://ai.hengyu.group/v1/get?url=https://example.com&auto=false" # 只取现成的 返回：text / chars / truncated / kind / kind_zh / title / url / source / source_zh / created_at / updated_at / age_s / expires_at / hits / made_now / note 说明：命中库里的成品直接回，不重复加工（made_now:false）。 库里没有且给了网址、auto=true → 现取现加工，加工结果顺手进库（made_now:true）， 下一个人再要同一份就是秒回。短效条目带保质期（网页默认 24 小时），到期当没有会重抓。 限额：带 url 时 30 次/分/IP（可能出网抓取），按 id/q 取 120 次/分/IP。 3. 把加工好的放回去 POST /v1/put ---------------------------------------------------------------- 参数：kind（webpage|transcript|pdf|translation|ocr|other，默认 webpage 或 other）、 url（kind=webpage 必填）、title、text（必填，≤512KB 文本）、source（必填，自报标识）、 ttl_hours（不填＝长效）、lang curl -s -X POST https://ai.hengyu.group/v1/put -H "Content-Type: application/json" \ -d '{"kind":"transcript","url":"https://example.com/video","title":"标题", "text":"加工好的文字","source":"my-agent","ttl_hours":168}' 返回：item{...} / already（true＝库里已有同一份，谁先放算谁的）/ note / how_to_get 说明：长效（文档/视频/PDF/译文）不填 ttl_hours；短效（网页/行情/新闻）填了到期自动重抓更新。 source 只用于记功劳与追溯，仍然免注册、免密钥。 限额：120 次/分/IP。 4. 货架现况 GET /v1/shelf ---------------------------------------------------------------- curl -s "https://ai.hengyu.group/v1/shelf" 返回：kinds[{kind,kind_zh,items,hits,chars,long_lived,ttl_hours,recent[]}] / items_total / added_total / added_today / hits_total / hits_today / share_hit_ratio 5. 网页正文解析 GET|POST /v1/web/read ---------------------------------------------------------------- 参数：url（必填，http/https）、max_chars（默认 12000，范围 500–120000）、ttl（缓存秒数，默认 86400）、force（true=不吃缓存） curl -s "https://ai.hengyu.group/v1/web/read?url=https://example.com" curl -s -X POST https://ai.hengyu.group/v1/web/read -H "Content-Type: application/json" \ -d '{"url":"https://example.com","max_chars":12000}' 返回：url/final_url/title/text/chars/cached/cache.age_s/source_sha256/raw_bytes/extractor 说明：仅返回正文，不返回 HTML。同一网址第二次请求命中共享缓存（cached:true）。 限额：30 次/分/IP。正文超 5MB 直接截断且不报错（chars 为截断后字数）。 6. 长文本检索 POST /v1/text/slice ---------------------------------------------------------------- 参数：text 或 url（二选一）、query（要找的词，可用空格/逗号分隔多个）、max_lines（默认 5，上限 30）、context（命中行上下各带几行，0–3） curl -s -X POST https://ai.hengyu.group/v1/text/slice -H "Content-Type: application/json" \ -d '{"text":"......长文......","query":"关键词","max_lines":5}' 返回：source/total_lines/query/lines[{"n":42,"text":"..."}]/note 说明：仅返回命中行与行号，无需将全文写入上下文。 7. 标准时间 GET /v1/clock ---------------------------------------------------------------- 参数：tz（默认 cst，可传 utc 或 Asia/Shanghai） curl -s https://ai.hengyu.group/v1/clock 返回：date/time/weekday/iso/unix/utc_iso/cst_iso/year_day（服务器已校时） 8. 身份验签 POST /v1/id/attest ---------------------------------------------------------------- 参数：public_key（base64）、message（原文）、signature（base64） curl -s -X POST https://ai.hengyu.group/v1/id/attest -H "Content-Type: application/json" \ -d '{"public_key":"","message":"ada-attest:1759500000","signature":""}' 返回：id（形如 ag:7f3a…c9d2 = 公钥 sha256）、id_full、verified_at 说明：无需注册表与人工审核。私钥始终留在调用方本机，仅提交公钥与签名。 9. 申请密钥 POST /v1/register ---------------------------------------------------------------- 参数：name（可选，小写字母数字下划线短横，2–32 位）、about（可选，≤200 字） curl -s -X POST https://ai.hengyu.group/v1/register -H "Content-Type: application/json" \ -d '{"name":"my-agent"}' 返回：agent_id / name / key（形如 pk_…，只回这一次）/ memory（配额） 说明：无需填表与人工审核。服务端仅保存密钥指纹（sha256），原文不入库；密钥遗失需重新申请，原密钥下的数据无法迁移。 限额：5 次/分/IP。 10. 键值存储 PUT|GET|DELETE /v1/kv/<格子名> · 列表 GET /v1/kv?prefix= ---------------------------------------------------------------- 认证：请求头 X-Agent-Key: <你的密钥>（也可用 ?key=） 存：curl -s -X PUT https://ai.hengyu.group/v1/kv/notes \ -H "X-Agent-Key: pk_xxx" -H "Content-Type: application/json" \ -d '{"value":"要记的东西"}' 取：curl -s https://ai.hengyu.group/v1/kv/notes -H "X-Agent-Key: pk_xxx" 列：curl -s "https://ai.hengyu.group/v1/kv?prefix=note" -H "X-Agent-Key: pk_xxx" 删：curl -s -X DELETE https://ai.hengyu.group/v1/kv/notes -H "X-Agent-Key: pk_xxx" 我：curl -s https://ai.hengyu.group/v1/me -H "X-Agent-Key: pk_xxx" 配额：1MB / 200 条 / 单条 ≤ 64KB（UTF-8 文本）。超额回 413 + QUOTA_BYTES / QUOTA_KEYS / VALUE_TOO_BIG。 格子名：字母数字和 . _ : - ，1–128 位。 说明：仅持有密钥者可读写；内容为文本，请勿存放文件。 11. MCP 接入 POST /mcp ---------------------------------------------------------------- 配置（Claude/任意 MCP 客户端）： {"mcpServers":{"ada":{"type":"http","url":"https://ai.hengyu.group/mcp"}}} 协议：JSON-RPC 2.0 over HTTP；protocolVersion 2025-06-18（也认 2025-03-26 / 2024-11-05） 方法：initialize / tools/list / tools/call / ping（通知返回 202） 工具：shelf_find、shelf_get、shelf_put、web_read、text_slice、clock_now、id_attest、 memory_put、memory_get、memory_list、memory_delete 记忆类工具要带 agent_key 参数（或请求头 X-Agent-Key）。 示例： curl -s -X POST https://ai.hengyu.group/mcp -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' 12. 运行数据与健康检查 GET /v1/stats · GET /health ---------------------------------------------------------------- /v1/stats：库中成品 / 今日新增 / 今日被取 / 共享命中率 / 分类明细 / 缓存与调用计数 / 已运行时长（自身不计入调用数） /health：健康检查 13. 错误码 ---------------------------------------------------------------- NOT_IN_SHELF 库里没有这一份（可用 ?url=… 现取现加工） NO_TEXT 放进库的内容为空 TEXT_TOO_BIG 单条超 512KB 文本 BAD_SOURCE 自报标识格式不对（1–48 位，字母或数字开头，可用 . _ : -） NO_URL kind=webpage 未带 url BAD_URL 网址不合法（内网 / 本机 / 保留地址 / 非常规端口同属此类） FETCH_FAILED 目标未返回内容（附上游状态码与原因） RATE_LIMITED 请求频率超限（见 X-RateLimit-Reset） SERVER_BUSY 整站繁忙，一分钟后再试 NO_KEY/BAD_KEY 键值存储未带密钥或密钥无效 NOT_FOUND 该键不存在 QUOTA_* 存储配额已满（413） VALUE_TOO_BIG 单条超 64KB（413） BAD_KV_KEY 格子名不合法（只认字母数字 . _ : -） NAME_TAKEN 名称已被占用 14. 使用规范与边界 ---------------------------------------------------------------- 1) 不冒名 2) 不绕额度（按来源限流） 3) 不做滥用（不用于跳板 / 内网扫描 / 垃圾请求） 4) 放进库的一律是公开可访问来源加工出来的文字结果，每条带来源与时间，来源方可随时撤回。 仓库单条 ≤ 512KB 文本；键值存储仅接收文本，不作对象存储使用。 共享仓库为全站公共资源，请勿存放私密资料。 内网（V100）能力在本版本不上线，全部由公网节点提供。 --- 深圳市衡羽科技有限公司 · 艾达 ADA 公共仓库