bridgeflow 0.1.6

BridgeFlow 人机协作桥接与团队巡检工具

BridgeFlow

BridgeFlow 是一个面向多 Agent 团队协作场景的人机桥接与轻量巡检工具。

第一阶段目标不是“远程操控电脑”，而是把真人成员 ADMIN01 正式纳入团队协议：

• 手机端通过 PWA 发送文本
• 桌面端收到文本后落成标准任务文件
• PM01 按既有 TASK-*.md 协议接单
• PM01 或团队给 ADMIN01 的回复，也通过标准文本文件回流

这样，手机端看到的不是一套独立聊天记录，而是按时间展开的一条条项目文本文件。

第一阶段能力

• Python 包与 CLI 入口
• ADMIN01 -> PM01 任务文件生成
• PM01/DEV01/OPS01/QA01 -> ADMIN01 回复文件识别与摘要推送
• WebSocket 轻量中继
• GitHub Pages 可托管的手机 PWA 静态页
• bridgeflow_config.json 配置化

架构

flowchart LR
    adminPwa[AdminPWA]
    relayServer[RelayServer]
    desktopBridge[DesktopBridge]
    taskFiles[TaskFiles]
    replyFiles[ReplyFiles]
    pmAgent[PMAgent]

    adminPwa -->|"文本消息"| relayServer
    relayServer -->|"JSON事件"| desktopBridge
    desktopBridge -->|"写 TASK-*-ADMIN01-to-PM01.md"| taskFiles
    pmAgent -->|"处理任务"| taskFiles
    pmAgent -->|"写 TASK-*-PM01-to-ADMIN01.md"| replyFiles
    desktopBridge -->|"扫描回复并推送摘要"| relayServer
    relayServer -->|"状态/回执/链接"| adminPwa

目录结构

BridgeFlow/
├── .cursor/
│   └── rules/
│       └── admin-human-bridge.mdc
├── pyproject.toml
├── README.md
├── docs/
│   ├── 产品设计说明.md
│   └── agents/
│       ├── README.md
│       └── ADMIN-01.md
├── examples/
│   └── bridgeflow_config.json
├── server/
│   └── relay/
│       └── server.py
├── src/
│   └── bridgeflow/
│       ├── cli.py
│       ├── config.py
│       ├── file_protocol.py
│       ├── task_writer.py
│       ├── relay_client/
│       │   └── ws_client.py
│       ├── desktop/
│       │   └── runner.py
│       └── models/
│           └── events.py
└── web/
    └── pwa/
        └── index.html

Agent 文件结构

BridgeFlow 第一阶段已经内置一套最小 agent_bridge 协议骨架：

• docs/agents/README.md
• docs/agents/ADMIN-01.md
• docs/联调启动说明.md
• .cursor/rules/admin-human-bridge.mdc

作用分别是：

• README.md：说明 docs/agents/ 的目录结构和文件协议
• ADMIN-01.md：定义真人角色 ADMIN01 的职责和边界
• admin-human-bridge.mdc：给桥接逻辑或后续会话一个明确规则，要求“每条手机文本都必须落成任务文件”

核心原则

• 手机端只处理文本文件，不碰 Cursor 窗口
• PC 端负责团队内部巡检与文件桥接
• 中继只传文本与链接，不传大文件
• 发送与回复都必须文件化，避免形成第二套协议
• 角色与显示名分离，后续支持 PM/CTO 等别名

中继边界

• 默认接口端口：5252
• 仅转发文本 JSON 事件
• 不落盘、不执行、不上传文件
• 单条消息限制 8KB
• 默认频率限制：10 秒内最多 20 条
• 公网入口示例：wss://relay.example.com/bridgeflow/ws/

公开发布建议：

• 不要把真实生产 wss 地址写死到默认配置
• room_key 建议改成随机值，不要继续使用演示房间
• 生产环境建议通过配置文件或环境变量覆盖示例值

本地开发

cd BridgeFlow
py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .

主要命令

bridgeflow init
bridgeflow write-admin-task --text "请 PM 帮我安排下一步任务"
bridgeflow write-reply --sender PM01 --text "已接单，开始拆解任务" --thread-key "demo-thread-001"
bridgeflow relay-connect
bridgeflow run

示例配置建议：

• 本地联调可使用 ws://127.0.0.1:5252
• 公开示例中的 room_key 请替换成你自己的随机房间名
• PWA 默认配置建议使用示例中继地址，发布时再按部署环境覆盖

第一阶段联调顺序

1. 启动 server/relay/server.py
2. 运行 bridgeflow init
3. 运行 bridgeflow run
4. 打开 web/pwa/index.html 本地预览或发布到 GitHub Pages
5. 在手机端输入文本，验证桌面端是否生成 TASK-*-ADMIN01-to-PM01.md
6. 运行 bridgeflow write-reply --sender PM01 --text "已接单"，验证手机端是否收到回复摘要

后续扩展

• 对接现有 ops/auto_patrol.py 的窗口巡检逻辑
• 把当前基础 thread_key 能力升级成完整会话线程 UI
• 增加 OSS 链接分享与图片附件
• 加入 room_key 和更严格的中继鉴权

命名约定

• 应用名：BridgeFlow
• 文件协作协议：agent_bridge
• Python 包名：bridgeflow
• CLI 命令：bridgeflow