OneScience Primitives Resource

Primitive Unification Scope

This skill is the unified OneSkills primitive registry. A primitive is any reusable scientific capability that can be recalled, bound into a plan, handed to an executor, or used as planning evidence. Primitives may be first-party OneScience resources or third-party tools, packages, databases, services, datasets, workflow patterns, output formats, validation contracts, and execution templates.

Task-Centric Knowledge Layer: TC 知识对象与传统资源原语同构同址——一律是 assets/<domain>/<category>/<primitive>/ 下的 metadata.json + knowledge.md 文档组，不新增 metadata 字段、不改字段名，因此 catalog_search 逻辑不变。对象类型由 type 区分：

• Task（type: task，category tasks/）：科研能力单元（如 material-property-prediction），含目标、输入输出契约、方法路线、操作序列、验证契约、实体槽
• Workflow（type: workflow，category workflow/）：以 Task 为节点的编排（如 material-screening-workflow）
• Scenario（type: scenario，category scenario/）：需求绑定与验收口径（如 material-candidate-screening）
• Resource（type: model | tool | dataset | ...，各资源 category）：被 Task 引用的资源，含带可运行脚本的资源卡
• Method / Operation / Validation：不单独建卡，作为 Task 卡 knowledge.md 的章节 + tags 词表边存在

知识图的全部连接关系编码在 tags 里（命名空间前缀 edge: / slot: / atom:），字段契约见 references/tc/card_contract.md。

Third-party tools can be primitives. Record the source through provider / provenance metadata and expose only distilled content through resource_retrieval_result; do not require a permanent bridge skill unless the provider needs its own retrieval backend, credentials, lifecycle, or access policy.

Use onescience-primitive-distiller when a new external scientific agent skill or third-party capability needs to be converted into primitive assets. This skill remains retrieval-only: it returns existing primitive content through the resource contract and does not perform distillation, migration, file creation, or script promotion itself.

When an application or workflow primitive depends on a specific primitive such as bio.tools.scanpy, expose that relationship through primitive_dependencies in the consumer metadata and mention the primitive_id in the consumer spec or workflow notes.

The preferred category set is open and includes models, components, datapipes, datasets, tools, databases, services, application, visualization, workflow-planning, contracts, and output-format, plus the Task-Centric categories tasks, workflow, and scenario. Preserve legacy category names when they already exist. TC 的 Workflow / Scenario 卡各自独占 workflow/ 与 scenario/ category，与 legacy 实例卡所在的 workflow-planning/ 物理隔离，不再做 workflow→workflow-planning 的别名归并。

你负责从 skills/onescience-primitives/assets/ 中找到最相关的 OneScience 原语，通过范围判定、快速过滤和语义匹配进行召回。不生成实现方案、不改代码、不执行脚本。

强制协议

本技能的 assets/ 目录仅供本技能内部使用。调用方（orchestrator / coder / 其他技能）不得：

• 直接 Glob / Read 本技能 assets/ 下的文件来获取原语信息
• 绕过 resource_retrieval_request 直接消费原语的 metadata.json、spec.md、usage.md 等文件内容
• 在未收到或构造 resource_retrieval_request 之前，禁止阅读或引用 assets/ 下的任何文件

调用方必须通过 resource_retrieval_request → resource_retrieval_result 的完整闭环获取资源。

协议范围豁免：当调用方已构造合法的 resource_retrieval_request（包含 user_request 和/或 filters），并按本技能「召回流程」中的步骤执行资源检索时，调用方可以使用以下工具操作——这属于本技能召回逻辑的执行，不是违规的直接消费。豁免范围分为两级：

优先路径 —— catalog_search + catalog_resolve：

• 使用 catalog_search 工具（kind=primitive, domain=..., q=...）搜索原语
• 使用 catalog_resolve 工具（part=body/contract/location）获取 companions 和契约
• catalog_search 搜索的是 OneCode 内置 catalog（含 bundled seed 原语），不依赖本地文件系统

降级路径 —— 文件系统 Glob/Read（仅当 catalog_search 无结果且确认 skills/onescience-primitives/assets/ 目录在本地存在时使用）：

• 枚举候选集（步骤 2）：Glob 列出资源目录
• 快速过滤/语义匹配（步骤 3-4）：Read 各资源的 metadata.json
• 内容组织（步骤 7）：Read 命中资源的 spec.md、usage.md、workflow_planning.md 及经白名单校验的执行资产
• 命名直查（命名直查模式步骤 3-4）：Glob 搜索目录名、Read metadata.json

