docs: V2 拍板 ADR-R2(方案A+两补丁)，6 项 ADR 全部闭环
This commit is contained in:
yu
parent
b14ad0b89b
commit
d972a18bda
@ -286,3 +286,7 @@
|
||||
- 用户确认两项关键决策：①桌面点击逻辑改写进对面 C# 原生进程（PowerShell 通道仅限 demo）；②按能力域拆分部署（纯 Node 域→backend plugin-worker，桌面/视觉/弹窗域→用户电脑 Electron 宿主）
|
||||
- V2 文档已更新：§0 结论、§10 拆"已拍板/待评审"、A6 改哪侧、阶段 0 范围、风险 R1/R2 降级为已缓解
|
||||
- 剩余 4 ADR（R1/R2/R4/R5）+ 3 Q 留待与对面对评审
|
||||
|
||||
## ADR-R2 拍板（11-06 10:00）
|
||||
- 方案 A + 两补丁：RPA 流程=单能力 rpa.flow.execute；节点事件走 event-bus 旁路；人审/高危节点升级对面审批。B 触发条件留档（仅当产品需逐步控制）。不用 B 的三层理由（双账本/控制流节点无副作用/审批重试粒度）已写入 §10。
|
||||
- 至此 6 项 ADR 全部拍板，仅剩 Q1/Q2 待对面确认。6-阶段计划可开工，阶段 1（RPA 侧收口）不依赖对面。
|
||||
|
||||
@ -17,7 +17,7 @@
|
||||
4. **两条硬边界不变且加严**（用户红线）：
|
||||
- 所有带副作用的能力必须经 capability-gateway（授权→租约→幂等→执行→审计），**不得绕行**；
|
||||
- rpa-core **不得依赖 Electron 主进程**（当前仍有 5 处动态 import，是接入阻塞项）。
|
||||
5. **6 项 ADR 已拍板 5 项（2026-11-06）**，仅 R2（集成形态）带问题清单去对面对评审，详见 §10。已定基调：
|
||||
5. **6 项 ADR 全部拍板（2026-11-06）**，仅剩 2 个小问题（Q1/Q2）需对面口头确认，详见 §10。已定基调：
|
||||
- **R3 桌面执行**：C# 路线——五域执行逻辑移植进 windows-runner 原生进程，PowerShell 通道仅限本 demo。
|
||||
- **R6 部署拓扑**：按能力域拆分——纯 Node 域进 backend plugin-worker，桌面/视觉/弹窗域装用户电脑 Electron 宿主，同一包按分组加载。
|
||||
- **R1 能力清单**：全局一份，权限隔离全交对面网关按租户管。
|
||||
@ -152,7 +152,7 @@
|
||||
|
||||
| RPA 侧（packages/rpa-core） | Agent-Employee 侧 | 关系 | 现状 |
|
||||
|---|---|---|---|
|
||||
| `engine/runtime.ts` 流程执行 | `workflow-engine` WorkflowEngine/StepRun | RPA=执行算法候选，AE=权威状态 | 集成形态待 ADR-R2 |
|
||||
| `engine/runtime.ts` 流程执行 | `workflow-engine` WorkflowEngine/StepRun | RPA=执行算法候选，AE=权威状态 | 已拍板方案 A（ADR-R2） |
|
||||
| `engine/registry.ts` 全局注册表 | `plugin-registry` + `capability-gateway` CapabilityRef | ref↔componentId 映射层（rpa-adapter） | 映射待建 |
|
||||
| 719 能力 handler | `plugin-contract` CapabilityDefinition + PermissionScope 13 项 | 能力清单生成 + 权限映射 | 待建（脚本生成） |
|
||||
| `RunContext.signal` | `CapabilityExecutionContext.signal` | 均 AbortSignal，直通 | 兼容 |
|
||||
@ -220,7 +220,7 @@
|
||||
- **兼容性**：状态映射大体可行；RPA 缺 `waiting_user`/`unknown` 两态；对面 StepStatus 无 RPA 的 `idle`。
|
||||
- **问题**：两套状态权威冲突风险；集成形态二选一未定（整体作为一个 capability vs 节点级映射为 step）。
|
||||
- **改哪侧**：adapter + 双侧小改。
|
||||
- **方案**：**推荐 MVP 方案 A**——整个 RPA 流程注册为**一个** capability（`rpa.flow.execute`），workflow-engine 的一个 step 调它，RunResult→ActionResult、节点级事件→event-bus 事件流、human-dialog→requestApproval 挂对面 approval 流、取消→signal 直通；方案 B（RPA 节点=step 1:1 映射）等方案 A 验收后按需评估。NodeState 增 `waiting_user`/`unknown` 两态（unknown 用于崩溃恢复对齐）。
|
||||
- **方案**：**已拍板（ADR-R2）方案 A + 两补丁**——整个 RPA 流程注册为**一个** capability（`rpa.flow.execute`），workflow-engine 的一个 step 调它，RunResult→ActionResult、节点级事件→event-bus 事件流（旁路，不进权威账本）、human-dialog→requestApproval 挂对面 approval 流、取消→signal 直通。补丁 1：节点事件流保透明；补丁 2：人审/高危节点照常升级对面审批。方案 B（节点=step 1:1）的触发条件留档：仅当对面产品确认需要"逐步控制 RPA"（单步执行/任意步回退）时局部启用，届时事件流已备好数据不返工。NodeState 增 `waiting_user`/`unknown` 两态（unknown 用于崩溃恢复对齐）。
|
||||
- **验收**：状态映射契约测试（含 waiting_user/unknown/cancelled 全分支）；一次含审批节点、一次执行中取消、一次进程崩溃恢复的端到端演练；对面 Run 状态终态与 RPA RunResult 永远一致。
|
||||
|
||||
### A6 Computer Control 与 Windows 桌面执行
|
||||
@ -281,7 +281,7 @@
|
||||
|
||||
| 阶段 | 内容 | 前置 | 验收门 |
|
||||
|---|---|---|---|
|
||||
| **0 事实确认**（双侧，1 次评审会） | 评审 R2（带方案 A/B 对比与三项待答问题）+ 3 项 Q；对面确认 CapabilityDefinition 平台字段、utilityExtended 对应 scope；同步已拍板 5 项结论（R1/R3/R4/R5/R6）给对面并预估 C# actuate 扩展量 | 无 | R2 与 Q 有书面结论 |
|
||||
| **0 事实确认**（双侧，1 次评审会） | 向对面同步 6 项已拍板结论（R1-R6）并预估 C# actuate 扩展量；确认 2 个小问题（Q1 platform 字段 / Q2 utilityExtended 权限归属）；确认事件流接口与 rpa.browser 清单备案 | 无 | Q 有书面结论 |
|
||||
| **1 RPA 侧收口**（本仓库） | A3 四件（取消贯通/状态映射/重试元数据/Graph Validator）+ A1 注入参数 + A9（Electron 残留、check-deps 升级、依赖闭包）+ A2 的 ADR 固化 + catalog 脏值清洗 + rpa-cli 重写（显式注册、经 engine 取 handler） | 无 | 审查报告 §7 第一/二阶段清单全绿；纯 Node 环境 Core 全量加载 |
|
||||
| **2 迁入与 adapter 骨架** | git subtree 迁包改名 @agent-worker/rpa-core；bun@1.4.3 test 冒烟（exceljs/pdf/PowerShell 编码）；新建 @agent-worker/rpa-adapter（CapabilityRunner + ref 映射 + 状态映射表）；demo 侧冻结 | 阶段 1 + ADR-R1/R2 | bun test 纯逻辑全绿；未经 gateway 不可达 handler；719 映射完整性测试 |
|
||||
| **3 垂直切片** | 一个文件能力 + 一个 HTTP 能力走通：workflow-engine create/start → gateway authorize → adapter → rpa-core handler → 事件/证据回传 → cancel 中途取消；方案 A（rpa.flow.execute 整体注册） | 阶段 2 | 取消/审批/审计全链有证据；对面 Run 终态与 RunResult 一致 |
|
||||
@ -336,18 +336,16 @@
|
||||
| R4 | 浏览器双路径 | **按场景分工**：RPA 场景走咱们的 CDP 接管路线（复用用户登录态/真实页面——RPA 核心价值）；对面 PlaywrightBrowserRunner 留给 AI 智能体场景（无头自管浏览器）。约束：①咱们 CDP 路线必须接对面 BrowserContextPolicy 白名单与证据体系，不自建；②迁移前修完 transport 超时与定位器不统一两缺陷；③需对面在插件清单给咱们的 runner 备案（rpa.browser） |
|
||||
| R5 | 包消费方式 | **源码并入 + 锁版本**：git subtree 进对面仓库统一编译，Bun 锁 1.4.3（与对面全家 workspace:* 源码消费现状一致） |
|
||||
| R6 | 部署拓扑：rpa-core 各域跑在哪 | **按能力域拆分部署**：纯 Node 域→backend plugin-worker；桌面/视觉/弹窗域→用户电脑 Electron 宿主；同一包按 PLATFORM_GROUPS 分组加载，不维护两份代码 |
|
||||
| R2 | 集成形态：RPA 流程=单个 capability（方案 A）还是节点=step 映射（方案 B） | **方案 A + 两补丁**：RPA 流程=`rpa.flow.execute` 单能力，对面一个 step 一次租约一次结算；节点级事件走 event-bus 旁路（保透明、不进权威账本）；人审/高危节点照常升级对面审批。**不用 B 的理由**（记录在案）：双账本一致性（崩溃窗口两边分歧、破坏对面 recovery 的单账本假设）、控制流节点无副作用无法映射 CapabilityRef、审批/重试粒度与业务语义错位。**B 的触发条件**：对面产品确认需要"逐步控制 RPA"（单步执行/任意步回退）时局部启用，事件流已备好数据不返工 |
|
||||
|
||||
### 待对面对评审确认（不猜测）
|
||||
|
||||
| ADR | 问题 | 评审要点 |
|
||||
|---|---|---|
|
||||
| R2 | 集成形态：RPA 流程=单个 capability（方案 A）还是节点=step 映射（方案 B）？ | 本方需对面补充信息后定：①对面产品上是否要求逐步审批/逐步可见（决定 A 是否够用）；②对面 workflow-engine 的 step 粒度是否有上限或性能顾虑（719 能力×节点数映射成 step 的量级）；③对面对 RPA 执行中途取消/暂停的交互预期。方案对比：A=对面一个 step 跑完一条 RPA 流程（工作量小、状态映射简单、对面只见"开始/结束"+事件流）；B=每个节点一个 step（全程透明可逐步审批，工作量数倍、两套状态机对表复杂）。本方倾向 A 起步、协议预留节点级事件上报。 |
|
||||
### 待对面对确认（仅剩小问题，不猜测）
|
||||
|
||||
| Q# | 问题 | 评审要点 |
|
||||
|---|---|---|
|
||||
| Q1 | CapabilityDefinition 是否需要 platform 字段（对面清单未见） | 建议对面补字段或约定由 catalog platformTag 承载 |
|
||||
| Q2 | utilityExtended（命令执行）对应哪个 PermissionScope | 13 项中 desktop.process 是候选，需对面确认语义（backend 无桌面，进程执行属哪域） |
|
||||
| Q3 | human-dialog 弹窗宿主落点 | 已被 R6 顺带回答：用户电脑 Electron 宿主窗口；仅弹窗样式/交互细节与对面 UI 对齐 |
|
||||
|
||||
> 已回答：Q3（human-dialog 弹窗落点）已由 R6 回答——用户电脑 Electron 宿主窗口；仅样式/交互细节与对面 UI 对齐。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user