# Knowledge V2 系统架构说明

## 整体流程梳理

```
function_knowledge.py (入口)
    ├── [步骤1] generate_query: 生成查询语句
    ├── [步骤2] select_tool: 选择工具
    ├──┬── [有工具]
    │  │    ├── [步骤3] extract_tool_params: 提取工具参数（通过LLM）
    │  │    └── [步骤4] call_tool: 调用工具
    │  └── [无工具] 
    │       └── [步骤4] multi_search_knowledge.py
    │                   ├── llm_search_knowledge.py
    │                   │    ├── generate_queries: 生成多个query
    │                   │    ├── search_knowledge_batch: 批量搜索
    │                   │    └── merge_knowledge: 合并多个query的结果
    │                   └── merge_knowledge: 合并多渠道结果
    └── [后台] generate_and_save_new_tool: 异步生成新工具
```

## 核心特性

### 1. 动态工具参数提取
- **问题**：之前工具调用参数是硬编码的 `{"keyword": query}`
- **解决**：使用LLM根据工具信息动态提取参数
- **优势**：通用、智能、支持多参数工具
- **详细说明**：[IMPROVEMENT_SUMMARY.md](IMPROVEMENT_SUMMARY.md)

### 2. 结构化JSON输出
- **输出格式**：完整的执行记录JSON，包含输入、执行过程、结果和元数据
- **双文件保存**：
  - `execution_record.json` - 格式化的JSON，易于阅读
  - `final_result.json` - 系统缓存
- **优势**：可追溯、可调试、可审计

### 3. Prompt和LLM交互追踪（新）⭐
- **完整记录**：每个LLM调用都记录prompt和response
- **透明度**：可以看到系统如何与LLM交互
- **调试利器**：快速定位问题，优化prompt效果
- **详细说明**：[DETAILED_TRACKING.md](DETAILED_TRACKING.md)
- **示例**：[example_detailed_output.json](example_detailed_output.json)

**示例结构**：
```json
{
  "steps": [{
    "name": "generate_query",
    "detail": {
      "prompt": "完整的prompt文本...",
      "response": "LLM的响应..."
    }
  }]
}
```

### 4. 完善的缓存系统
- 分级缓存结构
- 支持断点续传
- 节省资源和成本

### 4. 详细的日志系统
- 结构化日志输出
- 清晰的步骤标记
- 便于调试和监控
```

## 缓存策略

### 缓存目录结构
```
.cache/
├── {question_hash}/                 # 每个问题一个文件夹
│   ├── question.txt                # 原始问题文本（方便查看）
│   ├── function_knowledge/         # function_knowledge模块缓存
│   │   ├── generated_query.txt     # 生成的query
│   │   ├── selected_tool.txt       # 选择的工具名
│   │   ├── tool_params.json        # 提取的工具参数（新）
│   │   ├── tool_result.json        # 工具执行结果
│   │   └── final_result.txt        # 最终结果
│   ├── multi_search/               # multi_search模块缓存
│   │   ├── final_knowledge.txt     # 最终合并知识
│   │   └── merged_knowledge.txt    # 合并后的知识
│   └── llm_search/                 # llm_search模块缓存
│       ├── generated_queries.json  # 生成的查询列表
│       ├── merged_knowledge.txt    # 合并后的知识
│       └── search_results/         # 搜索结果
│           ├── search_result_001.txt
│           ├── search_result_002.txt
│           └── search_result_003.txt
```

### 缓存优点
1. **节省资源**：避免重复调用LLM和搜索引擎
2. **断点续传**：任何步骤失败都可以从缓存恢复
3. **调试方便**：可以查看每个步骤的中间结果
4. **性能提升**：缓存命中时速度大幅提升

### 缓存key设计
- `function_knowledge`: 使用 `question||post_info||persona_info` 组合
- `multi_search`: 使用原始 `question`
- `llm_search`: 使用原始 `question`

## 日志系统

### 日志格式
```
[模块] 操作状态 - 描述
  ↓ 级联操作
  ✓ 成功
  ✗ 失败
  ⚠ 警告
  → 正在执行
