最近我一直在折腾 iFlow CLI 的自定义 Command，起因是每天要看好几篇英文技术博客，一边开翻译网页一边复制粘贴实在太低效。后来我用 iFlow CLI 写了一个自定义 Command，把“网页文章下载 + 翻译”打包成一条命令，输入 URL 直接输出中英对照的干净正文，整个过程从想法到落地用了不到一个下午。这个工具对我的意义在于：它不只是省时间，而是把“读外文资料”这件小事变成了一个可复用、可分享、可继续扩展的工作流。如果你也经常需要快速阅读外文网页、整理资料，或者正在研究 iFlow CLI 的自定义命令玩法，这篇内容应该能给你一个可以直接照搬的方案。
我猜很多人对 iFlow CLI 的第一印象是“这不就是个聊天命令行工具吗”，但它的自定义 Command 设计其实比表面看起来要灵活得多。你可以把一次固定的 AI 处理流程固化成命令，像用脚本一样重复调用。这篇我会从设计思路、配置文件结构、正文提取和翻译参数调优一路讲到我实际踩过的坑，代码和配置都会放出来，你照着抄就能跑。
1. 项目概览与设计思路
1.1 为什么选择 iFlow CLI 来打造自定义 Command
先交代一下背景。在做这个网页文章下载翻译工具之前，我用的是两种老办法：一是写 Python 爬虫脚本，调第三方翻译 API；二是手动复制原文丢给在线翻译或对话框处理。前者的问题非常典型：各种网页结构不一样，爬虫脚本要针对每个网站做 CSS 选择器适配，遇到动态渲染页面还得上 Selenium，维护成本比写脚本本身还高；翻译 API 要么有字数限制，要么术语处理僵硬，翻完根本没法直接读。后者的问题就更直接了，手动操作意味着每天重复同样的复制粘贴动作，效率低还容易漏内容。
iFlow CLI 的自定义 Command 恰好解决了这几个痛点。它可以让我在一个配置文件里编排“抓取网页 → 提取正文 → 调用大模型翻译 → 格式化输出”这条完整链路，不需要自己写爬虫框架，也不需要维护多个 API 账号。更重要的是，Command 一旦定义好，不只是我一个人能用，团队里其他人装好 iFlow CLI 后也能共享同一个命令，这对做技术资讯监控、外文资料归档这类工作来说非常实用。
我实际用的场景是每天早上把收藏夹里的 5 到 8 篇英文文章统一跑一遍，生成一个 Markdown 文件，然后在飞书文档里贴一份中英对照版，做早报素材。以前这个过程要小一个小时，现在一条命令十几秒就出结果，剩下的时间基本只花在通读和挑重点上。
1.2 网页文章下载与翻译的核心链路拆解
把整个工具拆开看，核心链路其实就五个环节：输入 URL、抓取网页原始 HTML、从 HTML 里提取正文内容、将正文交给大模型翻译、最后按指定格式输出结果。听着简单，但每个环节都有不少细节需要处理。
第一环节输入 URL，看起来只是传参，实际上要考虑 URL 是否包含中文参数、是否是短链、是否需要带 User-Agent 或者 Cookie。第二个环节抓取网页，普通浏览器能打开的页面不一定能被程序拿到，有些站点会做 UA 校验，有些页面内容是通过 JavaScript 动态渲染出来的，首次抓取拿到的 HTML 可能只是一个空壳。第三个环节正文提取，这是最核心也是最有坑的一步，HTML 里除了正文还有导航、侧边栏、广告、评论区，如果提取不够精准，翻译出来的内容会混杂大量无关信息。第四个环节翻译，直接调大模型翻译虽然可行，但提示词方案直接决定了术语准确性和格式保留程度。最后一个环节输出，需要处理 Markdown 结构、超长文本分段和编码统一的问题。
我把这一步一步都固化到 Command 配置里，目的就是让这些复杂性对使用者完全透明。你只需要记住一个命令名，填一个 URL，其他事情全交给 iFlow CLI 的执行器去编排。下面我会把每个环节的具体配置方法掰开揉碎了讲。
2. 环境准备与基础认知
2.1 iFlow CLI 安装与环境配置
动手之前先把环境跑通。iFlow CLI 的安装方式我用的 npm 全局安装，前提是你本机已经有 Node.js 18 或更高版本。安装命令很简单：
npm install -g @iflow/cli安装完可以先确认版本号和基本帮助信息：
iflow --version iflow --help接下来是登录认证。iFlow CLI 属于大模型开放平台的前端入口，所以需要先注册一个账号并创建 API Key。登录交互方式一般有两种，一种是直接在终端里运行iflow auth login然后输入账号密码，另一种是更常见的 API Key 方式，把密钥导出为环境变量：
export IFLOW_API_KEY="你的_API_Key"建议把这一行写进 shell 的配置文件，比如~/.bashrc或~/.zshrc，避免每次开终端都手动导一遍。配置完成后可以运行iflow command list看看默认自带哪些命令，如果能看到命令列表，说明 CLI 和服务端的连接已经通了。
这里特别提醒一点：自定义 Command 最终翻译用的模型能力依赖于账号权限，有些新注册账号默认只有基础模型，跑较大文章时可能会提示模型不可用。我一开始就遇到llm.generate报模型无法加载的问题，后来检查后台才发现是没开通高级模型权限。所以环境配置时，顺手去控制台确认一下模型服务的可用范围，能省掉后面很多排查时间。
2.2 理解自定义 Command 的配置文件结构
iFlow CLI 的自定义 Command 本质上是一个结构化描述文件，我习惯用 YAML 格式维护，因为可读性最好，也便于放进 Git 做版本管理。这个文件的含义可以类比为给一个外包团队写的任务委托书：你描述清楚命令叫什么、接收哪些输入、每一步做什么，执行器就会按照步骤依次完成。
一个典型的自定义 Command 会包含这些板块：
name：命令的唯一标识，后续执行时就是iflow command run <name>。description：一段给人和模型看的说明，方便别人理解这个命令的用途。parameters：声明命令接收的参数，包括参数名、类型、是否必填、默认值。steps：核心执行步骤列表，每个步骤调用一个内置工具，比如http.fetch抓网页、html.extract提取正文、llm.generate调用大模型。output：定义命令最终输出的格式，常见有markdown、json、text。
目录结构上我喜欢按命令单独建文件夹，就像一个小型项目：
commands/ └── article-download-translate/ ├── command.yaml └── README.mdcommand.yaml是执行器读取的入口，README.md主要给团队成员看使用说明。这样的组织方式在后期扩展多个命令时非常清晰，不会所有配置都堆在一个文件里。
3. 自定义 Command 的完整实现
3.1 Command 入口与参数设计
先看完整版command.yaml，然后我再拆开讲解为什么这么写。这个文件是我实际在用的版本，去掉了内部的一些环境信息：
name: article-download-translate description: 下载指定网页的文章正文，并翻译为目标语言，输出中英对照 Markdown version: 1.0.0 parameters: - name: url type: string required: true description: 网页文章链接，必须以 http:// 或 https:// 开头 pattern: "https?://.+" - name: target_lang type: string required: false default: zh-CN description: 目标语言代码，例如 zh-CN、en、ja - name: source_lang type: string required: false default: auto description: 源语言代码，auto 表示自动识别 - name: max_chars type: integer required: false default: 5000 description: 单次翻译的最大字符数，超过部分自动分段 steps: - id: fetch_page use: http.fetch with: url: "{{ url }}" timeout: 30 headers: User-Agent: "Mozilla/5.0 (compatible; iFlow CLI)" - id: extract_article use: html.extract with: html: "{{ fetch_page.body }}" mode: readability content_selector: "article, .post-content, .article-content" - id: split_content use: text.split with: content: "{{ extract_article.content }}" max_chars: "{{ max_chars }}" - id: translate_article use: llm.generate with: model: "{{ model | default('auto') }}" temperature: 0.2 system: | 你是一名专业的科技文章翻译者。你的任务是准确翻译技术文章，保持术语一致性，保留原有 Markdown 结构和代码块内容，不要总结原文。 prompt: | 请将下面的网络文章翻译成 {{ target_lang }}，源语言为 {{ source_lang }}。 需要输出中英对照格式： - 第一行为英文原文段落 - 第二行为中文翻译段落 不要输出额外的说明文字。 文章内容如下： {{ item }} loop: over: "{{ split_content.parts }}" as: item - id: render_output use: output.render with: format: markdown content: "# {{ extract_article.title }}\n\n源链接：{{ url }}\n\n{{ translate_article.output }}"先看参数设计。url是唯一必填参数，加了正则限制，避免有人漏掉协议头导致抓取失败。target_lang默认中文简体，但保留覆盖能力，万一我想看日语版文章就不用改配置。source_lang默认auto，让模型自动判断源语言。max_chars这个参数是我踩坑后加上的，后面翻译环节会细说。
steps里最需要解释的是loop这一层。很多人第一次写自定义 Command 时会忽略超长文本的问题，直接一次性把全文丢给模型，结果十篇有八篇因为上下文过长报错。我这里的做法是把提取出来的正文先按max_chars切分成多个片段，然后用 loop 逐段交给llm.generate翻译，每一段独立输出，最后再合并。虽然牺牲了一点上下文连贯性，但胜在稳定，而且实际翻译效果经过实测是可以接受的。
3.2 网页正文提取的关键实现
网页正文提取是整个工具里最容易被低估的环节。你可能觉得抓 HTML 还不简单，但实际上一个新闻页面的原始 HTML 可能有几十 KB，其中真正属于文章的段落占比不到一半。如果不对内容做裁剪就送进翻译，模型会连导航菜单和页脚广告一起翻出来。
我配置里用的html.extract工具，mode设置为readability，它的核心原理是遍历页面里的 DOM 节点，根据每个节点的文本密度、链接密度、标签特征来识别哪个容器最像正文区域。这个算法在多数博客和新闻网站上表现都不错，基本能替代以前我手动写的选择器。
但 readability 也有失灵的时候，所以我在配置里额外加了一个兜底设计：content_selector列出常见的正文容器选择器。执行器会先试 readability 提取，如果得到的内容长度低于某个阈值，就改走选择器方案，直接定位<article>或.post-content这样的容器。相当于读文科生的阅读理解：第一遍通读找中心思想，不行就根据小标题定位重点。
实际处理中还有两个细节。第一是编码问题，国内有些站点还是 GBK 编码，抓回来全是乱码。我在 fetch 步骤里没有显式配置编码，但 iFlow CLI 的http.fetch会根据响应头自动处理，遇到那些没声明 charset 的老页面，偶尔需要手动在环境变量里指定默认编码为 UTF-8。第二是动态渲染问题，如果页面内容是通过 JavaScript 异步加载的，直接抓到的 HTML 里根本没有正文。这时的表现是提取结果为空或只有几十个字，我会再检查是不是页面结构比较特殊，然后用打开浏览器模式的替代方案或换用该页面的 print 版本打印版本 URL 来规避。
分享一个我的实测细节：html.extract提取正文后会自动把结构转成文本，但部分技术站点里的代码块会丢失换行。我后来在split_content之前加了一个简单的text.normalize步骤，统一把\r\n转成\n，同时合并连续空行。这个改动很小，但对后续翻译输出质量的影响非常大，代码块一旦错乱，模型翻译时经常把代码也当成英文给翻了。
正文提取这段，我给你的建议是不要迷信单一方案。先在本地挑 10 个不同类型的网站试跑，看提取结果里有没有残留页眉页脚。我试下来，Readability 模式对长篇技术博客的表现最好，对资讯类页面偶尔会吃掉开头几个段落，这时就需要手动调一下content_selector的优先级。
3.3 翻译链路的接入与参数调优
翻译环节是整个 Command 的“灵魂”，也是参数最值得调的地方。我其实可以调用现成的机器翻译 API，但技术文章里经常出现开源项目名、函数名、专业术语，机器翻译往往处理得很僵硬。换成大模型生成式翻译之后，术语一致性好了很多，而且我能通过提示词让模型保留 Markdown 结构。
我的system提示词里强调了三件事：术语一致性、结构保留、不要总结原文。这三点都是在实际测试中总结出来的。最初版本我的提示词只写了“请翻译以下文章”，结果模型会把技术术语意译成奇怪的中文组合词，甚至把 Markdown 标题层级打乱。后来我明确了系统提示词之后，输出稳定了很多。
温度参数我固定在0.2。我试过默认温度0.7，翻译结果里会出现同一个术语前后翻法不一致的情况，比如第一条里latency翻成“延迟”，第三条里变成“时延”。这种情况在技术文档场景里很致命，因为读者会以为作者在说两个不同概念。温度调低后，模型更倾向于保守一致的输出，虽然少了点文采，但对技术翻译来说准确比文采重要得多。
在提示词里我还特意要求输出“中英对照格式”，这是这个工具的隐藏重要需求。因为我做早报不只是要中文译文，经常需要回看英文原文原文确认细节，尤其遇到长难句的时候，中文翻译可能会损失信息，对照着看才能放心。输出格式是这样：
第一行是英文原文段落，第二行是中文翻译段落。这里有一个实现技巧：模型在每一段循环翻译时并不知道它翻的是第几段，所以合并时我会在原配置里用translate_article.output直接拼接。如果你希望每段之间加分割线，可以在 loop 里多做一步text.append。
还有一个常见争议：到底该翻译整篇全文，还是先提取摘要再翻译？我两种模式都试过。提取摘要再翻译，速度快、token 省，但遇到信息密度高的技术文章，摘要级翻译经常会漏掉关键实现细节。我现在默认是全文翻译，但在内部评审时发现其实可以做成一个mode参数，full和summary随意切换。后续版本我准备在参数里加一个mode，让命令更通用。
翻译链路里最后也最关键的一点是超长处理。text.split按max_chars切分文本时，我会设置一个合理的经验值：默认 5000 字符。为什么不是更大的 8000 或 10000？因为一个中文汉字和一个英文字符在 token 计算里不是一个量级。5000 字符折算成 token 大概在 2000 到 3000 之间，加上输入输出预留，能稳定跑完不会被大模型上下文窗口卡死。如果你的常用模型上下文很长，可以适当调大，但建议留出至少三分之一的余量。
4. 实操经验与常见问题排查
4.1 真实使用场景踩坑记录
第一坑，URL 带中文参数。收藏夹里的一些文章链接长这样：https://example.com/article?title=机器学习实战。直接在命令行里传给iflow command run时，shell 可能会把中文当成特殊字符处理，导致http.fetch拿到的是被截断的 URL。解决方式是执行前先用encodeURIComponent处理，或者至少用英文引号把整个 URL 包起来。我在配置里加了 pattern 校验只检查协议头，这一步建议封装成快捷键来解决。
第二坑，正文提取后残留广告段落。我拿某科技博客测试时，Readability 模式居然把页面上的一条赞助内容也识别成正文的一部分，结果译文里突然冒出一段和文章毫无关系的“限时特惠”。这个问题后来通过content_selector指定多个候选容器才解决，测试了几个页面后我把优先级调整成article优先，广告区块通常在aside或div里，能被自然过滤掉。
第三坑，翻译 token 超限。这个问题前面提过，是我最开始写 Command 时忽略的。我试过一次性翻译一篇 8000 词的深度长文，连续报了几次上下文过长错误。后来我加了text.split分段循环之后，又遇到另一个连锁问题：分段点如果正好落在代码块中间，翻译出来的代码块就会残缺。我的规避方案是把分段的大小设置得比模型上限更保守，并且在抓取正文后先进行一次“代码块保护”，大致逻辑就是先把代码块内容替换成特殊占位符，分段完成后再还原，这样代码就不会被拦腰截断。如果 iFlow CLI 没有内置这个能力，技巧是设置max_chars时留大量余量，分段尽量均匀。
第四坑，输出格式不统一。早期版本我没有配置output.render的格式，导致终端里直接打印模型的原始输出，有时代码块会丢失标记，有时还会混入模型自己的思考前缀。后来我把format固定成markdown，并且把源链接和文章标题全部拼接进输出内容里。这样命令的输出不仅能直接看，还能重定向到文件生成日报。
4.2 常见问题速查表
我把这一阵子使用 iFlow CLI 过程中遇到的高频问题整理成一张表，方便你拿去直接排查。
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
http.fetch返回空内容 | 网站做了 JS 动态渲染或 UA 校验 | 设置 User-Agent，试打印版 URL，或换用浏览器渲染模式 |
| 提取正文后内容只有几十字 | Readability 识别失败 | 调整content_selector，优先使用article容器 |
| 网页乱码 | 页面编码为 GBK 且未声明字符集 | 指定默认编码为 UTF-8 或手动转码 |
| 翻译结果术语前后不一致 | 温度值过高 | 调低 temperature，建议在 0.2 到 0.3 之间 |
| token 超限报错 | 全文一次送入模型 | 用text.split分段，并配合 loop 逐段翻译 |
| 代码块翻译后残缺 | 分段切在代码块内部 | 先保护代码块占位符，分段后还原 |
| 输出结果混入模型额外说明 | 提示词未约束输出格式 | 明确要求“只输出翻译结果，不要输出额外说明” |
| 中文参数 URL 执行失败 | shell 未正确编码 URL | 先做 URL 编码，或用引号包裹再传递 |
排查这些问题时我的习惯顺序是：先看抓取是否成功，再看正文是否提取完整，最后才看翻译参数。很多人一遇到输出不对就直接调提示词，反而浪费时间。抓取和提取这两步问题没解决，提示词改得再好也没有意义。
4.3 一条命令延伸出的完整工作流
这个自定义 Command 最让我舒爽的使用方式是配合批量脚本。我写了一个简单的 bash 函数来循环调用命令：
#!/bin/bash URLS=( "https://example.com/article/1" "https://example.com/article/2" "https://example.com/article/3" ) for url in "${URLS[@]}"; do iflow command run article-download-translate \ --param url="$url" \ --param target_lang=zh-CN \ --param max_chars=4000 >> daily_digest.md done然后把生成的daily_digest.md扔进 Obsidian 或直接发到团队文档里，一份外文资讯早报就成型了。这个方案比在线翻译工具强的一点是，我可以把整个处理过程保存成可复现的工作流，后面想调整模型、语言、输出格式，都只改配置文件，不用改使用端的任何东西。
5. 写在最后的项目体验
这个项目做到后期，我已经不太把它当成一个“翻译工具”了，而是一个通用的“网页内容处理框架”：同一套 Command 结构，稍微修改提示词就可以变成“一键总结文章”、“提取某篇文章的所有链接”、“把博客转成小红书文案”等等。iFlow CLI 自定义 Command 真正的价值就在于把一次性的 AI 对话转化成了可编程、可组合、可分享的原子能力。
我个人在用了差不多两个星期之后，最大感受是：以后遇到重复的文字处理需求，第一反应不再是打开编辑器写脚本，而是先想想能不能用一条 Command 固化下来。固化的过程本身也是在整理自己的方法论，因为你需要把模糊的需求拆成抓取、提取、清洗、生成、输出这几个明确步骤，这个拆解动作本身就足够有价值。如果你也想做类似的网页文章下载翻译工具，建议先从这个最小配置起步，跑通一个 URL，再慢慢加参数、调提示词、加批量处理。等这一步走顺了，你会回来感谢那个愿意折腾的自己。
