mooncat-browser 0.1.0 → 0.2.1

package/skills/browser/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: browser
-description: "Drive the user's local Chrome via @mooncat/browser (BrowserClient -> browserd RPC) for page probing, data collection, form automation, screenshots. Long-session co-work model (open once, reuse handle across turns), never judge route, stepwise with artifacts on disk. Use when the user wants to probe/collect/automate a web page, mentions browser automation, sycm/taobao scraping, or form filling. Independent toolkit - no mooncat distribution / workspace / PM2 dependency."
+description: "Drive the user's local Chrome via mooncat-browser (BrowserClient -> browserd RPC) for page probing, data collection, form automation, screenshots. Long-session co-work model (open once, reuse handle across turns), never judge route, stepwise with artifacts on disk. Use when the user wants to probe/collect/automate a web page, mentions browser automation, sycm/taobao scraping, or form filling. Independent toolkit - no mooncat distribution / workspace / PM2 dependency."
 ---
 
 # browser
 
-通过 `@mooncat/browser` 的 `BrowserClient` 驱动**用户本地 Chrome**（用户看得见的浏览器，
+通过 `mooncat-browser` 的 `BrowserClient` 驱动**用户本地 Chrome**（用户看得见的浏览器，
 不是无头集群），做页面探查、采集、表单自动化、截图。
 
 `BrowserClient` 是薄 HTTP RPC client，连接常驻的 **browserd 服务**（`mooncat-browser start`
@@ -31,31 +31,54 @@ description: "Drive the user's local Chrome via @mooncat/browser (BrowserClient
 
 ## 怎么用
 
+> **前置**:mooncat-browser 是实例化、项目级配置的独立包。**不写全局 appData**,
+> 必须先 `init` 生成项目配置,再 `start`。找不到配置会 fail fast。
+>
+> **实例(instance)= 一个 Chrome 进程边界**:一组端口 + 一个 profile + 一套 state/logs。
+> **不是 task**——task 是调用方(workspace/agent)的概念,本包不规定、不关心。
+> 一个项目**默认就一个 `default` 实例**(够用);只有需要**同时跑两个独立 Chrome**
+> 时才加实例(各自独立 profile,互不串登录态/cookie)。
+
+```bash
+# 一次性:在项目目录初始化(生成 config/browser.json + .browser/default/ 数据目录)
+npx mooncat-browser init                    # 默认建 default 实例,绝大多数项目就这一个
+
+# 启动实例(常驻,另一个终端)
+npx mooncat-browser start default
+# 高危平台走 extension 路:先 prepare 扩展目录 + 手动 load unpacked(见 high-risk.md)
+npx mooncat-browser start default --route-mode extension
+# open 时显式指定路由(高危平台必走 extension)
+npx mooncat-browser open default --url https://example.com --route-mode extension
+
+# 同时跑第二个独立 Chrome(高级,按需):init 时给名,各自独立 profile
+npx mooncat-browser init shop-b             # 加 shop-b 实例(独立 profile)
+```
+
 ```ts
-import { BrowserClient } from "@mooncat/browser";
+import { BrowserClient } from "mooncat-browser";
 
-// 连接到已启动的服务（端口要和 mooncat-browser start --port 一致，默认 17322）
+// 端口要和实例配置里 rpcPort 一致(默认 17322,多实例各自不同)
+// 不确定时看 config/browser.json,或用 mooncat-browser list 查
 const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
 
-// 探测 browserd 是否就绪
 const h = await browser.health();
 if (!h?.browserOpen) await browser.open({ headless: false });
 
-// 打开页面 (newTab 返回 TabInfo, operate 传 tab.pageHandle)
 const tab = await browser.newTab({ url: "https://example.com" });
 
-// 所有页面动作走 operate (action 清单见包内 references/operate-actions 或 README)
+// 所有页面动作走 operate (action 清单见 references/operate-actions)
 const snap = await browser.operate({ pageHandle: tab.pageHandle, action: "snapshot" });
 await browser.operate({ pageHandle: tab.pageHandle, action: "click", params: { selector: "#login" } });
 ```
 
