octopus-rpa-app-runner 技能升级 PRD

原始文件：wecom_fa808185_octopus-rpa-app-runner_技能升级PRD_20260806.md

octopus-rpa-app-runner 技能升级 PRD

基于 2026-08-06「招聘Agent告警群」真实人机对话与实战用例整理
用于升级八爪鱼 RPA 应用控制技能（Windows UI Automation / pywinauto）

---

一、文档信息

项目内容
文档名称octopus-rpa-app-runner 技能升级 PRD
版本v1.0
日期2026-08-06（Asia/Shanghai）
来源招聘Agent告警群（wecom:group:wrGWBkBwAAkg6X8OPUPvHLSKFBG8QGPQ）真实对话与操作记录
目标将本次会话中暴露出的真实用例、边界场景与临时脚本实践沉淀为技能升级需求
技能现状octopus-rpa-app-runner（E:\workspace\ogl-rpa\skills\octopus-rpa-app-runner，已安装至工作区）

---

二、背景与目标

本技能用于通过 Windows UI Automation / pywinauto 操作八爪鱼 RPA（Octopus RPA Studio）应用：列出应用、选择应用、运行应用、查看运行状态、停止/恢复界面等。

2026-08-06 在真实生产环境中完成了一次完整链路：安装技能 → 列出应用 → 运行「下载简历」→ 处理参数对话框 → 运行「新招呼求简历」→ 关闭运行浮窗恢复界面。过程中出现了技能文档未覆盖的边界场景，需要通过临时脚本补足，这些正是本次升级的核心输入。

本次要解决的问题

---

三、完整对话时间线（原始记录）

以下为 2026-08-06 群内与 RPA 相关的全部轮次，按时间顺序整理。

3.1 安装技能

用户："@RPA远程电脑机器人 安装技能http://git-repositories.zuzuche.com:10081/human-resources/ogl-rpa.git"

助手动作：尝试 git clone → 本机无 git 命令 → 改用 curl 探测 → GitLab 私有仓库需认证（401）→ 请求用户提供凭据或本地路径。

用户："@RPA远程电脑机器人 技能在E:\workspace\ogl-rpa\skills 叫 octopus-rpa-app-runner"

助手动作：读取 SKILL.md 与脚本 → 复制技能到工作区 → 创建 .venv → 安装 pywinauto 0.6.9 / pywin32 312 / comtypes 1.4.16 → py_compile 通过 → tests_static.py 通过 → CLI --help 正常。技能安装完成。

3.2 首次运行（下载简历）

用户："@RPA远程电脑机器人 运行RPA"

助手动作：--current-running → RUN_LIST_STATE=empty（无任务在跑）→ --list-only 列出 8 个应用 → 引导用户选择。

用户："@RPA远程电脑机器人 1"

助手动作：确认目标 = OGL_BOSS_下载简历_生产_v1.0.2 → 请求运行确认。

用户："@RPA远程电脑机器人 确认"

助手动作：--run-exact-name ... --yes-run → 点击运行按钮成功 → 但弹出了运行参数对话框，且对话框有多个输入框 → 脚本报错 Run parameter dialog has multiple possible inputs; refusing low-confidence auto-fill. → 应用未真正启动。

用户："@RPA远程电脑机器人 3. 直接点运行"

助手动作：写临时脚本 scripts/click_run_app_direct.py（复用技能内部函数，直接定位参数对话框并点击"运行应用"按钮）→ 首次执行报 AttributeError（类名写错）→ 修正为 OctopusPywinautoRunner → 执行成功 CLICKED_RUN_APPLICATION → --current-running 显示八爪鱼进入浮动运行窗口 → --process-snapshot 确认 Studio / BrowserBridge / msedge 进程拉起。任务启动成功。

用户："@RPA远程电脑机器人 截屏发出来"

助手动作：desktop_screenshot + 发送。说明纯文本模型无法看图，等待用户描述。

3.3 恢复界面

用户："@RPA远程电脑机器人 运行rpa"

助手动作：--current-running → 八爪鱼仍处于浮动运行窗口模式 → 询问用户意图（A 停止后重选 / B 查状态 / C 停窗口恢复界面）。

用户："@RPA远程电脑机器人 3"

助手动作：--stop-run-window → 报 Stop button was not found in run window. → 写临时脚本 scripts/close_run_window_direct.py（调用技能内部 close_run_window_if_present，先尝试停止再关闭浮窗）→ 执行成功 Closed Octopus run window to restore Studio. → --current-running 验证 RUN_LIST_STATE=empty。界面恢复正常。

3.4 再次运行（新招呼求简历）

用户："@RPA远程电脑机器人 运行rpa"

助手动作：--list-only 列出 8 个应用 → 引导用户选择。

用户："@RPA远程电脑机器人 7"

