# aisf-pipeline

**Repository Path**: eric-leo/aisf-pipeline

## Basic Information

- **Project Name**: aisf-pipeline
- **Description**: pipeline 
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 持续集成智能体工作台（aisf-pipeline）

一个「自然语言驱动 + 智能化测试 + 编码智能体闭环修复」的持续集成智能体演示项目。

后端基于 `spring-agent-foundation` 仓库 `saf-pipeline` 模块（`feat_aisf` 分支）重构，
前端采用 `codeteams` 仓库 `pmCiOpenAgent()` 视图的三栏智能体工作台风格（Vite + React）。

> 所有阶段均为前端 / 后端的**模拟执行**（按 `pipeline-config.json` 中配置的 `delayMs` 推进），
> 不依赖真实的 git / Maven / SonarQube / K8s 资源，但接口语义、循环修复、缺陷报告、可下载
> artifact 与生产化系统完全一致，可作为后续接入真实工具链的 UI 基线。

## 1. 核心演示效果

1. **自然语言生成流水线**：在中间对话框输入「为电商平台构建部署与测试流水线」，
   智能体自动生成含 **6 个固定阶段** 的流水线：
   `代码检出 → 静态扫描 → 编译构建 → 部署 → 智能测试方案生成 → 智能化测试`
2. **自然语言触发执行**：在同一个对话框输入「启动」，智能体驱动流水线按阶段模拟流转。
3. **智能化测试结论 + 编码智能体闭环**：测试失败时输出缺陷结论，
   智能测试方案被重新生成（含脚本差异、缺陷库对照），
   回到「智能化测试」再次执行，循环直至通过或达到最大失败阈值。
4. **自然语言重置**：输入「重置」即可重置当前流水线，回到初始态。
5. **可下载 artifact**：测试脚本（`AutoTest.java`）、静态扫描报告（Markdown）、
   智能化测试报告（Markdown）通过 Blob URL 在前端下载。

## 2. 架构

```
                                                内置 H2（./data/aisf-pipeline.mv.db）
                                                          │
浏览器 ──http──▶ 前端 Vite (8080) ──/api/v1/...──▶ saf-pipeline-provider (9011) ──┐
                    │                                                              │
                    └─ codeteams pmCiOpenAgent 三栏风格                              ▼
                                                              流水线 + 循环 + 缺陷池 + 修复方案
                                                              （pipeline-config.json 全外置）
```

| 模块 | 端口 | 角色 |
|------|------|------|
| `saf-pipeline-provider` | **9011** | 业务服务：流水线模拟引擎 + 循环修复 + 内置 H2 持久化 + REST + OpenAPI 3 |
| 前端 Vite (React) | **8080** | `npm run dev` / `npm run build` + `/api/v1` 反向代理 → 9011 |

## 3. 技术栈

| 层 | 技术 |
|----|------|
| 后端 | Java 21 + Spring Boot 4.1.0 + Spring Data JPA |
| 数据 | 内置 H2 文件数据库（`./data/aisf-pipeline.mv.db`）+ JPA/Hibernate |
| JSON | Jackson 3.x（`tools.jackson.databind`，Spring Boot 4.1 默认） |
| API 文档 | springdoc-openapi + knife4j（中文 Swagger UI） |
| 持久化字段 | 流水线 / 项目 / 循环 / 阶段 / 测试报告 / 缺陷 / 修复方案 全部 JPA Entity |
| 外置配置 | `pipeline-config.json`（阶段模板、缺陷池、修复方案、演示场景、业务默认值） |
| 前端 | Vite 5 + React 18 + TypeScript（`frontend/src/modules/*`） |
| 通信 | REST + 前端轮询；可选 SSE 流式推送 MCP 创建步骤 |

## 4. 快速启动

### 4.1 一键启动

```bash
./start.sh
```

脚本会先后启动后端 `saf-pipeline-provider`（9011）和前端 Vite 开发服务器（8080）。
启动后访问：

- 前端页面：`http://localhost:8080`
- Knife4j Swagger UI（中文，推荐）：`http://localhost:9011/doc.html`
- 原生 Swagger UI：`http://localhost:9011/swagger-ui.html`
- OpenAPI 3 JSON：`http://localhost:9011/v3/api-docs`
- H2 控制台：`http://localhost:9011/h2-console`（JDBC URL `jdbc:h2:file:./data/aisf-pipeline`）

### 4.2 手动启动（开发者推荐）

#### 4.2.1 环境准备

| 工具 | 版本 | 说明 |
|------|------|------|
| JDK | **21** | 后端 Spring Boot 4.1 必须 JDK 21+ |
| Maven | 3.9+ | 后端构建 |
| Node.js | 20+ | 前端 Vite 5 / React 18 / TypeScript 5 |
| npm | 10+ | 前端依赖管理（也可使用 pnpm / yarn） |

