跨产品契约与四条红线

6 个跨产品契约在 P1 就冻结接口签名（可判定的冻结基线），随产品实现逐步对齐；四条红线是全部设计决策的判据。契约草案来源：action/wiki/design/design_overview.md §3.3。

6 契约一览

① SemanticSearch（Foundry 提供 → AIP OAG / Swift 风控消费）

POST /api/v1/ontology/semantic-search：按文本匹配指标/对象/属性，返回结构化结果（非文本块）。

{ "request": {
    "query": "本月订单收入口径",
    "scopes": ["metric", "object", "property"],
    "limit": 20,                       // 默认 20，上限 50
    "filters": { "data_source": "sales_data_warehouse" },
    "object_level_visible": true       // 对象级安全生效后才返回
  },
  "response_ok": { "code": 0, "data": { "items": [ { "type": "metric", "id": "m_42",
      "name": "订单收入", "description": "唯一口径：paid_amount 求和",
      "matched_fields": ["metric_name","synonyms"], "score": 0.91,
      "payload": { "formula": "SUM(paid_amount)", "dimensions": ["date","region"] } } ],
      "total": 1 },
    "meta": { "trace_id": "t_xxx" } },
  "error": { "code": "SEMANTIC_SEARCH_INVALID_QUERY", "message": "query 不能为空" } }

② Action 执行（Foundry 提供 → AIP 写工具 / Swift 结算动作消费）

POST /api/v1/ontology/actions/{actionName}/execute：四模式（VALIDATE/RUN/ASYNC/VALIDATE_AND_EXECUTE）。HTTP 200 仅代表受理，成功判定以响应体 validation.result == "VALID" 为准；冲突返回 409 + ACTION_CONFLICT + latest_state。

{ "request": {
    "mode": "VALIDATE_AND_EXECUTE",
    "params": { "order_id": "o_1024", "new_status": "shipped",
                "_expected_updated_at": "2026-08-09T10:00:00Z" },  // 乐观锁期望值(可选)
    "actor": { "user_id": 7, "agent_id": null },                   // 人或 Agent 必有一
    "idempotency_key": "action_run_9f3a" },                        // 幂等键
  "response_ok": { "code": 0, "data": { "operation_id": "run_9f3a",
      "action": "update_order_status", "mode": "VALIDATE_AND_EXECUTE",
      "status": "succeeded",
      "validation": { "result": "VALID", "criteria_results": [ { "rule": "status_is_valid", "passed": true } ] },
      "edits": { "changed_records": 1 }, "affected_records": 1, "result": {} },
    "meta": { "trace_id": "t_yyy" } },
  "errors": [ "ACTION_VALIDATION_FAILED", "ACTION_NOT_AUTHORIZED",
              "ACTION_APPROVAL_REQUIRED", "ACTION_IDEMPOTENT_REPLAY",
              "ACTION_CONFLICT" ] }   // 409 + latest_state；客户端以最新状态重试

③ LLM 网关调用（AIP 提供 → Swift 风控 / Apollo 告警诊断消费）

POST /api/v1/llm/chat：task_type + model_alias（不填按路由表默认）；熔断时返回降级结果并置 degraded=true。

{ "request": { "task_type": "nlq", "model_alias": "main",
    "messages": [ { "role": "system", "content": "..." }, { "role": "user", "content": "..." } ],
    "options": { "temperature": 0.1, "max_tokens": 1024 } },
  "response_ok": { "code": 0, "data": { "content": "SELECT ...",
      "usage": { "prompt_tokens": 120, "completion_tokens": 40, "total_tokens": 160 },
      "provider": "deepseek-v4-flash", "model": "...", "latency_ms": 350, "degraded": false },
    "meta": { "trace_id": "t_zzz" } },
  "error": { "code": "LLM_PROVIDER_UNAVAILABLE", "message": "..." } }

④ bundle 制品（Apollo 打包 → AIP/Foundry 配置、Swift SSPM 更新消费）

