# BridgeFlow

[![PyPI version](https://img.shields.io/pypi/v/bridgeflow.svg)](https://pypi.org/project/bridgeflow/)
[![Python](https://img.shields.io/pypi/pyversions/bridgeflow.svg)](https://pypi.org/project/bridgeflow/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PWA](https://img.shields.io/badge/PWA-GitHub%20Pages-green)](https://joinwell52-ai.github.io/bridgeflow-pwa/)
[![GitHub](https://img.shields.io/badge/GitHub-joinwell52--ai%2FBridgeFlow-black)](https://github.com/joinwell52-ai/BridgeFlow)

**BridgeFlow** 是一套面向多 AI 角色团队的**人机协作桥接工具**。

手机是主控台，PC 是执行机，中继是文本传输层。  
每一条消息都落成标准任务文件，不形成第二套聊天协议。

---

## 产品架构

```
手机端 PWA                  中继（WebSocket）               PC 执行机
────────────                ──────────────────────────     ──────────────────
发送任务文本       ──────>  wss://your-relay-server   <──── bridgeflow run
查看任务清单                /bridgeflow/ws/                写 TASK-*.md
查看回复摘要       <──────  转发 JSON 事件           ──────> 扫描回执推送
扫码绑定 PC                                                Cursor 窗口控制
```

---

## 快速开始（PC 端）

```powershell
# 1. 安装（来自 PyPI）
pip install bridgeflow

# 2. 初始化（生成配置 + 复制 Cursor 规则文件到 .cursor/rules/）
bridgeflow init

# 3. 启动（自动打开浏览器仪表盘 localhost:18765）
bridgeflow run
```

浏览器仪表盘包含：
- 环境检测（OS / Python / Cursor 安装状态）
- 连接状态（中继连接是否成功）
- **二维码**（手机扫码一键绑定）

---

## 手机端 PWA

**访问地址：** https://joinwell52-ai.github.io/bridgeflow-pwa/

> 用手机浏览器打开，点"添加到主屏幕"即可像 App 一样使用。

页面布局（v1.6.0）：

```
┌──────────────────────────┐  ← 固定顶部 Header
│ [logo] BridgeFlow  [●][我的] │
├──────────────────────────┤
│  [今日任务] [今日回复]    │  ← 看板（4个快捷按钮）
│  [进行中]  [已完成]       │
├──────────────────────────┤  ↑ 以下整体可上下滚动
│  [PM] [DEV] [OPS] [QA]   │  ← 团队（点击切换任务列表）
├──────────────────────────┤
│  任务清单                │  ← 点任务展开详情+MD记录
├──────────────────────────┤
│  发送任务区              │  ← 人员/输入/级别/发送
└──────────────────────────┘
"我的" → 点顶部右角按钮 → 独立全屏页
```

---

## 发布渠道

| 渠道 | 地址 | 说明 |
|------|------|------|
| **PyPI** | https://pypi.org/project/bridgeflow/ | PC 端 Python 包 |
| **GitHub** | https://github.com/joinwell52-ai/BridgeFlow | 源码仓库 |
| **GitHub Pages (PWA)** | https://joinwell52-ai.github.io/bridgeflow-pwa/ | 手机端 PWA |

---

## 目录结构

```text
BridgeFlow/
├── pyproject.toml               # Python 包配置
├── README.md                    # 本文件
├── CHANGELOG.md                 # 版本历史
│
├── src/bridgeflow/              # Python 包源码
│   ├── cli.py                   # CLI 入口（init / run / write-* / bind-*）
│   ├── config.py                # 配置读写
│   ├── file_protocol.py         # TASK-*.md 文件协议
│   ├── task_writer.py           # 任务文件写入器
│   ├── env_check.py             # 跨平台环境检测（Win/Mac/Linux）
│   ├── relay_client/
│   │   └── ws_client.py         # WebSocket 中继客户端
│   ├── desktop/
│   │   └── runner.py            # 桌面桥接主逻辑
│   ├── dashboard/
│   │   ├── server.py            # 本地 HTTP 仪表盘（localhost:18765）
│   │   └── index.html           # 仪表盘前端页面
│   ├── models/
│   │   └── events.py            # 中继事件数据模型
│   └── data/
│       ├── bridgeflow_config.json   # 默认配置模板
│       └── rules/
│           ├── admin-human-bridge.mdc
│           ├── pm-bridge.mdc
│           ├── dev-bridge.mdc
│           ├── ops-bridge.mdc
│           └── qa-bridge.mdc
│
├── web/pwa/                     # 手机端 PWA 源码
│   ├── index.html               # 主页面（v1.6.0）
│   ├── config.js                # 前端配置（中继地址/房间/版本）
│   ├── sw.js                    # Service Worker（离线缓存）
│   └── manifest.json            # PWA 清单
│
├── .github/
│   └── workflows/
│       ├── publish.yml          # tag 触发 → 自动发布到 PyPI
│       └── deploy-pwa.yml       # main 推送 → 自动部署 PWA 到 GitHub Pages
│
├── docs/                        # 公开文档（随 GitHub 发布）
│   ├── user-manual.md           # 用户操作手册
│   ├── config-reference.md      # 配置参数字典
│   └── agents/                  # 角色定义 + 任务/回执文件
│       ├── README.md            # Agent 文件结构说明
│       ├── ADMIN-01.md / PM-01.md / DEV-01.md / OPS-01.md / QA-01.md
│       ├── tasks/
│       ├── reports/
│       ├── log/
│       └── issues/
│
├── private/                     # 开发者内部文档（非敏感信息）
│   ├── product-design.md        # 产品设计说明
│   ├── local-debug-guide.md     # 本地联调步骤
│   ├── public-deploy-guide.md   # 公网部署说明
│   ├── pc-setup-guide.md        # PC 执行机落地说明
│   ├── relay-keepalive-guide.md # 中继保活指南
│   ├── github-release-guide.md  # GitHub 发布说明
│   └── pypi-release-guide.md    # PyPI 发布说明
│
├── server/relay/
│   └── server.py                # 本地联调用独立中继
│
├── .cursor/rules/               # Cursor AI 规则（bridgeflow init 自动复制）
│   ├── bridgeflow-project.mdc   # 项目总规范
│   ├── admin-human-bridge.mdc
│   ├── pm-bridge.mdc
│   ├── dev-bridge.mdc
│   ├── ops-bridge.mdc
│   └── qa-bridge.mdc
│
└── _smoke_test/                 # 本地烟雾测试目录
```

---

## 中继地址

| 环境 | 地址 |
|------|------|
| **自部署中继** | `wss://your-relay-server/bridgeflow/ws/`（自行部署，见部署说明） |
| 本地联调 | `ws://127.0.0.1:5252`（运行 `server/relay/server.py`） |

中继为轻量 WebSocket 服务，可集成到任意 FastAPI / Starlette 后端，也可独立运行。

---

## CLI 命令速查

```powershell
bridgeflow init                    # 初始化配置 + 复制 Cursor 规则文件
bridgeflow run                     # 启动桥接 + 打开本地仪表盘

bridgeflow write-admin-task --text "请 PM 安排下一步"
bridgeflow write-reply --sender PM01 --text "已接单" --thread-key "xxx"

bridgeflow bind-status             # 查看绑定状态
bridgeflow bind-code               # 生成绑定码（手动绑定备用方案）
bridgeflow approve-bind --code A1B2 --mobile-device-id mobile-xxx
bridgeflow unbind                  # 解除绑定

bridgeflow desktop-action --action focus_cursor
bridgeflow desktop-action --action inspect
bridgeflow desktop-action --action start_work
```

---

## 扫码绑定流程

1. PC 端运行 `bridgeflow run`，浏览器打开 `localhost:18765`
2. 仪表盘显示 QR 码（内含中继地址、房间、机器码）
3. 手机打开 PWA → 点顶部右角"我的" → 点"📷 扫码绑定 PC"
4. 对准 PC 仪表盘二维码，自动解析并发送绑定请求
5. PC 端确认（`approve-bind`），绑定完成

---

## Agent 文件协议

任务文件命名格式：

```text
TASK-YYYYMMDD-序号-发送方-to-接收方.md
```

每个文件包含标准元数据头：

```yaml
---
protocol: agent_bridge
version: 1
kind: task
sender: ADMIN01
recipient: PM01
priority: P1
thread_key: 20260401-123000-ADMIN01-to-PM01
created_at: 2026-04-01 12:30:00
---
```

---

## 核心原则

- 手机端只处理文本，不碰 Cursor 窗口
- PC 端负责桥接、巡检、文件生成
- 中继只传文本 JSON，不落盘、不执行、不传大文件
- 每条消息必须文件化，不形成第二套聊天协议
- 角色与显示名分离，支持后续扩展

---

## 贡献与发布

- 源码：[github.com/joinwell52-ai/BridgeFlow](https://github.com/joinwell52-ai/BridgeFlow)
- 版本历史：[CHANGELOG.md](CHANGELOG.md)
- 用户手册：[docs/user-manual.md](docs/user-manual.md)
- 配置参考：[docs/config-reference.md](docs/config-reference.md)
