webfetch-plus

WebFetch Plus

执行原则

• 把当前 skill 路径设置给 WFP_PATH
• 任何命令执行，必须先 cd "$WFP_PATH"
• 普通抓取可用管道，跳过安全提示
• 管道输入按空白字符拆分参数；URL 和参数值不得包含空格
• 脚本按 runtime/node/package.json 自动安装 CloakBrowser 与 Playwright；首次安装会使用进程锁，其他调用会等待完成
• Agent / 非 TTY 环境不要运行人工验证流程；脚本会从 /tmp/wfp-states/*.json 自动选择匹配目标域名的最新会话，找不到时才报告需要交互验证
• 默认 state 路径的唯一权威是 runtime 的 getDefaultStatePath()：/tmp/wfp-states/<hostname-clean>.json（hostname-clean 为 URL hostname 中非字母数字和连字符替换为 - 的结果）。不要在调用方自行猜测或另行实现该命名。

外部副作用

• 访问传入的 HTTP(S) URL，并启动本地浏览器；--stealth 首次使用可能下载 Chromium
• 正文默认写入 /tmp/wfp-tasks/
• 失败证据始终写入 /tmp/wfp-evidence/，不受 --output-dir 影响
• --save-state 会写入 Playwright storageState JSON（cookies / localStorage）；文件可能含登录态，勿提交到 git
• --out 和 --output-dir 会写入调用方指定路径；不要让多个调用共用同一 --out 路径

抓取网页

管道传入 URL 和参数：

echo "https://example.com" | bash "bin/wfp.sh"

也可直接传参：

bash bin/wfp.sh "https://example.com" --wait 3000

脚本在 stdout 输出正文文件路径。

动态页面超时

动态页面长期保持连接时，networkidle 可能连续导航超时。此时改用 --wait-until domcontentloaded，并按页面实际加载时间提高 --timeout；例如：

bash bin/wfp.sh 'https://example.com' --wait-until domcontentloaded --timeout 90000

验证码、登录与会话复用

遇到人机验证或登录时，在交互 TTY 中运行启动器，完成验证后按回车。启动器会以 headed + stealth 模式保存该目标的默认会话；未显式传入 --wait-until 时使用 domcontentloaded，显式值优先：

bash bin/wfp-human.sh 'https://example.com/protected-page'

后续普通抓取会复用会话：--state 优先；未提供时，脚本从 /tmp/wfp-states/*.json 中验证 cookie 域名或 localStorage origin 与目标域名匹配，并采用最新文件。会话过期再次被拦时，重新运行启动器即可覆盖默认 state。

风控拦截且没有可复用会话时，stderr 会输出一条带实际目标 URL 的可复制启动器命令。自动任务和 Agent 不运行启动器，只使用已有或自动发现的会话。非 TTY 的 macOS 调用会自动打开 Terminal。

参数

参数	说明
--out <path>	直接写入指定文件；同一路径不可并发使用
--output-dir <path>	将唯一正文文件直接写入该目录
--visible	显式打开浏览器窗口（headed）；默认隐式 headless
--state <path>	显式加载 Playwright storageState JSON（优先于自动发现；文件必须已存在）
--save-state <path>	抓取成功后保存 storageState JSON
--wait <ms>	页面加载后额外等待时间
--timeout <ms>	页面导航超时时间，默认 45000
`--wait-until <load	domcontentloaded
--retries <1-3>	最多尝试次数，默认 3；首次发现 WAF 时后续自动 --stealth
--selector <css>	只抽取指定 CSS 选择器内容
`--format <markdown	text
--stealth	CloakBrowser 定制 Chromium 增强反 WAF

人工验证不属于公开 wfp.sh 参数。仅通过 bash bin/wfp-human.sh '<url>' [fetch options] 启动；启动器会强制 headed 与 stealth，并保存默认 state。它拒绝 --state、--save-state、--out、--visible 等受管理参数。

执行流程

传入 URL →（优先 --state，否则自动匹配本地会话）→ 抓取
  → 若 WAF：自动 stealth 重试 → 仍失败则提示 wfp-human.sh 启动器
  → 启动器内部启用人工验证 → 等人回车 → reload 目标 URL → 保存 state
  → 成功则可选 --save-state → stdout 输出正文路径

成功判定：stdout 输出唯一正文路径

• 空标题 + 极短正文 + 大 HTML / 可见挑战文案 → 失败
• 已有真实标题且正文够长时，不因 HTML 中残留挑战相关 CSS 或文案误判失败

失败处理契约：

1. 非零退出；stderr 输出 failure summary 路径，evidence 的 suggestion 保留同一建议
2. 首次 WAF → 剩余重试自动 --stealth
3. stealth 仍失败且没有匹配的 /tmp/wfp-states/*.json 会话 → 最终 stderr 只输出一条带实际目标 URL 的完整可复制启动器命令：bash bin/wfp-human.sh '<url>'
4. 人工挑战同页可多次回车；挑战未消失会提示再试，不会立刻关页重开三轮

通用规则：

• 默认 headless；启动器内部人工挑战强制 headed，且不隐藏启动窗口
• 启动器不自动解滑块
• 无人值守任务只用 --state，不要运行启动器