@qing3a/flow-rpa-app 0.5.12 → 0.7.0

package/README.md

@@ -20,7 +20,7 @@ flow-rpa 是本地 RPA 引擎：解释执行**流程定义**（JSON 数据），
 npm i -g @qing3a/flow-rpa-app --registry=https://registry.npmjs.org
 
 # 1.5 装后先验证（防 PATH 混乱/装错目录：确认版本与你预期的 npm 前缀一致）
-flow-app --version   # 应输出 0.4.5+；若版本不对，检查 PATH 里 node/npm 来自哪个安装目录
+flow-app --version   # 应输出当前版本（≥0.6.0）；若版本不对，检查 PATH 里 node/npm 来自哪个安装目录
 
 # 2. 初始化（创建数据/流程目录 + 引导；**装完自带 1 个 starter 流程 boss_search_jobs**，init 自动复制到 flows/）
 flow-app init
@@ -28,7 +28,7 @@ flow-app init
 # 3. 体检（✅ 通过 / ⚠️ 可忽略 / ❌ 阻断；仅 ❌ 退出码非 0）
 #    可先单独体检 Edge 项：
 flow-app doctor --edge "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
-#    平台未配置/空流程/Edge 未配置均属 ⚠️ 可忽略（本地模式正常）
+#    空流程/Edge 未配置均属 ⚠️ 可忽略（本地模式正常）
 
 # 4. 启动常驻服务（--edge 必填：从零环境无 9222 调试实例时引擎靠它拉起专用浏览器）
 #    PowerShell 专属写法（引号内的空格/括号不会被拆坏）：
@@ -50,17 +50,13 @@ flow-app install-skill <你的 skills 目录>
 
 ## 流程包获取
 
-本包**内置 1 个 starter 流程**：`boss_search_jobs`（v6，BOSS 搜索职位）——`flow-app init` 首次初始化自动复制到 `flows/`（同名已存在则跳过，不覆盖用户/`pkg_update` 版本）。更多流程从协作平台 md-forge 获取：
+本包**内置 1 个 starter 流程**：`boss_search_jobs`（BOSS 搜索职位）——`flow-app init` 首次初始化自动复制到 `flows/`（同名已存在则跳过，不覆盖本地定制版本）。
 
-- **发布源**：`https://md-forge-3774306-1256846151.ap-shanghai.run.tcloudbase.com`
-- **示例**：`boss_search_jobs`（v6，BOSS 搜索职位）
-- **方式**：配置平台后 `flow-app` 的 `pkg_update` 工具自动拉取（manifest → 版本比对 → 下载 → 哈希校验 → 替换本地 `flows/<name>/`）
-- **平台凭据**：`--platform-url <url> --platform-token <token>`（token 由 owner 提供，**不写死在包内/文档**）
-- **手工**：也可把流程包直接放入 `flows/` 目录（结构见 `flow-app validate <flow.json>`）
+更多流程由 owner 分发：把流程包目录（含 `flow.json`）直接放入 `flows/` 即可（结构可用 `flow-app validate <flow.json>` 校验）。
 
 ## Skill 位置
 
-- 包内：`skill/flow-rpa-engine.md`（引擎能力说明书：13 个 MCP 工具签名、调用规则、失败处理）
+- 包内：`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`
@@ -78,14 +74,21 @@ flow-app install-skill <你的 skills 目录>
 ## 安全边界
 
 - **登录一次**：仅首次人工登录，之后全自动化（引擎每次 run 后自动轮换浏览器会话，**登录态保留**——同 profile）
