From fb6e8ca0bf2b1fc6af53a0e10e8228e72adc2224 Mon Sep 17 00:00:00 2001 From: yu <1919727607@qq.com> Date: Fri, 6 Nov 2026 14:59:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8E=E7=BB=AD=E5=B7=A5=E4=BD=9C?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E6=B8=85=E5=8D=95=EF=BC=88W1-W14=EF=BC=89+?= =?UTF-8?q?=20Q1/Q2/=E6=88=AA=E5=9B=BE=E6=97=B6=E6=9C=BA/rpa.browser=20?= =?UTF-8?q?=E5=9B=9B=E9=A1=B9=E8=AE=BE=E8=AE=A1=E6=8F=90=E6=A1=88=E5=AE=9A?= =?UTF-8?q?=E7=A8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/next-work-plan.md | 85 +++++++++++++++++++++++++++++ docs/rpa-core-migration-guide-v2.md | 4 +- 2 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 docs/next-work-plan.md diff --git a/docs/next-work-plan.md b/docs/next-work-plan.md new file mode 100644 index 0000000..a814784 --- /dev/null +++ b/docs/next-work-plan.md @@ -0,0 +1,85 @@ +# RPA 迁移后续工作完整清单（2026-11-06 定稿） + +> 前提：阶段 0 前置作业 + 阶段 1 收口 + 本仓库代码活已 100% 完成（含 C# actuate 原型、A++ 字段、NodeState 两态）。本清单是"接下来做什么"的唯一权威账本，按可动性分四档。更新规则：完成一项就划掉并记提交号；新工作先进"待评估"再入档。 + +## 三个"不知道"的设计提案（已定稿，发对面确认即可，不再阻塞） + +### 提案 1（原 Q1）：平台字段怎么表达 + +对面 plugin-contract 的 `CapabilityDefinition` 增可选字段 `platforms?: readonly ("win32"|"darwin"|"linux")[]`： + +- **缺省 = 全平台**——旧插件清单不加字段，零破坏； +- `assertPluginManifest` 校验值域，未知平台值直接拒绝； +- plugin-worker 认领动作时按宿主 `process.platform` 过滤，不匹配的能力对宿主不可见； +- **RPA 插件清单不手工维护**：rpa-adapter 从 rpa-core catalog 的 `platformTag` 自动生成（687 win32 / 326 null 单一事实源）。 + +### 提案 2（原 Q2）：utilityExtended 权限归属 + +utilityExtended 在对面源码中无同名物（纯 RPA 侧能力域）。**映射到对面 13 项 PermissionScope 的 `desktop.process`**： + +- 理由：RPA 命令执行发生在用户电脑 Electron 宿主进程内，"宿主即桌面进程"，与 `desktop.process` 语义吻合； +- 该域全部标 `highImpact + idempotencyRequired`（走审批，与 ADR-R1/R6 一致）； +- 备选：若对面坚持 desktop.process 严格指"桌面进程管理"，则新增 `desktop.command` scope（对面 plugin-contract 加一个 union 成员 + Set 一行）。 + +### 提案 3：晨间助手截图时机 + +不设专门时机，**全部挂在既有证据节奏上**： + +1. 流程开始：observe 基线一张（定位 + 前置证据，windows-runner 现有能力）； +2. 人审弹窗前：human-dialog 展示前截当前画面，作为"待确认状态"证据随审批事件存证； +3. 每次动作后：actuate 已内置动作前后双证据（PrintWindow + SHA-256），无需额外处理。 + +需要对面做的只有一件：审批事件关联 evidence 的接口（A++ 两侧改动清单里 event-bus 入审计链一项已覆盖）。 + +### 提案 4：rpa.browser 备案单（发给对面即可登记） + +| 项 | 值 | +|---|---| +| pluginId | `rpa.browser` | +| capabilities | `rpa.flow.execute`（RPA 流程整体入口，方案 A）| +| runner | 双 runner：对面 PlaywrightBrowserRunner（AI 智能体场景）+ 我方 CDP 接管（RPA 场景主力，ADR-R4）| +| PermissionScope | `browser.domain`（白名单复用对面 BrowserContextPolicy 三重复检）+ `filesystem.download`（下载类流程）| +| manifest 类型 | browser 能力按对面现行 browser-plugin 口径（域名白名单强校验）| +| 证据 | snapshot/截图走对面证据体系（SHA-256 落盘），不自建 | + +--- + +## 第一档：本周就能做（不依赖对面） + +- [ ] **W1 发提案包**：上面 4 个提案 + 6 项 ADR 结论，一条消息发对面负责人，等书面确认（Q1/Q2 提案已写入 V2 §10） +- [ ] **W2 C# actuate 合入对面主干**（你自办）：按 `contrib/windows-runner-actuate/PATCH-NOTES.md` 执行——3 文件 + Program.cs 最小 diff + **同一提交**更新当前事实.json 与 README 区块，跑 `document-facts --check` + `ci-gate --mode fast` 过门禁 +- [ ] **W3 rpa.browser 侧准备**（本仓库）：浏览器能力 transport 单命令超时 + 统一 resolveElement 修复（ADR-R4 前置，V2 §7-A6 列明的迁前必修项） + +## 第二档：等对面书面确认后立即动（预计 1-2 天内解锁） + +- [ ] **W4 git subtree 迁包**：rpa-core → `code/backend/packages/rpa-core` 改名 `@agent-worker/rpa-core`；Bun 1.4.3 复验（本机 1.4.4 冒烟 37/37 已绿）+ PowerShell 编码冒烟 +- [ ] **W5 rpa-adapter 骨架**（对面仓库新建）：CapabilityRunner（gateway.execute → ref→componentId → RunContext → handler）+ 权限映射表（34 域 × 13 scope，utilityExtended→desktop.process）+ 状态映射直接 import 本方 `toStepStatus()` + 719 能力"未经 authorize 不得触达 handler"全量冒烟 +- [ ] **W6 platform 字段实现**（对面 plugin-contract）：按提案 1，registry 校验 + worker 过滤 + 契约测试 + +## 第三档：阶段 3+（前置：W4/W5 完成） + +- [ ] **W7 垂直切片**：1 文件能力 + 1 HTTP 能力全链（create/start → authorize → adapter → handler → 事件/证据回传 → 中途取消）；Run 终态与 RunResult 一致性断言 +- [ ] **W8 A++ 检查点最小验证**：崩溃 → resumeToken 重入 → 幂等键去重（`checkpointId`/`idempotencyKey` 已定稿，只差实现） +- [ ] **W9 双 ADR 落地**：R4 浏览器（W3 产物接对面白名单）+ R3 桌面（W2 产物接 TS 宿主适配器——actuate 前先 observe 解析精确标题） +- [ ] **W10 TS 宿主 actuate 适配器**：native-observer.ts 扩展（请求侧精确标题解析、响应侧证据逐项复核、宿主超时 ≥15s） + +## 第四档：规模化与收尾（阶段 5/6） + +- [ ] **W11 34 域分批接入**：files/data/http/ftp → office/excel/word → desktop/utility 高影响（末批 + 审批矩阵抽查） +- [ ] **W12 ocr-smoke 素材治理**（迁移时**必做**，非可选）：素材入库 `test-fixtures/ocr/` + evidenceDir 改 `os.tmpdir()`——硬编码 `D:/office-test2` 在对面机器必然失效 +- [ ] **W13 平台扩展**：Linux/macOS 驱动按 ADR-R3 原生通道（阶段 6） +- [ ] **W14 demo 侧冻结**：本 demo 仓库转入只读维护 + +## 挂账小项（低优先） + +- [ ] 晨间助手截图时机：提案 3 已替代"确认需求"，待对面认领审批-证据关联接口 +- [ ] `.workbuddy/tmp/actuate-build` 编译沙盒：留作 W2 合入前复验环境，合入后可删 + +## 里程碑对照 + +| 里程碑 | 依赖 | 预计解锁 | +|---|---|---| +| Q1/Q2/备案 书面确认 | W1 | 第二档全部 | +| 对面仓库可提交 | W1 | W2/W4/W5/W6 | +| 垂直切片全链绿 | W4-W7 | 阶段 4（W8-W10）| +| 高影响域过审批矩阵 | W11 | 阶段 5 完成即"接入就绪" | diff --git a/docs/rpa-core-migration-guide-v2.md b/docs/rpa-core-migration-guide-v2.md index 83b2615..90d290a 100644 --- a/docs/rpa-core-migration-guide-v2.md +++ b/docs/rpa-core-migration-guide-v2.md @@ -349,8 +349,8 @@ | Q# | 问题 | 评审要点 | |---|---|---| -| Q1 | CapabilityDefinition 是否需要 platform 字段（对面清单未见） | 建议对面补字段或约定由 catalog platformTag 承载 | -| Q2 | utilityExtended（命令执行）对应哪个 PermissionScope | 13 项中 desktop.process 是候选，需对面确认语义（backend 无桌面，进程执行属哪域） | +| Q1 | CapabilityDefinition 是否需要 platform 字段（对面清单未见） | **本方设计提案（2026-11-06）**：对面 plugin-contract 增可选 `platforms?: readonly ("win32"\|"darwin"\|"linux")[]`，缺省=全平台（旧清单零破坏）；registry 的 `assertPluginManifest` 校验值域；plugin-worker 认领动作时按宿主 `process.platform` 过滤。RPA 侧清单由 rpa-adapter 从 catalog `platformTag` 自动生成，不手工维护第二份。与对面确认后照此实现 | +| Q2 | utilityExtended（命令执行）对应哪个 PermissionScope | **本方设计提案（2026-11-06）**：utilityExtended 域在对面源码无同名物，属纯 RPA 侧概念。提案映射到 `desktop.process`——RPA 命令执行发生在用户电脑 Electron 宿主内，宿主即桌面进程，语义吻合；该域标 highImpact + idempotencyRequired 走审批。若对面认为 desktop.process 严格指"桌面进程管理"，备选新增 `desktop.command` scope。13 项 PermissionScope 其余映射维持 §7-A4 初稿 | > 已回答：Q3（human-dialog 弹窗落点）已由 R6 回答——用户电脑 Electron 宿主窗口；仅样式/交互细节与对面 UI 对齐。