召回 API

输入

json

{
  "prompt": "Fix UI and validate in browser",
  "provider": "codex",
  "cwd": "/path/to/project",
  "limit": 4,
  "budget": {
    "maxChars": 6000
  }
}

Task Envelope

json

{
  "summary": "Fix UI and validate in browser",
  "language": "en",
  "taskTypes": ["ui"],
  "surfaces": ["ui"],
  "risks": [],
  "operations": ["fix"],
  "constraints": [],
  "files": [],
  "commands": [],
  "intentModes": ["execute"],
  "ruleSignals": [
    {
      "id": "explicit_execute",
      "polarity": "positive",
      "weight": 8,
      "reason": "explicit execution wording"
    },
    {
      "id": "ui_surface",
      "polarity": "positive",
      "weight": 8,
      "reason": "UI, frontend, or browser surface wording"
    }
  ],
  "keywords": ["UI", "browser", "validate"],
  "negativeKeywords": [],
  "segments": ["Fix UI and validate in browser"],
  "length": 30
}

Match Output

json

{
  "rank": 1,
  "id": "browser-validation",
  "title": "Browser Validation",
  "score": 82,
  "rawScore": 12.4,
  "rankScore": 32.1,
  "postSelectionScore": 82,
  "evidenceFamilies": ["triggers", "signals"],
  "strongAnchor": true,
  "recallPolicy": "must",
  "risk": "high",
  "confidence": "high",
  "summary": "Open the real browser after UI changes.",
  "card": {
    "libraryScope": "project"
  },
  "reasons": [
    { "field": "triggers", "term": "browser validation", "weight": 52, "kind": "phrase-exact" },
    { "field": "ruleSignals", "term": "ui_surface", "weight": 48, "kind": "UI, frontend, or browser surface wording" }
  ],
  "similarCards": []
}

active 卡片的 scope 与检测到的 projectContext 不匹配时，会在评分前被过滤掉。

CLI explain surface 会把同一数据包裹成 envelope 和 query diagnostics：

bash

ome match "Fix UI and validate in browser" --explain --json

json

{
  "ok": true,
  "threshold": 40,
  "limit": 4,
  "diagnostics": {
    "engineVersion": "sparse-v2",
    "scorerVersion": "bm25f-evidence-v2",
    "threshold": 40,
    "limit": 4,
    "inputCardCount": 1,
    "applicableCardCount": 1,
    "evaluatedCardCount": 1,
    "timedOut": false,
    "complete": true,
    "candidateListTruncated": false,
    "abstained": false,
    "abstainReason": null,
    "selectedCardIds": ["browser-validation"],
    "candidates": [
      {
        "id": "browser-validation",
        "libraryScope": "project",
        "score": 82,
        "rawScore": 12.4,
        "rankScore": 32.1,
        "postSelectionScore": 82,
        "priorityScore": 7,
        "evidenceFamilies": ["triggers", "signals"],
        "strongAnchor": true,
        "eligible": true,
        "selected": true,
        "rejectionReason": null,
        "reasons": []
      }
    ]
  },
  "queryVariants": ["Fix UI and validate in browser", "ui test browser validate"],
  "projectContext": {
    "projectKey": "github.com/example/app",
    "modulePath": "apps/web",
    "source": "git"
  },
  "libraries": [
    { "scope": "global", "exists": true, "readable": true },
    { "scope": "project", "exists": true, "readable": true }
  ],
  "matches": [
    {
      "rank": 1,
      "id": "browser-validation",
      "score": 82,
      "rawScore": 12.4,
      "rankScore": 32.1,
      "postSelectionScore": 82,
      "evidenceFamilies": ["triggers", "signals"],
      "strongAnchor": true,
      "card": {
        "libraryScope": "project"
      },
      "reasons": [
        { "field": "ruleSignals", "term": "ui_surface", "weight": 48, "kind": "UI, frontend, or browser surface wording" }
      ],
      "similarCards": [
        {
          "id": "browser-validation-overlap",
          "title": "Browser smoke checklist",
          "score": 82,
          "reason": "标题、触发词或主题高度接近"
        }
      ]
    }
  ],
  "additionalContext": "# OME Matched Experience Cards\\n\\nMatched cards are optional reminders, not required reuse.\\n- Choice: You may apply a whole card, use only the useful parts, or ignore any match that does not fit the task.\\n- Before acting: If a card helps, say one short sentence about what OME reminded you to consider, then proceed.\\n- Final: If any card was used, state how many cards were used and include only the applied `Final link if used` values; omit this line if none.\\n..."
}

libraries 描述本次 match 使用的全局/项目经验库栈。项目卡会带 libraryScope: project；渲染出的完整卡片命令会使用 ome experience show CARD_ID --scope project --section rule。

similarCards 列出因为近似重复而从 ranked output 中省略的卡片。Renderer 可以提到这些 omitted related cards，但不应注入重复的完整经验。

不同 score 字段有不同契约：

score 是不随 corpus 大小漂移的 0-100 evidence score，用于 configured threshold；
rawScore 是只用于 ranking channel 的 BM25F sparse value；
rankScore 是 deterministic reciprocal-rank-fusion 结果；
postSelectionScore 是 selection pipeline 之后的 evidence score；
priorityScore 出现在 candidate diagnostics 中，只作为来自 card metadata 的 non-relevance tie-breaker。

diagnostics 让 rejection 和 abstention 可解释，同时不记录 raw prompt。它包含 retrieval versions、counts、completeness、selected ids 和有上限的 candidate list。 candidateListTruncated 明确说明列表是否省略候选行，evaluatedCardCount 保留总数。Rejected candidates 保留 rejectionReason 和正负 reasons。没有 candidate 越过 evidence contract 时，abstained 为 true、matches 为空；引擎不会用弱卡填满 limit。

ruleSignals 是从 prompt 派生出来的 registered 内部召回提示。正向 engine hint 提供 evidence 或 routing gate；负向 hint 只压制其声明的 targets。它们是启发式，不是最终使用标准。Hook 上下文展示自然语言使用标准和自然语言命中原因，不暴露 hint id。

additionalContext 的框架提示固定使用英文，且只包含紧凑索引信息。卡片规则正文不会被注入。命中卡片只是候选，不代表 Agent 已经采用。框架会要求 Agent 逐条判断：可以完整采用、只采用相关部分、忽略无关或冲突卡，或在全部不贴合时全部弃用。Agent 只在判断适用后再读取规则，并在最终回复里只披露实际使用过的卡。披露行应使用用户回复语言，说明实际使用了几张 OME 经验卡，并且只包含已采用卡片的 Final link if used 链接。复盘或来源扫描任务中，命中的主题旧卡是 active overlap 信号，不是来源证据，应写入复盘审计而不是披露为 used card。卡片标题会渲染为指向相关经验卡路径的 Markdown 链接。

Budgeted Context

json

{
  "cards": ["browser-validation"],
  "additionalContext": "...",
  "truncated": false,
  "budgetUsedChars": 1200
}

召回 API ​

输入 ​

Task Envelope ​

Match Output ​

Budgeted Context ​

召回 API

输入

Task Envelope

Match Output

Budgeted Context