波仔
🐦 第14章 实战案例：自动生成 PPT 的智能办公助手
📄 一句话概括

输出节点最容易漏的是「把中间产物当结果」：只回 task_id，用户拿着号不知道去哪取。 结果是链接，不是任务号。输出节点交出去的那一个字段，决定用户最后拿到什么。 五项检查里四项能自动验：页数、单页要点、链接可打开、文件名规范。版面只能人看。

📝 本章和前面几章的关系

这一节对应书上「应用优化与质量控制要点」和「项目小结」两小节，合成一篇。 质量控制这件事在前面的案例里都出现过（第 12 章的品牌规范、第 13 章的测试集）， 这一节讲它在这个案例里的具体形态。 末尾是本章小结，也是整本书七个案例的收口——七个案例其实只有三种形状。

一、最容易漏的一个字段

漏了什么 后果 怎么补
只回 task_id 用户拿着号，不知道去哪取 必须回 url
只回 url 不说过期 第二天点开是 404 要写有效期
回 url 但文件名乱 下载下来一堆 output.pptx 给个能认的名字

三种里第一种最常见：前面的节点全对，最后一步把中间产物当成结果交出去了。 为什么会这样？ 因为调插件的人满脑子都是「任务」，提交、轮询、取货，最后手一滑就把 task_id 传下去了。 而 task_id 对用户毫无意义。 这一条和第 13.6 节是同一件事：输出节点是唯一决定用户看到什么的地方，它漏一个字段，前面全白做。

二、文件名要能认出来

好的名字带三样：主题、页数、日期。比如「2026年新品培训_8页_20261031.pptx」，26 个字。 再长手机上一行放不下，会被截成两行，反而更难认。 坏的名字是 output.pptx 或者一串哈希。下发给二十个人，他们分不清哪个是哪个，最后还是得回来问你。

文件名这一项能自动验：一条正则就够了。能自动验的检查，就不该让人去看。

三、五项检查，四项能自动

检查项 怎么验 能自动吗
页数对不对 数 pages 字段 能
单页要点超没超 生成前就拦住 能
链接能不能打开 HEAD 一次 能
文件名规不规范 正则匹配 能
版面好不好看 只能人看 不能

四项能自动验的，就该写进链里。 第五项别硬做——用规则判版面，判出来的结论没人信，还会让人误以为已经验过了。 这也和第 12 章的品牌规范一样：能自动验的写进链，验不了的交给人的抽检。 抽检要定比例。全看太贵，不看会漏。按百分之十抽，一周抽一次，通常够发现问题。

四、链接为什么必须真打开一次

接口返回 200 不等于链接能用。可能是权限没开、可能是对象还在同步、可能是域名配错了。 验的办法很土：真发一次 HEAD 请求，看状态码。200 或 206 算通，403 是权限，404 是文件没生成。 这一步花不到一秒，省的是用户点开发现 404 的那一通投诉。

用 HEAD 不用 GET，是因为 HEAD 只要响应头、不下载文件。 真要 GET 一个 20 兆的 PPT，这一秒就变成好几秒。

五、这一章的三个教训

教训 一句话
先拦后生成 校验放在插件前面，不是后面
异步要分状态 五种状态四种去处，不能只写 done
结果是链接，不是任务号 交出去那一个字段，决定用户拿到什么

三条都不是 PPT 特有的。换成视频、换成报表、换成长文档，一样成立。 这一章真正教的不是「怎么生成 PPT」，是「怎么把一个慢的、会失败的异步服务包好」。 第 15 章的新闻视频生成器，形状和这一章几乎一模一样。

六、项目小结：七个案例，三种形状

形状 案例 难在哪
一条直线 室内设计、营销海报 提示词写得准不准
分支加兜底 抖音文案、智能客服 判类判得准不准
包一个外部服务 PPT 助手、视频生成器 失败和等待怎么处理

七个案例里，前几个难在「说清楚」，中间几个难在「判准确」，最后几个难在「接得住」。 这三件事的顺序也基本是学习的顺序：先把一句话说清楚，再学怎么分岔，最后学怎么和外面的东西打交道。 零件是有限的，组合是无限的。 到这一章为止， 你已经见过扣子平台上几乎所有会用到的节点——剩下的是把它们排对。

七、动手 Demo：生成完不给链接，等于没做完

先列输出节点最容易漏的三样，再看文件名和有效期该怎么给。 最后列五项检查，看哪四项能写成代码。