-> 服务必须先启动：`mooncat-browser start --port 17322`（另一个终端，常驻）。
-> 没启动时 `health()` 返回 null，`operate` 会连接拒绝报错。CLI 一键开页验证：
-> `mooncat-browser open --url https://example.com`。
+> 服务必须先启动:`mooncat-browser start <name>`(另一个终端,常驻)。
+> 没启动时 `health()` 返回 null,`operate` 会连接拒绝报错。
+> 多实例:每个实例独立 profile/端口/state,`mooncat-browser list` 查所有实例状态,
+> `mooncat-browser stop <name>` / `status <name>` 按实例名管理。
 
-**操作清单不在本 skill 列**——`operate` 的 40+ 个 action（导航/交互/读取/等待/存储/截图）
-是公开契约，查包内 `README.md` 的 "operate 的 action 清单" 或
-`browser-op/backend/browserd.cjs` 的 `rpcOperate`（始终权威）。
+**操作清单不在本 skill 列**——`operate` 的 40+ 个 action(导航/交互/读取/等待/存储/截图)
+是公开契约,查包内 `README.md` 的 "operate 的 action 清单" 或
+`browser-op/backend/browserd.cjs` 的 `rpcOperate`(始终权威)。
 
 ## 步进式 co-work 的标准节奏
 