助手动作：确认目标 = OGL_BOSS_新招呼_求简历_生产_常用语版_v2.0.2 → 请求运行确认。

用户："@RPA远程电脑机器人 yes"

助手动作：--run-exact-name ... --yes-run → 点击运行按钮成功 → 本次未出现参数对话框 → Done → --current-running 显示八爪鱼进入浮动运行窗口。任务启动成功。

用户："@RPA远程电脑机器人 截屏发出来"

助手动作：desktop_screenshot + 发送。

---

四、用例场景（Use Cases）

按本次实战归纳的典型用例，作为技能行为规范的验收基准。

UC-01：安装技能（本地目录）

UC-02：列出可用应用

UC-03：运行指定应用（标准路径）

UC-04：参数对话框多输入框（本次新增边界）

UC-05：恢复界面（停止/关闭运行浮窗）

UC-06：运行前确认与安全

---

五、非技能指导下的临时脚本实践

本次会话中，两个技能内置模式未覆盖的场景由临时脚本补足。这些脚本直接复用技能内部函数，是技能升级的直接素材，应被吸收为正式 CLI 模式。

5.1 click_run_app_direct.py（参数对话框直接点运行）

背景：技能 run_app_by_name 点击运行按钮后调用 handle_run_parameter_dialog，多输入框时 raise，导致应用未启动。

做法：新建脚本，复用 OctopusPywinautoRunner.find_run_parameter_dialog_root / descendants / control_type / text_of / invoke / RUN_APP_BUTTON_NAME，定位对话框后直接点击"运行应用"按钮，不填任何输入框。

踩坑：首次实例化用 M.OctopusRpaAppRunner() → AttributeError（模块内无此类）→ 修正为 M.OctopusPywinautoRunner() 成功。

结果：CLICKED_RUN_APPLICATION → 应用成功启动。

# 核心逻辑（简版）
import OctopusRpaAppRunner as M
runner = M.OctopusPywinautoRunner()
dialog = runner.find_run_parameter_dialog_root()   # 轮询最多12秒
for d in M.descendants(dialog):
    if M.control_type(d) == "Button" and M.text_of(d) == M.RUN_APP_BUTTON_NAME:
        runner.invoke(d, "run application button (manual)")
        print("CLICKED_RUN_APPLICATION")

5.2 close_run_window_direct.py（关闭运行浮窗恢复界面）

背景：--stop-run-window 仅尝试点击"停止"按钮，找不到停止按钮时失败（WARN），无法恢复 Studio 界面。

做法：新建脚本，直接调用技能内部方法 close_run_window_if_present（内部实现：先尝试停止 → 关闭浮窗 → 恢复 Studio）。

结果：CLOSED_RUN_WINDOW_OK → --current-running 验证 RUN_LIST_STATE=empty。

# 核心逻辑（简版）
import OctopusRpaAppRunner as M
runner = M.OctopusPywinautoRunner()
ok = runner.close_run_window_if_present()   # 先stop后close
print("CLOSE_RUN_WINDOW_OK" if ok else "NO_RUN_WINDOW_OR_FAILED")

5.3 教训与沉淀

---

六、技能升级需求（Requirements）

REQ-01：新增 --click-run-app-direct 模式

REQ-02：新增 --close-run-window 模式

REQ-03：参数对话框交互升级

REQ-04：SKILL.md 补充类名与函数复用说明

REQ-05：用例回归与验证

---

七、附录

7.1 当前可用 CLI 参数（安装后 --help 实测）

--list-only                 只列应用，不运行
--run-exact-name NAME       运行指定完整应用名
--run-latest-by-prefix KEY  按前缀运行最高版本
--check-run-list / --current-running  只读查询运行列表
--process-snapshot          打印进程快照
--stop-run-window           尝试点击停止按钮
--restart-studio-clean      清理残留进程并重启 Studio
--skip-run-parameter-dialog 跳过参数对话框等待/填充
--yes / --yes-run           跳过运行确认
--yes-restore-existing-run  同意停止/关闭已有运行浮窗

7.2 群内 8 个可运行应用

OGL_BOSS_下载简历_生产_v1.0.2
OGL_BOSS_二次复聊_all_检查_发送话术_v1.0.6
OGL_BOSS_二次复聊_step1_检查_v2
OGL_BOSS_二次复聊_step2_自动发送_v2.0.1
OGL_BOSS_新招呼_求简历_生产
OGL_BOSS_新招呼_求简历_生产_常用语版_v1
OGL_BOSS_新招呼_求简历_生产_常用语版_v2.0.2
OGL_BOSS_筛选在线简历和打招呼_生产_v1.0.3

7.3 临时脚本清单

---

*文档由 QwenPaw 机器人（default）基于招聘Agent告警群实战对话自动整理*