调用方仍然不得沿 matched_resources[].path 自由读取任意文件，不得在未构造请求的情况下随意浏览 assets/ 目录，不得消费未在 execution_assets 白名单中声明的脚本或文件。

当本技能被上游技能调用时，resource_retrieval_request 是输入控制消息，不是需要回显给用户的最终内容。本技能直接执行召回流程并返回 resource_retrieval_result。

原语资产目录

assets/
  <domain>/
    <category>/
      <resource_name>/
        metadata.json            ← 基础信息（name, type, domain, description, tags, version）
        knowledge.md             ← 灵活单文档形态的完整正文（与下方三文件形态二选一）
        spec.md                  ← 规格知识（架构、参数、依赖）
        usage.md                 ← 使用知识（启动示例、接口、限制）
        workflow_planning.md     ← 规划决策知识（时机、流程、约束）
        references/               ← 可按需读取的扩展知识；仅允许 metadata 声明的文件
        scripts/                 ← 可选受控执行资产；必须由 spec.md 的 # execution_assets 结构化白名单 白名单声明

    scenario/                    ← Task-Centric Scenario 层（type=scenario）：需求绑定与验收口径，由 scenario_catalogs 场景 JSON 转换而来
      <scenario_name>/
        metadata.json            ← type=scenario；edge:workflow 指向 Workflow 卡；src:scenario_id 溯源
        knowledge.md
    workflow/                    ← Task-Centric Workflow 层（type=workflow）：以 Task 为节点的编排骨架
      <workflow_name>/
        metadata.json            ← type=workflow；edge:task / edge:step 展开到各 Task；src:scenarios_count 记归并场景数
        knowledge.md
    tasks/                       ← Task-Centric Task 层（type=task，与其他 category **平级**，不嵌套 resources）
      <task_name>/
        metadata.json            ← type=task；tags 承载 edge:/slot:/atom: 全部图边
        knowledge.md             ← 任务正文（目标、实体槽、输入输出契约、方法路线、操作序列、验证契约、资源引用、Task Graph、缺口与降级）
    workflow-planning/           ← 既有实例卡（legacy，type=workflow-planning）；不再存放 TC 的 scenario/workflow 卡
    models/ tools/ datasets/ datapipes/ components/
    application/ visualization/ databases/ output-format/ contracts/
                                 ← Resource 层：既有 category，与 scenario/workflow/tasks 平级；可运行资源在卡内 script/ 或 scripts/ 下

