# 数据流声明（Data Flow）

本文说明 BRB 在本地 Pi Agent、ChatGPT Web、BRB 与用户配置的 AI provider 之间如何传递数据，以及哪些信息可能被持久化到本机。

**BRB 不是 ChatGPT 与用户之间的隐私代理。** 发送到 ChatGPT 的内容仍由 ChatGPT / OpenAI 按其自身条款和隐私规则处理；发送给你在 Pi 中配置的其他 AI provider 的内容，由相应 provider 处理。BRB 不替用户选择或控制这些服务的政策。

---

## 1. 核心数据流

```
用户 / Pi
   │
   │ 任务、上下文、可选附件
   ▼
BRB（本机）
   │
   │ 浏览器自动化（CDP，驱动你本人已登录的 Chrome/Edge）
   ▼
ChatGPT Web
   │
   │ 回复内容
   ▼
BRB（本机）
   │
   │ 捕获后的回复 + 最小路由元数据
   ▼
Pi Agent
   │
   │ 取决于你的工作流
   ▼
你配置的 AI provider
```

最后一步**不是每次必然发生**：只有 Pi 后续确实把内容作为模型上下文发送时才会发生。

## 2. Pi → BRB → ChatGPT

可能包含：

- 你输入的任务正文
- 当前工作流需要的上下文
- 代码或文本片段
- 你主动指定的附件
- BRB 协议 envelope

这些内容会**进入 ChatGPT Web**。请勿提交你无权交给 ChatGPT 的数据（公司机密、第三方个人信息、受合同或法规限制的内容等）。

## 3. ChatGPT → BRB

BRB 可能观察：

| 类别 | 内容 |
| --- | --- |
| 回复正文 | ChatGPT 回复文本（用于交回 Pi） |
| 路由/安全元数据 | 页面 DOM 状态、conversation URL / id、账号身份观察结果（MATCH / MISMATCH / UNKNOWN）、复制按钮与操作条状态、是否仍在生成、错误与安全挑战状态 |

**元数据用于路由与安全判断；回复正文才是内容。** 二者在诊断与日志中分开处理（见 §6–§9）。

## 4. BRB → Pi

返回给 Pi 的内容可能包括：ChatGPT 回复正文、来源与捕获方式（`via`）、轮次状态、绑定状态、诊断错误、有界恢复状态。

**一旦回复进入 Pi Agent，它就成为你当前工作流的一部分。**

## 5. Pi → 你配置的 provider（最容易被忽略的一跳）

如果 Pi 后续把 ChatGPT 返回内容放入模型上下文，则该内容**可能发送给你在 Pi 中配置的 AI provider**——可能是 OpenAI，也可能是 DeepSeek、Anthropic、Google 或其他服务。BRB 不参与、不选择、也不控制这一跳。

因此准确的说法是：

> **BRB 的控制与状态处理在本机完成；你提交的内容会发送到你实际使用的第三方 AI 服务。**

而不是"所有数据只在本机"。

## 6. 本机持久化数据

状态根目录：`~/.pi/agent/`（可用 `PI_WEBGPT_HOME` 隔离到测试目录）。

| 数据 | 路径 | 用途 | 是否包含正文 | 删除方式 |
| --- | --- | --- | --- | --- |
| 配置 | `chatgpt-web-bridge.json` | 浏览器/端口/运行参数 | 否 | 直接删除文件（会回到默认配置） |
| 绑定登记 | `chatgpt-web-bridge-bindings.json` | Pi thread ↔ ChatGPT conversation 映射 | 否 | `/brb unbind` 或删除文件 |
| 轮次运行态 | `chatgpt-web-bridge-state/` | round / checkpoint / 有界恢复 | 默认否 | `/brb kill` 后删除目录 |
| 同意记录 | `chatgpt-web-bridge-consent.json` | 远端操作的一次性授权记录 | 否 | 删除文件 |
| 孤儿记录 | `chatgpt-web-bridge-orphans.json` | 创建残留恢复 | 否 | `/brb orphan` 处理后自动清理 |
| 影子采样 | `chatgpt-web-bridge-shadow-samples.jsonl` | 交付判定质量采样（默认关闭） | 否（长度/判定字段级） | 删除文件 |

诊断日志（如有）与上表同根目录，默认**不包含**任何正文（见下节）。

## 7. 日志脱敏要求（默认）

默认日志**禁止**记录：

- ChatGPT Cookie、`Authorization` / `Bearer`、完整 request/response header
- `localStorage` token、session token、密码、验证码
- 账号 principal 原值
- 完整用户 prompt 正文、完整 ChatGPT reply 正文、完整剪贴板内容
- 上传文件 / 附件原始内容、本地文件全文

已由代码强制（`src/runtime/diagnostics.ts` → `redactForDiagnostics()`，随 A18 落地）：

- `sk-…` / `Bearer …` / `Authorization: …` → 掩码
- URL query `?token= / &api_key= …` → 掩码
- 上下文含 token/key/secret/auth 的长 hex → 掩码
- `Cookie:` / `Set-Cookie:` 头 → 掩码（B 轮新增）
- 裸 UUID / conversation id / capability hash 保留（协议身份，非内容）

测试：`tests/diagnostics-test.mjs`（含 cookie 用例）断言上述规则实际生效，而不是只写在文档里。

## 8. 标识与身份

- **conversation 标识**：诊断与日志默认不输出完整 conversation URL / id；需要时用前缀或短 hash（如 `conversation=6aaf3e86…`）。`/brb status`、`/brb bind` 等用户主动命令可显示足以辨认的信息。
- **账号 principal**：日志记录 `principal=MATCH / MISMATCH / UNKNOWN` 即可；需要区分时使用短 hash（`principal=sha256:8chars`），不默认写原值。
- **正文长度**：诊断中记录 `payloadLength=823` / `replyLength=4312` 这类**长度**，不记录正文本身。确实需要正文排障时，必须显式进入敏感调试模式，并提示"敏感调试模式可能在本机日志中记录对话内容；排障完成后请关闭并删除相关日志"。
- **本地路径**：不完整记录（如 `C:\Users\…\公司项目\客户名\secret.pdf`）；记录 `file=secret.pdf` 或 `path=<redacted>\secret.pdf` 形式，除非路径本身就是被诊断的问题。
- **网络诊断**：如未来记录网络信息，默认只允许 host / method / status / timing / resource type；不保存 Cookie、Authorization、POST body、multipart 文件内容、response body；不默认生成完整 HAR。
- **截图与完整 DOM dump**：视为高敏感诊断资产（可能包含聊天正文、账号名称、项目数据、会话列表、文件名）。默认关闭；仅用户显式触发；只在本机保存、明确路径、不自动上传。

## 9. 验收

- [x] `docs/data-flow.md` 存在且 README 有入口
- [x] 明确列出 ChatGPT 与用户配置 provider 两个第三方处理节点
- [x] 不使用"所有数据只在本机"类绝对表述
- [x] 脱敏规则由代码强制且有测试（`diagnostics-test.mjs`，含 cookie 用例）
- [x] 截图/DOM dump 仅显式开启（既有诊断设计：默认不生成）

> 本声明随产品行为变化更新；如果未来增加 telemetry、崩溃上报、云端日志或同步服务，需要重新评估数据流与相应法定义务。