Metadata-Version: 2.4
Name: bridgeflow
Version: 0.1.7
Summary: BridgeFlow 人机协作桥接与团队巡检工具
Author: joinwell52-AI
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets<16,>=12

# 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` 配置化

## 架构

```mermaid
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
```

## 目录结构

```text
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/README.md)
- [docs/agents/ADMIN-01.md](docs/agents/ADMIN-01.md)
- [docs/联调启动说明.md](docs/联调启动说明.md)
- [.cursor/rules/admin-human-bridge.mdc](.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` 建议改成随机值，不要继续使用演示房间
- 生产环境建议通过配置文件或环境变量覆盖示例值

## 本地开发

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

## 主要命令

```powershell
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`