skills/onescience-primitives/references/tc/   ← TC 辅助索引（skill 内，**不进 assets 域树**）
  card_contract.md               ← 9 字段 + tags 边契约（替代原 schemas/*.yaml）
  atoms.jsonl                    ← 原子事实（数值级召回），靠 atom:<id> tag 回链卡片
    gaps.jsonl                     ← 缺口记录（retrieval_level != full 时追加）
  knowledge_evolution_log.jsonl  ← 知识演进日志（预留双向反馈闭环）

卡片双形态说明：资源目录支持两种形态——(A) 传统四文件形态（metadata.json + spec.md + usage.md + workflow_planning.md）和 (B) 灵活单文档形态（metadata.json + knowledge.md）。当目录中仅有 metadata.json 和 knowledge.md 时，knowledge.md 即为完整正文，必须读取。

当前 assets/ 顶层按 domain 组织，实际目录以仓库中的现状为准；当前可见的顶层 domain 包括：

• bio
• cfd
• climate
• matchem
• general

每个 domain 下的 category 目录可能不同，按实际存在的目录检索，不要求所有 domain 都具有同一套子目录。当前常见 category 包括：

• scenario ← Task-Centric Scenario 卡（type=scenario）
• workflow ← Task-Centric Workflow 卡（type=workflow）
• tasks ← Task-Centric Task 卡（bio / cfd / climate / general / matchem 五个 domain 均已建）
• components
• models
• datapipes
• application
• visualization
• workflow-planning ← legacy 实例卡（type=workflow-planning）
• contracts
• databases
• output-format

Task-Centric 知识检索路径

【重要】 当调用方的请求涉及科研任务规划、科研能力查询、工作流编排时，应优先使用 Task-Centric 知识检索路径，而不是传统的资源原语检索。

触发条件

当 resource_retrieval_request 中满足以下任一条件时，进入 Task-Centric 知识检索：

• intent 字段为 task、workflow、scenario 之一
• filters.task_id 或 filters.scenario_id 已指定
• user_request 中包含科研目标关键词（如“筛选”“预测”“验证”“排序”“性质计算”等）
• user_request 中包含方法选择需求（如“用什么方法”“哪种技术路线”）
• user_request 中包含工作流编排需求（如“流程是什么”“步骤有哪些”）

Task-Centric 检索步骤

0. 读契约（首次或边约定不确定时）：Read skills/onescience-primitives/references/tc/card_contract.md，明确 9 字段约定与 tags 边命名空间（edge: / slot: / atom: / runnable: / src:）及解析规则。

0b. 查确定性索引（TC 检索的第一动作，不可跳过）：Read skills/onescience-primitives/references/tc/scenario_task_index.json，按 domain + scenario_title（中文场景名）定位条目。条目的 entry_points 列出该场景全部入口卡（图谱 sc-* / 语义 / legacy workflow-planning），lineages 列出每条谱系的 workflow→tasks→resources 完整展开。命中条目时，必须把条目列出的每一层卡片 Read 原文并全部纳入召回结果，不得只取其中一张；exists=false 或 dangling_resources 非空的项按悬空边降级并记缺口，不得编造。仅当索引无命中（新场景、跨域、口语化描述）时才降级到下方关键词检索步骤。

1. 识别科研目标与 domain，并按 category 目录锁定 TC 层：从 user_request 判断科研目标与 domain。TC 三层各自独占一个 category 目录，先按目录锁层、再用 metadata.json 的 type 复核（目录与 type 必须一致）：

   • Scenario 层（需求绑定与验收口径）→ assets/<domain>/scenario/，卡 type=scenario
   • Workflow 层（以 Task 为节点的编排）→ assets/<domain>/workflow/，卡 type=workflow
   • Task 层 → assets/<domain>/tasks/，卡 type=task
   • 既有实例卡（legacy） → assets/<domain>/workflow-planning/，卡 type=workflow-planning，不是 TC 编排层

   定位方式：Glob assets/<domain>/scenario/*/metadata.json、assets/<domain>/workflow/*/metadata.json、assets/<domain>/tasks/*/metadata.json。TC 层已与 legacy 的 workflow-planning/ 物理隔离，无需再靠 Grep type 从上百张 legacy 卡里筛，误召回风险从结构上消除。

   硬规则：legacy 实例卡（workflow-planning/）仅当 TC Scenario / Workflow 无命中时才能作为补充证据返回，且必须标注 legacy_instance: true；不得用 legacy 实例卡替代 TC 链的任一层，也不得因此跳过 Scenario→Workflow→Task 的逐层展开。

   场景溯源：Scenario 卡通常由仓库外的 scenario_catalogs/<域>/*.json 场景需求书转换而来，原 scenario_id 记在 src:scenario_id tag 里（卡 name 用 kebab-case 英文或 sc-* 哈希，不等于 scenario_id）。请求里给的是中文场景名时，用 Grep src:scenario_id 定位，不要用 Grep name。

   入口不是终点（硬规则）：同一场景可能存在三类入口卡——语义 Scenario 卡、图谱 sc-* Scenario 卡、legacy workflow-planning 卡。legacy 卡已通过 edge:scenario:<卡名> / edge:workflow:<卡名> 接线，两类 Scenario 卡之间有 edge:alias:<卡名> 互指。无论从哪张卡进入（包括关键词 Grep 只命中一张 Task 卡或 legacy 卡的情况），都必须提取场景身份（顶层 scenario_id 字段、src:scenario_id tag、description 中的场景名、或 edge:scenario:* 边），反查定位 Scenario 卡，然后执行步骤 6 的完整展开；命中任何单张卡即停止检索、直接进入提问或规划，属协议违规。

2. Task 检索（catalog 优先）：

   • 优先 catalog_search（kind=primitive, domain=, q=<目标关键词>），命中 type=task 的卡
   • catalog 是发布时快照：新建的 TC 卡可能尚未进 catalog，无结果属正常，此时必须走文件系统降级路径，不得就此判定「无命中」
   • catalog_search 无结果时降级：Glob assets/<domain>/tasks/*/metadata.json → Read 各 metadata.json，按 description / tags 语义匹配
   • filters.task_id 已指定时命名直查：Glob 目录名 → Read metadata.json

3. 实体槽精确匹配：从请求抽取实体（如 CO₂ / MOF / band_gap），与 Task 卡 slot:* tags 求交集。无交集时不得硬套该 Task：改道（见步骤 8）或降级并记缺口。

4. 读 Task 正文：Read 命中 Task 的 knowledge.md，取方法路线、操作序列、验证契约、输入输出契约与已知缺口。（仅有 metadata.json + knowledge.md 时，knowledge.md 即完整正文，必读。）

