# UniAppAgent

**Repository Path**: dirty_up/UniAppAgent

## Basic Information

- **Project Name**: UniAppAgent
- **Description**: 本项目是一个面向移动应用产品设计的 本地工作流 HTTP 服务：用户只需提供产品名称，即可由大模型按既定框架生成应用的功能设计文档，并自动落盘到本地；在用户确认后，再通过 Google Stitch MCP 将文档提交至 Stitch 生成界面与代码资源，并支持将项目中全部资源批量下载保存到 assets 目录，，适合作为从「产品一句话」到「可落地的 Stitch 设计资产」的自动化桥梁。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目结构说明

本项目是一个面向移动应用产品设计的 本地工作流 HTTP 服务：用户只需提供产品名称，即可由大模型按既定框架生成 单机工具类应用的功能设计文档（Markdown），并自动落盘到本地；在用户确认后，再通过 Google Stitch MCP 将文档提交至 Stitch 生成界面与代码资源，并支持将项目中 全部 Screen 的截图与 HTML 批量下载保存到 assets 目录，便于后续审阅、归档或与设计稿对齐。整体流程强调 本地文档与生成物管理、两阶段确认（先出文档再提交）以及 可脚本化调用（REST 接口），适合作为从「产品一句话」到「可落地的 Stitch 设计资产」的自动化桥梁。

该项目为一个工作流服务：
- **阶段1**：根据 `product_name` 生成“产品功能设计文档”（Markdown），并保存到 `assets/function_docs/`
- **阶段2**：用户确认后，将已保存的文档内容提交到 Google Stitch（通过 MCP），并在指定等待时间后拉取生成资源（截图/HTML）保存到本地

---

# 本地启动

## 1) 环境准备（推荐 Python 3.12）
macOS + Homebrew 建议使用：

```bash
brew install python@3.12
/opt/homebrew/bin/python3.12 -m venv .venv312
source .venv312/bin/activate
pip install -r requirements.txt
```

## 2) 配置环境变量
复制并修改 `.env`（注意：路径包含空格时必须加引号）：

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

启动前加载：

```bash
set -a
source .env
set +a
```

关键变量：
- `COZE_WORKLOAD_IDENTITY_API_KEY`
- `COZE_WORKSPACE_PATH`（例如：`"/Users/xxx/Coze/projects 2"`）
- `GOOGLE_STITCH_API_KEY`（用于 Stitch MCP）

## 3) 启动 HTTP 服务（FastAPI / uvicorn）

```bash
source .venv312/bin/activate
set -a && source .env && set +a
python src/main.py -m http -p 5000
```

健康检查：

```bash
curl -sS http://127.0.0.1:5000/health
```

---

# 接口说明

## 1) 生成文档（默认不提交 Stitch）
`POST /run`

请求：
```json
{"product_name":"智能记账本"}
```

响应关键字段：
- `product_id`: 形如 `{产品名}__{run_id}`
- `product_info`: 功能设计文档（Markdown）
- `saved_files`: 会包含落盘路径（`assets/function_docs/{product_id}.md`）

示例：

```bash
curl -sS -X POST 'http://127.0.0.1:5000/run' \
  -H 'Content-Type: application/json' \
  -d '{"product_name":"智能记账本"}'
```

## 2) 确认后提交 Stitch（同一接口）
`POST /run`

请求（确认提交）：
```json
{"product_name":"智能记账本","confirmed":true}
```

可选参数：
- `stitch_wait_seconds`: 提交后最多等待多少秒轮询资源（默认 300）
- `save_dir`: 生成资源保存目录（默认 `assets/stitch`）

示例：

```bash
curl -sS -X POST 'http://127.0.0.1:5000/run' \
  -H 'Content-Type: application/json' \
  -d '{"product_name":"智能记账本","confirmed":true,"stitch_wait_seconds":300,"save_dir":"assets/stitch"}'
```

## 3) 按文档 id 提交 Stitch（不重新生成文档）
`POST /submit_by_id/{doc_run_id}`

说明：
- `doc_run_id` 是文件名 `xxx__{doc_run_id}.md` 里的 uuid 部分
- 服务会自动读取 `assets/function_docs/*__{doc_run_id}.md` 并提交 Stitch

示例：

