# 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、硅基流动等兼容服务、国产模型或本地代理 | | Embedding 接入 | OpenAI API 兼容接口 | 用于文档向量化，供应商可自主选择 | | 部署 | 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: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告 system_prompt: 你是质量管理专家，需要基于知识库和工具结果输出结构化质量分析报告 instructions: - 回答必须基于知识库或工具结果 - 不确定时必须说明缺失信息 - 涉及质量风险时给出风险等级 rag: enabled: true collection: quality_docs top_k: 5 tools: - query_demo_records - calculate_rate output: type: quality_report audit: enabled: true log_retrieval: true log_tool_calls: true ``` ## 9. 功能需求 ### 9.1 首页 首页需要展示系统定位和可用场景列表。 页面能力： - 查看所有 Agent 场景。 - 进入某个场景的对话页。 - 查看最近审计日志入口。 - 查看文件上传入口。 ### 9.2 场景选择 系统需要支持从预置模板中选择业务场景。 V1 从 YAML 配置文件读取场景。后台管理只负责上传文件、审计日志和示例业务数据管理，不作为场景配置入口。 最低要求： - 展示场景名称。 - 展示场景描述。 - 展示场景适用题型。 - 点击后进入对应 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 兼容格式，可接入 OpenAI、硅基流动等兼容供应商。 - 支持独立配置 Embedding 模型，用于 RAG 入库和检索。 环境变量示例： ```env DJANGO_SECRET_KEY=replace-with-a-local-secret-key DJANGO_DEBUG=true DJANGO_ALLOWED_HOSTS=* LLM_API_KEY=your_api_key LLM_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-4.1-mini EMBEDDING_API_KEY= EMBEDDING_BASE_URL= EMBEDDING_MODEL=text-embedding-3-small SCENARIO_CONFIG_DIR=configs UPLOAD_ROOT=data/uploads CHROMA_PATH=data/chroma ``` 补充说明： - `EMBEDDING_API_KEY` 为空时可复用 `LLM_API_KEY`。 - `EMBEDDING_BASE_URL` 为空时可复用 `LLM_BASE_URL`。 - `.env.example` 仅作为模板，不允许放真实密钥。 - 当前 V1 代码会在 settings 初始化时自动读取根目录 `.env`，本地运行与 `pytest` 可复用同一套配置；当前 Docker Compose 配置也通过 `env_file` 读取 `.env`。 ## 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 个核心模块拆分，具体模块需求见： | 模块 | 文档 | |---|---| | 配置 | `docs/需求分析/3.配置模块需求.md` | | 场景 | `docs/需求分析/4.场景模块需求.md` | | 文档 | `docs/需求分析/5.文档模块需求.md` | | 对话 | `docs/需求分析/6.对话模块需求.md` | | 审计 | `docs/需求分析/7.审计模块需求.md` | | 智能核心 | `docs/需求分析/8.智能核心模块需求.md` | 模块总览见： ```text docs/需求分析/2.模块需求索引.md ``` ## 14. V1 验收标准 V1 完成后，需要满足以下验收标准： - 可以通过 Docker Compose 启动系统。 - 首页可以看到至少 5 个预置场景。 - 可以进入某个场景进行 Agent 对话。 - 可以上传 TXT、Markdown、PDF 或 DOCX 文件。 - 可以将上传文件写入本地知识库。 - 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 完成后，可以根据时间增加以下能力： - 支持 Excel 数据分析工具。 - 支持后台页面编辑场景配置，并同步生成或更新 YAML。 - 支持流式输出。 - 支持 OpenAI Agents SDK Adapter。 - 支持 Dify API Adapter。 - 支持 PostgreSQL 部署模式。 - 支持简单登录认证。 - 支持演示数据一键初始化。