# qaagent67 — 文档问答智能体 ❓

不断加入文件，然后针对内容提问。回答带引用来源，经过事实核查。

## 快速使用

```bash
# 启动问答智能体
lambdagent run agentexample/qaagent67/agent-config.yml "加入 docs/ 目录下的所有文件"
```

## 对话示例

```
用户: 加入 /path/to/docs 目录下的所有文件

qaagent: ✅ 索引完成
  文件数: 12
  总块数: 184
  知识库: qaagent_default

  文件清单:
    paper.pdf (pdf) → 28 个块
    api.py (py) → 15 个块
    config.md (md) → 8 个块
    ...

用户: 这些文件里提到了哪些性能优化建议？

qaagent: 根据文档，有以下性能优化建议:

  1. 使用数据库连接池 (pool_size=20) 减少连接开销
     [来源: config.md §3, perf.py L42]

  2. 对热点查询使用 Redis 缓存
     [来源: architecture.md §4.2]

  3. API 响应使用 lru_cache 装饰器
     [来源: api.py L120]

  ✓ 以上所有建议均已通过原文验证。

用户: 知识库里现在有哪些文件？

qaagent: 📋 知识库状态 (qaagent_default):
  总文件: 12 个
  总块数: 184 个
  ...

用户: 对比 api.py 和 auth.py 的鉴权方式有什么差异？

qaagent: (判断: 这是对比分析 → 调用 DeepAnalysis)

🔬 深度分析 — 3 路并行检索完成

  1. api.py 的鉴权实现:
     使用 JWT Bearer Token，在中间件层验证 [来源: api.py L15-30]

  2. auth.py 的鉴权实现:
     使用 OAuth2 + PKCE 流程，支持第三方登录 [来源: auth.py L42-80]

  3. 共同点:
     都使用 HTTPS + CORS 白名单 [来源: config.md §security]

  **结论**: api.py 适合内部微服务通信 (JWT 无状态),
  auth.py 适合面向用户的前端应用 (OAuth2 标准流程)。
```

## 架构: 混合模式 (工具 + SubAgent)

```
简单操作 → ReAct + 工具 (快, 零 LLM 成本)
复杂推理 → SubAgent 并行编排 (深, 多路检索+综合)

判断标准: 主 Agent 根据问题类型自动选择

三层架构:
  Layer 1 — Skill (7 个)
    file-reader, chunk-splitter, knowledge-indexer    ← 纯工具，无 LLM
    context-retriever                                 ← 纯工具，向量搜索
    answer-generator, source-citer, fact-checker      ← 需要 LLM

  Layer 2 — Pattern (2 个)
    喂文件: map_reduce (分而治之模式)
    提问:   pipeline + review (流水线 + 审查模式)

  Layer 3 — Orchestration
    agent-config.yml (ReAct 主循环，选择调用哪个工具)
```

## 工具

| 工具 | 功能 | 模式 | LLM? |
|------|------|------|------|
| `IngestFiles` | 批量喂文件 (文件/目录/glob) | map_reduce (工具) | 否 |
| `QueryKnowledge` | 简单事实查询 | pipeline (工具) | 否 (检索) |
| `DeepAnalysis` | 复杂对比/总结/评估 | fan_out_merge (SubAgent) | 是 (并行) |
| `ListKnowledge` | 查看已索引文件 | 直接 (工具) | 否 |
| `RemoveKnowledge` | 删除文件索引 | 直接 (工具) | 否 |

### 何时用 QueryKnowledge vs DeepAnalysis

```
QueryKnowledge (快):
  "API 端口是多少？"       → 精确查找
  "用了什么数据库？"        → 事实检索

DeepAnalysis (深):
  "对比 A 和 B 的差异"     → 多路并行检索 + 对比分析
  "从安全和性能角度评估"    → 多维度并行 + 综合
  "总结所有文件核心观点"    → 逐文件检索 + 合并
```

## 支持的文件格式

txt, md, py, js, ts, java, go, rs, c, cpp, css, html, xml, json, yaml, yml,
toml, ini, sh, sql, rb, php, swift, kt, pdf, csv, log

## 配置

```yaml
# 关键配置项
model:
  provider: ollama                 # 或 dashscope
  name: qwen2.5:32b
  baseUrl: http://localhost:11434

rag:
  collection: maritime_rag         # 知识库名称
  chunkSize: 512                   # 分块大小 (token)
  topK: 5                          # 检索返回数量

runtime:
  engine: cek                      # CEK 引擎: 成本监控 + 循环检测
  costBudget: 0.50                 # 最大成本 $0.50
```

### 路径配置（可部署适配）

所有文件路径集中在 `agent-config.yml` 的 `knowledge` 字段，部署时只需修改这里：

```yaml
knowledge:
  baseDir: /data/knowledge/maritime              # 知识库根目录
  rawDir: /data/knowledge/maritime/raw           # 原始 PDF/文档
  processedDir: /data/knowledge/maritime/processed  # 提取后的文本
  indexFile: /data/knowledge/maritime/rag_index.json
  keywordFile: /data/knowledge/maritime/rag_index.keywords.json
```

Python 代码通过读取 YAML 获取路径，不硬编码：

```python
# search_engine.py / app.py 都从配置读取
config_path = os.environ.get("AGENT_CONFIG", "agent-config.yml")
with open(config_path) as f:
    config = yaml.safe_load(f)
knowledge_dir = config["knowledge"]["baseDir"]
```

环境变量 fallback：`AGENT_CONFIG` 指定配置文件路径，`KNOWLEDGE_DIR` 指定知识库目录。

## Skill 定义

位于 `skills/` 目录:
- `answer-generator.yml` — 回答生成器 (LLM)
- `source-citer.yml` — 来源标注器 (LLM)
- `fact-checker.yml` — 事实核查器 (LLM, 审查模式审查者)