@dej4vu/websearch-cli

English | 简体中文

面向 Codex、Claude Code 及其他 CLI 助手代理的网页工具。目前提供 Bing 中文搜索、微信公众号文章搜索（经搜狗微信）、网页正文抓取、带黑名单的 Bing 结果抓取。

使用 npx 运行

默认无需全局安装，也无需代理：

npx -y @dej4vu/websearch-cli@latest fetch https://example.com --json

请先使用上面的普通形式。如果沙箱 shell 继承了不可用的本地代理，导致 npx 本身失败，再把清除继承代理变量作为备选方案：

env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
  -u http_proxy -u https_proxy -u all_proxy \
  npx -y --registry=https://registry.npmjs.org/ \
  @dej4vu/websearch-cli@latest fetch https://example.com --json

自动化场景可将 latest 替换为已发布版本。查询最新发布版本：

npm view @dej4vu/websearch-cli version

npx -y @dej4vu/websearch-cli@<version> fetch https://example.com --json

提示：npx 命令请保留 @latest，始终解析最新发布版本。如果 npx 仍运行旧的缓存副本，先清空 npx 缓存再重试：

rm -rf ~/.npm/_npx

如果包安装成功，但 search 或 fetch 目标请求遇到网络或反爬问题，可为该请求显式追加代理重试：

npx -y @dej4vu/websearch-cli@latest fetch https://example.com \
  --proxy-url http://127.0.0.1:7890 --json

代理是目标请求的备选方案，不是默认要求。请把示例 URL 替换为你环境中可用的 HTTP/HTTPS 代理。

如果想使用全局短命令（可选）：

npm install --global @dej4vu/websearch-cli
websearch fetch https://example.com --json

Bing 中文搜索

npx -y @dej4vu/websearch-cli@latest search "人工智能 最新进展" --count 10 --json

翻页：

npx -y @dej4vu/websearch-cli@latest search "人工智能 最新进展" --count 20 --offset 20 --json

普通文本输出按排名展示标题、URL、站点、摘要和可解析出的日期。JSON 输出包含 sort、freshness、requestedCount、resultCount、pagesFetched、pagesRequested、duplicatesRemoved、totalResults、hasMore；每条结果包含 rank、title、url、snippet、displayUrl、publishedAt、publishedAtText、publishedAtSource、dateMissing、fetchBlocked。

搜索选项

| 选项 | 说明 | |---|---| | --engine <name> | 搜索引擎：bing、weixin 或 all（双引擎合并）。 | | --count <n> | 返回结果条数（默认 10，最大 50）。 | | --offset <n> | 从该偏移量开始分页。 | | --sort <mode> | auto、relevance 或 date。 | | --freshness <window> | any、day、week 或 month。 | | --proxy-url <url> | 为 Bing 请求指定 HTTP/HTTPS 代理。 | | --timeout-ms <n> | 搜索超时（默认 15000）。 | | --json | 输出结构化搜索结果。 |

引擎会向 https://cn.bing.com/search 发送浏览器风格请求头，启用 Bing 中文网页结果模式；当 count > 10 时跟进原生「下一页」token、解码 Bing 跳转 URL，并在排序前聚合与去重。

auto 模式识别 最新、发布、上线、release、latest、news 等时效意图词，自动应用 month 时间过滤和日期排序；普通技术类查询保持相关性排序。这里的「时效」并不等同于严格的发布时间保证：

npx -y @dej4vu/websearch-cli@latest search "GLM 最新模型" --count 15 --json

npm registry / 代理问题排查

npx 会继承 shell 的代理变量和 npm registry 配置。在沙箱化 shell 中，本地代理如 127.0.0.1:7890 可能被拦截，出现：

EPERM ... connect 127.0.0.1:7890

针对这种 npx 安装阶段的问题，去掉继承的代理变量，并显式使用官方 registry：

env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
  -u http_proxy -u https_proxy -u all_proxy \
  npx -y --registry=https://registry.npmjs.org/ \
  @dej4vu/websearch-cli@latest search "GLM 最新模型" --json

包同时发布在 npmjs.com 与 npmmirror.com；此报错通常是代理连接被拦截，而不是版本缺失。

清除变量只解决包安装阶段的代理继承问题，不会让 CLI 自身请求走代理；目标请求需要代理时，仍要显式使用 --proxy-url。

日期尽量从 Bing 的 .news_dt、摘要、标题和 URL 解析；无法得到可信日期时 dateMissing 为 true，不伪造时间戳。官方域名获得适度加权用于同分场景；有明确日期的结果在日期排序中仍占主导。

