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

2026-05-29 21:09:03 +08:00
commit 569542bdea
12 changed files with 2047 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,154 @@
+# Universal Agent Demo Framework
+
+用于复试展示的通用 AI Agent Demo 框架。
+
+项目目标不是提前猜中某一个具体业务题，而是先准备一个可快速改题的基础平台。拿到复试题目后，可以通过修改场景配置、上传知识库、补充少量工具函数，快速完成一个可演示的企业业务 Agent。
+
+## 核心理念
+
+```text
+业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
+```
+
+## 技术路线
+
+V1 采用：
+
+- Django 单体应用
+- 独立 Agent Core 模块
+- SQLite
+- Chroma
+- Django Templates
+- Docker Compose
+- OpenAI API 兼容模型接口
+
+默认不强依赖 Dify。系统预留 Adapter 设计，后续可以接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。
+
+## 适用复试题型
+
+| 题型 | 推荐场景模板 |
+|---|---|
+| SOP 问答 | `knowledge_qa` |
+| 制度问答 | `knowledge_qa` |
+| 文档审核 | `document_review` |
+| 客服工单 | `ticket_assistant` |
+| 质量异常分析 | `quality_analysis` |
+| 财务审核 | `risk_audit` |
+| 采购审核 | `risk_audit` |
+| 合同风险分析 | `document_review` 或 `risk_audit` |
+
+## 模块划分
+
+```text
+config
+apps.scenarios
+apps.documents
+apps.chat
+apps.audit
+agent_core
+```
+
+职责边界：
+
+- Django Apps 负责页面、数据、文件、日志等企业应用外壳。
+- Agent Core 负责 RAG、工具调用、模型适配、结构化输出和 Agent 编排。
+- RAG、工具调用和模型调用不直接写进 Django View。
+
+## 推荐项目结构
+
+```text
+universal-agent-demo/
+  manage.py
+  requirements.txt
+  Dockerfile
+  docker-compose.yml
+  .env.example
+  README.md
+  AGENTS.md
+
+  config/
+  apps/
+    scenarios/
+    documents/
+    chat/
+    audit/
+
+  agent_core/
+    rag/
+    tools/
+    schemas/
+
+  configs/
+    knowledge_qa.yaml
+    document_review.yaml
+    ticket_assistant.yaml
+    quality_analysis.yaml
+    risk_audit.yaml
+
+  data/
+    uploads/
+    chroma/
+
+  docs/
+```
+
+## V1 功能范围
+
+V1 需要完成：
+
+- 场景列表。
+- Agent 对话页。
+- 文件上传。
+- 文档入库。
+- RAG 检索。
+- 内置工具调用。
+- 结构化输出展示。
+- 审计日志。
+- 模型 API 可配置。
+- Docker 一键启动。
+
+V1 暂不重点做：
+
+- 多租户。
+- 复杂权限。
+- 完整工作流引擎。
+- 前后端分离。
+- 深度 Dify 集成。
+- 生产级高并发优化。
+
+## 复试改题流程
+
+拿到题目后：
+
+1. 判断题目属于哪类模板。
+2. 复制最接近的 YAML 场景配置。
+3. 修改 Agent 角色、目标、指令和输出模板。
+4. 上传题目材料。
+5. 如需业务计算，新增一个工具函数。
+6. 用 2 到 3 个问题测试效果。
+7. 演示场景配置、知识库引用、工具调用、结构化输出和审计日志。
+
+## 计划启动方式
+
+本地启动：
+
+```bash
+python manage.py migrate
+python manage.py runserver
+```
+
+Docker 启动：
+
+```bash
+docker compose up --build
+```
+
+当前仓库处于需求和设计文档阶段，代码骨架尚未生成。
+
+## 文档入口
+
+- [V1 总需求文档](docs/requirements_v1.md)
+- [模块需求文档索引](docs/modules/00_module_requirements_index.md)
+- [Agent 设计文档](docs/agent_design.md)
+- [协作与编码约定](AGENTS.md)
+