# BPA Public Documentation

Authority order: current state → normative → architecture → operations → tutorial.
Plans, research, historical notes, private business sources, and local paths are excluded.

# 当前能力

> Summary: BPA 0.4 candidate 已实现、部分完成和明确未进入的能力边界。
> Authority: current-state
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/start/current-status/
> Raw: https://maplecity1314.github.io/BPA/raw/start/current-status.md
> Digest: sha256:0cd7a5d5324b4ea4f403437f1c1f3e00c5e39a5896d4ea114d42436f612a149e

> 实现基线：2026-07-30。这里描述的是仓库与自动测试已经证明的能力，不把协议设计
> 或页面 fixture 当成真实平台验收。

## 已进入运行闭环

| 能力 | 当前状态 |
| --- | --- |
| 本地控制面 | CLI、Console 和 MCP 先进行 Control Hello，再通过本机 Socket 调用 Core |
| 执行模型 | Workflow v1alpha1/v1alpha2/v1alpha3 编译到同一 IR2；计划与资产闭包随 Run 冻结 |
| 恢复 | Run Checkpoint、Inbox/Outbox、幂等结果、Lease 与 Fencing 已持久化 |
| 浏览器 | Browser Protocol v2、页面观察、主动探测、签名权限和精确标签页绑定 |
| 可信证据 | Evidence 分块、断点恢复、整体摘要、Result 引用门禁和 Evidence Link |
| 本地资产 | SHA-256 内容寻址 Blob、Source/Asset 元数据、保留策略和引用保护 |
| Dataset | 安全上传、格式校验、规范化记录、不可覆盖发布和分页读取 |
| 人工协作 | AI Review、Human Confirm、Human Action 的任务、认领、Lease 与提交 |
| 业务入口 | 只监听本机的 Operator Console、运行向导、任务中心、时间线和血缘视图 |

当前仓库门禁报告 30 个 Node、4 个 Workflow、1 个 Adapter、5 个 Assistance
Profile 和 3 个创作 Skill。整仓基线为 80 个测试文件、527 项测试通过。这些数字
是当前构建快照，不是公共 API 承诺。

## 已有基础，但仍需真实验收

- 页面 Readiness Contract 已定义并有解析测试，复杂延迟渲染、稳定采样和有限刷新
  仍需真实页面 replay。
- 多 Browser Session 和认证等级已能冻结、恢复和派发前复核，登录失效后的完整业务
  接管仍需真实登录环境验收。
- Evidence、Source、Asset 与 Export 元数据已经连通；完整参考资产包正文格式和下载
  通道仍在后续迭代。
- Operator Console 已覆盖日常入口，但真实业务的长流程、浏览器安装包 E2E 和影子
  对比尚未完成。

## 明确没有进入当前版本

- 浏览器表单修改、保存、发布等 R2+ 写动作。
- 验证码自动处理、会员权限规避、限流或风控绕过。
- 任意并行、通用回边循环和未受信代码沙箱。
- PostgreSQL、远程 Gateway、多人协作和云对象存储。
- 完整可视化 Workflow Studio。

## 如何判断一句能力描述是否可信

优先级从高到低：

1. 真实登录环境的只读验收和审计记录。
2. Chrome for Testing 或完整安装包 E2E。
3. 跨进程集成测试与崩溃恢复测试。
4. fixture/replay。
5. 单元测试。
6. 仅有 Schema、ADR 或计划。

文档中的“已实现”至少要求进入自动测试；“真实可用”还要求对应业务验收。

日常操作从[使用本地工作台](../../guides/operator-console/)开始；需要判断文档是否
代表当前事实时，可以读取[机器可读文档](../../reference/machine-readable/)中的
权威等级和实现状态。

# Workflow v1alpha1

> Summary: BPA 声明式 Workflow 的输入输出、节点图、风险与失败分支。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/workflow/v1alpha1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/workflow/v1alpha1.md
> Digest: sha256:1c782557ae8dd52f021354fe572dfc4783d71016b922dff3f2e3ee4853260ee3

**状态：v1alpha1**

v1alpha1 是保持兼容的线性/图式资产格式。新建的结构化流程优先使用
[v1alpha2 / v1alpha3](../structured/)；已有资产和 Run 不需要迁移。

Workflow 描述业务结果和节点图，不包含任意 JavaScript、`eval`、动态远程代码或未注册的浏览器动作。

## 顶层结构

```yaml
apiVersion: bpa/v1alpha1
kind: Workflow
metadata:
  id: order.export
  version: 0.1.0
  title: 导出指定日期的订单
spec:
  riskLevel: R0
  inputSchema: {}
  outputSchema: {}
  start: open_orders
  nodes: {}
```

`metadata.id` 使用稳定资产标识，`metadata.version` 使用 SemVer。已发布版本不应原地覆盖。

## 节点引用

每个节点至少包含一个固定版本引用：

```yaml
open_orders:
  use: browser.navigate@1.0.0
  with:
    url: https://example.com/orders
  timeout: 15s
  next: read_orders
```

节点可以声明 `next`，或使用 `on` 映射 `success`、`failure`、`timeout`、`rejected`、`cancelled` 与 `uncertain`。

## Retry 与 Timing

Workflow 级节点配置可以声明有限次数重试、退避和可重试错误。TimingPolicy 作为独立公共模型描述页面就绪、确定性抖动和限速边界。

Alpha 标识表示结构仍可能调整。实现方应固定完整版本，并对 Schema 变化执行兼容性测试。

Core 会把 v1alpha1 编译为与新 Workflow 相同的 `bpa.workflow-ir/2`。Run 创建后
保存 Plan Snapshot，因此后续发布新的 Workflow 或 Node 不会改变执行中的任务。

[下载 Workflow Schema](../../../reference/schemas/)

# Workflow v1alpha2 / v1alpha3

> Summary: 结构化 sequence、call、decision、foreach、Assistance 与 Browser Resource Slot。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/workflow/structured/
> Raw: https://maplecity1314.github.io/BPA/raw/models/workflow/structured.md
> Digest: sha256:493a01a15ebe0f8bb4cbb1c0116a3d12e0ddefc904d6584832691cc0cde79542

Workflow v1alpha2 使用结构化块替代任意跳转；v1alpha3 在同一执行模型上增加 Browser
Resource Slot。

## v1alpha2 Step

```text
sequence
├── call
├── decision
├── foreach
├── wait.assistance
└── terminal
```

绑定只允许 `${input...}`、`${steps..output...}`、`${item...}` 和
`${index}`。decision 使用结构化 `compare / all / any / not`，不接收表达式字符串。

## foreach

- 顺序执行。
- 最多 500 项，并有总时限。
- `itemKey` 必须稳定且唯一。
- `stop` 遇到第一项失败就停止。
- `collect` 可以收集普通失败，但 `uncertain` 始终停止。
- 输出按输入顺序聚合 succeeded、failed 和 unresolved。

## Assistance

`wait.assistance` 可以阻塞或非阻塞。阻塞任务的创建与 Run 暂停属于同一事务。Provider
不可用时，只能使用已发布 Profile 固定的升级策略。

## v1alpha3 Resource Slot

v1alpha3 的 `resourceSlots` 声明能力、Origin、认证等级和用途；Call 使用
`resourceMappings` 把 Node Requirement 映射到 Slot。Run 创建时再绑定精确 Browser
Session。

v1alpha1、v1alpha2 和 v1alpha3 都编译到 `bpa.workflow-ir/2`。已有 Run 不会因新
Workflow 版本重新编译。

# Node v1alpha1

> Summary: BPA 节点能力、运行时、风险、幂等与 Evidence 契约。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/node/v1alpha1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/node/v1alpha1.md
> Digest: sha256:6920c32ff54933e41ffaa8358f55bb7714c72e061c54a9ecdc01bcb2ea4d45b7

**状态：v1alpha1**

v1alpha1 保持兼容。需要冻结 Browser Session、Origin 与认证等级的新浏览器能力使用
[Node v1alpha2](../v1alpha2/)。

Node 是提前注册、测试和版本化的能力。Workflow 只能引用 Node，不能在运行时内嵌代码。

## 必需信息

| 分组 | 内容 |
| --- | --- |
| `metadata` | ID、SemVer、标题与说明 |
| `runtime` | `engine_builtin`、`engine_team`、`browser`、`human` 或 `composite` |
| `inputSchema` | 节点输入的 JSON Schema |
| `outputSchema` | 节点输出的 JSON Schema |
| `risk` | R0–R4、权限与浏览器域名 |
| `execution` | 默认超时、幂等类别、可重试错误与取消能力 |
| `errors` | 节点可能返回的稳定错误代码 |

## 幂等类别

```text
pure
repeatable_read
verified_write
non_repeatable
```

`verified_write` 要求动作后验证；`non_repeatable` 不得因普通超时自动重做。

## 浏览器节点

`runtime: browser` 的节点必须声明至少一个允许域名。实际执行仍需 Command 内的 Permission Grant 同时覆盖该域名和权限。

RiskSignal 可以由页面、Adapter 或 Bridge 产生。Node 的风险配置不能降低全局策略或平台阻断信号。

资源感知 Browser Node 不能通过 Single Node Run 猜测 Session；它必须进入带精确
Resource Slot 的已发布 Workflow。

[下载 Node Schema](../../../reference/schemas/)

# Node v1alpha2

> Summary: 资源感知 Browser Node 的能力、Origin、认证等级和版本冻结规则。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/node/v1alpha2/
> Raw: https://maplecity1314.github.io/BPA/raw/models/node/v1alpha2.md
> Digest: sha256:7151e67bbf670c7084dd238a3bbde117201a7f14c9311fd84b9cb8b92933fe61

Node v1alpha2 保留 v1alpha1 的输入、输出、风险、执行和错误契约，并为 Browser
Runtime 增加 `resources`。