#### 4.2.2 安装 JDK 21（如果还没有）

```bash
sudo mkdir -p /opt/jdk21
curl -fsSL -o /tmp/jdk21.tar.gz \
    https://download.java.net/java/GA/jdk21.0.2/f2283984656d49d69e91c558476027ac/13/GPL/openjdk-21.0.2_linux-x64_bin.tar.gz
sudo tar -xzf /tmp/jdk21.tar.gz -C /opt/jdk21 --strip-components=1
```

#### 4.2.3 启动后端（端口 9011）

```bash
# 进入仓库根目录
cd /workspace

# 第一次或代码改动后：编译打包（首次约 1-2 分钟，后续增量编译 < 30s）
cd backend
JAVA_HOME=/opt/jdk21 mvn -q -DskipTests package

# 启动 provider（默认端口 9011，可被 application.yml 覆盖）
JAVA_HOME=/opt/jdk21 /opt/jdk21/bin/java \
    -jar saf-pipeline/saf-pipeline-provider/target/saf-pipeline-provider-1.0.0.jar

# 验证：
curl http://localhost:9011/api/v1/meta/endpoints
# 浏览器打开 http://localhost:9011/doc.html  看 Knife4j Swagger UI
```

可选：直接用 Maven 跑 Spring Boot（无需先打包）：

```bash
cd /workspace/backend
JAVA_HOME=/opt/jdk21 mvn -pl saf-pipeline/saf-pipeline-provider spring-boot:run
```

可选 JVM 参数（按需）：

```bash
JAVA_OPTS="-Xms512m -Xmx1024m -Dfile.encoding=UTF-8"
# 设置 AIGF_PIPELINE_HOME 以改变 H2 数据库 / pipeline-config.json 的加载路径
export AIGF_PIPELINE_HOME=/path/to/work-dir
```

#### 4.2.4 启动前端（端口 8080）

```bash
cd /workspace/frontend

# 第一次：安装依赖（node_modules 已存在可跳过）
npm install

# 开发模式（默认 vite dev，HMR 热更新，监听 8080）
npm run dev

# 生产构建（生成 dist/）
npm run build

# 预览构建产物（端口 8080）
npm run preview
```

启动成功后浏览器打开 `http://localhost:8080`。
Vite 已配置 `proxy['/api/v1'] → http://localhost:9011`，
前端调用 `/api/v1/...` 全部经反代到后端，无需关心跨域。

### 4.3 启动顺序建议

1. **先启动后端**：等 `Started SafPipelineProviderApplication` 日志出现后再继续。
2. **再启动前端**：`npm run dev` 会在 8080 监听；
   Vite 会向 `http://localhost:9011/api/v1/meta/endpoints` 探测后端存活。
3. **修改后端代码** → 重新 `mvn package` → 重启 jar；
   **修改前端代码** → Vite HMR 自动热更新，无需重启。

## 5. Swagger / Knife4j API 文档访问

后端已集成 **springdoc-openapi + knife4j**，所有 Controller 上的 `@Operation` / `@Tag` 注解
会自动生成 OpenAPI 3 规范。启动后端后可直接访问：

| 路径 | 用途 | 备注 |
|------|------|------|
| `/doc.html` | **Knife4j Swagger UI（中文）** | 推荐，中文界面、支持离线 markdown 下载 |
| `/swagger-ui.html` | 原生 Swagger UI（英文） | springdoc 内置 |
| `/v3/api-docs` | OpenAPI 3 JSON 规范 | 可导入 Postman / Apifox / Insomnia |
| `/v3/api-docs.yaml` | OpenAPI 3 YAML 规范 | 同上 |
| `/api/v1/meta/endpoints` | 接口清单（含 method / path / body / description） | 脚本化探活首选 |

> 在线预览场景下，把 `localhost:9011` 替换为对应的 monkeycode 映射域名即可访问，
> 例如 `https://9011-xxx.monkeycode-ai.online/doc.html`。

Postman 导入步骤：

1. 打开 Postman → `Import` → `Link`
2. 粘贴 `http://localhost:9011/v3/api-docs`
3. 导入完成后即可在 Postman 中直接调用所有 REST 接口。

## 6. 演示步骤

1. 浏览器打开 `http://localhost:8080`，进入「持续集成智能体」三栏工作台。
2. 左栏选择 / 新建项目（默认项目由后端 `DefaultProjectBootstrap` 自动写入）。
3. 在中间对话框输入需求（含「生成 / 创建 / 新建」关键字），点击「发送」：
   - `generate` → 选定项目 + 自然语言需求 → `POST /api/v1/pipeline/generate`
   - `start` → 触发当前流水线执行（按当前演示场景）
   - `reset` → 重置当前流水线
   - 其他 → 查询当前状态
