Librarian Agent

文档维护规范

先改文档，再动代码
文档分层，链接代码 — 格式：module/file.py:function_name
简洁快照，日志分离 — 决策依据记录在 knowhub/docs/decisions.md

定位

Librarian Agent（原 Knowledge Manager Agent）是 KnowHub 的智能层，负责：

知识查询的整合回答（将散点搜索结果用 LLM 整合为带引用的回答）
知识上传的去重和处理
工具与知识的关联分析

架构

Agent（端侧）
  ↓ ask_knowledge / upload_knowledge 工具（HTTP）
KnowHub Server（FastAPI）
  ├── POST /api/knowledge/ask（同步）
  │   → 运行 Librarian Agent（AgentRunner.run）
  │   → Agent 检索 + LLM 整合 → 返回结果
  │
  └── POST /api/knowledge/upload（异步 202）
      → 存 buffer → BackgroundTasks 运行 Librarian Agent
      → Agent 做图谱编排（去重、关联 capability/tool）

Librarian Agent 不是常驻后台进程。每次 HTTP 请求触发一次 AgentRunner.run()，所有状态持久化在 trace 中。通过 trace_id 续跑实现跨请求的上下文积累。

实现：

Agent 核心：knowhub/agents/librarian.py（ask() / process_upload()）
Prompt：knowhub/agents/librarian_agent.prompt
Agent 侧工具：agent/tools/builtin/librarian.py
Server 端点：knowhub/server.py:ask_knowledge_api / upload_knowledge_api

trace_id 续跑

同一个 caller trace_id 映射到同一个 Librarian trace_id（映射持久化在 .cache/.knowledge/trace_map.json）。首次请求创建新 trace，后续请求续跑该 trace，Agent 保持对调用方任务的上下文理解。

ask 接口

POST /api/knowledge/ask
{
  "query": "ControlNet 相关的工具知识",
  "trace_id": "caller-trace-xxx",
  "top_k": 5
}

同步阻塞。Librarian Agent 通过 knowledge_search、tool_search、capability_search 等工具跨表检索，用 LLM 综合分析后返回结构化回答。

响应：{"response": "...", "source_ids": [...], "sources": [...]}

upload 接口

POST /api/knowledge/upload
{
  "data": {"knowledge": [...], "resources": [...], "tools": [...]},
  "trace_id": "caller-trace-xxx",
  "finalize": false
}

立即返回 202。数据同时写入 buffer 目录（.cache/.knowledge/buffer/，便于回溯），Librarian Agent 在后台运行图谱编排：检索已有实体去重、挂载 capability、构建关系、写入草稿池。

知识注入

inject_knowledge_for_goal（agent/trace/goal_tool.py）通过 ask 接口查询，结果记录为 cognition_log 的 query 事件（详见 agent/docs/cognition-log-plan.md）。

与 Cognition Log 的关系

ask 接口的每次调用在 Agent 侧产生一个 query 事件，记录查询、整合回答和 source_ids。后续评估以 query 为单位，逐 source 评估。详见 cognition-log-plan.md。

与知识处理流水线的关系

upload 提交的知识进入处理流水线（去重、工具关联分析）。当前这部分逻辑在 server.py:KnowledgeProcessor 中。详见 processing-pipeline.md。

librarian-agent.md 3.1 KB Historia Raaka