这次我们来看一个很有意思的开源项目：把任意网站改造成 AI Agent 可以直接调用的 CLI 接口。项目标题里最抓眼球的是那个对比数字——比直接用 HTML 给 AI 当上下文，最多能省 142 倍的 tokens。做过 AI 编程、Agent 开发、RAG 检索的读者应该都知道，tokens 意味着成本、延迟和上下文窗口上限。把网页 HTML 原样塞给模型，不仅费钱，信息密度也低。这个项目的思路是：与其让 AI 读 HTML，不如给它一个干净的 CLI，让它像调用本地命令一样去操作网站。
先快速给结论：这个项目核心解决的是 AI Agent 与网站交互效率问题，面向的是 Codex CLI、Claude Code、通用 Agent 框架以及任何支持工具调用的大模型应用。核心卖点有三条：tokens 消耗大幅下降、交互结构从“读页面”变成“调接口”、保留 MCP/Tool 生态的接入能力。本文会带你把项目跑起来，演示如何把一个网站包装成 CLI，并给出本地调用、接口验证、批量任务和 tokens 对比的完整测试流程。适合正在做 AI Agent 工具链、需要频繁让模型抓取网页信息、或者想省接口成本的开发者阅读。
1. 核心能力速览
以下参数基于项目标题和常见 Claude Code / Codex CLI 环境整理，具体数字需要以你本机运行结果为准。
| 能力项 | 说明 |
|---|---|
| 项目类型 | 网站转 CLI 工具，面向 AI Agent 的接口封装层 |
| 核心功能 | 把任意网站的操作抽象为 CLI 命令，供 AI Agent 调用 |
| 效率提升 | 相比直接传 HTML，tokens 消耗大幅降低（标题数据为 142x） |
| 运行环境 | 需要 Node.js 或 Python 环境，具体以项目 README 为准 |
| 启动方式 | 命令行安装 + 启动，可注册为 MCP 工具或 Tool 函数 |
| 是否支持 API | 支持，CLI 本身可作为函数调用接口 |
| 是否支持批量任务 | 可批量执行 CLI 命令，通过脚本或循环调用 |
| 适合场景 | AI 编程助手、Agent 网页操作、RAG 网页数据采集、自动化测试 |
| 技术门槛 | 中低，熟悉命令行即可上手 |
从项目定位看，它不是传统意义上抓取网页正文的爬虫工具，而是给 AI Agent 设计的一套“网站操作协议”。你不需要让模型理解复杂 HTML，只需要把网站暴露的搜索、翻页、点击、表单提交等行为封装成命令，模型调用命令就能拿到结果。
2. 适用场景与使用边界
这个项目第一类适用场景是 AI 编程助手。Codex CLI、Claude Code 这类工具在工作时经常需要查询文档、查看 API 示例、搜索网页信息。如果直接抓取 HTML，动辄几万 tokens 的网页内容会让上下文窗口迅速膨胀。做成 CLI 后，模型只需要传几个参数，返回的也是精简文本结果，省下大量上下文空间。
第二类是 Agent 自动化操作。比如你需要做一个电商比价 Agent、文档聚合 Agent、信息监控 Agent，过去要让 Agent 直接解析网页，现在可以先把目标网站抽象成 CLI，Agent 通过命令行完成操作。
第三类是 RAG 网页数据采集。把网页内容转成 CLI 输出后，可以配合脚本批量采集、清洗、入库，比解析 HTML 再切块的流程更可控。
使用边界需要重点关注。第一，这个项目不能绕开网站的登录鉴权、反爬限制和用户协议。把需要登录才能访问的页面包装成 CLI，本质上仍然是在访问受保护内容，必须确认你有合法访问权限。第二，版权问题。将网站内容抓取后用于训练模型或商业发布，需要获得授权，不能因为转成了 CLI 格式就觉得可以随意使用。第三，稳定性。网站改版会导致 CLI 失效，这是所有依赖网页结构项目的通病，需要定期维护。第四，安全责任。你自己封装的 CLI 命令，如果输入检查不严，可能引入命令注入风险，需要做好参数过滤。
3. 环境准备与前置条件
这个项目依赖 Node.js 环境，因为 CLI 工具链大多基于 Node.js 生态。测试机器建议准备以下环境：
3.1 基础环境检查
# 检查 Node.js 版本，建议 v18 以上 node -v # 检查 npm 版本 npm -v # 检查 Python 是否可用（部分辅助脚本可能需要） python --version如果是 Linux 服务器或 Windows WSL 环境，还需要确认网络可以正常访问 npm registry。国内网络环境建议配置 npm 镜像：
npm config set registry https://registry.npmmirror.com3.2 确认 AI CLI 环境
既然是给 AI Agent 用，需要确认本机已经配置好 Codex CLI 或 Claude Code：
# Codex CLI codex --version # Claude Code claude --version如果没有安装，可以用以下命令安装 Codex CLI：
npm install -g @openai/codex3.3 磁盘与目录规划
建议单独建一个工作目录，把网站转 CLI 项目、测试脚本、输出结果分开管理：
mkdir -p ~/website-cli-project/inputs mkdir -p ~/website-cli-project/outputs mkdir -p ~/website-cli-project/scripts cd ~/website-cli-project4. 安装部署与启动方式
4.1 安装项目依赖
项目是 npm 包方式分发。按照标题的 Show HN 说明，安装命令大致如下：
npm install -g aii-site-cli或者通过项目仓库手动克隆安装：
git clone <你的项目仓库地址> cd aii-site-cli npm install npm run build npm link注意，具体包名以项目实际发布名为准。如果你拿到的仓库地址不同，就把上面的aii-site-cli替换成实际包名。
4.2 验证 CLI 是否正确安装
aii --help如果安装成功，应该能看到类似下面的输出：
Usage: aii [options] [command] Commands: convert <url> 将网站转换为 CLI 定义 call <command> 调用已定义的 CLI 命令 list 列出当前已转换的网站 CLI serve 启动 MCP 服务 ...4.3 将网站转换为 CLI
这是整个项目最核心的一步。假设我们要把一个文档网站转成 CLI 接口：
aii convert https://example.com/docs --name docs转换过程会分析目标网站的结构，识别出搜索框、导航链接、正文区域等可交互元素，然后生成一份 CLI 定义文件。定义文件是 JSON 格式，里面描述了网站支持的命令和参数。
{ "site": "docs", "base_url": "https://example.com/docs", "commands": [ { "name": "search", "description": "搜索文档内容", "parameters": { "keyword": "string" }, "endpoint": "/search?q={keyword}" }, { "name": "get_page", "description": "获取指定文档页面内容", "parameters": { "path": "string" }, "endpoint": "/{path}" } ] }4.4 调用 CLI 命令
生成定义文件后，AI Agent 可以直接调用命令行：
aii call docs search --keyword "installation"返回结果就是精简后的文本内容，不再包含 HTML 标签、脚本、样式和导航噪音。
4.5 注册为 MCP 服务
项目还支持以 MCP（Model Context Protocol）方式集成到 Agent 生态。启动 MCP 服务后，Codex CLI、Claude Code 等工具会自动发现并提供给模型调用：
aii serve --port 8080这样配置的优势是，模型不需要在提示词里写复杂的工具定义，而是通过 MCP 协议自动发现可用命令。
5. 功能测试与效果验证
5.1 测试“网站转 CLI”是否成功
测试目的是确认转换结果真的能替代 HTML 抓取。
首先准备一个目标网站，建议选一个结构简单、无复杂 JavaScript 渲染的文档站。然后执行转换命令，并对比转换前后的上下文大小。
# 抓取原始 HTML 并统计 token 数 curl -s https://example.com/docs/installation | wc -c # 转换网站为 CLI aii convert https://example.com/docs --name docs # 调用 CLI 获取安装说明 aii call docs get_page --path "installation" > output.txt wc -c output.txt判断标准是：CLI 返回的内容体积明显小于原始 HTML，且关键信息完整。如果原始 HTML 返回 300KB，CLI 只返回 2KB 文本，说明转换成功。
5.2 搜索功能测试
测试目的：确认网站内的搜索功能可以通过 CLI 调用。
aii call docs search --keyword "configuration"预期输出是搜索结果列表，包含标题、链接和摘要。如果输出为空，先检查网站本身是否有搜索接口，再检查 CLI 定义文件中的搜索 endpoint 是否正确。
5.3 表单交互测试
部分网站需要提交表单才能获取数据，例如查询订单、筛选商品。命令行需要支持多参数：
aii call docs filter --category "guide" --sort "recent"这里要重点看 CLI 是否完整传递了全部参数。失败常见原因有三种：参数名不一致、网站接口改为 POST 请求但 CLI 定义还是 GET、网站有 CSRF Token 校验。
5.4 多轮对话场景测试
把 CLI 接入 Codex CLI 后，测试多轮对话效果：
codex然后在对话中直接问：
请帮我查看 docs 网站上的安装文档，并总结安装步骤。观察点：模型是否自动调用了aii call docs get_page --path "installation"，是否把返回文本用于回答。如果模型没有主动调用工具，需要检查 MCP 服务是否启动、CLI 名称是否正确注册。
5.5 tokens 消耗对比测试
这是项目最大的卖点，建议用控制变量法对比：
# 方式一：直接把 HTML 内容粘贴给模型 curl -s https://example.com/docs/installation > raw.html # 用 claude code 或 codex 读取文件再提问 # 方式二：让模型调用 CLI 获取结果 aii call docs get_page --path "installation"在 Codex 或 Claude Code 的会话中观察 token 使用量。如果项目标题数据准确，CLI 方式的 tokens 消耗会显著低于 HTML 方式。具体倍数取决于网站的 HTML 复杂度。
6. 接口 API 与批量任务
6.1 作为工具函数调用
除了 MCP 模式，这个 CLI 也可以直接封装成 Agent 的 Tool 函数。Python Agent 示例：
import subprocess import json def call_site_cli(site_name, command, **params): cmd = ["aii", "call", site_name, command] for key, value in params.items(): cmd.append(f"--{key}") cmd.append(str(value)) result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) if result.returncode != 0: raise RuntimeError(f"CLI 调用失败: {result.stderr}") return result.stdout然后在 Agent 的工具列表里注册这个函数即可。
6.2 MCP 服务接口
启动 MCP 服务后，可以通过 HTTP 请求调用：
curl -X POST http://127.0.0.1:8080/mcp \ -H "Content-Type: application/json" \ -d '{ "command": "docs.search", "arguments": {"keyword": "configuration"} }'这个接口的响应格式是标准 JSON，包含命令名、耗时、返回内容。
6.3 批量任务设计
批量采集场景下，可以写一个循环脚本：
import subprocess import time keywords = ["installation", "configuration", "api", "deployment", "troubleshooting"] for i, keyword in enumerate(keywords): print(f"正在处理第 {i+1}/{len(keywords)} 个关键词: {keyword}") cmd = ["aii", "call", "docs", "search", "--keyword", keyword] try: result = subprocess.run( cmd, capture_output=True, text=True, timeout=60 ) if result.returncode == 0: output_path = f"outputs/search_{keyword}.txt" with open(output_path, "w", encoding="utf-8") as f: f.write(result.stdout) print(f"写入 {output_path}") else: print(f"执行失败: {result.stderr}") except subprocess.TimeoutExpired: print(f"任务超时，跳过关键词: {keyword}") time.sleep(1)批量任务建议加入日志和重试机制：
import logging logging.basicConfig( filename="batch.log", level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s" ) def run_with_retry(cmd, max_retries=3): for attempt in range(max_retries): try: result = subprocess.run( cmd, capture_output=True, text=True, timeout=60 ) if result.returncode == 0: return result.stdout logging.warning(f"第 {attempt+1} 次尝试失败: {result.stderr}") except subprocess.TimeoutExpired: logging.warning(f"第 {attempt+1} 次尝试超时") time.sleep(5) return None6.4 失败重试建议
批量任务最常见的三种失败类型：
- 网络波动导致请求超时：设置合理的超时时间，重试间隔 5 到 10 秒。
- 网站接口限流：连续请求之间加 sleep，或者使用指数退避策略。
- CLI 定义文件失效：网站改版后 endpoint 可能失效，需要定期重跑
aii convert。
7. 资源占用与性能观察
7.1 显存和 CPU 占用
这个项目本身是轻量级 CLI 工具，不涉及模型推理，所以不需要独立的显存资源。它只负责发 HTTP 请求和解析文本。真正的资源消耗发生在调用 AI 模型时——Codex CLI 或 Claude Code 需要连接云端模型或本地模型。
7.2 tokens 消耗观察
这是最重要的观察维度。用 Codex CLI 测试时，每次提问后终端会显示本次会话累计使用的 tokens。通过对比同一问题在不同方式下的 tokens 消耗，就能验证项目价值。
观察建议：
- 连续跑 10 个不同问题，分别记录 HTML 方式和 CLI 方式的 tokens 消耗。
- 关注输入 tokens 的差异，CLI 方式主要省的是输入侧 tokens。
- 如果目标网站是多层导航、大量脚本的现代网站，压缩效果会更明显。
7.3 性能瓶颈排查
最常见的性能问题有两个：
- 网站响应慢：CLI 工具本身不缓存，每次调用都会实时请求目标网站。如果网站响应慢，CLI 调用自然慢。建议在 CLI 层增加缓存机制。
- 并发请求被限流：批量任务并发过高时，网站可能返回 429 或验证码。建议控制并发数，必要时用代理池。
7.4 降低 tokens 的技巧
- 优先让 CLI 返回 Markdown 格式，而不是纯文本，结构更清晰。
- 在 CLI 定义文件中裁剪不必要的字段，比如评论数、点赞数、相关文章链接。
- 对于长文档，可以拆分命令行，先获取目录，再按章节获取正文。
8. 常见问题与排查方法
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
aii命令不存在 | npm 全局安装失败或 PATH 未配置 | 检查npm ls -g和echo $PATH | 重新npm install -g或配置 PATH |
| 转换网站时报错 | 目标网站有反爬限制或需要登录 | 查看错误日志中的 HTTP 状态码 | 确认访问权限，或配置 Cookie |
| CLI 调用返回内容为空 | 网站接口路径变化或参数不对 | 用浏览器开发者工具查看真实请求 | 重新运行aii convert更新定义 |
| 搜索功能返回结果不完整 | 网站搜索是 JS 渲染，非原生接口 | 打开浏览器无头模式观察 | 改用aii convert --browser模式 |
| MCP 服务启动后无法被发现 | 端口被占用或 Agent 配置错误 | 检查端口lsof -i :8080 | 更换端口或检查 Agent 的 MCP 配置 |
| 批量任务部分失败 | 网站限流或网络超时 | 查看 batch.log 的错误记录 | 增加重试机制和请求间隔 |
| tokens 节省不明显 | 网站本身内容很少 | 对比原始 HTML 和 CLI 输出的大小 | 换一个内容更丰富的网站测试 |
| 中文内容乱码 | 编码格式问题 | 检查 CLI 输出文件的编码 | 统一用 UTF-8 编码处理 |
8.1 依赖安装失败的排查步骤
# 清理 npm 缓存 npm cache clean --force # 删除 node_modules 重新安装 rm -rf node_modules package-lock.json npm install # 如果仍然失败，检查网络代理设置 npm config get proxy npm config get https-proxy8.2 模型不调用 CLI 工具的排查思路
- 检查 MCP 服务是否正常运行。
- 确认工具描述是否清晰，模型需要知道“调用这个命令可以获取网站信息”。
- 在提示词中明确建议模型优先使用 CLI 工具。
- 观察模型日志，看它是否在思考过程中提到了工具调用。
9. 最佳实践与使用建议
9.1 先小规模验证
第一次部署时，不要直接给 CLI 接几十个命令。先用一个简单网站跑通全流程：转换、调用、接入 Agent、对比 tokens。确定稳定后，再逐步增加网站和命令。
9.2 维护一份 CLI 定义清单
项目运行一段时间后，命令会越来越多。建议用 Markdown 文件维护一份所有已转换网站的清单，记录每个网站的名称、用途、最后一次转换时间、注意事项。
9.3 分类管理输出结果
outputs/ docs/ search_configuration.txt get_page_installation.txt news/ ...每个网站独立目录，避免文件混乱。
9.4 接口服务安全建议
如果 MCP 服务监听在非本机地址，必须做好访问控制：
- 只在
127.0.0.1绑定。 - 如果需要在局域网访问，加一层 API Token 鉴权。
- 不要让 CLI 暴露在公网，尤其是涉及登录态 Cookie 的网站。
9.5 合规使用提醒
再次强调：把网站转成 CLI 不影响你对它的使用权边界。涉及版权内容、个人隐私信息、登录后才能访问的数据，必须在合法授权范围内使用。批量抓取行为还要遵守目标网站的 robots 协议和服务条款。用于 AI 模型训练的前，先确认网站内容的授权许可是否允许。
10. 总结与下一步
这个项目最大的价值不是“爬虫便捷化”，而是把 AI Agent 的网页交互模式从“理解 HTML”升级为“调用接口”。对于那些需要频繁让模型访问网页信息的工作流，它确实能显著降低 tokens 消耗，同时让模型的行为更容易预期。
建议按这个顺序验证：先跑通一个简单网站的 CLI 转换，然后对比一次 tokens 消耗，最后把它挂到 Codex CLI 里测试真实问答效果。最容易踩的坑是网站本身有反爬或 JS 渲染，测试时优先选轻量文档站，成功后再挑战复杂网站。
后续可以尝试的方向：把 CLI 定义文件接入自己的 Agent 框架、用脚本批量采集并入库 RAG、在团队内部共享一份网站 CLI 库。这个项目思路也很适合做二次开发，比如给 CLI 定义加缓存、加多站点聚合、加深层链接挖掘。建议收藏备用，等你的 Agent 工作流遇到 tokens 成本问题时，回来把这一步加上。
