智造申报 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 端口映射。

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 仅供百炼知识库使用，不参与模型配置。

启动后端前必须设置模型密钥加密主密钥：

$env:APP_MASTER_KEY = '<使用独立生成的高强度密钥>'

Docker Compose 部署

部署包含 Nginx 前端、Spring Boot 后端、沙箱镜像和 PostgreSQL。沙箱 不是常驻 API 服务：镜像在开发机预先构建并导入服务器，服务器上的 sandbox 服务只校验 镜像存在，随后以状态码 0 退出；后端再通过 Docker Socket 为每个 Agent Session 动态创建隔离容器。

1. 在开发机构建并导出沙箱镜像：

   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，若镜像不存在会直接报错， 不会在服务器自动拉取或构建：

   docker load -i agent-sandbox-0.1.tar
   docker image inspect agent-sandbox:0.1
   

2. 复制环境变量模板并替换其中的三个必填密码/密钥；生产环境建议使用密码管理系统生成随机值。

   cp .env.example .env
   

3. Compose 中的镜像、数据库名称、端口和数据目录均使用静态值；调整时直接修改根目录的 docker-compose.yml。 数据目录固定为 /srv/manuagent/data；修改时须同步更新后端的 APP_DATA_ROOT 和对应挂载的 source、target，保持容器内外使用同一个宿主机绝对路径，供动态沙箱挂载项目材料和产物。

4. 构建前后端并启动完整服务：

   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 登录。查看日志或停止服务：

   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"。

验证

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 实现与验收。内置 Skill 与资源由 Flyway 种子迁移写入数据库，无需额外导入文件。