Reality → Model · 公开事实的读取投影
这些接口服务机器人、企业、关系、事件与部件读取。生产站点使用同源 /api，基础地址为 https://www.aiman.world；本地由 Web 代理到 Rust。下表均为公开 GET，账户与管理写接口不在此范围。
Interface · 常用端点
参数大小写敏感。{id} / {name} 是占位符，替换为搜索返回的值并进行 URL 编码，不能原样调用。响应形状按端点不同，不是统一的 data envelope。
| 端点 | 参数 / 返回重点 |
|---|---|
/api/robots | search、formCategory、primaryPurpose、origin、isOpenSource、page、pageSize；返回 robots/total/page/pageSize |
/api/robots/{id} | ID 或 slug；兼容名称查找但需检查 identity.ambiguous；返回 robot/identity/provenance/relatedBlogs |
| 机器人字段目录 · 分类元数据 | 字段、筛选项目录与可用分类；字段目录不是完整 OpenAPI / JSON Schema |
/api/companies | search、sort、role、page、page_size；注意分页参数为下划线形式 |
/api/companies/{name} | 规范公司身份、profile、lifecycle、产品与图谱摘要 |
/api/companies/{name}/relationships | 关系方向、sourceUrl 和 evidence |
/api/graph | 现有产业图谱；不接受查询参数 |
/api/world/graph | 必填 entity，depth 当前只能为 1，limit 默认 200、上限 400；canonical 一跳关系 |
/api/timeline | type/class/event/company/robotId/from/to/limit；产业 Event Store，详见 时间线 |
/api/world/timeline | limit 默认 200、上限 500；批准的 canonical 事件与 stateChanges |
/api/world/state · /api/world/state/history | subjectType 与 canonicalId 同时提供或同时省略；可选 dimension/limit；返回 states 或 transitions |
/api/world/events | 展会届次列表，status/limit；详情 /api/world/events/{key}，key 为届次 ID 或 canonicalId |
/api/parts · /api/parts/{id} | 只读部件列表 / 详情，含审核状态和逐条规格证据；完整说明 |
/api/parts/match | category/spec/limit；spec=field:op:value[:unit]，不能使用虚构的 field/value/unit 独立参数 |
/api/robots/{id}/parts | status 默认 approved；组成关系不等于完整 BOM |
/api/blog · /api/blog/{slug} | 列表可传 limit；文章用于解释事实，不替代 Event |
| 统计 · 语义 · 部件能力 | 统计覆盖、知识协议、schema 实测与写能力 |
curl -fsS -G https://www.aiman.world/api/robots \
--data-urlencode 'search=G1' --data-urlencode 'pageSize=5'
curl -fsS -G https://www.aiman.world/api/companies \
--data-urlencode 'search=宇树' --data-urlencode 'page_size=5'
错误契约
| 信号 | 当前响应 | 客户端应对 |
|---|---|---|
| 已纳入严格校验的路径出现未知 query key | HTTP 400；success: false、code: INVALID_QUERY_PARAMETER、unknownParameters、allowedParameters、error | 修正拼写或映射；不能忽略原约束 |
| 一般业务错误 | AppError 使用对应 HTTP 状态和 { "success": false, "error": "…" } | 先判断状态，再检查实际响应体；不要假设一定有 code |
| 查询值无法解码 | Axum 提取器可返回 400 文本错误 | 兼容非 JSON 错误体，修正类型 |
| 资源不存在 | 通常 HTTP 404，例如 Robot ID / slug 无匹配 | 先重新搜索规范身份 |
| 权限 / 冲突 / 限流 | 对应路径可能返回 401 / 403 / 409 / 429 | 按授权和任务上下文处理，限制重试 |
| 服务或依赖异常 | 5xx | 报告不可用，不能当作“没有数据” |
例如 GET /api/robots?manufacturer=Unitree 会返回 400：机器人列表不接受 manufacturer。使用 search 查找候选，再逐项核对规范厂商。MCP 使用的是 query，也不能直接当作 REST 参数。
校验覆盖边界： 目前机器人列表/详情/schema/组成、企业列表/详情/关系、parts 列表/详情/match，以及 graph、blog、cases、partners、stats、semantics、health 有显式 query 白名单。/api/timeline、World timeline/graph/state/events、parts capability/series、机器人 metadata 尚未全部纳入这一层；不能声称所有 GET 都拒绝未知参数，HTTP 200 也不证明过滤已生效。
部件列表的 seriesId 在 handler 与 query 白名单间存在命名不一致，当前不要依赖该筛选；按系列读取可用 /api/parts/series/{id}。这里记录真实限制，不把它包装成已支持契约。
Agent behavior · 检查语义成功
保留原始状态码、错误体及请求参数；遵循 Agent Guide。结果为空、参数被拒绝、上游失败与证据不足是不同情况。批量读取请分页、限制并发，不假定存在统一 SLA 或无限流承诺。
实现依据：emibot-rs/src/main.rs、emibot-rs/src/query_validation.rs、emibot-rs/src/error.rs、emibot-rs/src/routes/robots.rs、emibot-rs/src/routes/parts.rs。