bridgeflow 0.2.5

BridgeFlow — 手机主控 + PC 执行机 + 文件协议的多 AI 角色人机协作桥接工具

BridgeFlow

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

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

---

产品架构

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

---

快速开始（PC 端）

# 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

---

目录结构

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 命令速查

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 文件协议

任务文件命名格式：

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

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

---
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
• 版本历史：CHANGELOG.md
• 用户手册：docs/user-manual.md
• 配置参考：docs/config-reference.md