@qing3a/flow-rpa-app 0.4.1 → 0.4.3

package/README.md

@@ -0,0 +1,56 @@
+# flow-rpa-app —— 本地 RPA 执行引擎（给 Agent 用）
+
+flow-rpa 是本地 RPA 引擎：解释执行**流程定义**（JSON 数据），拟人化操作用户本地的浏览器（CDP），
+产生结构化执行记录。**使用者是用户的 Agent**：用户只给一句话 + 本包名，Agent 按下面序列自举，
+人工只做「引擎浏览器登录一次」。
+
+## 安装与自举（Agent 按序执行）
+
+```bash
+# 1. 安装（公共 npm；镜像同步延迟时加 --registry=https://registry.npmjs.org）
+npm i -g @qing3a/flow-rpa-app
+
+# 2. 初始化（创建数据/流程目录 + 引导）
+flow-app init
+
+# 3. 体检（目录/流程解析/Edge/锁）——必须通过项：目录、流程解析、无警告、锁；
+#    平台未配置项可忽略（仅影响观察/流程同步，本地模式正常使用）
+flow-app doctor
+
+# 4. 启动常驻服务（--http-port 可改；--edge 必填：从零环境无 9222 调试实例时引擎靠它拉起专用浏览器）
+flow-app --http --http-port 3111 --flows <流程目录> --data <数据目录> --edge "<Edge 可执行文件路径>"
+#    Windows 默认路径示例：C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
+#    替代：外部已用 --remote-debugging-port=9222 拉起 Edge 时可省略 --edge（引擎复用调试实例）
+
+# 5. 挂引擎级 skill 到 Agent 平台的 skills 目录（幂等，带版本标注）
+flow-app install-skill <你的 skills 目录>
+```
+
+- **MCP 地址**：`http://127.0.0.1:3111/mcp`（`--http-port` 可改）
+- **状态页**：`http://127.0.0.1:3111/status.json`（只读：版本/浏览器连接/队列/锁/流程列表）
+- 已装好/已连上的：直接跳过安装，用 `get_status` 预检后跑流程（详见包内 skill）
+
+## Skill 位置
+
+- 包内：`skill/flow-rpa-engine.md`（引擎能力说明书：13 个 MCP 工具签名、调用规则、失败处理）
+- `flow-app install-skill <dir>` 自动拷贝到目标目录并标注版本；也可直接从 npm 包目录读
+
+## 首次使用（唯一人工步骤）
+
+引擎用**专用浏览器（独立 profile）**：第一次跑流程前需人工登录目标平台一次。
+**用户日常浏览器登录 ≠ 引擎已登录**（profile 隔离）；未登录时报「登录页/未登录」，人工登录后再跑。
+
+## 安全边界
+
+- **登录一次**：仅首次人工登录，之后全自动化
+- **防封**：同站节流 15~70s 引擎强制；跑真实流程前**同站冷却 ≥2h 优先**（冷却不足时点击
+  60-500s/次、run 时长拉长——属平台节奏非引擎故障，不要重试/不要绕过闸门）
+- **不做**：无人值守调度（一切由 Agent 对话驱动）、L3 自主探索（不直接操作页面元素）、
+  绕过同站闸门/修改冷却参数、自动应用未成熟建议（结构改动必须人工确认 confirm:true）
+
+## 工具面（13 个 MCP 工具）
+
+`get_status` / `list_flows` / `run_flow` / `get_run` / `cancel_run` / `validate_flow`
+（核心执行）+ `list_suggestions` / `apply_suggestion` / `dismiss_suggestion`（学习与建议）
++ `export_observation` / `sync_pending_uploads` / `get_perf` / `pkg_update`（运维，仅 owner）。
+签名与调用规则见包内 `skill/flow-rpa-engine.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qing3a/flow-rpa-app",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "description": "flow-rpa 应用壳（原 app crate）：MCP server + CLI",
   "publishConfig": {
@@ -28,7 +28,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@qing3a/flow-rpa-engine": "^0.4.1",
+    "@qing3a/flow-rpa-engine": "^0.4.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   }

package/skill/flow-rpa-engine.md

@@ -7,6 +7,44 @@
 
 ---
 
+## 〇、首次使用/自举（Bootstrap）——从零到能跑
+
+> 适用：引擎还没装好（Agent 接到任务时）。已装好/已连上的跳过本节，直接进「典型调用序列」。
+
+### 0.1 检测是否已安装
+
+- 先试 `flow-app doctor`（或 MCP `get_status`）：**命令不存在（command not found）或连不上 → 引擎未安装/未启动**
+- `flow-app doctor` 6 项体检（数据/流程目录、流程解析+警告、平台配置、Edge 可执行、单实例锁）——**修到全部通过再继续**
+
+### 0.2 安装序列（依次执行）
+
+1. `npm i -g @qing3a/flow-rpa-app`（公共 npm；镜像同步延迟时加 `--registry=https://registry.npmjs.org`）
+2. `flow-app init`（创建数据/流程目录 + 4 步引导）
+3. `flow-app doctor`（体检：目录可写、流程合法、Edge 路径、锁无冲突）
+   - **必须通过**：flows/data 目录、流程可解析、流程定义无警告、单实例锁
+   - **Edge 项**：传 `--edge <路径>` 后通过（见第 4 步）；平台未配置项**可忽略**（仅影响观察/流程同步，本地模式正常使用）
+4. `flow-app --http --http-port 3111 --flows <流程目录> --data <数据目录> --edge "<Edge 可执行文件路径>"`（启动常驻服务；端口可改）
+   - `--edge` 必填（从零环境无 9222 调试实例时，引擎靠它拉起专用浏览器）；Windows 默认路径示例：`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`
+   - 替代：外部已用 `--remote-debugging-port=9222` 拉起 Edge 时可省略（引擎复用调试实例）
+   - MCP 地址：`http://127.0.0.1:3111/mcp`；状态页：`http://127.0.0.1:3111/status.json`
+5. `flow-app install-skill <Agent 的 skills 目录>`（把引擎级 skill 拷到 Agent 平台，覆盖安装幂等，带版本标注）
+
+### 0.3 首次登录（唯一的人工步骤）
+
+- 引擎用**专用浏览器（独立 profile）**：第一次跑流程前，人工在引擎浏览器里登录目标平台一次
+- **用户日常浏览器登录 ≠ 引擎已登录**（profile 隔离）；未登录时报「登录页/未登录」类错误，告知用户处理，不要重试流程
+
+### 0.4 冷却提示（防封节奏，USAGE-ISSUES #18）
+
+- 跑真实流程前**同站冷却 ≥2h 优先**（冷却 ≥5h 实证点击恢复正常 3-6s）
+- 冷却不足时点击动作 60-500s/次、run 时长显著拉长——**属平台节奏，非引擎故障**；不要重试、不要绕过同站闸门
+
+### 0.5 自举完成
+
+- 用 `get_status` 预检（浏览器连接/队列/锁/平台配置）→ 进入下文「典型调用序列」
+
+---
+
 ## 一、这是什么
 
 flow-rpa 是本地 RPA 执行引擎：它解释执行**流程定义**（JSON 数据），拟人化操作用户本地的浏览器（CDP），产生结构化执行记录，并把脱敏统计上传到协作平台（md-forge）。
