Aida 知识库管理与搜索可行性研究

摘要

推荐 MVP

1. 在 Config DB 中增加由 Admin 管理的 KnowledgeBase、KnowledgeDocument、KnowledgeChunk、KnowledgeCluster 表。
2. 增加 /admin/knowledge-bases CRUD 和 Admin Web 中的 KnowledgeBasesPage。
3. 增加只读 internal tools：searchKnowledgeBase、getKnowledgeCluster，可选 listKnowledgeClusters。
4. 用显式 knowledgeBaseIds 把知识库绑定到 Agent 定义。
5. 先支持 text / markdown / JSON / CSV ingestion 和 PostgreSQL full-text search；Phase 2 再加入 embedding 和更丰富的文档抽取。

Sirchmunk 实际实现

核心数据模型

Sirchmunk 的持久化单元是 KnowledgeCluster：一个被综合出来的知识单元，包含 name、description、content、evidence list、confidence、lifecycle、query history、related clusters、source results，以及可选 semantic metadata（/Users/stanley/Repos/sirchmunk/src/sirchmunk/schema/knowledge.py:157）。Evidence 携带 doc_id、source path 或 URL、summary、snippet、extraction time，这正是 Aida 想要给出可信回答时需要的证据追溯能力（/Users/stanley/Repos/sirchmunk/src/sirchmunk/schema/knowledge.py:28）。

Cluster 在 retrieval 之后构建：Sirchmunk 从 top files 中抽取 evidence，调用 LLM synthesis，从合成文本派生确定性的 cluster id，然后返回完整 KnowledgeCluster（/Users/stanley/Repos/sirchmunk/src/sirchmunk/learnings/knowledge_base.py:175，/Users/stanley/Repos/sirchmunk/src/sirchmunk/learnings/knowledge_base.py:280）。

存储

Sirchmunk 把 cluster 存在 in-memory DuckDB table 中，并周期性、进程退出时同步到 Parquet（/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:35，/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:205）。它提供 CRUD、fuzzy search、merge/split、stats、embedding persistence 和 cosine-similar cluster search（/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:472，/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:634，/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:958，/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:1045）。

这很适合 local-first 工具，但不适合 Aida 的 server Agent，因为 Aida 已经有 tenant-aware Postgres Config DB、audit tables、Admin routes 和 request-scoped TenantContext。

搜索管线

Sirchmunk 有三个公开模式：FILENAME_ONLY、FAST、DEEP（/Users/stanley/Repos/sirchmunk/src/sirchmunk/search.py:926）。FAST 先尝试 cluster reuse，然后做一次 LLM query-analysis、关键词搜索、聚焦证据采样、一次 LLM answer call，以及可选 cluster persistence（/Users/stanley/Repos/sirchmunk/src/sirchmunk/search.py:1608）。DEEP 会并行 probe：keyword extraction、directory scan、knowledge-cache search、spec-cache load，然后进入 retrieval、evidence assembly、summary 或 ReAct refinement、persistence（/Users/stanley/Repos/sirchmunk/src/sirchmunk/search.py:1106，/Users/stanley/Repos/sirchmunk/src/sirchmunk/search.py:1153）。

它的 retrieval 基础是通过 ripgrep-all 做 indexless lexical search，并使用 shell=False 和结构化参数规避 shell 注入风险（/Users/stanley/Repos/sirchmunk/src/sirchmunk/retrieve/text_retriever.py:19）。它的 ReAct retrieval tools 包括 keyword search、file read、knowledge query，以及可选 directory scan（/Users/stanley/Repos/sirchmunk/src/sirchmunk/search.py:843）。

管理面

