chore(master): 清理V2合并后的旧版遗留文件
This commit is contained in:
172
AGENTS.md
172
AGENTS.md
@@ -1,172 +0,0 @@
|
||||
# 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 一键启动。
|
||||
|
||||
当前仓库状态说明:
|
||||
|
||||
- Django 单体骨架已完成。
|
||||
- 5 个预置场景 YAML 已接通首页和对话页。
|
||||
- Agent Core 已具备 Prompt 编排、结构化解析、工具注册和 RAG fallback / Chroma 双路径。
|
||||
- Chat、Documents、Audit 页面已经可以形成完整演示闭环。
|
||||
- 全量测试已覆盖主要模块行为,并默认隔离真实 LLM 网络调用。
|
||||
|
||||
## 编码约定
|
||||
|
||||
- Python 代码优先保持简单、直观、可讲解。
|
||||
- 不为了抽象而抽象。
|
||||
- View 只做请求处理和页面渲染,复杂逻辑放到 `services.py` 或 `agent_core`。
|
||||
- 配置化优先,业务场景不要写死在代码中。
|
||||
- 工具函数必须通过 Tool Registry 注册。
|
||||
- 模型调用必须通过 LLM Provider,不允许散落在业务代码中。
|
||||
- 审计日志要记录成功和失败两种情况。
|
||||
- 不在日志中保存 API Key、密钥或敏感环境变量。
|
||||
- 新增或重构模块时,优先补清晰的中文注释,说明职责边界、输入输出和设计取舍。
|
||||
- 页面模板优先直接表达业务信息,不在模板中堆积复杂逻辑判断。
|
||||
- 测试优先覆盖服务层和核心编排逻辑,再由页面测试补齐关键展示行为。
|
||||
|
||||
## 文档约定
|
||||
|
||||
需求文档放在:
|
||||
|
||||
```text
|
||||
docs/
|
||||
```
|
||||
|
||||
需求分析文档放在:
|
||||
|
||||
```text
|
||||
docs/需求分析/
|
||||
```
|
||||
|
||||
设计文档放在:
|
||||
|
||||
```text
|
||||
docs/设计文档/
|
||||
```
|
||||
|
||||
场景配置放在:
|
||||
|
||||
```text
|
||||
configs/
|
||||
```
|
||||
|
||||
重要设计变更需要同步更新:
|
||||
|
||||
- `README.md`
|
||||
- `docs/需求分析/1.V1总需求文档.md`
|
||||
- 相关模块需求文档
|
||||
- `AGENTS.md` 中的协作边界与当前实现状态
|
||||
|
||||
推荐同步文档的场景:
|
||||
|
||||
- 新增用户可见页面或流程。
|
||||
- 调整环境变量、生效方式或部署命令。
|
||||
- 修改 Agent Core 的输入输出合约。
|
||||
- 新增工具、审计字段或场景配置字段。
|
||||
|
||||
## 测试与验证约定
|
||||
|
||||
每个阶段至少验证:
|
||||
|
||||
- Django 可以启动。
|
||||
- 首页可以访问。
|
||||
- 场景列表可显示。
|
||||
- 对话流程可执行。
|
||||
- 出错时页面有清晰提示。
|
||||
- 审计日志能记录。
|
||||
- Docker Compose 可以启动。
|
||||
|
||||
当前默认验证命令:
|
||||
|
||||
```bash
|
||||
pytest
|
||||
python manage.py check
|
||||
docker compose config
|
||||
```
|
||||
|
||||
补充约定:
|
||||
|
||||
- 若本地 `.env` 存在真实模型密钥,测试仍应保持可离线执行。
|
||||
- 每完成一项功能或一轮重构后,应先跑相关测试,再跑全量测试或核心回归测试。
|
||||
- 完成改动后,按逻辑分组使用 Conventional Commit 风格提交到本地。
|
||||
|
||||
## 不优先做的事项
|
||||
|
||||
第一版不要优先做:
|
||||
|
||||
- React / Vue 前端。
|
||||
- 多租户。
|
||||
- 复杂 RBAC。
|
||||
- 完整工作流引擎。
|
||||
- 深度 Dify 集成。
|
||||
- 微服务拆分。
|
||||
- 分布式任务队列。
|
||||
|
||||
这些内容可以作为后续增强,不应影响 V1 快速成型。
|
||||
Reference in New Issue
Block a user