# windows-runner-actuate 原型补丁包

**用途**：把 RPA 桌面驱动（`packages/rpa-core/src/driver/windows/windows-driver.ts`，PowerShell 实现）的鼠标/键盘/窗口执行能力移植为对面 Agent-Employee `windows-runner` 的 C# 原生实现——即 ADR-R3（C# 路线）的第一块实体。

**状态**：本地原型，未合入对面主干。对面 backend/README Windows 行已明确下一步为"click/type、视觉/OCR 或随本轮客户端交付"，本补丁正是其路线图的第一步。

## 内容清单

| 文件 | 内容 |
|---|---|
| `PORTING-MAP.md` | PowerShell → C# 逐原语移植对照表：三处语义差异（模糊→精确匹配、进程模型、证据增强）、错误码映射、mouse_event→SendInput 标志位映射 |
| `native/ActuateProtocol.cs` | actuate 协议扩展类型（请求/动作/结果），复用对面 DesktopPolicy/EvidenceRef/ObservedWindow |
| `native/NativeInput.cs` | 输入类 P/Invoke + **抢前台五招兜底逐行移植**（RPA 实战参数，一行语义不改） |
| `native/ActuateService.cs` | 执行服务：安全门与 observe 同构（白名单/Session/精确匹配），10 种动作闭集分发，动作前后证据截图，平滑移动公式逐行保真 |
| `PATCH-NOTES.md` | 合入指引：Program.cs 最小 diff、TS 宿主适配要点、验证计划、**门禁合规硬性清单** |

## 设计红线（对面安全模型的尊重项）

1. `NativeWindows.cs` 只读编译边界不动——输入类 P/Invoke 独立成 `NativeInput.cs`；
2. 安全门一个不少：进程文件名白名单正则、窗口精确匹配、OS Session 三重核验后才允许输入；
3. 副作用证据：动作前后各一张窗口 PNG（PrintWindow + SHA-256，默认 secret），接入对面证据体系；
4. 稳定错误码进 stdout，系统路径/控件文字不回显；
5. 单请求单响应、超时杀进程，遵守对面进程模型。

## 交接方式

按 `PATCH-NOTES.md` 执行：3 个新文件 + Program.cs 最小 diff + TS 适配器后续工作。合入提交必须带事实文件与文档区块更新（对面 2026-11-06 门禁），清单见 PATCH-NOTES 第 5 节。

## 验证状态

**已编译通过 + 协议冒烟通过**（2026-11-06，.NET SDK 10.0.403）：对面 csproj 原样 + 本补丁三文件 + Program.cs 最小 diff → `dotnet build` 0 警告 0 错误；五例零桌面交互协议冒烟全部符合预期（安全门错误码、双路分发、requestId 回显、observe 无回归）。真实窗口用例留待对面 `test/fixture` 集成测试。