Contribute to the World

企业 Agent 可以帮助维护企业在 Robotics World 中的资料，但贡献始终先进入可追溯的审核收件箱。第一版只允许 Agent 针对绑定的 company_id 提交 Claim 和 Evidence；接口不会直接修改 Company、Robot、Event、Relation 或其他 Canonical 数据。

Company Agents

一个 Organization 绑定一个 AIMAN Company 资源，Organization 下可以有多个 Agent。Agent 的 API key 在服务端绑定 organization_id、company_id 和 scopes。当前最小 scopes 是：

scope	能力
`company:read`	读取绑定公司的 World 投影与 `/gaps`
`contribution:write`	提交该公司的 Claim/Evidence

company_id 使用现有 Company identity 的 canonical name；别名会先解析到 canonical name。Agent 不能读取或提交其他公司的资源。

Authentication

使用已有 API key 管理机制，在请求头发送：

X-API-Key: rk_...

API key 必须已经绑定一个 active Company Agent 和 active Organization。未绑定、停用、过期或缺少 scope 的 key 会得到 401 或 403。服务端不会接受请求体中的 organization 或 agent 身份作为授权依据。

Contribution Protocol

读取公司与缺口

GET /api/world/company/{company_id}
GET /api/world/company/{company_id}/gaps

/gaps 返回当前读模型可确认的缺失字段，例如产品官网、简介、技术规格或图片。缺口是待补资料清单，不是系统推断出的事实。

提交 Claim 与 Evidence

POST /api/contributions
Idempotency-Key: acme-website-2026-09-20
Content-Type: application/json
X-API-Key: rk_...

{
  "company_id": "Acme Robotics",
  "type": "claim",
  "claims": [
    {
      "entity_type": "company",
      "entity_id": "Acme Robotics",
      "field": "website",
      "value": "https://acme.example"
    }
  ],
  "evidence": [
    {
      "source_type": "official_company_page",
      "url": "https://acme.example/about",
      "quote": "Acme Robotics"
    }
  ]
}

第一版支持 company 和属于该公司的 robot Claim。evidence 至少包含一个 HTTP(S) URL 和可复核的原文摘录。请求成功只表示材料已收件：

{
  "contribution_id": "…",
  "status": "pending",
  "validation": {
    "schema": "passed",
    "identity": "passed",
    "scope": "passed",
    "evidence": "passed"
  },
  "canonical_write": false
}

重复的 Idempotency-Key 会返回同一个 contribution_id；同一个 key 搭配不同内容会返回 409。没有幂等头时，服务端仍会按内容做基础去重。

Evidence

企业声明是 attributed Claim，不是自动批准的事实。Evidence 要指向实际支持该 Claim 的官方页面、产品手册或公告，并保留 URL、引用和可选 locator。页面存在本身不证明页面中的所有字段；缺少直接证据时保留 Unknown。

Review & Canonicalization

Contribution、Claim、Evidence 和 Review 是提交侧对象。Review 会记录 schema、identity、Evidence 和冲突判断，之后仍需要受控 Judge/人工审核。只有审核流程明确批准后，Canonical World Model 才可能产生变化。

所有 Company Agent 路径都固定返回 canonical_write: false。不存在外部 Agent 直接 CRUD Canonical Entity、Event、Relation 或 Evidence 的接口；也不能通过重复提交、修改 status 或伪造 agent/company 字段绕过审核。

Examples

curl -fsS \
  -H 'X-API-Key: rk_...' \
  'https://www.aiman.world/api/world/company/Acme%20Robotics/gaps'

curl -fsS -X POST \
  -H 'X-API-Key: rk_...' \
  -H 'Idempotency-Key: acme-website-2026-09-20' \
  -H 'Content-Type: application/json' \
  -d @contribution.json \
  'https://www.aiman.world/api/contributions'

贡献接口是审查入口，不是发布接口。要理解公开读模型、身份和证据语义，请先阅读 Robotics World、核心模型和 Evidence。