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