Agent API

用紧凑、可分页、可缓存的接口读取 CiteArk 研究结论、执行、计量与证据。

Agent API 是机器客户端的首选接口。公开读取无需密钥；默认响应保持紧凑，采用游标分页，提供稳定后续链接，并支持 ETag / If-None-Match，因此轮询时不必重复下载没有变化的完整研究快照。

论文页面本身也支持内容协商。对任意 /r/{owner}/{slug} 或 /zh/r/{owner}/{slug} 发送 Accept: application/json，会直接返回对应的紧凑仓库记录；普通 HTML 响应同时通过 Link: …; rel="alternate"; type="application/json" 声明机器入口。

机器发现

OpenAPI 3.1：https://citeark.com/openapi.json
JSON Schema：https://citeark.com/api/v1/schema
MCP Streamable HTTP：https://citeark.com/mcp
Agent 索引：https://citeark.com/llms.txt

紧凑调用流程

先搜索，不下载每个仓库的完整快照：

curl "https://citeark.com/api/v1/search?q=language+model&limit=10"

使用选中仓库的稳定 ID，只读取结论：

curl "https://citeark.com/api/v1/claims?repository_id=<repository-id>&include=assessments&limit=20"

读取单次运行，仅在需要时加入证据：

curl "https://citeark.com/api/v1/runs?repository_id=<repository-id>&execution_state=succeeded&assessment_conclusion=supports&limit=20"

接口

接口	用途
`GET /api/v1/search?q=`	搜索仓库元数据与结论文本
`GET /api/v1/repositories`	筛选、分页读取紧凑仓库摘要
`GET /api/v1/repositories/resolve?owner=&slug=`	从人类可读路径解析紧凑仓库记录
`GET /api/v1/repositories/{id}`	读取单个仓库，可选 `include=readme,claims,experiments,runs,evidence,assessments`
`GET /api/v1/claims`	跨仓库筛选、分页读取结论
`GET /api/v1/claims/{id}?repository_id=`	解析仓库内唯一的结论 ID
`GET /api/v1/runs`	用 `execution_state` 与 `assessment_conclusion` 分别筛选执行事实和科学判断
`GET /api/v1/runs/{id}`	解析单次运行，可选 `include=environment,attestation,logs,evidence,assessments`
`GET /api/v1/evidence/{id}?repository_id=`	解析证据元数据与下载地址
`POST /api/v1/runs`	发起复现，需要具有 `run` 权限的 API Key

集合接口支持 limit（1–100）、不透明 cursor，以及用逗号分隔顶层字段的 fields。请跟随 pagination.nextCursor 或响应头里的 RFC 8288 Link: <…>; rel="next"，不要自行拼接游标。所有 self、next 与 Link 地址都固定使用公开域名 https://citeark.com。仓库、结论、运行集合均支持 ISO 8601 格式的 updated_since。

计划、执行与 Assessment

这三类状态不能互相替代：

claim.plan 说明准备怎样验证，不表示已经执行；
run.execution.state 只记录物理执行发生了什么；
run.assessment.conclusion 与 claim.evidence 聚合不可变 Assessment，表达证据是支持、质疑、矛盾还是不足。

旧字段 claim.verification、claim.reproduction 与 run.state 为 v1 兼容别名，已在 Schema 中标记弃用。新 Agent 不应根据“执行失败”推断论文结论错误，也不应让最近一次运行覆盖历史 Assessment。

计量真值模型

请使用 measurementId，不要用 metric 作为唯一标识。同一篇论文可能针对不同模型、数据集、数据划分或实验条件报告同名指标。每条规范计量因此都包含：

{
  "measurementId": "ag-news-bigram-test-accuracy",
  "metric": "accuracy",
  "unit": "percentage_points",
  "dimensions": { "features": "bigram", "dataset": "AG News" },
  "reportedValue": 92.5,
  "observedValue": 92.5,
  "tolerance": 0.2,
  "verification": "verified",
  "evidenceIds": ["…"]
}

若旧快照曾把多个同名计量压缩为一个数值，CiteArk 会返回 observedValue: null 与 verification: "review_required"，不会把同一个数复制成多个实验结果。

公开投影会去除 IEEE-754 无意义尾数。失败原因使用稳定的 diagnostic.code/category/retryable/summary/recoveryAction，默认响应不会暴露内部文件路径或运行日志；需要审计时再按需读取签名证据或 include=logs。

条件轮询

保存读取响应中的 ETag，下一次请求时原样传回：

curl -i "https://citeark.com/api/v1/runs/<run-id>" \
  -H 'If-None-Match: "<etag>"'

记录没有变化时返回无正文的 304。公开 v1 读取还会返回 Cache-Control: public, max-age=60, stale-while-revalidate=300。

错误格式

v1 错误具有稳定的机器可读结构：

{
  "error": {
    "code": "repository_not_found",
    "message": "Public repository not found."
  }
}

旧版 /api/repositories 仍用于浏览器集成与完整兼容快照；新的 Agent 应使用 /api/v1。