flow-rpa-app —— 本地 RPA 执行引擎（给 Agent 用）

flow-rpa 是本地 RPA 引擎：解释执行流程定义（JSON 数据），拟人化操作用户本地的浏览器（CDP）， 产生结构化执行记录。使用者是用户的 Agent：用户只给一句话 + 本包名，Agent 按下面序列自举， 人工只做「首次跑流程时在引擎弹出的浏览器里登录目标平台一次」。

给用户的一句话引导语（复制即用）

帮我 [一句话任务]。用本地 RPA 引擎 @qing3a/flow-rpa-app 执行：如果没装，先 npm i -g @qing3a/flow-rpa-app --registry=https://registry.npmjs.org，装完读包内 README 和 skill/flow-rpa-engine.md 自举；首次跑流程时引擎会自动弹出专用浏览器，我会在里面登录一次目标平台。

说明：不要用 npmjs.com 网页 URL 抓取文档（网页抓取常失败）；直接执行上面的安装命令， 装完后从包内读 README 与 skill（node_modules/@qing3a/flow-rpa-app/ 下，或用 flow-app install-skill）。

安装与自举（Agent 按序执行，Windows PowerShell 环境默认）

# 1. 安装（公共 npm；成功标志 = 输出 "added N packages"；npm 的 stderr 升级通知可忽略）
npm i -g @qing3a/flow-rpa-app --registry=https://registry.npmjs.org

# 1.5 装后先验证（防 PATH 混乱/装错目录：确认版本与你预期的 npm 前缀一致）
flow-app --version   # 应输出当前版本（≥0.6.0）；若版本不对，检查 PATH 里 node/npm 来自哪个安装目录

# 2. 初始化（创建数据/流程目录 + 引导；**装完自带 1 个 starter 流程 boss_search_jobs**，init 自动复制到 flows/）
flow-app init

# 3. 体检（✅ 通过 / ⚠️ 可忽略 / ❌ 阻断；仅 ❌ 退出码非 0）
#    可先单独体检 Edge 项：
flow-app doctor --edge "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
#    空流程/Edge 未配置均属 ⚠️ 可忽略（本地模式正常）

# 4. 启动常驻服务（--edge 必填：从零环境无 9222 调试实例时引擎靠它拉起专用浏览器）
#    PowerShell 专属写法（引号内的空格/括号不会被拆坏）：
$edge = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
flow-app --http --http-port 3111 --flows <流程目录> --data <数据目录> --edge $edge
#    或外部已用 --remote-debugging-port=9222 拉起 Edge 时可省略 --edge（引擎复用调试实例）

# 5. 挂引擎级 skill 到 Agent 平台的 skills 目录（幂等，带版本标注 + SKILL.md 结构）
flow-app install-skill <你的 skills 目录>

• MCP 地址：http://127.0.0.1:3111/mcp（--http-port 可改）
• 健康检查：GET http://127.0.0.1:3111/status.json（不需要 Accept 头）
• MCP 握手：POST /mcp 需带 Accept: application/json, text/event-stream（缺头返回 406 及说明体）
• 中文参数：MCP 客户端 JSON 序列化必须 UTF-8（引擎按 UTF-8 解析；输入变 ? 时用 DEBUG_HEX=1 启动引擎查 [hex] 日志）。PowerShell 直测必须转 UTF-8 字节：$bytes = [System.Text.Encoding]::UTF8.GetBytes($body) 再 -Body $bytes -ContentType "application/json; charset=utf-8"（IWR 字符串 Body 默认 GBK 会污染中文）；正式验收用真实 agent / Node MCP SDK 客户端
• 正常初始状态：未跑流程前 status.json 的 browser.connected=false、flows=[] 均为正常—— 浏览器是懒加载的（首次 run_flow 才弹出），流程需先获取（见下节）
• 要求 Node ≥ 20（package.json engines 声明）

流程包获取

本包内置 1 个 starter 流程：boss_search_jobs（BOSS 搜索职位）——flow-app init 首次初始化自动复制到 flows/（同名已存在则跳过，不覆盖本地定制版本）。

更多流程由 owner 分发：把流程包目录（含 flow.json）直接放入 flows/ 即可（结构可用 flow-app validate <flow.json> 校验）。

Skill 位置

• 包内：skill/flow-rpa-engine.md（引擎能力说明书：12 个 MCP 工具签名、调用规则、失败处理）
• flow-app install-skill <dir> 写入 <dir>/flow-rpa-engine/SKILL.md（SKILL.md 子目录结构，主流平台自动发现）
  • 平铺 <dir>/flow-rpa-engine.md（兼容）；若平台不识别子目录，按平铺路径引用
• 也可直接从 npm 包目录读：node_modules/@qing3a/flow-rpa-app/skill/flow-rpa-engine.md

首次登录（唯一人工步骤，二选一）

引擎用专用浏览器（独立 profile data/edge-profile），登录态持久（后续 run 复用 9222 或重启浏览器均保持）。