-- **防封**：同站节流 15~70s 引擎强制；**会话轮换优先**（0.5.0 起引擎每次 run 后自动重启浏览器会话，点击恢复 3-5s）；同站冷却 ≥2h 降级为辅助（平台关注度管理）；不要重试/不要绕过闸门
+- **防封**：同站节流 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` 事件去「硬点」——这些动作平台侧看得出不是人做的（无鼠标轨迹、事件对象残缺），等于自己给账号加风险指纹
 
-## 工具面（13 个 MCP 工具）
+## 工具面（12 个 MCP 工具）
 
-`get_status` / `list_flows` / `run_flow` / `get_run` / `cancel_run` / `validate_flow`
+`get_status` / `list_flows` / `run_flow` / `get_run` / `cancel_run` / `resume_run` / `validate_flow`
 （核心执行）+ `list_suggestions` / `apply_suggestion` / `dismiss_suggestion`（学习与建议）
-+ `export_observation` / `sync_pending_uploads` / `get_perf` / `pkg_update`（运维，仅 owner）。
++ `export_observation` / `get_perf`（运维，仅 owner）。
 签名与调用规则见包内 `skill/flow-rpa-engine.md`。
 
 ## 其它 CLI

package/dist/cli.d.ts

@@ -1,8 +1,9 @@
 import { type RunConfig } from './config.js';
+import { type ResumePrecheck, type RunFlowResult } from './runner.js';
 /**
  * CLI（移植 Rust `main.rs`，node:util parseArgs）。
- * 参数兼容：--flows / --data / --mock / --port / --edge / --platform-url / --platform-token /
- * list / validate <flow.json>。
+ * 参数兼容：--flows / --data / --mock / --port / --edge / list / validate <flow.json> / run / resume / get。
+ * T029（0.6.0）：--platform-url/--platform-token 与 issues 子命令随 md-forge 退役移除。
  *
  * D-N3 缺省目录语义（M11a 定案）：
  * - 显式 --flows/--data → 用传入值
@@ -16,8 +17,6 @@ export interface CliOptions {
     mock: boolean;
     cdpPort?: number;
     edgePath?: string;
-    platformUrl?: string;
-    platformToken?: string;
     /** M11d：--http 常驻模式 */
     http: boolean;
     /** --http-port（默认 3081） */
@@ -26,9 +25,9 @@ export interface CliOptions {
     httpToken?: string;
     /** D3：工具面角色（owner 缺省 / hunter 裁剪集） */
     role?: string;
-    /** T020 P0-3：issues list 状态过滤（--status open 等） */
-    status?: string;
-    /** 位置参数（list / validate <path> / install-skill <dir> / issues <子命令>） */
+    /** T026/B1：run --vars <JSON>（变量插值，对齐 run_flow vars 语义） */
+    vars?: string;
+    /** 位置参数（list / validate <path> / install-skill <dir> / run <flowId> / resume <runId> / get <runId>） */
     positionals?: string[];
 }
 /** D-N3：缺省目录（本地开发 → 仓库根；全局 → ~/.flow-rpa） */
@@ -37,12 +36,12 @@ export declare function defaultDirs(): {
     dataDir: string;
 };
 export declare function parseCli(argv: string[]): CliOptions;
-/** 从 CLI 选项构造 RunConfig（含环境变量兜底 + 平台配置持久化自动加载） */
+/** 从 CLI 选项构造 RunConfig（含环境变量兜底） */
 export declare function configFromCli(opts: CliOptions): RunConfig;
 /**
  * `flow-app init`：首启引导——创建 flows/data 目录 + 复制内置 starter 流程 + 提示下一步
  * （USAGE-ISSUES #1 教训：装完 list 空无引导；T004 P1-5：内置 starter 流程）。
- * 幂等：目录已存在则跳过创建；starter 复制同名跳过（不覆盖用户/pkg_update 版本）。
+ * 幂等：目录已存在则跳过创建；starter 复制同名跳过（不覆盖用户已有版本）。
  */
 export declare function runInit(opts: CliOptions): void;
 /** 体检报告行（T002 #3 三级口径：✅ 通过 / ⚠️ 可忽略 / ❌ 阻断） */
@@ -51,16 +50,31 @@ export interface DoctorLine {
     label: string;
     detail: string;
 }
-/** doctor 体检（纯函数，可单测）：返回报告行 + 退出码（仅 ❌ 令退出码非 0） */
-export declare function doctorReport(opts: CliOptions): {
+/** doctor 体检（纯函数，可单测）：返回报告行 + 退出码（仅 ❌ 令退出码非 0）
+ *  `detectEdge`（T033-2）：Edge 自动探测注入缝（缺省 `defaultEdgePath`）——测试可注入「探测不到」
+ *  以覆盖三态中的「未配置」分支，不依赖跑测机器的 Edge 安装情况。 */
+export declare function doctorReport(opts: CliOptions, detectEdge?: () => string): {
     lines: DoctorLine[];
     exitCode: number;
 };
 /**
- * `flow-app doctor`：体检——flows/data 目录、流程可解析、平台配置、Edge 路径、单实例锁。
+ * `flow-app doctor`：体检——flows/data 目录、流程可解析、Edge 路径、单实例锁。
  * 三级口径（T002 #3）：✅ 通过 / ⚠️ 可忽略（不阻塞）/ ❌ 阻断（令退出码非 0）。
  */
 export declare function runDoctor(opts: CliOptions): void;
+/**
+ * T025/B3：install-skill 常见目标清单（只读探测，不自动写——M11c D-K2 定案不变）。
+ * 只列已验证的平台目录（WorkBuddy/Claude）；其它平台用通用提示（<target-dir> 即可）。
+ */
+export interface SkillTarget {
+    name: string;
+    dir: string;
+    /** 本机该目录是否存在（只读探测） */
+    exists: boolean;
+}
+export declare function installSkillTargets(): SkillTarget[];
+/** install-skill 无参帮助：目标清单 + 已存在标记 + 用法（退出码 2 = 用法错误，与其它子命令一致；以 process.exit 结尾 → never） */
+export declare function printInstallSkillHelp(): never;
 /**
  * M11c D-K2：install-skill —— 拷贝引擎级 skill 到 Agent 平台的 skills 目录。
  * skill 内容来自包内 skill/flow-rpa-engine.md（构建时从 docs/SKILL-ENGINE.md 复制，唯一真源）。
@@ -83,14 +97,33 @@ export declare function detectDefaultEdge(): string | undefined;
  */
 export declare function runOpenBrowser(opts: CliOptions): Promise<void>;
 /**
- * T020 P0-3：反馈消费端读入口 CLI。
- *   flow-app issues list [--status open]  列出反馈 issue（可选状态过滤）
- *   flow-app issues get <id>               查看单个 issue 详情
- *   flow-app issues comment <id> "<文本>"   回复评论（确认闭环）
- * 平台配置来自 CLI/env 或 data/platform.json 持久化（configFromCli）。
+ * T026/B1：--vars 解析（JSON 单参数，对齐 run_flow vars 语义——值必须是字符串）。
+ * 非法 JSON / 非对象 / 非字符串值 → 抛错（调用方转退出码 2 用法错误）。
  */
-export declare function runIssuesCommand(opts: CliOptions): Promise<void>;
-/** CLI 子命令：list / validate / install-skill / init / doctor / unlock / open-browser；返回 true 表示已处理（退出） */
+export declare function parseVarsJson(raw: string | undefined): Record<string, string>;
+/** 运行结果摘要（run/resume 共用输出形态；paused 附 T027/B2 统一指引映射） */
+export declare function formatRunResult(r: RunFlowResult, runsDir: string): string;
+/**
+ * T026/B1：`flow-app run <flowId> [--vars '<JSON>']`——同步执行一个流程（wait:true 语义）。
+ * 复用 server 同一执行路径（spawnRun → executeRun）：串行队列/闸门/落盘/L2 全同源；
+ * 单实例锁与 stdio/--http 互斥（D-R2 语义不变）。owner='cli'（D7 问责：CLI 直跑标识）。
+ * 返回退出码：done/paused → 0（paused 是定义内的人工接管中间态，指引在输出里）；failed → 1；用法错误 → 2。
+ */
+export declare function cliRun(opts: CliOptions, flowId: string | undefined, varsRaw?: string): Promise<{
+    code: number;
+    output: string;
+}>;
+/** T026/B1：`flow-app resume <runId>`——人工接管后从暂停点继续（复用 resumeRun 同一路径；precheck 供测试注入，CLI 实际走缺省探测器）。 */
+export declare function cliResume(opts: CliOptions, runId: string | undefined, precheck?: ResumePrecheck): Promise<{
+    code: number;
+    output: string;
+}>;
+/** T026/B1：`flow-app get <runId>`——读 run.json 摘要（只读，不取锁；paused 附 T027/B2 统一指引）。 */
+export declare function cliGet(opts: CliOptions, runId: string | undefined): {
+    code: number;
+    output: string;
+};
+/** CLI 子命令：list / validate / install-skill / init / doctor / unlock / open-browser / run / resume / get；返回 true 表示已处理（退出） */
 export declare function runCliCommand(opts: CliOptions & {
     positionals?: string[];
 }): Promise<boolean>;