## Browser Resource Requirement

每个 Requirement 声明：

- 当前 Node 内唯一的 key。
- 所需浏览器能力。
- 允许的 Origin。
- 最低认证等级。
- 面向操作者的用途说明。

认证等级按以下顺序收紧：

```text
anonymous < optional < authenticated < membership
```

Workflow 映射时，Slot 的能力必须包含 Requirement，Origin 不能扩大，认证等级不能
降低。

## 兼容规则

- 只有 Browser Node 可以声明 `resources`。
- Browser Node v1alpha2 必须声明至少一个资源。
- v1alpha1 Node 保持原行为，不会被推断出 Resource Slot。
- Single Node Run 不能猜测资源感知 Node 所需的 Browser Session。
- 新 Requirement 或 Adapter 行为需要新 Node 版本，不能覆盖已有版本。

资源要求属于权限边界，不应作为普通 input 让页面或模型动态填写。

# Assistance Task v1alpha1

> Summary: AI Review、Human Confirm、Human Action、Lease、Fencing 与自动继续边界。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/assistance/v1alpha1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/assistance/v1alpha1.md
> Digest: sha256:12b249949d30adc45303b7cc2430af1ab1fb1e5ceb9582e7e658cfcad6b95a6c

Assistance Task 把非确定性判断和人工动作从 Engine 中分离出来。

## 模式

| 模式 | 用途 |
| --- | --- |
| `ai_review` | 结构化分析、归类或建议 |
| `human_confirm` | 确认、修正或拒绝长期决定 |
| `human_action` | 登录、验证码、切换页面或其他必须由人完成的动作 |

## 生命周期

```text
queued → claimed → processing → completed
                         └─────→ awaiting_human → completed

queued / claimed / processing → expired | cancelled | failed
```

Claim 使用可续租 Lease 和递增 Fencing Token。Lease 过期后可重新认领，但旧 Owner
不能提交。

## AI 自动继续

- R0 Profile 可以明确允许自动继续。
- R1 还要求白名单和确定性结果验证器。
- R2+、长期决定和未来写入影响必须人工确认。
- confidence 只用于排序与审计。

自动继续必须来自已发布 Profile 的 Policy Snapshot；没有快照时默认不能继续。
Codex 通过任务队列认领工作，Core 不直接调用模型 API。

# Dataset 与 Decision

> Summary: 不可变 DatasetVersion、受限读取、Decision Candidate 与可撤销 DecisionRecord。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/data/v1alpha1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/data/v1alpha1.md
> Digest: sha256:72ec1985acb76aebe9406755b29b03f0e5200ba6049341cbca6f94f2ac5b03e2

## Dataset 导入

```text
Core-issued upload lease
→ verified content-addressed Blob
→ Dataset Profile parse
→ schema and digest validation
→ normalized records
→ atomic DatasetVersion publish
```

相同 Dataset ID + version 不能覆盖。Run 保存 DatasetRef；Runtime 通过分页、限量的
Query Port 读取记录，不接收任意文件路径。

当前本地工作台只公开经过审核的 `.xlsx` Profile。文件正文走独立上传通道，Control
只传回执和 Dataset 元数据。

## Decision Candidate 与 DecisionRecord

AI 或匹配器产生的是 Candidate，不是长期决定。只有人工确认后才能创建 active
DecisionRecord。

DecisionRecord 保存：

- 精确 scope。
- 前置摘要。
- 版本化结果值。
- 确认主体与时间。
- 可选的替代或撤销关系。

复用时必须同时匹配 scope 和 precondition digests。`superseded` 与 `revoked`
记录保留审计，但不能继续复用。

# Page Model 与 Readiness

> Summary: PageModel、ElementContract、受限 Design Mode 和 Adapter-owned Readiness Contract。
> Authority: normative
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/models/page/v1alpha1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/page/v1alpha1.md
> Digest: sha256:6edc1ee2cf6c1d7a894e66a576941791c98ab2afd0e2d1144814f4e39f742ab3

## PageModel 与 ElementContract

PageModel 描述页面状态、语义元素和精确 Adapter 关系。ElementContract 描述一个语义
意图可使用哪些稳定定位策略、前后置条件和已验证快照。

ElementContract Candidate 至少需要：

- 两个不同的脱敏页面快照摘要。
- 至少一个非 CSS 的稳定策略。
- 明确的 Origin、页面状态和预期数量。
- 无 XPath、坐标和任意脚本。

## Design Mode

Design Mode 绑定精确 Tab、Origin、Session 和最长 15 分钟 TTL。它只读、脱敏，只能
创建 PageModel、ElementContract 或 Adapter Candidate，不能发布正式资产。

复杂分页、虚拟滚动、导航恢复和未来写动作必须由审核 Adapter Handler 实现，不能由
声明式定位器替代。

## Readiness Contract

Readiness 属于精确 Adapter 发布闭包，不进入 Workflow。它只允许：

- 语义目标出现。
- DOM 在有限窗口保持安静。
- 网络在有限窗口保持安静。
- 资产数量连续多次稳定。

Contract 固定总超时、采样间隔和最多三次刷新。第一次扫描为 0 只是一条样本，不能
单独证明页面确实为空。

当前 Readiness Contract 的结构与解析已经进入代码；复杂真实页面的延迟渲染、刷新
恢复和空状态仍需要实际 replay 验收。

# Execution Event v1

> Summary: BPA 执行历史中的有序、可审计事件信封。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/execution-event/v1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/execution-event/v1.md
> Digest: sha256:16ec6bafed76e2fcbc2abcbcfcdaea52ab6af1eb61bdc3dd46decdb01bd78bd3

**状态：v1**

Execution Event 记录一次 Run 中已经发生的状态变化。事件按 `sequence` 排序，`payload` 由事件类型解释。

## 字段

| 字段 | 约束 |
| --- | --- |
| `event_id` | 事件唯一标识 |
| `run_id` | 所属 Run |
| `node_execution_id` | 可选的节点执行标识 |
| `sequence` | 从 1 开始的整数 |
| `type` | 大写下划线错误或事件代码 |
| `occurred_at` | RFC 3339 时间 |
| `payload` | 事件类型定义的数据 |

Event 是审计记录，不是重新执行任意代码的指令。消费者应按稳定事件类型处理，并保留未知类型的原始记录。

[下载 Execution Event Schema](../../../reference/schemas/)

# Evidence v1

> Summary: BPA Evidence Metadata 的分类、完整性与保留字段。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/models/evidence/v1/
> Raw: https://maplecity1314.github.io/BPA/raw/models/evidence/v1.md
> Digest: sha256:309ea25173268db09f8c6db8fa4cebf6e5a5b11a6f1757702e420bb6ff3587df

**状态：v1，Browser Evidence 传输已启用**

Evidence Metadata 描述动作前后或错误场景中的验证材料。正文与 Metadata 分开存储。

## 字段

| 字段 | 作用 |
| --- | --- |
| `evidence_id` | Evidence 唯一标识 |
| `run_id` | 所属 Run |
| `node_execution_id` | 产生 Evidence 的节点执行 |
| `kind` | DOM 摘要、截图、文件、验证结果或错误 |
| `digest` | `sha256:` 前缀的正文摘要 |
| `size` | 原始正文大小 |
| `media_type` | 可选 MIME 类型 |
| `storage_ref` | 可选存储引用 |
| `created_at` / `expires_at` | 创建和过期时间 |
| `classification` | `public`、`internal`、`confidential` 或 `restricted` |

`storage_ref` 不是公开 URL。当前 Core 只接受由本地内容寻址存储产生的受信引用；
读取 Evidence 仍需经过权限和数据分类检查。

Browser Protocol 的 Evidence 分块会分别验证每个块和完整正文的 SHA-256。Evidence
在 ACK 前由 Extension 保留，完整落盘并 ACK 后，Result 才能通过 `evidence_refs`
引用它。

Evidence 与来源、业务资产的关系由 SourceRecord、AssetRecord 和 EvidenceLink
表达。详情见[可信证据与资产](../../../control/trusted-evidence/)。

[下载 Evidence Metadata Schema](../../../reference/schemas/)

# Control Hello

> Summary: bpa.control/hello/1 的协商顺序、帧边界、错误语义和兼容策略。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/control/hello/
> Raw: https://maplecity1314.github.io/BPA/raw/control/hello.md
> Digest: sha256:1fd261c103aa230db689de418290ef9d90051a7399b9b348aedafc13131c6e6e

新 CLI、Console 和 MCP 客户端在发送业务请求前，先用
`bpa.control/hello/1` 协商应用协议、帧上限和功能位。成功后继续使用
`bpa.control/1`。

## Hello

```json
{
  "version": "bpa.control/hello/1",
  "kind": "hello",
  "requestId": "hello-01",
  "supportedApplicationProtocols": ["bpa.control/1"],
  "runtime": { "name": "example-client", "version": "0.4.0" },
  "maxFrameBytes": 524288,
  "features": ["evidence_refs", "resource_bindings"]
}
```

Server 按自身优先级选择第一个公共应用协议；帧上限取双方较小值；功能位取交集。
协商信封不携带业务参数或大型能力清单。

## 错误

| 错误码 | 含义 |
| --- | --- |
| `MALFORMED_HELLO` | 首帧无法按严格结构解释 |
| `NO_COMMON_APPLICATION_PROTOCOL` | 双方没有公共应用协议 |
| `FRAME_LIMIT_TOO_SMALL` | 协商结果无法承载最小控制信封 |

错误响应固定要求 `connection: "close"`。只关闭当前连接，不终止 Core。

## 帧边界

控制面硬上限为 512 KiB。Dataset、图片、DOM 和其他大型正文不能降级进入 Control；
它们必须走 Staging Lease 或 Browser Evidence Transport。

