42md 知识编排（3）：写一条自己的编排

假设你常做这件事：把外文 PDF 转成中文，再导出 EPUB，揣手机上读。

内置里没有正好这条——pdf2zh 只到翻译，pdf2book 又是从中文 PDF 起步。那就自己写一条。别担心，编排是一份纯文本 YAML，跟着搭一遍就懂了。

一份编排，长什么样

动手前，先认一眼一条编排的几个字段，心里有底：

字段	干什么	必填
`name`	编排的名字，以后按它运行	是
`description`	一句话说明，列表里显示	否
`steps`	步骤清单，从上到下依次跑	是
`steps[].id`	给这步起个代号，后面引用它的产物要用	是
`steps[].run`	这步调哪个动作（`acquire` 或 `tools.<名>`）	是
`steps[].with`	传给这个动作的参数（含输入和 flag）	否（默认空，但几乎都要填）
`steps[].billed`	这步要花 AI 额度，标一下，跑前会提示	否
`output`	最后交给你哪一步的产物	否（默认取末步产物）

记不住没关系，下面搭的时候每个都会用到、随手就熟。

先搭个骨架

一条编排至少要有名字和步骤。先写第一步——提取：

name: pdf2zhbook                 # 名字，以后按它运行
steps:
  - id: extract                  # 步骤 id，唯一
    run: acquire                 # acquire = 把输入转成 Markdown
    with: ["{{ input }}"]        # 给它的参数：你运行时传的那份 PDF

run: acquire 是「主获取」，把 PDF / 网页 / 录音转成 Markdown，几乎所有编排的第一步都是它。{{ input }} 是个占位符，代表你运行时给的那份文件。

加第二步：翻译

提取出的 Markdown，要喂给翻译。这就用到编排的核心——把上一步的产物接到下一步：

  - id: translate
    run: tools.translate                          # 调「翻译」这个单步工具
    with: ["{{ steps.extract.output }}", "--target", "中文"]
    billed: true                                  # 这步花钱，标一下

{{ steps.extract.output }} 的意思是「extract 这一步产出的文件」。你不用关心它叫什么、存哪——编排替你接好。--target 中文 就是你平时 42md tools translate 会写的参数，原样透传。

加第三步：导出 EPUB

同样，把翻译的产物喂给导出：

  - id: book
    run: tools.md2epub
    with: ["{{ steps.translate.output }}"]

最后告诉它你要哪一步的产物：

output: "{{ steps.book.output }}"

能调哪些动作？查一下，别背

上面用了 acquire、tools.translate、tools.md2epub。还能调什么？别背、别猜——一条命令列全：

42md recipe verbs

它会列出当前版本所有能调的动作，标好哪个免费、哪个计费。这是真相源，永远跟你的 42md 对得上。常用的这些先有个印象：

动作	干什么	计费
`acquire`	把 PDF / 网页 / 录音转成 Markdown（主获取）	视输入（音频转写计费，多数本地免费）
`tools.translate`	翻译成目标语言	计费
`tools.improve`	按模板改写 / 润色	计费
`tools.summarize`	提炼要点摘要	计费
`tools.lint`	版式优化（断行、全角化）	免费
`tools.md2epub`	导出 EPUB 电子书	免费
`tools.md2pdf`	导出精排 PDF	免费
`tools.md2wechat`	转公众号排版	免费

（除上面这些，还有 tools.hotwords、tools.md2docx、tools.md2html、tools.merge、tools.split、tools.compress 等——完整清单以 42md recipe verbs 当场列出的为准，你的版本支持哪些，它就显示哪些。）

拼起来，跑

把三步合到一份文件，存成 ~/.42md/recipes/pdf2zhbook.yaml（文件名和 name 一致）：

name: pdf2zhbook
description: 外文 PDF → 翻译成中文 → 导出 EPUB
steps:
  - id: extract
    run: acquire
    with: ["{{ input }}"]
  - id: translate
    run: tools.translate
    with: ["{{ steps.extract.output }}", "--target", "中文"]
    billed: true
  - id: book
    run: tools.md2epub
    with: ["{{ steps.translate.output }}"]
output: "{{ steps.book.output }}"

存好它立刻就和内置一样可用：

42md recipe list                       # 能看到 pdf2zhbook，标着「自定义」
42md recipe run pdf2zhbook 论文.pdf    # 按名运行

写一次，以后一行命令复用。

不想碰命令行？网页端填同样的字段

YAML 看着眼晕的话，网页端也能可视化地填。打开「我的编排 → 新建编排」，同样是名字、说明、步骤这几样，下方编辑框里还把字段含义标在旁边：

网页端「新建编排」表单：名称、说明、步骤编辑框，底部标注各字段含义

填好保存，命令行一样按名运行。手写、网页填，殊途同归——字段是同一套。

还能更稳、更灵活

这条能跑了。但你可能想让它「随手换个花样」，也想在跑之前确认没写错、别白花钱。这些下一篇讲——参数化、多产物，和运行前的自检。

知识编排系列

第（1）篇：多步流程，一条命令跑完
第（2）篇：七个内置编排，开箱即用
第（3）篇：写一条自己的编排（本篇）
第（4）篇：让编排更灵活、更可靠
第（5）篇：一句话，让 AI 生成编排
第（6）篇：把编排交给 AI 助手

活水 AI 实验室（42ailab） — 探索智能边界的 AI 创新实验室，以认知科学为基石，推动 AI 与人类智能的深度融合，真正理解并增强智能 —— 碳基的，也是硅基的。

活水MD（42md） — 活水 AI 实验室出品的高性能 Markdown 处理工具。AI 时代的 Markdown，一站式处理：42+ 种格式一行转 Markdown，还支持翻译、摘要、导出等十余种知识工具，并支持知识编译、流程编排、本地引擎与 Agent 调用。