# 智造申报 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 种子迁移写入数据库，无需额外导入文件。