跳转至

私域 Agentic Search 设计

核心定位

OrgReOrg / Harness 需要把组织私域数据做成可被 Agent 主动检索、深度阅读和引用的上下文基础设施。

它不是传统的一次性 RAG Pipeline，也不是只建一个向量库。更准确地说，它是 Runtime Projection 的检索投影能力：从 Ontology 中选出候选知识制品、索引对象和 Evidence 引用，再按权限、生命周期和 rank log 交给 Agent。

Evidence 原始证据
  -> Ontology 对象 / 关系 / 规则 / 制品 / Skill
  -> Runtime Projection
      -> D1/D2：入口索引、Skill、Markdown、ADR、实验报告
      -> D3：BM25 / FTS / vector / RRF / rerank 检索投影
      -> D4：Connector / MCP 回查证据或业务对象
      -> D5：Ask Router 主动补充
  -> Agent 多轮搜索、阅读、验证、回答

当前 runtime session 已经携带用户消息、临时文件和工作记忆；Context Router 的职责是判断当前上下文不足时，应投影哪些本体制品、检索索引、证据回查或主动询问对象。

参考 /home/ai/workspace/data_engineering 的实现，检索投影可以采用 OpenSearch/Elasticsearch 或 Postgres FTS/pgvector 对照实现：BM25 / FTS 负责精确关键词、术语、编号和人名匹配，向量检索负责语义相似和模糊表达，Rerank 负责把候选结果按问题相关性重新排序。

当前选型基线

第一轮 agentic_search_option_benchmark 后，当前 P0 基线调整为：

D1/D2：AGENTS / docs / vault / ADR / task skills 渐进披露
  -> D3 P0 默认：Postgres FTS + pgvector context document projection
  -> D3 scale adapter：OpenSearch / Elasticsearch hybrid search
  -> D4：业务系统 Connector / MCP 回查证据
  -> D5：Ask Router 主动询问负责人

这意味着：

  • Site/Knowledge 继续作为知识生产、review 和渐进披露层。
  • P0 先用 Postgres FTS/pgvector 承担低运维、强一致、权限字段好落地的检索投影。
  • ES/OpenSearch 保留为规模化 adapter，当上下文库、部门系统和并发查询增长后再接入。
  • managed vector only 不作为默认核心，因为它不能独自解决精确编号、权限过滤、生命周期、审计和证据追溯。

详见：Agentic Search Option Benchmark：技术路线选型实验。

当前已新增 SearchConnector Contract：framework/context/search_connector.py 定义了 SearchConnector Protocol、ContextDocument、SearchQuery、EvidenceHit、GapReport 和合成 InMemorySearchConnector；framework/context/document_schema.py 定义了正式 ContextDocumentRecord 入库 schema。下一步真实 Postgres FTS/pgvector 与 OpenSearch/ES adapter 必须实现同一 contract。

当前 adapter 进展：

  • sqlite_fts：CI 可跑的本地 SQL/FTS 替身，用来证明 SearchConnector contract。
  • postgres_fts：Postgres FTS adapter skeleton，配置 HARNESS_POSTGRES_DSN 后进入 live conformance。
  • opensearch：OpenSearch / Elasticsearch adapter skeleton，配置 HARNESS_OPENSEARCH_URL 后进入 live conformance。

详见 Postgres Search Adapter 和 OpenSearch Adapter。

为什么不是只做 RAG

传统 RAG 常见流程是：

文档切片 -> Embedding -> 向量库 -> 单次 top-k 检索 -> 塞进 prompt -> 生成回答

这条链路的问题是反馈回路太弱。复杂组织问题经常需要多次查询、换关键词、查不同系统、阅读完整上下文、比较多个证据源，而不是一次检索定生死。

OrgReOrg 更适合采用本体驱动的渐进披露 + 搜索引擎 + Connector 模式：

  • Codex / Claude Code 可以先读目录、索引页、ADR 和 Markdown 原文。
  • 搜索结果可解释，能返回标题、来源、路径、时间、权限标签和片段。
  • Agent 可以先搜宽，再搜窄，再读原文。
  • 对复杂问题可以拆成多个搜索子问题。
  • 检索不到时，Agent 能识别知识缺口并触发主动收集。
  • 搜索工具通过 MCP 暴露，便于 Claude Code、Codex、内部 Agent 或网页端统一调用。

详见：本体驱动上下文架构 和 运行时渐进披露与上下文访问路径。

Agentic Search Loop

Trigger: 用户提出问题或 workflow 需要上下文
Plan: Agent 拆分检索意图，选择系统和关键词
Search: 调用私域搜索 MCP，返回候选结果
Read: 读取文档详情、章节、业务对象或原始记录
Verify: 交叉验证来源、时间、权限和事实一致性
Synthesize: 生成带证据引用的答案或行动建议
Gap: 标记缺失数据、过期数据或权限不足
Persist: 写入检索记录、引用、知识缺口和后续任务

