# smart-data-forge

**Repository Path**: aiagentdemo/smart-data-forge

## Basic Information

- **Project Name**: smart-data-forge
- **Description**: 大模型时代的数据 Mock 平台重写版：**代码链路分析 × Skill 脚本 × 大模型智能造数 × 数据血缘 × 智能清理 × 开放接口
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Data Forge · 智能数据构造平台

> 大模型时代的数据 Mock 平台重写版：**代码链路分析 × Skill 脚本 × 大模型智能造数 × 数据血缘 × 智能清理 × 开放接口**
>
> Python3（FastAPI）+ Vue3 + Element Plus，蓝白科技风，首页为发布会风格的能力介绍。

---

## 一、它解决什么问题

传统数据 mock 平台靠手工维护造数脚本，与业务脱节、难以复用、造完难清理。本平台：

1. **代码分析核心调用链路** — 静态扫描 Java Spring / Python(FastAPI/Flask/Django) / Node.js(Express/Koa) 仓库，自动提取接口、处理函数与下游调用（Service/Mapper）；支持大模型按语义聚类核心业务流，也支持可视化手工补充/编排（接口节点 + Skill 节点）。
2. **Skill 技能包** — 上传 **zip 技能包**自动解析为 Skill（支持一个 zip 内多个技能包、同包多脚本互相 import、资源文件），子进程隔离执行 + 超时控制，带参数表单、脚本文件在线查看/编辑、在线测试、模板 zip 下载。
3. **大模型智能造数** — 依据调用链路上下文与可用 Skill，自动生成造数计划（字段、模式、依赖、可清理实体），按拓扑顺序逐步执行；步骤间支持 `${s1.data.id}` / `${s1.payload.username}` 引用。多供应商可配置（火山 ARK / DeepSeek / OpenAI 及一切 OpenAI 兼容端点），**未配置 Key 时自动降级为规则 + 仿真数据生成模式，全流程照样跑通**。
4. **按业务流查看/修改数据** — 批次 → 步骤 → 入参/返回/实体血缘，支持在线修改 payload/result、单步重放。
5. **智能清理** — Skill 走 `cleanup(ctx, entity)` 精准删除，mock 数据标记回收；支持按计划 / 批次号 / 项目全量 / 单条清理，计划状态联动。
6. **对外开放接口** — Token 鉴权的 OpenAPI，供接口自动化、UI 自动化平台在用例前置阶段造数、后置阶段按批次清理。
7. **完整平台体验** — 发布会风格首页、蓝白科技风 UI、内置「示例电商系统」（混合三语言代码仓库 + 2 个 Skill + 一条下单支付链路），首次启动即可体验。

## 二、快速开始

### 方式 A：前后端分离开发（推荐开发使用）

```bash
# 后端
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # 默认 SQLite，零配置；生产改 MySQL
uvicorn app.main:app --host 0.0.0.0 --port 8096

# 前端（另开终端）
cd frontend
npm install
npm run dev                   # http://localhost:5196 （已配置代理到 8096）
```

或直接 `bash start-dev.sh` 一键并行拉起。

### 方式 B：单端口部署（前端构建后由 FastAPI 托管）

```bash
bash build-and-run.sh         # 构建到 backend/frontend_dist，访问 http://localhost:8096
```

打开页面后会自动生成种子数据：示例项目 `demo-mall`、8 个左右接口、2 个 Skill、1 条已确认业务流、1 个演示 Token。

### 端到端自测（无需联网/MySQL/前端）

```bash
cd backend
pip install -r requirements.txt
python ../tests/e2e_test.py   # 覆盖 分析→Skill→造数→血缘→开放接口→清理 共 30+ 断言
```

## 三、切换 MySQL

编辑 `backend/.env`：

```ini
SDF_DATABASE_URL=mysql+pymysql://root:123456@127.0.0.1:3306/smart_data_forge?charset=utf8mb4
```

先建库（表由 SQLAlchemy 自动创建）：

```sql
CREATE DATABASE smart_data_forge DEFAULT CHARACTER SET utf8mb4;
```

## 四、配置大模型（可选，不配置即为模拟模式）

平台「模型配置」页新增即可，统一 OpenAI 兼容协议：

| 供应商 | Base URL | 模型名示例 |
| --- | --- | --- |
| 火山方舟 ARK | `https://ark.cn-beijing.volces.com/api/v3` | `deepseek-v3-241226` |
| DeepSeek 官方 | `https://api.deepseek.com/v1` | `deepseek-chat` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| 本地 Ollama/vLLM 等 | `http://localhost:11434/v1` | 对应模型名 |

## 五、典型使用流程

1. **项目与代码分析**：新建项目，填写后端可访问的代码目录，或直接上传 `.zip/.tar.gz`；点「扫描代码目录」得到接口清单（方法/路径/处理函数/下游调用）。
2. **业务链路**：点「AI 识别业务流」让大模型聚类（无 Key 时按资源规则聚类），勾选保存；或在 Vue Flow 画布上手工拖线编排，把接口节点、Skill 节点串成业务流，确认。
3. **Skill**：上传/编写造数脚本（如下发优惠券、开通资金账户等复杂逻辑），在线测试后在链路节点上绑定。
4. **智能造数**：选业务流 → 填业务变量 → AI 生成计划 → 微调字段/模式/依赖 → 执行；时间线查看每步数据与实体。
5. **业务流数据**：按批次查看/修改数据、单步重放。
6. **智能清理**：用完按批次一键回收。

## 六、对外开放接口（给自动化平台）

鉴权头：`X-SDF-Token: sdf_xxxx`（平台「开放接口」页创建）。