@@ -100,7 +123,7 @@ await browser.operate({ pageHandle: tab.pageHandle, action: "click", params: { s
 
 > 如果你在一个更大的系统里（有自己的通知渠道，如飞书/Slack/webhook），
 > 把"报告用户"换成你的通知机制即可。本 skill 只规定"必须可见化 + 叫人"的纪律，
-> 不规定具体通知后端——`@mooncat/browser` 是独立工具包，不带任何通知能力。
+> 不规定具体通知后端——`mooncat-browser` 是独立工具包，不带任何通知能力。
 
 ## 参考
 

package/skills/browser/references/collect.md

@@ -14,12 +14,14 @@
 ## 标准采集 step 模板
 
 ```ts
-import { BrowserClient } from "@mooncat/browser";
+import { BrowserClient } from "mooncat-browser";
 
 const SITE = "example.com";
+// 端口要和实例配置 rpcPort 一致(默认 17322,多实例各自不同)
 const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
 
 // 1. 复用已有 tab (不要盲目 newTab)
+//    高危平台:open({ routeMode: "extension" }),见 high-risk.md
 await browser.open({ headless: false });
 const tabs = await browser.listTabs();
 let tab = tabs.find((t) => t.url?.includes(SITE));
@@ -147,7 +149,7 @@ await browser.operate({ pageHandle: page, action: "waitForSelector", params: { s
 ## 中间产物落盘
 
 采集每一步的中间产物（snapshot / 截图 / 抓取的数据）建议落盘到本地目录，便于审计 + 给用户看。
-用 Node 原生 `fs` 写即可（`@mooncat/browser` 不提供文件落盘能力，那是你应用层的职责）：
+用 Node 原生 `fs` 写即可（`mooncat-browser` 不提供文件落盘能力，那是你应用层的职责）：
 
 ```ts
 import { writeFileSync } from "node:fs";

package/skills/browser/references/high-risk.md

@@ -21,21 +21,34 @@ CDP 路由通过 `--remote-debugging-port` 暴露调试端口，**强风控脚
 **高危平台必须走 extension 路由**：`open({ routeMode: "extension" })`。
 若 profile 没装扩展，extension 路会失败——此时**停下来报告用户**，不要降级到 CDP 凑合。
 
-## WebPlater 扩展安装（每个 profile 一次性）
+## WebPlater 扩展安装（每个实例 profile 一次性）
 
-extension 路由依赖 WebPlater 扩展。**扩展装在具体 Chrome profile 里**——换 profile 就要重装。
-首次使用高危平台前，用户需在目标 profile 装 WebPlater：
+extension 路由依赖 WebPlater 扩展。**扩展装在具体实例的 Chrome profile 里**——
+每个实例有独立 profile(`config/browser.json` 里的 `profileDir`),换实例就要重装。
 
-1. `mooncat-browser install-extension` 拿到扩展目录绝对路径（包内 `browser-op/webplater/dist/chrome-mv3/`）。
-2. `mooncat-browser start --port 17322` 启动服务，`browser.open({ routeMode: "auto" })` 启动 Chrome，
-   拿到 profile 的 user-data-dir（默认 `%LOCALAPPDATA%\mooncat-browser\profile`，或 `--profile` 指定）。
-3. 用户在该 Chrome 访问 `chrome://extensions`，开「开发者模式」。
-4. 点「加载已解压的扩展程序」，选第 1 步拿到的扩展目录（校验路径下有 `manifest.json`）。
-5. 等几秒 background service worker 连上 WS server。
-6. 重新 `open`（routeMode=auto），看返回的 `mode` 是否为 `extension`。
+多实例下,**每个实例生成自己的扩展目录**(写死该实例的 WS 端口),扩展不共享:
 
-**必须先算好扩展绝对路径再告诉用户**，不要让用户自己找。`mooncat-browser install-extension`
-会打印路径。校验路径下有 `manifest.json`。
+```bash
+# 1. 为实例生成 unpacked 扩展目录(copy 包内模板 + 替换 WS 端口占位符)
+npx mooncat-browser prepare-extension <实例名>
+#    产物在 <实例 extensionDir>(默认 .browser/<实例名>/extension)
+#    里面 offscreen 代码已写死连 ws://127.0.0.1:<该实例 extensionPort>
+
+# 2. 启动实例(会弹出用该实例 profile 的 Chrome)
+npx mooncat-browser start <实例名> --route-mode extension
+
+# 3. 在弹出的 Chrome 里手动 load unpacked:
+#    chrome://extensions → 开「开发者模式」→「加载已解压的扩展程序」
+#    选择:<实例 extensionDir>(校验路径下有 manifest.json)
+#    profile 会永久记住这次安装,以后 start 不用再 load
+```
+
+`prepare-extension` 会打印实例 extensionDir 的绝对路径——**把这个路径告诉用户**,
+不要让用户自己找。校验路径下有 `manifest.json` 即正确。
+
+> 注意:extension 路不能 headless(Chrome 限制)。高危平台本就要看得见浏览器,不冲突。
+> 改了实例 extensionPort 或升级了包(扩展 build 变了),要重 `prepare-extension` 并在
+> Chrome 里重新 load unpacked。
 
 ## 装了扩展后必须重启浏览器
 
@@ -124,7 +137,7 @@ if (blocked) {
     writeFileSync(imgPath, Buffer.from(shot.dataUrl.split(",")[1], "base64"));
   }
 
-  // 2. 报告用户叫人来处理 (用你应用层的通知机制; @mooncat/browser 不带通知能力)
+  // 2. 报告用户叫人来处理 (用你应用层的通知机制; mooncat-browser 不带通知能力)
   //    内容: 拦截类型 + 截图路径 + "请打开浏览器完成验证, 会话将在登录态恢复后继续"
   reportToUser({ type: "登录拦截", 拦截类型, screenshot: imgPath });
 
@@ -134,7 +147,7 @@ if (blocked) {
 ```
 
 > 上例的 `reportToUser` 是占位——你的应用层用什么通知（飞书/Slack/webhook/console 打印 +
-> 等待）就用什么。`@mooncat/browser` 是独立工具包，**不带任何通知能力**，本 skill 只规定
+> 等待）就用什么。`mooncat-browser` 是独立工具包，**不带任何通知能力**，本 skill 只规定
 > "必须可见化 + 叫人"的纪律，不规定通知后端。
 
 **关键心态**：这些拦截"不能搞定"是**正常预期**，不是失败。职责是**第一时间发现并叫人**，

package/skills/browser/references/probing.md

@@ -35,7 +35,8 @@ iframe/portal/shadow 里的元素。正确做法是上面 5 类系统性枚举,
 ### listFrames + 逐 frame eval 范式
 
 ```ts
-import { BrowserClient } from "@mooncat/browser";
+import { BrowserClient } from "mooncat-browser";
+// 端口 = 实例 rpcPort(默认 17322,多实例各自不同,看 config/browser.json)
 const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
 
 const tab = await browser.newTab({ url: "https://example.com" });
@@ -238,14 +239,14 @@ Chrome 有**自动下载保护**：点击下载后，文件可能被浏览器**
 能把探查过程结构化留痕：事件流（events.ndjson）+ 三态结果（pass/fail/skip）+ 产物附件（截图/数据）。
 它和 BrowserClient 是**天然搭档**：browser 做探查动作，cateye-probe 记录反应。
 
-> cateye-probe 是**可选推荐**，不是 `@mooncat/browser` 的依赖。不需要它也能探查（手动 fs 落盘
+> cateye-probe 是**可选推荐**，不是 `mooncat-browser` 的依赖。不需要它也能探查（手动 fs 落盘
 > 即可）；需要可回溯 trace 时推荐搭配。两者都是独立包，互不耦合。
 
 ### 分工
 
 | | 职责 | 来源 |
 |---|---|---|
-| browser | 决定做什么探查（导航/交互/读取），执行动作 | `@mooncat/browser` 的 `BrowserClient` |
+| browser | 决定做什么探查（导航/交互/读取），执行动作 | `mooncat-browser` 的 `BrowserClient` |
 | cateye-probe | 把过程留痕（事件流/结果/产物） | 独立 npm 包 `cateye-probe`（`import { probe } from "cateye-probe/sdk"`） |
 
 ### 组合范式骨架
@@ -253,7 +254,7 @@ Chrome 有**自动下载保护**：点击下载后，文件可能被浏览器**
 一个探查脚本里：browser 做动作，probe 在关键节点写痕迹。每个 step 问一个问题、留一段 trace。
 
 ```ts
-import { BrowserClient } from "@mooncat/browser";
+import { BrowserClient } from "mooncat-browser";
 import { probe } from "cateye-probe/sdk";   // 可选搭配, 独立包
 import { writeFileSync } from "node:fs";
 
@@ -261,6 +262,7 @@ const browser = new BrowserClient({ baseUrl: "http://127.0.0.1:17322" });
 
 const done = probe.section("采集订单");          // 结构化段落
 
+// 高危平台:open({ routeMode: "extension" }),见 high-risk.md
 await browser.open({ headless: false });
 const tab = await browser.newTab({ url: "https://example.com/orders" });
 const page = tab.pageHandle;

package/browser-op/webplater/dist/chrome-mv3/chunks/offscreen-CFXYw9Mo.js

@@ -1 +0,0 @@
-import"./_virtual_wxt-html-plugins-DPbbfBKe.js";const l="ws://127.0.0.1:17321",p=1e3,E=2e4;let e=null,s=null,c=null;function d(){(e==null?void 0:e.readyState)===WebSocket.CONNECTING||(e==null?void 0:e.readyState)===WebSocket.OPEN||(e=new WebSocket(l),e.addEventListener("open",()=>{s&&(clearTimeout(s),s=null),console.log("[WebPlater/offscreen] connected to host",l),i({type:"hello",name:"bee-web-plugin"}),y()}),e.addEventListener("message",async t=>{let n;try{n=JSON.parse(String(t.data))}catch{console.error("[WebPlater/offscreen] invalid JSON from host",t.data);return}if(!(!n||n.type!=="command"||typeof n.id!="number"))try{const r=await S(n.id,n.method,n.params??{});u(n.id,{ok:!0,result:r})}catch(r){u(n.id,{ok:!1,error:r instanceof Error?r.message:String(r)})}}),e.addEventListener("close",()=>{console.log("[WebPlater/offscreen] disconnected, reconnecting..."),e=null,f(),b()}),e.addEventListener("error",()=>{e==null||e.close()}))}function i(t){(e==null?void 0:e.readyState)===WebSocket.OPEN&&e.send(JSON.stringify(t))}function u(t,n){const r={id:t,type:"response",...n};i(r)}function S(t,n,r){return new Promise((m,a)=>{chrome.runtime.sendMessage({source:"offscreen-command",id:t,method:n,params:r},g=>{if(chrome.runtime.lastError){a(new Error(chrome.runtime.lastError.message));return}const o=g;if(o&&typeof o=="object"&&o.ok===!1){a(new Error(o.error??"background error"));return}m(o==null?void 0:o.result)})})}function y(){f(),c=setInterval(()=>{i({type:"ping",time:Date.now()})},E)}function f(){c&&(clearInterval(c),c=null)}function b(){s||(s=setTimeout(()=>{s=null,d()},p))}d();