@@ -68,6 +106,7 @@ Agent 按自己被赋予的角色调用，超出裁剪集的工具会报「工
 - **引擎默认使用专用浏览器（独立 profile）**：首次使用需人工登录一次（引擎会拉起自己的浏览器实例，登录目标平台后即可）——登录态与用户日常浏览器**隔离**，用户日常登录 ≠ 引擎已登录
 - 可选能力：若用户主动以调试模式（9222）启动了浏览器，引擎可复用其登录态（不鼓励给日常浏览器开调试模式——同 profile 双进程有锁冲突风险）
 - 同站节流：同一站点两次执行间隔**随机 15~70 秒**（引擎强制，2026-08-26 owner 拍板修订，原 ≥10 分钟为起步值）；间隔不足会被拒（返回需等待时间）——**不要自行绕过或频繁重试**
+- **冷却节奏（USAGE-ISSUES #18，2026-08-27 诊断）**：目标站点对自动化访问有**交互响应节流**——同站冷却不足（<2h）时点击动作 60-500s/次（run 时长显著拉长）；冷却 ≥5h 后点击恢复 3-6s。跑真实流程前**同站冷却 ≥2h 优先**（点击正常且反封安全）；冷却不足时预计 run 时长大幅增加，属平台节奏而非引擎故障
 
 **参数组装**
 - `vars` 按 `list_flows` 返回的 `inputs` 声明组装（`{name, required, description}`）；值为字符串