5. Resource 关联（沿 tags 边）：解析 edge:resource:<category>/<name> → 同 domain 的 assets/<domain>/<category>/<name>/，Read 其 metadata.json（必要时 knowledge.md 或四文件形态）。解析不到目录 = 悬空边：该资源判缺失，不得编造其能力，计入降级与缺口。

6. Task Graph 完整展开：解析 Scenario 的 edge:workflow:* → Workflow 的全部 edge:task:*（不得只取一个 Task），再对每个 Task 解析其 edge:resource:*；并用 edge:prev:* / edge:next:* 校验顺序一致性。输出必须给出「场景 → 工作流 → 各 Task → 各资源」的逐层卡片路径凭证；某一 Task 的资源边悬空时，只降级该 Task，不得连带丢弃整条链。

   检索纪律（硬规则）：

   • ① Grep / Glob / catalog 输出中出现截断提示（truncated、结果数达上限等）时，必须缩小检索范围（按 category 目录、更精确的关键词）重查直至无截断，禁止基于截断输出下「无命中 / 只有 N 个」的结论。
   • ② 检索结果中出现同一场景的多张卡（语义 Scenario 卡、sc-* 图谱卡、legacy 卡、多张 tk-* / it-* 任务卡）是 Task Graph 存在的信号：必须把它们聚合成同一条链后按本步骤展开，不得只挑其中一张读完就停。
   • ③ 在向用户提问、宣布 BLOCKED、或输出任何规划之前，必须先给出本步骤要求的逐层路径凭证表（含每一层的卡片相对路径与命中方式）；凭证不完整即视为检索未完成，禁止进入下一环节。

6b. 泛化与复用判定（上层需求是「一个场景能不能复用已有 Task」时必做）：

• 读 Workflow 骨架卡的 src:scenarios_count 与 src:scenario_family，得到这张骨架归并了多少个场景；泛化率 = src:scenarios_count : 该 Workflow 的 edge:task:* 数量。
• Workflow 的 edge:step:<step_id>:<task> 给出源场景步骤到 Task 卡的映射，用它说明「源 workflow 的第几步落在哪张卡」。
• 判定某张 Task 是新建还是复用：Grep 该 Task 的 name 于 assets/<domain>/，看它被多少张其他卡引用（被 2 条以上 Workflow 或其他 Task 的 edge:prev/next 引用 = 已复用骨架），并把 Grep 模式与命中数作为凭证输出。
• 请求的场景在 src:scenario_id 中无精确命中、但其骨架族匹配时：仍可用该 Workflow + Task 骨架，把场景差异落到 slot:* 取值上，并在输出里标注「骨架匹配、场景未建卡」，不计为悬空边。

7. Atom 检索（数值级，可选）：请求涉及具体数值或判据（如“精度多少”“形成能阈值”）时，先取 Task 卡的 atom:<id> tags，再 Read skills/onescience-primitives/references/tc/atoms.jsonl 按 atom_id 定位；无 tag 时按 statement 关键词匹配。

8. 前提核验与改道：核对方法路线前提（势函数覆盖范围、算力与求解器可用性、阈值/权重是否可审计）。前提不满足 → 按 edge:fallback_method:* 改道，并在输出中写明改道原因与精度/成本影响。

9. 分层降级判定：确定 retrieval_level（task_centric 路径产出）：

   • full：Task 卡命中 + 全部 edge:resource:* 解析成功 + 至少一个操作有可执行或可规划落点
   • partial：Task 命中，但部分资源悬空/缺失（≥1 个资源解析成功）
   • task_only：仅命中 Task 卡（返回目标与输入输出契约作为方法框架，显式声明缺口）
   • none：无 Task 命中

9b. 跨路径实质命中判定（决定 knowledge_gap——在线兜底触发的唯一依据，必做、不可跳过）：retrieval_level 只在 task_centric 路径产生；当请求走 traditional_resource 路径、或 TC 层无卡而回退到 legacy workflow-planning/ 平铺卡时，retrieval_level 不足以反映「到底查没查到领域知识」。因此无论走哪条路径，都必须再判定一次 knowledge_gap：