Sirchmunk 暴露了 REST endpoints，用于 knowledge refresh、list、get、search、stats（/Users/stanley/Repos/sirchmunk/src/sirchmunk/api/knowledge.py:14）。它的 MCP tool surface 包含 sirchmunk_search、sirchmunk_get_cluster、sirchmunk_list_clusters，这些 schema 可以比较自然地映射到 Agent tools（/Users/stanley/Repos/sirchmunk/src/sirchmunk_mcp/tools.py:21，/Users/stanley/Repos/sirchmunk/src/sirchmunk_mcp/tools.py:130，/Users/stanley/Repos/sirchmunk/src/sirchmunk_mcp/tools.py:153）。

当前 Aida 的适配度

现有杠杆点

Aida 已经有合适的接入点：

• Config DB DDL 集中在 runConfigDDL，并且已经有 agents、skills、conversations、messages、runs、scheduled tasks、observability、channel config 等一等表（packages/agent/src/config/ddl.ts:10，packages/agent/src/config/ddl.ts:30，packages/agent/src/config/ddl.ts:148，packages/agent/src/config/ddl.ts:328）。
• Admin Config routes 已经处理 CRUD、write auth、audit emission，并且承载 Providers、Skills、Agents、Entitlements、ScheduledTasks、Channels 等配置页面（packages/agent/src/gateway/admin-config.ts:226，packages/agent/src/gateway/admin-config.ts:374，packages/agent/src/gateway/admin-config.ts:700）。
• Admin Web 已经有 API client 和复杂的 Skills 管理页面，可以复用其文件 / 文档树、编辑器、详情布局模式（packages/web/src/lib/admin-api.ts:18，packages/web/src/pages/SkillsPage.tsx:71）。
• Runtime Agent preparation 已经有清晰的 pre-flight step，会按 resolved Agent 组装 tools 和 prompt（packages/agent/src/gateway/prepare-agent-context.ts:46）。
• Internal read tools 已有模式：readSkillFile 和 scheduled task management 都在 internal-tools.ts 中构建，internal tools 会按 Run 与 domain tools 合并（packages/agent/src/orchestrator/internal-tools.ts:105，packages/agent/src/orchestrator/internal-tools.ts:312，packages/agent/src/orchestrator/agent.ts:127）。
• TenantContext 可以在 internal tools 内通过 getTenantContext() 取得，scheduled task tools 已经这样使用（packages/agent/src/orchestrator/internal-tools.ts:184）。

关键约束

建议的 Aida 架构

领域术语

实现开始时，建议把这些术语加入 CONTEXT.md：

• KnowledgeBase：租户作用域内、可被 Agents 搜索的语料集合。
• KnowledgeDocument：注册在某个 KnowledgeBase 内的文档或资源。
• KnowledgeChunk：从 KnowledgeDocument 中抽取出的可搜索文本片段。
• KnowledgeCluster：由成功搜索生成的、可复用的综合答案 / 证据包。
• KnowledgeSearch：只读 Agent 操作，返回 grounded snippets 或可复用 KnowledgeCluster。

存储模型

建议增加以下 Config DB tables：

knowledge_bases (
  id uuid primary key default gen_random_uuid(),
  tenant_id text not null,
  name text not null,
  description text not null default '',
  status text not null default 'active',
  created_by text not null,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now(),
  unique (tenant_id, name)
);

