用iFlow CLI自定义Command实现网页抓取与自动翻译

最近用 iFlow CLI 折腾了一个特别顺手的小工具一条命令抓取网页文章正文再自动翻译成指定语言。这个需求我其实惦记很久了——每天要读不少英文技术博客浏览器自带翻译体验一般把全文复制到对话窗口又总是被上下文长度卡住。最初我只是想简化这个流程等真正理解了 iFlow CLI 的自定义 Command 机制之后才发现它非常适合固化这种“多步骤、重复、有固定套路”的任务于是把整套流程沉淀成了可以直接调用的 Command。这篇文章完整记录了我的实现过程从 Command 的配置结构、提示词设计、参数体系到调试过程中踩过的几个坑都会逐一展开。如果你也在用 iFlow CLI或者单纯对“把多步骤任务固化成一条命令”这个思路感兴趣可以直接照着抄。1. 整体思路为什么要把下载和翻译固化成 Command1.1 一个真实的工作场景说个实际场景。我在做技术调研的时候经常需要同时阅读多个来源的文章官方的英文文档、社区里的英文帖子、偶尔还有日文或韩文的技术博客。过去我的流程是这样的打开网页全选复制粘贴到文本编辑器里简单清理格式再复制到对话工具里告诉它“请翻译成中文”。一篇文章走完这套流程至少要五六分钟而且每换一篇文章同样的动作就要重复一遍。一开始我试过用浏览器插件但插件有个问题它的翻译结果和上下文是割裂的。我需要同时保留原文和译文方便对照检查术语翻译得是不是准确。浏览器翻译通常只能二选一要么纯译文要么纯原文对照比较麻烦。后来我想能不能让大模型直接来完成“下载 提取 翻译”这条链路答案是可以但前提是要把任务流程说清楚把参数留好不能每次都从头打字。于是就有了用 iFlow CLI 创建自定义 Command 的想法。1.2 Command 的本质固化流程参数化输入iFlow CLI 里的 Command本质上是把一段精心设计的提示词、一组可替换的参数、以及模型的运行参数模型版本、温度、输出长度上限等打包成一个可重复执行的“命令行函数”。它和我们平时写脚本有点像但区别在于脚本处理的是确定性的逻辑而 Command 处理的是需要模型理解和生成的内容。以前我在终端里调用大模型都是“临时起意”式的想起来了就打一段话模型给个回复。这种方式适合闲聊和一次性提问但遇到“抓网页 翻译”这种需要稳定输出的任务就很吃亏。我可能会在每次提问时把要求描述得不太一样模型的行为也随之抖动有时候它直接翻译有时候它先总结一段再翻译有时候它把链接和代码块弄丢。Command 就是用来消灭这种不确定性的——提示词模板固定下来每次替换的只是 URL 和语言参数输出结构就能保持在同一个框架内。1.3 为什么用 iFlow CLI 而不是自己写脚本可能有人会问这个需求用 Python 写个爬虫加翻译脚本不行吗当然行我自己也写过一个雏形但最后放弃了原因有三个。第一网页正文提取这件事看着简单做起来很烦。样式的变化太多了有的页面正文在article里有的在div.content里有的要顺着 JSON 数据源去挖。正则写了几十条还是会有漏网之鱼。而大模型天生擅长做信息判别给它一段 HTML它能准确找出正文区域并剔除导航、页脚、广告。第二翻译质量取决于语义理解。脚本调用翻译 API得到的是机械的直译。大模型翻译能结合上下文保留术语一致性代码块和链接格式也不会弄丢。第三iFlow CLI 已经把“调用模型、管理密钥、输出格式化”这些管道工程做完了。我只需要专注写提示词和设计参数不需要自己处理 HTTP 请求、token 计数、错误重试这些琐碎的事。所以最终方案是用 iFlow CLI 的 Command 配置把提示词模板固化成两个可复用的命令——一个负责提取正文一个负责翻译。然后再用一个组合命令把两者串起来实现“输入 URL输出译文”。2. 环境准备与 Command 机制入门2.1 安装与初始化先交代一下我的环境。我用的是 macOS 终端iFlow CLI 通过 Homebrew 安装。如果你的环境不太一样也没关系CLI 的安装方式大同小异。brew install iflow-cli iflow --version安装完成之后第一次使用需要初始化认证。iFlow 开放平台的后台可以创建 API Key在终端里把它配置到 CLI 的配置文件里。这一步各家 CLI 的做法非常相似目的都是让后续命令免去反复输入密钥的麻烦。iflow auth login # 按提示输入 API Key iflow auth status如果你更愿意把密钥放在环境变量里也可以这么做我团队里有同事习惯用.env文件管理export IFLOW_API_KEY你自己的key配置好之后验证一下通路是否正常iflow run 你好请回复OK能正常返回 OK就说明 CLI 已经能够调用模型。后面所有 Command 的执行都建立在通路正常这个前提之上。2.2 Command 配置文件的核心字段我选的配置文件格式是 YAML。虽然 iFlow CLI 也支持在命令行里直接传入--prompt但当提示词超过几行之后放在配置文件里明显更清晰。一个最小的 Command 配置文件通常包含这样几个字段name: webpilot description: 抓取网页正文并翻译为目标语言 model: iflow-pro temperature: 0.3 max_tokens: 4096 inputs: - name: url type: string required: true description: 目标网页URL - name: lang type: string required: false default: zh-CN description: 翻译目标语言 prompt: | ...提示词模板...我想单独解释一下temperature这个参数。翻译和抓取任务希望输出稳定不需要创意所以温度要调低。我实测下来0.3是一个比较舒服的值既不会像0那样偶尔出现机械重复也不会因为温度太高而出现凭空发挥。2.3 参数系统的设计原则Command 参数不是随便列的设计参数时一定要想清楚一个核心问题哪些东西需要用户每次输入哪些东西应该固化在提示词里我的原则是任务对象URL、语言做成参数行为偏好输出格式、术语要求固化在提示词里。URL 是必须做成参数的因为每次处理的目标不同。语言也做成参数但给一个默认值zh-CN这样大多数情况下用户可以不填。而“输出要保留代码块和链接”“标题用加粗展示”这些要求就不适合做成参数否则用户每次都要重复输入。iFlow CLI 的参数类型支持字符串、枚举、布尔值等基础类型。其中枚举类型特别适合“模式切换”。我这套工具里定义了三种翻译模式就是用枚举实现的- name: mode type: enum default: translate options: - translate - summary - bilingual这样用户可以通过--mode summary直接切换行为非常直观不用在提示词里写复杂的条件判断。2.4 理解 Command 的变量注入机制Command 里参数注入到提示词的方式一般有两种一种是{{url}}这种占位符模板另一种是把参数作为独立字段传给模型。我习惯用占位符模板因为它可以让提示词读起来像一段完整的指令模型的遵循度会更高。举个例子在提示词里写你现在要做的事情是抓取用户提供的网页链接 {{url}} 中的正文内容并翻译成 {{lang}}。模型收到的就是完整的、已经把具体 URL 和语言填进去的句子。这比“用户消息里包含了URL”这种割裂的方式要自然得多。3. 核心实操网页文章正文提取 Command3.1 创建下载提取命令的完整配置我管它叫webfetch它的职责只有一个把 URL 里的网页正文提取出来转成干净的 Markdown。这个命令是翻译的前置步骤但也可以单独使用。name: webfetch description: 抓取网页正文并输出为干净的Markdown model: iflow-pro temperature: 0.2 max_tokens: 8192 inputs: - name: url type: string required: true description: 目标网页URL - name: min_chars type: integer required: false default: 200 description: 正文段落的最短字符阈值低于此值的段落将被视为噪声 prompt: | 你是一个网页正文提取引擎。用户会给你一串从浏览器或爬虫获取的网页HTML/文本内容。 你的任务是提取文章正文忽略导航栏、侧边栏、页脚、广告、cookie提示、评论区、相关推荐等噪声内容。 要求 1. 只输出正文部分不要输出任何解释性文字。 2. 输出格式为Markdown保留原文的标题层级结构。 3. 保留原文中的代码块、表格、图片链接和超链接。 4. 如果正文包含多个小节用二级标题##分隔。 5. 如果一个段落少于 {{min_chars}} 个字符且内容明显是广告或导航请删除它。这里我想强调一下min_chars参数的用法。短段落判噪是大模型提取正文时最容易出错的地方之一它要么过度删除把正文里的短句也干掉了要么保留太多把导航里的链接列表都当成了内容。给一个“最短字符阈值”参数相当于给了一个客观的过滤器实测下来效果好很多。3.2 写提取提示词的三个关键技巧第一要让模型明确“输入的是什么形态”。用户从不同网页复制来的内容格式差异巨大有的带着 HTML 标签有的是纯文本有的含有大量换行。我在提示词开头就说明“你会收到网页 HTML/文本内容”并告诉模型“内容的原始格式可能凌乱这不是你需要修复的重点重点是提取正文结构”。第二要给正面目标也要给反面清单。只说“提取正文”不够模型对“正文”的理解可能跟我不一样。我特意列了反面清单忽略导航栏、侧边栏、页脚、广告、cookie 提示、评论区、相关推荐。这样模型就不会把“热门文章”列表误当成正文。第三要规定输出中“必须保留什么”。翻译和后续处理最怕代码块、表格、链接丢失。我明确要求保留这四类元素并且测试后发现模型在遵循这条指令上做得不错特别是代码块基本能原样保留。3.3 处理编码问题和异常页面网页抓取遇到过几次编码问题。有些老网页是 GBK 编码直接按 UTF-8 解析会出现乱码。如果你是在 CLI 里直接让模型处理 HTML编码问题通常已经被工具链处理过了但如果你是自己用脚本下载 HTML 再传给模型就要格外注意。我的做法是先用脚本探测字符集再统一转成 UTF-8。这个逻辑可以放在一个简单的 Python 预处理脚本里import requests import chardet url https://目标网页.com/article resp requests.get(url, timeout15) resp.encoding chardet.detect(resp.content)[encoding] html resp.text print(html)如果页面内容太长超过了模型的上下文窗口还要做截断处理。我的经验是保留前三段和每段首句同时告诉模型“内容较长如果超过处理范围请提取你看到的核心部分并做概括不要强行输出”。3.4 遇到的第一个坑把整个 HTML 都给模型我第一次配置webfetch的时候为了省事直接把浏览器“另存为”出来的整个 HTML 文件内容塞给了模型。结果上下文立刻爆掉而且模型被大量script和style标签带偏输出了一堆莫名其妙的标签残留。后来我调整了策略在调用 Command 之前先用一个极简的脚本把script、style、nav、footer这些明显不是正文的标签剥掉再进行正文提取。这一步叫做“粗清洗”相当于大战前的炮火准备可以大幅减轻模型的负担。粗清洗之后HTML 的体积通常能减少 70% 以上。3.5 实测运行 webfetch配置写好后执行方式很简单iflow run webfetch --url https://example.com/tech-article --min_chars 200输出会直接打印在终端里。我习惯加一个重定向把结果保存到本地文件为下一步翻译做准备iflow run webfetch --url https://example.com/tech-article article.md这种“Command 重定向”的组合让我感觉 iFlow CLI 就像一个大模型管道工具每个 Command 可以像 Unix 命令一样参与组合这是它让我觉得顺手的重要原因。4. 进阶实现翻译引擎与组合命令4.1 三种翻译模式设计正文提取搞定之后重头戏来了翻译。我定义了一个webpilot命令把翻译工作分成三种模式translate纯翻译原文和译文一一对应summary摘要模式输出这篇文章的核心观点bilingual双语对照模式逐段对照展示。name: webpilot description: 翻译网页文章正文 model: iflow-pro temperature: 0.3 max_tokens: 8192 inputs: - name: url type: string required: true description: 目标网页URL - name: lang type: string required: false default: zh-CN description: 目标语言 - name: mode type: enum default: translate options: [translate, summary, bilingual] prompt: | 你会收到一篇从网页提取出来的Markdown格式文章。请根据 {{mode}} 模式处理 如果modetranslate 将全文翻译成{{lang}}要求 - 术语保持一致原文术语首次出现时在括号内标注英文原词 - 代码块、表格、链接URL原样保留不翻译 - 标题层级结构保持不变 如果modesummary 输出这篇文章的核心观点分条列出每条不超过50字。 如果modebilingual 分段输出原文和译文格式为原文段落后跟空行再跟译文段落。 如果原文是{{lang}}语言或与目标语言相同请直接输出原文不做翻译。为了给webpilot提供输入实际操作中可以把文件内容通过管道传入cat article.md | iflow run webpilot --lang zh-CN --mode translate不过纯管道有个问题url参数是必填的我在这个 Command 的设计里还需要把 URL 传给模型让模型知道文章出处这样术语提取会更有上下文感。所以更合理的做法是把正文提取和翻译放在同一个配置里让模型端到端处理。4.2 端到端的组合 Command一箭双雕组合的思路很简单webpilot接收 URL在提示词中要求模型先以“网页抓取器”角色提取正文再以“翻译器”角色进行翻译。这样一个命令干两件事省去中间环节。name: webpilot description: 一条命令下载并翻译网页文章 model: iflow-pro temperature: 0.3 max_tokens: 8192 inputs: - name: url type: string required: true - name: lang type: string required: false default: zh-CN - name: mode type: enum default: translate options: [translate, summary, bilingual] prompt: | 第一轮任务抓取正文 用户会提供网页URL。请先获取该URL对应的HTML内容提取正文剔除导航、广告、页脚、 评论等噪声并转换为一篇干净的Markdown文章。 第二轮任务翻译处理 提取完成后根据 {{mode}} 模式对Markdown文章执行指定操作 - translate全文翻译成 {{lang}} - summary输出核心观点分条摘要 - bilingual原文译文分段对照 输出直接以翻译/摘要/对照结果开始不要输出以下是翻译结果之类的引导语。执行体验非常顺手iflow run webpilot --url https://example.com/tech-article --lang zh-CN --mode bilingual第一次跑通的时候我真切感受到“一条命令取代一套流程”带来的快乐。按下回车等个十几秒一篇双语对照的网页文章就出现在终端里了。4.3 模型选择和参数调优的心得关于模型选择我对比过默认模型和经过指令优化的模型之间的差异。在正文提取和翻译这一类任务上经过指令微调的大模型明显更“听话”对格式要求的遵循度更高几乎不会出现自说自话的情况。所以model字段我固定选择iflow-pro指令模型。max_tokens我设成 8192。网页文章翻译成中文后如果原文很长输出可能会超过单次生成的上限。遇到这种情况我在提示词里做了兜底设计如果文章过长优先翻译全文的前 80%并在结尾标注“[内容过长已截断请使用分段模式]”。4.4 一个容易踩坑的细节目标语言检测如果你从来没有遇到“把中文网页翻译成中文”这种尴尬情况说明你运气好。我遇到过几次——用webpilot处理一个中文网页分明指定了--lang en结果模型还是一副“原文就是英文”的错觉输出仍然带着中文。后来我在提示词里加了一个前置判断在翻译之前先判断原文的语言。如果原文已经是{{lang}}语言则直接输出原文 不要再进行翻译操作。把这句话加进去之后这个“自转译”的毛病就再没犯过。这类细微的提示词修正虽然看起来不起眼但实际使用体验的提升是很明显的。5. 实战问题排查那些年我踩过的坑5.1 问题速查表我把使用过程中遇到的典型问题整理了一下方便你遇到同类问题时快速定位。现象可能原因解决方案Command 报 URL 访问超时目标网站响应慢或需要代理增大请求超时时间先本地下载 HTML 再喂给模型输出中残留大量 HTML 标签缺少粗清洗步骤模型被script带偏预处理时剥掉script、style、nav标签正文提取把链接列表当正文噪声清单写得不全在提示词中补充“相关推荐”“热门文章”等词语翻译丢代码块提示词未明确保留代码块加一句“代码块原样保留不翻译”翻译结果出现重复段落temperature 过高把 temperature 降到 0.3 以下长文章输出被截断单次生成 token 超限用--max_tokens调大上限或分段落处理中文网页被错误翻译缺少语言前置判断在提示词中加入“原文已是目标语言则直接输出”终端输出乱码字符编码不一致确保 HTML 输入统一转为 UTF-85.2 记忆最深刻的一次调试最让我抓狂的问题是webfetch命令在处理某个网站时输出内容永远只有标题和第一段后面的正文全都不见了。排查了很久最后发现原因有两个叠加第一那个网站的正文长度极长单次输入已经把上下文占了大半第二我的提示词里有一条“保持简洁避免重复”模型在上下文紧张时把“简洁”理解成了“截断到摘要长度”。这一度让我意识到提示词里的每一个模糊形容词都可能被模型以意想不到的方式执行。“保持简洁”这种说法太主观了不同模型对简洁的理解差异很大。后来我把这句删掉换成“输出全文无论内容多长都要完整输出所有段落”问题立刻解决。5.3 日志和调试的实用技巧在我这版 CLI 上有几个调试技巧帮了大忙分享给你。首先是用--verbose或-v参数查看详细的请求日志能直观看到模型实际收到的提示词长什么样。很多问题当天就能定位比如变量是不是正确替换进去了提示词里的{{}}占位符有没有残留都能看清楚。其次是善用--max_tokens来控制成本。调试阶段没有必要每次都生成 8192 个 token设成 512 快速验证逻辑确认没问题后再调大。第三文件重定向加tee好用到爆iflow run webpilot --url https://example.com --lang zh-CN 21 | tee result.log这样既能在终端实时看结果又能把输出存到文件里方便后续检查。6. 进阶扩展让这个工具更适合日常使用6.1 从单条命令到批量处理网页下载翻译工具做出来后很快就不满足于一次只处理一篇文章了。我有一个批量处理需求一次性翻译 5 篇相关文档然后合并成一个知识笔记。这个需求用 Shell 循环就能解决for url in $(cat urls.txt); do iflow run webpilot --url $url --lang zh-CN --mode translate notes.md echo notes.md done注意批量调用时务必要控制并发数量。CLI 工具默认是串行调用的但如果你手动开了多个终端并行执行不要超过平台的并发限制否则可能触发限流。6.2 保存常用术语表翻译技术文档时术语一致性很关键。同一个英文术语在不同的段落里被翻译成不同中文词汇会让读者很困惑。我的做法是在 Command 里增加一个可选的glossary参数输入一组“术语译名”的映射并在提示词里要求模型严格遵守- name: glossary type: text required: false description: 术语表格式为 英文中文多个用分号分隔iflow run webpilot --url https://example.com --glossary API应用程序接口;CLI命令行工具这个方法在处理框架文档的时候尤其好用能确保整套文档的术语口径一致。6.3 给团队用的一些建议如果想把这套 Command 分享给团队成员配置文件本身可以直接复用。不过要注意两点一是成员需要各自完成iflow auth login二是如果团队有统一的术语表或输出格式要求最好在配置里内置不要依赖个人记忆。7. 我的实操心得与后续打算7.1 几个亲测有效的“土办法”踩过这些坑之后我现在写这类 Command 已经有一套固定套路了。无论什么任务只要涉及网页内容和翻译我都会先做粗清洗再加语言前置判断最后规定输出格式。这三个步骤看起来简简单单但缺一个都会在日常使用中出现让你头疼的问题。比如语言前置判断我一开始根本没想到还有“翻译同语言文本”这种怪事直到实际遇到两次才意识到。后来我把这个判断放到了所有翻译类 Command 里不管是网页翻译还是文档翻译都先问一句“原文语言是什么”这句话能避免至少一半的无效调用。7.2 这类能力的通用性做完这个项目之后我最大的感受是Command 这种“把复杂任务固化成接口”的思路其实不限于抓网页和翻译。只要是重复的、需要模型参与的任务都能套用这个模式。比如定时收集资讯并生成简报、把会议录音的转写文本整理成纪要、监测页面变化并生成差异说明——这些都可以用类似的方法封装成 Command。我现在已经把“资讯收集简报”做成了另一个 Command用的还是这套架构一个参数topic一个参数lang提示词模板改一改新增一个 Command 只需要几分钟。这也是为什么我特别推崇 CLI 工具的原因——一旦掌握了模式复用的成本低得惊人。7.3 最后分享一个实用小技巧作为收尾分享一个我最近特别喜欢的小技巧把 Command 输出和系统剪贴板打通。在 macOS 上可以这样操作iflow run webpilot --url https://example.com --lang zh-CN --mode translate | pbcopy瞬间译文就复制到剪贴板了再找个地方粘贴出来核对整个过程一气呵成。对于经常需要处理外文资料的人来说这个体验真的很舒服。如果你平时也用 iFlow CLI我建议你从一个小任务开始先别贪多把一个页面下载翻译跑通在这个过程中感受提示词设计和参数配置的微妙之处。等思路顺了再用同样方法去封装下一个任务后面会越做越快、越做越上瘾。