From d4a236d0db5cae5030880667e4a2a534ed89b562 Mon Sep 17 00:00:00 2001 From: bruce Date: Fri, 29 May 2026 22:58:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(requirements):=20=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E9=9C=80=E6=B1=82=E6=96=87=E6=A1=A3=E4=B8=AD=E6=96=87=E5=91=BD?= =?UTF-8?q?=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../1.V1总需求文档.md} | 40 ++++++++++--------- .../2.模块需求索引.md} | 15 ++++--- .../3.配置模块需求.md} | 16 ++++---- .../4.场景模块需求.md} | 10 +++-- .../5.文档模块需求.md} | 22 +++++----- .../6.对话模块需求.md} | 9 +++-- .../7.审计模块需求.md} | 0 .../8.智能核心模块需求.md} | 26 ++++++++---- 8 files changed, 79 insertions(+), 59 deletions(-) rename docs/{requirements_v1.md => 需求分析/1.V1总需求文档.md} (89%) rename docs/{modules/00_module_requirements_index.md => 需求分析/2.模块需求索引.md} (72%) rename docs/{modules/01_config_module_requirements.md => 需求分析/3.配置模块需求.md} (80%) rename docs/{modules/02_scenarios_module_requirements.md => 需求分析/4.场景模块需求.md} (89%) rename docs/{modules/03_documents_module_requirements.md => 需求分析/5.文档模块需求.md} (77%) rename docs/{modules/04_chat_module_requirements.md => 需求分析/6.对话模块需求.md} (88%) rename docs/{modules/05_audit_module_requirements.md => 需求分析/7.审计模块需求.md} (100%) rename docs/{modules/06_agent_core_module_requirements.md => 需求分析/8.智能核心模块需求.md} (80%) diff --git a/docs/requirements_v1.md b/docs/需求分析/1.V1总需求文档.md similarity index 89% rename from docs/requirements_v1.md rename to docs/需求分析/1.V1总需求文档.md index a01bd7d..88454b9 100644 --- a/docs/requirements_v1.md +++ b/docs/需求分析/1.V1总需求文档.md @@ -56,7 +56,6 @@ Django Monolith | |-- 审计日志查看 | |-- Django Admin - | |-- 场景配置管理 | |-- 上传文件管理 | |-- 审计日志管理 | |-- 示例业务数据管理 @@ -83,7 +82,8 @@ Django Monolith | 数据库 | SQLite | V1 默认数据库，适合本地演示 | | 向量库 | Chroma | 本地 RAG 知识库 | | Agent Core | 自研轻量 Orchestrator | 保证可控、易讲解、易改题 | -| LLM 接入 | OpenAI API 兼容接口 | 方便切换 OpenAI、国产模型或本地代理 | +| LLM 接入 | OpenAI API 兼容接口 | 方便切换 OpenAI、硅基流动等兼容服务、国产模型或本地代理 | +| Embedding 接入 | OpenAI API 兼容接口 | 用于文档向量化，供应商可自主选择 | | 部署 | Docker + Docker Compose | 支持一键启动 | ## 5. 用户角色 @@ -142,7 +142,7 @@ V1 预置 5 类通用场景模板，用于覆盖大多数复试题型。 - 场景描述。 - Agent 角色。 - Agent 任务目标。 -- 系统提示词。 +- 系统提示词 可选。 - 是否启用 RAG。 - RAG 检索参数。 - 可用工具列表。 @@ -159,6 +159,7 @@ description: 用于分析生产质量异常、检索 SOP、生成处理建议 agent: role: 质量管理专家 goal: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告 + system_prompt: 你是质量管理专家，需要基于知识库和工具结果输出结构化质量分析报告 instructions: - 回答必须基于知识库或工具结果 - 不确定时必须说明缺失信息 @@ -170,8 +171,8 @@ rag: top_k: 5 tools: - - get_recent_defect_records - - calculate_defect_rate + - query_demo_records + - calculate_rate output: type: quality_report @@ -199,7 +200,7 @@ audit: 系统需要支持从预置模板中选择业务场景。 -V1 可以先从配置文件读取场景，不要求在页面上完成复杂编辑。 +V1 从 YAML 配置文件读取场景。后台管理只负责上传文件、审计日志和示例业务数据管理，不作为场景配置入口。 最低要求： @@ -216,7 +217,7 @@ Agent 对话页是核心演示页面。 - 当前场景名称。 - 用户输入框。 -- 文件上下文选择。 +- 文件上下文选择，可多选当前场景已入库文档；不选时默认使用当前场景全部已入库文档。 - Agent 输出区域。 - 结构化结果展示区域。 - 引用片段展示区域。 @@ -242,7 +243,7 @@ V1 支持的文件类型： - TXT - Markdown - PDF -- DOCX 可作为后续增强 +- DOCX - XLSX 可作为后续增强 文件上传后需要保存： @@ -355,7 +356,8 @@ V1 模型适配器需要支持： - 从环境变量读取 API Key。 - 从环境变量读取 Base URL。 - 从环境变量读取 Model Name。 -- 支持 OpenAI API 兼容格式。 +- 支持 OpenAI API 兼容格式，可接入 OpenAI、硅基流动等兼容供应商。 +- 支持独立配置 Embedding 模型，用于 RAG 入库和检索。 环境变量示例： @@ -363,6 +365,7 @@ V1 模型适配器需要支持： LLM_API_KEY=your_api_key LLM_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-4.1-mini +EMBEDDING_MODEL=text-embedding-3-small ``` ## 10. Dify 集成策略 @@ -496,17 +499,17 @@ V1 按 6 个核心模块拆分，具体模块需求见： | 模块 | 文档 | |---|---| -| Config | `docs/modules/01_config_module_requirements.md` | -| Scenarios | `docs/modules/02_scenarios_module_requirements.md` | -| Documents | `docs/modules/03_documents_module_requirements.md` | -| Chat | `docs/modules/04_chat_module_requirements.md` | -| Audit | `docs/modules/05_audit_module_requirements.md` | -| Agent Core | `docs/modules/06_agent_core_module_requirements.md` | +| 配置 | `docs/需求分析/3.配置模块需求.md` | +| 场景 | `docs/需求分析/4.场景模块需求.md` | +| 文档 | `docs/需求分析/5.文档模块需求.md` | +| 对话 | `docs/需求分析/6.对话模块需求.md` | +| 审计 | `docs/需求分析/7.审计模块需求.md` | +| 智能核心 | `docs/需求分析/8.智能核心模块需求.md` | 模块总览见： ```text -docs/modules/00_module_requirements_index.md +docs/需求分析/2.模块需求索引.md ``` ## 14. V1 验收标准 @@ -516,7 +519,7 @@ V1 完成后，需要满足以下验收标准： - 可以通过 Docker Compose 启动系统。 - 首页可以看到至少 5 个预置场景。 - 可以进入某个场景进行 Agent 对话。 -- 可以上传 TXT 或 Markdown 文件。 +- 可以上传 TXT、Markdown、PDF 或 DOCX 文件。 - 可以将上传文件写入本地知识库。 - Agent 回答时可以使用知识库检索结果。 - 至少支持 2 个内置工具调用。 @@ -554,9 +557,8 @@ V1 完成后，需要满足以下验收标准： V1 完成后，可以根据时间增加以下能力： -- 支持 DOCX 和 PDF 更完整解析。 - 支持 Excel 数据分析工具。 -- 支持 Django Admin 中编辑场景配置。 +- 支持后台页面编辑场景配置，并同步生成或更新 YAML。 - 支持流式输出。 - 支持 OpenAI Agents SDK Adapter。 - 支持 Dify API Adapter。 diff --git a/docs/modules/00_module_requirements_index.md b/docs/需求分析/2.模块需求索引.md similarity index 72% rename from docs/modules/00_module_requirements_index.md rename to docs/需求分析/2.模块需求索引.md index e84a2a2..ee50f30 100644 --- a/docs/modules/00_module_requirements_index.md +++ b/docs/需求分析/2.模块需求索引.md @@ -27,12 +27,12 @@ agent_core | 模块 | 文档 | 说明 | |---|---|---| -| Config | `01_config_module_requirements.md` | Django 项目配置、环境变量、部署配置 | -| Scenarios | `02_scenarios_module_requirements.md` | 场景模板、场景配置、场景列表 | -| Documents | `03_documents_module_requirements.md` | 文件上传、文件管理、RAG 入库入口 | -| Chat | `04_chat_module_requirements.md` | 对话页面、Agent 调用、结果展示 | -| Audit | `05_audit_module_requirements.md` | 审计日志、检索记录、工具调用记录 | -| Agent Core | `06_agent_core_module_requirements.md` | RAG、工具、模型调用、结构化输出、编排 | +| 配置 | `3.配置模块需求.md` | Django 项目配置、环境变量、部署配置 | +| 场景 | `4.场景模块需求.md` | 场景模板、场景配置、场景列表 | +| 文档 | `5.文档模块需求.md` | 文件上传、文件管理、RAG 入库入口 | +| 对话 | `6.对话模块需求.md` | 对话页面、Agent 调用、结果展示 | +| 审计 | `7.审计模块需求.md` | 审计日志、检索记录、工具调用记录 | +| 智能核心 | `8.智能核心模块需求.md` | RAG、工具、模型调用、结构化输出、编排 | ## 3. 模块依赖关系 @@ -62,7 +62,7 @@ agent_core 1. Config 模块：保证项目可启动。 2. Scenarios 模块：展示 5 个预置场景。 -3. Agent Core 最小闭环：输入问题，返回模拟结构化结果。 +3. 智能核心最小闭环：输入问题，通过 OpenAI 兼容模型接口返回结构化结果。 4. Chat 模块：页面调用 Agent Core。 5. Audit 模块：记录每次对话。 6. Documents 模块：上传文档。 @@ -83,4 +83,3 @@ agent_core - 工具调用和引用来源可以展示。 - 每次对话都有审计日志。 - Docker Compose 可以一键启动。 - diff --git a/docs/modules/01_config_module_requirements.md b/docs/需求分析/3.配置模块需求.md similarity index 80% rename from docs/modules/01_config_module_requirements.md rename to docs/需求分析/3.配置模块需求.md index 46c16b4..79a819f 100644 --- a/docs/modules/01_config_module_requirements.md +++ b/docs/需求分析/3.配置模块需求.md @@ -1,4 +1,4 @@ -# Config 模块需求文档 +# 配置模块需求文档 ## 1. 模块定位 @@ -9,7 +9,7 @@ Config 模块是 Django 项目的基础配置模块，负责系统启动、路 ## 2. 模块目标 - 支持本地开发和 Docker 部署两种运行方式。 -- 支持通过环境变量切换模型 API、数据库、调试模式和文件路径。 +- 支持通过环境变量切换模型 API、Embedding API、调试模式和文件路径。 - 统一注册 Django Apps、模板目录、静态资源目录和上传目录。 - 提供系统级 URL 路由入口。 - 为后续扩展 PostgreSQL、Redis、Celery 等组件预留配置空间。 @@ -25,7 +25,7 @@ Config 模块是 Django 项目的基础配置模块，负责系统启动、路 - SQLite 默认数据库配置。 - 静态文件和上传文件配置。 - Chroma 本地持久化目录配置。 -- LLM 相关环境变量配置。 +- LLM 与 Embedding 相关环境变量配置。 ### 3.2 不负责 @@ -44,10 +44,13 @@ Config 模块是 Django 项目的基础配置模块，负责系统启动、路 | `DJANGO_SECRET_KEY` | `dev-secret-key` | Django 密钥 | | `DJANGO_DEBUG` | `true` | 是否开启调试模式 | | `DJANGO_ALLOWED_HOSTS` | `*` | 允许访问的主机 | -| `DATABASE_URL` | 空 | V1 可不启用，默认 SQLite | +| `DATABASE_URL` | 空 | 预留配置，V1 默认 SQLite，不要求解析该配置 | | `LLM_API_KEY` | 空 | 大模型 API Key | -| `LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容接口地址 | +| `LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容接口地址，可接入 OpenAI、硅基流动等兼容服务 | | `LLM_MODEL` | `gpt-4.1-mini` | 默认模型名称 | +| `EMBEDDING_API_KEY` | 空 | Embedding API Key；为空时可复用 `LLM_API_KEY` | +| `EMBEDDING_BASE_URL` | 空 | Embedding OpenAI 兼容接口地址；为空时可复用 `LLM_BASE_URL` | +| `EMBEDDING_MODEL` | `text-embedding-3-small` | 默认 Embedding 模型名称 | | `CHROMA_PATH` | `data/chroma` | Chroma 持久化目录 | | `UPLOAD_ROOT` | `data/uploads` | 上传文件目录 | | `SCENARIO_CONFIG_DIR` | `configs` | 场景配置目录 | @@ -100,6 +103,5 @@ docker compose up --build - 项目可以通过 `docker compose up --build` 启动。 - `/admin/` 可以访问。 - 首页 `/` 可以访问。 -- 环境变量可以覆盖默认模型配置。 +- 环境变量可以覆盖默认 LLM 与 Embedding 配置。 - 上传目录和 Chroma 目录有明确配置。 - diff --git a/docs/modules/02_scenarios_module_requirements.md b/docs/需求分析/4.场景模块需求.md similarity index 89% rename from docs/modules/02_scenarios_module_requirements.md rename to docs/需求分析/4.场景模块需求.md index 6cf0a25..390645f 100644 --- a/docs/modules/02_scenarios_module_requirements.md +++ b/docs/需求分析/4.场景模块需求.md @@ -1,4 +1,4 @@ -# Scenarios 模块需求文档 +# 场景模块需求文档 ## 1. 模块定位 @@ -12,7 +12,7 @@ Scenarios 模块负责管理业务 Agent 场景，是整个平台快速适配未 - 展示可用业务 Agent 列表。 - 提供场景详情。 - 为 Chat 模块提供当前场景的完整配置。 -- 支持后续扩展为 Django Admin 可编辑场景。 +- 以 YAML 配置文件作为 V1 场景唯一事实来源。 ## 3. 职责边界 @@ -46,7 +46,7 @@ V1 预置 5 类场景模板： ## 5. 场景配置字段 -场景配置文件建议使用 YAML。 +场景配置文件使用 YAML。V1 的后台管理只管理上传文件、审计日志和示例业务数据等外围数据，不作为场景配置入口。 必填字段： @@ -58,6 +58,7 @@ V1 预置 5 类场景模板： | `agent.role` | string | Agent 角色 | | `agent.goal` | string | Agent 目标 | | `agent.instructions` | list[string] | Agent 指令 | +| `agent.system_prompt` | string | 可选字段；配置后优先作为系统提示词 | | `rag.enabled` | boolean | 是否启用 RAG | | `tools` | list[string] | 可用工具列表 | | `output.type` | string | 输出模板类型 | @@ -73,6 +74,7 @@ description: 检查合同、制度或 SOP 中的风险点和缺失项 agent: role: 文档审核专家 goal: 根据审核规则和知识库内容输出结构化审核意见 + system_prompt: "" instructions: - 只基于用户提供文档和知识库进行判断 - 不确定的问题必须标记为需人工复核 @@ -136,6 +138,6 @@ validate_scenario(config: dict) -> ValidationResult - 首页可以展示 5 个预置场景。 - 点击场景可以进入对应对话页。 - 场景配置来自配置文件，而不是硬编码在 View 中。 +- 后台管理不作为 V1 场景配置编辑入口。 - 缺失必填字段时能给出明确错误。 - Chat 模块可以根据 `scenario_id` 获取完整场景配置。 - diff --git a/docs/modules/03_documents_module_requirements.md b/docs/需求分析/5.文档模块需求.md similarity index 77% rename from docs/modules/03_documents_module_requirements.md rename to docs/需求分析/5.文档模块需求.md index 43a9042..8ff736e 100644 --- a/docs/modules/03_documents_module_requirements.md +++ b/docs/需求分析/5.文档模块需求.md @@ -1,4 +1,4 @@ -# Documents 模块需求文档 +# 文档模块需求文档 ## 1. 模块定位 @@ -40,14 +40,14 @@ V1 必须支持： |---|---|---| | 文本文档 | `.txt` | 第一优先级，最稳定 | | Markdown | `.md` | 适合准备知识库和规则 | +| PDF | `.pdf` | 复试常见材料格式，V1 抽取纯文本 | +| Word | `.docx` | 复试常见材料格式，V1 抽取段落文本 | -V1 可选支持： +后续增强： | 类型 | 扩展名 | 说明 | |---|---|---| -| PDF | `.pdf` | 复试常见，但解析复杂度略高 | -| Word | `.docx` | 后续增强 | -| Excel | `.xlsx` | 后续可作为业务数据源 | +| Excel | `.xlsx` | 后续可作为业务数据源或结构化表格导入 | ## 5. 数据模型需求 @@ -60,7 +60,7 @@ V1 可选支持： | `id` | int | 主键 | | `scenario_id` | string | 关联场景 ID | | `original_name` | string | 原始文件名 | -| `file` | FileField | 文件路径 | +| `file` | FileField | Django FileField 相对路径，不保存用户本机绝对路径 | | `file_type` | string | 文件类型 | | `size` | int | 文件大小 | | `status` | string | `uploaded` / `indexed` / `failed` | @@ -116,15 +116,17 @@ V1 文本抽取策略： - `.txt`：按 UTF-8 读取，失败时尝试系统默认编码。 - `.md`：按 UTF-8 读取，保留标题和正文。 -- `.pdf`：如果实现，优先抽取纯文本，不处理复杂版式。 +- `.pdf`：抽取纯文本，不要求 OCR、表格还原和复杂版式理解。 +- `.docx`：抽取段落、标题和普通表格文本，不要求完整保留 Word 样式。 + +入库失败后的文档允许重新触发入库。重新入库前需要清理或覆盖同一 `document_id` 对应的旧 chunk，避免重复检索。 ## 9. 验收标准 -- 可以上传 `.txt` 文件。 -- 可以上传 `.md` 文件。 +- 可以上传 `.txt`、`.md`、`.pdf`、`.docx` 文件。 - 上传后可以在文件列表看到记录。 - 文件可以关联到指定场景。 - 可以触发文件入库。 - 入库成功后状态变为 `indexed`。 - 入库失败时页面能显示失败原因。 - +- 入库失败的文档可以重新入库。 diff --git a/docs/modules/04_chat_module_requirements.md b/docs/需求分析/6.对话模块需求.md similarity index 88% rename from docs/modules/04_chat_module_requirements.md rename to docs/需求分析/6.对话模块需求.md index 49f566f..f3b9638 100644 --- a/docs/modules/04_chat_module_requirements.md +++ b/docs/需求分析/6.对话模块需求.md @@ -1,4 +1,4 @@ -# Chat 模块需求文档 +# 对话模块需求文档 ## 1. 模块定位 @@ -43,6 +43,7 @@ Chat 模块负责 Agent 对话页面和用户交互，是复试演示时最核 页面区域： - 当前场景摘要。 +- 当前场景下已入库文档多选框。 - 用户问题输入框。 - 提交按钮。 - Agent 结构化输出区域。 @@ -58,12 +59,15 @@ Chat 模块负责 Agent 对话页面和用户交互，是复试演示时最核 | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `message` | textarea | 是 | 用户业务问题 | +| `document_ids` | list[int] | 否 | 本次对话指定使用的已入库文档 | 校验规则： - 输入不能为空。 - 输入长度建议不超过 4000 字。 - 如果场景不存在，需要返回明确错误。 +- `document_ids` 只能包含当前场景下状态为 `indexed` 的文档。 +- 未选择文档时，默认使用当前场景下全部已入库文档作为 RAG 范围。 ## 6. Agent 执行流程 @@ -76,7 +80,7 @@ Chat 模块调用 Agent Core 的流程： ↓ 获取场景配置 ↓ -调用 agent_core.orchestrator.run() +调用 `run_agent(scenario_config, user_input, options=None)` ↓ 获取 AgentResult ↓ @@ -123,4 +127,3 @@ Agent Core 返回结果建议包含： - 页面能展示工具调用记录。 - 执行失败时有可理解的错误提示。 - 每次对话都会产生审计日志。 - diff --git a/docs/modules/05_audit_module_requirements.md b/docs/需求分析/7.审计模块需求.md similarity index 100% rename from docs/modules/05_audit_module_requirements.md rename to docs/需求分析/7.审计模块需求.md diff --git a/docs/modules/06_agent_core_module_requirements.md b/docs/需求分析/8.智能核心模块需求.md similarity index 80% rename from docs/modules/06_agent_core_module_requirements.md rename to docs/需求分析/8.智能核心模块需求.md index 4b83890..bb70b08 100644 --- a/docs/modules/06_agent_core_module_requirements.md +++ b/docs/需求分析/8.智能核心模块需求.md @@ -1,4 +1,4 @@ -# Agent Core 模块需求文档 +# 智能核心模块需求文档 ## 1. 模块定位 @@ -12,7 +12,7 @@ Agent Core 是系统的智能能力核心，负责根据场景配置完成 RAG - 根据场景配置组织 Prompt。 - 支持 RAG 检索。 - 支持工具注册与调用。 -- 支持 OpenAI API 兼容模型调用。 +- 支持 OpenAI API 兼容的 LLM 与 Embedding 调用，可自主接入 OpenAI、硅基流动等兼容服务。 - 支持结构化输出解析。 - 返回可审计的 AgentResult。 @@ -73,7 +73,7 @@ run_agent( 1. 读取场景配置。 2. 根据配置判断是否启用 RAG。 -3. 检索相关知识片段。 +3. 按 `scenario_id` 和可选 `document_ids` 检索相关知识片段。 4. 根据配置加载可用工具。 5. 构造系统提示词。 6. 调用大模型。 @@ -91,13 +91,14 @@ V1 可以使用轻量 Orchestrator，不强制引入完整 Agent SDK。 - 接收文档文本。 - 文本切分。 -- 生成 embedding。 +- 通过 OpenAI 兼容 Embedding Provider 生成 embedding。 - 写入 Chroma。 - 保存 metadata。 metadata 至少包含： - `scenario_id` +- `document_id` - `source_file` - `chunk_id` - `created_at` @@ -108,6 +109,7 @@ metadata 至少包含： - 根据用户问题检索相关片段。 - 支持按 `scenario_id` 过滤。 +- 支持按本次对话选择的 `document_ids` 过滤；未选择时使用当前场景全部已入库文档。 - 返回 top_k 结果。 - 返回内容、来源和分数。 @@ -140,7 +142,7 @@ V1 内置工具： `llm_provider.py` 负责模型调用。 -V1 需要支持 OpenAI API 兼容接口： +V1 需要支持 OpenAI API 兼容 LLM 接口： - `LLM_API_KEY` - `LLM_BASE_URL` @@ -152,6 +154,14 @@ V1 需要支持 OpenAI API 兼容接口： 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` 负责将模型输出转换为业务结构。 @@ -201,15 +211,15 @@ V1 默认使用 `LightweightOrchestrator`。 Adapter 需要保持同样输入输出： ```text -run(scenario_config, user_input, options=None) -> AgentResult +run_agent(scenario_config, user_input, options=None) -> AgentResult ``` ## 12. 验收标准 - Chat 模块可以调用 Agent Core 获得统一 AgentResult。 - RAG 可以按场景检索知识片段。 +- RAG 可以按本次对话选择的文档范围检索知识片段。 - 工具调用结果可以记录并返回。 -- 模型配置可以通过环境变量切换。 +- LLM 与 Embedding 配置可以通过环境变量切换。 - 结构化输出解析失败时不会导致整个流程崩溃。 - Agent Core 不依赖 Django View。 -