# 智能核心模块需求文档

## 1. 模块定位

Agent Core 是系统的智能能力核心，负责根据场景配置完成 RAG 检索、工具调用、大模型调用和结构化输出。

该模块应保持独立于 Django View，方便后续迁移为独立服务，或接入 OpenAI Agents SDK、Dify 等外部编排引擎。

## 2. 模块目标

- 提供统一 Agent 执行入口。
- 根据场景配置组织 Prompt。
- 支持 RAG 检索。
- 支持工具注册与调用。
- 支持 OpenAI API 兼容的 LLM 与 Embedding 调用，可自主接入 OpenAI、硅基流动等兼容服务。
- 支持结构化输出解析。
- 返回可审计的 AgentResult。

## 3. 职责边界

### 3.1 负责

- Agent 编排。
- 场景配置对象消费。
- RAG 入库和检索核心逻辑。
- 工具注册和工具执行。
- LLM Provider 适配。
- 输出结构化解析。
- 生成 AgentResult。

### 3.2 不负责

- 不渲染页面。
- 不直接处理 Django 表单。
- 不直接保存 Django Model。
- 不管理用户登录。
- 不负责 Docker 部署。

## 4. 子模块划分

```text
agent_core/
  orchestrator.py
  scenario_loader.py
  llm_provider.py
  tool_registry.py
  structured_output.py

  rag/
    ingest.py
    retriever.py

  tools/
    builtin_tools.py

  schemas/
    outputs.py
```

## 5. Orchestrator 需求

`orchestrator.py` 提供统一入口：

```text
run_agent(
  scenario_config,
  user_input,
  options=None
) -> AgentResult
```

执行流程：

1. 读取场景配置。
2. 根据配置判断是否启用 RAG。
3. 按 `scenario_id` 和可选 `document_ids` 检索相关知识片段。
4. 根据配置加载可用工具。
5. 构造系统提示词。
6. 调用大模型。
7. 执行必要的工具调用。
8. 解析结构化输出。
9. 返回 AgentResult。

V1 可以使用轻量 Orchestrator，不强制引入完整 Agent SDK。

## 6. RAG 需求

### 6.1 入库

`rag/ingest.py` 负责：

- 接收文档文本。
- 文本切分。
- 通过 OpenAI 兼容 Embedding Provider 生成 embedding。
- 写入 Chroma。
- 保存 metadata。

metadata 至少包含：

- `scenario_id`
- `document_id`
- `source_file`
- `chunk_id`
- `created_at`

### 6.2 检索

`rag/retriever.py` 负责：

- 根据用户问题检索相关片段。
- 支持按 `scenario_id` 过滤。
- 支持按本次对话选择的 `document_ids` 过滤；未选择时使用当前场景全部已入库文档。
- 返回 top_k 结果。
- 返回内容、来源和分数。

## 7. 工具系统需求

`tool_registry.py` 负责工具注册、查找和执行。

V1 内置工具：

| 工具名 | 说明 |
|---|---|
| `calculate_rate` | 计算通过率、缺陷率、占比等 |
| `query_demo_records` | 查询模拟业务数据 |
| `check_required_fields` | 检查必填项是否缺失 |
| `generate_action_items` | 生成行动项清单 |

工具执行结果需要统一格式：

```json
{
  "tool_name": "calculate_rate",
  "success": true,
  "arguments": {},
  "result": {},
  "error": ""
}
```

## 8. LLM Provider 需求

`llm_provider.py` 负责模型调用。

V1 需要支持 OpenAI API 兼容 LLM 接口：

- `LLM_API_KEY`
- `LLM_BASE_URL`
- `LLM_MODEL`

接口需要隐藏不同模型供应商差异，对 Orchestrator 暴露统一方法：

```text
generate(messages, response_format=None) -> LLMResponse
```

Embedding 也通过 OpenAI 兼容接口接入：

- `EMBEDDING_API_KEY`
- `EMBEDDING_BASE_URL`
- `EMBEDDING_MODEL`

当 Embedding 专用 Key 或 Base URL 为空时，可以复用 LLM 的 Key 和 Base URL。RAG 入库和检索必须通过真实 embedding 与 Chroma 完成，模拟 embedding 或简单文本匹配只能作为开发阶段临时桩，不计入 V1 验收。

## 9. 结构化输出需求

`structured_output.py` 负责将模型输出转换为业务结构。

V1 输出类型：

- `general_answer`
- `document_review_report`
- `ticket_response`
- `quality_report`
- `risk_audit_report`

解析策略：

- 优先要求模型直接返回 JSON。
- JSON 解析成功则展示结构化结果。
- JSON 解析失败则保留原始输出，并返回解析错误。

## 10. AgentResult 需求

Agent Core 最终返回统一结果对象。

字段：

| 字段 | 说明 |
|---|---|
| `answer` | 最终自然语言回答 |
| `structured_output` | 结构化输出 |
| `references` | RAG 引用片段 |
| `tool_calls` | 工具调用记录 |
| `raw_output` | 模型原始输出 |
| `model_name` | 模型名称 |
| `latency_ms` | 执行耗时 |
| `status` | `success` / `failed` |
| `error` | 错误信息 |

## 11. Adapter 扩展需求

V1 默认使用 `LightweightOrchestrator`。

后续可扩展：

- OpenAI Agents SDK Adapter。
- Dify API Adapter。
- LangGraph Adapter。

Adapter 需要保持同样输入输出：

```text
run_agent(scenario_config, user_input, options=None) -> AgentResult
```

## 12. 验收标准

- Chat 模块可以调用 Agent Core 获得统一 AgentResult。
- RAG 可以按场景检索知识片段。
- RAG 可以按本次对话选择的文档范围检索知识片段。
- 工具调用结果可以记录并返回。
- LLM 与 Embedding 配置可以通过环境变量切换。
- 结构化输出解析失败时不会导致整个流程崩溃。
- Agent Core 不依赖 Django View。