Metadata-Version: 2.4
Name: bizyair-cloudberry
Version: 0.2.4
Summary: ComfyUI custom node for cloud-based workflow execution via BizyAir API
Project-URL: Repository, https://github.com/siliconflow/BizyAir-CloudBerry
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets>=12.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# ☁️ BizyAir-CloudBerry

ComfyUI 自定义节点插件，通过 BizyAir/SCX API 实现工作流的云端执行。

## 安装

```bash
pip install bizyair-cloudberry
```

## 配置

必填：

```bash
export BIZYAIR_API_KEY=sk-xxxxxx
```

可选（已有默认值）：

| 变量名 | 说明 |
|--------|------|
| `BIZYAIR_API_URL` | BizyAir API 地址 |
| `BIZYAIR_SCX_API_URL` | SCX API 地址 |

## 开发

### 前端开发 (Vue 3 独立包)

前端是一个独立的 Vue 3 + TypeScript 应用，提供模型选择对话框功能。

```bash
cd frontend
npm ci
npm run dev     # 开发服务器 (端口 5175)
npm run build   # 构建，输出到 ../src/bizyair_cloudberry/web/
```

构建产物为 UMD 格式的 `bizyair_cloudberry_ui.js`，通过 `window.bizyairCBLib.showModelSelect()` 调用。

技术栈：Vue 3 + TypeScript + Tailwind CSS + naive-ui + vue-i18n

### 后端开发

```bash
# Python 依赖安装
pip install -e ".[dev]"

# 代码格式化
ruff format .

# 运行测试（集成测试需要设置 BIZYAIR_API_KEY）
PYTHONPATH=src python -m pytest tests/ -v
```

### UI 测试 (Playwright)

```bash
cd tests/ui
npm ci
npx playwright install --with-deps
npx playwright test
```

需要先启动 ComfyUI 实例（`localhost:8188`）。

### 构建打包

前端必须先构建，产物 `bizyair_cloudberry_ui.js` 会被打包进 wheel：

```bash
# 1. 构建前端
cd frontend && npm ci && npm run build

# 2. 构建 Python 包（开发）
pip install -e .

# 2. 构建 Python 包
pip install build && python -m build
```

## 架构

```text
ComfyUI Server → hijack.py → CloudBerrySubgraphNode → InputHandler → SCXAPIExecutor
                                                              ↓
                        ← progress_handler.py ← TaskMonitor ← Task WebSocket
                                                              ↑
                                          gateway_manager.py ← Draft WebSocket
```

### 关键组件

#### 后端 (src/bizyair_cloudberry/)

- `cloudberry_node.py` - ComfyUI 节点入口
- `hijack.py` - 拦截 prompt 并注入 CloudBerry wrapper
- `input_handler.py` - 文件/模型映射与解析，图片上传 OSS
- `process_transform.py` - 转换工作流 prompt 为云端执行格式
- `file_utils.py` - OSS 文件上传下载（三阶段：获取凭证→上传→提交）
- `event_processor.py` - 远程事件转换为本地格式
- `env.py` - pydantic-settings 环境变量管理
- `scx_executor/` - SCX API 执行器，含双 WebSocket 管理（Draft WS + Task WS）
- `client/scx_client.py` - SCX API 客户端（HTTP + WebSocket）
- `routes/community.py` - 社区相关 API 端点（模型浏览等）

#### ComfyUI 前端扩展 (src/bizyair_cloudberry/web/)

- `cloudberry.js` - 主入口，注册扩展
- `model_apply.js` - 模型 widget 点击行为配置
- `modules/state.js` - CloudBerry 模式状态（localStorage）
- `modules/logic.js` - 拦截 graphToPrompt 注入 cloudberry_mode
- `modules/model.js` - 模型选择逻辑、徽章系统
- `modules/configLoader.js` - 远程节点配置加载

#### Vue 前端 (frontend/)

- Vue 3 + TypeScript 独立包，构建为 UMD 格式
- `showModelSelect()` 导出到 `window.bizyairCBLib`，由原生 JS 扩展调用
- 通过 `/bizyair/*` API 与后端通信
- 支持中英文 i18n