• 方案 A（推荐，先登录再跑）：flow-app open-browser --edge "<Edge 路径>" --data <数据目录> → 浏览器弹出 → 登录目标平台 → Ctrl-C 关命令（锁释放、浏览器保持）→ 再启动引擎跑流程
• 方案 B（懒加载弹窗）：直接跑流程——首次 run_flow 时引擎弹出浏览器并导航到目标站 → 在弹窗里登录一次 → 流程继续/重跑

用户日常浏览器登录 ≠ 引擎已登录（profile 隔离）；未登录时报「未登录：请先登录」，登录后重跑即可。

安全边界

• 登录一次：仅首次人工登录，之后全自动化（引擎每次 run 后自动轮换浏览器会话，登录态保留——同 profile）
• 防封：同站节流 15~70s 引擎强制；会话轮换优先（引擎每次 run 前自动重启浏览器会话，点击恢复 3-5s）；同站冷却 ≥2h 降级为辅助（平台关注度管理）；翻页护栏（页间 15~25s 节拍、单步 ≤20 页 / 单 run ≤30 页、翻页后同站再冷却 150~300s 随机，流程参数只能调慢）；不要重试/不要绕过闸门
  • 闸门锚点是「实际访问的站点」（0.6.7 起）：没有 navigate 步骤的流程（手工导航后操作当前页）同样受同站节流——若第一次跑完立刻再跑被拒，同站节流：site:…（站点维度）／flow:…（流程维度兜底） 是护栏生效，不是故障：等够间隔再跑
• 流程来源标注（0.6.7 起）：flow-app list / doctor / list_flows 会标 builtin（内置原样）/ builtin-modified（内置被本地改过）/ local（自建）；builtin-modified 只告警不阻断（引擎照你的版本执行），自建流程不受影响
• 不做：无人值守调度（一切由 Agent 对话驱动）、L3 自主探索（不直接操作页面元素）、绕过同站闸门/修改冷却参数、自动应用未成熟建议（结构改动必须人工确认 confirm:true）
• 先查引擎再自研：页面交互遇阻时，先查引擎能力/包内 SKILL（skill/flow-rpa-engine.md）再决定自研；自研仅兜底（如复用引擎已注入页面的 window.__rpaDom），探索出的新交互回写流程，不长期维护并行自研代码
• 引擎护栏只保护「走引擎跑的流程」——自己写脚本直连浏览器不受任何保护：上面这些护栏（拟人动作、同站节流、翻页节奏、验证码中止、掩码、运行记录）都长在引擎进程里。另写一个脚本连上引擎用的那个浏览器调试端口去操作页面，等于所有护栏同时离场：节奏由脚本常量决定、没有 runId、没有验证码检测、出了事没有记录。这不是配置问题，改任何参数都补不回来——要么走引擎流程，要么由你自行承担平台风控后果
  • 本案复盘（真实事故）：远程用户用自写脚本直连引擎浏览器的调试端口跑猎聘，脚本里写死「每页间隔 8~15 秒 + 每 5 页停 12 秒 + 关键词之间零冷却」，连续跑 6 个关键词，约 180 页 / 40 分钟不间断，随后命中平台验证码页。注意：引擎当时报的「第 21 页」不是页数阈值，是累积访问量到了——这类脚本没有冷却、没有节律扰动，出事只是时间问题
• 不要与引擎共用同一个 9222 端口 / 同一个 profile 并行操作：引擎每次 run 前都会重启浏览器会话（会话轮换，重启后重新打开页面）；脚本与引擎并行 → 两边互相打断：脚本刚打开的页面被引擎重启掉、脚本占着 profile 又让引擎连不上。要自己调试，就单独开一个浏览器实例（另一个调试端口 + 另一个 profile 目录），或者只在引擎完全闲置时临时用一下——不要两边同时操作同一个账号
• 遇阻先查引擎能力，不要用「合成事件」替代拟人动作：页面交互失败时先查包内 SKILL（skill/flow-rpa-engine.md）的调用规则与失败处理（很多「点不动」的问题引擎已经解决——如输入框联想下拉遮挡导致真实点击落空，引擎会先关下拉再点）。不要用直调页面组件的 onClick、element.click()、手工派发 input/change 事件去「硬点」——这些动作平台侧看得出不是人做的（无鼠标轨迹、事件对象残缺），等于自己给账号加风险指纹

工具面（12 个 MCP 工具）

get_status / list_flows / run_flow / get_run / cancel_run / resume_run / validate_flow （核心执行）+ list_suggestions / apply_suggestion / dismiss_suggestion（学习与建议）

• export_observation / get_perf（运维，仅 owner）。 签名与调用规则见包内 skill/flow-rpa-engine.md。

其它 CLI

• flow-app --help / --version：用法 / 版本
• flow-app unlock：清理过期/残留单实例锁（pid 已死的死锁；存活实例的锁不动）
• flow-app list / validate <flow.json>：流程查看 / 校验

改到拟人动作层（输入/点击语义）的开发者：仓库根有真实浏览器冒烟门 pnpm smoke:browser （opt-in，不进 pnpm test；前置 pnpm build，端口/环境变量见 docs/SMOKE-BROWSER.md）。