```bash
# 用例前置：按业务流智能造数
curl -X POST http://localhost:8096/open/v1/data/generate \
  -H "X-SDF-Token: sdf_xxxx" -H "Content-Type: application/json" \
  -d '{"project_code":"demo-mall","flow_biz_key":"order_pay_flow","variables":{"amount":199}}'
# => { "batch_no": "B2026...", "steps": [...], "entity_index": {"user":[...], "order":[...]} }

# 用例后置：按批次清理
curl -X POST http://localhost:8096/open/v1/data/cleanup \
  -H "X-SDF-Token: sdf_xxxx" -H "Content-Type: application/json" \
  -d '{"batch_no":"B2026..."}'
```

其余端点：`GET /open/v1/flows?project_code=`、`GET /open/v1/data/batch/{batch_no}`、
`POST /open/v1/skills/{skill_code}/run`。完整交互式文档：`http://localhost:8096/docs`。

pytest 夹具样例见平台「开放接口」页的 **pytest 集成** 标签。

## 七、Skill 技能包约定（zip）

在「Skill 技能」页上传 zip 即自动解析为 Skill；模板分 **Python** 与 **Shell** 两种可下载。
一个 zip 内允许放多个技能包目录（每个目录一个 `SKILL.md`），支持同包内多脚本互相引用。

**清单文件是 Markdown（`SKILL.md`）**：YAML frontmatter 写元信息，正文写技能说明：

```
my_skill/
├── SKILL.md          # 清单（Markdown + frontmatter）
├── main.py           # Python 入口，或 run.sh（Shell 入口，由 entry 指定）
├── helpers.py        # Python 同包模块（可 import）/ *.sh（可 source）
└── README.md
```

`SKILL.md` 示例：

```markdown
---
name: 标准测试用户
code: create_standard_user
description: 构造带画像的测试用户
tags: 用户,基础数据
entry: main.py            # 支持 .py(Python) 或 .sh(Shell)
params_schema:
  - {"name": "username", "label": "用户名", "type": "string", "required": false}
---

# 标准测试用户
这里用 Markdown 描述技能用途、参数、清理策略（可在平台直接查看）。
```

**Python 入口**（`.py`）实现 `construct` / 可选 `cleanup`，可 import 同包模块：

```python
from helpers import build_user

def construct(ctx, **params) -> dict:
    # ctx.variables / ctx.step_outputs / ctx.base_url / ctx.get/post
    # ctx.pkg_dir / ctx.read_file(rel) 读取包内资源
    data = build_user(params)
    return {"entities": [{"type": "user", "key": str(data["id"]), "label": data["username"]}],
            "data": data}

def cleanup(ctx, entity) -> bool:
    return True
```

**Shell 入口**（`.sh`）通过环境变量调用，在标准输出打印结果行：

- 环境变量：`SDF_ACTION`(construct/cleanup)、`SDF_PARAMS`(construct 参数或 cleanup 实体 JSON)、
  `SDF_CTX`(variables/base_url/step_outputs)、`SDF_PKG_DIR`。
- stdout 最后一行：`__SDF_RESULT__{"ok":true,"entities":[...],"data":{...}}`（cleanup 为 `{"ok":true}`）。

```bash
#!/usr/bin/env bash
set -euo pipefail
USER_ID=$(python3 -c "import json,os;print(json.loads(os.environ['SDF_PARAMS']).get('user_id') or 1)")
# 可用 curl 实际造数 ...
USER_ID="$USER_ID" python3 - <<'PY'
import json, os
print("__SDF_RESULT__" + json.dumps(
    {"ok": True, "entities": [], "data": {"id": int(os.environ["USER_ID"])}}))
PY
```

没有 `SKILL.md` 时，平台会把包含 `def construct` 的 `.py` 或输出 `__SDF_RESULT__` 的 `.sh`
自动识别为入口。技能包落盘于 `backend/workspace/skills/<code>/`，页面编辑保存后即时生效；
旧版单文件 `skills/<code>.py` 启动时自动迁移为技能包目录。

## 八、目录结构

```
smart-data-forge/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI 入口（含 SPA 同源托管）
│   │   ├── config.py / database.py / models.py / schemas.py
│   │   ├── routers/             # projects/flows/skills/forge/models/tokens/openapi/stats
│   │   └── services/
│   │       ├── analyzer.py      # Java/Python/Node 静态分析
│   │       ├── flow_service.py  # AI 业务流聚类（规则兜底）
│   │       ├── llm_service.py   # 多模型客户端（OpenAI 兼容，无 Key 模拟）
│   │       ├── forge_engine.py  # 造数计划生成/执行/引用解析/清理
│   │       ├── mock_generator.py# 仿真数据生成（字段语义识别）
│   │       ├── skill_service.py # 技能包管理（zip 解析/安装/文件）
│   │       ├── skill_runner.py  # 子进程执行器（construct/cleanup，支持同包 import）
│   │       └── seed_service.py  # 内置示例项目/代码/技能包
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── pages/               # 首页(发布会风)+8 个业务页面
│   │   ├── components/FlowNode.vue
│   │   ├── api/http.js / router.js / styles/main.css
│   └── vite.config.js           # 5196 端口，代理 /api /open → 8096
├── tests/e2e_test.py
├── start-dev.sh / build-and-run.sh
└── README.md
```

## 九、说明与限制

- 代码分析为轻量正则/AST 方案，满足 Controller 路由与一层下游调用提取；超复杂注解/多模块分发建议在画布上人工校正。
- mock 模式不真实写库，清理即血缘标记；配置「被测环境地址」且步骤为 api 模式时会真实调用目标接口（生产环境清理可在 Skill 的 `cleanup` 中发 DELETE 请求）。
- Skill 脚本在子进程中执行（超时默认 30s），多租户公网场景请配合容器/沙箱进一步隔离。