@qing3a/flow-rpa-app 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@qing3a/flow-rpa-app",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "flow-rpa 应用壳（原 app crate）：MCP server + CLI",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "flow-app": "dist/main.js"
+  },
+  "main": "./dist/main.js",
+  "types": "./dist/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "skill"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/build-skill.mjs",
+    "test": "vitest run --root ../.. --project app",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@qing3a/flow-rpa-engine": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
+  }
+}

package/skill/flow-rpa-engine.md

@@ -0,0 +1,102 @@
+<!-- 由 docs/SKILL-ENGINE.md 构建生成（M11c D-K1），勿手改；改 docs 真源后重跑 pnpm build -->
+# 引擎级 skill 初稿：flow-rpa 本地 RPA 引擎（契约版）
+
+> 状态：**初稿**（2026-08-25，基于已冻结的 MCP 工具面契约；M11 打包进 npm 时按实现校对）
+> 用途：挂载在 npm 包内作为「引擎级 skill」的唯一真源（ARCHITECTURE #10），安装时同步/链接到 Agent 平台的 skills 目录。
+> 分工：本 skill 只讲「怎么调引擎」；业务编排（何时调、调哪个流程）在业务级 skill（外部/平台分发）。
+
+---
+
+## 一、这是什么
+
+flow-rpa 是本地 RPA 执行引擎：它解释执行**流程定义**（JSON 数据），拟人化操作用户本地的浏览器（CDP），产生结构化执行记录，并把脱敏统计上传到协作平台（md-forge）。
+
+- **流程是数据**：执行什么由 flow.json 决定，引擎不含业务逻辑。
+- **接口是 MCP**：本引擎通过 MCP 工具被 Agent 调用（stdio 传输，进程由 Agent 拉起）。
+- **流程级工具面**：只提供「跑流程/查结果/管建议」等流程级工具，**不提供**页面原子操作（点击/输入/截图等），也不提供业务工具。
+
+## 二、工具面（12 个，签名冻结；get_status 为第 12 个，2026-08-25）
+
+### 核心执行
+
+| 工具 | 参数 | 返回 | 说明 |
+|---|---|---|---|
+| `get_status` | 无 | 引擎状态 JSON（版本/skill 版本/浏览器连接/队列/锁/流程列表/上传台账/platform） | **调用流程前预检环境**：浏览器是否连接、队列是否忙、锁是否被占、平台是否配置；platform 不含 token |
+| `list_flows` | 无 | 流程列表（id/name/version） | **调用任何流程前先查这里**，不要硬编码流程 id（流程包会更新） |
+| `run_flow` | `flow_id`（必填）、`vars`（可选，如 `{"keyword":"算法工程师"}`）、`wait`（可选，默认 false） | `{runId, status:'running'\|'done'\|'failed', error?}` | **异步**：wait=false 立即返回 runId，用 `get_run` 轮询；流程含 30~60s 冷却，同步等待会超时 |
+| `get_run` | `run_id` | run.json 全量（每步 verify/耗时/失败类别） | 轮询直到 status 为 done/failed；**步骤级**看哪步失败 |
+| `validate_flow` | `json` 或 `path` | `{valid, flowId?, error?}` | 校验流程定义 |
+
+### 学习与建议
+
+| 工具 | 参数 | 返回 | 说明 |
+|---|---|---|---|
+| `list_suggestions` | `flow_id?` | 建议列表（来源 local/platform、状态 pending/mature、样本数） | L2 学习产物；**未成熟建议必须人工确认后才能应用** |
+| `apply_suggestion` | `suggestion_id`、`confirm`（布尔） | 应用结果 | 结构改动铁律：pending 建议必须 confirm=true；mature 建议可自动 |
+| `dismiss_suggestion` | `suggestion_id` | 忽略结果 | 人工处置，不再展示 |
+
+### 运维（仅 owner / 开发期，不暴露给最终用户）
+
+| 工具 | 说明 |
+|---|---|
+| `export_observation` | 把一次执行导出为观察报告包（观察通道；本地模拟/真实平台上传） |
+| `sync_pending_uploads` | 重试待上传的观察包（断网恢复入口） |
+| `get_perf` | 端到端性能基准（质量门数据） |
+| `pkg_update` | 从 md-forge 更新流程包（拉 manifest → 版本比对 → 下载 → 哈希校验 → 替换） |
+
+## 三、典型调用序列
+
+```
+0. get_status（可选）        → 预检环境：浏览器是否连接、队列是否忙、锁是否被占、平台是否配置
+   （浏览器未连接 / 锁被其他实例持有 → 先处理环境再调流程，见「失败处理·环境类」）
+1. list_flows                → 确认流程 id + **inputs 参数声明**（每个流程要什么变量）
+2. run_flow(flow_id, vars)   → {runId, status:"running"}
+   vars 按 list_flows 返回的 inputs 组装；缺必填参数引擎会报「缺少必填参数: {name}」
+3. get_run(runId) 轮询       → status=done → 读 steps 结果
+   （轮询间隔建议 3~5s；流程含冷却，跑完可能要几分钟）
+4. 流程失败 → 看 error 与失败步骤的 verify/失败类别 → 决定重试/换词/人工
+```
+
+## 四、调用规则
+
+**前置条件（2026-08-25 定案：独立 profile 优先）**
+- **引擎默认使用专用浏览器（独立 profile）**：首次使用需人工登录一次（引擎会拉起自己的浏览器实例，登录目标平台后即可）——登录态与用户日常浏览器**隔离**，用户日常登录 ≠ 引擎已登录
+- 可选能力：若用户主动以调试模式（9222）启动了浏览器，引擎可复用其登录态（不鼓励给日常浏览器开调试模式——同 profile 双进程有锁冲突风险）
+- 同站节流：同一站点两次执行间隔 ≥10 分钟（引擎强制）；间隔不足会被拒（返回需等待时间）——**不要自行绕过或频繁重试**
+
+**参数组装**
+- `vars` 按 `list_flows` 返回的 `inputs` 声明组装（`{name, required, description}`）；值为字符串
+- 循环索引 `{i}` 由引擎注入，不要传
+
+**结果解读**
+- run.json 的 `status`：done / failed
+- 每步记录：`status`（done/failed）、`verify`（验证点结果：passed/durationMs）、`durationMs`、失败时 `error`（已脱敏掩码）
+- extract 步骤：`field`（字段标签）、`count`（命中数）、`saved`（是否落盘本地明细）
+- `selectorHit`：实际生效的选择器（页面改版排查用）
+
+**失败处理**
+- `索引越界`：循环内列表耗尽，**正常终止不是错误**，流程仍为 done
+- 验证码 / 环境验证：**立即停止，告知用户人工处理**，绝不自动重试（执行树级风险事件）
+- **环境类失败（首次使用必踩，重点）**：
+  - `浏览器未就绪` / 9222 连不上 → 引擎浏览器没启动或调试端口不可用 → **告知用户检查/启动引擎浏览器**，不要重试流程（调用前可用 `get_status` 预检 `browser.connected`）
+  - 登录页 / 未登录 → 引擎浏览器的登录态失效或从未登录 → **告知用户在引擎浏览器里登录目标平台**，不要重试流程
+  - 引擎浏览器与用户日常浏览器是隔离的 profile——用户日常登录 ≠ 引擎已登录
+- 其他失败：看失败步骤与类别；重试前先确认前置条件（登录态/节流），**重试最多一次**
+
+**禁止事项**
+- ❌ 不直接操作浏览器页面（无此工具；那是 L3 自主探索，明确不做）
+- ❌ 不绕过同站闸门 / 不修改冷却参数
+- ❌ 不自动应用 pending 建议（人工确认铁律；除非用户明确同意，不得传 confirm:true）
+- ❌ 不把业务判断写成引擎工具调用链的循环（业务编排在业务级 skill）
+- ❌ 不使用运维工具（export_observation 等）除非你是 owner 且明确需要
+
+## 五、与业务级 skill 的关系
+
+- 本 skill：引擎能力说明书（npm 包内，随版本更新）
+- 业务级 skill（如「猎头工作流」）：何时调、调哪个流程、业务规则（外部维护或平台分发）
+- 冲突时：业务级 skill 管「做什么」，本 skill 管「怎么调」
+
+## 六、版本与同步
+
+- 本 skill 与引擎版本绑定：npm 包升级 → 本文件更新 → 安装/启动时同步到 Agent skills 目录（带版本标注）
+- 若 Agent 平台已有一份旧拷贝：以「引擎版本 + skill 内容哈希」判断是否需要覆盖