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

AGENTS.md

@@ -0,0 +1,134 @@
+# AGENTS.md
+
+本文档约定本项目后续由人或编码 Agent 协作开发时需要遵守的边界、风格和实现顺序。
+
+## 项目定位
+
+Universal Agent Demo Framework 是一个用于复试展示的通用 AI Agent Demo 框架。
+
+优先目标：
+
+- 快速适配未知复试题。
+- 保证本地可运行。
+- 保证代码结构清楚，方便讲解。
+- 避免为了平台完整性牺牲改题速度。
+
+## 架构原则
+
+采用：
+
+```text
+Django 单体 + 独立 Agent Core + Docker Compose
+```
+
+核心边界：
+
+- Django 负责页面、数据库、文件上传、审计日志和后台管理。
+- Agent Core 负责 RAG、Prompt、工具调用、模型适配和结构化输出。
+- Django View 不直接写大模型调用、向量检索和工具执行细节。
+- Agent Core 不依赖 Django View。
+
+## 模块边界
+
+### config
+
+负责 Django 项目配置、URL 总入口、环境变量、静态资源、上传路径和部署配置。
+
+### apps.scenarios
+
+负责场景列表、场景配置读取、场景元信息展示。
+
+### apps.documents
+
+负责文件上传、文件记录、文件状态和触发 RAG 入库。
+
+### apps.chat
+
+负责对话页面、用户输入表单、调用 Agent Core 和展示结果。
+
+### apps.audit
+
+负责审计日志模型、日志写入服务、日志列表和详情页。
+
+### agent_core
+
+负责 Agent 编排、RAG、工具注册、LLM Provider、结构化输出和 Adapter 扩展。
+
+## 开发顺序
+
+建议按以下顺序推进：
+
+1. 创建 Django 项目骨架。
+2. 完成 Config 模块。
+3. 完成 Scenarios 模块，先展示 5 个场景。
+4. 完成 Agent Core 最小闭环，先返回模拟结果。
+5. 完成 Chat 页面，打通对话链路。
+6. 完成 Audit 模块，记录每次对话。
+7. 完成 Documents 模块，支持上传文件。
+8. 完成 RAG 入库和检索。
+9. 完成内置工具系统。
+10. 补 Docker Compose 一键启动。
+
+## 编码约定
+
+- Python 代码优先保持简单、直观、可讲解。
+- 不为了抽象而抽象。
+- View 只做请求处理和页面渲染，复杂逻辑放到 `services.py` 或 `agent_core`。
+- 配置化优先，业务场景不要写死在代码中。
+- 工具函数必须通过 Tool Registry 注册。
+- 模型调用必须通过 LLM Provider，不允许散落在业务代码中。
+- 审计日志要记录成功和失败两种情况。
+- 不在日志中保存 API Key、密钥或敏感环境变量。
+
+## 文档约定
+
+需求文档放在：
+
+```text
+docs/
+```
+
+模块需求文档放在：
+
+```text
+docs/modules/
+```
+
+场景配置放在：
+
+```text
+configs/
+```
+
+重要设计变更需要同步更新：
+
+- `README.md`
+- `docs/requirements_v1.md`
+- 相关模块需求文档
+
+## 测试与验证约定
+
+每个阶段至少验证：
+
+- Django 可以启动。
+- 首页可以访问。
+- 场景列表可显示。
+- 对话流程可执行。
+- 出错时页面有清晰提示。
+- 审计日志能记录。
+- Docker Compose 可以启动。
+
+## 不优先做的事项
+
+第一版不要优先做：
+
+- React / Vue 前端。
+- 多租户。
+- 复杂 RBAC。
+- 完整工作流引擎。
+- 深度 Dify 集成。
+- 微服务拆分。
+- 分布式任务队列。
+
+这些内容可以作为后续增强，不应影响 V1 快速成型。
+