bridgeflow 0.1.0__tar.gz

bridgeflow-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: bridgeflow
+Version: 0.1.0
+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`

bridgeflow-0.1.0/README.md

@@ -0,0 +1,164 @@
+# 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`

bridgeflow-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bridgeflow"
+version = "0.1.0"
+description = "BridgeFlow 人机协作桥接与团队巡检工具"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "joinwell52-AI" }
+]
+dependencies = [
+  "websockets>=12,<16"
+]
+
+[project.scripts]
+bridgeflow = "bridgeflow.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

bridgeflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bridgeflow-0.1.0/src/bridgeflow/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

bridgeflow-0.1.0/src/bridgeflow/binding.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+import secrets
+import string
+
+from bridgeflow.config import PatrolConfig
+
+
+BIND_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+
+def _now() -> datetime:
+    return datetime.now()
+
+
+def _fmt(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _parse(value: str) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.strptime(value, "%Y-%m-%d %H:%M:%S")
+    except ValueError:
+        return None
+
+
+def _new_code(length: int = 6) -> str:
+    return "".join(secrets.choice(BIND_ALPHABET) for _ in range(length))
+
+
+def has_active_bind_code(config: PatrolConfig) -> bool:
+    if not config.pending_bind_code or not config.pending_bind_expires_at:
+        return False
+    expires_at = _parse(config.pending_bind_expires_at)
+    return expires_at is not None and expires_at >= _now()
+
+
+def public_bind_state(config: PatrolConfig) -> dict:
+    return {
+        "status": config.bind_status,
+        "machine_code": config.machine_code,
+        "bound_mobile_device_id": config.bound_mobile_device_id,
+        "bound_mobile_device_name": config.bound_mobile_device_name,
+        "bound_at": config.bound_at,
+        "has_pending_code": has_active_bind_code(config),
+        "pending_bind_expires_at": config.pending_bind_expires_at if has_active_bind_code(config) else "",
+        "pending_mobile_device_id": config.pending_mobile_device_id,
+        "pending_mobile_device_name": config.pending_mobile_device_name,
+        "bind_code_ttl_seconds": config.bind_code_ttl_seconds,
+    }
+
+
+def private_bind_state(config: PatrolConfig) -> dict:
+    data = public_bind_state(config)
+    data["pending_bind_code"] = config.pending_bind_code if has_active_bind_code(config) else ""
+    data["last_bind_code_issued_at"] = config.last_bind_code_issued_at
+    return data
+
+
+def issue_bind_code(
+    config: PatrolConfig,
+    *,
+    mobile_device_id: str = "",
+    mobile_device_name: str = "",
+) -> dict:
+    now = _now()
+    code = _new_code()
+    expires_at = now + timedelta(seconds=config.bind_code_ttl_seconds)
+    config.update_bind(
+        status="pending",
+        pending_bind_code=code,
+        pending_bind_expires_at=_fmt(expires_at),
+        pending_mobile_device_id=mobile_device_id.strip(),
+        pending_mobile_device_name=mobile_device_name.strip(),
+        last_bind_code_issued_at=_fmt(now),
+    )
+    return private_bind_state(config)
+
+
+def approve_bind(
+    config: PatrolConfig,
+    *,
+    bind_code: str,
+    mobile_device_id: str,
+    mobile_device_name: str,
+) -> dict:
+    bind_code = bind_code.strip().upper()
+    if not bind_code:
+        raise ValueError("绑定码不能为空")
+    if not mobile_device_id.strip():
+        raise ValueError("mobile_device_id 不能为空")
+    if not has_active_bind_code(config):
+        raise ValueError("当前没有可用的绑定码")
+    if bind_code != config.pending_bind_code.strip().upper():
+        raise ValueError("绑定码不正确")
+
+    now = _now()
+    config.update_bind(
+        status="bound",
+        bound_mobile_device_id=mobile_device_id.strip(),
+        bound_mobile_device_name=mobile_device_name.strip(),
+        bound_at=_fmt(now),
+        pending_bind_code="",
+        pending_bind_expires_at="",
+        pending_mobile_device_id="",
+        pending_mobile_device_name="",
+    )
+    return public_bind_state(config)
+
+
+def clear_binding(config: PatrolConfig) -> dict:
+    config.update_bind(
+        status="unbound",
+        bound_mobile_device_id="",
+        bound_mobile_device_name="",
+        bound_at="",
+        pending_bind_code="",
+        pending_bind_expires_at="",
+        pending_mobile_device_id="",
+        pending_mobile_device_name="",
+    )
+    return public_bind_state(config)