旧客户端只在显式 legacy adapter 范围内兼容。新客户端不能在协商失败后猜测能力并
继续发送业务帧。

# Browser Resource Binding

> Summary: Node Requirement、Workflow Slot、Run Binding Snapshot 与派发前复核。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/control/resource-binding/
> Raw: https://maplecity1314.github.io/BPA/raw/control/resource-binding.md
> Digest: sha256:1304eccc89cab78b54a80a47014dbc92a1a2d15deac6019365872caf5de5820d

资源绑定解决“一个 Workflow 需要多个浏览器来源，但恢复时不能偷偷换 Session”的
问题。

## 三层模型

```text
Node v1alpha2 Requirement
        ↓ mapped by
Workflow v1alpha3 Resource Slot
        ↓ bound at run creation
exact Browser Session Snapshot
```

Node Requirement 声明所需能力、允许 Origin、最低认证等级和用途。Workflow Slot
聚合业务层的资源需求，并将每个 Call 的本地 Requirement 映射到一个命名 Slot。

## Run 启动时冻结

- 精确 Session ID。
- Capability Manifest Digest 和能力集合。
- Origin 范围。
- 认证等级。
- 绑定时间和批准主体。

缺少任意必需 Slot 时 Run 不启动。Slot 不能从普通 Workflow input、页面内容或
Node 输出生成。

## 每次派发仍要复核

冻结不等于永远有效。Browser Provider 在每次执行前重新检查 Session、能力摘要、
Origin、认证等级和状态。失效时暂停对应 Checkpoint，并创建人工接管任务；不会自动
选择另一个 Session。

同一个 Browser Node 当前不能跨多个 Session 执行。需要多个来源时，Workflow 应拆成
多个顺序 Call，并分别映射资源槽位。

# 可信证据与资产

> Summary: Browser Evidence、SourceRecord、AssetRecord、EvidenceLink 和本地内容寻址存储。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/control/trusted-evidence/
> Raw: https://maplecity1314.github.io/BPA/raw/control/trusted-evidence.md
> Digest: sha256:fa90f46e7e62cbf5b7cd8ede941e49d62ee2807e51747f64a8c991ea7f6b0814

## 四类对象

| 对象 | 责任 |
| --- | --- |
| SourceRecord | 来源、时间、访问范围、分类和精确 Adapter 身份 |
| Evidence v1 | 某次 Node Execution 产生或使用的验证材料 |
| AssetRecord | 不可变 Blob 的摘要、媒体属性、派生关系和保留策略 |
| EvidenceLink | 把 Run/Execution/Evidence 与 Source/Asset 连接起来 |

这些对象都不复制正文。正文存放在 SHA-256 内容寻址存储，SQLite 保存元数据和引用。

## Browser Evidence 顺序

```text
evidence.begin
→ evidence.chunk × N
→ evidence.complete
→ evidence.ack(accepted=true)
→ command.result(evidence_refs)
→ result.ack
```

Evidence 必须先完整落盘并收到 ACK，Result 才能引用。每块最多 256 KiB；块摘要、
完整摘要、大小、所有权、Session 和 Fencing Token 都要匹配。

相同块可以幂等补发；相同 Evidence ID 的不同正文会被拒绝。Core 重启后根据持久化
状态返回 `next_chunk_index`。

## 存储与保留

- 单 Blob 默认最多 25 MiB。
- 单 Run 上限 2 GiB。
- 本地总存储达到 10 GiB 时告警，不静默删除。
- restricted/confidential 页面材料默认 24 小时。
- 未引用的公开研究资产默认 30 天。
- 被有效资产包引用的 Asset 在引用解除前不能删除。

`storageRef` 由 Core 产生，是不透明引用，不是调用方路径或公开 URL。

# Browser Protocol v2

> Summary: Gateway、Native Host 与 Extension Bridge 之间的消息边界和完整生命周期。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/browser/v2/
> Raw: https://maplecity1314.github.io/BPA/raw/browser/v2.md
> Digest: sha256:f9d04697ce0f30d482f64140c1fc3e4c0d820b2d887d18d241de52e2ef9165c8

**状态：已确认 v2，页面观察与定向绑定已启用**
协议族：`bpa.browser/2`
Schema 版本：`2.0.0`

Browser Protocol v2 连接 Browser Gateway 与 Extension Bridge。首个 Transport 是 Chrome Native Messaging，但 Workflow、Node 和执行语义不依赖具体 Transport。

## 组件边界

### Browser Gateway

- 建立与恢复 Session。
- 调度经过编译和授权的 Command。
- 维护 Gateway → Bridge 的单调序列。
- 接收结果、证据和风险信号。

### Native Host

- 校验 Chrome 传入的精确 Extension Origin。
- 处理 Chrome stdio framing。
- 将完整消息转发到受限的 Local Core 端点。

Native Host 不解释 Workflow，不执行 Node，也不修改权限或业务参数。

### Extension Bridge

- 维护 Bridge → Gateway 的单调序列。
- 校验 Session、Permission Grant、Fencing Token 与页面上下文。
- 调用已经注册的浏览器能力。
- 先持久化 Result，再等待 Gateway 确认。

## 固定信封

每条消息都包含：

| 字段 | 含义 |
| --- | --- |
| `protocol` | 固定为 `bpa.browser/2` |
| `version` | 当前 Schema 版本 `2.0.0` |
| `message_id` | 全局唯一；相同 ID 表示重复投递 |
| `session_id` | 新会话使用 `new`，其余使用已建立 Session |
| `seq` | 每个方向独立、单调递增 |
| `sent_at` | RFC 3339 UTC 时间 |
| `type` | 消息类型 |
| `trace_id` | 仅用于关联追踪 |
| `payload` | 按 `type` 严格校验 |

应用消息上限为 512 KiB。未知字段一律拒绝；普通 Result 不允许内嵌完整 DOM、截图或文件。

## Session 生命周期

```text
DISCONNECTED
  ↓ Native Port connected
HELLO_REQUIRED
  ↓ session.hello
NEGOTIATING
  ├─ incompatible → session.error(fatal) → CLOSED
  └─ session.welcome
       ↓
CAPABILITY_REQUIRED
  ↓ capability.report
READY
  ├─ heartbeat timeout → DISCONNECTED
  ├─ Native Port close → DISCONNECTED
  ├─ capability change → capability.report → READY
  └─ resume accepted → READY
```

Resume Token 最长有效 24 小时。恢复成功后立即轮换，设备撤销时同步失效。Gateway 从未确认的 Command Sequence 开始重放。

恢复沿用稳定的 Browser Instance 身份并重新解析当前标签页。临时 Session ID 和 Tab ID
不能作为长期配置；旧 Binding 在重启或 page epoch 变化后进入 `needs_rebind`。

## 页面观察与资源绑定

Session 就绪不等于页面可执行。Content Script 加载、导航、SPA 路由、认证上下文变化和
标签页离开都会触发 Adapter observer 探测。Core 只看到通用页面事实和不可解析的认证
上下文摘要，并冻结 Browser Instance、Tab、Origin/path、capability、revision 与 page
epoch。命令只能发往这个确切标签页，不回退到当前活动标签页。

## Command 生命周期

```text
QUEUED
  ↓ command.dispatch
DELIVERED
  ├─ command.ack(accepted=false) → REJECTED
  └─ command.ack(accepted=true) → ACCEPTED
       ↓
EXECUTING
  ↓ command.result
RESULT_PENDING_ACK
  ↓ result.ack(accepted=true)
TERMINAL
```

`command.ack` 只表示接收。Bridge 必须先持久化 Result，再发送；收到 `result.ack` 后才能删除正文。

如果 Result 引用 Evidence，完整顺序还包括：

```text
evidence.begin → chunk → complete → evidence.ack
→ command.result(evidence_refs) → result.ack
```

未完整、跨 Run、跨 Node Execution 或旧 Fencing Token 的 Evidence 不能推进 Engine。

继续阅读：[消息参考](./messages/) · [安全边界](./security/) · [Timing 与 Risk](./timing-and-risk/)

# 消息参考

> Summary: Browser Protocol v2 的页面观察、探测、命令和确认语义。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/browser/v2/messages/
> Raw: https://maplecity1314.github.io/BPA/raw/browser/v2/messages.md
> Digest: sha256:9fbb2ba5e6342d371fd414b6f0440acba5f5d39634e91206b1271825be72df26

v2 使用严格消息联合。Gateway → Bridge 与 Bridge → Gateway 使用独立序列空间；同一方向的非重复消息必须严格大于已接受序号。

## Session 与能力

| 类型 | 方向 | 作用 |
| --- | --- | --- |
| `session.hello` | Bridge → Gateway | 发起新会话或携带恢复信息 |
| `session.welcome` | Gateway → Bridge | 选择协议、下发公钥与 Resume Token |
| `session.resume` | Gateway → Bridge | 告知恢复是否接受及重放起点 |
| `capability.report` | Bridge → Gateway | 声明节点、版本、风险和权限 |
| `session.error` | Gateway → Bridge | 返回协议或会话级错误 |

新会话固定使用 `session_id: "new"` 与 `seq: 0`。恢复请求携带上次 `resume_token` 和 `last_acked_command_seq`。

## 页面观察与主动探测

| 类型 | 方向 | 作用 |
| --- | --- | --- |
| `page.observation` | Bridge → Gateway | 上报标签页通用事实、认证上下文摘要、revision 与 page epoch |
| `page.probe.request` | Gateway → Bridge | 请求对确切标签页执行短时探测 |
| `page.probe.result` | Bridge → Gateway | 返回探测是否完成以及对应 observation revision |

页面观察不是 Workflow 的期望值。只有 Adapter observer 实际读取到的事实才能上报；
重复的同语义 ready 只刷新观察时间，导航、文档替换或认证上下文变化才推进 epoch。

