# 知识管理系统

## 文档维护规范

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

---

## 知识结构

单条知识的数据格式：

```json
{
  "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`

检索知识。

```python
@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`

保存新知识。

```python
@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`

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

```python
@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`

批量反馈知识有效性。

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

调用 `POST /api/knowledge/batch_update`

### `knowledge_list`

列出已保存的知识。

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

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

### `knowledge_slim`

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

```python
@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`

### 注入流程

```python
# 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 引导

```markdown
## 知识管理

当你使用 `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`

**响应**：

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

### `POST /api/knowledge`

保存新知识。

**请求体**：

```json
{
  "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}`

更新知识。

**请求体**：

```json
{
  "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`

批量反馈知识有效性。

**请求体**：

```json
{
  "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`

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

**请求体**：

```json
{
  "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. **质量保证**：两阶段检索（语义路由 + 质量精排）确保准确性