Agent-Crawl

AI 辅助的浏览器采集 CLI。

它和 agent-e2e 使用相似入口，但目标不同：agent-e2e 产出可回放测试配置，agent-crawl 面向网页内容采集、语义抽取、筛选和文件导出。

快速开始

npm install
npm run build

agent-crawl config set llm.apiKey <your-key>
agent-crawl https://example.com

也可以用环境变量：

export AGENT_CRAWL_LLM_API_KEY=<your-key>
export AGENT_CRAWL_LLM_MODEL=gpt-4o

进入 Chat 后可以直接说：

当前页面主列表里的详情内容你爬下，转成 markdown 格式，放到 ~/Downloads/details.md

当前列表页获取 id、姓名，然后到每条详情页里获取用户电话号码，导出 id、姓名、电话号码 三列 Excel

当前页下拉过滤浙江省、杭州市，再过滤市场销售。过滤后的列表每页 detail 都进去，在详情页工作经历里语义匹配教育或互联网直播相关经历，符合的整理成 Excel，列是 id、姓名、电话号码、工作单位

启动后会先输出访问诊断，例如 public_static、public_dynamic、auth_required、 auth_available、captcha_or_verify、permission_blocked 或 rate_limited，并自动选择 static fetch、Chrome Headless、browser session、handoff 或 fail-closed。普通用户不需要 提前判断目标站点类型。

CLI

agent-crawl <url>
agent-crawl chat <url>
agent-crawl config
agent-crawl config set llm.apiKey <key>
agent-crawl config show

高级用法

需要复用浏览器登录态、做 canary 或让外部 agent 精确控制浏览器时，再使用这些参数：

agent-browser profiles
agent-crawl https://example.com/folder --headed
agent-crawl https://example.com/folder --browser-state ~/.agent-crawl/auth/site.json
agent-crawl https://example.com/folder --browser-auto-connect
agent-crawl https://example.com/folder --browser-cdp 9222

这些模式适合短信验证码、第三方登录或用户已在 Chrome 中登录的站点。普通入口诊断到 auth_required 时，会提示用户在打开的浏览器窗口完成登录，再回到 Chat 输入“继续”。 继续 会重新运行访问诊断；只有 blocker 解除后才恢复采集。它们只复用用户已授权的 浏览器状态；遇到验证码、登录失效、限流或访问控制仍会 fail closed，不会绕过验证。

Chat 中的 auth_handoff 会返回当前 URL/title、页面 blocker、navigator.webdriver、是否已连接 CDP，以及可直接重启的 --headed / --browser-cdp 命令建议。若 discovery 只看到登录页导航、账号菜单或其他低置信候选，pipeline 会停止抓详情并在 manifest 里记录 warning。

浏览器会话的同源策略只用于 discovery/采集裁决，不会默认传给 agent-browser --allowed-domains 做网络资源过滤。很多登录态 SPA 会从独立 CDN、上传域或静态资源域加载编辑器、图片和正文通道；如果把 seed host 当成浏览器资源白名单，详情页可能表现为空白并在 DevTools 中出现 ERR_BLOCKED_BY_CLIENT.Inspector。

部分高风控登录页会识别受控浏览器环境；如果人工点击登录后按钮变灰、无短信或无跳转，改用用户手动启动的 Chrome CDP 模式：

open -na "Google Chrome" --args \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.agent-crawl/chrome-cdp-profile"

# 在这个 Chrome 窗口里手动登录目标站点，然后：
agent-crawl https://example.com/folder --browser-cdp 9222

如果要复用日常 Chrome 的 Default profile，需要用户先自行关闭 Chrome 并用 CDP 参数重新打开；不要由脚本强制关闭用户浏览器。

默认数据目录是 ~/.agent-crawl，可通过 AGENT_CRAWL_HOME 修改。每次会话会创建独立产物目录，Chat 里的 write_markdown、write_excel、write_json 工具会把文件落到用户指定路径或默认产物目录。

当前边界

第一版初始化的是基础架构和可运行 Chat 主链路：

• 自动入口：agent-crawl <url> 会先运行 AccessDiagnosis，再自动选择 static fetch、Chrome Headless、browser session、handoff 或 fail-closed。
• 浏览器直连：基于 agent-browser 打开页面、读取 snapshot、点击、填写、滚动、读取页面文本。
• 凭证隔离：启动参数中的密码只通过 browser_fill_secret 使用，不进入普通工具参数。
• 登录 handoff：支持 --headed 下人工完成短信验证码/SSO/第三方登录，再由 agent 复用同一 browser session 继续采集。
• 通用列表/详情发现：static href、browser href、SPA click probe 会合并成带 role/confidence/blocker 的发现合同；登录页、权限页、低置信导航和空白加载页 fail closed。
• 页面证据：read_current_page 会抽取当前页面文本、markdown 和链接。
• 访问 fallback：resilient_fetch_page 会按 curl 移动端 UA、Chrome Headless dump-dom、浏览器 session DOM 的顺序读取公开页面。
• 正文证据：browser session DOM 等待正文候选区域稳定，ContentEvidence 保存候选根评分/原因/备选项；无 LLM transform 只有正文密度达标才会 high confidence。
• 微信公众号合集：fetch_wechat_album_articles 可抓取 mp.weixin.qq.com/mp/appmsgalbum 前 N 篇文章正文；支持合并 Markdown，或每篇独立 Markdown + 标题/原文链接 Excel 索引。
• 语义抽取：extract_records 使用 LLM 把页面内容转成结构化 records。
• 语义筛选：semantic_filter_records 用 LLM 判断模糊条件，避免只能靠关键词。
• 文件导出：支持 Markdown、JSON、Excel。

访问 fallback 的边界是 fail closed：如果页面返回验证码、登录、限流或访问限制，工具会报告阻塞，不会绕过验证码、伪造身份或规避访问控制。

低置信结果不会静默导出 Markdown。raw HTML、evidence 和 transform 可以保留用于复查，但 confidence=low 或空正文会阻止 Markdown 导出。

后续要增强的是自动化 executor：分页遍历、列表项详情页展开、断点续跑、去重、限速、增量采集和更强的抽取 schema。

开发

npm run typecheck
npm run test
npm run lint
npm run build

架构

详细说明：

• Architecture
• Content Evidence Pipeline
• Auto Crawl Frontdoor