## Command 与结果

| 类型 | 方向 | 作用 |
| --- | --- | --- |
| `command.dispatch` | Gateway → Bridge | 下发节点、输入、权限和执行边界 |
| `command.ack` | Bridge → Gateway | 确认是否接收 Command |
| `command.result` | Bridge → Gateway | 返回最终状态、输出和 Evidence 引用 |
| `result.ack` | Gateway → Bridge | 确认 Result 已接受 |

Result 状态只能是：

```text
succeeded | rejected | failed | timed_out | cancelled | uncertain
```

`uncertain` 表示系统无法证明写动作是否生效。它是需要人工核验的终态，不是可安全重试的普通失败。

## Cancel 与心跳

| 类型 | 方向 | 作用 |
| --- | --- | --- |
| `cancel.request` | Gateway → Bridge | 表达停止意图 |
| `cancel.ack` | Bridge → Gateway | 确认收到 Cancel 并说明动作是否开始 |
| `cancel.effective` | Bridge → Gateway | 返回 `cancelled` 或 `uncertain` |
| `heartbeat.ping` | 双向 | 探测连接 |
| `heartbeat.pong` | 双向 | 回应相同 nonce |

Cancel 不是回滚。写动作已经开始且无法确认副作用时必须返回 `uncertain`。

## Evidence

| 类型 | 方向 | 作用 |
| --- | --- | --- |
| `evidence.begin` | Bridge → Gateway | 声明 Evidence 元数据和分块信息 |
| `evidence.chunk` | Bridge → Gateway | 发送一个 Base64 数据块 |
| `evidence.complete` | Bridge → Gateway | 声明全部块已发送 |
| `evidence.ack` | Gateway → Bridge | 确认接收或要求从指定块继续 |

原始块大小为 256 KiB。每个块和完整 Evidence 都使用 SHA-256 校验。

完整字段与示例见[规范消息样例](../../../reference/examples/)。

# 安全边界

> Summary: Permission Grant、Ed25519、Fencing Token 与不可信页面输入的约束。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/browser/v2/security/
> Raw: https://maplecity1314.github.io/BPA/raw/browser/v2/security.md
> Digest: sha256:56066a1c95efeacbad3e93a679eba346f4b5eafa3ed01308a4681f391c1b950a

Browser Protocol 把页面视为不可信输入。Bridge 不接受页面、Content Script 或远程调用方自报权限。

## Permission Grant 是完整权限快照

每个 Command 内嵌当前节点的最小权限快照，包括：

- 权限集合与允许的域名。
- 风险等级与有效期。
- Run、Node Execution、Node 版本和 Fencing Token。
- 签名密钥标识、Grant 摘要与授权签名。

Core 对规范化 JSON 计算 SHA-256 `grant_digest`，再使用 Ed25519 私钥生成 `authorization_tag`。`session.welcome` 下发当前公钥、算法和 `key_id`。

Bridge 必须同时验证摘要、签名、有效期、域名、风险等级、节点版本和 Command 绑定。任一字段变化都必须拒绝，不能降级为“仅引用可信”。

## Fencing 防止旧执行推进状态

Command、ACK、Result 和 Cancel 都绑定当前 `fencing_token`。旧 Token 的结果可以保留为审计记录，但不能推进 Workflow。

Fencing 解决的是过期执行者问题，不代替幂等键，也不证明页面动作未发生。

## 页面验证发生在动作之前

Bridge 在执行前重新检查：

1. Deadline 是否仍有剩余时间。
2. 冻结的确切 Tab、Origin、Observation Revision 与 Page Epoch 是否匹配。
3. Permission Grant 是否覆盖目标域名和动作。
4. 页面是否稳定，是否出现验证码、登录或风险控制。
5. Timing Policy 的等待是否会越过 Deadline。

Blocking Risk Signal 必须停止动作并返回 `rejected`。协议不允许尝试绕过验证码、登录、二次认证或平台风控。

对于 Workflow v1alpha3，Gateway 还会核对 Command 所需的精确 Browser Instance、
Tab、Capability Digest、Origin/path、认证上下文、Observation Revision 与 Page Epoch。
任一事实与冻结 Binding Snapshot 不一致时，Command 不会被派发到当前活动页或其他
“看起来可用”的 Session。

## Evidence 与业务结果分离

普通 Result 只携带结构化输出和 `evidence_refs`。截图、文件或较大的验证材料通过 Evidence 分块传输，正文与 Metadata 分开保存。

Evidence 在完整 ACK 前保留在 Bridge 本地；Result 在 Result ACK 前保留。Core 只有
在 Evidence 已持久化、所有权与当前执行一致时才接受引用。

Console 文件使用另一条受限本机 Staging 通道。控制面只携带一次性租约和不可变上传
回执，不接收浏览器提交的最终路径。

# Timing 与 Risk

> Summary: TimingPolicy 的有界等待与 RiskSignal 的明确阻断语义。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/browser/v2/timing-and-risk/
> Raw: https://maplecity1314.github.io/BPA/raw/browser/v2/timing-and-risk.md
> Digest: sha256:068f667a92922df8395ab60094c3fb12ea0318d9120524477b1ed514b0d5c0ba

Browser Protocol v2 允许 `command.dispatch` 携带已经由 Compiler 解析的 `timing_policy`，并允许 `command.result` 返回结构化 `risk_signals`。

这些字段不会授权新动作，也不能扩大 Permission Grant。

## TimingPolicy

TimingPolicy 可以定义四类有界行为：

| 分组 | 作用 | 主要边界 |
| --- | --- | --- |
| `readiness` | 等待页面就绪并保持稳定 | 超时不超过 120 秒 |
| `dispatchJitter` | 在有限区间内分散调度 | 最大 10 秒 |
| `retryBackoff` | 固定或指数退避 | 最大等待 120 秒 |
| `rateLimit` | 按域名、认证上下文或 Tab 限速 | 队列上限 120 秒 |

所有实际等待都受 Command Deadline 约束。若等待会越过 Deadline，Bridge 不得继续执行。

抖动必须由确定性种子产生，才能在重放、审计和测试中得到相同结果。TimingPolicy 不是模拟真人操作的随机脚本。

## RiskSignal

RiskSignal 使用明确的代码、类别、严重级别和来源：

```text
CAPTCHA_REQUIRED
RATE_LIMITED
RISK_CONTROL
SESSION_EXPIRED
AUTH_REQUIRED
PAGE_CONTEXT_CHANGED
```

`severity: "blocking"` 表示当前动作必须停止。`warning` 可以记录并返回，但是否继续仍要满足权限、页面上下文和 Deadline。

来源只能是 `page`、`adapter` 或 `bridge`。可重试的限速信号可以携带 `retry_after_ms`，但这个建议值仍受 TimingPolicy 和 Deadline 限制。

## 不允许的行为

- 通过随机等待规避平台检测。
- 在验证码或登录失效后继续写操作。
- 把 TimingPolicy 当作权限。
- 因为收到 `RATE_LIMITED` 就无限重试。
- 在 Page Epoch 已变化时沿用旧元素引用。

机器定义见 [Timing Policy Schema](../../../reference/schemas/) 与 Risk Signal Schema。

# JSON Schema

> Summary: BPA 协议与公共模型的机器可读 JSON Schema 下载。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/reference/schemas/
> Raw: https://maplecity1314.github.io/BPA/raw/reference/schemas.md
> Digest: sha256:907b1cbc5b51196dc15aec228ff3d03cd0a8c54e22fb62659fbecbd780e1a848

这里列出的文件由构建过程从 `packages/schemas/schema` 白名单复制。发布文件必须与仓库源文件字节一致。

## 使用方式

Schema 使用 JSON Schema Draft 2020-12。Browser Protocol 对未知字段严格失败，并通过绝对 `$id` 引用 Permission Grant、Timing Policy 和 Risk Signal。

`$id` 是规范身份，不保证可以直接作为下载 URL。外部工具应使用本页提供的 `/specs/` 地址获取文件，同时保留 Schema 内原始 `$id`。

## 稳定性

- `v1`：字段语义与安全边界已经确认；不兼容变化需要新 Major。
- `v1alpha1`：允许结构调整；实现方必须固定版本并执行兼容测试。

本网站不会自动发布目录中的新 Schema。每个新增文件都必须显式加入公开白名单。

# 规范消息样例

> Summary: Browser Protocol v2 与 Control Hello 的中性、可下载规范样例。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/reference/examples/
> Raw: https://maplecity1314.github.io/BPA/raw/reference/examples.md
> Digest: sha256:cfa44f449ce9781d172f7838df6dba7ece07ffeaf89b41405ef5a4d9d361f74b

Browser 样例覆盖 Session、Capability、Command、Result、Cancel、Heartbeat、
Evidence 与恢复消息。Control 样例覆盖 Hello、Welcome 和不兼容响应。公开示例使用
中性标识，不包含业务适配器、真实来源或凭据。

  下载 Browser 消息

  下载 Control Hello

## Control Hello

```json
{
  "version": "bpa.control/hello/1",
  "kind": "hello",
  "requestId": "hello-01",
  "supportedApplicationProtocols": ["bpa.control/1"],
  "runtime": {
    "name": "example-client",
    "version": "0.4.0"
  },
  "maxFrameBytes": 524288,
  "features": ["evidence_refs", "resource_bindings"]
}
```

## Session Hello

```json
{
  "protocol": "bpa.browser/2",
  "version": "2.0.0",
  "message_id": "message-hello",
  "session_id": "new",
  "seq": 0,
  "sent_at": "2026-07-27T06:00:00.000Z",
  "type": "session.hello",
  "trace_id": "trace-session",
  "payload": {
    "browser_instance_id": "browser-example-01",
    "extension_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "extension_version": "0.2.0",
    "supported_protocols": ["bpa.browser/2"],
    "features": ["page_observation_v2", "exact_tab_binding_v2", "active_page_probe_v1"],
    "last_acked_command_seq": 0
  }
}
```