knowledge_documents (
  id uuid primary key default gen_random_uuid(),
  knowledge_base_id uuid not null references knowledge_bases(id) on delete cascade,
  tenant_id text not null,
  title text not null,
  source_type text not null,
  source_uri text,
  content_sha256 text not null,
  status text not null default 'ready',
  metadata jsonb not null default '{}',
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

knowledge_chunks (
  id uuid primary key default gen_random_uuid(),
  document_id uuid not null references knowledge_documents(id) on delete cascade,
  knowledge_base_id uuid not null references knowledge_bases(id) on delete cascade,
  tenant_id text not null,
  chunk_index int not null,
  content text not null,
  tsv tsvector generated always as (to_tsvector('simple', content)) stored,
  metadata jsonb not null default '{}'
);

knowledge_clusters (
  id uuid primary key default gen_random_uuid(),
  knowledge_base_id uuid not null references knowledge_bases(id) on delete cascade,
  tenant_id text not null,
  query_history text[] not null default '{}',
  name text not null,
  content text not null,
  evidence jsonb not null default '[]',
  confidence double precision,
  hotness double precision,
  lifecycle text not null default 'emerging',
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

agent_knowledge_bases (
  agent_id uuid not null references agents(id) on delete cascade,
  knowledge_base_id uuid not null references knowledge_bases(id) on delete cascade,
  primary key (agent_id, knowledge_base_id)
);

建议使用 agent_knowledge_bases，而不是给 agents 再加一个 text-array 字段。这是一个真实关系，会让 Admin UI 反查、删除行为、租户过滤都比 skill_ids 更简单。

运行时接口

增加 KnowledgeService Module：

• listAgentKnowledgeBases(agentId, tenantId)
• searchKnowledgeBase({ tenantId, agentId, query, knowledgeBaseIds?, limit? })
• getKnowledgeCluster({ tenantId, clusterId })
• recordClusterHit({ tenantId, clusterId, query })
• saveClusterFromSearch(...)

增加只读 internal tools：

• searchKnowledgeBase：Input 为 query，可选 knowledgeBaseIds、limit、mode: "fast" | "deep"；Output 是可直接用于回答的 evidence pack：matched chunks、document metadata、source ids、可选 reusable cluster。
• getKnowledgeCluster：Input 为 clusterId；Output 是 cluster content + evidence。
• listKnowledgeClusters：可选，用于 Admin / Agent 自检，类似 Sirchmunk 的 sirchmunk_list_clusters。

只在 resolved Agent 绑定了知识库时，才在 buildInternalToolSet 中挂载这些 tools。这与现有 readSkillFile 的条件注册方式一致（packages/agent/src/orchestrator/internal-tools.ts:321），也能保持工具 affordance 诚实。

Prompt 集成

不要把文档正文 inline 进 system prompt。

在 prepareAgentToolsAndPrompt 中，仅当 Agent 绑定了知识库时加入短 catalog segment：

## Knowledge Bases

You can search the following tenant-scoped knowledge bases with searchKnowledgeBase:
- HR Policies: internal HR policy documents
- Onboarding: onboarding guides and FAQs

这遵循现有 write-tool catalog 模式：prompt 中只放小目录，完整数据通过工具读取（packages/agent/src/gateway/prepare-agent-context.ts:82）。

搜索策略

Phase 1 应刻意保持简单：

1. Cluster reuse：先搜索 knowledge_clusters.query_history / name / content。
2. Lexical retrieval：对 knowledge_chunks.tsv 做 Postgres full-text search。
3. Evidence pack：返回 top chunks，包含 documentId、title、score、snippets。
4. 可选 LLM synthesis：可以让主 Orchestrator 直接使用 evidence，也可以让 searchKnowledgeBase 合成 compact answer 和 evidence list。
5. 只有证据足够强时才保存 cluster。

这能得到和 Sirchmunk FAST mode 类似的形状，同时不需要引入 subprocess、Python、DuckDB、Parquet、sentence-transformers 或 ripgrep-all。

Phase 2 可以加入 embeddings：

• 增加 embedding_model、embedding_vector、embedding_text_hash。
• 如果 Config DB Postgres 支持 pgvector，优先使用 pgvector；否则保留 lexical search，并稍后增加外部 vector adapter。
• 从 query history 计算 cluster embedding，借鉴 Sirchmunk 的 combine_cluster_fields(queries) 方法（/Users/stanley/Repos/sirchmunk/src/sirchmunk/storage/knowledge_storage.py:941）。

Phase 3 可以加入类似 Sirchmunk 的 DEEP mode：

• 基于 chat history 做 query rewriting。
• 并行进行 lexical + metadata + cluster reuse probes。
• 使用 LLM 做 evidence reranking。
• 自动创建带 confidence / hotness / lifecycle 的 cluster。

可行性评估

MVP 可行性：高

Admin CRUD、text ingestion、chunk storage、lexical search、只读 Agent tools 都与当前 Aida Modules 很匹配。整体主要是 additive change：

• DDL：packages/agent/src/config/ddl.ts
• Backend service：packages/agent/src/config/services/knowledge-service.ts
• Admin routes：packages/agent/src/gateway/admin-config.ts
• Runtime pre-flight：packages/agent/src/gateway/prepare-agent-context.ts
• Internal tools：packages/agent/src/orchestrator/internal-tools.ts
• Admin Web API/types：packages/web/src/lib/admin-api.ts
• Admin Web page：新增 KnowledgeBasesPage.tsx，复用 SkillsPage patterns

预计工作量：5-8 个工程日，可完成 text-only、Postgres full-text MVP，包含单测和小型 Admin UI。

生产级可行性：中高

更重的部分不是架构 blocker，但需要产品选择：

• PDF/DOCX/XLSX/PPTX 的 document extraction
• original files 的存储方式
• embedding provider 和 vector index 策略
• 谁可以读取或修改各个 KnowledgeBase 的 tenant/admin permission model
• search result quality evals
• observability 和 cost controls

预计工作量：3-5 周，可完成稳健 ingestion、更丰富文档格式、cluster reuse、eval coverage 和可用的 Admin UX。

直接移植 Sirchmunk 可行性：中低

把 Sirchmunk 直接嵌成 sidecar 可以很快做 demo，但对 Aida 风险较高：

• Python runtime 和 ripgrep-all 不在当前 Node 20 / pnpm / ESM 技术栈里。
• DuckDB/Parquet 会在 Config DB 之外创建第二个 persistence authority。
• 本地文件系统 paths 无法自然映射到多租户企业数据。
• tenant isolation 和 Backend Token 规则更容易被绕开；Aida-owned storage 更稳。
• Admin UI 和 audit 仍然要重建。

结论：把 Sirchmunk 当作设计参考，不要当作 runtime dependency。

实施计划

1. Phase 0：决策与术语
   把 KnowledgeBase 相关术语加入 CONTEXT.md；决定 MVP 文档存储是 Postgres text-only，还是 local filesystem + metadata；决定 Agent 绑定是仅 per-Agent，还是 tenant entitlement 也控制 KnowledgeBase 可见性。
2. Phase 1：Admin-Managed Text KnowledgeBase
   增加 DDL tables、knowledge-service.ts、/admin/knowledge-bases routes，以及 Admin Web page；先支持 .txt、.md、.json、.csv、.yaml；测试 service CRUD、tenant isolation、search ranking smoke tests、route auth。
3. Phase 2：Agent Runtime Search
   在 Agent Admin UI 中增加 agent_knowledge_bases 编辑能力；扩展 ResolvedAgentContext；把 KnowledgeService 加到 runtime deps 或 ConfigFacade；条件注册 searchKnowledgeBase / getKnowledgeCluster；增加 prompt catalog segment；测试 conditional tool exposure、tenant filtering、Orchestrator tool-call smoke test。
4. Phase 3：KnowledgeCluster Reuse
   增加 cluster save/reuse 路径；实现 hotness / query-history updates；增加 listKnowledgeClusters 的 Admin 和 Agent 只读 surface；只有返回 evidence 至少包含一个 chunk，且 confidence 超过阈值时才保存；测试 cluster reuse hit、stale/deleted source exclusion、evidence traceability。
5. Phase 4：Rich Extraction And Embeddings
   增加 PDF/DOCX/XLSX/PPTX extraction adapters；增加可选 embeddings，以及 hybrid lexical + vector retrieval；如果 ingestion/search 变成长任务，增加 streaming progress events；增加 Eval Charters，覆盖 groundedness、source citation、tenant isolation、missing evidence 时拒答。

风险与缓解

推荐结论