```bash
curl -sS -X POST 'http://127.0.0.1:5000/submit_by_id/0a808734-bbd3-4192-b8d9-5a4071d0c645' \
  -H 'Content-Type: application/json' \
  -d '{"stitch_wait_seconds":300,"save_dir":"assets/stitch"}'
```

## 4) 拉取 Stitch 项目资产（批量下载 Screens 的截图/HTML）
`POST /fetch_stitch_assets`

用途：
- 当你已经拿到 Stitch 的 `project_id`（不带 `projects/` 前缀），希望**重新批量拉取**该项目下所有 screens 的生成物（`screenshot.png` 与 `screen.html`）并保存到本地时使用
- 该接口会调用 Stitch MCP 的 `list_screens`，并下载每个 screen 的 `screenshot.downloadUrl` 与 `htmlCode.downloadUrl`

请求参数：
- `project_id`（必填）：Stitch 项目 ID（不带 `projects/` 前缀）
- `api_key`（可选）：Google Stitch API Key；不传则使用环境变量 `GOOGLE_STITCH_API_KEY`
- `save_dir`（可选）：保存目录（相对工作区，默认 `assets/stitch`）
- `prefer_screen_name`（可选）：保留字段（目前不会影响下载逻辑）

示例：

```bash
curl -sS -X POST 'http://127.0.0.1:5000/fetch_stitch_assets' \
  -H 'Content-Type: application/json' \
  -d '{"project_id":"13492189359683220425","save_dir":"assets/stitch"}'
```

返回说明（关键字段）：
- `ok`: 是否成功拉取到 screens 并完成下载尝试
- `project_id`: 你传入的项目 ID
- `count`: screens 数量
- `items`: 每个 screen 的下载/落盘结果（含 `screen_name`、`screen_id`、`saved_screenshot`、`saved_html`）
- `saved_files`: 实际保存到本地的文件路径列表

落盘路径规则：
- `assets/stitch/{project_id}/{screen_title_or_id}/screenshot.png`
- `assets/stitch/{project_id}/{screen_title_or_id}/screen.html`

说明：
- `{screen_title_or_id}` 优先使用 Stitch 返回的 screen `title`（会做安全字符清理），若为空则使用 `screen_id`
- 若多个 screen 的 `title` 重名，会自动追加后缀 `__{screen_id前8位}` 以避免覆盖

## 5) 查询 Stitch 项目信息
`GET /get_stitch_project/{project_id}`

用途：
- 当你只需要查看 Stitch 项目元信息（项目名、screen 实例信息、状态等），而不需要下载 screen 资产时使用
- 该接口会调用 Stitch MCP 的 `get_project`，请求参数为 `name=projects/{project_id}`

路径参数：
- `project_id`（必填）：Stitch 项目 ID（不带 `projects/` 前缀）

认证参数（二选一）：
- query 参数 `api_key`：例如 `?api_key=AIza...`
- 请求头 `X-Stitch-Api-Key`
- 若都不传，则回退使用环境变量 `GOOGLE_STITCH_API_KEY`

示例：

```bash
curl -sS "http://127.0.0.1:5000/get_stitch_project/9176054261514250787"
```

```bash
curl -sS "http://127.0.0.1:5000/get_stitch_project/9176054261514250787?api_key=YOUR_API_KEY"
```

返回说明（关键字段）：
- `ok`: 是否成功
- `project_id`: 你传入的项目 ID
- `project`: 结构化后的项目信息（由 Stitch MCP 响应解析得到）
- `raw_response`: Stitch MCP 原始响应（便于排查）

异常说明：
- 未提供可用 API Key 时，返回 `400`，错误为 `GOOGLE_STITCH_API_KEY missing`
- `project_id` 为空时，返回 `400`，错误为 `project_id is required`
- 若 Stitch MCP 调用失败，接口返回 `ok=false`，并在 `response` 字段返回原始错误信息

## 6) 其他常用接口
- `GET /graph_parameter`: 获取工作流入参/出参 schema
- `POST /stream_run`: SSE 流式运行
- `POST /cancel/{run_id}`: 取消指定 run（推荐配合请求头 `x-run-id`）


---

# 旧脚本（仍可用）
## 运行流程
```bash
bash scripts/local_run.sh -m flow
```

## 运行节点
```bash
bash scripts/local_run.sh -m node -n node_name
```

## 启动 HTTP 服务（脚本）
```bash
bash scripts/http_run.sh -p 5000
```