Bruce/DEMO-AGENT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
bruce
2026-05-29 22:58:21 +08:00
parent 569542bdea
commit d4a236d0db
8 changed files with 79 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/requirements_v1.md → docs/需求分析/1.V1总需求文档.md
View File

@@ -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。

15
docs/modules/00_module_requirements_index.md → docs/需求分析/2.模块需求索引.md
View File

@@ -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 可以一键启动。

16
docs/modules/01_config_module_requirements.md → docs/需求分析/3.配置模块需求.md
View File

@@ -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 目录有明确配置。

10
docs/modules/02_scenarios_module_requirements.md → docs/需求分析/4.场景模块需求.md
View File

@@ -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` 获取完整场景配置。

22
docs/modules/03_documents_module_requirements.md → docs/需求分析/5.文档模块需求.md
View File

@@ -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`。
- 入库失败时页面能显示失败原因。
- 入库失败的文档可以重新入库。

9
docs/modules/04_chat_module_requirements.md → docs/需求分析/6.对话模块需求.md
View File

@@ -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 返回结果建议包含：
- 页面能展示工具调用记录。
- 执行失败时有可理解的错误提示。
- 每次对话都会产生审计日志。

0
docs/modules/05_audit_module_requirements.md → docs/需求分析/7.审计模块需求.md
View File

26
docs/modules/06_agent_core_module_requirements.md → docs/需求分析/8.智能核心模块需求.md
View File

@@ -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。