4. 右侧面板：
   - **DAG 可视化**：6 节点 SVG，节点含阶段名称 + 时长；状态实时联动
   - **循环列表**：每轮循环的阶段轨迹、耗时、缺陷 / 修复动作
   - **会话气泡**：智能体逐步输出每个阶段的结果、缺陷报告、可下载 artifact
5. 智能体响应同样带服务端绝对时间戳，方便审计与回溯。
6. 重启 provider 后数据自动从 `./data/aisf-pipeline.mv.db` 恢复（H2 文件持久化）。

## 7. REST API（provider 9011）

所有接口可通过 `GET /api/v1/meta/endpoints` 自描述查询，也可通过
Knife4j / Swagger UI 在线调试。

### 7.1 项目管理

| 方法 | 路径 | 入参 | 说明 |
|------|------|------|------|
| GET | `/api/v1/projects` | — | 列出全部项目（按创建时间倒序） |
| GET | `/api/v1/projects/{id}` | — | 按 ID 查询项目 |
| POST | `/api/v1/projects` | `{name, description, appType, createdBy}` | 新建项目（name 必填且全局唯一） |
| DELETE | `/api/v1/projects/{id}` | — | 删除项目（默认项目保留） |

### 7.2 流水线

| 方法 | 路径 | 入参 | 说明 |
|------|------|------|------|
| POST | `/api/v1/pipeline/generate` | `{projectName, projectId?, prompt}` | 自然语言生成流水线 |
| GET | `/api/v1/pipeline` | `?project=` 可选 | 流水线列表（可按项目过滤） |
| GET | `/api/v1/pipeline/{id}` | — | 查询实时状态与循环轨迹 |
| POST | `/api/v1/pipeline/{id}/execute` | `{scenario}` | 触发执行（场景见 `/api/v1/pipeline/meta/scenarios`） |
| POST | `/api/v1/pipeline/{id}/reset` | — | 重置（清空循环与步骤种子） |
| GET | `/api/v1/pipeline/{id}/creation-steps` | — | 轮询 MCP 步骤快照 |
| GET | `/api/v1/pipeline/{id}/creation-steps/stream` | — | SSE 流：`event:init/step/done` |

### 7.3 元信息 / 调试

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/pipeline/meta/scenarios` | 演示场景列表（`PASS_NOW/FAIL_ONCE/FAIL_TWICE/THREE_FAIL`） |
| GET | `/api/v1/meta/endpoints` | 当前后端暴露的所有 REST 接口清单（自描述） |
| GET | `/v3/api-docs` | OpenAPI 3 JSON 规范 |
| GET | `/doc.html` | Knife4j Swagger UI（中文） |
| GET | `/swagger-ui.html` | 原生 Swagger UI |
| GET | `/h2-console` | H2 Web 控制台（JDBC URL `jdbc:h2:file:./data/aisf-pipeline`） |

### 7.4 示例

```bash
# 列出所有项目
curl http://localhost:9011/api/v1/projects

# 新建项目
curl -X POST -H "Content-Type: application/json" \
     -d '{"name":"订单系统","description":"金融业务","appType":"finance","createdBy":"alice"}' \
     http://localhost:9011/api/v1/projects

# 生成流水线（MCP 步骤异步执行）
curl -X POST -H "Content-Type: application/json" \
     -d '{"projectName":"演示项目","prompt":"请为电商平台生成部署与全面测试流水线"}' \
     http://localhost:9011/api/v1/pipeline/generate

# 触发执行
curl -X POST -H "Content-Type: application/json" \
     -d '{"scenario":"FAIL_ONCE"}' \
     http://localhost:9011/api/v1/pipeline/{id}/execute

