octopus-rpa-app-runner 技能升级需求 v2

原始文件：wecom_e588f9e2_octopus-rpa-app-runner_技能升级需求_v2.md

octopus-rpa-app-runner 技能升级需求 v2

基于《octopus-rpa-app-runner 技能升级 PRD》v1.0、当前 SKILL.md、Python/PowerShell 脚本、临时脚本与静态测试形成的可实施需求基线。

---

1. 文档信息

1.1 规范用语

• “必须”：P0/P1 交付不可缺少，未满足即不通过验收。
• “应”：原则上实现；若不实现，必须在发布说明中记录原因和替代方案。
• “可以”：增强项，不阻塞本次发布。
• “直接运行”：仅指参数对话框已经存在时，不修改任何输入框，点击该对话框的“运行应用”按钮；不等同于从应用列表首次点击 running。
• “关闭浮窗”：先尝试通过 UI 停止当前运行，再关闭“八爪鱼RPA运行窗口”以恢复 Studio；关闭窗口本身不等同于已证明业务任务停止。
• “只读命令”：不得启动 Studio、点击运行/停止、关闭窗口、创建目录、写配置或清理进程的命令。

---

2. 背景、现状与差距

2.1 已有能力

当前技能以 scripts/run_pywinauto.cmd + OctopusRpaAppRunner.py 为默认实现，以 OctopusRpaAppRunner.ps1 为兼容回退，已经具备：

• 列出应用、精确名称运行、按关键词/前缀选最高版本、互动选择。
• --current-running / --check-run-list 只读查询，输出 RUN_LIST_STATE=empty|active|unknown。
• 运行确认与恢复已有运行浮窗确认分离：--yes-run、--yes-restore-existing-run。
• 单个高置信度 Edit 输入框的目录填写，以及默认目录记忆。
• --stop-run-window、进程快照、显式清理重启。
• 浮窗快照二次校验，避免确认后窗口对象发生变化仍继续操作。
• 临时 click_run_app_direct.py 与 close_run_window_direct.py 已验证两个真实边界场景。

2.2 原 PRD 的主要价值

原 PRD 正确识别了两个 P0 缺口：参数弹窗多输入框时需要受控“直接运行”；停止按钮不存在时需要显式“关闭浮窗恢复 Studio”。本 v2 保留这两个核心目标，不改变原 PRD 的业务方向。

2.3 现状差距

---

3. 目标与成功指标

3.1 产品目标

1. 多输入框弹窗出现时，技能能安全地：显式映射参数后运行、经用户确认后不填直接运行，或保持弹窗等待人工处理。
2. 浮窗残留时，技能能经独立确认执行“尝试停止 -> 关闭浮窗 -> 验证 Studio”，并如实报告每一步，而不把关闭视为停止证明。
3. 所有动作具有稳定命令语义、结果字段、错误码、退出码和最小可回归测试。
4. 保持现有默认 Python 路径和 PowerShell 回退，不扩大为系统级架构重构。

3.2 成功指标

• P0/P1 验收用例通过率 100%。
• 所有危险动作在无对应确认时，UI 点击数为 0，目录/配置写入数为 0。
• Python 与 PowerShell 在 P0 安全用例中的退出类别和错误码一致率 100%。
• 对直接运行和关闭浮窗，输出可区分 confirmed、clicked、verified、partial、cancelled。
• 静态/单元/CLI mock 测试可在无 Octopus、无生产动作的环境运行。

---

4. 范围与非范围

4.1 本次范围

• 正式提供参数弹窗“直接运行”能力。
• 正式提供“关闭运行浮窗恢复 Studio”能力。
• 参数对话框策略、单输入框和多输入框映射规则。
• 用户确认机制、状态机、幂等规则、安全边界。
• CLI 参数、结构化输出、日志、错误码和退出码契约。
• Python 默认实现与 PowerShell 回退的关键安全行为对齐。
• SKILL.md、自动测试、受控现场验收和版本迁移说明。

4.2 非范围

• 不重构 Octopus RPA Studio、BrowserBridge 或 Bot。
• 不实现跨机器调度、队列、定时任务、账号管理或远程凭据管理。
• 不判断 RPA 内部业务逻辑是否最终成功；仅观测 UI/进程/运行列表等启动证据。
• 不实现多个应用串行/并行批量运行。
• 不通过 OCR/视觉模型猜测未知字段；本次仅使用 UI Automation 可验证属性。
• 不自动杀死所有 Edge、Bot 或未知进程。
• 不为所有 Octopus 应用建立业务参数模板；仅提供通用映射和可选配置基础。
• 不取消 PowerShell 回退，也不要求将两套实现重写为同一代码库。

