xwebsearch — VS Code 扩展
给 Claude Code 装好 xwebsearch:一个零依赖的网页搜索 CLI。
扩展自带本仓库的源码(.vsix 由仓库构建产出,不是手抄的第二份,所以不会漂移),
所以你只需要这一个文件 —— 不用 git、不用 clone。
安装
让 AI 装 —— 最短路径
把 .vsix 放到手边,发给 Claude Code / 任意 AI 助手:
把这个 .vsix 装到 VS Code(code --install-extension),然后我重载窗口自己跑命令面板里的
「xwebsearch: 安装 / 更新」。需要我本人授权的步骤列出来给我。
或者手动装
code --install-extension xwebsearch-extension.vsix
然后重载 VS Code 窗口(Ctrl+Shift+P → Developer: Reload Window),命令面板里会有:
| 命令 |
作用 |
| xwebsearch: 安装 / 更新 |
把自带源码复制到固定目录 → npm link → 让选中的 agent 认识它 |
| xwebsearch: 检查状态 |
看命令 / 安装目录 / skill 三样齐不齐 |
| xwebsearch: 选择要覆盖的 agent |
重新选哪些 agent 要知道这个工具 |
| xwebsearch: 加入权限规则 |
往 ~/.claude/settings.json 加 Bash(xwebsearch:*),免去每次弹框 |
状态栏右下角会显示 xwebsearch ✓ 或 xwebsearch !。
支持哪些 AI agent
工具本身跟 agent 无关。 npm link 之后 xwebsearch 就是个普通命令行工具 —— Codex、Trae、
Cursor、Copilot,甚至你在终端里手敲,都能跑。
不同的是**「AI 怎么知道该用它」:每个 agent 有自己的约定文件。安装时会检测你装了哪些**,
如果一个以上,让你勾选要覆盖哪些:
| Agent |
写到哪里 |
范围 |
| Claude Code |
~/.claude/skills/xwebsearch/SKILL.md |
全局 |
| Codex |
AGENTS.md(有项目则项目内,否则 ~/.codex/) |
项目优先 |
| Trae |
<项目>/.trae/rules/project_rules.md |
项目级 |
- 只检测到 1 个 → 直接写,不打扰你
- 检测到多个 → 弹出多选,全选即可
- 选择会被记住,之后更新不再重复问;新装了 agent 会重新问一次
- 想改主意:命令面板 →「xwebsearch: 选择要覆盖的 agent」
Trae 的规则是项目级的,没有全局文件可写。所以选 Trae 时需要先打开一个项目文件夹;
没打开的话它会跳过并在日志里说明。
不会覆盖你的文件。 对于 AGENTS.md / project_rules.md 这类你可能已经在用的文件,
扩展只在末尾追加一段带标记的区块:
<!-- BEGIN xwebsearch (managed by the xwebsearch VS Code extension) -->
...
<!-- END xwebsearch -->
重复运行是替换这段区块,不会累加、也不会动你自己写的内容。
只收录了实测确认过约定的 agent。Cursor(.cursor/rules)和 Windsurf(.windsurf/rules)
形状相同,但没验证过确切文件名,所以没写进来 —— 猜一个路径只会让你去找一个 agent 根本不读的文件。
装完之后还剩两步(故意的)
这两件扩展不会替你做,因为都是你的决定:
- 权限规则 —— 不加也能用,只是 Claude 每次调用都会问你一次
- 在 Claude Code 里跑
/reload-skills —— 让新写入的 skill 被加载。这是斜杠命令,扩展调不了
⚠️ 已经装过的人
如果你已经用 npm link 从源码装过 xwebsearch,扩展会检测到并问你:
- 保留现有的(默认,推荐)—— 不动你的全局命令,只补上 skill
- 让扩展接管 —— 重新装一份并把全局命令指过去,你原来的安装不再生效
这个默认很要紧:npm link 会把命令指向执行时所在的目录,无脑接管会让开发者正在改的仓库失效。
设置
| 项 |
默认 |
说明 |
xwebsearch.installRoot |
扩展存储目录 |
装到哪。别改成临时目录 —— 见下 |
xwebsearch.skillsDir |
~/.claude/skills |
skill 写到哪 |
xwebsearch.autoInstallOnStartup |
false |
启动时缺就自动装。默认关,避免静默改动环境 |
为什么默认放扩展存储目录:npm link 把全局命令指向执行 link 时所在的目录,所以目录被清理或
移动,命令就废了。扩展存储目录是每扩展独立、跨重启稳定、不会被清理的。
用法
扩展只负责装。工具本身的用法看主仓库的
README:
xwebsearch "<query>" -f json # 搜索,机器可读
xwebsearch doctor # 看哪些引擎在你的网络下能用
xwebsearch "<query>" --fetch-top 3 # 顺带读前 3 条正文(需要 xwebfetch)
它和 xwebfetch 是一对:搜不到就用它搜,有 URL 就用
xwebfetch 读。两个是独立仓库,要分别安装。
开发
node extension/build.mjs # 或 cd extension && npm run package
build.mjs 把扩展和本仓库的 bin/src 一起暂存到 extension/.build/,在那里调用 vsce package。
装出来的东西是构建产物,仓库始终是唯一真相来源。
卸载
⚠️ 卸载扩展不会自动清理它装的东西。 VS Code 只删扩展自己,剩下的都会留着:
| 装了什么 |
卸载扩展时 |
| 扩展代码 |
✅ 会删 |
工具副本 + node_modules |
❌ 留着(在扩展存储目录里) |
| npm 全局链接(6 个 shim + 符号链接) |
❌ 留着 —— 所以 xwebsearch 命令还会在 |
skill(~/.claude/skills/) |
❌ 留着 |
AGENTS.md / project_rules.md 里的区块 |
❌ 留着 |
settings.json 权限规则 |
❌ 留着 |
危险在于:卸载后命令可能还在、还能跑,但指向一个没人管的副本 —— 你以为卸干净了,其实留了个失控的命令。
正确顺序:先清理,再卸载扩展。
命令面板 → xwebsearch: 卸载并清理
它会逐项列出将删除什么,你确认后才动手。或者用 CLI:
xwebsearch --uninstall --dry-run # 只预览,不改动
xwebsearch --uninstall # 交互确认
xwebsearch --uninstall --yes # 免确认
为什么这条 CLI 路径重要:卸载扩展后 npm 链接和 skill 会留下,所以命令通常还活着 ——
它正好是收拾残局最合适的入口。这也是清理没做成"卸载钩子"的原因:
- VS Code 没有「即将卸载」事件(唯一相关的
extensions.onDidChange 是事后通知,那时扩展已经不在内存里)
deactivate() 不是卸载钩子 —— 它在扩展更新时也会调用,把清理放那儿会导致每次更新都删掉你装好的工具
限制
- 只在 VS Code 里管安装。装出来的 CLI 是普通命令行工具,终端、别的编辑器、CI 里照样能用
- 不发布到 Marketplace,团队内部用
.vsix 分发