一、开始节点只收一个字段

share_text，字符串，必填。就这一个。 为什么不多收几个？比如让用户顺便指定「改成什么风格」。 因为每多一个参数，智能体就多一个填错的机会。 风格这件事可以放到第二次对话里问，不必塞进第一次调用。

必填项要设。 不设的话，用户什么都没粘，智能体也能调——插件那边收到空串，回你一个空结果，你还以为是接口坏了。 这一条和第 9.3 节的「开始节点只有一个图片地址」是同一个做法：入口窄，链路才好维护。

二、视频解析插件：接口描述四件套

插件不是一段代码，是一份说明书。四样东西缺一不可：

四样里最容易被糊弄的是「描述」。 它就是一句给人看的话，可大模型也读它——智能体判断「该不该调这个插件」的时候，看的就是这句。 所以描述要写清「给什么、返什么」，不要写「视频解析工具」这种废话。 演示里两份描述都过了平台的五项校验：有名字、有描述、地址 http 开头、有参数、参数有类型和必填标记。

三、中文参数必须编码

这是本节第一个真踩到的坑。 分享文案长这样：「3.24 复制打开抖音， 看看【英语老张】的作品 # 英语学习 https://v.douyin.com/iRNBho6u/」 直接把它拼进 URL 的查询串，请求会失败——里面有空格、有中文、有井号。 井号尤其致命，它把后面全当成了锚点，服务端根本收不到。 第一次跑就是这样：状态 0，返回一个 _raw 字段，里面是异常文本。

改法一行：把参数值整个 quote 一遍再拼。演示里改完，状态 200，5 个字段全回来了。 插件调不通，先看参数编码，再看地址。 这两个占九成的失败。

四、字幕获取插件：串联的证据

第二个插件的参数是 video_id，值来自第一个插件的输出。 真调一次：状态 200，十四毫秒，六条字幕。第一条是「很多人学英语，背了十年单词，还是开不了口」。 这条成功本身就是「顺序对了」的证据。 顺序反了的话，这里拿到的是空 ID。

顺便看一眼解析节点返回的 5 个字段：video_id、author、title、duration、subtitle_url。 其中 subtitle_url 是字幕地址，video_id 是钥匙。 两个都在，但用法不同——前者可以直接请求，后者要传给下一个插件。 真机上往往两个都要：先用 ID 换地址，再请求地址拿字幕。这里合并成了一步，少一次往返。

五、少传一个参数，接口照样 200

这是本节最重要的一条。故意不传 video_id 再调一次字幕接口： 状态 200，返回的还是那六条字幕。 因为本地这个服务不校验参数——真接口会校验，但它的反应通常是 400 或者返回空列表，不是抛异常。

两种都不会让链停下来。链照跑，结束节点交出一个空字符串，卡片上是空的，日志是绿的。 所以插件节点的输出必须判空。判空这一步不在插件里，在你后面那个节点里。 接口回 200 不等于数据对。 这句话值得抄在本子上，插件调试能省一半时间。

六、第一个大模型：提炼金句

输入是整段字幕，输出是三条「有传播力」的句子。 演示里六句字幕，按关键词命中数挑：命中「问题不在」「教你」「别再」「胜过」这些词的优先。 结果是三条：「问题不在词汇量，在于你没把句子说完整」「今天教你一个笨办法」「别再背单词表了， 背句子」。

注意第四句「一句话练二十遍，胜过二十句话各练一遍」命中两个词，却没进前三——因为按顺序取前三条， 它排在后面。 这就是规则替身的局限：它不会权衡。 真机上模型会看哪句更适合做开头，而不是数关键词。 提示词要写清三件事：挑几句、什么样的句子算好、输出格式（一行一句，不要编号）。

第三件最容易被忽略。不写格式，模型会给你一段话，下一节点又要拆一次。

七、第二个大模型：二次创作

输入是三条金句，输出是一段仿写。演示里用一张替换表：英语换健身、单词换器械、句子换动作。 三句的相似度：0.47、0.89、0.37。 0.89 那句只换了三个字，基本等于没改——这是「改」不是「写」。

0.37 那句换了骨架，可以发。0.47 也在区间里。 这条替换表当然不是真仿写，它只能说明一件事：「换词」和「换结构」是两件事，相似度能量出差别。 真机上提示词要写清「保留观点、换掉结构和例子」，还要给一两个例子。 第 6.3 节讲过，例子比形容词管用。

八、结束节点交什么

交三个字段：original（原句）、draft（仿写）、score（相似度）。 为什么把原句也交出去？因为人要对照着看。只给仿写，判断不了改得够不够。 为什么把相似度也交出去？因为它是一个可以让人一眼判断的数。0.89 摆在那儿，不用读两遍就知道得重写。

输出里带上「判断依据」，比只带结论有用。 这一条在第 8.7 节没讲， 但对这种「人要做最后一道筛」的场景特别重要。

九、六个节点配完，回头看

两个插件负责「拿」，两个大模型负责「想」，开始和结束负责「进」和「出」。 配的过程中真正卡住的只有两处：参数编码、输出判空。都不是节点的问题，是接口的问题。 这也说明一件事：工作流本身不难，难的是外面那些你控制不了的东西。

十、动手 Demo：两个插件真调，两段大模型真跑

本地起一个 HTTP 服务，挂两条路由：/parse 和 /subtitle。 插件按接口描述真发请求，拿到视频信息，再拿 ID 换六条字幕。

