[全量] 初始化项目代码、配置、文档及Agent协同harness

2026-04-02 11:36:05 +08:00
parent 0553309cdf
commit 87e571d9ec
1133 changed files with 221948 additions and 0 deletions
--- a/.harness/CLAUDE.md
+++ b/.harness/CLAUDE.md
@@ -0,0 +1,33 @@
+# 钢研院智能问答平台（gangyan）
+
+面向冶金行业的 LLM 智能问答系统，提供智能对话、文档撰写、知识库管理、文献检索、翻译等功能。
+
+## 项目结构
+
+| 模块 | 路径 | 技术栈 | 端口 |
+|------|------|--------|------|
+| 前端 | `chat_web_front/` | Vue 3 + TypeScript + Element Plus + Vite | :3000 (上下文 `/metalinfo`) |
+| Java 后端 | `chat_web_backend/` | Spring Boot 2.3.7 + MyBatis-Plus + JDK 11 | :8099 (上下文 `/chat_web_backend`) |
+| Python RAG | `langchain-chat/` | Python 3.11 + FastAPI + LangChain + Milvus | :7861 |
+
+## 基础设施
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| MySQL 8.4.4 | 33306 | 数据库 `chat_gpt_yj`，root/1234567890 |
+| Redis | 6379 | 无密码，database 0 |
+| Milvus 2.6.4 | 19530 | 向量数据库 |
+| MinIO | 9002(console)/9003(API) | 对象存储（Milvus 依赖） |
+| Embedding API | 10.102.24.75:3000 | bge-m3 向量模型 + LLM 网关 |
+
+## 项目位置
+
+- 服务器路径：`/opt/download/oss_files/gangyan-deploy/gangyan`
+- Git 仓库：`http://123.57.146.97:3000/liuguancen/gangyan.git`
+- 分支：`main`
+
+## 详细文档索引
+
+- [系统架构与运行配置](architecture.md) — 服务拓扑、各模块详细配置、包结构、API 分组
+- [开发构建指南](development-guide.md) — 启动顺序、构建命令、环境要求、日志与健康检查
+- [Agent 协同规则](agent-coordination.md) — 多 Agent 并行开发的分支、接口变更、提交规范
--- a/.harness/agent-coordination.md
+++ b/.harness/agent-coordination.md
@@ -0,0 +1,81 @@
+# 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/` 与实际代码不一致。**
--- a/.harness/architecture.md
+++ b/.harness/architecture.md
@@ -0,0 +1,206 @@
+# 系统架构与运行配置
+
+## 服务拓扑
+
+```
+Vue前端(:3000/metalinfo)
+    │  proxy /chat_web_backend
+    ▼
+Java后端(:8099/chat_web_backend)  ──→  Python RAG(:7861)
+    │                                      │
+    ├── MySQL(:33306/chat_gpt_yj)          ├── Milvus(:19530)
+    ├── Redis(:6379)                       ├── Embedding API(10.102.24.75:3000)
+    └── 科协SSO(kxsso.cast.org.cn)        └── LLM API(10.102.24.75:3000 + DeepSeek/阿里云)
+```
+
+---
+
+## Java 后端 `chat_web_backend/`
+
+### 运行配置（Profile: yj）
+
+| 配置项 | 值 |
+|--------|-----|
+| 主类 | `com.inspur.llm.ChatApplication` |
+| 端口 | 8099，上下文 `/chat_web_backend` |
+| 数据库 | `jdbc:mysql://127.0.0.1:33306/chat_gpt_yj`，root / 1234567890 |
+| 连接池 | Druid，初始5，最小10，最大20 |
+| Redis | `127.0.0.1:6379`，无密码，database 0 |
+| LangChain | `http://localhost:7861` |
+| 默认 LLM | deepseek-v3 |
+| 前端地址 | `http://localhost:3000` |
+| SSO | 科协 `https://kxsso.cast.org.cn/` |
+| 文件上传限制 | 50MB |
+
+### 包结构 `com.inspur.llm.chat`
+
+- **`base/`** — 框架层
+  - `config/` `security/` `filter/` `interceptor/` `aspect/` — Spring 配置与安全
+  - `util/` `constant/` `enums/` `exception/` — 工具与异常
+  - `mybatis/` — MyBatis-Plus 配置
+  - `xss/` — XSS 防护过滤器
+
+- **`gpt/`** — 业务层
+  - `controller/`
+    - `app/` — 前端公开接口：ChatController、LoginController、UserController
+    - `gpt/` — 核心业务（15个）：ChatController、ChatMessageController、FileController、KnowledgeBaseController、AgentController、AssistantController、MetallurgyChatController、OutlinesController、SmartChatController、ConfigController、CommonController、FileNoteController、FileTranslateController、AssistantTypeController、UserController
+    - `writterassitant/` — 文档撰写：DocController、WriterAssistantController
+    - `personal/` — 个人知识库：ChatPersonalController
+    - `sys/` — 系统管理：SysLogController、SysUserController
+  - `service/` — 业务服务接口（IChatService、IGptService、IDocService、IKnowledgeBaseConfigService、IUploadFileService、IOutlinesService、TranslateFileService 等）
+  - `mapper/` — MyBatis 数据访问
+  - `pojo/` — entity / dto / vo / command
+
+### 配置文件
+
+| 文件 | 用途 |
+|------|------|
+| `application.yml` | 公共配置（mybatis-plus、xss、tomcat） |
+| `application-yj.yml` | **当前在用**：本机 MySQL/Redis/LangChain |
+| `application-dev.yml` | 开发环境（历史） |
+| `application-test.yml` | 测试环境 |
+| `application-prod.yml` | 生产环境（ENC 加密） |
+
+---
+
+## Python RAG `langchain-chat/`
+
+### 模型配置（configs/model_config.py）
+
+| 配置项 | 值 |
+|--------|-----|
+| Embedding | `bge-m3-api` → `http://10.102.24.75:3000/v1` |
+| 默认 LLM | deepseek-v3 |
+| LLM 列表 | deepseek-v3、deepseek-r1、deepseek-chat、qwen-max、Qwen2-72B-Instruct |
+| LLM 设备 | cuda |
+| Embedding 设备 | cpu |
+| 历史长度 | 20 |
+| 温度 | 0.7 |
+
+**LLM API 来源：**
+- 内网网关：`http://10.102.24.75:3000/v1` — deepseek-v3、deepseek-r1、Qwen2-72B-Instruct、bge-m3
+- 阿里云：`https://dashscope.aliyuncs.com/compatible-mode/v1` — qwen-max
+- DeepSeek 官方：`https://api.deepseek.com/v1` — deepseek-chat、deepseek-reasoner
+
+### 知识库配置（configs/kb_config.py）
+
+| 配置项 | 值 |
+|--------|-----|
+| 向量库类型 | Milvus |
+| Milvus 地址 | `127.0.0.1:19530` |
+| 默认知识库 | `t_policy_total_bge_new_v2` |
+| MySQL | `127.0.0.1:33306/chat_gpt_yj`，root/1234567890 |
+| 文本切分 | ChineseRecursiveTextSplitter，chunk_size=250，overlap=50 |
+| 向量检索 Top K | 5 |
+| 搜索引擎 | duckduckgo |
+| PDF 转换服务 | `http://127.0.0.1:6006/convert/` |
+
+**知识库分类：**
+
+| 知识库 | Collection 名 | 说明 |
+|--------|---------------|------|
+| 政策库 | t_policy_total_bge_new_v2 | 默认主库 |
+| 报告库 | gydemo_report_v2 | 冶金行业报告 |
+| 期刊论文库 | t_journal_article_bge_v1 | 学术期刊 |
+| 冶金新闻库 | yj_news_bge_v1_recover | 2024年及之前 |
+| 冶金中文期刊库 | yj_ch_journal_bge_v1_recover | - |
+| 冶金外文期刊库 | yj_for_journal_bge_v1_recover | - |
+| 冶金OA期刊库 | yj_oa_journal_bge_v2_recover | - |
+| 冶金政策库 | yj_policys_bge_v1_recover | - |
+| 钢铁行业动态库 | steel_kb_token_chunk | - |
+
+> 注意：当前所有知识库常量都被统一指向 `DEFAULT_KNOWLEDGE_BASE = t_policy_total_bge_new_v2`，注释中保留了原始 collection 名。
+
+### 服务配置（configs/server_config.py）
+
+| 服务 | Host | Port |
+|------|------|------|
+| API Server | 0.0.0.0 | 7861 |
+| WebUI | 0.0.0.0 | 8501 |
+| FastChat OpenAI API | 0.0.0.0 | 20000 |
+| FastChat Controller | 0.0.0.0 | 20101 |
+
+### 源码结构
+
+- `server/api.py` — 主 API 路由
+- `server/llm_api.py` — LLM 调用
+- `server/utils.py` — 工具函数
+- `server/knowledge_base/` — 知识库 CRUD、文件转换、向量化
+- `server/custom/` — 定制功能（章节速览、文章综述、摘要检索、论文翻译）
+- `server/model_workers/` — 各模型 Worker（OpenAI、智谱、百川等）
+- `server/reranker/` — 重排序
+- `configs/` — 所有配置文件
+
+---
+
+## Vue 前端 `chat_web_front/`
+
+### 运行配置（.env）
+
+| 配置项 | 值 |
+|--------|-----|
+| 前端上下文 | `/metalinfo` |
+| 后端代理 | `/chat_web_backend` → `http://localhost:8099` |
+| 端口 | 3000 |
+| 路由模式 | Hash |
+
+### 页面路由
+
+| 路径 | 页面 | 说明 |
+|------|------|------|
+| `/chat` | 智能对话 | 主对话页（默认首页） |
+| `/writing` | 文档撰写 | 文档列表 |
+| `/writing/edit` | 文档编辑 | 大纲→正文撰写 |
+| `/knowledgeBase` | 知识库 | 个人知识库管理 |
+| `/knowledgeBase/fileList` | 文件列表 | 知识库内文件 |
+| `/knowledgeBase/fileDetail` | 文件详情 | 文件阅读/对话 |
+| `/applications` | 应用广场 | 工具集合 |
+| `/translate` | 翻译 | 文档翻译 |
+| `/login` | 登录 | 科协SSO/本地登录 |
+
+### 前端 API 分组（src/api/index.ts）
+
+| 分组 | 核心接口 | 对应后端 |
+|------|----------|----------|
+| 对话 | fetchChatAPI、fetchConversationId、fetchChatAPIProcess（流式）、LiteratureChat | app/ChatController + gpt/ChatController |
+| 文档撰写 | createOutLine、sessionFlow、expandKnow、docSave、getDoc | WriterAssistantController + DocController + OutlinesController |
+| 知识库 | getKnowledgeBaseList、uploadFile、getFileContent、streamDocumentOverview、streamChapterOverview | KnowledgeBaseController + FileController |
+| 翻译 | fileTranslate、translateString、checkTextLanguage | FileTranslateController |
+| 智慧场景 | fetchSmartPrompt、searchPrompt | SmartChatController + AssistantController |
+| 用户 | fetchSession、updateUser、fetchCASLogin | UserController + LoginController |
+
+### 源码结构
+
+- `src/views/` — 页面组件（chat、writing、reading、applications、translate、login）
+- `src/components/` — 通用组件（Message、AIbox、AIcreate、AIrewrite、KnowledgeBox、WritingGuide、Literatures、Translate 等）
+- `src/api/index.ts` — 所有 API 请求
+- `src/store/index.ts` — Pinia 状态管理
+- `src/router/` — 路由与权限守卫
+- `src/utils/` — 工具函数（request 封装、copy）
+- `src/locales/` — 多语言（中/英/韩/俄/越/繁）
+- `src/config/properties.ts` — 前端配置
+
+---
+
+## Docker 基础设施
+
+### MySQL
+
+- Compose 文件：`mysql/docker-compose.yml`
+- 容器：`mysql-server`，镜像 `mysql:8.4.4`
+- 端口：33306 → 3306
+- 数据卷：`mysql/mysql-8.4.4/mysql_bind`
+- 初始库：`chat_LLM`（实际使用 `chat_gpt_yj`）
+
+### Milvus
+
+- Compose 文件：`milvus/docker-compose.yml`
+- 容器：`milvus-standalone`，镜像 `milvusdb/milvus:v2.6.4`
+- 端口：19530(gRPC)、9091(健康检查)
+- 依赖：etcd(v3.5.18) + MinIO(2024-12-18)
+- 数据卷：`milvus/volumes/`
+
+### Redis
+
+- 非 Docker 部署（宿主机直接运行或 `docker start redis-server`）
+- 端口：6379，无密码
--- a/.harness/development-guide.md
+++ b/.harness/development-guide.md
@@ -0,0 +1,156 @@
+# 开发构建指南
+
+## 环境要求
+
+| 组件 | 版本 | 位置 |
+|------|------|------|
+| JDK | 11 | `/usr/lib/jvm/java-11-openjdk-amd64` |
+| Maven | - | 系统安装 |
+| Node.js | - | 系统安装 |
+| Python | 3.11 | Conda env `langchain-chat` |
+| Conda | - | `/opt/software/miniconda3` |
+| Docker | - | 系统安装 |
+
+## 启动顺序
+
+### 1. Docker 数据层
+
+```bash
+cd /opt/download/oss_files/gangyan-deploy/gangyan
+
+# MySQL
+cd mysql/mysql-8.4.4 && docker compose up -d && cd ../..
+
+# Redis
+docker start redis-server 2>/dev/null || docker run -d --name redis-server -p 6379:6379 redis:7-alpine
+
+# Milvus（含 etcd + MinIO）
+cd milvus && docker compose up -d && cd ..
+```
+
+验证：`docker ps` 确认 mysql-server、redis-server、milvus-standalone、milvus-etcd、milvus-minio 均 running。
+
+### 2. Java 后端
+
+```bash
+# 使用现有 jar 启动
+sudo bash /opt/download/oss_files/gangyan-deploy/gangyan/backend/start_local.sh
+
+# 或手动启动
+export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
+export PATH=$JAVA_HOME/bin:$PATH
+cd /opt/download/oss_files/gangyan-deploy/gangyan/backend
+nohup java -Xms512m -Xmx2048m -Dspring.profiles.active=yj -jar chat_web_yj.jar > nohup.out 2>&1 &
+```
+
+### 3. Python RAG
+
+```bash
+source /opt/software/miniconda3/etc/profile.d/conda.sh
+conda activate langchain-chat
+cd /opt/download/oss_files/gangyan-deploy/gangyan/langchain-chat
+export PYTHONPATH="$(pwd):$PYTHONPATH"
+nohup python startup.py --all-api > langchain.log 2>&1 &
+
+# PDF 转换微服务（可选）
+bash /opt/download/oss_files/gangyan-deploy/gangyan/scripts/pdf-convert-service.sh
+```
+
+### 4. 前端
+
+```bash
+cd /opt/download/oss_files/gangyan-deploy/gangyan/chat_web_front
+npm run dev
+# 或后台运行
+nohup npm run dev > nohup.out 2>&1 &
+```
+
+### 一键启动
+
+```bash
+bash /opt/download/oss_files/gangyan-deploy/gangyan/start_all.sh
+```
+
+## 构建
+
+### Java 后端重新打包
+
+修改源码后必须重新打 jar：
+
+```bash
+cd /opt/download/oss_files/gangyan-deploy/gangyan/chat_web_backend
+mvn -DskipTests package
+# 输出：target/chat_web_backend.jar
+# 复制到 backend/ 目录
+cp target/chat_web_backend.jar ../backend/chat_web_yj.jar
+```
+
+注意：`lib/` 下有两个 system scope jar（aspose-words、app-sign-sdk），打包时需确保 `includeSystemScope=true`（pom.xml 已配置）。
+
+### 前端生产构建
+
+```bash
+cd /opt/download/oss_files/gangyan-deploy/gangyan/chat_web_front
+npm run build
+# 输出到 dist/ 目录
+```
+
+## 健康检查
+
+```bash
+curl -s -o /dev/null -w "Java %{http_code}\n"      http://127.0.0.1:8099/chat_web_backend/app/user
+curl -s -o /dev/null -w "Langchain %{http_code}\n"  http://127.0.0.1:7861/docs
+curl -s -o /dev/null -w "Frontend %{http_code}\n"   http://127.0.0.1:3000/
+```
+
+## 日志文件
+
+| 服务 | 日志位置 |
+|------|----------|
+| Java 后端 | `backend/nohup.out`、`logs/spring.log`、`logs/backend.log` |
+| Python RAG | `langchain-chat/langchain.log`、`logs/langchain-chat.log` |
+| 前端 | `chat_web_front/nohup.out` |
+| PDF 转换 | `logs/pdf-convert-service.log` |
+
+## 运维脚本
+
+`scripts/` 目录下提供各模块独立重启脚本：
+
+| 脚本 | 用途 |
+|------|------|
+| `backend-restart.sh` | 重启 Java 后端 |
+| `langchain-restart.sh` | 重启 Python RAG |
+| `frontend-restart.sh` | 重启前端 |
+| `mysql-restart.sh` | 重启 MySQL |
+| `redis-restart.sh` | 重启 Redis |
+| `milvus-restart.sh` | 重启 Milvus |
+| `common-restart.sh` | 通用重启 |
+| `log-trim-daemon.sh` | 日志清理 |
+| `pdf-convert-service.sh` | PDF 转换服务 |
+| `backend-pack.sh` | 后端打包 |
+
+## 配置文件位置速查
+
+```
+chat_web_backend/src/main/resources/
+├── application.yml              # 公共配置
+├── application-yj.yml           # 当前在用（本机数据库）
+├── application-dev.yml          # 开发环境（历史）
+├── application-test.yml         # 测试环境
+├── application-prod.yml         # 生产环境（ENC加密）
+├── mapper/                      # MyBatis XML
+│   ├── sys/                     # 系统表映射
+│   └── gpt/                     # 业务表映射
+└── ueditorConfig/               # UEditor 配置
+
+langchain-chat/configs/
+├── model_config.py              # 模型、API Key、模型路径
+├── server_config.py             # 服务端口、Worker 配置
+└── kb_config.py                 # 知识库、向量库、MySQL、搜索引擎
+
+chat_web_front/
+├── .env                         # 环境变量（端口、代理、上下文）
+├── vite.config.ts               # Vite 配置（代理、插件）
+├── tsconfig.json                # TypeScript 配置
+└── tailwind.config.js           # Tailwind CSS
+```