Agent 接入说明

AgriHot 面向爬虫 / 资讯聚合 Agent 开放推送接口。推送的内容经服务层自动去重后直接上线，无需人工审核。新条目会由 AI 先做相关性门槛判断，再按影响力 / 信息增量 / 专业深度 / 信源权威 / 时效性多维度打分，每天达阈值且评分最高的前 5 篇进入首页「精选」。本页包含全部接入细节，也适合作为 LLM Agent 的上下文直接阅读。

OpenAPI 交互文档 ↗去重规则代码示例

① 快速开始

向站点管理员申请 API Key（形如 agri_xxxxxxxx）。
每次请求在 HTTP 头携带：X-API-Key: <你的Key>。
向 POST https://agrihot.com/api/v1/ingest/items 提交 JSON，收到 created 即上线。

bash

# 推送第一条资讯
curl -X POST https://agrihot.com/api/v1/ingest/items \
  -H "X-API-Key: <你的APIKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "8项农业人工智能标准立项获批 智慧农业迎来标准时刻",
    "url": "https://example.com/news/20260714-ai-standards",
    "summary": "2026年第二批农业国家和行业标准制修订计划中，8项农业人工智能相关行业标准获立项，覆盖农业机器人、农业农村大模型等领域。",
    "source_name": "示例信源",
    "published_at": "2026-07-14T09:00:00+08:00",
    "category": "政策",
    "tags": ["农业人工智能", "行业标准"]
  }'

# → {"status":"created","item_id":20,"message":"已收录并直接上线"}

② 认证方式

请求头	`X-API-Key: <key>`
缺失 / 无效	返回 `401`（Problem JSON）
频率限制	每个 Key 60 次/分钟，超限返回 `429`，请指数退避重试
Key 管理	服务端只存 SHA-256 哈希；不同爬虫建议各用一个 Key 以便溯源

③ 推送接口

POST/api/v1/ingest/items推送单条

POST/api/v1/ingest/items/batch批量推送，body 为 {"items": [...]}，一次 ≤ 50 条

DELETE/api/v1/ingest/items/{id}删除条目（下架测试/违规内容），需同一个 API Key

字段说明

字段	类型	必填	说明
title	string	是	标题，4–500 字
url	string	是	原文链接；论文优先填 DOI 链接（https://doi.org/…）
summary	string	是	摘要，≥10 字；论文建议附原文标题与作者
source_name	string	否	信源名称，如「农民日报」；多信源合并时展示
source_url	string	否	信源首页/出处链接
published_at	datetime	否	原文发布时间（ISO 8601 带时区）
category	string	否	政策 / 报道 / 论文 / 行业，缺省归「报道」
tags	string[]	否	标签数组，每项一个短主题，如 ["智慧农业","遥感"]。不要把标题拼成一条。服务端会先按空格/顿号切开，评分时再用正文提炼 3–6 个可聚合主题并覆盖；模型失败则保留切开后的原标签
cover_url	string	否	封面图 URL
content	string	否	正文（可选，Markdown，详情页展示；缺省时服务端自动抓取补充）
lang	string	否	语种标记，如 zh / en
doi	string	否	论文 DOI。不填时若 url 是 doi.org 链接会自动抽取。DOI 相同视为同一篇，优先于 URL / 标题去重

响应（HTTP 200，逐条结果）

json

// 单条响应
{
  "status": "duplicate",          // created | duplicate | invalid
  "item_id": 19,
  "duplicate_of": 19,             // 重复时指向已有条目
  "dup_reason": "similar_title",  // exact_url | similar_title
  "message": "与已有条目「…」标题相似，信源已合并"
}

// 批量响应
{ "total": 3, "created": 2, "duplicate": 1, "invalid": 0,
  "results": [ /* 每条同上 */ ] }

created — 新条目，已直接上线，item_id 为条目 ID。
duplicate — 判定为重复，不是错误；信源已合并到 duplicate_of 指向的条目。
invalid — 该条入库失败（批量模式下不影响其他条目）。

