★ FEATURED ARTICLE 1. 先聊清楚CLI 爬虫智能体到底解决什么问题我先把结论放前面所谓 CLI 爬虫智能体本质就是把「抓数据」和「让模型读数据写结论」这两件事塞进一条终端命令里。你在命令行敲一行它去抓公开页面、整理成结构化表格再调用大模型生成一份能直接看的分析报告。适合谁适合经常要做竞品调研、选品分析、内容选题但又不想每次都打开浏览器手动复制粘贴的人。也适合想练手 Agent 工程化的 Python 开发者因为 CLI 形态最轻不用前后端分离不用部署服务跑通就是跑通。我这次的目标场景很具体抓取公开的商品信息商品链接、店铺链接、关键词三类输入落成 CSV然后让 DeepSeek 读这份 CSV 输出 Markdown 报告。技术栈是 Python requests OpenAI 兼容 SDK 一个负责网页解锁的 scraper API。整个链路里最容易翻车的不是 Python 代码而是两处外部调用一是抓取接口的鉴权与快照下载二是大模型接口的 Base URL 和模型名。所以我把这两处统一收敛到 TaoToken 的 Key/API 通道上环境变量只维护一套换模型只改一个字符串。先说说为什么值得做成 CLI 而不是脚本堆砌。脚本堆砌的问题是参数靠改代码跑一次改一次久了就没人维护。CLI 的好处是输入输出契约清晰-i给输入-o给输出--analyze决定要不要调模型。这样你可以把它挂到定时任务里也可以被别的程序调用。我实测下来一个能跑通的 CLI 智能体代码量大概三百行出头分三个模块抓取请求、快照下载、模型分析。下面按这个结构拆。还有一个认知要先建立爬虫智能体不是「绕过限制」的工具它只是把公开数据的采集流程自动化。你采集的量要克制字段要克制频率要克制。我这次只跑极少量公开数据做验证够用就行。真正有价值的部分是后面的分析环节——数据抓回来是一堆字段模型把它变成结论这才是省时间的地方。2. 前置准备TaoToken 统一通道与依赖安装这一章把「钥匙」配好。你需要两样东西一个能同时调抓取接口和模型接口的 API Key 通道以及本地 Python 环境。我选择把模型调用统一走 TaoToken原因是它提供 OpenAI 兼容的接口形态base_url指向https://taotoken.net/api模型名按需切换代码里不用为不同厂商写分支。抓取接口那边是独立的服务Key 单独申请但两者在代码里都通过环境变量注入互不污染。先看依赖。建议用虚拟环境避免和系统包打架python3 -m venv venv source venv/bin/activate pip install requests openai python-dotenvrequests负责抓取接口的提交与快照下载openai负责模型调用DeepSeek 走 OpenAI 兼容协议python-dotenv用来读.env。版本不用卡太死openai1.0即可因为新版 SDK 的OpenAI(base_url..., api_key...)写法是稳定的。接着建.env文件放在项目根目录# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELdeepseek-chat SCRAPER_API_KEY你的抓取服务密钥 SCRAPER_DATASET_ID你的数据集ID这里解释三个关键点。第一TAOTOKEN_BASE_URL结尾不要带/v1SDK 会自己拼路径带了容易 404。第二TAOTOKEN_MODEL填你账号下可用的模型 IDDeepSeek 系列一般用deepseek-chat这类标识具体以控制台模型列表为准别凭记忆写。第三抓取服务的DATASET_ID决定你调哪个采集器商品链接、店铺链接、关键词往往对应不同数据集这个 ID 在服务后台的采集器详情页能看到。Key 的获取路径我建议直接走控制台别在文档里翻半天。模型侧的 Key 在 TaoToken 控制台的 API Keys 页面创建创建后只显示一次记得当场存进密码管理器。抓取侧的 Key 在对应服务后台的账户设置里新建。两边都拿到后先做一次最小连通性验证别等写完三百行才发现 Key 是错的curl -s https://taotoken.net/api/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 300能返回模型列表 JSON 就说明通道通了。如果返回 401先检查 Key 有没有多余空格、有没有把Bearer拼错。这一步花两分钟能省后面半小时排障。注意.env一定要进.gitignore。我见过太多人把 Key 提交到公开仓库第二天收到账单提醒。密钥管理不是洁癖是基本操作。3. 可复制配置三个模块与 CLI 参数骨架这一章给能直接落地的代码结构。项目目录建议这样组织模块职责单一排障时一眼能定位cli-scraper-agent/ ├── .env ├── agent.py ├── scraper_client.py ├── analyzer.py └── input_sample.csvscraper_client.py负责两件事提交采集任务拿快照 ID用快照 ID 下载结果。analyzer.py负责读 CSV、拼提示词、调模型。agent.py是 CLI 入口用argparse解析参数。先看抓取客户端的核心写法# scraper_client.py import os, time, requests from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(SCRAPER_API_KEY) DATASET_ID os.getenv(SCRAPER_DATASET_ID) def trigger_collect(urls: list[str]) - str: resp requests.post( https://api.brightdata.com/datasets/v3/trigger, params{dataset_id: DATASET_ID, include_errors: true}, headers{Authorization: fBearer {API_KEY}, Content-Type: application/json}, json[{url: u} for u in urls], timeout60, ) resp.raise_for_status() return resp.json()[snapshot_id] def download_snapshot(snapshot_id: str, out_path: str) - str: for _ in range(30): r requests.get( fhttps://api.brightdata.com/datasets/v3/snapshot/{snapshot_id}, params{format: csv}, headers{Authorization: fBearer {API_KEY}}, timeout120, ) if r.status_code 200 and r.text.strip(): with open(out_path, w, encodingutf-8) as f: f.write(r.text) return out_path time.sleep(10) raise TimeoutError(快照下载超时检查数据集ID与任务状态)这段代码有两个细节值得说。trigger的请求体是数组每个元素一个url字段批量提交就多塞几个对象别拼成字符串。download_snapshot加了轮询因为采集是异步的提交完立刻下载大概率拿到空响应等十秒再试是常态。轮询上限三十次、每次十秒够大多数小批量任务跑完。再看模型分析模块这里就是 TaoToken 通道发挥作用的地方# analyzer.py import os, csv from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) PROMPT 你是电商选品分析师。下面是商品数据CSV的前若干行 请输出Markdown报告包含数据概览、品类分布、价格区间、 高销量商品特征、选品建议。不要编造数据缺失字段标注为未知。 def analyze_csv(csv_path: str, out_md: str) - str: with open(csv_path, encodingutf-8) as f: rows list(csv.reader(f))[:60] table \n.join(,.join(r) for r in rows) resp client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL), messages[ {role: system, content: PROMPT}, {role: user, content: table}, ], temperature0.3, ) report resp.choices[0].message.content with open(out_md, w, encodingutf-8) as f: f.write(report) return out_mdbase_url指向 TaoToken 的 API 地址model从环境变量读这样你换模型不用改代码。temperature0.3是我试出来的平衡点太低报告干巴太高容易编数字。截取前六十行是为了控制上下文长度商品字段多的时候整份 CSV 塞进去会超限先给模型一个样本让它抓规律够用。最后是 CLI 入口参数设计要克制# agent.py import argparse, csv from scraper_client import trigger_collect, download_snapshot from analyzer import analyze_csv def main(): p argparse.ArgumentParser(descriptionCLI 爬虫智能体) p.add_argument(-i, --input, requiredTrue, help输入CSV含url列) p.add_argument(-o, --output, defaultoutput.csv) p.add_argument(--analyze, actionstore_true, help生成分析报告) args p.parse_args() with open(args.input, encodingutf-8) as f: urls [row[url] for row in csv.DictReader(f) if row.get(url)] sid trigger_collect(urls) download_snapshot(sid, args.output) print(f采集完成: {args.output}) if args.analyze: md analyze_csv(args.output, args.output.replace(.csv, _report.md)) print(f报告已生成: {md}) if __name__ __main__: main()输入 CSV 的格式就两列起步url列必填其他列随意url,note https://example.com/item/1001,竞品A https://example.com/item/1002,竞品B到这里配置骨架就齐了。三个文件加起来不到一百五十行但契约完整输入是 CSV输出是 CSV 加可选 Markdown。你可以先把trigger_collect里的接口地址和参数按你实际用的采集服务文档对齐字段名以文档为准别照抄我的示例就上线。4. 跑一次验证从命令行到报告落盘配置写完接下来是验证。验证要分层别一上来就跑全链路出错你不知道是哪一层。我的顺序是先验模型通道再验抓取通道最后跑端到端。第一层模型通道。单独跑一个最小脚本确认base_url和模型名都对python3 -c from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() c OpenAI(api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL)) r c.chat.completions.create(modelos.getenv(TAOTOKEN_MODEL), messages[{role:user,content:回复两个字通了}]) print(r.choices[0].message.content) 终端打印「通了」说明 Key、Base URL、模型 ID 三件套正确。这一步失败后面全白搭所以必须先过。第二层抓取通道。拿一条公开链接试提交观察返回的snapshot_id是不是一串正常字符python3 -c from scraper_client import trigger_collect print(trigger_collect([https://example.com/item/1001])) 拿到 ID 后手动下载一次确认 CSV 有表头有数据python3 -c from scraper_client import download_snapshot print(download_snapshot(你的快照ID, test.csv)) head -n 3 test.csv如果test.csv只有表头没有数据行多半是采集还在跑或者目标页面结构变了导致字段没匹配上。前者等一会儿重试后者要去采集服务后台看任务日志。第三层端到端。准备input_sample.csv跑完整命令python3 agent.py -i input_sample.csv -o output.csv --analyze预期输出三行采集完成、报告已生成以及两个文件路径。打开output.csv应该能看到商品字段打开output_report.md应该是一份带小标题的 Markdown。我实测下来三条链接的小批量任务从提交到报告落盘大概一两分钟主要耗时在采集轮询。验证通过后建议做一次「换模型不改代码」的回归把.env里的TAOTOKEN_MODEL换成另一个可用模型重跑--analyze确认报告照样生成。这一步能证明你的代码没有硬编码模型名后面想对比不同模型的报告质量就很方便。这也是统一通道的实际价值——切换成本低到只改一行配置。提示验证阶段把采集量压到最小三条五条足够。等链路稳定了再放量别一上来就提交几百条出问题不好定位也不礼貌。5. 常见报错排查401、快照空、choices 缺失这一章按真实报错来。我把踩过的和读者反馈最多的几类整理成对照表遇到问题先查表别急着改代码。报错现象大概率原因处理动作401 UnauthorizedKey 错误、含空格、或用了抓取 Key 调模型分别打印两个 Key 的前后各四位核对确认没串用local proxy failed/ 连接超时本机网络策略拦截或 Base URL 写错检查TAOTOKEN_BASE_URL是否为https://taotoken.net/api去掉多余路径reading choices/NoneType响应体不是预期结构通常是鉴权失败返回了错误 JSON打印resp原始文本先看error字段再改代码快照下载为空采集未完成就下载或数据集 ID 不匹配加长轮询间隔核对DATASET_ID与输入类型是否对应OAuth相关报错误用了需要 OAuth 流程的端点CLI 场景用 API Key 即可别走授权码流程CSV 中文乱码写入未指定utf-8所有open加encodingutf-8重点说三个。第一个是 401。这个报错最迷惑的地方在于它可能是模型侧也可能是抓取侧。我的做法是在两个客户端初始化后各打一行日志只打 Key 的后四位确认哪个 Key 被用在了哪个请求上。串用是高频错误——把SCRAPER_API_KEY填进了TAOTOKEN_API_KEY或者反过来。第二个是reading choices这类报错。它通常不是 SDK 的 bug而是服务端返回了一个错误对象SDK 尝试按成功结构解析就炸了。排查方法很简单在create调用外面包一层 try异常时打印原始响应try: resp client.chat.completions.create(...) except Exception as e: print(原始错误:, e) raise看到error.message里写的是invalid api key还是model not found方向立刻就清楚了。模型名写错是很常见的尤其是把展示名当成了 API 模型 ID。第三个是快照为空。采集是异步任务提交成功不等于数据就绪。我的轮询逻辑里判断了r.text.strip()空字符串就继续等。但还有一种情况是数据集 ID 和输入类型不匹配——你用商品链接的数据集去提交关键词任务可能成功但结果为空。这时候去采集服务后台看任务详情它会告诉你匹配到几条、失败几条。还有一个隐蔽的坑CSV 里的 URL 带了多余空格或换行。csv.DictReader读出来是原样字符串requests提交时不会帮你 trim。建议在读取时统一strip()urls [row[url].strip() for row in csv.DictReader(f) if row.get(url, ).strip()]这类小问题不报错但会让采集结果莫名其妙地少几条排查起来很费时间。6. 继续往下走把智能体用顺手的几个建议链路跑通只是起点。真正让它变成日常工具还有几件事值得做。第一把输入输出契约固化。input_sample.csv的列名固定为url加备注列输出 CSV 的字段以采集服务返回为准不要在下游代码里假设字段一定存在。分析模块读 CSV 时用csv.reader而不是按列名取值就是为了容忍字段变化。字段缺失时让模型标注「未知」而不是让它猜。第二给分析提示词留可配置入口。现在提示词硬编码在analyzer.py里改一次要动代码。更顺手的做法是加一个--prompt-file参数把提示词放外部文件不同任务用不同模板。比如选品分析一套、评论情感一套、竞品对比一套切换只换文件。第三控制成本。模型调用按 token 计费商品字段多的时候一份 CSV 很容易上万 token。我的做法是只取前若干行做样本分析报告里注明「基于样本」。如果你确实需要全量分析就分批调用再合并别一次性塞进去。抓取侧同理批量提交前先估算条数小步快跑。第四把 CLI 挂进工作流。跑通之后你可以用 cron 定时执行或者用 shell 脚本串起来先采集再分析最后把 Markdown 推到你的笔记目录。CLI 的价值就在这里——它是可组合的不像 GUI 工具那样只能人肉点。如果你想把模型调用这部分再简化可以直接用 TaoToken 的模型对话页面先手动试提示词确认输出结构满意了再写进代码省得反复改代码调试。长期做编码和 Agent 类任务的话Coding Plan 那条线也值得看一眼按需选择就行。接入文档里有各语言的调用示例遇到 Base URL 或参数疑问对照文档比猜快得多。最后说个真实体会这类小工具的价值不在代码多漂亮而在它替你省下的重复劳动。我现在的习惯是凡是「打开网页、复制字段、粘进表格、再让模型总结」这种四步以上的重复动作就考虑做成一条命令。CLI 爬虫智能体只是其中一个例子同样的骨架换成别的数据源、别的分析目标改改参数就能复用。先把这一条跑顺后面的事自然就快了。
阅读完成 · 觉得有帮助？
