docs: 初始化项目需求和协作文档

2026-05-29 21:09:03 +08:00
commit 569542bdea
12 changed files with 2047 additions and 0 deletions
--- a/docs/agent_design.md
+++ b/docs/agent_design.md
@@ -0,0 +1,211 @@
+# Agent 设计文档
+
+## 1. 设计目标
+
+Agent 设计的核心目标是支持未知复试题的快速适配。
+
+系统不针对单一业务写死，而是通过场景配置、知识库、工具和输出模板组合出不同业务 Agent。
+
+```text
+业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
+```
+
+## 2. Agent 类型
+
+V1 预置 5 类 Agent 场景：
+
+| Agent ID | 名称 | 适用场景 |
+|---|---|---|
+| `knowledge_qa` | 知识库问答助手 | SOP、制度、客服知识库 |
+| `document_review` | 文档审核助手 | 合同、制度、SOP、材料审核 |
+| `ticket_assistant` | 工单处理助手 | 客服、售后、运维工单 |
+| `quality_analysis` | 质量异常分析助手 | 生产、质检、缺陷分析 |
+| `risk_audit` | 风险审核助手 | 财务、采购、报销、合同风险 |
+
+## 3. Agent 执行链路
+
+```text
+用户输入
+  ↓
+加载场景配置
+  ↓
+判断是否启用 RAG
+  ↓
+检索知识库片段
+  ↓
+加载可用工具
+  ↓
+构造 Prompt
+  ↓
+调用大模型
+  ↓
+解析工具调用和结构化输出
+  ↓
+生成 AgentResult
+  ↓
+写入审计日志
+  ↓
+页面展示
+```
+
+## 4. 场景配置结构
+
+场景配置建议使用 YAML。
+
+```yaml
+id: quality_analysis
+name: 质量异常分析助手
+description: 用于分析生产质量异常、检索 SOP、生成处理建议
+
+agent:
+  role: 质量管理专家
+  goal: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告
+  instructions:
+    - 回答必须基于知识库或工具结果
+    - 不确定时必须说明缺失信息
+    - 涉及质量风险时给出风险等级
+
+rag:
+  enabled: true
+  collection: quality_docs
+  top_k: 5
+
+tools:
+  - get_recent_defect_records
+  - calculate_defect_rate
+
+output:
+  type: quality_report
+
+audit:
+  enabled: true
+  log_retrieval: true
+  log_tool_calls: true
+```
+
+## 5. Prompt 组成
+
+Prompt 建议由以下部分组成：
+
+```text
+系统角色
+任务目标
+行为约束
+输出格式要求
+知识库检索内容
+工具调用结果
+用户问题
+```
+
+V1 不追求复杂 Prompt 框架，优先保证可读、可改、可解释。
+
+## 6. RAG 策略
+
+RAG 在 V1 中负责给 Agent 提供题目材料和业务知识。
+
+入库流程：
+
+```text
+上传文件
+  ↓
+抽取文本
+  ↓
+文本切分
+  ↓
+生成 embedding
+  ↓
+写入 Chroma
+```
+
+检索流程：
+
+```text
+用户问题
+  ↓
+按 scenario_id 过滤
+  ↓
+向量检索 top_k
+  ↓
+返回片段内容、来源和分数
+```
+
+## 7. 工具调用策略
+
+工具用于补足大模型不能直接可靠完成的业务动作。
+
+V1 内置工具：
+
+| 工具 | 用途 |
+|---|---|
+| `calculate_rate` | 计算比例、缺陷率、通过率 |
+| `query_demo_records` | 查询模拟业务数据 |
+| `check_required_fields` | 检查必填项 |
+| `generate_action_items` | 生成行动项 |
+
+工具返回格式：
+
+```json
+{
+  "tool_name": "calculate_rate",
+  "success": true,
+  "arguments": {},
+  "result": {},
+  "error": ""
+}
+```
+
+## 8. 结构化输出
+
+V1 支持以下输出类型：
+
+- `general_answer`
+- `document_review_report`
+- `ticket_response`
+- `quality_report`
+- `risk_audit_report`
+
+结构化输出优先使用 JSON。
+
+解析失败时：
+
+- 保留模型原始输出。
+- 返回解析错误。
+- 页面展示原始回答。
+- 审计日志记录失败原因。
+
+## 9. AgentResult
+
+Agent Core 统一返回：
+
+```json
+{
+  "answer": "",
+  "structured_output": {},
+  "references": [],
+  "tool_calls": [],
+  "raw_output": "",
+  "model_name": "",
+  "latency_ms": 0,
+  "status": "success",
+  "error": ""
+}
+```
+
+## 10. Adapter 策略
+
+V1 默认使用自研轻量 Orchestrator。
+
+后续可以扩展：
+
+- OpenAI Agents SDK Adapter。
+- Dify API Adapter。
+- LangGraph Adapter。
+
+所有 Adapter 应保持统一接口：
+
+```text
+run(scenario_config, user_input, options=None) -> AgentResult
+```
+
+这样可以保证 Django 业务层不受底层 Agent 编排实现影响。
+
--- a/docs/modules/00_module_requirements_index.md
+++ b/docs/modules/00_module_requirements_index.md
@@ -0,0 +1,86 @@
+# 模块需求文档索引
+
+本文档用于汇总 Universal Agent Demo Framework V1 的模块拆分和需求文档位置。
+
+## 1. 模块拆分原则
+
+V1 按 6 个核心模块拆分：
+
+```text
+config
+apps.scenarios
+apps.documents
+apps.chat
+apps.audit
+agent_core
+```
+
+拆分原则：
+
+- Django Apps 负责业务外壳。
+- Agent Core 负责 AI 能力。
+- RAG、工具调用、模型适配不直接写进 View。
+- 第一版不做复杂权限、多租户和完整工作流。
+- 模块数量保持克制，方便复试前快速改题。
+
+## 2. 模块文档列表
+
+| 模块 | 文档 | 说明 |
+|---|---|---|
+| 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. 模块依赖关系
+
+```text
+apps.chat
+  |-- depends on apps.scenarios
+  |-- depends on apps.audit
+  |-- calls agent_core
+
+apps.documents
+  |-- depends on apps.scenarios
+  |-- calls agent_core.rag.ingest
+
+apps.audit
+  |-- stores result from apps.chat / agent_core
+
+agent_core
+  |-- reads scenario config object
+  |-- uses Chroma
+  |-- uses LLM Provider
+  |-- uses Tool Registry
+```
+
+## 4. 推荐开发顺序
+
+建议按以下顺序开发：
+
+1. Config 模块：保证项目可启动。
+2. Scenarios 模块：展示 5 个预置场景。
+3. Agent Core 最小闭环：输入问题，返回模拟结构化结果。
+4. Chat 模块：页面调用 Agent Core。
+5. Audit 模块：记录每次对话。
+6. Documents 模块：上传文档。
+7. Agent Core RAG：文档入库和检索。
+8. Agent Core 工具系统：增加内置工具。
+9. Docker：一键启动。
+
+## 5. V1 完成标准
+
+模块文档全部完成后，V1 的实现应满足：
+
+- 系统可以启动。
+- 首页可以看到 5 个场景。
+- 可以进入场景对话。
+- 可以上传文档。
+- 可以触发 RAG 入库。
+- Agent 可以返回结构化输出。
+- 工具调用和引用来源可以展示。
+- 每次对话都有审计日志。
+- Docker Compose 可以一键启动。
+
--- a/docs/modules/01_config_module_requirements.md
+++ b/docs/modules/01_config_module_requirements.md
@@ -0,0 +1,105 @@
+# Config 模块需求文档
+
+## 1. 模块定位
+
+Config 模块是 Django 项目的基础配置模块，负责系统启动、路由装配、环境变量读取、静态资源、文件存储、数据库、日志和第三方组件配置。
+
+该模块不承载业务逻辑，只负责让系统稳定启动，并为其他模块提供统一运行环境。
+
+## 2. 模块目标
+
+- 支持本地开发和 Docker 部署两种运行方式。
+- 支持通过环境变量切换模型 API、数据库、调试模式和文件路径。
+- 统一注册 Django Apps、模板目录、静态资源目录和上传目录。
+- 提供系统级 URL 路由入口。
+- 为后续扩展 PostgreSQL、Redis、Celery 等组件预留配置空间。
+
+## 3. 职责边界
+
+### 3.1 负责
+
+- Django `settings.py` 配置。
+- Django `urls.py` 总路由配置。
+- WSGI / ASGI 启动配置。
+- 环境变量读取。
+- SQLite 默认数据库配置。
+- 静态文件和上传文件配置。
+- Chroma 本地持久化目录配置。
+- LLM 相关环境变量配置。
+
+### 3.2 不负责
+
+- 不处理具体 Agent 业务逻辑。
+- 不解析场景 YAML。
+- 不处理文件入库。
+- 不直接调用大模型。
+- 不保存审计日志。
+
+## 4. 配置项需求
+
+系统至少需要支持以下环境变量：
+
+| 配置项 | 默认值 | 说明 |
+|---|---|---|
+| `DJANGO_SECRET_KEY` | `dev-secret-key` | Django 密钥 |
+| `DJANGO_DEBUG` | `true` | 是否开启调试模式 |
+| `DJANGO_ALLOWED_HOSTS` | `*` | 允许访问的主机 |
+| `DATABASE_URL` | 空 | V1 可不启用，默认 SQLite |
+| `LLM_API_KEY` | 空 | 大模型 API Key |
+| `LLM_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容接口地址 |
+| `LLM_MODEL` | `gpt-4.1-mini` | 默认模型名称 |
+| `CHROMA_PATH` | `data/chroma` | Chroma 持久化目录 |
+| `UPLOAD_ROOT` | `data/uploads` | 上传文件目录 |
+| `SCENARIO_CONFIG_DIR` | `configs` | 场景配置目录 |
+
+## 5. 目录需求
+
+系统启动时需要保证以下目录存在：
+
+```text
+data/
+  uploads/
+  chroma/
+  db.sqlite3
+
+configs/
+```
+
+如果目录不存在，V1 可以在初始化脚本或启动流程中创建。
+
+## 6. 路由需求
+
+总路由需要聚合以下模块路由：
+
+| 路径 | 模块 | 用途 |
+|---|---|---|
+| `/` | `apps.scenarios` | 首页和场景列表 |
+| `/chat/` | `apps.chat` | Agent 对话 |
+| `/documents/` | `apps.documents` | 文件上传和文档管理 |
+| `/audit/` | `apps.audit` | 审计日志查看 |
+| `/admin/` | Django Admin | 后台管理 |
+
+## 7. 启动需求
+
+本地启动：
+
+```bash
+python manage.py migrate
+python manage.py runserver
+```
+
+Docker 启动：
+
+```bash
+docker compose up --build
+```
+
+## 8. 验收标准
+
+- 项目可以通过 `python manage.py runserver` 启动。
+- 项目可以通过 `docker compose up --build` 启动。
+- `/admin/` 可以访问。
+- 首页 `/` 可以访问。
+- 环境变量可以覆盖默认模型配置。
+- 上传目录和 Chroma 目录有明确配置。
+
--- a/docs/modules/02_scenarios_module_requirements.md
+++ b/docs/modules/02_scenarios_module_requirements.md
@@ -0,0 +1,141 @@
+# Scenarios 模块需求文档
+
+## 1. 模块定位
+
+Scenarios 模块负责管理业务 Agent 场景，是整个平台快速适配未知复试题的核心入口。
+
+场景定义需要尽量配置化，避免把具体业务逻辑写死在 Django View 或 Agent Core 中。
+
+## 2. 模块目标
+
+- 读取预置场景配置。
+- 展示可用业务 Agent 列表。
+- 提供场景详情。
+- 为 Chat 模块提供当前场景的完整配置。
+- 支持后续扩展为 Django Admin 可编辑场景。
+
+## 3. 职责边界
+
+### 3.1 负责
+
+- 场景模板定义。
+- 场景配置文件读取。
+- 场景元信息展示。
+- 场景启用/禁用状态。
+- 场景与文档、审计日志的关联关系。
+
+### 3.2 不负责
+
+- 不执行 Agent 对话。
+- 不直接处理 RAG 检索。
+- 不直接调用工具。
+- 不直接调用大模型。
+- 不解析结构化输出。
+
+## 4. 场景模板需求
+
+V1 预置 5 类场景模板：
+
+| 模板 ID | 模板名称 | 适用题型 |
+|---|---|---|
+| `knowledge_qa` | 知识库问答助手 | SOP、制度、客服知识库、内部文档问答 |
+| `document_review` | 文档审核助手 | 合同审核、制度审核、材料合规检查 |
+| `ticket_assistant` | 工单处理助手 | 客服工单、售后工单、运维工单 |
+| `quality_analysis` | 质量异常分析助手 | 生产质量、缺陷分析、原因定位 |
+| `risk_audit` | 风险审核助手 | 财务审核、采购审核、报销审核、合同风险 |
+
+## 5. 场景配置字段
+
+场景配置文件建议使用 YAML。
+
+必填字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | string | 场景唯一标识 |
+| `name` | string | 场景名称 |
+| `description` | string | 场景说明 |
+| `agent.role` | string | Agent 角色 |
+| `agent.goal` | string | Agent 目标 |
+| `agent.instructions` | list[string] | Agent 指令 |
+| `rag.enabled` | boolean | 是否启用 RAG |
+| `tools` | list[string] | 可用工具列表 |
+| `output.type` | string | 输出模板类型 |
+| `audit.enabled` | boolean | 是否记录审计 |
+
+示例：
+
+```yaml
+id: document_review
+name: 文档审核助手
+description: 检查合同、制度或 SOP 中的风险点和缺失项
+
+agent:
+  role: 文档审核专家
+  goal: 根据审核规则和知识库内容输出结构化审核意见
+  instructions:
+    - 只基于用户提供文档和知识库进行判断
+    - 不确定的问题必须标记为需人工复核
+    - 输出必须包含风险等级和修改建议
+
+rag:
+  enabled: true
+  collection: document_review
+  top_k: 5
+
+tools:
+  - check_required_fields
+
+output:
+  type: document_review_report
+
+audit:
+  enabled: true
+```
+
+## 6. 页面需求
+
+### 6.1 场景列表页
+
+路径：`/`
+
+展示内容：
+
+- 场景名称。
+- 场景描述。
+- 适用题型。
+- 是否启用。
+- 进入对话按钮。
+
+### 6.2 场景详情页 可选
+
+路径：`/scenarios/<scenario_id>/`
+
+展示内容：
+
+- Agent 角色。
+- Agent 目标。
+- RAG 是否启用。
+- 可用工具列表。
+- 输出模板类型。
+
+V1 可以不做独立详情页，在对话页展示当前场景摘要即可。
+
+## 7. 服务接口需求
+
+Scenarios 模块至少需要提供以下服务函数：
+
+```text
+list_scenarios() -> list[ScenarioConfig]
+get_scenario(scenario_id: str) -> ScenarioConfig
+validate_scenario(config: dict) -> ValidationResult
+```
+
+## 8. 验收标准
+
+- 首页可以展示 5 个预置场景。
+- 点击场景可以进入对应对话页。
+- 场景配置来自配置文件，而不是硬编码在 View 中。
+- 缺失必填字段时能给出明确错误。
+- Chat 模块可以根据 `scenario_id` 获取完整场景配置。
+
--- a/docs/modules/03_documents_module_requirements.md
+++ b/docs/modules/03_documents_module_requirements.md
@@ -0,0 +1,130 @@
+# Documents 模块需求文档
+
+## 1. 模块定位
+
+Documents 模块负责文件上传、文件管理、文本抽取和知识库入库入口。
+
+该模块是复试题快速适配的关键模块。拿到题目材料后，用户需要能快速上传文档，并让 Agent 在对话中使用这些文档。
+
+## 2. 模块目标
+
+- 支持上传题目材料和知识库文件。
+- 保存文件元数据。
+- 支持按场景关联文件。
+- 提供文档入库入口。
+- 为 Agent Core 的 RAG 模块提供文件内容。
+
+## 3. 职责边界
+
+### 3.1 负责
+
+- 文件上传页面。
+- 文件保存。
+- 文件元数据记录。
+- 文件与场景关联。
+- 文本抽取入口。
+- 触发 RAG 入库。
+
+### 3.2 不负责
+
+- 不负责具体向量检索算法。
+- 不负责 embedding 生成细节。
+- 不负责 Agent 对话编排。
+- 不负责模型回答。
+
+## 4. 支持文件类型
+
+V1 必须支持：
+
+| 类型 | 扩展名 | 说明 |
+|---|---|---|
+| 文本文档 | `.txt` | 第一优先级，最稳定 |
+| Markdown | `.md` | 适合准备知识库和规则 |
+
+V1 可选支持：
+
+| 类型 | 扩展名 | 说明 |
+|---|---|---|
+| PDF | `.pdf` | 复试常见，但解析复杂度略高 |
+| Word | `.docx` | 后续增强 |
+| Excel | `.xlsx` | 后续可作为业务数据源 |
+
+## 5. 数据模型需求
+
+建议模型：`UploadedDocument`
+
+字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 主键 |
+| `scenario_id` | string | 关联场景 ID |
+| `original_name` | string | 原始文件名 |
+| `file` | FileField | 文件路径 |
+| `file_type` | string | 文件类型 |
+| `size` | int | 文件大小 |
+| `status` | string | `uploaded` / `indexed` / `failed` |
+| `error_message` | text | 入库失败原因 |
+| `created_at` | datetime | 上传时间 |
+| `updated_at` | datetime | 更新时间 |
+
+## 6. 页面需求
+
+### 6.1 文件上传页
+
+路径：`/documents/upload/`
+
+页面元素：
+
+- 场景选择下拉框。
+- 文件选择按钮。
+- 上传按钮。
+- 支持类型提示。
+- 上传结果提示。
+
+### 6.2 文件列表页
+
+路径：`/documents/`
+
+展示内容：
+
+- 文件名。
+- 所属场景。
+- 文件类型。
+- 文件大小。
+- 入库状态。
+- 上传时间。
+- 入库按钮。
+
+## 7. RAG 入库流程
+
+用户上传文件后，可以手动触发入库。
+
+流程：
+
+1. 用户上传文件。
+2. 系统保存文件和元数据。
+3. 用户点击入库按钮。
+4. Documents 模块读取文件文本。
+5. 调用 `agent_core.rag.ingest`。
+6. 入库成功后更新状态为 `indexed`。
+7. 入库失败后更新状态为 `failed` 并保存错误信息。
+
+## 8. 文本抽取需求
+
+V1 文本抽取策略：
+
+- `.txt`：按 UTF-8 读取，失败时尝试系统默认编码。
+- `.md`：按 UTF-8 读取，保留标题和正文。
+- `.pdf`：如果实现，优先抽取纯文本，不处理复杂版式。
+
+## 9. 验收标准
+
+- 可以上传 `.txt` 文件。
+- 可以上传 `.md` 文件。
+- 上传后可以在文件列表看到记录。
+- 文件可以关联到指定场景。
+- 可以触发文件入库。
+- 入库成功后状态变为 `indexed`。
+- 入库失败时页面能显示失败原因。
+
--- a/docs/modules/04_chat_module_requirements.md
+++ b/docs/modules/04_chat_module_requirements.md
@@ -0,0 +1,126 @@
+# Chat 模块需求文档
+
+## 1. 模块定位
+
+Chat 模块负责 Agent 对话页面和用户交互，是复试演示时最核心的入口。
+
+该模块接收用户问题，加载场景配置，调用 Agent Core 执行智能编排，并将结构化结果、引用来源、工具调用和审计信息展示给用户。
+
+## 2. 模块目标
+
+- 提供按场景进入的 Agent 对话页。
+- 支持用户输入业务问题。
+- 调用 Agent Core 执行完整 Agent 流程。
+- 展示结构化输出。
+- 展示 RAG 引用片段。
+- 展示工具调用记录。
+- 触发审计日志写入。
+
+## 3. 职责边界
+
+### 3.1 负责
+
+- 对话页面渲染。
+- 表单接收和校验。
+- 当前场景上下文传递。
+- 调用 Agent Core。
+- 展示 Agent 返回结果。
+
+### 3.2 不负责
+
+- 不直接读取 YAML 场景文件。
+- 不直接执行 RAG 检索。
+- 不直接执行工具函数。
+- 不直接调用大模型 API。
+- 不直接写复杂审计细节。
+
+## 4. 页面需求
+
+### 4.1 Agent 对话页
+
+路径：`/chat/<scenario_id>/`
+
+页面区域：
+
+- 当前场景摘要。
+- 用户问题输入框。
+- 提交按钮。
+- Agent 结构化输出区域。
+- 引用来源区域。
+- 工具调用区域。
+- 执行耗时区域。
+- 审计日志详情入口。
+
+## 5. 表单需求
+
+用户输入表单字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `message` | textarea | 是 | 用户业务问题 |
+
+校验规则：
+
+- 输入不能为空。
+- 输入长度建议不超过 4000 字。
+- 如果场景不存在，需要返回明确错误。
+
+## 6. Agent 执行流程
+
+Chat 模块调用 Agent Core 的流程：
+
+```text
+用户提交问题
+  ↓
+校验 scenario_id 和 message
+  ↓
+获取场景配置
+  ↓
+调用 agent_core.orchestrator.run()
+  ↓
+获取 AgentResult
+  ↓
+调用 Audit 模块记录日志
+  ↓
+渲染结果页面
+```
+
+## 7. AgentResult 展示需求
+
+Agent Core 返回结果建议包含：
+
+| 字段 | 说明 |
+|---|---|
+| `answer` | 自然语言回答 |
+| `structured_output` | 结构化结果 |
+| `references` | RAG 引用来源 |
+| `tool_calls` | 工具调用记录 |
+| `raw_output` | 模型原始输出 |
+| `latency_ms` | 执行耗时 |
+| `error` | 错误信息 |
+
+页面需要优先展示结构化结果。如果结构化解析失败，则展示自然语言回答和错误提示。
+
+## 8. 错误处理需求
+
+需要处理以下错误：
+
+| 错误 | 页面行为 |
+|---|---|
+| 场景不存在 | 显示场景不存在 |
+| 用户输入为空 | 显示表单错误 |
+| LLM API Key 缺失 | 显示模型配置缺失 |
+| RAG 检索失败 | 显示检索失败，但允许模型基于已有信息回答 |
+| 工具调用失败 | 显示工具失败信息，并继续生成结果 |
+| 结构化解析失败 | 展示原始回答，并提示结构化解析失败 |
+
+## 9. 验收标准
+
+- 可以从场景列表进入对话页。
+- 可以提交问题并获得 Agent 输出。
+- 页面能展示结构化结果。
+- 页面能展示引用来源。
+- 页面能展示工具调用记录。
+- 执行失败时有可理解的错误提示。
+- 每次对话都会产生审计日志。
+
--- a/docs/modules/05_audit_module_requirements.md
+++ b/docs/modules/05_audit_module_requirements.md
@@ -0,0 +1,143 @@
+# Audit 模块需求文档
+
+## 1. 模块定位
+
+Audit 模块负责记录和展示 Agent 执行过程，是项目体现企业级能力的重要模块。
+
+复试演示时，审计日志用于证明系统不是黑盒问答，而是可以追踪输入、检索、工具调用、模型输出和执行耗时。
+
+## 2. 模块目标
+
+- 记录每次 Agent 对话。
+- 记录 RAG 检索片段。
+- 记录工具调用详情。
+- 记录模型输出和结构化结果。
+- 提供审计日志列表和详情页。
+- 支持按场景查看日志。
+
+## 3. 职责边界
+
+### 3.1 负责
+
+- 审计日志数据模型。
+- 日志写入服务。
+- 日志列表页面。
+- 日志详情页面。
+- 工具调用记录展示。
+- RAG 引用记录展示。
+
+### 3.2 不负责
+
+- 不执行 Agent。
+- 不执行工具调用。
+- 不执行 RAG 检索。
+- 不参与模型生成。
+- 不做复杂权限控制。
+
+## 4. 数据模型需求
+
+建议模型：`AgentAuditLog`
+
+字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 主键 |
+| `scenario_id` | string | 场景 ID |
+| `scenario_name` | string | 场景名称 |
+| `user_input` | text | 用户输入 |
+| `retrieved_chunks` | JSON | 检索片段 |
+| `tool_calls` | JSON | 工具调用记录 |
+| `structured_output` | JSON | 结构化输出 |
+| `final_answer` | text | 最终回答 |
+| `raw_output` | text | 模型原始输出 |
+| `model_name` | string | 模型名称 |
+| `latency_ms` | int | 执行耗时 |
+| `status` | string | `success` / `failed` |
+| `error_message` | text | 错误信息 |
+| `created_at` | datetime | 创建时间 |
+
+## 5. 日志写入需求
+
+Audit 模块需要提供服务函数：
+
+```text
+create_audit_log(
+  scenario_id,
+  scenario_name,
+  user_input,
+  agent_result
+) -> AgentAuditLog
+```
+
+写入规则：
+
+- Agent 成功时，记录完整结果。
+- Agent 失败时，也要记录用户输入、场景和错误信息。
+- RAG 片段和工具调用使用 JSON 保存。
+- 不记录 API Key 等敏感配置。
+
+## 6. 页面需求
+
+### 6.1 审计日志列表页
+
+路径：`/audit/`
+
+展示字段：
+
+- 日志 ID。
+- 场景名称。
+- 用户输入摘要。
+- 状态。
+- 模型名称。
+- 执行耗时。
+- 创建时间。
+- 详情入口。
+
+### 6.2 审计日志详情页
+
+路径：`/audit/<log_id>/`
+
+展示内容：
+
+- 用户输入。
+- 最终回答。
+- 结构化输出。
+- RAG 检索片段。
+- 工具调用记录。
+- 模型名称。
+- 执行耗时。
+- 错误信息。
+
+## 7. 检索片段展示需求
+
+每个引用片段建议包含：
+
+| 字段 | 说明 |
+|---|---|
+| `source` | 来源文件名 |
+| `chunk_id` | 片段 ID |
+| `content` | 片段内容 |
+| `score` | 相似度分数 |
+
+## 8. 工具调用展示需求
+
+每次工具调用建议包含：
+
+| 字段 | 说明 |
+|---|---|
+| `tool_name` | 工具名称 |
+| `arguments` | 调用参数 |
+| `result` | 工具结果 |
+| `success` | 是否成功 |
+| `error` | 错误信息 |
+
+## 9. 验收标准
+
+- 每次对话成功后都会生成审计日志。
+- Agent 执行失败时也会生成失败日志。
+- 审计列表可以查看所有日志。
+- 审计详情可以查看用户输入、检索片段、工具调用和最终输出。
+- 日志中不保存 API Key。
+- 可以根据日志解释一次 Agent 输出的依据。
+
--- a/docs/modules/06_agent_core_module_requirements.md
+++ b/docs/modules/06_agent_core_module_requirements.md
@@ -0,0 +1,215 @@
+# Agent Core 模块需求文档
+
+## 1. 模块定位
+
+Agent Core 是系统的智能能力核心，负责根据场景配置完成 RAG 检索、工具调用、大模型调用和结构化输出。
+
+该模块应保持独立于 Django View，方便后续迁移为独立服务，或接入 OpenAI Agents SDK、Dify 等外部编排引擎。
+
+## 2. 模块目标
+
+- 提供统一 Agent 执行入口。
+- 根据场景配置组织 Prompt。
+- 支持 RAG 检索。
+- 支持工具注册与调用。
+- 支持 OpenAI API 兼容模型调用。
+- 支持结构化输出解析。
+- 返回可审计的 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. 检索相关知识片段。
+4. 根据配置加载可用工具。
+5. 构造系统提示词。
+6. 调用大模型。
+7. 执行必要的工具调用。
+8. 解析结构化输出。
+9. 返回 AgentResult。
+
+V1 可以使用轻量 Orchestrator，不强制引入完整 Agent SDK。
+
+## 6. RAG 需求
+
+### 6.1 入库
+
+`rag/ingest.py` 负责：
+
+- 接收文档文本。
+- 文本切分。
+- 生成 embedding。
+- 写入 Chroma。
+- 保存 metadata。
+
+metadata 至少包含：
+
+- `scenario_id`
+- `source_file`
+- `chunk_id`
+- `created_at`
+
+### 6.2 检索
+
+`rag/retriever.py` 负责：
+
+- 根据用户问题检索相关片段。
+- 支持按 `scenario_id` 过滤。
+- 返回 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_API_KEY`
+- `LLM_BASE_URL`
+- `LLM_MODEL`
+
+接口需要隐藏不同模型供应商差异，对 Orchestrator 暴露统一方法：
+
+```text
+generate(messages, response_format=None) -> LLMResponse
+```
+
+## 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(scenario_config, user_input, options=None) -> AgentResult
+```
+
+## 12. 验收标准
+
+- Chat 模块可以调用 Agent Core 获得统一 AgentResult。
+- RAG 可以按场景检索知识片段。
+- 工具调用结果可以记录并返回。
+- 模型配置可以通过环境变量切换。
+- 结构化输出解析失败时不会导致整个流程崩溃。
+- Agent Core 不依赖 Django View。
+
--- a/docs/requirements_v1.md
+++ b/docs/requirements_v1.md
@@ -0,0 +1,565 @@
+# Universal Agent Demo Framework V1 需求文档
+
+## 1. 项目背景
+
+本项目用于复试展示。复试题目暂时未知，但大概率围绕企业生产、质量、客服、财务、SOP、文档审核、工单处理等场景。
+
+项目目标不是提前猜中某一个具体业务题，而是先搭建一个通用 AI Agent Demo 底座。拿到复试题目后，可以通过修改场景配置、上传知识库、补充少量业务工具，快速生成一个可演示的业务 Agent 系统。
+
+核心理念：
+
+```text
+业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
+```
+
+## 2. 项目目标
+
+V1 版本目标是实现一个可运行、可演示、可快速改题的基础平台。
+
+系统需要支持：
+
+- 通过配置快速创建不同业务 Agent。
+- 支持上传文档并构建 RAG 知识库。
+- 支持根据场景调用内置业务工具。
+- 支持结构化输出，方便展示报告、风险点、建议动作等结果。
+- 支持审计日志，记录用户输入、检索内容、工具调用和模型输出。
+- 支持 Docker 一键启动，降低复试现场环境风险。
+- 支持快速替换大模型 API。
+
+## 3. 非目标
+
+V1 不追求完整企业级平台能力，以下内容暂不作为第一版重点：
+
+- 复杂权限系统。
+- 多租户管理。
+- 完整工作流引擎。
+- 复杂多 Agent 协作。
+- 前后端分离架构。
+- 深度集成 Dify。
+- 生产级高并发优化。
+- 完整在线文档协同编辑。
+
+## 4. 技术方案
+
+### 4.1 总体架构
+
+V1 使用 Django 单体应用承载企业系统外壳，Agent Core 作为独立 Python 模块承载智能编排能力。
+
+```text
+Django Monolith
+  |
+  |-- Web UI
+  |   |-- 场景选择
+  |   |-- Agent 对话
+  |   |-- 文件上传
+  |   |-- 结构化结果展示
+  |   |-- 审计日志查看
+  |
+  |-- Django Admin
+  |   |-- 场景配置管理
+  |   |-- 上传文件管理
+  |   |-- 审计日志管理
+  |   |-- 示例业务数据管理
+  |
+  |-- Agent Core
+  |   |-- 场景配置加载
+  |   |-- RAG 检索
+  |   |-- 工具注册与调用
+  |   |-- 大模型适配
+  |   |-- 结构化输出解析
+  |
+  |-- Storage
+      |-- SQLite
+      |-- Chroma
+      |-- Uploaded Files
+```
+
+### 4.2 技术栈
+
+| 模块 | 技术 | 说明 |
+|---|---|---|
+| Web 框架 | Django | 负责页面、模型、后台、文件上传和业务管理 |
+| 页面渲染 | Django Templates + Bootstrap | 降低前端复杂度，快速完成 Demo |
+| 数据库 | SQLite | V1 默认数据库，适合本地演示 |
+| 向量库 | Chroma | 本地 RAG 知识库 |
+| Agent Core | 自研轻量 Orchestrator | 保证可控、易讲解、易改题 |
+| LLM 接入 | OpenAI API 兼容接口 | 方便切换 OpenAI、国产模型或本地代理 |
+| 部署 | Docker + Docker Compose | 支持一键启动 |
+
+## 5. 用户角色
+
+V1 只设计一个主要用户角色：
+
+### Demo 操作者
+
+通常是复试时的展示者，负责选择场景、上传材料、输入问题、查看 Agent 输出和审计记录。
+
+暂不区分管理员、业务人员、审核人员等复杂角色。
+
+## 6. 核心使用流程
+
+### 6.1 复试前准备流程
+
+1. 启动系统。
+2. 选择或复制一个已有场景模板。
+3. 根据题目修改场景配置。
+4. 上传题目相关文档。
+5. 如有必要，补充一个业务工具函数。
+6. 运行一次测试对话。
+7. 使用审计日志确认 RAG、工具调用和输出链路正常。
+
+### 6.2 复试演示流程
+
+1. 打开系统首页。
+2. 展示系统支持多个业务场景。
+3. 选择当前题目对应的 Agent。
+4. 上传或选择知识库文档。
+5. 输入业务问题。
+6. 展示 Agent 的结构化输出。
+7. 展示引用来源、工具调用和审计日志。
+8. 说明同一平台可通过配置切换到其他业务场景。
+
+## 7. 场景模板
+
+V1 预置 5 类通用场景模板，用于覆盖大多数复试题型。
+
+| 模板 ID | 模板名称 | 适用题型 |
+|---|---|---|
+| knowledge_qa | 知识库问答助手 | SOP、制度、客服知识库、内部文档问答 |
+| document_review | 文档审核助手 | 合同审核、制度审核、SOP 审核、材料合规检查 |
+| ticket_assistant | 工单处理助手 | 客服工单、售后工单、运维工单 |
+| quality_analysis | 质量异常分析助手 | 生产质量、缺陷分析、原因定位 |
+| risk_audit | 风险审核助手 | 财务审核、采购审核、报销审核、合同风险 |
+
+## 8. 场景配置需求
+
+场景应通过 YAML 或 JSON 文件定义，避免把业务逻辑写死在代码中。
+
+配置内容包括：
+
+- 场景 ID。
+- 场景名称。
+- 场景描述。
+- Agent 角色。
+- Agent 任务目标。
+- 系统提示词。
+- 是否启用 RAG。
+- RAG 检索参数。
+- 可用工具列表。
+- 输出模板类型。
+- 审计策略。
+
+示例：
+
+```yaml
+id: quality_analysis
+name: 质量异常分析助手
+description: 用于分析生产质量异常、检索 SOP、生成处理建议
+
+agent:
+  role: 质量管理专家
+  goal: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告
+  instructions:
+    - 回答必须基于知识库或工具结果
+    - 不确定时必须说明缺失信息
+    - 涉及质量风险时给出风险等级
+
+rag:
+  enabled: true
+  collection: quality_docs
+  top_k: 5
+
+tools:
+  - get_recent_defect_records
+  - calculate_defect_rate
+
+output:
+  type: quality_report
+
+audit:
+  enabled: true
+  log_retrieval: true
+  log_tool_calls: true
+```
+
+## 9. 功能需求
+
+### 9.1 首页
+
+首页需要展示系统定位和可用场景列表。
+
+页面能力：
+
+- 查看所有 Agent 场景。
+- 进入某个场景的对话页。
+- 查看最近审计日志入口。
+- 查看文件上传入口。
+
+### 9.2 场景选择
+
+系统需要支持从预置模板中选择业务场景。
+
+V1 可以先从配置文件读取场景，不要求在页面上完成复杂编辑。
+
+最低要求：
+
+- 展示场景名称。
+- 展示场景描述。
+- 展示场景适用题型。
+- 点击后进入对应 Agent 对话页。
+
+### 9.3 Agent 对话
+
+Agent 对话页是核心演示页面。
+
+页面需要包含：
+
+- 当前场景名称。
+- 用户输入框。
+- 文件上下文选择。
+- Agent 输出区域。
+- 结构化结果展示区域。
+- 引用片段展示区域。
+- 工具调用展示区域。
+
+Agent 执行流程：
+
+1. 接收用户问题。
+2. 加载当前场景配置。
+3. 如果启用 RAG，则检索相关知识片段。
+4. 根据场景判断是否调用工具。
+5. 调用大模型生成结果。
+6. 解析为结构化输出。
+7. 写入审计日志。
+8. 返回页面展示。
+
+### 9.4 文件上传
+
+系统需要支持上传题目材料和知识库文档。
+
+V1 支持的文件类型：
+
+- TXT
+- Markdown
+- PDF
+- DOCX 可作为后续增强
+- XLSX 可作为后续增强
+
+文件上传后需要保存：
+
+- 原始文件名。
+- 文件路径。
+- 文件类型。
+- 上传时间。
+- 关联场景。
+- 是否已入库。
+
+### 9.5 RAG 知识库
+
+系统需要支持将上传文档写入向量库，并在 Agent 对话时检索。
+
+V1 RAG 流程：
+
+1. 读取上传文件文本。
+2. 按固定长度切分文本。
+3. 生成 embedding。
+4. 写入 Chroma collection。
+5. 对话时根据用户问题检索 top_k 片段。
+6. 将片段作为上下文传给 Agent。
+7. 在结果中展示引用来源。
+
+### 9.6 工具调用
+
+系统需要提供一个工具注册机制。
+
+V1 内置工具建议包括：
+
+| 工具名 | 用途 |
+|---|---|
+| calculate_rate | 计算比例、缺陷率、通过率等指标 |
+| query_demo_records | 查询模拟业务数据 |
+| check_required_fields | 检查文档或表单必填项 |
+| generate_action_items | 根据问题生成行动项 |
+
+工具调用需要记录到审计日志中。
+
+### 9.7 结构化输出
+
+不同场景需要不同输出模板。
+
+V1 至少支持以下输出类型：
+
+#### 通用问答输出
+
+- answer
+- references
+- confidence
+
+#### 文档审核输出
+
+- summary
+- issues
+- risk_level
+- suggestions
+- missing_items
+- references
+
+#### 工单处理输出
+
+- reply
+- category
+- priority
+- suggested_action
+- need_human_review
+
+#### 质量分析输出
+
+- summary
+- possible_causes
+- evidence
+- risk_level
+- suggested_actions
+- references
+
+### 9.8 审计日志
+
+系统需要记录每次 Agent 执行过程。
+
+审计字段：
+
+- 日志 ID。
+- 场景 ID。
+- 用户输入。
+- 检索片段。
+- 工具调用记录。
+- 模型名称。
+- 结构化输出。
+- 原始输出。
+- 执行耗时。
+- 创建时间。
+
+审计日志页面需要支持：
+
+- 查看日志列表。
+- 查看单条日志详情。
+- 展示检索内容。
+- 展示工具调用。
+- 展示最终输出。
+
+### 9.9 模型适配
+
+系统需要通过统一接口调用大模型，避免模型 API 写死。
+
+V1 模型适配器需要支持：
+
+- 从环境变量读取 API Key。
+- 从环境变量读取 Base URL。
+- 从环境变量读取 Model Name。
+- 支持 OpenAI API 兼容格式。
+
+环境变量示例：
+
+```env
+LLM_API_KEY=your_api_key
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4.1-mini
+```
+
+## 10. Dify 集成策略
+
+V1 不把 Dify 作为核心依赖。
+
+原因：
+
+- 复试现场需要最大程度保证可控。
+- 自研 Agent Core 更方便解释架构设计。
+- 题目未知时，直接依赖外部平台会增加部署和调试风险。
+- Django + Agent Core 已能覆盖第一版演示需求。
+
+系统预留 Agent Engine Adapter 概念，后续可接入 Dify、OpenAI Agents SDK 或其他企业 AI 平台。
+
+V1 默认引擎：
+
+```text
+Lightweight Orchestrator
+```
+
+后续可扩展：
+
+```text
+Dify API Adapter
+OpenAI Agents SDK Adapter
+LangGraph Adapter
+```
+
+## 11. Docker 部署需求
+
+系统需要支持 Docker Compose 一键启动。
+
+基础命令：
+
+```bash
+docker compose up --build
+```
+
+V1 容器内容：
+
+- Django Web 服务。
+- SQLite 数据文件挂载。
+- Chroma 数据目录挂载。
+- 上传文件目录挂载。
+
+V1 暂不强制引入 PostgreSQL。如果后续需要更正式的部署效果，可以在 Docker Compose 中增加 PostgreSQL 服务。
+
+## 12. 推荐项目结构
+
+```text
+universal-agent-demo/
+  manage.py
+  requirements.txt
+  Dockerfile
+  docker-compose.yml
+  .env.example
+  README.md
+
+  config/
+    settings.py
+    urls.py
+    wsgi.py
+    asgi.py
+
+  apps/
+    scenarios/
+      models.py
+      admin.py
+      services.py
+
+    chat/
+      views.py
+      urls.py
+      forms.py
+
+    documents/
+      models.py
+      views.py
+      services.py
+
+    audit/
+      models.py
+      admin.py
+      services.py
+
+  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
+
+  configs/
+    knowledge_qa.yaml
+    document_review.yaml
+    ticket_assistant.yaml
+    quality_analysis.yaml
+    risk_audit.yaml
+
+  data/
+    uploads/
+    chroma/
+    db.sqlite3
+
+  templates/
+    base.html
+    home.html
+    chat/index.html
+    documents/upload.html
+    audit/logs.html
+
+  static/
+    css/
+    js/
+```
+
+## 13. 模块需求文档
+
+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` |
+
+模块总览见：
+
+```text
+docs/modules/00_module_requirements_index.md
+```
+
+## 14. V1 验收标准
+
+V1 完成后，需要满足以下验收标准：
+
+- 可以通过 Docker Compose 启动系统。
+- 首页可以看到至少 5 个预置场景。
+- 可以进入某个场景进行 Agent 对话。
+- 可以上传 TXT 或 Markdown 文件。
+- 可以将上传文件写入本地知识库。
+- Agent 回答时可以使用知识库检索结果。
+- 至少支持 2 个内置工具调用。
+- Agent 输出可以以结构化方式展示。
+- 每次对话都会生成审计日志。
+- 审计日志中可以查看用户问题、检索内容、工具调用和最终输出。
+- 可以通过环境变量切换大模型 API 地址和模型名。
+
+## 15. 复试改题策略
+
+拿到题目后，优先按以下步骤适配：
+
+1. 判断题目属于哪类模板。
+2. 复制最接近的 YAML 场景配置。
+3. 修改 Agent 角色、任务目标和输出模板。
+4. 上传题目给出的文档或样例数据。
+5. 如果题目需要业务计算，则新增一个工具函数。
+6. 用 2 到 3 个测试问题验证效果。
+7. 演示时重点展示配置、知识库、工具调用、结构化输出和审计日志。
+
+题型映射：
+
+| 题目类型 | 优先模板 |
+|---|---|
+| SOP 问答 | knowledge_qa |
+| 制度问答 | knowledge_qa |
+| 文档审核 | document_review |
+| 客服处理 | ticket_assistant |
+| 质量异常分析 | quality_analysis |
+| 财务审核 | risk_audit |
+| 采购审核 | risk_audit |
+| 合同风险分析 | document_review 或 risk_audit |
+
+## 16. 后续迭代方向
+
+V1 完成后，可以根据时间增加以下能力：
+
+- 支持 DOCX 和 PDF 更完整解析。
+- 支持 Excel 数据分析工具。
+- 支持 Django Admin 中编辑场景配置。
+- 支持流式输出。
+- 支持 OpenAI Agents SDK Adapter。
+- 支持 Dify API Adapter。
+- 支持 PostgreSQL 部署模式。
+- 支持简单登录认证。
+- 支持演示数据一键初始化。