@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/protocol/browser/config.env

@@ -0,0 +1,9 @@
+# web-access skill 用户偏好配置
+# 此文件是模板。首次运行 check-deps.mjs 时会自动复制为 config.env（git ignored）。
+#
+# 用户长期偏好的默认 Agent 浏览器
+# - 留空：每次启动都问用户偏好哪个
+# - 设值：固定使用该浏览器；若未检测到对应 toggle 则硬错（不擅自降级）
+#
+# 合法值：chrome / edge
+WEB_ACCESS_BROWSER=

package/templates/qoder/scripts/protocol/browser/references/cdp-api.md

@@ -0,0 +1,110 @@
+# CDP Proxy API 参考
+
+## 基础信息
+
+- 地址：`http://localhost:3456`
+- 启动：`node ~/.claude/skills/web-access/scripts/cdp-proxy.mjs &`
+- 启动后持续运行，不建议主动停止（重启需 Chrome 重新授权）
+- 强制停止：`pkill -f cdp-proxy.mjs`
+
+## API 端点
+
+### GET /health
+健康检查，返回连接状态。
+```bash
+curl -s http://localhost:3456/health
+```
+
+### GET /targets
+列出所有已打开的页面 tab。返回数组，每项含 `targetId`、`title`、`url`。
+```bash
+curl -s http://localhost:3456/targets
+```
+
+### POST /new
+创建新后台 tab，自动等待页面加载完成。**URL 通过 POST body 原样传入**，无需 URL-encode、不会因 query 中含 `&` 被切分。返回 `{ targetId }`。
+```bash
+curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
+# 含 query 的目标 URL（如带 token 的小红书笔记）也直接原样传：
+curl -s -X POST --data-raw 'https://www.xiaohongshu.com/explore/xxx?xsec_source=app_share&xsec_token=ABC&type=normal' http://localhost:3456/new
+```
+> v2.5.3 起改为 POST。旧的 `GET /new?url=...` 返回 400 + 迁移指引，详见 `migration-2.5.3.md`。
+
+### GET /close?target=ID
+关闭指定 tab。
+```bash
+curl -s "http://localhost:3456/close?target=TARGET_ID"
+```
+
+### POST /navigate?target=ID
+在已有 tab 中导航到新 URL，自动等待加载。**target 走 query（不带特殊字符的不透明 ID），URL 走 POST body**。
+```bash
+curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
+```
+> v2.5.3 起改为 POST。旧的 `GET /navigate?target=...&url=...` 返回 400 + 迁移指引，详见 `migration-2.5.3.md`。
+
+### GET /back?target=ID
+后退一页。
+```bash
+curl -s "http://localhost:3456/back?target=ID"
+```
+
+### GET /info?target=ID
+获取页面基础信息（title、url、readyState）。
+```bash
+curl -s "http://localhost:3456/info?target=ID"
+```
+
+### POST /eval?target=ID
+执行 JavaScript 表达式，POST body 为 JS 代码。
+```bash
+curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
+```
+
+### POST /click?target=ID
+JS 层面点击（`el.click()`），POST body 为 CSS 选择器。自动 scrollIntoView 后点击。简单快速，覆盖大多数场景。
+```bash
+curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
+```
+
+### POST /clickAt?target=ID
+CDP 浏览器级真实鼠标点击（`Input.dispatchMouseEvent`），POST body 为 CSS 选择器。先获取元素坐标，再模拟鼠标按下/释放。算真实用户手势，能触发文件对话框、绕过部分反自动化检测。
+```bash
+curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
+```
+
+### POST /setFiles?target=ID
+给 file input 设置本地文件路径（`DOM.setFileInputFiles`），完全绕过文件对话框。POST body 为 JSON。
+```bash
+curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file1.png","/path/to/file2.png"]}'
+```
+
+### GET /scroll?target=ID&y=3000&direction=down
+滚动页面。`direction` 可选 `down`（默认）、`up`、`top`、`bottom`。滚动后自动等待 800ms 供懒加载触发。
+```bash
+curl -s "http://localhost:3456/scroll?target=ID&y=3000"
+curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
+```
+
+### GET /screenshot?target=ID&file=/tmp/shot.png
+截图。指定 `file` 参数保存到本地文件；不指定则返回图片二进制。可选 `format=jpeg`。
+```bash
+curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
+```
+
+## /eval 使用提示
+
+- POST body 为任意 JS 表达式，返回 `{ value }` 或 `{ error }`
+- 支持 `awaitPromise`：可以写 async 表达式
+- 返回值必须是可序列化的（字符串、数字、对象），DOM 节点不能直接返回，需要提取属性
+- 提取大量数据时用 `JSON.stringify()` 包裹，确保返回字符串
+- 根据页面实际 DOM 结构编写选择器，不要套用固定模板
+
+## 错误处理
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `Chrome 未开启远程调试端口` | Chrome 未开启远程调试 | 提示用户打开 `chrome://inspect/#remote-debugging` 并勾选 Allow |
+| `attach 失败` | targetId 无效或 tab 已关闭 | 用 `/targets` 获取最新列表 |
+| `CDP 命令超时` | 页面长时间未响应 | 重试或检查 tab 状态 |
+| `端口已被占用` | 另一个 proxy 已在运行 | 已有实例可直接复用 |