④ 去重规则（服务层自动执行）

第 0 级 · DOI / OpenAlex ID exact_doi / openalex_id

论文先按规范化 DOI（小写、去掉 doi.org 前缀）判重，再按 OpenAlex Work ID。同一篇论文的出版社页、DOI 链接与 OpenAlex 记录会合并为一条。

第 1 级 · URL 精确去重 exact_url

URL 先做规范化（去除 utm_*/from/ref 等追踪参数、统一协议与大小写、去锚点与末尾斜杠），再取 SHA-256。哈希已存在 → 判重。同一篇文章带不同追踪参数重复推送会被识别为同一条。

第 2 级 · 标题相似去重 similar_title

标题清洗（去标点空白、全角转半角）后计算 64 位 SimHash，与近 30 天条目比较：海明距离 ≤ 6，或标题互相包含（如「…指导意见」与「…指导意见（全文）」）→ 判重。

第 3 级 · 合并而非拒绝

判重后推送不会被丢弃：新信源会并入已有条目的信源列表（前端展示「N 个信源同时报道」），热度随之提升。幂等安全：网络超时后原样重推即可，不会产生重复条目。

提示：想让自己的信源出现在「多信源报道」里，请填好 source_name 与 source_url。

⑤ 状态码与错误格式

200	成功（含 duplicate 结果）
401	缺少或无效 API Key
422	字段校验失败（缺 title/url/summary、summary 过短等）
429	超出频率限制，稍后重试

错误统一为 Problem JSON：{"title": "...", "status": 401, "detail": "..."}

⑥ 代码示例

Python（httpx）

python

import httpx

API = "https://agrihot.com/api/v1/ingest/items"
KEY = "<你的APIKey>"

def push(item: dict) -> dict:
    r = httpx.post(API, json=item, headers={"X-API-Key": KEY}, timeout=30)
    if r.status_code == 429:
        raise RuntimeError("限流，退避后重试")
    r.raise_for_status()
    return r.json()

result = push({
    "title": "全国智慧农业现场会在江苏召开",
    "url": "https://example.com/news/smart-agri-conf?utm_source=rss",  # 追踪参数无需处理
    "summary": "全国智慧农业现场会在江苏南京召开，展示农业机器人、AI农情监测等新技术。",
    "source_name": "我的爬虫",
    "category": "报道",
    "tags": ["智慧农业", "农业机器人"],
})
# 幂等：超时后原样重推不会生成重复条目
print(result["status"], result.get("item_id") or result.get("duplicate_of"))

批量推送（curl）

bash

curl -X POST https://agrihot.com/api/v1/ingest/items/batch \
  -H "X-API-Key: <你的APIKey>" \
  -H "Content-Type: application/json" \
  -d '{"items": [
    {"title": "…", "url": "https://a.example/1", "summary": "……（≥10字）"},
    {"title": "…", "url": "https://a.example/2", "summary": "……（≥10字）"}
  ]}'

⑦ 最佳实践

直接推原始 URL 即可，无需自行去追踪参数，服务端会规范化。
失败/超时请原样重试，接口幂等，重复推送只会合并信源。
批量优于单条：一轮抓取打包成 ≤50 条一次推送，减少请求数。
published_at 用 ISO 8601 带时区（如 2026-07-15T08:00:00+08:00）；站点按收录时间分组排序，此字段仅用于展示原文日期。
category 建议用 政策 / 报道 / 论文 / 行业，其他值会归为「报道」。
tags 必须是独立短词数组（["智慧农业","遥感"]），不要写成整句。服务端会先切开，入库后的 AI 评分会根据正文重写主题；给的 tags 只是评分完成前的兜底。
摘要 ≥ 10 字、标题 ≥ 4 字，否则会被 422 拒绝。
遵守 60 次/分钟限制；收到 429 时指数退避（1s → 2s → 4s…）。