Agent/knowhub/docs/knowledge-management.md

知识管理系统

文档维护规范

1. 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
2. 文档分层，链接代码 - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：module/file.py:function_name
3. 简洁快照，日志分离 - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议、决策历史、修改日志、大量代码；决策依据或修改日志若有必要，可在knowhub/docs/decisions.md另行记录

---

架构

KnowHub Server 是统一的知识管理服务，Agent 通过 API 调用来保存和检索知识。

Agent                           KnowHub Server
├── knowledge_search 工具   →   GET /api/knowledge/search
├── knowledge_save 工具     →   POST /api/knowledge
├── knowledge_update 工具   →   PUT /api/knowledge/{id}
└── goal focus 自动注入     →   GET /api/knowledge/search

---

知识结构

单条知识的数据格式：

{
  "id": "knowledge-20260305-a1b2",
  "message_id": "msg-xxx",
  "tags": {
    "type": ["tool", "usecase", "definition", "plan", "strategy"]
  },
  "scenario": "在什么场景下要完成什么目标",
  "content": "核心知识内容",
  "source": {
    "urls": ["https://example.com"],
    "agent_id": "research_agent",
    "timestamp": "2026-03-05T12:00:00"
  },
  "eval": {
    "score": 3,
    "helpful": 0,
    "harmful": 0,
    "helpful_history": [],
    "harmful_history": []
  },
  "metrics": {
    "helpful": 1,
    "harmful": 0
  },
  "created_at": "2026-03-05 12:00:00",
  "updated_at": "2026-03-05 12:00:00"
}

字段说明

• id: 唯一标识，格式 knowledge-{timestamp}-{random}
• message_id: 来源 Message ID（用于精确溯源到具体消息）
• tags.type: 知识类型（可多选）
  • tool: 工具使用方法、优缺点、代码示例
  • usecase: 用户背景、方案、步骤、效果
  • definition: 概念定义、技术原理、应用场景
  • plan: 流程步骤、决策点、方法论
  • strategy: 执行经验（从反思中获得）
• scenario: 任务描述，什么场景、在做什么
• content: 核心知识内容
• source.urls: 参考来源链接
• source.agent_id: 创建者 agent ID
• source.timestamp: 创建时间戳
• eval.score: 初始评分 1-5
• eval.helpful/harmful: 好用/不好用次数
• metrics.helpful/harmful: 累计反馈次数

---

Agent 工具

Agent 通过以下工具与 KnowHub Server 交互。工具只是 API 调用的封装，核心逻辑在 Server 实现。

实现位置：agent/tools/builtin/knowledge.py

knowledge_search

检索知识。

@tool()
async def knowledge_search(
    query: str,
    top_k: int = 5,
    min_score: int = 3,
    tags_type: Optional[List[str]] = None
) -> ToolResult

调用 GET /api/knowledge/search?q={query}&top_k={top_k}&min_score={min_score}

knowledge_save

保存新知识。

@tool()
async def knowledge_save(
    scenario: str,
    content: str,
    tags_type: List[str],
    urls: List[str] = None,
    agent_id: str = "research_agent",
    score: int = 3,
    message_id: str = ""
) -> ToolResult

调用 POST /api/knowledge

knowledge_update

更新已有知识的评估反馈。

@tool()
async def knowledge_update(
    knowledge_id: str,
    add_helpful_case: Optional[Dict] = None,
    add_harmful_case: Optional[Dict] = None,
    update_score: Optional[int] = None,
    evolve_feedback: Optional[str] = None
) -> ToolResult

调用 PUT /api/knowledge/{knowledge_id}

知识进化：当提供 evolve_feedback 时，Server 使用 LLM 重写知识内容。

knowledge_batch_update

批量反馈知识有效性。

@tool()
async def knowledge_batch_update(
    feedback_list: List[Dict[str, Any]]
) -> ToolResult

调用 POST /api/knowledge/batch_update

knowledge_list

列出已保存的知识。

@tool()
async def knowledge_list(
    limit: int = 10,
    tags_type: Optional[List[str]] = None
) -> ToolResult

调用 GET /api/knowledge?limit={limit}

knowledge_slim

知识库瘦身，合并相似知识。

@tool()
async def knowledge_slim(
    model: str = "anthropic/claude-sonnet-4.5"
) -> ToolResult

调用 POST /api/knowledge/slim

---

知识注入机制

知识注入在 goal focus 时自动触发。

实现位置：agent/trace/goal_tool.py:focus_goal

注入流程

# 1. LLM 调用 goal 工具
goal(action="focus", goal_id="goal-123")

# 2. goal 工具内部自动执行
current_goal = goal_tree.find("goal-123")
knowledge_results = await knowledge_search(
    query=current_goal.description,
    top_k=3,
    min_score=3
)

# 3. 保存到 goal 对象
current_goal.knowledge = knowledge_results.metadata["items"]

# 4. 持久化到 trace store
await trace_store.update_goal_tree(trace_id, goal_tree)

