@qing3a/flow-rpa-app 0.5.1 → 0.5.2

package/README.md

@@ -43,7 +43,7 @@ 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]` 日志）
+- **中文参数**：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 声明）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qing3a/flow-rpa-app",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "engines": { "node": ">=20" },
   "type": "module",
   "description": "flow-rpa 应用壳（原 app crate）：MCP server + CLI",
@@ -26,7 +26,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@qing3a/flow-rpa-engine": "^0.5.1",
+    "@qing3a/flow-rpa-engine": "^0.5.2",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   }

package/skill/flow-rpa-engine.md

@@ -40,14 +40,17 @@
 
 - 引擎用**专用浏览器（独立 profile `data/edge-profile`）**，登录态持久（后续 run 复用 9222 或重启浏览器均保持）
 - **方案 A（推荐，先登录再跑）**：`flow-app open-browser --edge "<Edge 路径>" --data <数据目录>`
-  → 浏览器弹出（不跑流程）→ 登录目标平台 → Ctrl-C 关命令（锁释放、浏览器保持）→ 再启动引擎跑流程
+  → 浏览器弹出（不跑流程）→ 登录目标平台 → **Ctrl-C 关命令（释放单实例锁；浏览器保持运行）** → 再启动引擎跑流程
+  → ⚠️ **锁 UX**：open-browser 与引擎服务互斥（同一把锁）——用 open-browser 时**先 Ctrl-C 退出再启动服务**；
+  若服务已在跑（持锁），open-browser 会报「另一个实例运行」——先停服务
 - **方案 B（懒加载弹窗）**：直接跑流程——首次 `run_flow` 需要开页面时才弹出浏览器并导航到目标站 → 在弹窗里登录一次 → 流程继续/重跑
 - **用户日常浏览器登录 ≠ 引擎已登录**（profile 隔离）；未登录时引擎报「未登录：请先登录」（不再误报误点），登录后重跑即可
+- ⚠️ **杀进程注意**：强杀引擎服务不会带走其拉起的 Edge（detached）——残留 9222 实例会占 profile 锁，下次启动前可 `flow-app unlock` 或先清 9222 Edge
 
-### 0.4 会话轮换与冷却（防封节奏，T009 策略 A 已拍板）
+### 0.4 会话轮换与冷却（防封节奏，T009/T010 策略 A）
 
-- **会话轮换优先（引擎自动，0.5.0 起）**：每次 run 结束后引擎自动重启浏览器会话（同 profile，登录态保留）——实证新会话点击恢复 3-5s（docs/CLICK-SLOW-DIAGNOSIS.md：点击慢与冷却弱相关、与会话累积强相关）
-- **同站冷却 ≥2h 降级为辅助**：会话轮换后点击正常（3-5s），冷却主要用于平台关注度管理；轮换已覆盖"会话累积节流"场景
+- **会话轮换（引擎自动，0.5.1 起 run 前轮换）**：每次 run 开始前引擎重启浏览器会话（同 profile，登录态保留）——首 run 不复用 open-browser/上次旧会话；实证新会话点击恢复 3-5s（docs/CLICK-SLOW-DIAGNOSIS.md）
+- **同站冷却 ≥2h 降级为辅助**：会话轮换后点击正常（3-5s），冷却主要用于平台关注度管理
 - 冷却不足时点击动作 60-500s/次、run 时长显著拉长——**属平台节奏，非引擎故障**；不要重试、不要绕过同站闸门
 
 ### 0.5 自举完成（正常初始态）
@@ -126,6 +129,13 @@ Agent 按自己被赋予的角色调用，超出裁剪集的工具会报「工
 - 循环索引 `{i}` 由引擎注入，不要传
 - **可选参数**（inputs 声明 `required:false`）：`limit`（循环提取数量上限，如 `{"keyword":"产品经理","limit":"3"}` → 最多 3 轮）、`city`（BOSS直聘城市代码，如 珠海=101280700；缺省不带 → 平台默认城市）
 - **中文参数必须 UTF-8 发送**：引擎收包按 UTF-8 解析；若输入变 `?`，用 `DEBUG_HEX=1` 启动引擎查 `[hex]` 日志（body/vars/typeCharacter 字节）定位发送端
+- **PowerShell 直测注意**：`Invoke-WebRequest` 的 `-Body` 字符串默认按系统代码页（中文 Windows=GBK）编码，中文会变 `?`——**必须转 UTF-8 字节数组**：
+  ```powershell
+  $body = '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_flow","arguments":{"flowId":"boss_search_jobs","vars":{"keyword":"产品经理"}}}}'
+  $bytes = [System.Text.Encoding]::UTF8.GetBytes($body)
+  Invoke-WebRequest -Uri "http://127.0.0.1:3111/mcp" -Method Post -Body $bytes -ContentType "application/json; charset=utf-8"
+  ```
+- **正式验收请用真实 agent / Node MCP SDK 客户端**（HTTP 传输默认 UTF-8，无此问题）；PowerShell 手动构造仅适合调试
 
 **结果解读**
 - run.json 的 `status`：done / failed