微信公众号文章搜索

通过搜狗微信搜索公众号文章：

npx -y @dej4vu/websearch-cli@latest search "Temporal 工作流" --engine weixin --count 10 --json

引擎请求 https://weixin.sogou.com/weixin?type=2，并把每条搜狗 /link?url=... 跳转解析成真实的 mp.weixin.qq.com 文章 URL，返回公众号名称、精确发布时间、摘要和封面图。--sort date 按发布时间排序；--offset 支持最多 10 页翻页。

搜狗的时间筛选参数目前已在服务端失效，因此该引擎不支持除 any 以外的 --freshness 值。如果搜狗返回反爬验证页，CLI 会报出明确错误；可稍后重试，或通过 --proxy-url 走代理。

该引擎返回的微信文章 URL 是限时签名链接，请在搜索后尽快抓取；过期是搜狗/微信平台行为，不是 CLI 缺陷。

双引擎聚合

--engine all 并行查询 Bing 中文和搜狗微信，合并返回：

npx -y @dej4vu/websearch-cli@latest search "GLM 最新模型" --engine all --count 10 --json

相关性模式按两个引擎轮询交错；date 模式按发布时间全局排序。跨引擎重复结果会去重，每条结果带 engine 字段（bing-cn 或 weixin-sogou）。单个引擎失败时仍返回另一引擎结果，并在顶层 warnings 中说明；--freshness 只作用于 Bing 引擎。每个引擎单次查询窗口最多贡献 50 条结果，深翻页 --offset 受此上限约束。

Fetch 抓取

fetch 执行 HTTP GET、跟随重定向、检查 robots.txt、提取正文 HTML 并转换为 Markdown。非 HTML 内容按原始响应文本返回。

npx -y @dej4vu/websearch-cli@latest fetch https://example.com

大页面分块读取：

npx -y @dej4vu/websearch-cli@latest fetch https://example.com --max-length 10000 --json

# 使用 JSON 结果中的 nextStartIndex 继续。
npx -y @dej4vu/websearch-cli@latest fetch https://example.com --start-index 10000 --json

选项

| 选项 | 说明 | |---|---| | --max-length <n> | 返回最大字符数（默认 10000，最大 1000000）。 | | --start-index <n> | 从该字符偏移量开始返回。 | | --raw | 跳过 readability 提取和 Markdown 转换。 | | --user-agent <ua> | 自定义 User-Agent。 | | --proxy-url <url> | HTTP/HTTPS 代理。 | | --ignore-robots-txt | 关闭 robots.txt 检查。 | | --timeout-ms <n> | 单请求超时（默认 30000）。 | | --json | 输出结构化元数据与内容。 |

默认遵守 robots.txt。除非用户明确要求且用途合规，否则不要使用 --ignore-robots-txt。

微信文章

fetch 针对 mp.weixin.qq.com 文章做了专用提取：读取通用 readability 会跳过的隐藏 #js_content 正文，把懒加载的 data-src 图片还原为真实图片 URL，将微信代码块（每行一个 <code> 元素）保留为换行完整的围栏代码，清理作者的排版占位（纯 nbsp 空段、仅含图片的标题、装饰性行号），并在 Markdown 顶部附加文章标题、公众号名称和发布时间。JSON 输出还会包含 articleMeta 对象。已删除、违规屏蔽、仅粉丝可见和环境验证页会返回明确的错误提示，而不是输出拦截页文字。

npx -y @dej4vu/websearch-cli@latest fetch "https://mp.weixin.qq.com/s?src=11&timestamp=...&signature=...&new=1" --json

mp.weixin.qq.com 的 robots.txt 对全站 Disallow，包括用户明确提供的文章链接。对该域名，fetch 按用户主动访问处理，跳过自主爬虫 robots 检查；签名链接本身的过期与访问控制仍由微信侧强制。带 timestamp/signature 参数的签名 URL 会过期，搜狗搜索后需尽快抓取；永久链接 mp.weixin.qq.com/s/<id> 不会过期。

掘金和语雀文章

fetch 对常见中文文章/文档站也有专用处理。掘金文章（juejin.cn/post/...）直接读取 SSR 正文，保留真实表格和围栏代码，安全展开语法高亮片段中导致转换崩溃的空标记表格，还原 link.juejin.cn 跳转链接，并在正文顶部附加标题、作者和发布日期。公开语雀文档会获取同一文档的 Markdown 表示，保留文档元数据，去除代码块外仅用于编辑器着色的 <font> 包装，并在正文顶部附加文档标题。两个站点在 JSON 输出中都会提供 articleMeta 对象。

