DEMO-AGENT/docs/需求分析/1.V1总需求文档.md

Universal Agent Demo Framework V1 需求文档

1. 项目背景

本项目用于复试展示。复试题目暂时未知，但大概率围绕企业生产、质量、客服、财务、SOP、文档审核、工单处理等场景。

项目目标不是提前猜中某一个具体业务题，而是先搭建一个通用 AI Agent Demo 底座。拿到复试题目后，可以通过修改场景配置、上传知识库、补充少量业务工具，快速生成一个可演示的业务 Agent 系统。

核心理念：

业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器

2. 项目目标

V1 版本目标是实现一个可运行、可演示、可快速改题的基础平台。

系统需要支持：

• 通过配置快速创建不同业务 Agent。
• 支持上传文档并构建 RAG 知识库。
• 支持根据场景调用内置业务工具。
• 支持结构化输出，方便展示报告、风险点、建议动作等结果。
• 支持审计日志，记录用户输入、检索内容、工具调用和模型输出。
• 支持 Docker 一键启动，降低复试现场环境风险。
• 支持快速替换大模型 API。

3. 非目标

V1 不追求完整企业级平台能力，以下内容暂不作为第一版重点：

• 复杂权限系统。
• 多租户管理。
• 完整工作流引擎。
• 复杂多 Agent 协作。
• 前后端分离架构。
• 深度集成 Dify。
• 生产级高并发优化。
• 完整在线文档协同编辑。

4. 技术方案

4.1 总体架构

V1 使用 Django 单体应用承载企业系统外壳，Agent Core 作为独立 Python 模块承载智能编排能力。

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 检索参数。
• 可用工具列表。
• 输出模板类型。
• 审计策略。

示例：

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 入库和检索。

环境变量示例：

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 集成策略

V1 不把 Dify 作为核心依赖。

原因：

• 复试现场需要最大程度保证可控。
• 自研 Agent Core 更方便解释架构设计。
• 题目未知时，直接依赖外部平台会增加部署和调试风险。
• Django + Agent Core 已能覆盖第一版演示需求。

系统预留 Agent Engine Adapter 概念，后续可接入 Dify、OpenAI Agents SDK 或其他企业 AI 平台。

V1 默认引擎：

Lightweight Orchestrator

后续可扩展：

Dify API Adapter
OpenAI Agents SDK Adapter
LangGraph Adapter

11. Docker 部署需求

系统需要支持 Docker Compose 一键启动。

基础命令：

docker compose up --build

V1 容器内容：

• Django Web 服务。
• SQLite 数据文件挂载。
• Chroma 数据目录挂载。
• 上传文件目录挂载。

V1 暂不强制引入 PostgreSQL。如果后续需要更正式的部署效果，可以在 Docker Compose 中增加 PostgreSQL 服务。

12. 推荐项目结构

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

模块总览见：

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 部署模式。
• 支持简单登录认证。
• 支持演示数据一键初始化。