• 领域实质命中（knowledge_gap=false，本地可答）：命中了与 user_request 的目标 domain + 具体研究对象/属性/方法直接相关的可执行 Task 卡，或领域专属资源卡（model / tool / dataset / datapipe / component / database / contract / scenario / workflow 等），足以支撑对该具体科学问题的准确回答。full 与 partial 均属实质命中。
• 没查到领域知识（knowledge_gap=true，触发在线兜底），满足任一即是： a. task_centric 路径 retrieval_level ∈ {none, task_only}； b. traditional_resource 路径 matched_resources 为空； c. matched_resources 仅由泛化规划/流程卡构成——即全部条目都是 workflow_planning_primitive（或标注 legacy_instance: true 的通用「文献综述 / 通用分析 / 通用建模流程 / 通用四步筛选」类卡），而无任何与目标 domain 具体研究对象直接相关的领域专属资源或 Task； d. 命中资源的 domain 与请求目标 domain 不一致（如问 cfd 却只命中 general 域通用流程卡），且无该 domain 的实质资源。
• 铁律：泛化 workflow-planning 卡只描述「怎么做研究」的通用流程，不构成对具体科学问题的领域知识回答。仅命中此类卡一律等同「没查到」，必须置 knowledge_gap=true，不得当成「有资源可用」继续往下走。

10. 缺口记录：retrieval_level != full 或 knowledge_gap=true 时，向 skills/onescience-primitives/references/tc/gaps.jsonl 追加一行 JSON：{ts, domain, task, retrieval_level, knowledge_gap, request_slots{}, missing_resources[], dangling_edges[], suggested_fill, domain_match_summary{exact, adjacent, cross_domain}, gate_hit, gate_layer}。只追加、不删改历史记录。

    • domain_match_summary：在线兜底完成后按 step 11 的 domain_match 标签统计三档数量；未触发兜底时三档均填 0。
    • gate_hit：∈ {domain_mismatch, bare_number_reject, result_identity_lock, validation_rollback, complete_downgrade, null}。本技能只在 A 层门禁命中时填 domain_mismatch（cross_domain 文献被当参数来源、或兜底后 exact=0）；B/C/D 层由 orchestrator 命中后追加各自 gate_hit 行（同一 gaps.jsonl，四层共用，便于 A/B 归因统计）。
    • gate_layer：∈ {A_knowledge, B_planning, C_execution, D_acceptance}，与 gate_hit 配套。

11. 在线兜底检索（knowledge_gap=true 时强制触发——即 step 9b 判定「本地没查到领域实质知识」，涵盖 none / task_only / 空召回 / 仅命中泛化 workflow-planning 卡 / domain 不符 五种情形）：本地资产已无法产出准确完整的回答 → 调用 onescience-live-literature 技能联网兜底：把上层需求转成该技能 Step 1 的查询分解，走两级在线检索（OpenAlex 摘要层迭代精炼 + Europe PMC/PMC 全文层取细节），产出带连续编号引用 [n] 的分层综合答案作为兜底。兜底硬约束：① 答案顶部显式标注「⚠ 本地知识缺口（knowledge_gap=true, retrieval_level=<none|task_only|empty|generic_only>），以下为在线文献兜底结果」；② 全程遵守 live-literature 的纪律铁律（只引池内论文、数值/极性有出处、abstract-only 降权标注、失败通道显式报告）；③ 在 step 10 已写入的 gaps.jsonl 缺口行 suggested_fill 末尾追加「已触发在线兜底」；④ 兜底答案是补充而非替代——若仍有任意本地 Task/资源命中，须一并列出本地凭证；⑤ 严禁编造：knowledge_gap=true 时不得用泛化 workflow-planning 剧本假装完成、不得返回「模拟检索结果 / 模拟数据 / 默认参数 / 历史案例」充数；联网通道不可用（离线）时不得报错、不得中断整个任务：如实标注「本地知识缺口 + 当前离线，在线兜底不可用」，把该缺口作为已知限制交回上层，由上层继续执行任务其余部分（离线不构成 blocked，更不是编造模拟数据的理由）。⑥ 单一集中通道 + 证据并回召回结果：本 step 11 是在线兜底的唯一集中执行点；兜底产出的带编号引用与接地事实必须以 online_evidence 字段并入本技能召回结果（见输出格式），作为上层规划/执行消费文献证据的唯一来源；orchestrator 见到 online_evidence 非空时不得重复触发检索（单次集中通道，防限流/防双跑）。⑦ 召回阶段证据边界（严禁自造）：召回结果中不得填入任何未经「用户提供 / 本地卡 / 在线引文[n]」支持的参数、阈值、数据集或研究对象；无法支持的项只能标 proposed_candidate(待确认) 或留空，绝不伪造。⑧ domain_match 标签与跨域降级（A 层门禁，修 ws07 文献场景错配）：兜底产出的 online_evidence.citations[] 每条必须带 domain_match ∈ {exact, adjacent, cross_domain} 标签——exact=文献研究对象与本任务目标域及具体研究对象直接一致（如本任务问数据中心浸没液冷，文献即研究 immersion cooling of data center/server rack）；adjacent=同目标域但不同冷却方式/子场景（如 data center 但 air-cooled、liquid-cooled battery 但非机柜级）；cross_domain=不同应用领域（如电池热管理、PCM 储能、铸造、氢能）。cross_domain 文献只能作为方法学参考（验证思路、网格无关性方法、湍流模型候选），不得作为本次参数/阈值/几何/工况来源；违反时该参数降级为 proposed_candidate(待确认) 并向 gaps.jsonl 追加 gate_hit=domain_mismatch, gate_layer=A_knowledge。兜底完成后若池内 exact 数为 0：必须要求 live-literature 触发第二轮场景锚词精炼检索（锚词=目标域+具体研究对象，如「immersion cooling」+「data center」）；仍为 0 则在 online_evidence 顶部如实标注「在线兜底形式成功、实质未命中目标域（exact=0）」，相关科学结论保持 BLOCKED/诚实 PARTIAL，不得用 adjacent/cross_domain 文献硬凑本次参数。knowledge_gap=false（full / partial / 命中领域专属资源）不触发兜底，仍走本地链，仅在缺口处按 step 10 记录。

