CrawlerCLI

面向人、脚本和 Agent 的多平台浏览器数据采集 CLI。

CrawlerCLI 复用本机 Chrome 的真实登录态，通过 Playwright 获取页面和网络数据，再输出统一的 Table 或 JSON 结果。CLI、daemon、浏览器和账号 Profile 都运行在本机，不依赖远程服务端。

当前支持：

• Twitter / X
• Douyin
• Weibo

特点

• 统一命令：平台能力统一为 crawlercli <platform> <command>。
• 真实浏览器取数：复用页面上下文、Cookie 和平台自身产生的网络请求。
• 多平台多账号：按 platform/account 隔离 Chrome Profile。
• 并发管理：统一限制浏览器实例、Page、账号和平台并发。
• 登录态持久化：浏览器关闭后，登录状态仍保存在本地 Profile。
• 稳定输出：Table 面向人工，JSON 面向脚本和 Agent。
• 失败诊断：持久化脱敏日志，可选保存失败截图和页面 HTML。
• 易于扩展：平台 Adapter 复用统一命令、运行时、浏览器和输出层。

环境要求

• Node.js 20 或更高版本
• 本机已安装 Google Chrome

CrawlerCLI 使用 playwright-core 驱动系统 Chrome，不下载 Playwright 内置浏览器。

安装

从 npm 全局安装：

npm install -g @rlwb/crawlercli

确认安装：

crawlercli --version
crawlercli doctor

升级到最新版：

npm install -g @rlwb/crawlercli@latest
crawlercli daemon restart

CLI 升级只会更新 npm 包，不会自动覆盖 Codex、Claude Code 等 Agent 已经安装的 Skill。使用 Agent Skill 的用户还需要重新执行：

npx skills add echoonlyecho/CrawlerCli --skill crawlercli-usage

更新后重启 Agent，使新版 Skill 重新加载。

从源码运行：

git clone https://github.com/echoonlyecho/CrawlerCli.git
cd CrawlerCli
npm install
npm run build
npm link

快速开始

crawlercli doctor
crawlercli auth login twitter
crawlercli auth status --all-accounts --full
crawlercli twitter search "openai" --type user --limit 20
crawlercli douyin search "央视新闻" --type user --limit 20
crawlercli weibo search "人工智能" --type post --limit 20

auth login 会打开可见 Chrome。登录完成后回到终端按 Enter，状态会保存在对应平台的本地 Profile。

使用 -f json 输出适合脚本和 Agent 消费的 JSON：

crawlercli twitter profile openai -f json

常用命令

内置命令

crawlercli list
crawlercli doctor
crawlercli config list
crawlercli auth accounts
crawlercli auth status --all-accounts --full
crawlercli daemon status

Twitter / X

crawlercli twitter search "<keyword>" --type user --limit 20
crawlercli twitter user-posts "<screen_name>" --limit 20
crawlercli twitter profile "<screen_name>"

Douyin

crawlercli douyin search "<keyword>" --type user --limit 20
crawlercli douyin profile "<sec_uid|profile_url>"
crawlercli douyin user-posts "<sec_uid|profile_url>" --limit 20
crawlercli douyin post "<aweme_id|video_url>"

Weibo

crawlercli weibo hot --limit 30
crawlercli weibo search "<keyword>" --type post --limit 20
crawlercli weibo profile "<uid|screen_name>"
crawlercli weibo user-posts "<uid|screen_name>" --limit 20
crawlercli weibo post "<idstr|mblogid>"
crawlercli weibo comments "<idstr>" --limit 20
crawlercli weibo feed --type following --limit 20
crawlercli weibo favorites --limit 20
crawlercli weibo me

完整语法、参数、返回字段和示例见 命令手册。

架构

下图展示平台抓取命令的启动注册和执行主链路：

flowchart LR
    subgraph Startup[启动注册]
        Modules[Platform Adapter 模块] --> Registry[CommandSpec Registry]
        Registry --> CLI[CLI 命令树]
    end

    User[用户 / 脚本 / Agent] --> CLI
    CLI --> Dispatch[匹配 CommandSpec 与校验参数]
    Dispatch --> Context[创建并注入 CommandContext]
    Context --> AdapterRun[Platform Adapter 执行]
    AdapterRun --> BrowserAPI[调用 CommandContext 浏览器接口]
    BrowserAPI --> Daemon[本地 Playwright Daemon]
    Daemon --> Scheduler[账号与平台调度]
    Scheduler --> Slots[全局 Page 槽位]
    Slots --> Manager[BrowserInstanceManager]
    Manager --> BrowserContext[platform/account BrowserContext]
    BrowserContext --> Page[Playwright Page]
    Page <--> Platform[目标平台]
    Page --> Data[页面与网络数据]
    Data --> AdapterParse[Platform Adapter 解析]
    AdapterParse --> Result[CanonicalResult]
    Result --> Output[Table / JSON]
    Output --> User

Loading

详细设计见 技术架构，汇报版说明见 项目架构说明。

账号与浏览器

每个 platform/account 使用独立 Chrome Profile，默认位于 ~/.crawlercli/profiles/<platform>/<account>。--account 是本地别名，不要求等于平台用户名。

crawlercli auth login twitter --account personal
crawlercli auth whoami twitter --account personal
crawlercli auth logout twitter --account personal
crawlercli twitter profile openai --account personal

普通抓取默认无头运行。可持久化设置，也可按命令覆盖：

crawlercli config set browser.headless false
crawlercli twitter profile openai --headed

平台命令会自动连接本地 daemon。daemon 默认监听 127.0.0.1:19826，统一管理浏览器实例、Page 并发和账号冷却；空闲实例自动关闭，登录态继续保存在 Profile 中。

输出与诊断

默认输出 Table，-f json 输出 JSON。业务结果写入 stdout，日志和错误写入 stderr。

~/.crawlercli/logs/commands.jsonl
~/.crawlercli/logs/daemon.log

平台命令添加 --artifacts 后，失败时会把截图和 HTML 保存到 ~/.crawlercli/artifacts/<run_id>/。默认不保存页面现场。

文档

• 完整命令手册
• 技术架构
• 汇报说明
• 变更记录
• 项目协作约束

AI Agent Skill

使用通用 Skills 安装器将 CrawlerCLI 使用规范安装到 Codex、Claude Code 等 Agent：

npx skills add echoonlyecho/CrawlerCli --skill crawlercli-usage

Skill 负责命令发现、登录态检查、账号选择、JSON 输出和错误恢复。执行数据采集前仍需安装 CLI：

npm install -g @rlwb/crawlercli

开发

npm run dev -- twitter search "openai" --type user --limit 10
npm run typecheck
npm run build
npm test
npm run test:integration

集成测试使用临时 daemon 端口、临时 Profile 和本地 HTTP fixture，不读取个人登录数据。

新增平台或命令时，需要同步：

1. 注册 CommandSpec
2. 补充正常路径和重要失败路径测试
3. 更新 docs/commands.md
4. 更新 CHANGELOG.md

当前边界

• 当前只提供读取能力，不包含发布、删除等写操作。
• 依赖真实 Chrome 和平台登录态，不适合无浏览器环境。
• 平台页面、接口或响应结构变化后，需要更新对应 Adapter。
• 当前是本地单机工具，不提供远程服务端。

License

Apache License 2.0