oma-search

搜索路由

调度

目标

根据请求选择所需的搜索或检索渠道，并返回来源及其支持证据和检索限制。

意图特征

• 查找外部文档、网络信息或远程实现示例。
• 读取已知外部 URL，或向其他技能提供外部来源。

适用场景

库文档、网络研究、远程代码搜索、读取已知 URL，以及需要选择外部来源渠道的请求。

不适用场景

• 纯本地代码探索 → 直接使用 ../_shared/core/code-intelligence.md 中配置的代码智能；不要调用此技能。
• Git 历史记录或 blame → oma-scm；架构分析 → oma-architecture。

预期输入

查询或已知 URL；可选路由提示（docs、web、code、fetch）；版本、新近程度、主机、仓库和来源限制；可选的网络搜索提供方覆盖项。显式指定 --docs、--code 或 --web 可选择搜索路由。--gitlab 可选择远程代码主机。--strict 要求提供适当的主要或官方来源，并检查其支持内容；--wide 会纳入范围更广的结果及其局限。这些修饰项会保留请求的来源限制。

预期输出

答案或相关来源列表，包含来源 URL／文件引用、路由、实际提供方、来源类型、内容读取状态、支持证据和重大限制。若能观察到，需注明发布日期、检索日期和版本详情。不要编造结果、日期、来源或确定性。

依赖项

文档使用 Context7；网络发现使用已配置的 providers.web（native、brave 或 exa）；远程代码使用 oma search code／gh／glab；已知 URL 使用运行时检索工具或 oma search fetch。oma search providers 会报告注册、选择和凭据元数据；oma doctor 会检查凭据是否存在，但不会验证凭据有效性或 API 可访问性。

结构流程

路由

路由	执行方式	范围
docs	使用 Context7 解析库并执行查询；必要时发现官方网站	请求版本限制内的官方文档
web	使用已选定的网络搜索提供方：native 使用运行时工具，brave 或 exa 使用 CLI 适配器	发现与查询相关的 URL
code	通过已选定的代码主机使用 oma search code	主机／仓库限制内的远程实现匹配项
fetch	使用可用的 URL 阅读器／浏览器或 oma search fetch <url>	读取已提供或已发现的 URL

失败与恢复

• 文档查找缺失或结果为空：在保留文档路由的版本和来源限制的同时，发现官方网站。
• 已选定的网络搜索提供方不可用、未经身份验证或受到速率限制：报告其失败。不要在未说明的情况下用原生搜索替换明确指定的提供方。
• 搜索未返回候选 URL：在原有限制内调整查询，或报告无结果。URL 检索不能替代缺失的搜索结果。
• 无法读取已知 URL：使用针对检索的恢复参考，并保留访问／身份验证错误及存档来源信息。
• 没有来源满足 --strict：报告来源或证据缺口。结果范围更广并不意味着自动满足严格请求。

退出

返回有依据的结果，并披露失败的路由、未读取的来源、过时或存档内容以及版本限制。提供方名称或域名标签不能证明具体说法属实。

逻辑操作

标准工作流路径

1. 确定请求的结果和约束。纯本地代码请求直接交给已配置的代码智能工具处理。对于外部工作，选择一条主要路径；仅在选择不明确时使用 resources/intent-rules.md。
2. 按照 resources/execution-protocol.md 执行该路径。根据配置或请求中的覆盖项确定网络提供方。只有在剩余证据缺口需要时才增加另一条路径；默认不要分散到多条路径。
3. 阅读支撑答案所需的相关内容。保留 URL 和检查状态，对结果去重，并应用来源／版本约束。有关来源规则或明确需要的可选领域诊断，请使用 resources/trust-registry.md；普通结果无需进行数值查询。
4. 根据与问题的相关性和来源适用性排序。返回所请求的答案或来源，并附上证据、实际使用的路径／提供方及重要限制。

CLI 入口

oma search providers
oma search web "<query>" [--provider <id>] [--limit <n>]
oma search code "<query>" [--host gitlab] [--language <lang>] [--repo <owner/repo>]
oma search fetch <url>
oma search trust <domain>

仅当所选操作需要相应基本功能时，才使用 api、rss、meta、media、archive 或 doctor。trust 仍是可选的领域诊断工具。

防护措施

• 保留明确指定的路径、提供方、来源、主机、版本和日期约束。
• 将查询发现与读取现有 URL 分开处理。
• 将搜索摘要和摘录视为有限证据；指出尚未阅读的来源。
• 不要编造信任评分，也不要仅凭提供方或托管域名，就将 Context7／GitHub 结果提升为可验证声明。
• 不要重复已成功的路径，不要通过网络搜索本地项目文件，不要安装提供方，也不要自动跟踪代码库。

资源范围和影响

搜索可能会联系外部服务，并启动已配置的提供方或代码托管平台进程。检索可能会启动可用的浏览器。查询约束和来源信息属于会话上下文；持久缓存应存放在生成状态中，而非技能定义中。本地源码导航应交由已配置的代码工具处理。

参考资料

• 路径选择：resources/intent-rules.md（外部请求不明确时）
• 执行：resources/execution-protocol.md（仅限所选路径）
• 来源与可选领域诊断：resources/trust-registry.md（来源／证据解读）
• 故障恢复：resources/error-playbook.md（路径失败时）
• 结果检查：resources/checklist.md（适用的来源和证据检查）
• 示例：resources/examples.md（输入不熟悉或处于边界情况时）
• 本地代码交接：../_shared/core/code-intelligence.md（本地请求）