这个 loop 的重点不是“模型一次答对”，而是让 Agent 像研究员一样持续搜索、阅读和校验。

检索对象

第一阶段先覆盖结构化程度较高的信息：

  • workspaces/variai/site/ 和 workspaces/variai/knowledge/ 中的组织知识。
  • GitHub Issue、PR、Commit、CI 日志和技术文档。
  • 项目管理系统中的任务、里程碑、负责人和状态。
  • 文档系统中的制度、方案、会议纪要、合同摘要和培训材料。
  • CRM、财务、BI 等系统中经过授权的只读查询结果。

企业微信和飞书只作为统一交互入口与通知入口，不应被描述为组织信息的完整来源。真实业务信息分散在各部门业务系统中，搜索层必须围绕这些系统建立连接器和权限视图。

MCP 工具设计

最小工具集：

private_search.search
  输入：query, source, filters, top_k, use_rerank
  输出：候选结果、证据片段、来源、权限标签、score

private_search.get_document
  输入：doc_id, section
  输出：目录、章节正文、来源元数据

private_search.search_and_read
  输入：query, source, top_k
  输出：搜索结果与可阅读摘要

private_search.list_sources
  输入：无或权限上下文
  输出：当前用户可检索的数据源和覆盖范围

private_search.report_gap
  输入：问题、缺失信息、建议连接器或负责人
  输出：知识缺口记录

所有工具返回都必须包含证据元数据：来源系统、对象 ID、更新时间、访问权限、检索得分、是否经过 Rerank、可引用路径。

当前 Python contract 已把最小工具边界固化为：

search(SearchQuery) -> SearchResponse
get_document(doc_id, allowed_scopes) -> ContextDocument | None
report_gap(GapReport) -> GapReceipt
explain(doc_id, SearchQuery) -> RankExplanation
delete_or_supersede(doc_id, superseded_by=None) -> bool

详见：SearchConnector Contract：检索投影适配器边界。

证据引用

回答组织问题时，Agent 必须尽量引用具体证据，而不是只给结论。

推荐引用粒度：

  • 文档：文件路径、标题、章节、版本、更新时间。
  • GitHub：repo、issue/PR 编号、commit、CI run。
  • 财务：报销单、预算项、合同编号、发票编号，但要按权限脱敏。
  • CRM：客户、商机、合同、回款记录，同样按权限裁剪。
  • BI：看板、指标、查询时间、过滤条件。

用户没有权限查看的证据，不应在回答中泄露内容。系统可以说明“存在相关记录但当前角色不可见”，并给出申请授权路径。

知识缺口识别

Agentic Search 的一个关键产物是知识缺口，而不是只有答案。

常见缺口包括：

  • 搜不到相关资料。
  • 找到资料但明显过期。
  • 只有结论，没有原始证据。
  • 需要访问某个业务系统但没有连接器。
  • 有连接器但当前用户没有权限。
  • 多个系统信息互相冲突。

这些缺口应该进入主动收集和知识维护流程，由 Agent 识别部门、系统、负责人，发起授权或资料补充请求。

Anthropic 方向的工程启发

Anthropic 的 Claude Projects 提供了“围绕项目注入知识和指令”的产品形态；MCP Connector 提供了通过远程 MCP Server 接入工具的工程边界；连接器权限可以按工具动作做 allow、approval 或 block；Claude Code hooks 展示了在 agent loop 的不同生命周期插入治理逻辑的方式。

OrgReOrg 不应照搬任何单一产品形态，而应吸收这些工程启发：

  • Project Knowledge 对应组织上下文包。
  • Connectors / MCP 对应部门系统工具层。
  • Connector Permissions 对应工具动作权限。
  • Skills / Plugins 对应可复用任务模板和领域操作手册。
  • Hooks 对应权限、审计、质量和上下文维护的触发点。

Anthropic 后续总结 Claude Code Skills 内部实践时进一步说明：有效的 Skill 更像任务包，包含 gotchas、引用资料、脚本、模板、可选 hooks 和使用记忆，而不是单个 Markdown。对 OrgReOrg 来说，这强化了一个判断：Skill 是本体层中的可执行知识对象；规模化召回仍然通过 SearchConnector 处理。

任务技能包的详细采纳边界见：任务技能包：本体层中的可执行知识。

参考资料：

  • Anthropic MCP Connector 文档：https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector
  • Anthropic Connectors 帮助文档：https://support.anthropic.com/en/articles/11176164-pre-built-web-connectors-using-remote-mcp
  • Anthropic Projects 发布说明：https://www.anthropic.com/news/projects
  • Claude Code Hooks 文档：https://docs.anthropic.com/en/docs/claude-code/hooks
  • Anthropic Claude Code Skills 经验：https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills