docs(requirements): 统一需求文档中文命名

2026-05-29 22:58:21 +08:00
parent 569542bdea
commit d4a236d0db
8 changed files with 79 additions and 59 deletions
--- a/docs/需求分析/8.智能核心模块需求.md
+++ b/docs/需求分析/8.智能核心模块需求.md
@@ -0,0 +1,225 @@
+# 智能核心模块需求文档
+
+## 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。