---

5. 角色与场景

5.1 角色

5.2 核心场景

• SCN-01：用户只读列出应用或查询运行状态。
• SCN-02：用户确认运行指定应用，无参数弹窗。
• SCN-03：用户确认运行，出现唯一目录输入框，填值后二次点击。
• SCN-04：出现多个输入框，用户提供明确字段映射后运行。
• SCN-05：出现多个输入框，用户明确说“不填，直接点运行应用”。
• SCN-06：第一次运行流程失败后，参数弹窗仍在；用户独立授权接管该弹窗直接运行。
• SCN-07：浮窗存在，用户只要求停止；找不到停止按钮时不得自动关闭。
• SCN-08：浮窗存在，用户明确要求恢复 Studio；确认后尝试停止并关闭浮窗。
• SCN-09：有现存运行时用户要运行新应用；分别确认恢复现有运行和启动新应用。
• SCN-10：重复提交同一命令，技能避免重复点击或如实返回“已处于目标状态”。

---

6. 功能需求

6.1 动作与命令语义

6.2 参数对话框

6.3 应用选择与启动验证

6.4 浮窗停止与关闭

6.5 配置、兼容与文档

---

7. 非功能需求

---

8. 安全约束与确认机制

8.1 动作授权矩阵

8.2 交互确认内容

直接运行确认必须展示：

• 动作名称：“不填写参数，点击参数弹窗中的运行应用”。
• 弹窗所属进程、窗口标题/handle 摘要和指纹。
• 检测到的输入框数量、空/非空数量；不展示实际敏感值。
• 风险：“现有默认值或空值将原样提交，可能导致任务失败或使用应用内默认配置”。
• 可接受肯定词；其他输入一律取消。

关闭浮窗确认必须展示：

• 当前浮窗 title、pid、handle、检测时间。
• 计划：“先尝试停止；若停止按钮不存在或浮窗仍在，则关闭浮窗恢复 Studio”。
• 风险：“关闭浮窗不必然证明任务已停止；技能会在关闭后再次验证”。
• 是否正在为启动另一应用恢复旧运行；若是，仍需另行确认新应用运行。

8.3 确认有效期和竞态保护

• 确认仅对当前进程内、当前 OPERATION_ID、当前 UI 快照有效，不持久化。
• 确认后、点击前必须再次比较窗口 pid/handle/指纹；变化则返回 STALE_CONFIRMATION。
• 非交互 yes 标志仅授权命令行中明确声明的动作，不授权运行中动态升级出来的新副作用。
• 用户取消返回 cancelled，不得创建目录、写配置或点击后续按钮。

---

9. CLI 与输出契约

9.1 推荐 CLI

run_pywinauto.cmd --click-run-app-direct [--yes-direct-run]
run_pywinauto.cmd --close-run-window [--yes-close-run-window]
run_pywinauto.cmd --run-exact-name NAME --parameter-dialog-policy auto|map|direct|leave [--parameter KEY=VALUE ...] [--yes-run]
run_pywinauto.cmd --run-latest-by-prefix KEY --parameter-dialog-policy auto|map|direct|leave [--yes-run]
run_pywinauto.cmd --output text|json

约束：

• --parameter 仅可与 policy=map 一起使用。
• --yes-direct-run 仅可与 --click-run-app-direct 一起使用。
• --yes-close-run-window 仅可与 --close-run-window 一起使用。
• --skip-run-parameter-dialog 等价于 --parameter-dialog-policy leave，打印弃用警告。
• --yes 保留为 --yes-run 弃用别名，不扩展权限。
• 参数冲突在初始化 pywinauto 之前失败。

9.2 文本输出

机器可依赖的最终结果块必须每行一个 KEY=VALUE，至少包含：

CONTRACT_VERSION=2
OPERATION_ID=<uuid>
ACTION=<action>
RESULT=success|partial|cancelled|failed|already_satisfied
STAGE=<state>
CHANGED=true|false
VERIFIED=true|false
ERROR_CODE=<code-or-empty>
MESSAGE=<single-line-human-readable-message>

动作可增加字段，例如：