package/templates/qoder/scripts/protocol/browser/references/migration-2.5.3.md

@@ -0,0 +1,72 @@
+# v2.5.3 迁移指南：`/new` 和 `/navigate` 改 POST body
+
+## TL;DR
+
+```diff
+- curl -s "http://localhost:3456/new?url=https://example.com"
++ curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
+
+- curl -s "http://localhost:3456/navigate?target=ID&url=https://example.com"
++ curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
+```
+
+旧写法收到 `400` + 包含本文档路径的错误信息后，按下方对照表改写调用。同时把发现的旧写法在源站点经验文件中就地修正。
+
+## 为什么改
+
+旧版 `/new?url=...` 把目标 URL 塞进 query 参数。当目标 URL 自带 query（如小红书笔记必须携带 `xsec_token`、B 站、微博的分享链接），proxy 用 `URL.searchParams` 解析时，目标 URL 里未编码的 `&` 会被当成 **proxy 自身的** query 分隔符，导致目标 URL 被错误切分、token 等关键参数丢失，页面返回"内容不存在"或被反爬拦截。
+
+例：
+
+```
+GET /new?url=https://xhs.com/explore/x?a=1&b=2
+```
+
+proxy 解析结果：
+- `q.url = "https://xhs.com/explore/x?a=1"` ← 被截断
+- `q.b = "2"` ← 被当成 proxy 自己的参数吃掉
+
+根因是用一种"带语法的格式（query string）"承载另一种"也带相同语法的数据（URL）"，存在结构性歧义。靠调用方守纪律做 URL-encode 治标不治本：Agent 偶尔忘记就翻车，且增加每次调用的 token 成本。
+
+v2.5.3 把 URL 改为通过 **POST body** 传入。HTTP body 是不透明字节流（边界由 `Content-Length` header 显式声明，与数据本身解耦），不存在任何分隔符歧义，URL 原样传输，零编码负担。
+
+## 转换对照表
+
+### `/new`
+
+| 场景 | 旧（v2.5.2） | 新（v2.5.3） |
+|---|---|---|
+| 简单 URL | `curl ".../new?url=https://example.com"` | `curl -X POST --data-raw 'https://example.com' .../new` |
+| URL 含 query | `curl ".../new?url=https://xhs.com/explore/x?xsec_token=ABC"` ⚠️ token 丢失 | `curl -X POST --data-raw 'https://xhs.com/explore/x?xsec_token=ABC' .../new` ✓ |
+| URL 含 `#` fragment | `curl ".../new?url=https://app/page#sec"` ⚠️ fragment 丢失 | `curl -X POST --data-raw 'https://app/page#sec' .../new` ✓ |
+
+### `/navigate`
+
+| 旧 | 新 |
+|---|---|
+| `curl ".../navigate?target=ID&url=URL"` | `curl -X POST --data-raw 'URL' ".../navigate?target=ID"` |
+
+`target` 仍走 query（它是无特殊字符的不透明 ID，没有歧义问题）。
+
+## Agent 自检 checklist
+
+在迁移后的环境中工作时，遇到任何来源的 web-access 调用，按以下顺序处理：
+
+1. **判断调用是否过时**：搜索字符串 `localhost:3456/new?url=` 或 `localhost:3456/navigate?` 后跟 `&url=`。这两类模式属于 v2.5.2 旧写法。
+2. **就地改写**：按上表对照修改成 POST 形式。
+3. **更新源文件**：如果旧写法来自 `references/site-patterns/*.md` 中某个站点经验文件，把源文件也一并修正掉（不要只在当前调用上改）—— 这样下次复用同一站点经验时不会再踩坑。
+4. **保留 URL 原样**：POST body 是不透明字节流，目标 URL 中的 `?`、`&`、`=`、`#`、`%` 等字符**无需任何转义**，从 DOM/分享链接抓到什么样就传什么样。
+
+## FAQ
+
+**Q: 我用 GET `?url=` 调用会发生什么？**
+A: 收到 HTTP 400 响应，body 中包含 `error`、`migration` 文档路径、`example` 示例。按提示改 POST 调用即可。
+
+**Q: 为什么不在 proxy 里做兼容（同时支持 GET 和 POST）？**
+A: 兼容路径会留下永久的"启发式截取 query"代码 + SKILL.md 里"也支持旧写法"的脚注。两条路径长期共存 → Agent 学得不彻底、维护者两套都要测、读代码的人要分辨主路径 vs 兼容路径。把架构债转成了认知债。一次性 breaking change 配合迁移指南，更彻底也更便宜。
+
+**Q: 我自己的脚本/别名/笔记里有大量旧写法，有迁移脚本吗？**
+A: 没有也不打算提供。站点经验和脚本是人写的文档/代码，掺着说明、注释、上下文判断，正则替换容易误伤。本指南的 Agent 自检 checklist 就是给"Agent 看着内容自己判断怎么改"的，比脚本可靠。
+
+**Q: 还有哪些 endpoint 用 POST body？**
+A: 一直都有：`/eval`、`/click`、`/clickAt`、`/setFiles` 全是 POST + body。这次 `/new` `/navigate` 加入后，**所有传输"任意字符串载荷"的写操作都统一走 POST body** —— 内部一致性提升。