12. 可执行落点识别：若 Task 的 edge:operation:* 在某资源卡上有对应实现，且该卡带 runnable:script tag，则该操作本机可执行：输出中给出脚本相对路径与可直接运行的命令；否则标注「无可执行落点，仅规划」。

13. 组织输出：按下方输出格式返回。

Task 检索与传统资源检索的桥接

• Task 卡的 edge:resource:<category>/<name> 指向的就是传统原语目录（如 edge:resource:models/mace → assets/matchem/models/mace/），解析成功后按传统路径 Read 其 metadata.json + knowledge.md（或 spec.md / usage.md / workflow_planning.md）。
• 悬空边（无对应目录）视为资源缺失：不得编造资源能力，计入 partial 降级并写 gaps.jsonl。
• 反向边：资源卡可用 edge:task:<name> 声明被哪些 Task 引用（如 prediction-metric-calculator → prediction-accuracy-evaluation），便于从资源侧回查任务。
• Task / Workflow / Scenario 卡与传统资源卡共用同一套检索基础设施（catalog_search 优先 + 文件系统降级），无需第二套索引文件。

---

召回流程

【检索路径优先级】：OneScience 原语资产可能存储在两处：

1. 数据库/Blob Store（通过 catalog_search + catalog_resolve 访问）：bundled seed 或已同步至 OneCode 内置 catalog 的原语。这是默认检索路径，优先级最高。
2. 本地文件系统（通过 Glob + Read 访问 skills/onescience-primitives/assets/）：通过 oneskills 安装器解压到磁盘的原语。这是降级检索路径，仅在路径 1 无结果且确认本地 assets 目录存在时使用。

强制规则：

• 执行召回时，必须先尝试路径 1（catalog_search），不得跳过。
• 仅当 catalog_search 返回空结果，且确认 skills/onescience-primitives/assets/ 目录在本地存在时，才回退到路径 2（文件系统 Glob/Read）。
• 回退到路径 2 后，命名直查和常规召回管道的文件系统操作规则（步骤 0-9）仍然适用。

本技能没有统一索引文件，原语信息以各资源目录下的 metadata.json 为主。因此必须先确定检索范围，再枚举该范围内的资源目录并逐个读取 metadata.json，不要凭目录名猜测。

【路径规范】：本技能所有 assets/ 目录的绝对路径为 skills/onescience-primitives/assets/。资源目录采用三层嵌套结构：<domain>/<category>/<primitive_name>/（如 bio/visualization/complex_structure_visualization/）。在以下步骤中，凡出现 assets/<domain>/ 或 assets/<domain>/<category>/ 等路径，均指代相对于仓库根目录的 skills/onescience-primitives/assets/<domain>/...。使用 Glob 搜索候选资源时必须使用 ** 递归模式（如 assets/bio/**/metadata.json），不得使用单层 * 导致遗漏嵌套子目录。使用 Read 工具访问资产文件时，必须拼接完整路径前缀 skills/onescience-primitives/，不得使用不包含此前缀的相对路径。

【命名直查优先】：在执行常规召回管道（步骤 0-6）之前，必须先检查是否满足命名直查条件。