ROUTES = {u'/parse': (200, json.dumps({...})),
          u'/subtitle': (200, json.dumps({...}))}
base, stop = Q.serve(ROUTES)        # 真起服务，随机端口

code, data = Q.call_plugin(P_PARSE, base,
                            {u'share_text': quote(text, safe=u'')})

实跑输出：

--------------------------------------------------------------------
两个插件真调，两段大模型真跑
--------------------------------------------------------------------


  ① 两个插件的接口描述
  --------------------------------------------------------------------
  视频解析 ：给分享链接或视频 ID，返回标题、作者、字幕地址
      参数 share_text（string，必填）：分享文案
  字幕获取 ：给视频 ID，返回逐句字幕
      参数 video_id（string，必填）：视频 ID
  两份描述都过校验：五项全过

  ② 真发两次请求
  --------------------------------------------------------------------
  解析：状态 200，26.4 毫秒
  拿到 5 个字段：author、duration、subtitle_url、title、video_id
  分享文案里全是空格、中文、井号，
  不编码直接拼进 URL 会失败——这次把 share_text 整个 quote 了一遍才发出去。
  字幕：状态 200，2.4 毫秒，6 条
  第一条：很多人学英语，背了十年单词，还是开不了口。

  ③ 少传一个参数，接口照样返回 200
  --------------------------------------------------------------------
  不传 video_id：状态 200，返回 {"video_id": "7281000000000000001", "count": 6, "lines": ["…
  真实接口不会这么客气，它会给 400 或者一个空列表。两种都不会让链停下来，要你自己判空。
  ! 插件的坑几乎全是这一种：参数没对上，接口还回 200。

  ④ 提炼：从六句里挑三句
  --------------------------------------------------------------------

| 字幕 | 命中关键词 | 结论 |
|---|---:|---|
| 很多人学英语，背了十年单词，还是开不了口。 | 0 | — |
| 问题不在词汇量，在于你没把句子说完整。 | 1 | 选了 |
| 今天教你一个笨办法：每天只练一句话，练到不用想。 | 2 | 选了 |
| 第一周你会觉得慢，第二周你会觉得顺，第三个月你… | 0 | — |
| 别再背单词表了，背句子。 | 1 | 选了 |
| 一句话练二十遍，胜过二十句话各练一遍。 | 2 | 选了 |

  三条金句：「问题不在词汇量，在于你没把句子…」 / 「今天教你一个笨办法：
  每天只练一…」 / 「别再背单词表了，背句子。」
  真机上这一步是大模型在判「哪句有传播力」，这里是关键词表。差别在于它认得出第一次见到的说法。

  ⑤ 仿写：换主题不换骨架
  --------------------------------------------------------------------

| 原句 | 仿写 | 相似度 |
|---|---|---|
| 问题不在词汇量，在于你没把句子说完整。 | 问题不在训练量，在于你没把动作做标准。 | 0.47 |
| 今天教你一个笨办法：每天只练一句话，练… | 今天教你一个笨办法：每天只练一个动作，… | 0.89 |
| 别再背单词表了，背句子。 | 别再背器械表了，背动作。 | 0.37 |

  只换了几个词，骨架没动：三句的相似度分别是 0.47、0.89、0.37。这是「改」，不是「写」。
  第二句只换了「一句话」三个字，相似度 0.89——基本等于没改。
  第 10.1 节定的验收标准是 0.2 到 0.6，这一句必须打回。

  ⑥ 接口挂了会怎样
  --------------------------------------------------------------------
  服务关掉之后再调：状态 502
  返回：upstream connect failed: 由于目标计算机积极拒绝，无法连接。 (os erro…
  502 是本机代理转出来的；没有代理的环境里会是连接被拒。两种都是「链停在这儿」。
  所以插件后面要有一条兜底支路：解析失败就让用户手动粘字幕。

①第一段两份插件描述，各带一个必填参数，五项校验全过。 ②第二段解析真调：状态 200，拿回 5 个字段——video_id 在里面。 ③字幕真调：状态 200，六条，第一条就是「很多人学英语…开不了口」。 ④中文参数那段是本节第一坑：不 quote 直接拼 URL，请求会失败。 ⑤第三段少传 video_id，接口照样回 200 和六条字幕——这是本节最该记住的一条。

30 秒实验

1. 把你的插件参数值手动 quote 一遍再发。没编过码的，先试一次不编码，看报什么。
2. 故意少传一个必填参数，看你的接口回什么。回 200 的，说明你在下游必须判空。
3. 给提炼节点的提示词补上输出格式：一行一句、不要编号、最多三行。

常见误区

1. 「参数直接拼上去就行。」中文、空格、井号都会让请求失败，井号最致命。
2. 「接口回 200 就是对的。」少传参数也可能回 200，返回空数据。必须判空。
3. 「插件描述随便写。」智能体判断该不该调这个插件，看的就是这句描述。

六个节点配完，下一节挂到智能体上测。测的不是链，是「该不该调」。

• ☐ （本篇完，下一篇 10.4 智能体测试）

相关笔记

• 开发自定义插件案例：查询股票价格：接口描述怎么写
• 编写有效提示词的技巧：提示词里的输出格式
• 配置【信息提取】节点：上一个案例的节点配置
• 🐦 扣子开发 AI Agent · 索引