package/templates/qoder/scripts/protocol/browser/scripts/browser-discovery.mjs

@@ -0,0 +1,138 @@
+// 浏览器 CDP 端口发现 + 选择 - 单一职责模块
+// 被 check-deps.mjs 和 cdp-proxy.mjs 共享。
+//
+// 选择规则（resolution）：
+//   1. 调用方传入 override 参数（来自命令行 --browser） → 严格模式，找不到则硬错
+//   2. config.env 里 WEB_ACCESS_BROWSER 设了 → 严格模式，找不到则硬错
+//   3. 都没设 → "ask" 模式，提示调用方询问用户
+//
+// 不擅自降级：偏好不可用一律硬错，让用户介入。
+// 持久态只有 config.env 一处；override 是单次 spawn 通过命令行参数表达，不读 process.env。
+
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CONFIG_PATH = path.join(SKILL_ROOT, 'config.env');
+
+// 已知支持 chrome://inspect#remote-debugging toggle 的浏览器
+// 加新浏览器：只改这里
+export function knownBrowsers() {
+  const home = os.homedir();
+  const localAppData = process.env.LOCALAPPDATA || '';
+  switch (os.platform()) {
+    case 'darwin':
+      return [
+        { id: 'chrome',        label: 'Chrome',         devToolsPath: path.join(home, 'Library/Application Support/Google/Chrome/DevToolsActivePort') },
+        { id: 'chrome-canary', label: 'Chrome Canary',  devToolsPath: path.join(home, 'Library/Application Support/Google/Chrome Canary/DevToolsActivePort') },
+        { id: 'chromium',      label: 'Chromium',       devToolsPath: path.join(home, 'Library/Application Support/Chromium/DevToolsActivePort') },
+        { id: 'edge',          label: 'Microsoft Edge', devToolsPath: path.join(home, 'Library/Application Support/Microsoft Edge/DevToolsActivePort') },
+      ];
+    case 'linux':
+      return [
+        { id: 'chrome',   label: 'Chrome',         devToolsPath: path.join(home, '.config/google-chrome/DevToolsActivePort') },
+        { id: 'chromium', label: 'Chromium',       devToolsPath: path.join(home, '.config/chromium/DevToolsActivePort') },
+        { id: 'edge',     label: 'Microsoft Edge', devToolsPath: path.join(home, '.config/microsoft-edge/DevToolsActivePort') },
+      ];
+    case 'win32':
+      return [
+        { id: 'chrome',   label: 'Chrome',         devToolsPath: path.join(localAppData, 'Google/Chrome/User Data/DevToolsActivePort') },
+        { id: 'chromium', label: 'Chromium',       devToolsPath: path.join(localAppData, 'Chromium/User Data/DevToolsActivePort') },
+        { id: 'edge',     label: 'Microsoft Edge', devToolsPath: path.join(localAppData, 'Microsoft/Edge/User Data/DevToolsActivePort') },
+      ];
+    default:
+      return [];
+  }
+}
+
+// TCP 端口监听检测
+// 用 TCP connect 而非 WebSocket，避免触发浏览器的远程调试授权弹窗。
+export function checkPort(port, host = '127.0.0.1', timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection(port, host);
+    const timer = setTimeout(() => { socket.destroy(); resolve(false); }, timeoutMs);
+    socket.once('connect', () => { clearTimeout(timer); socket.destroy(); resolve(true); });
+    socket.once('error',   () => { clearTimeout(timer); resolve(false); });
+  });
+}
+
+// 读 config.env 文件（不写入 process.env，分清来源）
+// 格式：KEY=VALUE，# 开头是注释
+function readConfig() {
+  const cfg = {};
+  let content;
+  try { content = fs.readFileSync(CONFIG_PATH, 'utf8'); }
+  catch { return cfg; }
+  for (const line of content.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith('#')) continue;
+    const i = t.indexOf('=');
+    if (i === -1) continue;
+    const k = t.slice(0, i).trim();
+    const v = t.slice(i + 1).trim();
+    if (k && v) cfg[k] = v;
+  }
+  return cfg;
+}
+
+// 返回所有开了 toggle 且端口活的浏览器
+async function detectAll() {
+  const result = [];
+  for (const browser of knownBrowsers()) {
+    let content;
+    try { content = fs.readFileSync(browser.devToolsPath, 'utf8'); }
+    catch { continue; }
+    const lines = content.trim().split(/\r?\n/).filter(Boolean);
+    const port = parseInt(lines[0], 10);
+    if (!(port > 0 && port < 65536)) continue;
+    if (!(await checkPort(port))) continue;
+    result.push({ ...browser, port, wsPath: lines[1] || null });
+  }
+  return result;
+}
+
+// 决策入口
+// 参数：override — 调用方解析自命令行 --browser 的值（null 表示未传）
+// 返回 { kind, browser?, source?, detected, configured, override? }
+//   kind ∈ 'ok' | 'ambiguous' | 'mismatch' | 'empty'
+//   source ∈ 'override' | 'preference' | undefined
+//   ambiguous = 没设偏好 + 至少一个浏览器开了 toggle，需问用户
+//   mismatch  = override/配偏好设了但未检测到对应 toggle，硬错
+//   empty     = 0 浏览器开 toggle 且未设偏好/override
+export async function selectBrowser(override = null) {
+  const detected = await detectAll();
+  const configured = readConfig().WEB_ACCESS_BROWSER || null;
+
+  // 1. 命令行 override（最高优先，单次有效）
+  if (override) {
+    const match = detected.find(b => b.id === override);
+    if (match) return { kind: 'ok', browser: match, source: 'override', detected, configured, override };
+    return { kind: 'mismatch', source: 'override', detected, configured, override };
+  }
+
+  // 2. config.env preference（持久）
+  if (configured) {
+    const match = detected.find(b => b.id === configured);
+    if (match) return { kind: 'ok', browser: match, source: 'preference', detected, configured };
+    return { kind: 'mismatch', source: 'preference', detected, configured };
+  }
+
+  // 3. 无偏好 —— 一律询问用户（哪怕 detected 只有一个）
+  if (detected.length === 0) {
+    return { kind: 'empty', detected, configured };
+  }
+  return { kind: 'ambiguous', detected, configured };
+}
+
+// 兜底：扫描常用固定端口
+// 适用场景：用户手动 --remote-debugging-port=9222 启动浏览器，
+// 此时 DevToolsActivePort 可能不在默认 user-data-dir。
+export async function findFallbackPort() {
+  for (const port of [9222, 9229, 9333]) {
+    if (await checkPort(port)) return port;
+  }
+  return null;
+}