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/` 与实际代码不一致。**
|