82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
|
# Agent 协同规则
|
|||
|
|
|
|||
|
|
本文档定义多个 Agent 并行开发本项目时的协作规范。
|
|||
|
|
|
|||
|
|
## 接口变更协议
|
|||
|
|
|
|||
|
|
三个服务之间的接口边界：
|
|||
|
|
|
|||
|
|
| 调用方 | 被调用方 | 接口定义位置 | 说明 |
|
|||
|
|
|--------|----------|-------------|------|
|
|||
|
|
| 前端 | Java 后端 | `chat_web_front/src/api/index.ts` | 所有 HTTP 请求 |
|
|||
|
|
| Java 后端 | Python RAG | `application-yj.yml` 中 `chat.host` = `localhost:7861` | 后端通过 OkHttp 调用 |
|
|||
|
|
| Python RAG | 外部 | `configs/model_config.py` 中 `ONLINE_LLM_MODEL` | LLM/Embedding API |
|
|||
|
|
|
|||
|
|
**变更规则：**
|
|||
|
|
- 修改任何对外 API 路径或参数时，必须同步修改调用方代码
|
|||
|
|
- 新增 API 在对应 Controller 中添加，并在前端 `api/index.ts` 中注册
|
|||
|
|
- 删除或修改 API 前确认没有其他地方引用
|
|||
|
|
|
|||
|
|
## 配置文件规则
|
|||
|
|
|
|||
|
|
以下文件包含运行中的数据库连接、API Key 等敏感配置，**修改前须确认**：
|
|||
|
|
|
|||
|
|
- `chat_web_backend/src/main/resources/application-yj.yml`
|
|||
|
|
- `langchain-chat/configs/model_config.py`（API Key、模型端点）
|
|||
|
|
- `langchain-chat/configs/kb_config.py`（MySQL 密码、Milvus 连接）
|
|||
|
|
- `chat_web_front/.env`（端口、代理地址）
|
|||
|
|
- `mysql/docker-compose.yml`、`milvus/docker-compose.yml`
|
|||
|
|
|
|||
|
|
## 提交规范
|
|||
|
|
|
|||
|
|
- Commit message 使用中文
|
|||
|
|
- 格式：`[模块] 变更描述`
|
|||
|
|
- 示例：
|
|||
|
|
- `[前端] 对话页面增加搜索历史功能`
|
|||
|
|
- `[后端] 修复文件上传超时问题`
|
|||
|
|
- `[RAG] 优化知识库检索召回策略`
|
|||
|
|
- `[基础设施] 更新 Milvus 版本至 2.6.5`
|
|||
|
|
- `[前端+后端] 新增翻译语种选择功能`
|
|||
|
|
|
|||
|
|
## 测试验证
|
|||
|
|
|
|||
|
|
修改代码后需验证对应服务正常运行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Java 后端
|
|||
|
|
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8099/chat_web_backend/app/user
|
|||
|
|
|
|||
|
|
# Python RAG
|
|||
|
|
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7861/docs
|
|||
|
|
|
|||
|
|
# 前端
|
|||
|
|
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3000/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 文件结构约定
|
|||
|
|
|
|||
|
|
| 路径 | 归属 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `chat_web_front/src/` | 前端代码 | Vue 组件、API、路由、Store |
|
|||
|
|
| `chat_web_backend/src/` | 后端代码 | Java 源码 |
|
|||
|
|
| `langchain-chat/` | RAG 代码 | Python 源码与配置 |
|
|||
|
|
| `scripts/` | 运维脚本 | 各服务启停脚本 |
|
|||
|
|
| `mysql/`、`milvus/` | 基础设施 | Docker Compose 与数据卷 |
|
|||
|
|
| `backend/` | 后端部署 | 打包好的 jar 与启动脚本 |
|
|||
|
|
| `logs/` | 日志 | 各服务运行日志 |
|
|||
|
|
| `docs/` | 文档 | 项目文档 |
|
|||
|
|
| `.harness/` | Agent 协同 | 本目录，Agent 读取的项目上下文 |
|
|||
|
|
|
|||
|
|
## .harness 文件维护
|
|||
|
|
|
|||
|
|
当项目发生以下变更时，必须同步更新 `.harness/` 下的对应文档：
|
|||
|
|
|
|||
|
|
- **新增/删除/重命名 API 接口** → 更新 `architecture.md` 中的 API 分组和接口说明
|
|||
|
|
- **修改端口、数据库连接、Profile 等配置** → 更新 `architecture.md` 中的运行配置表
|
|||
|
|
- **新增/删除页面路由** → 更新 `architecture.md` 中的页面路由表
|
|||
|
|
- **修改启动方式、构建命令、脚本** → 更新 `development-guide.md`
|
|||
|
|
- **新增模块或基础设施组件** → 更新 `CLAUDE.md` 项目结构表 + `architecture.md`
|
|||
|
|
- **变更分支策略、提交规范等协作规则** → 更新 `agent-coordination.md`
|
|||
|
|
|
|||
|
|
**原则：代码变更和文档更新应在同一次提交中完成，避免 `.harness/` 与实际代码不一致。**
|