命名直查模式

当调用方明确知道目标原语名称时，跳过召回管道，直接定位并返回该原语。

触发条件（同时满足以下两项时进入命名直查）： a. filters.keyword 中包含一个可识别的原语名称（如 complex_structure_visualization、alphafold3、openfold_data_pipeline 等——即 assets/<domain>/<category>/ 下的某个目录名） b. filters.domain 已明确指定（如 bio、cfd、climate、matchem）

命名直查执行步骤：

1. 从 filters.keyword 中提取原语名称候选（将关键词按下划线连接、去空格、去标点等规范化处理后，与目录名比对）
2. 优先使用 catalog_search：调用 catalog_search 工具（kind=primitive, domain=<filters.domain>, q=<从 keyword 提取的名称>）。若命中，直接使用 catalog_resolve 获取 body/contract，并跳转到步骤 6。
3. 回退到文件系统：若 catalog_search 未命中且确认 skills/onescience-primitives/assets/ 目录存在，则在 skills/onescience-primitives/assets/<filters.domain>/ 下递归搜索匹配的目录名（使用 Glob 搜索 skills/onescience-primitives/assets/<domain>/**/<name>/metadata.json，其中 <domain> 替换为实际 domain 值如 bio，<name> 替换为从 keyword 提取的目录名）。必须使用 ** 递归匹配，不得使用单层 *。
4. 若找到唯一匹配，直接读取该目录的 metadata.json；若找到多个匹配（跨 category），读取所有匹配并取 domain 和 keyword 语义最接近的一个
5. 若未找到匹配，回退到常规召回管道（步骤 0-6）
6. 命中后，直接跳转到步骤 7（组织内容），跳过步骤 0-6 的枚举、过滤、语义匹配和截断
7. 命名直查命中的资源在 why_matched 中标注 named_lookup，说明是通过名称直查而非语义匹配

重要约束：

• 命名直查是精确匹配辅助机制，不是语义搜索的替代品
• 若 keyword 同时包含多个候选名称，对每个名称分别执行直查
• 命名直查仍然遵守内容组织规则（步骤 7-9），包括执行资产白名单校验
• 命名直查不绕过强制协议：调用方仍需通过 resource_retrieval_request 发起，不得直接读取 assets

---

常规召回管道

以下步骤仅在命名直查未命中时执行。

0. 优先使用 catalog_search：首先调用 catalog_search 工具（kind=primitive），传入 domain、keyword 等过滤条件。若返回非空结果，直接对结果项使用 catalog_resolve(part=body) 获取完整内容，跳过后续文件系统枚举步骤。仅当 catalog_search 无结果时，继续执行以下文件系统流程。

   判定 domain scope：先判断调用方是否通过 filters.domain 显式提供 domain。

   • 若 filters.domain 明确给出，则直接使用调用方提供的 domain，只检索对应的 skills/onescience-primitives/assets/<domain>/，且不要再读取 skills/onescience-primitives/references/domain_profile.md 做二次判断
   • 若 filters.domain 未提供、为空或不可靠，则必须先读取 skills/onescience-primitives/references/domain_profile.md，再结合 user_request 与 task_state_summary 按其中定义的领域信号进行回退判定
   • 回退判定结果若为 climate | cfd | matchem | bio | general，则只检索对应的 skills/onescience-primitives/assets/<domain>/
   • 回退判定结果若为 unknown，说明无法稳定路由到单一领域；此时允许检索 skills/onescience-primitives/assets/ 下全部 domain 目录，但输出中的 detected_domain 必须保持为 unknown
   • 当请求已路由到生信领域，且涉及生信工作流、模型/数据管线/应用选择或多候选资源取舍时，可读取skills/onescience-primitives/references/bio_profile.md文档作为召回提示；该文件只辅助候选排序和边界解释，不能替代 metadata.json 证据

1. 判定 category scope：根据 user_request、content_request、filters.keyword、task_state_summary 判断是否明确指定资源类别。

   • 若明确指定模型、组件、数据管线、应用、可视化规范、工作流规划、输出格式、契约或数据库/服务类资源，则只检索对应 category
   • 若未明确指定，则检索当前 domain scope 下全部实际存在的 category 目录
   • 【强制】可视化信号识别：当 user_request 或 filters.keyword 中出现以下任一信号时，必须将 visualization 纳入检索范畴：
     • 显式可视化词：可视化、visualization、visualize、visual、render、rendering
     • 三维结构渲染词：3D、三维、结构展示、structure view、interactive、交互式
     • 置信度着色词：pLDDT、PAE、confidence coloring、B-factor、chain coloring
     • 分子可视化工具名：PyMOL、3Dmol、MolStar、NGL、cartoon、ribbon、surface、stick
     • 结构文件格式（需渲染）：.pdb、.cif、.mmcif、.pse、.pml
     • 当上述任一信号出现时，即使主意图被判定为 model/datapipe/application，也必须将 visualization category 纳入检索范围，不可遗漏