npx -y @dej4vu/websearch-cli@latest fetch "https://juejin.cn/post/..." --json
npx -y @dej4vu/websearch-cli@latest fetch "https://www.yuque.com/<user>/<book>/<doc>" --json

安全提示：该命令可访问网络可达地址，包括内网地址（取决于宿主机策略）。请为不可信代理配置审批策略。

Bing 结果抓取

bing-fetch 与 fetch 行为一致，但额外执行 bing-search-cn skill 的黑名单：

npx -y @dej4vu/websearch-cli@latest bing-fetch https://example.com --json

拦截以下根域名及其子域名：

zhihu.com, xiaohongshu.com, xhs.com, weibo.com, weixin.qq.com,
douyin.com, tiktok.com, bilibili.com, csdn.net

JSON 搜索结果会把命中的条目标记为 fetchBlocked: true。通用 fetch 命令不会应用这份额外黑名单。

Agent Skill

skills/websearch/SKILL.md 是规范 skill 文件。请使用 skills 作为主要安装方式。skill 管理器与 websearch CLI 都要求 Node >=22.20。

用户级安装

npx -y skills@latest add dej4vu/websearch --skill websearch --agent codex --agent claude-code --agent hermes-agent --global --yes

在 [email protected] 中，Codex 规范副本放 ~/.agents/skills/，Claude Code 链接到 ~/.claude/skills/，Hermes 链接到 ~/.hermes/skills/。skills 文档里 Codex 的名义全局路径是 ~/.codex/skills/，实际使用通用安装路径。Hermes 使用自定义 home 时，安装前设置 HERMES_HOME。

项目级安装

npx -y skills@latest add dej4vu/websearch --skill websearch --agent codex --agent claude-code --agent hermes-agent --yes

在 [email protected] 中，项目级 Codex 使用 .agents/skills/。当项目不存在 .hermes/ 目录时，项目级软链安装会跳过 Hermes；如需生成 Hermes 软链，先创建该目录：

mkdir -p .hermes
npx -y skills@latest add dej4vu/websearch --skill websearch --agent codex --agent claude-code --agent hermes-agent --yes

或使用 --copy 为所有 agent 生成真实目录：

npx -y skills@latest add dej4vu/websearch --skill websearch --agent codex --agent claude-code --agent hermes-agent --copy --yes

本仓库已忽略生成的 .agents/、.claude/、.codex/、.hermes/ 目录，避免本地安装产物误提交。

管理已安装的 skill

npx -y [email protected] list
npx -y [email protected] list --json
npx -y [email protected] remove websearch --yes

本地开发安装

npx -y skills@latest add . --skill websearch --agent codex --agent claude-code --agent hermes-agent --yes

CI 或可复现自动化建议同时固定管理器版本和源码 tag。将 <release> 替换为 Releases 页面 中已发布的 tag：

npx -y [email protected] add 'dej4vu/websearch#v<release>@websearch' --skill websearch --agent codex --agent claude-code --agent hermes-agent --global --yes

不安装即可查看规范 skill：

npx -y [email protected] add . --list

开发

npm install
npm test
node ./bin/websearch.js --help

npm test 为离线回归，覆盖：

• 基础提取、截断、robots、raw 模式与代理测试；
• 文档站与 pre > span 高亮代码块场景的回归；
• 微信、掘金和语雀文章提取回归；
• 对齐官方 mcp-server-fetch 的 20 项测试；
• Bing 搜索 URL/freshness 构造、日期解析、意图排序、多页聚合、跳转还原、canonical 去重与黑名单测试。

知名站点矩阵

另有包含 22 个国内知名站点和 20 个国际站点的联网测试矩阵：

npm run test:sites -- --output /tmp/websearch-site-report.json

矩阵检查 HTTP 状态、提取成功率、预期文本和最小内容长度。它刻意不绕过 robots.txt，被 robots 拦截的 URL 会单独分类而非计为成功抓取。网络结果会随时间变化，因此该命令不属于默认离线测试套件。

Issue 驱动开发

• 非琐碎工作先建 GitHub issue，写清背景、约束和验收标准；新建前先搜索是否已有重复 issue。
• 开发在 codex/* 分支进行；PR 通过 Closes #N 关联 issue，合并后自动关闭。
• 发版用 checklist issue 跟踪（合并 → 升版本 → 打 tag → OIDC 发布）。

开源协议

MIT