## Command Dispatch

```json
{
  "protocol": "bpa.browser/2",
  "version": "2.0.0",
  "message_id": "message-command",
  "session_id": "session-01",
  "seq": 2,
  "type": "command.dispatch",
  "payload": {
    "command_seq": 1,
    "workflow_id": "example.page-context-observe",
    "node": {
      "id": "browser.page.context.read",
      "version": "1.1.0"
    },
    "fencing_token": 1,
    "permission_grant": {
      "domains": ["https://example.com"],
      "risk_level": "R0"
    }
  }
}
```

上面的节选只用于阅读，不是可直接校验的完整消息。下载文件包含所有必需字段，并在仓库测试中逐条通过正式 Schema 与 Session Guard。

# 机器可读文档

> Summary: BPA 的 llms.txt、完整文本索引、结构化目录和 Raw Markdown 入口。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/reference/machine-readable/
> Raw: https://maplecity1314.github.io/BPA/raw/reference/machine-readable.md
> Digest: sha256:74b097351ae4fe378c86e99e394dde0eaff850fa73ca853659237aa9b7bcc86d

BPA 为搜索引擎、Codex、Claude 和其他文档消费者提供明确的机器入口，不要求模型
通过文件名或页面视觉猜测权威状态。

## 入口

| 文件 | 用途 |
| --- | --- |
| [`llms.txt`](../../llms.txt) | 精简阅读顺序、关键页面和状态 |
| [`llms-full.txt`](../../llms-full.txt) | 按权威顺序合并的公开正文 |
| [`docs-index.json`](../../docs-index.json) | URL、受众、权威、实现状态和 SHA-256 |
| [`sitemap-index.xml`](../../sitemap-index.xml) | 搜索引擎页面发现 |
| [`robots.txt`](../../robots.txt) | 项目路径下的抓取策略 |

每个公开页面还提供 `/raw/.md`，并在 HTML `` 中声明
`rel="alternate"` 的 Markdown 地址。

## 权威顺序

```text
current-state
→ normative
→ architecture
→ operations
→ tutorial
→ plan
→ research
→ historical
```

公开 `llms-full.txt` 不包含内部计划、研究、历史归档、真实业务域名、本机路径或登录
材料。`docs-index.json` 的摘要针对原始公开文档正文，构建结果可重复验证。

## 关于 robots.txt

当前站点部署在 GitHub Pages 项目子路径 `/BPA/`。项目内的 `robots.txt` 可以表达
意图并链接 Sitemap，但不是 `maplecity1314.github.io` 域名根级 robots 策略。
因此机器目录以 `llms.txt` 和 `docs-index.json` 为准。

# 版本与兼容

> Summary: BPA 协议族、Schema 版本、Alpha 模型和兼容性规则。
> Authority: normative
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/reference/versioning/
> Raw: https://maplecity1314.github.io/BPA/raw/reference/versioning.md
> Digest: sha256:cf914511c0e8f6389aaea1e9014132a5d8b628e19060533f944312abdc2bdf5c

## Protocol 与 version

`protocol` 表示不兼容的协议族和 Major，例如 `bpa.browser/2`。`version` 是该 Major 内的完整 Schema 版本，例如 `2.0.0`。

连接双方先协商协议族，再按完整 Schema 校验每条消息。

## v2 兼容规则

- 未知字段严格失败，不以猜测方式兼容。
- 新增消息或字段需要发布新的完整 Schema 版本，并通过双端兼容测试。
- 删除字段、改变既有含义或放宽安全约束必须升级 Major。
- Permission Grant、Fencing、Deadline 与风险阻断不能通过 Minor 版本降级。

## Alpha 模型

当前 Workflow 支持 `bpa/v1alpha1`、`bpa/v1alpha2` 和 `bpa/v1alpha3`；Node
支持 `bpa/v1alpha1` 和 `bpa/v1alpha2`。Alpha 模型可以调整字段和约束；消费者
必须固定所支持的版本，不应把它们宣传为稳定接口。

- Workflow v1alpha2 引入结构化 sequence、decision、foreach 和 Assistance。
- Workflow v1alpha3 引入 Browser Resource Slot。
- Node v1alpha2 引入 Browser Resource Requirement。
- Source、Asset、Evidence Link、Dataset、Decision、Assistance 与页面模型仍是
  v1alpha1。

## 运行版本固定

一次 Run 创建后，应固定 Workflow、Node、协议和能力版本。发布新版本不会改变已经运行的任务。

v1alpha1/v1alpha2/v1alpha3 Workflow 都编译为 `bpa.workflow-ir/2`。IR 标识不随源
Workflow Alpha 版本变化；Run 恢复使用保存的 IR2 和资产闭包。

## 公共文档基线

当前文档以 2026-07-31 的已确认 Browser Protocol v2、Control Hello 和资源/证据
协议边界为基线。页面状态与下载 Schema 必须一致；网站解释不能覆盖机器规范。

## 兼容矩阵

| Producer | 接受的源版本 | 冻结形式 |
| --- | --- | --- |
| 新 CLI/MCP/Console | `bpa.control/hello/1` → `bpa.control/1` | 协商后的帧上限与功能快照 |
| 旧 Workflow | v1alpha1 / v1alpha2 | IR2 Plan Snapshot |
| 资源感知 Workflow | v1alpha3 | IR2 + Resource Binding Snapshot |
| 旧 Node | v1alpha1 | 不可变 Node Closure |
| 资源感知 Node | v1alpha2 | Requirement + Node Closure |
| Browser Runtime | `bpa.browser/2@2.0.0` | Session、页面观察、定向 Command 和 Evidence 状态 |

已有 Run 不会自动获得新的 Resource Slot、Adapter Readiness 或资产版本。

# 模块与边界

> Summary: BPA Core、编译器、执行引擎、Runtime Provider、Gateway、Adapter 与应用层的依赖边界。
> Authority: architecture
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/platform/architecture/
> Raw: https://maplecity1314.github.io/BPA/raw/platform/architecture.md
> Digest: sha256:0e8fd73017bd5247363667864ac97862e61d0e0cfe5b1db8b995d0ef54d21bf9

## 总体结构

```text
Apps
├── CLI
├── Operator Console
├── MCP Server
├── Local Core
├── Native Host
└── Extension
        │
        ▼
Control / Browser Protocol
        │
        ▼
Platform packages
├── schemas
├── compiler → workflow-ir
├── engine → node-runtime
├── assistance-core
├── dataset-core
├── evidence-core / asset-core / source models
├── persistence ports
└── gateway-core / browser-bridge
        │
        ▼
Adapters and reviewed runtime handlers
```

Apps 负责组合、I/O 和用户入口，不保存平台规则。通用包不能反向导入 App。

## 关键模块

| 模块 | 责任 |
| --- | --- |
| `schemas` | JSON Schema、生成类型和严格校验器的唯一事实来源 |
| `compiler` | 校验 Workflow、固定 Node 引用并生成 IR2 |
| `workflow-ir` | Scope、Execution Identity、结构化步骤和资产闭包 |
| `engine` | 确定性调度、暂停、恢复、重试、foreach 和状态推进 |
| `node-runtime` | Runtime Invocation/Outcome 与 Provider Registry |
| `assistance-core` | AI/人工任务、Lease、提交和自动继续边界 |
| `dataset-core` | Dataset 发布与受限记录读取 |
| `evidence-core` | Evidence 传输状态、块摘要和执行所有权 |
| `asset-core` | Blob/Asset 摘要、保留与引用约束 |
| `persistence` | Port 与原子 UoW；SQLite 是本地实现 |
| `gateway-core` | 浏览器 Session、签名、序列与协议门禁 |
| `page-model` | PageModel、ElementContract、Design Mode 生命周期和验证 |

## Engine 刻意不知道什么

Engine 不依赖 SQLite、Chrome、MCP、具体 Adapter 或业务领域。它只消费冻结的 IR2
和 Runtime Outcome。新增 Runtime 应通过 Provider Registry 注册，而不是继续扩大
Engine 内的条件分支。

## 业务逻辑放在哪里

- 平台页面定位和复杂交互只进入对应 Adapter。
- 领域匹配、证据等级和报告规则进入领域包或受信 Team Handler。
- Workflow 只组合已发布能力。
- Console 只做视图和输入，不直连数据库。
- Team Worker 不直连 Core 数据库，只通过受限调用获取输入并返回结构化结果。

这种边界让真实业务可以验证通用平台，但不会把 BPA 退化成一个不可维护的单站脚本。

# 执行、恢复与幂等

> Summary: IR2 计划快照、事务边界、Inbox/Outbox、Fencing 与不确定终态。
> Authority: architecture
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/platform/runtime-recovery/
> Raw: https://maplecity1314.github.io/BPA/raw/platform/runtime-recovery.md
> Digest: sha256:3c350d9b2a9560537413d2c06bdf46b0efa8ab5cb88da878cff9f6a1a017af0a

## 创建 Run 时冻结什么

新 Run 原子保存：

- 规范化 IR2 JSON 与摘要。
- Workflow 源摘要、风险快照和精确资产闭包。
- 初始 Checkpoint、Event 和必要的 Outbox。
- Workflow v1alpha3 所需的 Browser Resource Binding Snapshot。

恢复时读取保存的计划，不重新编译当前仓库中可能已经变化的资产。

## 事务边界

状态、Event、幂等记录和跨进程投递意图必须进入同一 Unit of Work。跨进程不使用
分布式事务，而采用：

