快速开始
概览
1stAuthor 给 agent 提供可推理的一手出处：论文全文、法规与判决、研究者档案，以及开放网页。每个垂域暴露同样的三个动词：
- Retrieve——像数据库一样能过滤的混合检索，返回 brief。
- Read——分层读一份文档：
brief → head → section → raw。 - Ask——agentic 循环：检索、按需阅读、流式返回带引用的回答。
Base URL https://data.rag.ac.cn。纯 HTTPS + JSON；agentic 端点另支持 NDJSON。CORS 已开，右侧 playground 直接从浏览器调 API。
免费样例（不需要 token）：论文 2409.05591、2504.21776；检索 query transformer、attention mechanism、large language model；PMC PMC544940、PMC514704。
鉴权
token 可以放请求头或 query 参数：
Authorization: Bearer YOUR_TOKEN ?token=YOUR_TOKEN
在 /signup 拿 key——Google、邮箱或 +86 手机号。SDK 首次使用会自动注册一个 token；该 token 不能调 agentic 端点（403）。在控制台认领它，即可提升到账号的额度。
配额与限流
两个独立配额池。agentic 调用不消耗通用请求，反之亦然。超出任一个返回 429。
| key | 通用 / 天 | agentic / 天 | 怎么拿 |
|---|---|---|---|
| SDK 自动注册 | 1,000 | 不可用（403） | 首次用 SDK/CLI 自动生成 |
| 注册 key | 10,000 | 30，免费 | /signup |
| Lite / Premium | 定制 | 500 / 10,000 | 邮件 tommy@chien.io 说明用途 |
计费：阅读与检索端点每次 1 次通用请求；/websearch 每次 50；每次 agentic 调用（arXiv、web、talent、law）扣 agentic 池 1 次。用 GET /stats/usage?days=7 查用量。
错误码
| 状态码 | 含义 |
|---|---|
| 400 | 参数无效 |
| 401 | token 无效或缺失 |
| 403 | SDK token 有效，但此端点需要注册 key |
| 404 | 文档不存在（trending 上表示还没有讨论） |
| 422 | 请求体校验失败（agentic 端点） |
| 429 | 超出当日限额——detail 里有档位和已用次数 |
| 503 | 检索后端不可用 |
错误为 JSON：{"detail": "…"}。
流式（NDJSON）
每个 agentic 端点都有 /stream 变体，返回 application/x-ndjson：一行一个 JSON 事件，请求体不变。协议在所有垂域一致。
| 事件 | 时机 | 内容 |
|---|---|---|
| billing | 第一行 | 档位、已用次数、日限额 |
| start | 开始运行 | 实际 effort、轮数、预算 |
| answer_start | 进入作答阶段 | — |
| answer_delta | 多次 | 回答文本增量 |
| sources | 回答之后 | 检索集（引用的超集） |
| done | 最后一行 | 统计，含 answer_truncated |
| error | 失败时 | 错误信息 |
仅 verbose: true 时 | ||
| tool_call | agent 调用工具 | 工具名 + 参数 |
| tool_result | 工具返回 | 结果摘要 |
| thinking | 输出推理 | 文本 |
| warning | 走了降级路径 | 信息 |
curl -sN -X POST "https://data.rag.ac.cn/arxiv/agent/search/stream" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"query": "what methods reduce KV cache memory for long-context inference", "verbose": true}'
playground 的事件查看器渲染的就是这个协议：选任一 Ask 端点，打开 流式。
MCP
一个 MCP 服务把所有垂域暴露成工具：papers_search、papers_read、law_search、law_read、case_search、case_read、ask。Claude Code、Cursor 和 Python SDK 的配置片段见 MCP 页。
SDK / CLI
pip install deepxiv-sdk deepxiv config --token YOUR_KEY deepxiv ask "what speedup does DEER report on HumanEval" --verbose deepxiv search "agentic memory" --venue NeurIPS --venue-year 2025 --min-citations 50 deepxiv paper 2409.05591 --brief deepxiv paper 2409.05591 --section "2. Method"
包名暂时沿用 DeepXiv（PyPI 上的 deepxiv-sdk，源码在 GitHub）。ask 是流式的：回答走 stdout，来源和进度走 stderr——方便管道。