2. 枚举候选集：在已确定的 domain/category scope 内，使用 Glob 递归搜索 skills/onescience-primitives/assets/<domain>/**/metadata.json（必须使用 ** 递归匹配，不得使用单层 *），得到完整候选集。从每个匹配路径中提取三层信息：domain（assets/ 后第一段）、category（domain 后第一段）、primitive_name（category 后第一段）。示例：路径 assets/bio/visualization/complex_structure_visualization/metadata.json → domain=bio, category=visualization, primitive_name=complex_structure_visualization。后续所有路径拼接必须保留完整的 <domain>/<category>/<primitive_name>/ 三层结构，不得省略中间 category 层。

3. 快速过滤：仅当 filters.keyword 提供了关键词时执行；结合目录名、metadata.json 的 name、domain、description 与 tags 排除明显不相关的资源。未提供关键词时跳过本步。

4. 语义匹配：遍历剩余每个候选资源的 metadata.json，对比 user_request 与 description 字段的语义相关性。

5. 上下文增强：结合 task_state_summary 进一步筛选和排序，但不能用上下文替代资源本身的证据。

6. 按匹配度排序并截断：按语义相关性排序，返回最相关的 5-8 个资源；没有强相关资源时返回空列表，不要凑数。

   • 【强制】多类别覆盖保障：当检索范围为全部 category（即未限定单一 category），且候选集中存在多个 category 的实际资源时，截断必须满足以下覆盖规则： a. 先按语义匹配度排序得到全序列表。 b. 从高到低选取前 5 个资源（保障核心语义匹配质量）。 c. 检查这 5 个资源是否覆盖了候选集中所有实际存在资源的 category。若某个 category 中的全部资源均未进入前 5，且该 category 中存在至少一个资源的语义匹配度不低于最高分的 60%，则从该 category 中取匹配度最高的 1 个资源追加到结果中（即使超出 5-8 范围也不得丢弃）。 d. 追加后结果总数不超过 10 个；若超过 10 个，按语义匹配度去掉末尾超出部分。 e. 追加的资源在 why_matched 中备注 category_coverage 标签，说明其被保留是因为类别覆盖而非纯语义排序。
   • 说明：此规则确保当查询信号隐含多类别需求（如"分析蛋白质结构预测结果并可视化"），visualization 类资源不会因 model/component 类资源在纯语义排序中得分略高而被截断丢弃。

7. 逐个组织内容：对每个命中的资源，按 content_request 分别读取并填充该资源的 content 字段：

   • 留空或 "摘要"：优先只读取 metadata.json，生成简短摘要，description 字段的关键信息不进行过度压缩
   • "使用说明"：读取 usage.md（若存在）；若不存在且存在 knowledge.md，则读取 knowledge.md
   • "规格说明"：读取 spec.md（若存在）；若不存在且存在 knowledge.md，则读取 knowledge.md
   • "工作流规划知识"：读取 workflow_planning.md（若存在）；若不存在且存在 knowledge.md，则读取 knowledge.md
   • "完整知识正文"：读取 knowledge.md（若存在）；这是灵活单文档形态卡片的完整正文
   • "参考资料" / "扩展知识"：只读取 metadata.json 中 knowledge_assets 声明的 references/ 文件，并按主题组织返回
   • "完整内容"：读取 metadata.json、spec.md、usage.md、workflow_planning.md 及 knowledge.md（若存在）和 knowledge_assets 索引；不得因为请求完整内容而自动返回全部参考文件或任意脚本。当目录中仅有 metadata.json + knowledge.md 时，knowledge.md 即完整正文，必须读取
   • "完整参考资料"：在路径、大小和 SHA-256 校验通过后，读取 knowledge_assets 声明的参考文件；大文件按物化规则处理
   • 当且仅当 include_execution_assets: true 时，按以下子步骤物化受控执行资产： a. 读取命中资源的 spec.md，定位唯一的一级标题

   execution_assets。

   读取该标题后紧邻的第一个 yaml 代码块，并从根字段 execution_assets 获取白名单数组。