```text
local state change + Outbox
→ at-least-once delivery
→ Inbox deduplication
→ CAS state transition
```

`expected_revision` 防止并发覆盖；Fencing Token 防止过期执行者提交；幂等键防止
相同业务结果重复应用。三者解决的问题不同，不能互相替代。

## foreach 与人工暂停

foreach 当前按顺序执行，最多处理冻结上限内的条目。`collect` 可以收集普通失败后
继续，但 `uncertain` 必须停止。创建阻塞 Assistance Task 与暂停 Run 属于同一事务；
任务提交通过 Inbox 幂等唤醒原 Checkpoint。

## 为什么需要 uncertain

当写动作已经开始，但系统无法证明页面是否接受了副作用时，既不能标记成功，也不能
当作普通失败自动重试。`uncertain` 是需要人工核验的终态。

当前公开能力仍以只读 R0/R1 为主，但保留这一状态可以防止未来写节点采用危险的
“超时即重做”逻辑。

## 当前支持与拒绝

已支持顺序、结构化 decision、顺序 foreach、有限重试、人工等待、取消和恢复。
任意并行、通用 paginate、任意回边与无上限循环会在编译期拒绝。

# 业务工作台

> Summary: 本地 Operator Console 的入口、安全会话、运行向导和当前功能范围。
> Authority: architecture
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/platform/operator-console/
> Raw: https://maplecity1314.github.io/BPA/raw/platform/operator-console.md
> Digest: sha256:3550ae2381112194774ab7879a848e5ff7773d3bfbd22d91e9c000162ab317ab

Operator Console 是业务人员的主要入口；CLI 保留给发布、运维和高级诊断。

## 启动与安全会话

```text
CLI launches temporary console host
→ binds a random 127.0.0.1 port
→ opens a one-time URL fragment token
→ exchanges it for an HttpOnly, SameSite=Strict session
→ console host calls Core through the local Control socket
```

Console 不监听局域网，不启用 CORS，不直连 SQLite。Host、Origin、CSRF 和严格 CSP
都在服务端检查。

## 当前页面

- 系统健康与 Browser Session 状态。
- 已发布只读 Workflow 的启动向导和资源槽位绑定。
- Run 时间线、当前步骤与业务化状态。
- “无需监管 / 请关注 / 需要操作”任务中心。
- Dataset 安全上传、校验与不可变发布。
- Evidence、Source 和 Asset 血缘查看。
- Export 元数据与报告入口。

## 文件不会经过控制协议

浏览器先申请一次性 Staging Lease，再把正文发送到权限受限的独立本机 Socket。
Core 校验大小、摘要、MIME 和用途后转入内容寻址存储。Dataset 导入只引用不可变
上传回执，不接受浏览器提交的本地路径。

## 当前限制

正式资产发布仍需 CLI 人工确认。Console 不提供 R2+ 写授权，也不会自动处理登录、
验证码或平台风险控制。完整 Export 正文下载仍属于后续能力。

面向业务人员的操作顺序见[使用本地工作台](../../guides/operator-console/)；启动、
资源绑定、人工任务和恢复分别有独立指南，不需要先阅读控制协议。

# AI 创作与发布边界

> Summary: Codex 如何搜索能力、生成 Workflow/Node Candidate，并保持人工发布边界。
> Authority: architecture
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/platform/ai-authoring/
> Raw: https://maplecity1314.github.io/BPA/raw/platform/ai-authoring.md
> Digest: sha256:85859dbd97adb4b40f7ffbe792ad9f8488a08951147e7430c89611158f0e13c2

AI 在 BPA 中负责搜索、组合、补充候选和解释缺口，不直接驱动浏览器，也不能发布
正式资产。

## 当前创作链

```text
ScenarioSpec
→ Authoring Session
→ Catalog / CapabilityGap
→ 人工授权 Design Mode
→ Evidence-backed PageSnapshot
→ PageModel / ElementContract Candidate
→ Candidate Bundle
→ 可验签 tar
→ 人工审查与发布
```

### Workflow 与 Node

- `catalog_search`：按能力、平台、输入输出、风险和权限搜索资产。
- `workflow_gen`：生成增量 Workflow Draft、测试和能力缺口。
- `workflow_validate`：使用正式 Schema 和 Compiler 验证。
- `workflow_simulate`：执行无副作用模拟。
- `artifact_diff`：比较 Candidate revision。
- `node_gen`：生成 Node Candidate、骨架、契约测试和权限报告。
- `node_requirement_create`：记录尚不存在的能力需求。

### 页面证据与候选

- `authoring_session_create/get/apply`：固定业务目标并使用 CAS 增量推进。
- `design_mode_start/stop`：核验或停止 Console 已批准的精确授权；MCP 不能批准。
- `design_snapshot_capture`：通过已发布只读 Node 捕获，并在 Evidence 落盘后固化
  PageSnapshot。
- `design_snapshot_query`：按 role/text 查询，每次最多返回 200 个不可信语义节点。
- `page_candidate_validate/gen`：在至少两个页面状态上校验后保存 Candidate；简单读取
  同时生成 CAS-backed 规范文件和实现计划。
- `candidate_bundle_validate/save/export`：验证完整闭包并导出确定性 tar。

## Candidate 不是 Published Artifact

AI 生成的内容只能进入 Candidate。正式发布要求：

1. Schema 与编译器通过。
2. Node 和 Adapter 使用精确版本。
3. 权限、风险、超时和失败语义完整。
4. 契约测试、fixture 或 replay 通过。
5. 候选包中的文件、风险报告、验证报告和依赖摘要完全闭合。
6. 人工通过 CLI 明确确认发布。

`bpa candidate inspect` 用于查看本地候选，`bpa candidate export` 生成只写入 BPA
数据目录的 tar，`bpa candidate verify` 可离线检查 tar header、manifest 和逐文件
SHA-256。导出不会把 patch 应用到仓库。

Workflow 不能包含 selector、XPath、坐标、任意 JavaScript 或页面实现细节。
选择器只属于审核后的 Adapter。

## 快速定位页面元素

PageModel 和 ElementContract 负责描述语义元素。受限 Design Mode 只能在固定 Tab、
Origin、Session 和 TTL 内生成 Candidate，并要求多个页面状态和非 CSS 稳定信号。

扩展会先裁剪、限量和脱敏语义节点。Core 不只信任 Browser Result，还会重新读取
CAS Evidence，核对页面绑定、Blob、快照和节点摘要。页面正文始终是数据，不能提高
风险、扩展权限、改变 ScenarioSpec 或要求执行代码。

当前 Authoring Session、Design Mode、快照、Page Candidate 和 Candidate Bundle
工具已经进入代码；既有电商 Adapter replay 已作为标准答案回归。第二个真实平台仍
需要用户对两个代表性页面状态逐次授权，因此整体继续标记为 `partial`，不应描述成
完整 Studio 或已发布的新平台能力。

# 数据与保留

> Summary: 本地数据分类、内容寻址存储、上传安全、删除约束与审计。
> Authority: operations
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/operations/data-security/
> Raw: https://maplecity1314.github.io/BPA/raw/operations/data-security.md
> Digest: sha256:57f82aad52856f58afd61b8f9455ada146d15ab8e8b2cb4505565fe0e40fc1d1

## 默认本地

当前版本使用 SQLite 保存状态和元数据，使用本地内容寻址目录保存大型正文。没有
PostgreSQL、云对象存储或远程 Gateway。

## 分类

```text
public
internal
confidential
restricted
```

分类决定读取权限和默认保留期。Runtime 可以把 confidential/restricted 收敛为
`sensitive`，但不能反向抹掉原始分类。

## 上传边界

- 调用方不能指定最终路径。
- 文件名、URL、MIME 和路径都视为不可信输入。
- Staging Lease 一次性、限时、限大小，并绑定用途。
- Core 重新计算 SHA-256；摘要不匹配时拒绝。
- 符号链接、路径穿越和非普通文件不进入受信读取。

## 删除

保留任务只处理到期且不再被有效引用的对象。进入有效资产包、Export 或 Evidence
关系的 Asset 不能静默删除。显式删除必须记录 Audit。

卸载 Runtime 默认保留业务数据；清理数据需要独立、明确的破坏性操作。

# 安装与升级边界

> Summary: 固定 Node.js 运行时、生产闭包、SQLite Migration、健康检查与安全回滚。
> Authority: operations
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/operations/runtime/
> Raw: https://maplecity1314.github.io/BPA/raw/operations/runtime.md
> Digest: sha256:c729d7a33f3627fd4cefc5bb12bd39814f8624ffd451d8be43f4a23c20f9ed00

## 生产闭包

桌面端本地包包含固定 Node.js 24、Core、CLI、Native Host、MCP、Team Worker、
Extension、Operator Console、正式 Schema/资产、SBOM 和逐文件摘要。

生产 allowlist 不包含完整源码、开发依赖、缓存、测试、个人 Skill 或用户文件。

## 升级

```text
checkpoint SQLite
→ create backup
→ run append-only migrations on a copy
→ verify integrity
→ install new immutable runtime
→ atomically switch current pointer
→ health check Core / DB / Socket / Host / Extension
```

Migration 失败时不能切换版本。健康检查失败可以恢复旧 Runtime；只有在确认新版本
没有业务写入时才能恢复数据库快照。

## 回滚

不提供 down migration。旧 Runtime 如果不认识新数据库 Schema，应明确拒绝启动，
而不是用旧代码写入新表结构。安装器保留上一版本和备份，以便在兼容范围内恢复。

macOS arm64 是已验证基线；Windows 11 x64 已进入 CI 原生构建与当前用户安装的
RC 候选阶段。Windows 真机 Chrome 与真实只读 Workflow 验收完成前，不应把它写成
正式稳定支持。签名、公证、SmartScreen 声誉、商店或企业策略分发不属于当前候选
闭环。

