# 智造申报 Agent

面向智能工厂申报的 Harness Agent 应用。用户创建企业项目并上传可用材料；Agent 完成材料检验与建设规划确认后，自主调用知识库、Skill 和受控工作区生成带 Word 原生批注的 DOCX 审阅稿。

## 技术栈

- Spring Boot 3.5.16、JDK 21、AgentScope Java 2.0.1、AG-UI
- Vue 3.5、Vite、Element Plus、Vue Element Plus X
- PostgreSQL 17、Flyway

## 本地启动

```bash
docker build -t smart-factory-agent-runtime:0.1.0 -f sandbox/Dockerfile sandbox
docker compose up -d postgres
mvn -q -f server/pom.xml spring-boot:run
npm --prefix web-ui install
npm --prefix web-ui run dev
```

本地开发服务器默认使用 Vite 配置的端口。容器化部署固定从 <http://127.0.0.1:5173> 访问。

模型连接只能在“模型配置”页面新增并持久化到 PostgreSQL；API Key 会使用 `APP_MASTER_KEY`
环境变量提供的主密钥加密后保存。`dashscope_key.txt` 仅供百炼知识库使用，不参与模型配置。

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

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

## Docker Compose 部署

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

1. 在开发机构建并导出 Agent Runtime 镜像：

   ```bash
   docker build -t smart-factory-agent-runtime:0.1.0 -f sandbox/Dockerfile sandbox
   docker save -o smart-factory-agent-runtime-0.1.0.tar smart-factory-agent-runtime:0.1.0
   ```

   将 Tar 文件传到服务器后导入。Compose 设置了 `pull_policy: never`，若镜像不存在会直接报错，
   不会在服务器自动拉取或构建：

   ```bash
   docker load -i smart-factory-agent-runtime-0.1.0.tar
   docker image inspect smart-factory-agent-runtime:0.1.0
   ```

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

   ```bash
   cp .env.example .env
   ```

3. 确认 `MANUAGENT_DATA_ROOT` 是 Docker 宿主机上的绝对路径。这个路径会以完全相同的路径挂载到
   后端容器，供动态 Agent Runtime 继续挂载项目材料、工作目录和产物。Linux 默认值为
   `/srv/manuagent/data`。

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

   ```bash
   docker compose -f docker-compose.yml up -d --build
   docker compose -f docker-compose.yml ps
   ```

5. 打开 <http://127.0.0.1:5173>，使用 `.env` 中的 `APP_ADMIN_USERNAME` 和
   `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，可仅在本机
验证时临时执行 `$env:FRONTEND_PORT = '15173'`；Linux 服务器部署应保留默认的 5173。

PostgreSQL 数据保存在 `postgres-data` 命名卷中；项目材料、Agent 工作区、快照和生成文件保存在
`MANUAGENT_DATA_ROOT`。`docker compose down` 不会删除它们，只有显式增加 `--volumes` 才会删除
PostgreSQL 卷。后端挂载 Docker Socket 等价于授予其管理宿主机容器的高权限，应只在受信任的
Docker 主机上运行，并限制 5173 端口的网络访问范围。通过 HTTPS 反向代理部署时，请将
`SESSION_COOKIE_SECURE` 设为 `true`。

## 验证

```bash
mvn -q -f server/pom.xml test
npm --prefix web-ui run test
npm --prefix web-ui run build
docker compose -f docker-compose.yml config --quiet
```

产品、数据库与验收设计见 [docs](docs/)。内置 Skill 与资源由 Flyway 种子迁移写入数据库，无需额外导入文件。