Proposal Name: artifact_search
Start Date: 2026-10-07
RFC PR: oceanbase/powercontext#1858

Summary

为同一 Scope 内的单个 Artifact Family 提供统一 search 接口，返回按相关性排序、受 limit 限制的 Artifact 数组。公共层约定调用方式和基础行为，各 Family 按需声明检索能力并负责业务实现。现有业务专用接口为兼容性继续保留，已接入 Family 的专用接口内部改为调用统一检索方法。

Motivation

ListActiveEntries 缺少针对查询的相关性排序，结果在预算不足时被截断，可能丢掉最相关的记忆。调用方需要按查询选取前 N 个相关制品。同时，各制品分散的检索入口增加了接入成本；新增 Family 应能通过注册接入统一接口。

Guide-level explanation

调用方使用 POST /v1/scopes/{scope_id}/artifacts/{family}/search，例如提交：

{
  "query": "数据库连接超时的处理经验",
  "limit": 5
}

响应的 results 是按相关性排序的 Artifact 数组，最多包含 5 项；每项内容由对应 Family 定义，没有匹配项时返回空数组。query 必须非空，省略检索模式时使用 Family 的默认行为。

调用方还可使用该 Family 声明支持的模式、过滤条件、相关性准入、融合配置、评分阈值或重排能力。未知 Family、不支持搜索或不支持所请求能力时，接口给出明确错误；运行失败不作为空结果返回。

每次请求检索一个 Family，只提供 limit，不提供分页。多制品编排和上下文预算分配继续使用 prepare。

Reference-level explanation

能力分派：Family 注册检索能力、参数约束和业务实现。公共入口按注册信息解析、分派请求，Family 负责专用参数及默认策略，框架不强制 auto，新增 Family 无需修改公共入口的分支逻辑。
能力范围：鼓励支持全文、向量、融合、过滤、准入、评分阈值和重排；Family 按需支持并公开可用组合。显式请求不支持的能力必须报错，不能忽略参数或静默切换策略。
评分契约：检索评分必须为有限的 [0, 1] 数值，越大表示评分越高。支持 min_score 时严格按归一化检索分数筛选，重排或补足数量不能绕过门槛。归一化不承诺跨 Family、算法或查询的绝对可比性。
融合职责：融合算法独立于制品，复用通用实现；Family 提供召回通道、候选和权重。算法专用参数随所选算法配置，已声明的相关性准入不因切换融合算法而改变。
兼容与接入：现有业务专用接口继续保留，保持既有请求、响应及默认行为。已接入 Family 的专用接口必须调用统一检索方法，通过参数和结果适配保持兼容，与新 HTTP 入口、SDK、prepare 共用同一业务检索实现。首批覆盖 Topic Memory、Experience 和 Skill；现有 Memory entry 检索保留原入口。Prompt 不纳入， Profile、Handoff 不为统一接口补充搜索能力，未提供搜索时明确报错。