PARAM_DIALOG_FOUND=true
PARAM_INPUT_COUNT=3
DIRECT_RUN_CLICKED=true
STOP_ATTEMPTED=true
STOP_CLICKED=false
WINDOW_CLOSED=true
STUDIO_RESTORED=true
RUN_STOP_VERIFIED=false
RUN_LIST_STATE=unknown

要求：

• 自由文本日志可保留，但最终结果块字段名和值域稳定。
• RUN_LIST_SAFE=true 仅在可信 empty 时输出；active 和 unknown 均为 false。
• VERIFIED=true 必须有对应后置条件证据，不能仅因为 InvokePattern 未抛异常。
• MESSAGE 不得包含换行或敏感参数值。

9.3 JSON 输出

--output json 必须只向 stdout 输出一个合法 JSON 对象；诊断日志写 stderr。最小 schema：

{
  "contract_version": 2,
  "operation_id": "...",
  "action": "close_run_window",
  "result": "partial",
  "stage": "studio_restored",
  "changed": true,
  "verified": false,
  "error": {"code": "RUN_STOP_UNVERIFIED", "message": "..."},
  "evidence": {
    "stop_attempted": true,
    "stop_clicked": false,
    "window_closed": true,
    "studio_restored": true,
    "run_list_state": "unknown"
  }
}

9.4 退出码

用户取消虽返回 0，但 RESULT=cancelled、CHANGED=false，调用方不得将其当作动作成功。

9.5 错误码

至少提供以下稳定错误码：

• ARG_CONFLICT、ARG_REQUIRED、UNSUPPORTED_IN_FALLBACK
• CONFIRMATION_REQUIRED、STALE_CONFIRMATION、USER_CANCELLED
• APP_NOT_FOUND、APP_MATCH_AMBIGUOUS、BATCH_RUN_UNSUPPORTED
• PARAM_DIALOG_NOT_FOUND、PARAM_DIALOG_AMBIGUOUS、PARAM_INPUT_NOT_FOUND
• PARAM_INPUT_AMBIGUOUS、PARAM_MAPPING_FAILED、PARAM_VALUE_UNVERIFIED
• RUN_APP_BUTTON_NOT_FOUND、DIRECT_RUN_CLICK_FAILED
• RUN_WINDOW_NOT_FOUND、STOP_BUTTON_NOT_FOUND、STOP_CLICK_FAILED
• RUN_WINDOW_CLOSE_FAILED、STUDIO_RESTORE_FAILED、RUN_STOP_UNVERIFIED
• RUN_LIST_UNKNOWN、RUN_START_UNVERIFIED
• CONFIG_INVALID、CONFIG_WRITE_FAILED、DEPENDENCY_MISSING、UI_SESSION_UNAVAILABLE

---

10. 状态机

10.1 运行状态机

IDLE/STUDIO_READY
  -> APP_SELECTED
  -> RUN_CONFIRMED
  -> INITIAL_RUN_CLICKED
     -> START_OBSERVED                         （无参数弹窗）
     -> PARAMETER_WAITING                      （检测到弹窗）
        -> PARAM_AUTO_MAPPED -> PARAM_SUBMITTED
        -> PARAM_EXPLICITLY_MAPPED -> PARAM_SUBMITTED
        -> DIRECT_RUN_CONFIRMED -> PARAM_SUBMITTED
        -> LEFT_FOR_MANUAL -> START_UNVERIFIED
        -> CANCELLED
     -> START_UNVERIFIED                       （超时无明确证据）
  -> FAILED

转换约束：

• PARAMETER_WAITING -> DIRECT_RUN_CONFIRMED 必须具备匹配当前快照的授权。
• PARAM_SUBMITTED -> START_OBSERVED 需要后置证据；点击成功本身不足。
• 任意竞态、目标歧义或未知状态进入 FAILED/START_UNVERIFIED，不得自动重试点击。
• 有现存运行浮窗时，在进入 APP_SELECTED 前先执行独立恢复子状态机。

10.2 浮窗恢复状态机

RUN_WINDOW_DETECTED
  -> CLOSE_CONFIRMED
  -> SNAPSHOT_REVALIDATED
  -> STOP_ATTEMPTED
     -> STOP_CLICKED -> WAIT_FOR_DISAPPEAR
     -> STOP_NOT_AVAILABLE
  -> WINDOW_ALREADY_GONE -> VERIFY_STUDIO
  -> WINDOW_CLOSE_ATTEMPTED -> WINDOW_CLOSED
  -> VERIFY_STUDIO
     -> RESTORED_AND_STOP_VERIFIED
     -> RESTORED_BUT_STOP_UNVERIFIED
     -> STILL_ACTIVE
     -> RESTORE_FAILED