# 正式资产发布

> Summary: 验证并人工发布 Workflow、Node、Adapter、Profile、Policy 和页面资产。
> Authority: operations
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/operations/publishing/
> Raw: https://maplecity1314.github.io/BPA/raw/operations/publishing.md
> Digest: sha256:deaa09885328da486a60db4f44b39b003adb79ab2ec4e3578b7ef126e3fcd590

正式发布是人工治理动作，不放入普通 Operator Console，也不允许 MCP/Codex
代替确认。

## 验证 Candidate

```bash
bpa validate  
```

`asset-type` 可以是 Workflow、Node、Adapter、Profile、Policy 或 Page Asset。
验证会检查 Schema、固定版本、权限、风险、编译能力和适用的契约。

## 人工发布

确认验证结果和摘要后：

```bash
bpa publish   --yes
```

发布记录操作者、时间、规范化 JSON 和 SHA-256。相同 `asset_id + version` 不能
覆盖；内容变化必须使用新版本。

## 发布前检查

- Candidate diff 与预期一致。
- 没有 selector 或脚本泄漏到 Workflow。
- Browser Node 的 Origin、权限和风险等级收敛。
- Adapter/Handler 是安装包内审核实现。
- 测试覆盖成功、失败、超时、恢复和迟到结果。
- R2+ 或长期决定已经获得单独人工授权。

审计可以通过 `bpa audit` 查询。AI 创作流程见
[AI 创作与发布边界](../../platform/ai-authoring/)。

# 使用本地工作台

> Summary: 启动 BPA Operator Console，理解健康状态、导航和当前产品边界。
> Authority: tutorial
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/guides/operator-console/
> Raw: https://maplecity1314.github.io/BPA/raw/guides/operator-console.md
> Digest: sha256:a65417f113396b144eec98ae7879e4b3d7cdbc339486933e3beda7aee93e5cdf

Operator Console 是日常运行 BPA 的主要入口。它把系统健康、浏览器会话、Workflow、
人工任务、Dataset 和证据放在同一处；CLI 主要保留给资产发布和高级诊断。

## 启动前确认

1. Local Core 已经运行。
2. Google Chrome 已加载 BPA Extension。
3. 需要访问的平台页面已经由用户正常登录。
4. 准备运行的 Workflow 和 Node 已正式发布。

在开发环境运行：

```bash
pnpm bpa console
```

安装后的 Runtime 直接运行：

```bash
bpa console
```

CLI 会启动一个临时 Console Host，并在浏览器打开只使用一次的入口。入口 Token
位于 URL fragment，不会发送给其他站点；交换成功后使用 `HttpOnly`、
`SameSite=Strict` Session。

## 先看系统状态

首页会把状态归为三类：

| 状态 | 含义 | 建议 |
| --- | --- | --- |
| 无需监管 | Core 与资源正常，没有等待处理的任务 | 可以离开工作台 |
| 请关注 | 某项资源状态变化，但流程可能仍能继续 | 查看对应 Run 或 Session |
| 需要操作 | 流程正在等待登录、确认或人工动作 | 打开任务中心处理 |

Browser Session 卡片会显示 Origin、用途、认证状态和最后活动时间。它只是当前已连接
资源的视图，不会替用户登录或自动选择其他账号。

## 日常入口

- **启动任务**：选择已发布 Workflow、填写输入并绑定精确 Browser Session。
- **运行记录**：按 Run ID 查看当前步骤和有序事件。
- **任务中心**：完成 Human Confirm、Human Action 等人工步骤。
- **数据集**：通过 Staging Lease 上传并发布经过审核的 `.xlsx` Profile。
- **证据与报告**：按 Run 查看 Source、Evidence、Asset 和已有导出。

继续阅读：[启动 Workflow](../run-workflow/) ·
[处理人工任务](../assistance-tasks/) ·
[查看证据](../evidence-assets/)

## 当前限制

工作台不发布正式 Workflow、Node、Adapter 或 Policy，也不授予 R2+ 浏览器写权限。
遇到验证码、登录失效或平台风控时，它只会提示并暂停对应资源。

# 启动 Workflow

> Summary: 选择正式 Workflow、填写输入、绑定浏览器资源并观察一次 Run。
> Authority: tutorial
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/guides/run-workflow/
> Raw: https://maplecity1314.github.io/BPA/raw/guides/run-workflow.md
> Digest: sha256:7c5b7b1a2f7cdc58c415da812ef4a04d86445903ab5627a9c6e364a4b5689fb1

BPA 只运行已经人工发布、版本固定的 Workflow。启动时会把编译后的 IR2、权限、
风险策略、Node/Adapter 版本和浏览器资源绑定一起冻结。

## 通过工作台启动

1. 打开“启动任务”。
2. 选择一个已发布的 Workflow 和精确版本。
3. 填写页面显示的业务输入。
4. 为每个 Resource Slot 选择满足 Origin、能力和认证要求的 Browser Session。
5. 核对只读范围和风险提示，然后启动。

缺少必需 Slot 时工作台不会提交 Run。一个 Slot 绑定到精确 Session，而不是“任意
可用 Chrome”；恢复时也不会偷偷换到其他登录上下文。

## 通过 CLI 启动

CLI 适合诊断不需要 Browser Resource Binding 的 Workflow：

```bash
bpa run  \
  --version  \
  --input '{"key":"value"}'
```

在 Windows PowerShell、批处理或多层自动化工具中，不要把含双引号的 JSON 继续嵌入
命令字符串。`workflow-run` 支持从 UTF-8 文件读取输入，避免 PowerShell、`cmd.exe` 和
CLI 之间发生二次转义：

```powershell
bpa workflow-run  `
  --version  `
  --input-file C:\BPA\run\workflow-input.json
```

`--input` 与 `--input-file` 不能同时使用，输入文件上限为 64 KiB。

当前 CLI 的 `run` 命令不提供资源槽位参数。需要绑定浏览器的 v1alpha3 Workflow
应从工作台启动，或由受信 Control Client 显式提交 `resourceBindings`。

## 运行期间

Run 时间线展示：

- 已进入的步骤和当前状态。
- Assistance 暂停点。
- 节点重试、超时和失败。
- 最终成功、失败、取消或 `uncertain`。

刷新或关闭 Console 不会取消 Run。Console Host、Core 或 Chrome 重启后的恢复语义
见[故障与恢复](../recovery/)。

## 取消不是回滚

取消表达“停止后续工作”的意图。已经开始的页面写动作如果无法证明结果，必须进入
`uncertain`；当前公开业务流程仍保持只读，不开放保存或发布。

# Browser Session 与登录

> Summary: 理解浏览器资源、精确绑定、认证状态和登录失效后的人工接管。
> Authority: tutorial
> Implementation: partial
> Canonical: https://maplecity1314.github.io/BPA/guides/browser-sessions/
> Raw: https://maplecity1314.github.io/BPA/raw/guides/browser-sessions.md
> Digest: sha256:1917efa1ad198f08df5fe591de4120d145bd093e5aa9b3d2277e563c135d86a9

Browser Session 表示 BPA Extension 与 Core 之间的一条已协商连接，也代表一个明确
的浏览器登录上下文。它不是普通 Workflow 输入。

## Session 需要满足什么

每个 Browser Node 可以声明：

- 所需 Capability 和精确 Node 版本。
- 允许的 Origin。
- 最低认证等级。
- 资源用途，例如业务页面或公开资产来源。

Workflow 把这些要求映射到命名 Resource Slot。创建 Run 时，操作者选择精确
Session；Core 保存 Capability Digest、Origin、认证状态和绑定时间的快照。

## 派发前仍会复核

冻结快照不代表 Session 永远有效。每次 Browser Command 派发前都会重新验证：

1. Session 仍然连接或可安全恢复。
2. Capability Digest 没有漂移。
3. 当前 Origin 在允许范围内。
4. 认证等级满足 Node Requirement。
5. Fencing Token、TabRef 和 Page Epoch 仍然有效。

不满足时不会自动改绑到另一个 Session。

## 登录、验证码和风控

登录失效会创建 `auth_takeover` 或同类 Human Action，Run 停在原 Checkpoint。
用户完成正常登录后再继续。BPA 不自动填写验证码，不规避会员权限、限流或平台
风控。

如果只有一个来源失效，已完成的其他来源证据仍然保留，不会从头重复采集。

## 重连

Native Host 或 Extension 重连时使用 Resume Token 恢复原 Session 身份，并轮换
Token。旧 Token、旧 Fencing Token 和迟到 Result 可以进入审计，但不能推进当前
Run。

协议细节见 [Browser Resource Binding](../../control/resource-binding/)。

# 处理人工任务

> Summary: 在任务中心处理 AI Review、Human Confirm 和 Human Action。
> Authority: tutorial
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/guides/assistance-tasks/
> Raw: https://maplecity1314.github.io/BPA/raw/guides/assistance-tasks.md
> Digest: sha256:dcd91f3d825bad09f3cea51e667e12f624eb2a9cf42ec3cce61de40fdc34c1b5

Assistance Task 把非确定性判断和人工动作从 Engine 中分离。Engine 创建任务并保存
Checkpoint；任务提交成功后，再通过幂等 Inbox 唤醒 Run。

## 三种任务

| 模式 | 典型情况 | 能否自动继续 |
| --- | --- | --- |
| `ai_review` | 归类、歧义分析或候选建议 | 仅限已发布 R0/R1 Profile 和确定性验证器 |
| `human_confirm` | 长期绑定、可比关系或最终选择 | 必须由人确认 |
| `human_action` | 登录、验证码、页面恢复 | 必须由人完成动作 |

## 在任务中心处理

