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