• STOP_NOT_AVAILABLE 只有在 close 专用确认覆盖降级风险时才能转入 WINDOW_CLOSE_ATTEMPTED。
• RESTORED_BUT_STOP_UNVERIFIED 是 partial，不是 success。
• 浮窗初始不存在且 Studio 可用，直接进入 ALREADY_RESTORED。

10.3 可观测状态与业务状态

技能仅声明：

• UI 点击是否发出。
• 参数是否写入并回读。
• 浮窗是否出现/消失。
• Studio 是否恢复。
• 运行列表和受控进程证据。

技能不得声明：

• 简历是否下载完成、招呼是否发送成功等业务结果。
• 仅凭浮窗关闭即声明 RPA 已停止。
• 仅凭 Edge/Bridge 存在即声明目标应用已运行。

---

11. 幂等性与重试

建议以 OPERATION_ID + action + target fingerprint 记录进程内动作账本；本次不要求跨进程持久化幂等键。

---

12. 异常处理

12.1 通用原则

1. 参数校验失败：不初始化 UI、不写配置。
2. 目标歧义：输出候选摘要，等待用户选择，不猜测。
3. 确认后对象变化：作废确认，不自动套用到新对象。
4. 点击结果未知：停止副作用动作，返回 partial/unknown，不盲目重试。
5. 只读命令遇到浮窗：报告受限，不关闭、不停止、不启动 Studio。
6. Python 默认实现失败时，不得在已执行副作用后自动切换 PowerShell 重做；只允许在任何点击前、安全可判定时回退。

12.2 关键异常表

---

13. 验收标准

13.1 P0 验收

13.2 P1 验收

13.3 发布门槛

• 所有 P0、P1 自动化验收通过。
• 代码评审确认没有扩大 Edge/Bot 清理范围。
• SKILL.md 与 --help 对新命令、确认和退出码一致。
• 完成一次受控现场 smoke：只读查询必测；直接运行和关闭浮窗仅在用户明确授权、白名单应用和可恢复环境下测试。
• 现场测试产生的运行/停止不作为自动 CI 的组成部分。

---

14. 测试矩阵

测试实现要求：

• 保留当前纯函数断言的有效部分，但拆分为可报告用例；失败必须指出用例名。
• 降低“源码必须包含某字符串”式测试比例，改为调用函数/CLI 并断言行为。
• Mock 必须记录 UI 调用序列，能断言“确认前零点击”“stop 先于 close”“旧 handle 不再操作”。
• 测试不得把历史真实运行记录当作当前回归证明。

---

15. 版本迁移与兼容策略

15.1 CLI 迁移

15.2 行为变化说明

• 过去“用户已确认运行”可能被用于参数弹窗继续；v2 只有当 direct 策略在首次计划中明确声明时，--yes-run 才覆盖该二次点击。
• 独立接管已有参数弹窗必须使用专用 direct 确认。
• 过去关闭临时脚本以方法返回 true 代表成功；v2 将“窗口已关闭”和“任务停止已验证”分开，可能返回 partial。
• 过去互动选择可多选；v2 因单实例安全约束改为单选。
• 旧调用方若只判断 exit 0/1，必须升级为理解 exit 2~7 或至少把所有非 0 视为未成功。

15.3 发布步骤

1. 先落地错误码、结果对象、参数互斥和 mock 测试。
2. 实现 Python direct/close 正式入口及确认。
3. 对齐 PowerShell P0 安全语义，或对未支持能力明确阻断。
4. 更新 SKILL.md、help、临时脚本转发和迁移说明。
5. 运行静态、单元、mock、只读集成测试。
6. 获得用户单独确认后进行受控现场验收。

---

16. 待确认项

---

17. 需求追溯

---

18. 最终交付物

• 更新后的 SKILL.md 与 --help。
• Python 默认实现的正式 direct/close 命令、参数策略和输出契约。
• PowerShell 回退的 P0 安全语义对齐或显式不支持提示。
• 单元、mock、CLI 契约、静态和只读集成测试。
• 临时脚本弃用转发与版本迁移说明。
• 一份现场验收记录，清晰区分“点击成功、启动已观测、业务结果未知”。

---

*本需求尊重原 PRD 的增量升级范围，核心聚焦参数弹窗直接运行与关闭浮窗恢复，不扩展为整个 RPA 系统重构。*