@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/orchestration/wlkj.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+wlkj.py - 工作流顶层调度器 (Facade 统一入口)
+
+角色: 所有 Qoder 载体 (commands/skills/rules 里写的脚本调用) 统一走本入口,
+由 DISPATCH 表路由到 scripts/ 下分层子目录的真实脚本。这样:
+  - 载体文件只认一个路径 (orchestration/wlkj.py); scripts/ 重组目录时
+    只需改 DISPATCH 一处, 载体文件不受影响 (根治"目录一重组就断链")。
+  - 脚本内部互调 (Python 进程间) 仍直接用分层路径, 不绕本入口 (避免 subprocess 嵌套)。
+
+用法:
+    python .qoder/scripts/orchestration/wlkj.py kg search 保险 --platform web
+    python .qoder/scripts/orchestration/wlkj.py task list
+    python .qoder/scripts/orchestration/wlkj.py doctor --fix
+    python .qoder/scripts/orchestration/wlkj.py search 考勤
+    python .qoder/scripts/orchestration/wlkj.py status
+
+分组 (逻辑导航, 非物理目录):
+    kg/*      知识图谱 (kg.py 的子命令直接透传)
+    task      任务系统
+    search    代码搜索
+    doctor    环境体检
+    status    项目状态
+    sync      团队同步
+    ...
+
+设计:
+  - 透明转发: 不改变任何子脚本的行为, 只是把 argv 转过去
+  - 单一真源: 脚本物理路径只在 DISPATCH 出现一次, 载体层不写死路径
+  - 零维护: 加新命令只需在 DISPATCH 表加一行
+"""
+
+import os
+import subprocess
+import sys
+
+# 命令 → 脚本 映射 (加新命令只需在此加一行)
+# v3.0: 脚本已分子目录, 路径更新为 子包/脚本
+DISPATCH = {
+    # ── 知识图谱 ──
+    'kg': 'domain/kg/kg.py',
+    'search': 'domain/kg/search/search_index.py',
+    'context': 'domain/kg/search/context_pack.py',
+    'prefetch': 'domain/kg/search/prefetch.py',
+    'kg-build': 'domain/kg/build/kg_build.py',
+    'kg-incremental': 'domain/kg/build/kg_incremental.py',
+    'kg-semantic': 'domain/kg/graph/kg_semantic.py',
+    'semantic': 'domain/kg/graph/kg_semantic.py',
+    'style': 'domain/kg/build/build_style_index.py',
+    # ── 任务 / 同步 ──
+    'task': 'domain/task/task.py',
+    'sync': 'domain/task/team_sync.py',
+    'team-sync': 'domain/task/team_sync.py',
+    'git-sync': 'domain/task/git_sync.py',
+    'zentao-sync': 'domain/task/zentao_sync.py',
+    # ── 需求 / PRD ──
+    'req': 'domain/requirement/req.py',
+    'archive-prd': 'domain/requirement/archive_prd.py',
+    # ── 设计 ──
+    'fill-prototype': 'domain/design/fill_prototype.py',
+    'design-doc': 'domain/design/gen_design_doc.py',
+    # ── 评估 / 学习 (飞轮) ──
+    'eval': 'validation/metrics/eval_prd.py',
+    'eva': 'validation/metrics/eval_prd.py',
+    'usability': 'validation/metrics/usability_score.py',
+    'learn': 'domain/learning/learn.py',
+    'learn-aggregate': 'domain/kg/build/learn_aggregate.py',
+    # ── 报告 / 状态 ──
+    'status': 'domain/report/status.py',
+    'status-snapshot': 'domain/report/status_snapshot.py',
+    'report': 'domain/report/report.py',
+    'report-snapshot': 'domain/report/report_snapshot.py',
+    'session': 'domain/report/add_session.py',
+    'add-session': 'domain/report/add_session.py',
+    'role': 'domain/report/role.py',
+    'export': 'domain/report/export.py',
+    # ── 测试 ──
+    'test': 'validation/test/autotest.py',
+    'autotest': 'validation/test/autotest.py',
+    'autotest-batch': 'validation/test/autotest_batch.py',
+    'benchmark': 'validation/test/benchmark.py',
+    # ── 环境 / 初始化 ──
+    'doctor': 'deployment/setup/init_doctor.py',
+    'init': 'deployment/setup/setup.py',
+    'install-qw': 'deployment/setup/install_qoderwork.py',
+    'setup-lanhu': 'deployment/setup/setup_lanhu.py',
+}
+
+
+
+
+def _find_script_by_name(scripts_root, name):
+    """未知命令时, 当作脚本名在 scripts/ 下递归查找。
+    支撑 'wlkj.py <脚本名>' 万能跑 (cli.js 的 run 命令底层依赖)。
+    返回绝对路径或 None。"""
+    import glob
+    if not name.endswith('.py'):
+        name = name + '.py'
+    # 递归找 scripts/**/name
+    pattern = os.path.join(scripts_root, '**', name)
+    hits = glob.glob(pattern, recursive=True)
+    return hits[0] if hits else None
+
+def _usage():
+    lines = [
+        'wlkj.py — 工作流顶层调度器',
+        '',
+        '用法: python .qoder/scripts/orchestration/wlkj.py <命令> [参数...]',
+        '',
+        '命令分组 (转发到对应脚本):',
+        '  知识图谱:  kg <子命令>          (kg.py, 13+ 能力)',
+        '             search <词>          (search_index.py)',
+        '             context <词>         (context_pack.py)',
+        '             kg-build              (全量构建图谱)',
+        '             kg-incremental        (增量构建, 定时任务用)',
+        '  任务:      task <子命令>        (task.py, create/list/start/finish)',
+        '  同步:      sync pull|push       (team_sync.py)',
+        '  需求:      req <子命令>         (req.py, 需求生命周期)',
+        '             archive-prd          (PRD 归档)',
+        '  设计:      fill-prototype <tpl> (真实数据预填原型)',
+        '             design-doc           (生成 DESIGN.md)',
+        '  评估/学习: eval <prd.md>        (eval_prd.py, EVA 评分)',
+        '             usability [--days N]  (usability_score.py, 工作流可用性: 采纳+流程)',
+        '             learn record/status  (个人埋点)',
+        '             learn-aggregate      (团队聚合 → kg.duckdb)',
+        '  状态/报告: status               (status.py, 健康度)',
+        '             report daily|weekly  (report.py)',
+        '             export <格式>        (export.py)',
+        '  测试:      test <子命令>        (autotest.py)',
+        '             autotest-batch <f>   (批量串测)',
+        '             benchmark            (性能基线)',
+        '  体检:      doctor [--fix]       (init_doctor.py)',
+        '',
+        '示例:',
+        '  wlkj.py kg search 保险 --platform web',
+        '  wlkj.py task create "登录优化"',
+        '  wlkj.py doctor --fix',
+        '  wlkj.py learn record prd_accepted \'{"req_id":"REQ-001","score":87}\'',
+        '',
+        '注: 所有 Qoder 载体 (命令/skills/rules) 统一走本入口; 脚本物理位置见 DISPATCH 表。',
+    ]
+    return '\n'.join(lines)
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ('-h', '--help', 'help'):
+        print(_usage())
+        return 0
+
+    cmd = argv[0]
+    rest = argv[1:]
+
+    # scripts/ 根 = __file__ 的上两级 (orchestration/ -> scripts/)
+    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    script = DISPATCH.get(cmd)
+    if not script:
+        # Fallback: 当作脚本名在 scripts/ 下递归找 (支撑 'wlkj.py run <脚本>')
+        # 这样 cli.js 的 'run' 和直接 'wlkj.py xxx.py' 都能走单一入口, 不需另维护路径表
+        hit = _find_script_by_name(scripts_root, cmd)
+        if hit:
+            script_path = hit
+            r = subprocess.run([sys.executable, script_path] + rest)
+            return r.returncode
+        sys.stderr.write('未知命令: %s\n' % cmd)
+        sys.stderr.write('可用命令: %s\n' % ', '.join(sorted(DISPATCH.keys())))
+        sys.stderr.write('提示: 也可用 wlkj.py <脚本名.py> 递归查找脚本\n')
+        return 1
+
+    # scripts/ 根 = __file__ 的上两级 (orchestration/ → scripts/)
+    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    script_path = os.path.join(scripts_root, script)
+    if not os.path.isfile(script_path):
+        sys.stderr.write('脚本不存在: %s\n' % script_path)
+        return 1
+
+    # 透明转发: 用当前 python 跑目标脚本, 透传所有参数和 exit code
+    r = subprocess.run([sys.executable, script_path] + rest)
+    return r.returncode
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/templates/qoder/scripts/protocol/browser/README.md

