gangyan/.harness/agent-coordination.md

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
  • [前端+后端] 新增翻译语种选择功能

测试验证

修改代码后需验证对应服务正常运行：

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