把网站改造成CLI接口：AI Agent节省142倍tokens的实践

这次我们来看一个很有意思的开源项目把任意网站改造成 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 调用效率提升相比直接传 HTMLtokens 消耗大幅降低标题数据为 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 直接解析网页现在可以先把目标网站抽象成 CLIAgent 通过命令行完成操作。第三类是 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 CLInpm 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 服务项目还支持以 MCPModel 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 返回 300KBCLI 只返回 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_outputTrue, textTrue, timeout30) if result.returncode ! 0: raise RuntimeError(fCLI 调用失败: {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正在处理第 {i1}/{len(keywords)} 个关键词: {keyword}) cmd [aii, call, docs, search, --keyword, keyword] try: result subprocess.run( cmd, capture_outputTrue, textTrue, timeout60 ) if result.returncode 0: output_path foutputs/search_{keyword}.txt with open(output_path, w, encodingutf-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( filenamebatch.log, levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s ) def run_with_retry(cmd, max_retries3): for attempt in range(max_retries): try: result subprocess.run( cmd, capture_outputTrue, textTrue, timeout60 ) if result.returncode 0: return result.stdout logging.warning(f第 {attempt1} 次尝试失败: {result.stderr}) except subprocess.TimeoutExpired: logging.warning(f第 {attempt1} 次尝试超时) 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 状态码确认访问权限或配置 CookieCLI 调用返回内容为空网站接口路径变化或参数不对用浏览器开发者工具查看真实请求重新运行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 成本问题时回来把这一步加上。