@@ -0,0 +1,207 @@
+<div align="right">
+  <details>
+    <summary>🌐 Language</summary>
+    <div>
+      <div align="center">
+        <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=en">English</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=zh-CN">简体中文</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=zh-TW">繁體中文</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=ja">日本語</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=ko">한국어</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=fr">Français</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=de">Deutsch</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=es">Español</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=pt">Português</a>
+        | <a href="https://openaitx.github.io/view.html?user=eze-is&project=web-access&lang=ru">Русский</a>
+      </div>
+    </div>
+  </details>
+</div>
+
+<img width="879" height="376" alt="image" src="https://github.com/user-attachments/assets/a87fd816-a0b5-4264-b01c-9466eae90723" />
+
+<p align="center">
+  <b>给 AI Agent 装上完整联网能力的 Skill。</b><br/>
+  <a href="https://web-access.eze.is">🌐 官网</a> · <a href="https://mp.weixin.qq.com/s/rps5YVB6TchT9npAaIWKCw">📖 设计详解</a> · <a href="#安装">⚡ 快速安装</a>
+</p>
+
+AI Agent 原本的联网能力（WebSearch、WebFetch）缺少调度策略和浏览器自动化能力。这个 Agent Skill 补上的是：**联网策略 + CDP 浏览器操作 + 站点经验积累**。兼容所有支持 SKILL.md 的 Agent（Claude Code、Cursor、Gemini CLI、Codex CLI 等）。
+
+> 推荐必读：[Web Access：一个 Skill，拉满 Agent 联网和浏览器能力](https://mp.weixin.qq.com/s/rps5YVB6TchT9npAaIWKCw) ，完整介绍了 Web-Access Skill 的开发细节与 Agent Skill 设计哲学，帮助你也能写出类似通用、高上限的 Skill
+
+---
+
+## v2.5.2 能力
+
+| 能力 | 说明 |
+|------|------|
+| 联网工具自动选择 | WebSearch / WebFetch / curl / Jina / CDP，按场景自主判断，可任意组合 |
+| CDP Proxy 浏览器操作 | 直连用户日常浏览器（Chrome / Edge / Chromium 系），天然携带登录态，支持动态页面、交互操作、视频截帧 |
+| 三种点击方式 | `/click`（JS click）、`/clickAt`（CDP 真实鼠标事件）、`/setFiles`（文件上传） |
+| 本地浏览器书签/历史检索 | `find-url.mjs` 跨 Chrome / Edge 查询公网搜不到的目标（内部系统）或用户访问过的页面，支持关键词/时间窗/访问频度排序 |
+| 并行分治 | 多目标时分发子 Agent 并行执行，共享一个 Proxy，tab 级隔离 |
+| 站点经验积累 | 按域名存储操作经验（URL 模式、平台特征、已知陷阱），跨 session 复用 |
+| 媒体提取 | 从 DOM 直取图片/视频 URL，或对视频任意时间点截帧分析 |
+
+**v2.5.2 更新：**
+- **Microsoft Edge 支持** — CDP Proxy 不再绑定 Chrome，新增 Edge 适配（及 Chromium、Chrome Canary 等 Chromium 系，通过同一套自动发现机制接入）。在 `edge://inspect/#remote-debugging` 勾选 "Allow remote debugging for this browser instance" 即可
+- **浏览器偏好持久化** — 新增 `config.env`（gitignored，首次运行从模板创建），通过 `WEB_ACCESS_BROWSER` 固定默认浏览器；多浏览器同时开启 toggle 时 Agent 会询问偏好。也支持单次覆盖 `--browser <chrome|edge>`
+- **不擅自降级** — 偏好/指定的浏览器没启动或没开 toggle 时硬错并给出明确处理步骤，不会悄悄连到别的浏览器；proxy 首次成功连接后 pin 住浏览器 id，避免运行中漂移
+- **find-url 也支持 Edge** — 本地书签/历史检索默认遍历 Chrome 与 Edge，可用 `--browser <chrome|edge>` 限定单一浏览器
+
+<details><summary>v2.5.0 更新</summary>
+
+- **本地 Chrome 资源检索** — 新增 `scripts/find-url.mjs`，从本地 Chrome 书签/历史按关键词/时间窗/访问频度定位 URL。典型场景：用户提到组织内部系统（"我们的 XX 平台"等公网搜不到的目标）、回查之前访问过但不记得地址的页面、查看最近高频访问网站等（场景感谢 @MVPGFC 在 #60 提出）
+</details>
+
+<details><summary>v2.4.3 更新</summary>
+
+- **修复 CLAUDE_SKILL_DIR 路径问题** — bash 代码块改用 `${CLAUDE_SKILL_DIR}` 字符串替换语法，修复 Windows Git Bash 路径转换错误和变量未设置问题（#47 #46）
+- **站点经验列表合并到前置检查** — 启动检查通过后自动输出已有站点经验列表，移除不可靠的 `!` 内联注入
+</details>
+
+<details><summary>v2.4.1 更新</summary>
+
+- **跨平台支持** — 脚本从 bash 迁移到 Node.js，Windows / Linux / macOS 均可使用
+- **DOM 边界穿透** — 新增技术事实：eval 递归遍历可穿透 Shadow DOM、iframe 等选择器不可跨越的边界
+</details>
+
+<details><summary>v2.4 更新</summary>
+
+- **站点内 URL 可靠性** — 新增事实说明：站点生成的链接自带完整上下文，手动构造的 URL 可能缺失隐式必要参数
+- **平台错误提示不可信** — 新增技术事实：平台返回的"内容不存在"等提示可能是访问方式问题而非内容本身问题
+- **小红书站点经验增强** — xsec_token 机制、创作者平台状态校验、暂存草稿流程
+</details>
+
+<details><summary>v2.3 更新</summary>
+
+- **浏览哲学重构** — 更清晰的「像人一样思考」框架，强调目标驱动而非步骤驱动
+- **Jina 积极推荐** — 明确鼓励在合适场景主动使用 Jina 节省 token
+- **子 Agent prompt 指引优化** — 明确加载写法，增加避免动词暗示执行方式的说明
+</details>
+
+## 安装
+
+**方式一：npx skills 一键安装（推荐）**
+
+```bash
+npx skills add eze-is/web-access
+```
+
+> [skills CLI](https://github.com/vercel-labs/skills) 是开源的 Agent Skill 包管理器，自动检测你的 Agent 环境并安装到正确位置。
+
+**方式二：让 Agent 自动安装**
+
+```
+帮我安装这个 skill：https://github.com/eze-is/web-access
+```
+
+**方式三：Plugin 安装（Claude Code）**
+
+```bash
+claude plugin marketplace add https://github.com/eze-is/web-access
+claude plugin install web-access@web-access --scope user
+```
+
+**方式四：手动**
+
+```bash
+git clone https://github.com/eze-is/web-access ~/.claude/skills/web-access
+```
+
+## 前置配置（CDP 模式）
+
+CDP 模式需要 **Node.js 22+** 和浏览器（Chrome / Edge）开启远程调试：
+
+1. 在你想用的浏览器地址栏打开对应 inspect 页面：
+   - Chrome：`chrome://inspect/#remote-debugging`
+   - Edge：`edge://inspect/#remote-debugging`
+2. 勾选 **Allow remote debugging for this browser instance**（可能需要重启浏览器）
+
+### 浏览器偏好（config.env）
+
+skill 长期偏好保存在 `${CLAUDE_SKILL_DIR}/config.env`（首次运行自动从 `config.env.template` 创建，gitignored）：
+
+```bash
+# 留空 = 每次启动都询问偏好；设值 = 固定使用该浏览器
+WEB_ACCESS_BROWSER=edge
+```
+
+合法值：`chrome` / `edge`
+
+**临时用别的浏览器**（不修改 config.env）：
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs" --browser chrome
+```
+
+**切换浏览器**（proxy 已连接旧的）：
+
+```bash
+pkill -f cdp-proxy.mjs && node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
+```
+
+环境检查（Agent 运行时会自动完成前置检查，无需手动执行）：
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
+# $CLAUDE_SKILL_DIR 是 skill 加载时自动设置的环境变量
+# 手动运行请替换为实际路径，如 ~/.claude/skills/web-access
+```
+
+## CDP Proxy API
+
+Proxy 通过 WebSocket 直连浏览器（兼容 `chrome://inspect` / `edge://inspect` 方式，无需命令行参数启动），提供 HTTP API：
+
+```bash
+# 启动（Agent 会自动管理 Proxy 生命周期，无需手动启动）
+node "${CLAUDE_SKILL_DIR}/scripts/cdp-proxy.mjs" &
+
+# 页面操作
+curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new  # 新建 tab（v2.5.3 起 URL 走 POST body）
+curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'  # 执行 JS
+curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'  # JS 点击
+curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d '.upload-btn'  # 真实鼠标点击
+curl -s -X POST "http://localhost:3456/setFiles?target=ID" \
+  -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'        # 文件上传
+curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"     # 截图
+curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"           # 滚动
+curl -s "http://localhost:3456/close?target=ID"                             # 关闭 tab
+curl -s "http://localhost:3456/health"                                      # 查看状态（含 managedTabs 数量）
+```
+
+Proxy 会自动追踪通过 `/new` 创建的 tab，闲置 15 分钟后自动关闭，防止 Agent 异常退出时留下孤儿 tab。可通过环境变量 `CDP_TAB_IDLE_TIMEOUT`（单位毫秒）调整超时时间。
+
+## ⚠️ 使用前提醒
+
+通过浏览器自动化操作社交平台（如小红书）存在账号被平台限流或封禁的风险。**强烈建议使用小号进行操作。**
+
+## 使用
+
+安装后直接让 Agent 执行联网任务，skill 自动接管：
+
+- "帮我搜索 xxx 最新进展"
+- "读一下这个页面：[URL]"
+- "去小红书搜索 xxx 的账号"
+- "帮我在创作者平台发一篇图文"
+- "同时调研这 5 个产品的官网，给我对比摘要"
+
+## 设计哲学
+
+> Skill = 哲学 + 技术事实，不是操作手册。讲清 tradeoff 让 AI 自己选，不替它推理。
+
+详见 [SKILL.md](./SKILL.md) 中的浏览哲学部分。
+
+## License
+
+MIT · 作者：[一泽 Eze](https://github.com/eze-is) · [官网](https://web-access.eze.is)
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=eze-is/web-access&type=Date)](https://star-history.com/#eze-is/web-access&Date)
+
+## Clawhub Download History
+
+[![Download History](https://skill-history.com/chart/eze-is/web-access.svg)](https://skill-history.com/eze-is/web-access)
+
+<img width="1280" height="306" alt="image" src="https://github.com/user-attachments/assets/2afa25c2-3730-413e-b40f-94e52567249d" />

package/templates/qoder/scripts/protocol/browser/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: web-access
+license: MIT
+github: https://github.com/eze-is/web-access
+description:
+  所有联网操作必须通过此 skill 处理，包括：搜索、网页抓取、登录后操作、网络交互等。
+  触发场景：用户要求搜索信息、查看网页内容、访问需要登录的网站、操作网页界面、抓取社交媒体内容（小红书、微博、推特等）、读取动态渲染页面、以及任何需要真实浏览器环境的网络任务。
+metadata:
+  author: 一泽Eze
+  version: "2.5.3"
+---
+
+# web-access Skill
+
+## 前置检查
+
+在开始联网操作前，先检查 CDP 模式可用性：
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
+```
+
+**Node.js 22+** 必需（使用原生 WebSocket）。
+
+按脚本输出处理：
+- `exit 0` → 继续
+- `exit 2` → 需询问用户偏好，写入 `${CLAUDE_SKILL_DIR}/config.env` 的 `WEB_ACCESS_BROWSER`
+- `exit 1` → 按 stdout 错误信息处理。若提示包含「Agent 处理顺序」，按其步骤执行（如先用系统命令打开浏览器后重跑），自动可解则不打扰用户；仍失败再向用户求助
+
+支持参数 `--browser <chrome|edge>` 表达本次临时覆盖（不写 config.env）。
+
+切换浏览器时，proxy 是长驻进程，需先 `pkill -f cdp-proxy.mjs` 再重跑 check-deps。
+
+检查通过后并必须在回复中向用户直接展示以下须知，再启动 CDP Proxy 执行操作：
+
+```
+温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。
+```
+
+## 浏览哲学
+
+**像人一样思考，兼顾高效与适应性的完成任务。**
+
+执行任务时不会过度依赖固有印象所规划的步骤，而是带着目标进入，边看边判断，遇到阻碍就解决，发现内容不够就深入——全程围绕「我要达成什么」做决策。这个 skill 的所有行为都应遵循这个逻辑。
+
+**① 拿到请求** — 先明确用户要做什么，定义成功标准：什么算完成了？需要获取什么信息、执行什么操作、达到什么结果？这是后续所有判断的锚点。
+
+**② 选择起点** — 根据任务性质、平台特征、达成条件，选一个最可能直达的方式作为第一步去验证。一次成功当然最好；不成功则在③中调整。比如，需要操作页面、需要登录态、已知静态方式不可达的平台（小红书、微信公众号等）→ 直接 CDP
+
+**③ 过程校验** — 每一步的结果都是证据，不只是成功或失败的二元信号。用结果对照①的成功标准，更新你对目标的判断：路径在推进吗？结果的整体面貌（质量、相关度、量级）是否指向目标可达？发现方向错了立即调整，不在同一个方式上反复重试——搜索没命中不等于"还没找对方法"，也可能是"目标不存在"；API 报错、页面缺少预期元素、重试无改善，都是在告诉你该重新评估方向。遇到弹窗、登录墙等障碍，判断它是否真的挡住了目标：挡住了就处理，没挡住就绕过——内容可能已在页面 DOM 中，交互只是展示手段。
+
+**④ 完成判断** — 对照定义的任务成功标准，确认任务完成后才停止，但也不要过度操作，不为了"完整"而浪费代价。
+
+## 联网工具选择
+
+- **确保信息的真实性，一手信息优于二手信息**：搜索引擎和聚合平台是信息发现入口。当多次搜索尝试后没有质的改进时，升级到更根本的获取方式：定位一手来源（官网、官方平台、原始页面）。
+
+| 场景 | 工具 |
+|------|------|
+| 搜索摘要或关键词结果，发现信息来源 | **WebSearch** |
+| URL 已知，需要从页面定向提取特定信息 | **WebFetch**（拉取网页内容，由小模型根据 prompt 提取，返回处理后结果） |
+| URL 已知，需要原始 HTML 源码（meta、JSON-LD 等结构化字段） | **curl** |
+| 非公开内容，或已知静态层无效的平台（小红书、微信公众号等公开内容也被反爬限制） | **浏览器 CDP**（直接，跳过静态层） |
+| 需要登录态、交互操作，或需要像人一样在浏览器内自由导航探索 | **浏览器 CDP** |
+
+浏览器 CDP 不要求 URL 已知——可从任意入口出发，通过页面内搜索、点击、跳转等方式找到目标内容。WebSearch、WebFetch、curl 均不处理登录态。
+
+**Jina**（可选预处理层，可与 WebFetch/curl 组合使用，由于其特性可节省 tokens 消耗，请积极在任务合适时组合使用）：第三方网络服务，可将网页转为 Markdown，大幅节省 token 但可能有信息损耗。调用方式为 `r.jina.ai/example.com`（URL 前加前缀，不保留原网址 http 前缀），限 20 RPM。适合文章、博客、文档、PDF 等以正文为核心的页面；对数据面板、商品页等非文章结构页面可能提取到错误区块。
+
+进入浏览器层后，`/eval` 就是你的眼睛和手：
+
+- **看**：用 `/eval` 查询 DOM，发现页面上的链接、按钮、表单、文本内容——相当于「看看这个页面有什么」
+- **做**：用 `/click` 点击元素、`/scroll` 滚动加载、`/eval` 填表提交——像人一样在页面内自然导航
+- **读**：用 `/eval` 提取文字内容，判断图片/视频是否承载核心信息——是则提取媒体 URL 定向读取或 `/screenshot` 视觉识别
+
+浏览网页时，**先了解页面结构，再决定下一步动作**。不需要提前规划所有步骤。
+
+### 补充：本地浏览器资源
+
+用户指向**本人访问过的页面**（"我之前看的那个讲 X 的文章"、"上次打开过的 XX 面板"）或**组织内部系统**（"我们的 XX 平台"、"公司那个 YY 系统"等公网搜不到的目标）时，检索本地浏览器（Chrome / Edge）书签/历史：
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/find-url.mjs" [关键词...] [--only bookmarks|history] [--browser chrome|edge] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]
+```
+
+关键词空格分词、多词 AND，匹配 title + url（可省略）；默认遍历所有已安装的 Chromium 系浏览器（Chrome、Edge），`--browser` 限定单一来源；`--since` / `--sort` 仅作用于历史；默认按最近访问倒序，`--sort visits` 按访问次数排序（适合"高频访问的网站"这类场景）。
+
+### 程序化操作与 GUI 交互
+
+浏览器内操作页面有两种方式：
+
+- **程序化方式**（构造 URL 直接导航、eval 操作 DOM）：成功时速度快、精确，但对网站来说不是正常用户行为，可能触发反爬机制。
+- **GUI 交互**（点击按钮、填写输入框、滚动浏览）：GUI 是为人设计的，网站不会限制正常的 UI 操作，确定性最高，但步骤多、速度慢。
+
+根据对目标平台的了解来灵活选择方式。GUI 交互也是程序化方式的有效探测——通过一次真实交互观察站点的实际行为（URL 模式、必需参数、页面跳转逻辑），为后续程序化操作提供依据；同时当程序化方式受阻时，GUI 交互是可靠的兜底。
+
+**站点内交互产生的链接是可靠的**：通过用户视角中的可交互单元（卡片、条目、按钮）进行的站点内交互，自然到达的 URL 天然携带平台所需的完整上下文。而手动构造的 URL 可能缺失隐式必要参数，导致被拦截、返回错误页面、甚至触发反爬。
+
+## 浏览器 CDP 模式
+
+通过 CDP Proxy 直连用户日常浏览器（Chrome / Edge / Chromium 等 Chromium 系），天然携带登录态，无需启动独立浏览器。
+若无用户明确要求，不主动操作用户已有 tab，所有操作都在自己创建的后台 tab 中进行，保持对用户环境的最小侵入。不关闭用户 tab 的前提下，完成任务后关闭自己创建的 tab，保持环境整洁。
+
+### 启动
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
+```
+
+脚本会依次检查 Node.js、浏览器调试端口，并确保 Proxy 已连接（未运行则自动启动并等待）。Proxy 启动后持续运行。
+
+### Proxy API
+
+所有操作通过 curl 调用 HTTP API：
+
+```bash
+# 列出用户已打开的 tab
+curl -s http://localhost:3456/targets
+
+# 创建新后台 tab（自动等待加载）— URL 走 POST body，避免目标 URL 含 query 时被切分
+curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
+
+# 页面信息
+curl -s "http://localhost:3456/info?target=ID"
+
+# 执行任意 JS：可读写 DOM、提取数据、操控元素、触发状态变更、提交表单、调用内部方法
+curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
+
+# 捕获页面渲染状态（含视频当前帧）
+curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
+
+# 导航（URL 走 POST body，target 走 query）、后退
+curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
+curl -s "http://localhost:3456/back?target=ID"
+
+# 点击（POST body 为 CSS 选择器）— JS el.click()，简单快速，覆盖大多数场景
+curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
+
+# 真实鼠标点击 — CDP Input.dispatchMouseEvent，算用户手势，能触发文件对话框
+curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
+
+# 文件上传 — 直接设置 file input 的本地文件路径，绕过文件对话框
+curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'
+
+# 滚动（触发懒加载）
+curl -s "http://localhost:3456/scroll?target=ID&y=3000"
+curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
+
+# 关闭 tab
+curl -s "http://localhost:3456/close?target=ID"
+```
+
+### 页面内导航
+
+两种方式打开页面内的链接：
+
+- **`/click`**：在当前 tab 内直接点击用户视角中的可交互单元，简单直接，串行处理。适合需要在同一页面内连续操作的场景，如点击展开、翻页、进入详情等。
+- **`/new` + 完整 URL**：使用目标链接的完整地址（包含所有URL参数），在新 tab 中打开。适合需要同时访问多个页面的场景。
+
+很多网站的链接包含会话相关的参数（如 token），这些参数是正常访问所必需的。提取 URL 时应保留完整地址，不要裁剪或省略参数。URL 通过 POST body 原样传入 `/new` 或 `/navigate`。
+
+> **v2.5.3 迁移提示**：若引用的站点经验文件（`references/site-patterns/*.md`）或其它脚本中仍含 `GET /new?url=...` 或 `/navigate?target=...&url=...` 的旧写法，调用会收到迁移指引。按 [`references/migration-2.5.3.md`](references/migration-2.5.3.md) 就地改写为 POST body 后再使用，并顺手把该站点经验文件更新掉。
+
+### 媒体资源提取
+
+判断内容在图片里时，用 `/eval` 从 DOM 直接拿图片 URL，再定向读取——比全页截图精准得多。
+
+### 技术事实
+- 页面中存在大量已加载但未展示的内容——轮播中非当前帧的图片、折叠区块的文字、懒加载占位元素等，它们存在于 DOM 中但对用户不可见。以数据结构（容器、属性、节点关系）为单位思考，可以直接触达这些内容。
+- DOM 中存在选择器不可跨越的边界（Shadow DOM 的 `shadowRoot`、iframe 的 `contentDocument`等）。eval 递归遍历可一次穿透所有层级，返回带标签的结构化内容，适合快速了解未知页面的完整结构。
+- `/scroll` 到底部会触发懒加载，使未进入视口的图片完成加载。提取图片 URL 前若未滚动，部分图片可能尚未加载。
+- 拿到媒体资源 URL 后，公开资源可直接下载到本地后用读取；需要登录态才可获取的资源才需要在浏览器内 navigate + screenshot。
+- 短时间内密集打开大量页面（如批量 `/new`）可能触发网站的反爬风控。
+- 平台返回的"内容不存在""页面不见了"等提示不一定反映真实状态，也可能是访问方式的问题（如 URL 缺失必要参数、触发反爬）而非内容本身的问题。
+
+### 视频内容获取
+
+用户浏览器真实渲染，截图可捕获当前视频帧。核心能力：通过 `/eval` 操控 `<video>` 元素（获取时长、seek 到任意时间点、播放/暂停/全屏），配合 `/screenshot` 采帧，可对视频内容进行离散采样分析。
+
+### 登录判断
+
+用户日常浏览器天然携带登录态，大多数常用网站已登录。
+
+登录判断的核心问题只有一个：**目标内容拿到了吗？**
+
+打开页面后先尝试获取目标内容。只有当确认**目标内容无法获取**且判断登录能解决时，才告知用户：
+> "当前页面在未登录状态下无法获取[具体内容]，请在你的浏览器中登录 [网站名]，完成后告诉我继续。"
+
+登录完成后无需重启任何东西，直接刷新页面继续。
+
+### 任务结束
+
+用 `/close` 关闭自己创建的 tab，必须保留用户原有的 tab 不受影响。
+
+Proxy 持续运行，不建议主动停止——重启后需要在浏览器中重新授权 CDP 连接。
+
+## 并行调研：子 Agent 分治策略
+
+任务包含多个**独立**调研目标时（如同时调研 N 个项目、N 个来源），鼓励合理分治给子 Agent 并行执行，而非主 Agent 串行处理。
+
+**好处：**
+- **速度**：多子 Agent 并行，总耗时约等于单个子任务时长
+- **上下文保护**：抓取内容不进入主 Agent 上下文，主 Agent 只接收摘要，节省 token
+
+**并行 CDP 操作**：每个子 Agent 在当前用户浏览器实例中，自行创建所需的后台 tab（`/new`），自行操作，任务结束自行关闭（`/close`）。所有子 Agent 共享一个浏览器、一个 Proxy，通过不同 targetId 操作不同 tab，无竞态风险。
+
+**子 Agent Prompt 写法：目标导向，而非步骤指令**
+- 必须在子 Agent prompt 中写 `必须加载 web-access skill 并遵循指引` ，子 Agent 会自动加载 skill，无需在 prompt 中复制 skill 内容或指定路径。
+- 子 Agent 有自主判断能力。主 Agent 的职责是说清楚**要什么**，仅在必要与确信时限定**怎么做**。过度指定步骤会剥夺子 Agent 的判断空间，反而引入主 Agent 的假设错误。**避免 prompt 用词对子 Agent 行为的暗示**：「搜索xx」会把子 Agent 锚定到 WebSearch，而实际上有些反爬站点需要 CDP 直接访问主站才能有效获取内容。主 Agent 写 prompt 时应描述目标（「获取」「调研」「了解」），避免用暗示具体手段的动词（「搜索」「抓取」「爬取」）。
+
+**分治判断标准：**
+
+| 适合分治 | 不适合分治 |
+|----------|-----------|
+| 目标相互独立，结果互不依赖 | 目标有依赖关系，下一个需要上一个的结果 |
+| 每个子任务量足够大（多页抓取、多轮搜索） | 简单单页查询，分治开销大于收益 |
+| 需要 CDP 浏览器或长时间运行的任务 | 几次 WebSearch / Jina 就能完成的轻量查询 |
+
+## 信息核实类任务
+
+核实的目标是**一手来源**，而非更多的二手报道。多个媒体引用同一个错误会造成循环印证假象。
+
+搜索引擎和聚合平台是信息发现入口，是**定位**信息的工具，不可用于直接**证明**真伪。找到来源后，直接访问读取原文。同一原则适用于工具能力/用法的调研——官方文档是一手来源，不确定时先查文档或源码，不猜测。
+
+| 信息类型 | 一手来源 |
+|----------|---------|
+| 政策/法规 | 发布机构官网 |
+| 企业公告 | 公司官方新闻页 |
+| 学术声明 | 原始论文/机构官网 |
+| 工具能力/用法 | 官方文档、源码 |
+
+**找不到官网时**：权威媒体的原创报道（非转载）可作为次级依据，但需向用户说明："未找到官方原文，以下核实来自[媒体名]报道，存在转述误差可能。"单一来源时同样向用户声明。
+
+## 站点经验
+
+操作中积累的特定网站经验，按域名存储在 `references/site-patterns/` 下。
+
+确定目标网站后，如果前置检查输出的 site-patterns 列表中有匹配的站点，必须读取对应文件获取先验知识（平台特征、有效模式、已知陷阱）。经验内容标注了发现日期，当作可能有效的提示而非保证——如果按经验操作失败，回退通用模式并更新经验文件。
+
+CDP 操作成功完成后，如果发现了有必要记录经验的新站点或新模式（URL 结构、平台特征、操作策略），主动写入对应的站点经验文件。只写经过验证的事实，不写未确认的猜测。
+
+文件格式：
+```markdown
+---
+domain: example.com
+aliases: [示例, Example]
+updated: 2026-03-19
+---
+## 平台特征
+架构、反爬行为、登录需求、内容加载方式等事实
+
+## 有效模式
+已验证的 URL 模式、操作策略、选择器
+
+## 已知陷阱
+什么会失败以及为什么
+```
+经验/陷阱内容标注发现日期，当作"可能有效的提示"而非"保证正确的事实"。
+
+## References 索引
+
+| 文件 | 何时加载 |
+|------|---------|
+| `references/cdp-api.md` | 需要 CDP API 详细参考、JS 提取模式、错误处理时 |
+| `references/site-patterns/{domain}.md` | 确定目标网站后，读取对应站点经验 |