# 5. 返回给 LLM
return ToolResult(
    title="✅ Goal 已聚焦",
    output=f"当前 Goal: {current_goal.description}\n\n📚 相关知识 ({len(knowledge_results)} 条):\n..."
)

知识展示

注入的知识会显示在 GoalTree 的「📚 相关知识」部分。

---

调研决策

调研决策与知识注入分离，通过 system prompt 引导。

决策流程

1. goal focus → 自动注入知识
   ↓
2. LLM 看到 GoalTree 中的「📚 相关知识」
   ↓
3. LLM 自主判断：
   ├─ 知识充足 → 直接制定计划
   └─ 知识不足 → 调用 agent 工具启动调研子任务

System Prompt 引导

## 知识管理

当你使用 `goal(action="focus")` 聚焦到某个 goal 时，系统会自动检索相关知识并显示在 GoalTree 的「📚 相关知识」部分。

根据知识充足性判断：

**知识充足**：
- 如果相关知识足以完成任务，直接制定计划
- 使用 `goal` 工具创建执行计划的子 goal

**知识不足**：
- 如果相关知识不足，需要进行调研
- 调用 `agent` 工具启动调研子任务
- 调研完成后，使用 `knowledge_save` 保存结果

调研完成后，再次 focus 该 goal，新保存的知识会被自动注入。

调研 Skill

调研指南存储在 agent/memory/skills/research.md。

---

KnowHub Server API

GET /api/knowledge/search

检索知识。核心逻辑在 Server 实现。

参数：

• q: 查询文本
• top_k: 返回数量（默认 5）
• min_score: 最低评分过滤（默认 3）
• tags_type: 按类型过滤（可选）

检索流程（两阶段，Server 端实现）：

1. 语义路由：使用 LLM（gemini-2.0-flash-001）从所有知识中挑选 2*k 个语义相关的候选

   • 输入：query + 知识元数据（id, tags, scenario 前 100 字符）
   • 输出：候选知识 ID 列表

2. 质量精排：根据评分和反馈计算质量分，筛选最终的 k 个

   • 质量分公式：quality_score = score + helpful - (harmful * 2.0)
   • 过滤：score < min_score 或 quality_score < 0 的知识被剔除

实现位置：knowhub/server.py:knowledge_search

响应：

{
  "results": [
    {
      "id": "knowledge-xxx",
      "scenario": "...",
      "content": "...",
      "tags": {...},
      "score": 4,
      "quality_score": 5.0,
      "metrics": {"helpful": 2, "harmful": 0}
    }
  ],
  "count": 3
}

POST /api/knowledge

保存新知识。

请求体：

{
  "scenario": "在什么场景下要完成什么目标",
  "content": "核心知识内容",
  "tags_type": ["tool", "strategy"],
  "urls": ["https://example.com"],
  "agent_id": "research_agent",
  "score": 4,
  "message_id": "msg-xxx"
}

实现位置：knowhub/server.py:save_knowledge

PUT /api/knowledge/{id}

更新知识。

请求体：

{
  "add_helpful_case": {"case_id": "...", "scenario": "...", "result": "..."},
  "add_harmful_case": {"case_id": "...", "scenario": "...", "result": "..."},
  "update_score": 4,
  "evolve_feedback": "改进建议（触发知识进化）"
}

知识进化：当提供 evolve_feedback 时，Server 使用 LLM 重写知识内容。

实现位置：knowhub/server.py:update_knowledge

POST /api/knowledge/batch_update

批量反馈知识有效性。

请求体：

{
  "feedback_list": [
    {
      "knowledge_id": "knowledge-xxx",
      "is_effective": true,
      "feedback": "改进建议（可选）"
    }
  ]
}

实现位置：knowhub/server.py:batch_update_knowledge

GET /api/knowledge

列出知识。

参数：

• limit: 返回数量（默认 10）
• tags_type: 按类型过滤（可选）

实现位置：knowhub/server.py:list_knowledge

POST /api/knowledge/slim

知识库瘦身，合并相似知识。

请求体：

{
  "model": "anthropic/claude-sonnet-4.5"
}

实现位置：knowhub/server.py:slim_knowledge

---

实现位置

组件	实现位置
KnowHub Server	knowhub/server.py
Agent 工具	agent/tools/builtin/knowledge.py
goal 工具（知识注入）	agent/trace/goal_tool.py:focus_goal
调研 skill	agent/memory/skills/research.md

---

设计原则

1. 统一服务：KnowHub Server 是唯一的知识存储和管理服务
2. Server 端逻辑：检索、进化等核心逻辑在 Server 实现，Agent 工具只是 API 封装
3. 自动注入：知识注入在 goal focus 时自动触发
4. 分离关注点：知识注入（自动）与调研决策（显式）分离
5. 工具自治：知识注入逻辑在 goal 工具中，不在 runner 中
6. 精确溯源：使用 message_id 而非 trace_id，可精确定位到具体消息
7. 质量保证：两阶段检索（语义路由 + 质量精排）确保准确性