草料开放平台文档

简体中文

English

简体中文

English

主题

English

工具列表 ​

公开 MCP 提供 5 个工具，全部只读。所有工具都接受同一个参数 code，值是扫码得到的完整链接（如 https://qr71.cn/okDISU/qssTnoy）。

工具回答的问题
entity_get这张码是什么？
entity_records_list这个物经历过什么？
entity_actions_list现在能做什么？
entity_action_get某个操作要填哪些字段？
entity_bindings_list这张码指向过哪些物？

注：本页示例的返回来自一个公开演示码，经过删节、人名做了替换。实际返回还包含 representations（Markdown 等其它表示形式的地址）、category、description、dateCreated、dateModified、items 等字段，完整结构以 schema.json 为准。

entity_get ​

一次取回实体全貌，包含操作和记录的预览。拿到码后从这里开始。

参数

参数类型必填说明
codestring是码的 URL
formatsstring[]否返回哪些表示形式，可选 json、markdown、jsonld、og。不传时返回 json

返回

返回值是一个以格式名为键的对象。默认只有 json 一个键，值为 ObjectCard：

json
{
  "json": {
    "$schema": "https://a2a.objqr.com/ext/caoliao-entity/v2/schema.json",
    "objectCardVersion": "2.0",
    "generatedAt": "2026-08-12T17:14:13.264Z",
    "thing": {
      "id": "thg_qssTnoy",
      "idScheme": "code-derived",
      "name": "数控车床-A08-03-06",
      "type": { "id": "generic", "additionalType": "https://schema.org/Thing" }
    },
    "code": {
      "id": "qssTnoy",
      "uri": "https://qr71.cn/okDISU/qssTnoy",
      "status": "bound"
    },
    "binding": {
      "boundAt": "2025-03-20T17:25:06.000Z",
      "historyCount": 1,
      "historyVia": "entity_bindings_list"
    },
    "org": { "id": "okDISU", "name": "草料二维码" },
    "properties": [
      { "name": "设备名称", "value": "数控车床" },
      { "name": "设备编号", "value": "A08-03-06" },
      { "name": "所在位置", "value": "液压再制造车间" }
    ],
    "states": [
      {
        "machine": "state_8985306",
        "name": "设备运行状态",
        "current": "正常",
        "updatedAt": "2026-06-23T02:26:36.000Z",
        "derivedFrom": "records",
        "byRecord": "rec_460807516"
      }
    ],
    "records": {
      "count": 1,
      "preview": [
        {
          "id": "rec_460807516",
          "type": "inspection",
          "label": "巡检记录表",
          "at": "2026-06-23T02:26:36.000Z",
          "result": "pass",
          "resultLabel": "正常",
          "by": { "name": "张工" }
        }
      ],
      "listVia": "entity_records_list"
    },
    "actions": [
      {
        "action": "record:1556557",
        "label": "巡检记录表",
        "requiresAuth": true,
        "formSchemaVia": "entity_action_get",
        "humanUrl": "https://qr71.cn/okDISU/qssTnoy"
      }
    ],
    "plans": [
      { "action": "record:1556556", "label": "维护保养记录", "cycle": "每周", "status": "running" }
    ],
    "endpoints": {
      "mcp": { "url": "https://mcp.objqr.com/mcp", "transport": "streamable-http" },
      "a2a": {
        "url": "https://a2a.objqr.com",
        "agentCard": "https://a2a.objqr.com/.well-known/agent-card.json"
      }
    },
    "contract": {
      "profile": "read-only-public",
      "rules": {
        "readOnly": true,
        "publicOnly": true,
        "singleOrgView": true,
        "actionsExecutable": false
      }
    }
  }
}

formats 决定返回对象里出现哪些键：数组里列出什么就返回什么，是替换不是追加。只传 ["markdown"] 时返回里没有 json，ObjectCard 不会出现——还需要结构化本体时，把 "json" 一并写进数组，如 ["json", "markdown"]。markdown 是同一实体的人读文本，jsonld 是 JSON-LD（schema.org 词汇）表示，og 是 Open Graph 元信息，适合搜索与分享场景。

主要字段

字段说明
thing物本身：名称、类型
code码：编码、URL、码状态（bound 正常 / disabled 已停用）
binding码与物的绑定关系及绑定时间
properties属性字段，来自二维码的内容模块
relations关系槽：所在位置、所属、责任人、从属于。未解析成结构化引用时为空对象 {}
states业务状态。derivedFrom 说明该状态由什么推导而来
records记录账本（巡检、报修、保养等）：count 是总数，preview 是最近几条
media图片、附件
actions此刻可执行的操作，只列出不执行
plans周期性计划，如「每周维护保养」
endpoints本实体在公开 MCP 和 A2A 上的地址
representations本实体其它表示形式的地址（HTML / Markdown 等）
contract本次返回遵守的边界声明

顶层块始终存在（schema 里标为必有）：未跟踪时取值为 null、{} 或 []，应一律解读为「未跟踪」，不是否定。「缺席」语义适用于块内部的可选子字段，见下方使用约定第 2 条。

四条使用约定

