从现实问题开始，回到实际使用
Reality-First Development 的工作顺序是：现实问题 → 最小有用数据 → 身份、时间与证据 → 模型和接口 → 实际使用 → 反馈修正。先让一次查询保留正确含义，再扩充数据量和界面。
下面是聚身之家已有实现或治理记录中的例子；代码能证明机制，不能单独证明某一生产版本已部署或数据已完善。
Robot duplicate → Identity
同名搜索可能命中多个机器人。详情接口会保留 matchType、canonicalId、ambiguous 与 candidates，把不确定性交给调用方处理。搜索得到名字之后还要确认厂商和规范 ID，不能用字符串相似度直接合并产品。
依据：emibot-rs/src/routes/robots.rs 的名称候选与身份响应。使用方式见 核心模型。
Company lifecycle → Time / Lifecycle
企业停止经营不应从知识图谱消失。企业详情读取批准的生命周期断言，保留有效期、证据数量与核验状态；没有断言时返回 unknown。historical 是由特定状态派生的展示标记，不是删除指令，也不能由官网打不开推断。
依据：emibot-rs/src/routes/companies.rs 的 lifecycle_json；事件状态链见 Timeline / State。
Source conflict → Evidence
两份资料的扭矩不同，可能属于不同版本或时间，也可能是真冲突。Part 模型保留独立规格主张、有效期、证据和修订链；不能只存一个“最新数字”。时间未知时无法证明两者互不冲突，应保留这个限制。
这是仓库已有的模型规则，不声称某两家厂商发生过未核实的争议。依据：docs/adr/0005-parts-bom-domain-schema.md 的规格时间与 source_conflict 规则；读取方式见 Evidence。
Missing cover → Quality rule
没有合格官方单机原图时，产品图留空并记录缺口。低清帧、遮挡、多主体图、猜测重绘和透明占位图不能让资料“变完整”。数据质量取决于真实可用信息，图片填充率不是目标。
依据：仓库 AGENTS.md 的产品参数与图片规则。这条规则约束维护行为，不表示公共 API 会自动完成图片质量判定。
REST unknown param → Agent-safe contract
把 manufacturer 误传给机器人列表，若服务端静默忽略，Agent 就可能把全量列表当作筛选结果。现有 query 白名单对覆盖的路径返回 400、INVALID_QUERY_PARAMETER 与允许参数，阻断这种错误结论。它尚未覆盖所有新增路径，所以文档必须交代实际范围。
依据：emibot-rs/src/query_validation.rs 的冷启动回归记录。见 REST 错误契约。
Migration incident → Governance guard
仓库治理记录说明：2026-09-18，8 个 company_profiles 迁移的审计发现其会向既有来源和证据表追加数据。它们从主干撤下并不撤销已经发生的数据库变化。这推动了敏感迁移分类、待执行集合核对及与内容摘要绑定的放行机制。
教训是把代码变更、数据库执行和实际读回分开验收。依据：docs/migration-governance.md 的事故与后续核实记录、scripts/check-migrations.py。本文只解释工程边界，不提供生产操作入口。
用一次接入检验这些原则
从 Getting started 发起真实搜索，用 Agent Guide 检查身份、未知与错误，再沿证据确认一个结论。遇到契约缺口时保留可复现请求和响应，而不是让页面叙述越过接口能力。