# Librarian Agent

## 文档维护规范

0. **先改文档，再动代码**
1. **文档分层，链接代码** — 格式：`module/file.py:function_name`
2. **简洁快照，日志分离** — 决策依据记录在 `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](cognition-log-plan.md)。

## 与知识处理流水线的关系

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