From 10d125ce9d88f1f7d55246e7d382105e9f818350 Mon Sep 17 00:00:00 2001 From: yu <1919727607@qq.com> Date: Fri, 6 Nov 2026 16:44:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20Q4=20=E6=BA=90=E7=A0=81=E6=A0=B8?= =?UTF-8?q?=E6=9F=A5=E8=90=BD=E6=A1=A3=EF=BC=88=E5=AE=A1=E6=89=B9=E4=B8=8A?= =?UTF-8?q?=E6=B8=B8=3Dworkflow-engine=20=E5=B7=B2=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=EF=BC=89+=20=E5=AE=A1=E6=89=B9=E5=AF=B9=E8=B1=A1=E4=B8=89?= =?UTF-8?q?=E5=B1=82=E8=AE=BE=E8=AE=A1=EF=BC=88=E7=99=BD=E5=90=8D=E5=8D=95?= =?UTF-8?q?/=E6=B5=81=E7=A8=8B=E4=B8=8A=E6=9E=B6/=E5=8D=95=E6=AC=A1?= =?UTF-8?q?=E9=AB=98=E5=8D=B1=E5=8A=A8=E4=BD=9C=EF=BC=8C=E5=BC=B9=E7=AA=97?= =?UTF-8?q?=3Dconsent=20=E4=B8=8D=E8=B5=B0=E5=AE=A1=E6=89=B9=E5=8D=95?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/rpa-core-migration-guide-v2.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/rpa-core-migration-guide-v2.md b/docs/rpa-core-migration-guide-v2.md index ea0b375..29e7e54 100644 --- a/docs/rpa-core-migration-guide-v2.md +++ b/docs/rpa-core-migration-guide-v2.md @@ -354,11 +354,26 @@ |---|---|---| | 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 初稿 | -| Q4 | 高危审批的"上游服务"成熟度 | gateway 只按 actionId 精确放行，注释明言"审批有效性判定（是否过期、是否本人审批）由上游负责"（capability-gateway index.ts:13-14），但该上游服务的实现与闭环未见。RPA 人审弹窗方案（human-dialog→requestApproval→绑定 actionId）依赖它，须确认其签发/过期/防代批机制现状 | +| Q4 | 高危审批的"上游服务"成熟度 | gateway 只按 actionId 精确放行，注释明言"审批有效性判定（是否过期、是否本人审批）由上游负责"（capability-gateway index.ts:13-14），但该上游服务的实现与闭环未见。RPA 人审弹窗方案（human-dialog→requestApproval→绑定 actionId）依赖它，须确认其签发/过期/防代批机制现状。**源码核查（2026-11-06）：上游已实现非设计**——即服务端 workflow-engine 包：approval-policy 纯函数（actionId=runId:stepId:attempt 重试不被旧审批放行 / expiresAt 过期判定 / 仅 high 风险可发起）+ workflow-api 路由（request_approval / decide_approval，403 发起人不能审批自己=防代批、409 缺审批、410 已过期）+ Postgres 持久化；桥=plugin-worker 取 approvedActionIds 喂 gateway。缺口：审批人身份仍为开发态 token（PRODUCT_APPROVER_TOKEN，生产形态未接完）；RPA 挂接的对齐点见下方"审批对象三层"专条 | | Q5 | 租户权限配置面 | 每租户/员工的 `allowedPermissions` 白名单由谁配置、走哪条链路（entitlement-contract / identity-store 成熟度），adapter 对接前须核一眼 | > 已回答：Q3（human-dialog 弹窗落点）已由 R6 回答——用户电脑 Electron 宿主窗口；仅样式/交互细节与对面 UI 对齐。 +### 审批对象三层设计（2026-11-06 设计思考，待与上游对齐） + +"审批什么、谁来批"须拆三层，混用会导致对面防代批机制（403）误伤合法场景： + +| 层 | 对象 | 谁来批/定 | 时机与频率 | 载体 | +|---|---|---|---|---| +| ① 能力白名单 | 租户/员工能用哪类能力 | 管理员配置 | 事前一次，长期生效 |对面 Q5 链路（entitlement），**不产生审批单** | +| ② 流程上架 | 流程定义版本 + 它声明的能力清单 | 上游审批人 | 事前一次，多次运行复用 | 审批单（或管理端流程发布流程，待对齐用哪个） | +| ③ 单次高危动作 | 某次运行中的具体高危节点 | **分两种**：有人值守=用户知情同意；无人值守=上游审批人 | 事中，逐动作 | 有人值守=human-dialog 弹窗（consent，**不走审批单**，否则"自己批自己"被对面 403 挡死）；无人值守=workflow-engine 审批单，运行暂停等批 | + +推论（修正此前对齐清单）： +- **actionId 粒度问题（attempt 维度）只存在于无人值守路径**；有人值守路径由"租约 60s + 每节点弹窗"兑现（§R2 三次拍板），与审批单无关。 +- 日常有人值守运行**不需要**每次调 workflow-api；只有定时/远程触发的无人值守高危动作才走 request_approval 暂停等批——这正面回答了"发起方通道"问题。 +- 对上游的对齐问题收敛为：②流程上架审批放哪个系统；③无人值守路径复用 workflow-engine 时 actionId（runId:stepId:attempt）与 rpa-core 幂等键（runId:nodeId）的映射（nodeId:attempt 是否补入 RunEvent）；审批人身份生产化（trusted-gateway-headers / 管理端账号）。 + ### R6 补记：双端透明调度设计（2026-11-06 用户拍板：前端留、后端也留） 同一能力允许本地（用户电脑宿主）与后端（plugin-worker）两驻地并存，调度对用户无感知，SaaS 与本地部署两形态通用（本地部署时"后端"即客户自有机房，规则不变）。防乱靠三条纪律与一张确定性路由表：