# BRB

![BRB](https://cdn.jsdelivr.net/npm/@yedan1122/brb/docs/assets/readme.webp)

<!-- section:hero -->

> 把 Pi 的工作流接到真实的 ChatGPT 会话上。

[English](README.md) | 简体中文

BRB 是 Pi 的扩展，用来把任务安全地交给 ChatGPT：拿到方案后回到 Pi 继续。它负责交付安全、账号身份校验，以及卡住之后的有界恢复。

<!-- section:platform-boundaries -->

BRB 是一个独立的开源本地自动化工具，通过浏览器自动化连接用户本人已登录的 ChatGPT Web 会话。BRB 与 OpenAI、Google 或 Microsoft 不存在隶属、授权、背书或官方合作关系。

BRB 不设计用于绕过验证码、使用限额、账号限制、安全挑战或其他平台保护措施—遇到它们会停止自动操作、报告原因，并把下一步交还给你。使用 BRB 访问第三方服务时，你有责任确认自己的使用方式符合相应服务条款、组织政策和适用规则。

BRB 在用户自己的计算机上驱动 Chrome/Edge，并使用用户本人已经登录的会话。BRB 不要求用户向 BRB 提供 ChatGPT 密码。

**数据流：** Pi、ChatGPT Web、BRB 与你配置的 AI provider 之间如何传递数据、本机可能持久化什么，见 [docs/data-flow.md](docs/data-flow.md)。


<!-- section:release-status -->
<!-- fact:package=@yedan1122/brb -->
<!-- fact:version=0.1.0-beta.10 -->
<!-- fact:release-status=beta-candidate -->
<!-- fact:pi-host-status=beta-candidate -->
<!-- fact:npm-status=published-beta -->

**状态：公开 beta**，版本 `0.1.0-beta.10`，已发布到 npm：`@yedan1122/brb@beta`。BRB 只支持 Pi。

## 使用 Pi

<!-- section:host-selection -->

| 使用方式 | 状态 | 接口 | 适合 |
|---|---|---|---|
| **Pi** | Beta 候选 / 主入口 | `/brb` 命令 + TUI | 完整 BRB 工作流：交接、执行、有界恢复、首次使用引导 |

网页运行时卡住时，Pi 只能处理有限的情形。协议或会话连续性一旦断了，还是要你手动运行 `/brb resume`。

## 安装

<!-- section:install -->

从 npm 安装 beta：

```bash
pi install npm:@yedan1122/brb@beta
```

## 快速开始

<!-- section:quick-start -->

```text
/brb setup          # 配置环境、登录、会话与 Git 推送策略
/brb status         # 查看状态，不发送消息
/brb ask <任务>     # 把任务发给 ChatGPT 会话
```

## 工作方式

<!-- section:how-it-works -->

```
Pi Agent ──BRB──CDP── ChatGPT 网页会话
```

## Pi 能力

<!-- section:host-support -->

| 能力 | Pi |
|---|---|
| 状态与诊断 | ✓ |
| 启动浏览器 | ✓ |
| 绑定已有会话 | ✓ |
| 账号身份匹配（A17） | ✓ |
| 安全交接与回执 | ✓ |
| 交互式首次使用引导 | ✓ |
| 自动接力循环 | ✓ |
| 网页运行时停滞恢复 | ✓ |
| 协议连续性恢复 | 手动 `/brb resume` |
| TUI 与补全 | ✓ |

## 为什么使用 BRB

- **真实 ChatGPT 会话**：BRB 不是 API 代理，它保留会话上下文与账号侧历史。
- **安全交接**：交付由 capability 闸门、发送前目标校验和交付对账保证。
- **账号身份匹配**（A17）：远端操作前，BRB 重新观察当前账号；身份不匹配即停止操作。
- **有界恢复**：恢复只增加检查，不增加权限；放弃后须由人工显式重新开始。

## 安全模型

BRB 通过 capability 登记授权；无法确认时停止操作；不保存密码；自动创建受限；默认不自动执行 Git push。详见 [docs/safety-model.md](docs/safety-model.md)。

<!-- section:auto-bind-on-unbound -->

### 未绑定 Pi 线程的首次使用引导

Pi 线程尚未绑定、而操作又依赖会话时（`ask`、`plan`、`read`、`copy`、`sources`、`start`），BRB 按 `autoCreateOnUnbound`（默认 `ask`）给出一次行内选择；显式 URL 优先。结果不明确时，BRB 记下尚未解决的创建残留，不自动重试。`/brb orphan clear <id>` 只解除本地阻断，不删除远端 ChatGPT 会话。

## 命令

输入 `/brb <空格>` 查看补全。完整列表见 [docs/commands.md](docs/commands.md)。

## 兼容性

- Node ≥18（已在 node22 验证）；Chrome/Edge + CDP；需已有 ChatGPT 账号（手动登录）；依赖 `@earendil-works/pi-coding-agent`。

## 文档

<!-- section:documentation -->

- [docs/quick-start.md](docs/quick-start.md)
- [docs/commands.md](docs/commands.md)
- [docs/safety-model.md](docs/safety-model.md)
- [docs/troubleshooting.md](docs/troubleshooting.md)
- Pi 详细参考（中文）：[docs/pi-reference.zh-CN.md](docs/pi-reference.zh-CN.md)
- 仓库：[github.com/yedan1122/brb](https://github.com/yedan1122/brb)

## 开发

[CONTRIBUTING.md](CONTRIBUTING.md) 说明 Node、Pi、测试和安全不变量。

> `package.json` 里的 scripts 用于仓库开发；`tests/` 与 `scripts/` 下的测试和工具不随 npm 包发布。要运行它们，请克隆仓库。

## 许可证

MIT — [LICENSE](LICENSE)

<!-- section:end -->

<!-- internal-doc-index:start -->
<!-- internal-doc-index:end -->