OceanBase seekdb × PowerContext 混合检索与上下文工程 Skill

一、技能简介与适用场景

技能名称：seekdb-powercontext-hybrid-rag
功能概述：指导 AI Agent 结合 OceanBase seekdb（原生向量 + 全文双索引引擎）与 PowerContext（结构化来源采集、记忆生命周期与证据预算装配框架），实现从原始多源证据入库、单 SQL 混合候选召回、跨批次重排到字节预算内精确片段装配的完整上下文工程闭环。
适用场景：
1. 需要同时利用关键词精确匹配（MATCH ... AGAINST）与语义向量近邻（l2_distance / cosine_distance）进行混合召回的 RAG 场景；
2. 需要保留原始证据回查引用（MemoryCitation）与字符级区间（start, end）的严肃知识问答（如财报分析、代码规范审计、表格记录检索）；
3. 需要在有限上下文窗口（UTF-8 字节预算）内动态筛选高价值证据片段并支持增量传输（ContextPackDelta）的多轮 Agent 协作场景。

二、标准执行工作流

步骤 1：多源证据结构化采集（Source Capture）

將外部输入（CSV 表格、PDF 物理页、Agent 会话 JSONL 树）解析为不可变的 CAPTURED Source，生成确定性身份标识并持久化标准 powercontext.text-evidence 投影：

CSV 行级证据：以 csv:{quote(document_id)}:{quote(primary_key_value)} 作为稳定主键身份，保留原始列序与字段值；
PDF 页级证据：以 (document_id, document_sha256, page_number) 标识物理页，保留页面正文与财务表格数字；
会话分支证据：沿所选叶节点 leaf_id 回溯祖先链，完整保留工具调用、工具输出与可见对话并记录增量 checkpoint。

步骤 2：seekdb 单条 SQL 混合检索（Single-SQL Hybrid Search）

在 seekdb 后端执行混合检索时，将全文检索通道（FTS）与向量检索通道（Vector Index）合并为单条 SQL 语句（UNION ALL），在数据库内核层一步完成作用域（scope_id）、当前版本（head_revision）与标签过滤：

(
  SELECT
    h.entry_id AS entry_id,
    h.entry_version_id AS entry_version_id,
    'fts' AS channel,
    MATCH(h.search_text) AGAINST (%s IN NATURAL LANGUAGE MODE) AS fts_score,
    NULL AS vector_distance
  FROM pc_memory_entry_heads AS h
  WHERE h.scope_id = %s
    AND h.memory_artifact_id = %s
    AND h.status = 'active'
    AND MATCH(h.search_text) AGAINST (%s IN NATURAL LANGUAGE MODE)
  ORDER BY fts_score DESC, h.entry_id ASC
  LIMIT %s
)
UNION ALL
(
  SELECT
    v.entry_id AS entry_id,
    v.entry_version_id AS entry_version_id,
    'vector' AS channel,
    NULL AS fts_score,
    l2_distance(v.embedding, %s) AS vector_distance
  FROM pc_memory_vector_entries AS v
  WHERE v.scope_id = %s
    AND v.memory_artifact_id = %s
    AND v.status = 'active'
  ORDER BY l2_distance(v.embedding, %s) APPROXIMATE
  LIMIT %s
)

执行计划核验：通过 EXPLAIN 确认单条 SQL 同时命中 TEXT RETRIEVAL SCAN 与 VECTOR INDEX，避免全表扫描与多次网络往返。

步骤 3：跨批次 HTTP 重排与查询驱动证据装配

分批重排（HTTP Reranking）：对召回的候选池按 batch_size 拆分请求至重排服务，保留每个候选在完整候选池中的原始一基序号 rank，最终按 (score DESC, rank ASC) 全局稳定排序。
字节预算内原文证据选择（Evidence Selection）：针对当前 query 在候选记忆正文内部定位高相关原文区间 entry.text[start:end]，连同 citation 与 BEGIN_POWERCONTEXT_PREPARED_CONTEXT_V1 协议信封一起严格控制在 max_bytes UTF-8 字节预算以内。
上下文增量传输（Incremental Context Pack）：多轮对话中通过 ContextPackDelta.between(base_pack, target_pack) 复用公共前缀分块，仅传输新增后缀与 SHA-256 校验摘要，在接收端无损重建完整上下文。

三、快速使用示例

from powercontext import PrepareContextRequest, open_builtin_runtime

async def build_agent_context(db_path: str, scope_id: str, query: str) -> str:
    async with open_builtin_runtime(database_url=f"sqlite+aiosqlite:///{db_path}") as runtime:
        app = runtime.context.for_scope(scope_id)
        prepared = await app.prepare(
            PrepareContextRequest(
                query=query,
                max_bytes=1800,
                evidence_selection=True,
            )
        )
        return prepared.content or ""

四、大赛验证行（提测时将本队验证行独立一行粘贴在下方）