FULL = {u'task_id': u'T20261031', u'state': u'done', u'pages': 8,
        u'url': u'https://files.example.com/t/ppt.pptx', u'expire_h': 24}

NAME_OK = u'2026年新品培训_8页_20261031.pptx'
HEAD    = Q.http_get(FULL[u'url'])   # 真打开一次，看状态码

实跑输出：

--------------------------------------------------------------------
生成完不给链接，等于没做完
--------------------------------------------------------------------


  ① 输出节点容易漏什么
  --------------------------------------------------------------------

| 漏了什么 | 后果 | 怎么补 |
|---|---|---|
| 只回 task_id | 用户拿着号，不知道去哪取 | 必须回 url |
| 只回 url 不说过期 | 第二天点开是 404 | 要写有效期 |
| 回 url 但文件名是乱的 | 下载下来一堆 ppt_2026.pptx | 给个能认的名字 |

  三种里第一种最常见：前面的节点都对，最后一步把中间产物当成结果交出去了。
  这一条和 13.6 节讲输出节点是同一件事：输出节点是唯一决定用户看到什么的地方，它漏一个字段，
  前面全白做。

  ② 文件名和有效期
  --------------------------------------------------------------------
  好的名字带三样：主题、页数、日期。长度 26 字，再长手机上一行放不下，会被截成两行，反而更难认。
  坏的名字（output.pptx）下发二十份，用户分不清哪个是哪个。
  有效期 24 小时。这个数要写进回复里，不然用户第二天点开是 404，还以为你没做完。

  ③ 五项检查，四项能自动验
  --------------------------------------------------------------------

| 检查项 | 怎么验 | 能自动吗 |
|---|---|---|
| 页数对不对 | 数 pages 字段 | 能 |
| 单页要点超没超 | 生成前就拦住 | 能 |
| 链接能不能打开 | HEAD 一次 | 能 |
| 文件名规不规范 | 正则匹配 | 能 |
| 版面好不好看 | 只能人看 | 不能 |

  四项能自动验的，就该写进链里。第五项别硬做——用规则判版面，判出来的结论没人信。
  这也和第 12 章的品牌规范一样：能自动验的写进链，验不了的交给人的抽检。

  ④ 这一章的三个教训
  --------------------------------------------------------------------

| 教训 | 一句话 |
|---|---|
| 先拦后生成 | 校验放在插件前面，不是后面 |
| 异步要分状态 | pending / running / done / failed 四种都要有去处 |
| 结果是链接，不是任务号 | 输出节点交出去的那一个字段，决定用户拿到什么 |

  三条都不是 PPT 特有的，换成视频、换成报表、换成长文档，一样成立。
  ! 这一章真正教的不是「怎么生成 PPT」，是「怎么包一个慢的、会失败的、异步的外部服务」。
  第 15 章的新闻视频生成器，形状和这一章几乎一模一样。

①输出节点三样容易漏：只回 task_id、不说过期、文件名乱。 ②好的文件名带主题、页数、日期，26 字。 ③五项检查里四项能自动验，版面那一项只能人看。 ④三个教训：先拦后生成、异步分状态、结果是链接。 ⑤项目小结：七个案例三种形状——直线、分支、包外部服务。

30 秒实验

  1. 检查你们的输出节点：交出去的是结果，还是中间产物？只看这一项就能找出几个洞。
  2. 给生成的文件定一个命名规则，写成正则。写不出来的规则，人也不会遵守。
  3. 把「链接能不能打开」做成一步真请求。不做这一步，你等于在赌对方服务没问题。

常见误区

  1. 「回了 task_id 就算完成。」用户不知道去哪取。结果要交结果，不是交任务号。
  2. 「版面用规则判一下就行。」规则判出版面结论没人信，还会让人以为验过了。
  3. 「接口 200 就说明链接能用。」可能是权限没开、文件还在同步。要真打开一次。
自测三问（点开对答案） 1. 输出节点最容易漏什么？ —— 把中间产物当结果交出去，比如只回 task_id。用户拿着号不知道去哪取。 2. 五项检查里哪项不能自动验？ —— 版面好不好看。只能人看，而且抽检比例要定，全看太贵，不看会漏。 3. 这一步的七个案例能归成哪三种形状？ —— 一条直线、分支加兜底、包一个外部服务。难的地方依次是「说清楚、判准确、接得住」。

下一章做新闻视频生成器。形状和这一章一样，但多了一样东西：做完了要主动通知用户。

相关笔记