```

### 日志层级

#### 1. Function Knowledge (最外层)
```
================================================================================
Function Knowledge - 开始处理
问题: ...
帖子信息: ...
人设信息: ...
================================================================================
[步骤1] 生成Query...
✓ 使用缓存的Query: ...
[步骤2] 选择工具...
  当前可用工具数: 1
  → 调用Gemini选择工具...
✓ 选择结果: wechat_search_article
[步骤3] 调用工具: wechat_search_article
  → 调用工具，参数: {'keyword': '...'}
✓ 工具调用完成
================================================================================
✓ Function Knowledge 完成 (结果长度: 123)
================================================================================
```

#### 2. Multi-Search (中层)
```
============================================================
Multi-Search - 开始处理问题: ...
============================================================
[渠道1] 调用 LLM Search...
  (LLM Search 内部日志)
✓ LLM Search 完成 (长度: 456)
[Multi-Search] 合并多渠道知识 - 1 个渠道
  有效渠道: ['LLM Search']
  → 调用Gemini合并多渠道知识...
✓ 多渠道知识合并完成 (长度: 450)
============================================================
✓ Multi-Search 完成 (最终长度: 450)
============================================================
```

#### 3. LLM Search (最内层)
```
============================================================
LLM Search - 开始处理问题: ...
============================================================
[步骤1] 生成搜索Query - 问题: ...
→ 调用Gemini生成query...
→ 解析生成的query...
✓ 成功生成 3 个query:
  1. query1
  2. query2
  3. query3
[步骤2] 批量搜索 - 共 3 个Query
  [1] 搜索Query: query1
  → 调用搜索引擎...
  ✓ 获取知识文本 (长度: 100)
  ...
✓ 批量搜索完成，获得 3 个有效结果
[步骤3] 合并知识 - 共 3 个文本
  有效文本数量: 3/3
  → 调用Gemini合并知识文本...
✓ 成功合并知识文本 (长度: 250)
============================================================
✓ LLM Search 完成 (最终长度: 250)
============================================================
```

## 使用示例

### 基本使用（启用缓存）
```python
from knowledge_v2.function_knowledge import get_knowledge

result = get_knowledge(
    question="去哪儿搜索微信文章？",
    post_info="无",
    persona_info="游戏博主"
)

# 访问执行结果
print(f"结果类型: {result['result']['type']}")
print(f"执行时间: {result['metadata']['execution_time']:.2f}秒")

# 如果是工具调用
if result['result']['type'] == 'tool':
    tool_info = result['execution']['tool_info']
    print(f"工具: {tool_info['tool_name']}")
    print(f"参数: {tool_info['parameters']}")

# 获取文本内容
content = result['result']['content']
```

### 禁用缓存
```python
from knowledge_v2.function_knowledge import FunctionKnowledge

agent = FunctionKnowledge(use_cache=False)
result = agent.get_knowledge(
    question="...",
    post_info="...",
    persona_info="..."
)
```

### 查看执行记录文件
执行后会生成格式化的JSON文件：
```
.cache/{question_hash}/execution_record.json
```
可以直接打开查看完整的执行过程。

### 清除缓存
```python
from knowledge_v2.cache_manager import CacheManager

cache = CacheManager()

# 清除特定问题的缓存
cache.clear("去哪儿搜索微信文章？")

# 清除所有缓存
cache.clear()
```

## 性能优化

### 缓存命中率统计
可通过日志中的 `✓ 使用缓存的...` 标记来统计缓存命中情况

### 建议
1. **首次运行**：完整流程，生成所有缓存
2. **后续运行**：大部分步骤使用缓存，只在必要时调用LLM
3. **调试时**：可关闭缓存或清除特定步骤缓存
4. **生产环境**：建议启用缓存，定期清理过期缓存

## 故障恢复

### 场景1：LLM调用失败
- 已完成的步骤有缓存
- 重新运行只需重试失败步骤

### 场景2：搜索引擎超时
- 部分query已有缓存
- 只需重试失败的query

### 场景3：网络中断
- 所有中间结果都有缓存
- 恢复后从断点继续

## 维护建议

1. **定期清理**：建议每周清理过期缓存（>7天）
2. **监控大小**：关注 `.cache` 目录大小
3. **备份重要**：可备份常用问题的缓存