1. 阅读任务标题、业务指引和关联 Run。
2. 确认当前页面或证据与任务描述一致。
3. 从已发布 Profile 提供的选项中提交结果。
4. 返回 Run 时间线确认是否继续。

任务认领使用 Lease 和递增 Fencing Token。Lease 过期后任务可以重新认领，但旧
Owner 的迟到提交不会生效。

## 判断边界

- Confidence 只用于排序与审计，不扩大权限。
- AI 返回值必须通过任务 Output Schema。
- R2+、长期绑定和未来写入影响必须人工确认。
- 没有 Codex 认领普通分析任务时，Profile 可以选择保留 unresolved，但不能无限
  阻塞且伪装成已完成。

数据模型见 [Assistance Task v1alpha1](../../models/assistance/v1alpha1/)。

# 查看证据与资产

> Summary: 从 Run 追溯 Source、Evidence、Asset、摘要、保留策略和导出记录。
> Authority: tutorial
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/guides/evidence-assets/
> Raw: https://maplecity1314.github.io/BPA/raw/guides/evidence-assets.md
> Digest: sha256:188328c83545dba2f5ebd09f386ef98fbd405bbf993e4a77e8bcdf8a2257f149

BPA 不把“节点返回成功”直接等同于业务事实。可信结果由来源、执行身份、Evidence、
不可变 Asset 和 Audit 共同支撑。

## 在工作台查看血缘

在“证据与报告”中输入 Run ID，可以查看：

- `SourceRecord`：信息来自哪里、何时访问、使用哪个 Adapter。
- `Evidence`：哪次 Node Execution 产生了什么验证材料。
- `AssetRecord`：正文 Blob 的 SHA-256、MIME、大小和派生关系。
- `EvidenceLink`：Run、Execution、Source 与 Asset 之间的关系。
- `Export`：已经登记的报告或资产包导出。

工作台展示的是元数据和受限下载入口，不会把本机存储路径暴露给页面。

## 为什么正文不在 SQLite

大型正文存放在本地内容寻址存储：

```text
assets/sha256//
```

SQLite 只保存元数据、引用和审计。调用方不能指定最终路径，相同内容按摘要去重，
仍保留不同 Source 和业务语义。

## Browser Evidence 顺序

```text
begin → chunk × N → complete → evidence ACK
→ command result(evidence_refs) → result ACK
```

Result 抢跑、跨 Run 引用、摘要冲突或旧 Fencing Token 都不能推进 Engine。

保留策略和删除约束见[数据与保留](../../operations/data-security/)。

# 故障与恢复

> Summary: 处理 Console、Core、Chrome、Session 和页面状态变化。
> Authority: tutorial
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/guides/recovery/
> Raw: https://maplecity1314.github.io/BPA/raw/guides/recovery.md
> Digest: sha256:f9cadebeb8ed1c6f350f9682cbd33413f8fd5bacde6b901e0c4e084682a36a4a

BPA 的恢复目标不是“什么都重试”，而是在可以证明安全的边界内继续。

## Console 被关闭

关闭工作台只会结束当前 UI Session，不会停止 Local Core 或正在执行的 Run。重新
运行 `bpa console`，再按 Run ID 查看时间线。

## Core 重启

Core 从 SQLite 读取冻结 IR2、Checkpoint、Execution Identity、Inbox/Outbox、
Lease 和 Fencing 状态。恢复使用 Run 创建时保存的计划，不重新编译已经变化的资产。

## Chrome 或 Extension 重连

Bridge 会尝试恢复原 Browser Session，并补发未确认 Result 和 Evidence Chunk。
幂等键防止重复消费，Fencing 防止旧执行者推进状态。

## 页面发生变化

Tab、Origin 或 Page Epoch 不匹配时，Bridge 拒绝沿用旧页面上下文。Adapter 可以在
有限 Readiness/刷新策略内恢复；验证码、登录或风险控制必须交给人工任务。

## 什么时候不能自动继续

- 页面写动作是否已经生效无法判断。
- 数据集或资源绑定的前置摘要已经变化。
- 证据没有完成摘要验证。
- Browser Capability 或认证等级不再满足要求。
- 页面结构连续异常并触发熔断。

这些情况会进入失败、人工暂停或 `uncertain`，而不是无限重试。

执行原理见[执行、恢复与幂等](../../platform/runtime-recovery/)。

# 可信地运行真实浏览器流程

> Summary: BPA 的产品边界、平台架构、执行模型、可信证据和公共协议入口。
> Authority: tutorial
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/
> Raw: https://maplecity1314.github.io/BPA/raw/index.md
> Digest: sha256:bd4c7f76f3ebc8f19121d06e88e622166779caab5148fecea218cfff7ba905a5

01 / EXECUTION
    一条不会在重启后失忆的执行链
    
      Workflow 决定结构，Node 描述能力，Adapter 理解页面。每次运行冻结计划、权限和
      资产版本，每一次状态变化都留下可验证记录。
    
  
  
    01Workflow业务意图
    02Frozen Plan版本与权限
    03Runtime确定性调度
    04Browser真实登录环境
    05Evidence摘要与来源
    06Audit完整追溯
  

  
    02 / PRINCIPLES
    自动化必须同时满足三件事
  
  
    
      R
      可恢复
      计划、Checkpoint、Inbox/Outbox、Lease 和 Fencing 共同保证中断后安全继续。
      了解执行恢复 →
    
    
      G
      受治理
      AI 只能组合或创建 Candidate；正式资产、权限扩大和写操作始终由人确认。
      了解资产边界 →
    
    
      V
      可验证
      来源、Evidence、不可变 Asset 和 Audit 让每条业务结论都能回到原始事实。
      了解可信证据 →
    
  

  
    03 / PATHS
    从与你有关的部分开始
  
  
    
      OPERATORS
      运营人员
      从工作台启动流程、绑定浏览器、处理人工任务并查看证据。
      进入使用指南 ↗
    
    
      BUILDERS
      平台开发者
      理解 Compiler、IR2、Engine、Runtime Provider 和持久化边界。
      阅读平台架构 ↗
    
    
      INTEGRATORS
      能力集成方
      从 Session、Capability、Permission Grant 到 Evidence ACK。
      查看正式协议 ↗
    
  

  
    04 / REALITY
    以当前事实为边界
    协议设计、fixture 和单元测试都不能替代真实页面验收。BPA 明确区分已实现、部分完成和规划能力。
  
  
    
      ACTIVE
      已进入闭环
      冻结 IR2、恢复与幂等、Browser Protocol v2、可信证据、Dataset 和人工任务。
    
    
      PARTIAL
      仍需真实验收
      复杂页面就绪、多来源登录恢复、完整长流程和业务影子运行。
    
    
      OUT OF SCOPE
      没有偷偷承诺
      R2+ 页面写入、验证码绕过、云端多租户、任意脚本和不可信代码执行。
    
  
  查看完整能力状态 →

  
    OPEN CONTRACTS
    协议、Schema 和实现放在同一个仓库里。
  
  
    查看 GitHub
    下载 Schema
    供 AI 阅读

# 核心概念

> Summary: 用最少的概念理解 BPA 的资产、执行、浏览器资源和可信证据。
> Authority: tutorial
> Implementation: active
> Canonical: https://maplecity1314.github.io/BPA/start/concepts/
> Raw: https://maplecity1314.github.io/BPA/raw/start/concepts.md
> Digest: sha256:6fe5b2822d8399d63a43d6a125f8eb43e6c499460624d899c97c95a70a7f4360

## Workflow、Node 与 Adapter

| 对象 | 回答的问题 | 不应包含 |
| --- | --- | --- |
| Workflow | 业务流程先做什么、何时分支、何时等待、何时结束 | selector、脚本、坐标、页面实现细节 |
| Node | 一步能力需要什么输入、产生什么输出、风险与权限是什么 | 动态远程代码、未声明副作用 |
| Adapter | 某个平台页面怎样定位、读取、翻页和判断就绪 | 跨平台业务编排 |

一个已发布 Workflow 只能引用已发布且版本固定的 Node。浏览器 Node 还必须由精确
Adapter 版本和 Extension Capability Manifest 提供实现。

## Candidate 与 Published Artifact

AI 和 MCP 工具可以生成 Candidate。Candidate 可以验证、模拟和比较，但不能进入
正式 Run。人工发布后形成不可变的 `asset_id + version + digest`；相同版本不能覆盖。

## Run 与 Execution Identity

Run 是一次被冻结的执行。IR2 中每次尝试的身份由以下字段决定：

```text
run + scopePath + iterationKey + stepKey + attempt
```

因此 foreach 中相同 Step 的不同条目、同一条目的不同重试不会混在一起。迟到结果和
旧 Fencing Token 不能推进当前状态。

## Resource Slot

Resource Slot 是 Workflow 对外部浏览器上下文的命名需求，例如“一个已认证的只读
页面会话”。Run 启动前，操作者把 Slot 绑定到精确 Browser Session。Slot 不是普通
输入，页面内容和 Node 输出都不能选择或替换 Session。

## Assistance Task

确定性流程遇到需要 AI 判断、人工确认或人工操作的步骤时创建 Assistance Task。
任务有独立状态、Lease 和 Fencing。AI 的 confidence 只用于排序和审计，不会扩大
权限。

## Dataset、Source、Evidence 与 Asset

- Dataset 是经过 Profile 校验和规范化的不可变记录集合。
- Source 描述信息从哪里、何时、以什么访问范围取得。
- Evidence 描述某次 Node Execution 的可验证材料。
- Asset 描述一个不可变 Blob、摘要、媒体类型、派生关系和保留策略。
- Evidence Link 把一次执行证据与 Source/Asset 连接起来，不复制正文。

这些对象分开后，同一个 Blob 可以去重，但不同来源、访问范围和业务含义不会被错误
合并。