注意：以下四条会影响你怎么存数据，请务必先读。

  1. thing.id 是过渡期的码派生标识（idScheme 为 code-derived），不要持久化依赖。需要长期保存的稳定标识是 code.uri。
  2. 子字段缺席、或块取值为 null / {} / []，都表示「未跟踪」或「无法解析」，不等于 false 或「没有」。不要把它们当作否定结论。
  3. code.status 是码的状态，states 是业务状态，两者不是一回事。
  4. 账本记录当前可被建档组织修订。不可变账本是目标态，本契约不承诺不可变性——不要把记录当成不可篡改的审计凭证持久化引用。

entity_records_list ​

取完整账本——巡检、报修、保养等记录，按时间倒序，游标分页。entity_get 只给最近几条，要翻历史用这个。

参数

参数类型必填说明
codestring是码的 URL
sizenumber否每页条数，默认 20，上限 50
page_tokenstring否上一页返回的 nextPageToken。首页留空

返回

json
{
  "url": "https://qr71.cn/okDISU/qssTnoy",
  "records": [
    {
      "id": "rec_460807516",
      "type": "inspection",
      "label": "巡检记录表",
      "at": "2026-06-23T02:26:36.000Z",
      "result": "pass",
      "resultLabel": "正常",
      "summary": "巡检结果：正常",
      "by": { "name": "张工" },
      "snapshot": { "codeId": "qssTnoy", "thingId": "thg_qssTnoy" }
    }
  ],
  "hasMore": false,
  "total": 1
}

每条记录带 snapshot，是记录发生当时的码与物快照。时间为 ISO 8601 带时区。

hasMore 为 true 时，返回顶层还会带 nextPageToken 字段（hasMore 为 false 时不出现，所以上面的示例里没有它），把它传给下一次调用的 page_token。

entity_actions_list ​

列出此刻可执行的操作清单——能填哪些表单、有哪些状态变更。只列出，不执行。

参数

参数类型必填说明
codestring是码的 URL

返回

json
{
  "url": "https://qr71.cn/okDISU/qssTnoy",
  "actions": [
    {
      "action": "record:1556557",
      "label": "巡检记录表",
      "requiresAuth": true,
      "annotations": {
        "readonly": false,
        "destructive": false,
        "idempotent": "by_request_key",
        "confirm": "none"
      },
      "precondition": null,
      "formSchemaVia": "entity_action_get",
      "humanUrl": "https://qr71.cn/okDISU/qssTnoy"
    },
    {
      "action": "record:1556556",
      "label": "维护保养记录",
      "requiresAuth": true,
      "annotations": {
        "readonly": false,
        "destructive": false,
        "idempotent": "by_request_key",
        "confirm": "none"
      },
      "precondition": null,
      "formSchemaVia": "entity_action_get",
      "humanUrl": "https://qr71.cn/okDISU/qssTnoy"
    }
  ]
}
字段说明
action操作标识，形如 record:1556557，传给 entity_action_get 用
requiresAuth该操作提交时是否需要授权
annotations操作性质：是否只读、是否破坏性、幂等方式、是否需要确认
humanUrl人在浏览器里执行这个操作的入口

注意：公开 MCP 不执行写入。要真正提交一条记录，把 humanUrl 交给人在草料页面上完成。

entity_action_get ​

取某个操作的完整可填字段。entity_actions_list 只列操作不带字段，准备填某张表单前用这个。

参数

参数类型必填说明
codestring是码的 URL
actionstring二选一操作标识，来自 entity_actions_list 的 action 字段
tpl_idnumber二选一表单模板 id

action 与 tpl_id 必须提供其中一个，都不传会返回错误。

返回

json
{
  "url": "https://qr71.cn/okDISU/qssTnoy",
  "tplId": 1556557,
  "fields": [
    {
      "id": 10098724,
      "title": "巡检项目",
      "type": "checklist",
      "required": true,
      "choices": [
        { "id": 53279777, "label": "设备无异响，可正常操作" },
        { "id": 53279779, "label": "刹车、变速箱、油箱均正常" }
      ],
      "desc": "检查正常打勾，异常打叉，异常时须补充说明异常情况"
    },
    {
      "id": 10098730,
      "title": "巡检结果",
      "type": "radio",
      "required": true,
      "choices": [
        { "id": 53279846, "label": "正常" },
        { "id": 53279847, "label": "异常" }
      ]
    },
    {
      "id": 10098732,
      "title": "巡检人",
      "type": "name",
      "required": true
    }
  ]
}

读字段结构不需要授权，提交才需要。

entity_bindings_list ​

查这张码指向过哪些物，用于审计。

参数

参数类型必填说明
codestring是码的 URL

返回

json
{
  "url": "https://qr71.cn/okDISU/qssTnoy",
  "bindings": [
    {
      "thingId": "thg_qssTnoy",
      "current": true,
      "boundAt": "2025-03-20T17:25:06.000Z"
    }
  ],
  "note": "无换绑历史(historyCount=1):当前世代码与物 1:1,创建即默认绑定;换绑功能上线后此处为真实绑定事件序列"
}

注意：草料当前不支持换绑，码与物是 1:1。本工具现在恒定返回一条 current 绑定，note 字段会如实说明这一点。换绑功能上线后，这里会返回真实的绑定事件序列。字段形状不会变，现在就可以按它写代码。

典型调用顺序 ​

entity_get                 拿到实体全貌，看 records.count 和 actions
  ├─ 记录多，要翻历史  → entity_records_list（分页取完）
  ├─ 要填某张表        → entity_action_get（拿字段）→ humanUrl 交给人
  └─ 要查码的历史归属  → entity_bindings_list

下一步 ​