结构 = bundle/{app}-{version}.tar.zst + manifest.json + SHA256SUMS.txt，整体 SM2 签名（升级版：签名清单 + signer 白名单）。Spoke 应用前校验顺序：① 逐文件 SM3 → ② 整体 SM2 验签 → ③ signer_id ∈ trusted_signers 白名单 → ④ 单调版本 → ⑤ 依赖就绪门控 → 应用。

{ "manifest": { "schema_version": "1.1", "app": "lightaip", "version": "1.2.0",
    "bundle_version": 42, "digest": "sm3:...", "signer_id": "ops-signer-01", "signature": "sm2:...",
    "files": [ { "path": "bundle/lightaip-1.2.0.tar.zst", "checksum": "sm3:...", "size_bytes": 123456 } ],
    "components": [ { "name": "server", "artifact": "bundle/lightaip-1.2.0.tar.zst", "type": "binary",
                      "checksum": "sm3:..." },
                    { "name": "llm_route", "artifact": "config/llm_routes.yaml", "type": "llm_route" },
                    { "name": "eval_set", "artifact": "eval/eval_v0.1.json", "type": "eval_set" },
                    { "name": "ontology", "artifact": "ontology/order.yaml", "type": "ontology_yaml" } ],
    "sbom": "sbom/cyclonedx.json", "channel": "STABLE", "created_at": "2026-08-08T10:00:00Z" } }

组件类型枚举：binary | config | llm_route | eval_set | ontology_yaml（配置/网关路由/评测集/本体 YAML 的分发载体；ontology_yaml 生产者 = Foundry ontology/export）。

⑤ 评测集制品（AIP 打包 → Swift 风控 NLQ 回归）

{ "schema_version": "1.0", "name": "nlq_v0.1", "version": 1,
  "cases": [ { "id": 1, "category": "nlq", "nl_query": "本月各区域收入",
               "expected_sql": "SELECT region, SUM(paid_amount) ...",
               "expected_result_fixture": {},
               "metric_or_object": "订单收入", "data_source": "sales_data_warehouse" } ],
  "metrics": ["sql_correct_rate", "exec_success_rate", "consistency"] }

随 bundle 分发，供目标机回归与跨产品复用。

⑥ 对象/动作模型（共享 ontology 包）

{ "object_type": { "name": "settlement", "display_name": "结算",
    "base_table": "sw_settlements", "pk_column": "id",
    "properties": [...], "links": [...],
    "actions": [ { "name": "reverse_settlement", "param_schema": {...} } ] } }

ObjectType/Property/LinkType/ActionType 的 Go 结构体与表结构即共享契约（Swift 结算对象建模、Gotham 图节点/边类型直接复用）。

四条红线

红线	来源	落地含义
R1 语义层是一等资产	research_overview 启示1；research_market §2.2（NL2Metrics 是准确率分水岭）	指标口径/业务术语/表列语义一体化；本体↔RAG 双向打通；不挂裸 LLM。落地：Foundry 指标语义层四层 + SemanticSearch；Gotham 图节点/边类型 = 本体 api_name。
R2 治理是 Action 路径内建约束	research_overview 启示2；research_aip §2.5（Rubix + Action 单一写路径）	一切写操作必须走 Action 定义（校验/授权/审计）；Agent 与人类同约束。落地：Foundry Action 写路径安全流水线；Gotham ABAC 挂 ontology_action；Apollo 部署/回滚全审计。
R3 单机优先 = 机制浓缩版	research_overview 启示3；research_apollo §4.1	Pull 模型/声明式/离线 bundle 做进内核，不做"先推送式后重来"。落地：Apollo 纯 Pull + 离线三区骨架；Gotham 内存图 + JSON 落盘；无 MQ/服务注册。
R4 共享同一套声明模型	research_apollo §2.5、§4.2；research_foundry §4.3	本体定义、Agent 配置、评测集、网关路由、期望状态都作为可版本化的声明制品，跨产品复用同一 Schema。落地：本体 YAML / 解析规则 / ABAC 策略 / 报告模板 / 期望状态全部声明式并随 bundle 分发。