Librarian Agent

文档维护规范

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

定位

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

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

当前实现：独立进程 + IM 通信

实现：knowhub/agents/knowledge_manager.py

架构

Agent（端侧）
  ↓ ask_knowledge / upload_knowledge 工具
  ↓ IM 消息（WebSocket，[ASK]/[UPLOAD] 前缀）
IM Server（WebSocket 中继）
  ↓
Librarian Agent（独立进程，监听 contact_id="knowledge_manager"）
  ↓ 调用 KnowHub HTTP API
KnowHub Server

启动方式

通过 start_knowledge_manager() 启动为异步后台任务，或直接运行 knowledge_manager.py。需要 IM Client 连接。

消息协议

[ASK] {query} → Librarian Agent 检索知识库 → LLM 整合 → 返回文本回答
[UPLOAD] {json} → 缓冲，5秒合并多次上传
[UPLOAD:FINALIZE] {json} → 最终提交入库

Agent 侧工具

ask_knowledge（agent/tools/builtin/knowledge_manager.py）：发送 [ASK]，同步等待回复（最多30秒），超时降级为直接 knowledge_search
upload_knowledge（agent/tools/builtin/knowledge_manager.py）：发送 [UPLOAD]，异步不等待

局限

依赖 IM 基础设施（WebSocket Server + Client 初始化）
部署复杂（3个服务）
测试困难（无法简单 HTTP 调用）
超时降级时丢失整合能力

计划重构：HTTP API + 内部 Agent

状态：设计中，未实现

目标

去掉 IM 依赖，将 Librarian Agent 作为 KnowHub Server 的内部实现，通过 HTTP API 暴露。

新架构

Agent（端侧）
  ↓ ask_knowledge / upload_knowledge 工具（HTTP 调用）
KnowHub Server
  ├── POST /api/knowledge/ask（同步阻塞）
  │   → 查找/创建 Librarian Agent trace（by caller trace_id）
  │   → Librarian Agent 检索 + LLM 整合
  │   → 返回整合回答 + source_ids
  │
  └── POST /api/knowledge/upload（异步队列）
      → 校验格式 → 立即返回 202
      → 消息队列 → Librarian Agent 后台处理

ask 接口

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

trace_id 用于 Librarian Agent 续跑：同一 trace_id 复用同一个 Agent trace，积累对调用方任务的理解
同步阻塞，调用方等待结果返回后继续执行（逻辑上要求必须复用已有知识）

响应：

{
  "response": "整合后的回答文本...",
  "source_ids": ["knowledge-xxx", "knowledge-yyy"],
  "sources": [
    {"id": "knowledge-xxx", "task": "...", "content": "...（截断500字）"}
  ]
}

upload 接口

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

立即返回 202 Accepted，后台队列处理。

Agent 侧改动

ask_knowledge 工具从 IM 改为 HTTP：

@tool
async def ask_knowledge(query: str, context: ToolContext) -> ToolResult:
    response = await httpx.post(f"{KNOWHUB_API}/api/knowledge/ask", json={
        "query": query,
        "trace_id": context.trace_id,
    })
    result = response.json()
    return ToolResult(
        output=result["response"],
        metadata={"source_ids": result["source_ids"], "sources": result["sources"]}
    )

inject_knowledge_for_goal 切换到 ask 接口，记录完整的 query 事件到 cognition_log（详见 cognition-log.md）。

与 Cognition Log 的关系

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

与知识处理流水线的关系

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

librarian-agent.md 4.3 KB 히스토리 Raw