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

最近用 iFlow CLI 折腾了一个特别顺手的小工具：一条命令抓取网页文章正文，再自动翻译成指定语言。这个需求我其实惦记很久了——每天要读不少英文技术博客，浏览器自带翻译体验一般，把全文复制到对话窗口又总是被上下文长度卡住。最初我只是想简化这个流程，等真正理解了 iFlow CLI 的自定义 Command 机制之后，才发现它非常适合固化这种“多步骤、重复、有固定套路”的任务，于是把整套流程沉淀成了可以直接调用的 Command。

这篇文章完整记录了我的实现过程，从 Command 的配置结构、提示词设计、参数体系，到调试过程中踩过的几个坑，都会逐一展开。如果你也在用 iFlow CLI，或者单纯对“把多步骤任务固化成一条命令”这个思路感兴趣，可以直接照着抄。

1. 整体思路：为什么要把下载和翻译固化成 Command

1.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. 核心实操：网页文章正文提取 Command

3.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, timeout=15) 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}} 模式处理： 如果mode=translate： 将全文翻译成{{lang}}，要求： - 术语保持一致，原文术语首次出现时在括号内标注英文原词 - 代码块、表格、链接URL原样保留，不翻译 - 标题层级结构保持不变 如果mode=summary： 输出这篇文章的核心观点，分条列出，每条不超过50字。 如果mode=bilingual： 分段输出原文和译文，格式为"原文段落"后跟空行再跟"译文段落"。 如果原文是{{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 问题速查表

我把使用过程中遇到的典型问题整理了一下，方便你遇到同类问题时快速定位。

5.2 记忆最深刻的一次调试

最让我抓狂的问题是：webfetch命令在处理某个网站时，输出内容永远只有标题和第一段，后面的正文全都不见了。排查了很久，最后发现原因有两个叠加：第一，那个网站的正文长度极长，单次输入已经把上下文占了大半；第二，我的提示词里有一条“保持简洁，避免重复”，模型在上下文紧张时，把“简洁”理解成了“截断到摘要长度”。

这一度让我意识到，提示词里的每一个模糊形容词都可能被模型以意想不到的方式执行。“保持简洁”这种说法太主观了，不同模型对简洁的理解差异很大。后来我把这句删掉，换成“输出全文，无论内容多长，都要完整输出所有段落”，问题立刻解决。

5.3 日志和调试的实用技巧

在我这版 CLI 上，有几个调试技巧帮了大忙，分享给你。

首先是用--verbose或-v参数查看详细的请求日志，能直观看到模型实际收到的提示词长什么样。很多问题当天就能定位：比如变量是不是正确替换进去了，提示词里的{{}}占位符有没有残留，都能看清楚。

其次是善用--max_tokens来控制成本。调试阶段没有必要每次都生成 8192 个 token，设成 512 快速验证逻辑，确认没问题后再调大。

第三，文件重定向加tee好用到爆：

iflow run webpilot --url "https://example.com" --lang zh-CN 2>&1 | 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，我建议你从一个小任务开始，先别贪多，把一个页面下载翻译跑通，在这个过程中感受提示词设计和参数配置的微妙之处。等思路顺了，再用同样方法去封装下一个任务，后面会越做越快、越做越上瘾。