E EvoCow API
v1 draft OpenAPI 下载 RFC
RFC-001 · 供讨论

一套围绕“观察 → 追问 → 建议 → 反馈”的简单接口

调用方只提交自然语言观察。EvoCow 维护同一次处方的上下文，并用一个字符串返回追问、升级提醒或最终建议；执行结束后，再一次性提交完整报告。

实现状态：Draft。 本页是重新设计后的目标契约；当前 Demo 代码仍是旧版结构化接口，尚未迁移，请勿把它当成生产可调用地址。
01

观察是字符串

observation 保留现场原话；可同时附带原始 hardware_data。

02

没有 refs

处方 ID 就是生命周期关联键，不接管牛只、设备、病例等外部实体。

03

报告只有三块

人工反馈、全量对话、硬件数据；不再拆成多种 report type。

01

Lifecycle

完整生命周期

当状态为 needs_more_information 时，content 就是下一句要问的问题。调用方收集到新信息后，只追加一条新的 observation，无需重传历史。服务端负责累积上下文。

02

Conventions

调用约定

鉴权

所有接口使用 Bearer API Key。租户归属由 Key 决定，不允许在正文里传 tenant_id。 

Authorization: Bearer <API_KEY>

写入幂等

POST/PUT 必须携带唯一键。相同 Key 与相同正文会返回第一次结果，不重复执行。

Idempotency-Key: 018f...unique
needs_more_information 需要继续观察 ready 已给出建议 urgent_escalation 立即转人工/兽医
03

Result variants

三种返回结果

三种结果使用完全相同的 id + status + content 外壳。区别只由 status 表达，content 始终是一段可以直接交给调用方 Agent 的文字。

needs_more_information

证据不足。content 是下一条需要向现场询问的问题；随后继续 PUT 新观察。 

{
  "id": "rx_01JEVOCOW001",
  "status": "needs_more_information",
  "content": "请测量体温，并观察呼吸是否费力、能否正常站立。"
}
ready

信息足够。content 是当前处置建议，处方进入终态，不再接受新 observation。 

{
  "id": "rx_01JEVOCOW001",
  "status": "ready",
  "content": "建议尽快联系驻场兽医检查。等待期间隔离观察并持续记录体温。"
}
urgent_escalation

存在紧急风险。content 是立即转人工/兽医的安全提示，不等待信息补齐。 

{
  "id": "rx_01JEVOCOW002",
  "status": "urgent_escalation",
  "content": "发现无法站立并伴随呼吸费力，请立即联系兽医进行现场急诊处理。"
}
POST

/v1/prescriptions

用第一条自然语言观察创建一次处方生命周期。

Request 
curl "$BASE_URL/v1/prescriptions" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: rx-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "observation": "这头牛今天不吃草，精神很差。",
    "hardware_data": {
      "source": "ear-sensor-live",
      "samples": [
        {"time": "2026-07-13T08:00:00+08:00", "temperature_c": 39.8},
        {"time": "2026-07-13T08:10:00+08:00", "temperature_c": 40.0}
      ]
    }
  }'
201 Response 
{
  "id": "rx_01JEVOCOW001",
  "status": "needs_more_information",
  "content": "请测量体温，并观察呼吸是否费力、能否正常站立。"
}
PUT

/v1/prescriptions/{id}

追加一条新观察。可调用零到多次；服务端用处方 ID 找回之前的全部观察。

Request 
curl "$BASE_URL/v1/prescriptions/rx_01JEVOCOW001" \
  -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: rx-observation-002" \
  -H "Content-Type: application/json" \
  -d '{
    "observation": "体温 40.2℃，呼吸不费力，可以站立，但反刍明显减少。",
    "hardware_data": {
      "source": "ear-sensor-live",
      "samples": [
        {"time": "2026-07-13T08:20:00+08:00", "temperature_c": 40.2}
      ]
    }
  }'
200 Response 
{
  "id": "rx_01JEVOCOW001",
  "status": "ready",
  "content": "建议尽快联系驻场兽医检查。等待期间隔离观察，持续记录体温和饮水，不要自行加药。"
}
GET

/v1/prescriptions/{id}

读取这次处方最新的状态与内容。它不会返回内部推理、历史 observation 或最终报告。

Request 
curl "$BASE_URL/v1/prescriptions/rx_01JEVOCOW001" \
  -H "Authorization: Bearer $API_KEY"
PUT

/v1/prescriptions/{id}/report

处方结束后提交唯一的最终报告。正文顶层严格只有下面三块。

Request 
curl "$BASE_URL/v1/prescriptions/rx_01JEVOCOW001/report" \
  -X PUT \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: rx-report-001" \
  -H "Content-Type: application/json" \
  -d '{
    "human_feedback": "兽医检查后按方案处理，24 小时后体温下降，采食开始恢复。",
    "conversation": [
      {"role": "user", "content": "这头牛今天不吃草，精神很差。"},
      {"role": "assistant", "content": "请测量体温，并观察呼吸是否费力、能否正常站立。"},
      {"role": "user", "content": "体温 40.2℃，呼吸不费力，可以站立，但反刍明显减少。"}
    ],
    "hardware_data": {
      "source": "ear-sensor-export",
      "samples": [
        {"time": "2026-07-13T08:00:00+08:00", "temperature_c": 40.2},
        {"time": "2026-07-14T08:00:00+08:00", "temperature_c": 39.3}
      ]
    }
  }'
201 Response 
{
  "id": "rpt_01JEVOCOW001",
  "prescription_id": "rx_01JEVOCOW001",
  "received_at": "2026-07-14T09:30:00+08:00"
}
04

Schemas

字段定义

PrescriptionInput

字段 类型 必填 说明
observation string 是 一条自然语言现场观察；非空，不超过 8 KB。
hardware_data JSON object | array 否 当前这一步可获得的原始硬件快照或时序片段；不强制设备 Schema。

Prescription

字段 类型 必填 说明
id string 是 服务端生成的处方生命周期 ID。
status enum 是 needs_more_information、ready 或 urgent_escalation。
content string 是 直接展示给调用方的追问、建议或升级提醒。

Report

字段 类型 必填 说明
human_feedback string 是 现场人员对执行过程和结果的自然语言总结。
conversation JSON object | array 是 调用方保留的全量原始对话；EvoCow 不强制消息 Schema。
hardware_data JSON | null 是 原始硬件/时序数据。暂无统一 Schema；没有数据时明确传 null。
请求里的 hardware_data 是“当前决策可见的增量证据”；最终 report 里的 hardware_data 是“处方结束后的完整数据”。两者用途不同，但都先保持原始 JSON，不把设备协议固化进公共接口。

机器可读版本：openapi.yaml

05

Open decision

硬件时序数据怎么存，暂不锁死

创建处方和追加观察时可以提交当前硬件片段，最终 report 再提交完整硬件数据。API 先把两者都当作不透明 JSON，避免设备协议、采样频率和查询需求还没确定时就固定 Schema。存储层建议分两阶段验证：

  1. MVP：原始 payload 压缩后放对象存储，PostgreSQL 只保存 URI、哈希、字节数和 report 关联；设置单次上传上限。
  2. 需要跨报告查询时：再把确认有价值的指标异步投影到 TimescaleDB/时序表，原始数据仍作为事实保留。
RFC 合并前还需决定：最大 payload、上传方式（内联 JSON 或预签名文件）、保留周期，以及是否需要按时间窗查询。它们不会改变 report 顶层的三块语义。