# 列出后端所有接口（自描述）
curl http://localhost:9011/api/v1/meta/endpoints
```

演示场景：

| code | 含义 |
|------|------|
| `PASS_NOW` | 顺利通过（0 次失败） |
| `FAIL_ONCE` | 失败一次后修复（1 次失败，下一轮通过） |
| `FAIL_TWICE` | 失败两次后修复（2 次失败，下一轮通过） |
| `THREE_FAIL` | 三次失败（最终失败） |

前端别名 `HAPPY / ONE_FAIL / TWO_FAIL / THREE_FAIL` 由 provider 自动映射到上述枚举。

## 8. 外置配置（pipeline-config.json）

所有可变属性从 `saf-pipeline-provider/src/main/resources/pipeline-config.json` 读取，
**修改后重启 provider 即生效**（无需改 Java 代码）。

支持自定义：

- 阶段定义（6 个固定阶段 `CHECKOUT/SCAN/BUILD/DEPLOY/TEST_PLAN/AI_TEST`）：名称 / 编码 / 描述 / 耗时 / 详情模板
- 详情变量 Base/Step 后缀规则（`XBase` = `X + loopNo`，`XStep` = `X × loopNo`，累加）
- 演示环境列表（按 loopNo 顺序取）
- 测试用例总数、测试结论模板（passed / failed）
- 缺陷池（id/type/severity/description/file/line）
- 修复方案映射（type → 方案文本）

完整字段说明见 `docs/pipeline-config.md`。

## 9. 目录结构

```
.
├── backend/                                后端实现（Java 21 + SB 4.1 + JPA）
│   ├── pom.xml                             父 POM（com.platform.saf:spring-agent-foundation）
│   └── saf-pipeline/
│       ├── pom.xml
│       └── saf-pipeline-provider/          业务服务（9011）
│           ├── src/main/java/...
│           │   ├── entity/                 JPA 实体（Project / Pipeline / LoopRun / StageRun / TestReport / Defect / FixAction）
│           │   ├── repository/             Spring Data JPA Repository
│           │   ├── service/                PipelineService + DefaultProjectBootstrap
│           │   ├── controller/             PipelineController / ProjectController / ApiDocsController / SessionController
│           │   ├── config/                 OpenApiConfig（springdoc + knife4j）
│           │   └── dto/                    GeneratePipelineRequest / CreateProjectRequest
│           └── src/main/resources/
│               ├── application.yml         H2 数据源 + JPA 配置 + springdoc + knife4j
│               └── pipeline-config.json    外置配置
├── frontend/                               前端实现（Vite 5 + React 18 + TS）
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts                      端口 8080 + /api/v1 反代 → 9011 + allowedHosts
│   ├── src/
│   │   ├── main.tsx                        React 入口
│   │   ├── App.tsx                         路由壳
│   │   ├── routes.tsx
│   │   └── modules/
│   │       ├── sessions/                   会话页面 + 消息流 + 三栏工作台
│   │       ├── pipeline/                   流水线 hook / API / DAG 视图 / 详情
│   │       └── agents/                     智能体侧栏
│   └── dist/                               生产构建产物（npm run build 生成）
├── backend-legacy/                         旧版实现（Java 17 + SB 3.4 + @Tool，参考）
├── docs/                                   文档
│   ├── pipeline-config.md                  pipeline-config.json 字段说明
│   ├── mcp-usage-manual.md                 V0.0.1 MCP 使用手册（历史参考）
│   ├── opencode-agent-definition.md        opencode 智能体定义
│   └── java-mcp-implementation.md          Java MCP 集成建议
├── .monkeycode/
│   ├── MEMORY.md                           项目知识与行为约定
│   └── specs/2026-08-16-ai-pipeline-demo/  需求 / 设计 / 任务列表
├── start.sh                                一键启动脚本
└── README.md                               本文件
```

## 10. 常见问题

| 问题 | 解决方案 |
|------|---------|
| `mvn package` 报 Java 版本不兼容 | 确认 `JAVA_HOME=/opt/jdk21` 且 `java -version` 输出 21 |
| `tools.jackson.databind` 找不到 | Spring Boot 4.1 默认 Jackson 3.x 新包名，不要再用 `com.fasterxml.jackson` |
| 前端 `npm run dev` 后访问 8080 报 404 | 检查 Vite 是否启动成功（`Local: http://localhost:8080/`），确认 `vite.config.ts` 中 `host: '0.0.0.0'` |
| 前端 `/api/v1` 调用 404 | 检查后端是否在 9011 监听：`curl http://localhost:9011/api/v1/meta/endpoints`；Vite 启动时会打印代理配置 |
| Knife4j `/doc.html` 404 | 确认 `application.yml` 中 `knife4j.enable: true` 且后端正常启动；老版本需清理 `target/classes` 后重新打包 |
| 在线预览 8080 端口无法访问 | `vite.config.ts` 已配 `allowedHosts: ['.monkeycode-ai.online']`；如映射其它域名请同步追加 |
| 后端 `ObjectMapper` 找不到 | Spring Boot 4.1 已自动配置，注入 `tools.jackson.databind.ObjectMapper` |
| H2 数据库文件锁冲突 | 确认 provider 进程只有一个；删除 `./data/aisf-pipeline.mv.db.lock` 后重启 |

## 11. 许可

本项目为演示用途，按 MIT 协议开源。基准仓库：

- 后端：[spring-agent-foundation](https://gitee.com/eric-leo/spring-agent-foundation) 的 `saf-pipeline` 模块（feat_aisf 分支）
- 前端：[codeteams](https://gitee.com/jitangdou/codeteams) 的 `pmCiOpenAgent()` 视图