153 lines
8.3 KiB
Markdown
153 lines
8.3 KiB
Markdown
# 智造申报 Agent
|
||
|
||
面向智能工厂申报的 Harness Agent 应用。用户创建企业项目并上传可用材料；Agent 完成材料检验与建设规划确认后，自主调用知识库、Skill 和受控工作区生成带 Word 原生批注的 DOCX 审阅稿。
|
||
|
||
## 技术栈
|
||
|
||
- Spring Boot 4.1.1、JDK 25、AgentScope Java 2.0.1、AG-UI
|
||
- MyBatis-Flex 1.11.8（Boot 4 starter）、业务与 HTTP 使用 Jackson 3；AgentScope 内部保留 Jackson 2
|
||
- Vue 3.5、Vite、Element Plus、Vue Element Plus X
|
||
- PostgreSQL 17、Flyway
|
||
|
||
## 本地启动
|
||
|
||
需要 JDK 25、Maven、Node.js 22 和 Docker。先设置 `JAVA_HOME` 指向 JDK 25；IDEA 从
|
||
`server/pom.xml` 导入 Maven reactor，项目 SDK 与 Maven runner 均选 JDK 25，运行
|
||
`manuagent-web` 的 `ManuAgentApplication`，工作目录设为仓库根目录。
|
||
IDEA 运行配置同时设置 `APP_DATA_ROOT` 为既有数据目录的绝对路径，以及
|
||
`APP_DASHSCOPE_KEY_FILE` 为知识库密钥文件的绝对路径，与下面的命令行启动配置保持一致。
|
||
|
||
后端通过 `SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD`
|
||
连接可用的 PostgreSQL 17。根 Compose 的数据库端口只供容器内部使用；宿主机开发需使用已发布
|
||
端口的本地数据库，或在本地 Compose override 中增加 PostgreSQL 端口映射。
|
||
|
||
```bash
|
||
docker build -t agent-sandbox:0.1 -f sandbox/Dockerfile sandbox
|
||
mvn -f server/pom.xml clean package
|
||
export APP_DATA_ROOT="$PWD/data"
|
||
export APP_DASHSCOPE_KEY_FILE="$PWD/dashscope_key.txt"
|
||
java -jar server/manuagent-web/target/manuagent-web.jar
|
||
# 在另一个终端启动前端；依赖只从 workspace 根目录安装。
|
||
npm --prefix web-ui ci
|
||
npm --prefix web-ui run dev
|
||
```
|
||
|
||
本地开发入口为 <http://127.0.0.1:15173>，代理后端 8080。唯一可执行产物是
|
||
`server/manuagent-web/target/manuagent-web.jar`。上述命令从仓库根目录执行，将 `APP_DATA_ROOT` 设为
|
||
根目录下 `data` 的绝对路径；已有数据时改为对应绝对路径，避免移动启动目录后找不到历史文件。
|
||
容器化部署固定从 <http://127.0.0.1:5173> 访问。
|
||
|
||
Agent 会话状态保存在 `APP_DATA_ROOT/agent-state`，与项目文件和沙箱快照一起持久化。
|
||
启动时，会为数据目录内的已有项目从当前运行用户的 `~/.agentscope/state`（或 JVM `agentscope.state.home`
|
||
指定目录）分别复制会话与沙箱状态，补齐此前只迁移会话的项目；保留旧目录，不覆盖已有新状态。
|
||
跨机器或从旧容器升级时，须先将旧状态目录复制到新环境的对应位置，并保留快照原有绝对路径；
|
||
仅保留项目文件不能恢复完整会话。旧进程停止后再迁移，避免继续写入旧位置。
|
||
|
||
沙箱镜像统一为 `agent-sandbox:0.1`。升级前停止旧后端并确认旧沙箱容器已退出；历史会话恢复时
|
||
会将旧 `smart-factory-agent-runtime` 镜像引用迁移到当前 `APP_SANDBOX_IMAGE` 配置，保留会话和快照。
|
||
|
||
`APP_RUN_TIMEOUT` 限制整个 Run（含重连与结果修复）的总时长，默认 60 分钟；结构化结果最多修复
|
||
3 次。`APP_MAX_CONCURRENT_RUNS` 限制单个后端同时运行的任务数，默认 2，新增任务满额时返回 429。
|
||
同项目的模型切换、停止后继续及阶段接续共用原运行名额，等待旧任务释放资源、保存快照后再启动。
|
||
修改沙箱文件后须重建 `sandbox/Dockerfile` 镜像；其中 `docx-example.cjs` 提供与已安装依赖
|
||
一致的表格、原生批注示例及可执行验证。
|
||
|
||
模型连接只能在“模型配置”页面新增并持久化到 PostgreSQL；API Key 会使用 `APP_MASTER_KEY`
|
||
环境变量提供的主密钥加密后保存。`dashscope_key.txt` 仅供百炼知识库使用，不参与模型配置。
|
||
|
||
启动后端前必须设置模型密钥加密主密钥：
|
||
|
||
```powershell
|
||
$env:APP_MASTER_KEY = '<使用独立生成的高强度密钥>'
|
||
```
|
||
|
||
## Docker Compose 部署
|
||
|
||
部署包含 Nginx 前端、Spring Boot 后端、沙箱镜像和 PostgreSQL。沙箱
|
||
不是常驻 API 服务：镜像在开发机预先构建并导入服务器，服务器上的 `sandbox` 服务只校验
|
||
镜像存在，随后以状态码 0 退出；后端再通过 Docker Socket 为每个 Agent Session 动态创建隔离容器。
|
||
|
||
1. 在开发机构建并导出沙箱镜像：
|
||
|
||
```bash
|
||
docker build -t agent-sandbox:0.1 -f sandbox/Dockerfile sandbox
|
||
docker save -o agent-sandbox-0.1.tar agent-sandbox:0.1
|
||
```
|
||
|
||
将 Tar 文件传到服务器后导入。Compose 设置了 `pull_policy: never`，若镜像不存在会直接报错，
|
||
不会在服务器自动拉取或构建：
|
||
|
||
```bash
|
||
docker load -i agent-sandbox-0.1.tar
|
||
docker image inspect agent-sandbox:0.1
|
||
```
|
||
|
||
2. 复制环境变量模板并替换其中的三个必填密码/密钥；生产环境建议使用密码管理系统生成随机值。
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Compose 中的镜像、数据库名称、端口和数据目录均使用静态值；调整时直接修改根目录的 `docker-compose.yml`。
|
||
数据目录固定为 `/srv/manuagent/data`；修改时须同步更新后端的 `APP_DATA_ROOT` 和对应挂载的
|
||
`source`、`target`，保持容器内外使用同一个宿主机绝对路径，供动态沙箱挂载项目材料和产物。
|
||
|
||
4. 构建前后端并启动完整服务：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.yml up -d --build
|
||
docker compose -f docker-compose.yml ps
|
||
```
|
||
|
||
根目录的 `docker-compose.yml` 是唯一部署入口。后端镜像使用 Maven 3.9.13 / Temurin 25.0.2
|
||
构建和 Temurin 25.0.2 JRE 运行；前端镜像从
|
||
`web-ui/apps/web/dist` 复制静态文件。
|
||
|
||
5. 打开 <http://127.0.0.1:5173>，使用 Compose 中的管理员账号 `admin` 和 `.env` 中的
|
||
`APP_ADMIN_PASSWORD` 登录。查看日志或停止服务：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.yml logs -f backend
|
||
docker compose -f docker-compose.yml down
|
||
```
|
||
|
||
端口映射为 `0.0.0.0:5173:80`。若 Windows 的动态端口排除范围占用了 5173，可在本机验证时
|
||
将 Compose 的端口映射临时改为 `0.0.0.0:15173:80`；Linux 服务器部署应保留 5173。
|
||
|
||
PostgreSQL 数据保存在 `postgres-data` 命名卷中；项目材料、Agent 工作区、快照和生成文件保存在
|
||
Compose 配置的数据目录。`docker compose down` 不会删除它们，只有显式增加 `--volumes` 才会删除
|
||
PostgreSQL 卷。后端挂载 Docker Socket 等价于授予其管理宿主机容器的高权限，应只在受信任的
|
||
Docker 主机上运行，并限制 5173 端口的网络访问范围。通过 HTTPS 反向代理部署时，请将
|
||
Compose 中的 `SERVER_SERVLET_SESSION_COOKIE_SECURE` 设为字符串 `"true"`。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
mvn -f server/pom.xml verify
|
||
npm --prefix web-ui test
|
||
npm --prefix web-ui run build
|
||
docker compose -f docker-compose.yml config --quiet
|
||
```
|
||
|
||
以上命令分别验证后端测试/打包、前端测试、四个 workspace 的类型检查及单应用构建、Compose 配置。
|
||
模块依赖边界仍需在代码审查中核对，当前没有自动边界检查命令。
|
||
|
||
## 模块边界
|
||
|
||
| 后端模块 | 前端 workspace | 职责 |
|
||
| --- | --- | --- |
|
||
| `manuagent-common` | `packages/common` | 错误、TypeHandler；前端共享请求、CSRF、基础样式 |
|
||
| `manuagent-admin` | `packages/admin` | 用户服务与用户持久化；登录页面 |
|
||
| `manuagent-agent` | `packages/agent` | 项目、文件、模型、Skill、Agent 执行、规划与产物；业务页面和侧栏 |
|
||
| `manuagent-web` | `apps/web` | HTTP、认证上下文、基础设施装配与启动；单应用壳和路由 |
|
||
|
||
Agent 和 Admin 只依赖 Common，Web 装配三者。仍是一个后端进程、一个数据源和一个事务体系。
|
||
Controller 从登录身份解析用户 UUID，业务服务负责事务及审计字段。`AdminProperties` 和
|
||
`AgentProperties` 继续绑定原有 `app.*` 键，数据库配置和环境变量名保持兼容。
|
||
|
||
历史 Flyway 文件保留在 `server/src/main/resources/db/migration`，由 Web 原样打包一份；
|
||
请勿迁移、重命名或改写这些已共享脚本。Agent 的 Mapper XML 和提示词随普通库 JAR 加载。
|
||
前端只有根目录一份 `package-lock.json`，业务包通过 `@manuagent/*` 的公开 exports 引用。
|
||
|
||
本次改造的证据与验收边界见 [MANU-1 实现与验收](docs/MANU-1-implementation.md)。内置 Skill 与资源由 Flyway 种子迁移写入数据库，无需额外导入文件。
|