Agent/examples/process_pipeline/script/search_eval/procedure-dsl/spec-back-1/extraction/phase1-skeleton.md

第一阶段 · 搭骨架

步骤

小步	做什么	产出
1.0 计划 (understanding)	先想清楚再动手：通读原文（含配图），把这篇拆成一份工序计划：(a) 有几条独立做法（几个工序）；(b) 每个工序的步骤序列逐条展开（每步：用什么工具·对什么输入·做什么动作·得什么输出，别压成单步，详细度见 §1.1）；(c) 每个工序覆盖原文哪些 0N 章节（原文每个章节都要被某个工序认领，别整段漏抽）。Cyber 引擎：调用一次 plan_procedures 工具把这份计划交上去——它校验完整性（有章节没认领→报错让你补；工序单步→警告），通过后自动据计划生成 workflow.json 骨架。其他引擎：把这份计划写进 understanding.md，再据它建骨架。	工序计划 + workflow.json（骨架版，结构按计划锁定）
1.1 填骨架	在已生成的骨架上填内容（别增删工序/步骤、别 write_file 重写整个 workflow.json）：逐步用 wf-patch.py 填每个输入/输出的 value（文字类用 @quote 拽完整逐字原文；提示词建成 type=提示词 的 IO value，别塞 directive，见下）。结构已按计划定死，你只补血肉。	workflow.json（填好 value）
1.3 连数据流	把数据流连起来 —— 给每个输入输出补上"来源/去处"：输入写 ← 上游某输出的编号（如 ← s2o1）、← 工序输入、← 某编号[i]（循环里逐个取）；输出写 → sN、→ 某列表.追加。连完自查：每个输入引用的编号都能在前面找到对应输出。连错就回改。几十处要连时用 wf-patch.py 一次过（见下），别写脚本硬塞。	workflow.json（补好"来源/去处"）
1.4 IO 校验（强制）	填完后、进 Phase 2 前，必须跑 python spec/tools/verify-io.py --workflow <wf> --source input/case-N.json --ocr <ocr>：它逐项校验 ①每个文本类 input/output 的 value、②每个生成步的 directive（提示词）是否在原文里逐字且完整（媒体类 IO 不要求对应；directive 改写/截断都会被点名）、③每个工序的 declarations（inputs/resources/returns）是否补全。报 ✗ 就回去修（此时可重新读原文；提示词用 @quote 把整段提全，别缩写/只取第一层），修完重跑直到通过。	workflow.json（文本 value/提示词逐字完整、declarations 补全）

---

workflow.json 整体结构

一个 workflow.json 描述一篇案例，里面可以有一个或多个工序（比如一篇文章同时讲了"简单做法"和"进阶做法"，那就是两个工序）。

{
  "source":     原帖信息,            # 平台/作者/日期/标题/摘要；正文和配图由 --source-input 自动补
  "procedures": [ 一个或多个工序 ]   # 只有一个工序时也用长度为 1 的数组
}
# page_title 不写进文件，由第三阶段 --page-title 命令传入

每个工序长这样：

{
  "id":           "p1",
  "name":         工序名字,
  "purpose":      一句话说明这个工序在做什么,
  "category":     类别（产物创造 / 资产建设 / 自动化 / 分析 / 学习）,
  "platform":     平台,  "author": 作者,
  "declarations": 这个工序需要哪些外部输入和长期资源，最后返回什么,
  "type_registry": 这个工序自己造的类型词（没有可不写），第二阶段归类时填,
  "steps":        [ 一步步的操作 ],
  "return_row":   表格最后一行，写明最终交付什么（可不写）
}

---

第一阶段要填的字段

每个工序填：id / name / purpose / category / platform / author / declarations / steps。

步骤级字段

字段	什么意思	怎么填	别这样
id	第几步	s1、s2；控制块子步用点号 s6.1	—
kind	步骤类型	普通步写 step；控制块用 block / nested（见下）	—
via	用了哪个具体工具/产品	写工具标准名：manus、nano_banana_pro、human（人工）；原文没点名就括号占位 (AI 生图工具)；控制块写 -	写一句话描述（那是 directive 的活）
directive	给工具的元指令（不是提示词本身）	只放"怎么用工具"的简短指示，如"严格反推，别发挥"、"比例 2:3"、"保持主角一致"；多数生图步留空即可	别把提示词原文塞这里——提示词是数据，归 type=提示词 的输入/输出 value（见下）

输入 / 输出的字段

字段	什么意思	怎么填	别这样
type	这份数据是什么角色（参考图？提示词？）	Phase 1 起个描述性标签即可（如 复刻图片、视觉风格分析），不必查词表、不校验；对到标准叶子 / type_registry 挂靠是 Phase 2 归类时做（那时才读 type.json）	Phase 1 就去查类型词表、注册 type_registry（那是 Phase 2 的活）
value	数据内容本身	文字类（提示词/JSON/报告/文案…）→ 填原文里那段的【完整逐字内容】：整段 prompt、整段 JSON 都要原样搬全，别缩写/概括/截断/凭记忆改写。推荐用 @quote\|<起锚>\|<止锚>（或 @quote\|<关键词> 落 JSON 块）标记 + wf-patch --resolve-quotes 让工具把那整段从原文/OCR 逐字回填——长内容你只写两个短锚点，不用手抄。图片/视频用尖括号写具体描述 <一张穿冲锋衣的登山者暴雨场景图>	把整段 prompt/JSON 缩成一句概括；写"见上一步"引用；写"参考图"这种笼统空壳
anchor	来源 / 去处	输入写来源：← 工序输入、← s2o1、← s2o1[i]（循环逐个取）；输出写去处：→ s7、→ 某列表.追加、→ 返回 X	在这里描述内容（那是 value 的活）
id（输出专属）	输出的编号	工序内唯一，如 s2o1；只有一个输出时 s2 也行	重复编号

🔑 提示词是数据，不是指令——建成 type=提示词 的 IO（这是最容易建错的地方）。标准范式（对齐参考实现）：

• 一个 human「写提示词」步：输入 type=描述（用户的需求阐述）→ 输出 type=提示词，value = 原文那段整段、逐字、完整的 prompt（所有分层/要素都要：主题+核心要素+输出要求，或视觉层+技术层+氛围层…别只取第一段）。
• 下游生成步（via=nano_banana 等）：输入 type=提示词（anchor: ← 上游那个提示词输出，value 同样填整段）→ 输出 type=样图/成品图。
• directive 留空（提示词不在这里）。原文没给详细 prompt 的步（如"生成符合调性的背景图"只一句），才在 value 写那一句或标 inferred。
• 第三阶段 verify-io.py 会检查：生成步必须有 type=提示词 输入、directive 里不准装提示词原文、提示词 value 不准截断——建错会被打回。

⚠ 值一定要写真实内容：哪怕某个输入就是上一步输出原样传过来的，"值"里也要把内容完整抄一遍，不能写"（同上）""见 s2o1"。嫌麻烦的话：只在源头填一次真内容，其余地方把"来源"写对，然后跑一次 wf-patch.py --resolve-passthrough，它会顺着编号自动把内容抄过去。

输入不用编号——没人会反过来引用一个输入。

命名约定

• 类型名用中文；工具品牌名用英文标准写法（seedream_4_5，不要写成 ByteDance-Seedream-4.5）。
• 每个输出都要有编号（工序内不重复），供后续步骤按编号引用。
• 自造的类型要挂靠：在工序的 type_registry 里写明它"算作"哪个标准词 + 一句说明，例如 "主角图": {"extends": "参考图", "desc": "本案例的女主肖像"}。

---

1.1 怎么判断"有几个工序"

⚠ 跟原文的章节标题无关：不管原文把某段叫"案例示范"还是"进阶玩法"，只要满足下面三条，就算一条独立工序。判断的单位是"一条完整的 输入→最终产物 链"，不是原文的段落结构。

怎么扫：以原文里每一张出现的成品图（或明确写出的最终产物）为起点，逐个看它有没有对应的"输入→做法"链条。有就记为一个候选工序，再用下面三条筛。别按段落扫。

🔒 扫完做一次「章节覆盖」交叉核对（结构强制，防整段漏抽）：原文常按 01 | … 02 | … 03 | 分章。逐章节过一遍，确认每个章节的核心内容都落进了某个工序或它的某个步骤。"按成品图扫"最容易漏掉没有独立成品图的方法论/框架章节（如"结构化 Prompt 框架""更多案例欣赏"）——这种章节本身就是一条工序（讲一套做法）或要拆成多个子步骤，不能因为它没配一张独立成品图就跳过。核对结论简记成"章节 0N → 工序 pX / 步骤 sY"对照；有章节对不上任何工序，回去补。Phase 3 lint-case.py --source 会按章节覆盖率把漏抽的章节抓出来，到时还得回这一步补，不如一次做全。

1. 有明确产物：这条链能产出一个看得见的结果（图、素材、成品）。
2. 有具体做法：链条里有可操作的方法（提示词、框架、流程）。
3. 产物或做法有差异：跟别的工序比，产物不同 或 做法不同，满足一条即可。哪怕产物类型一样（都是场景图），只要提示词不同，就算两个工序，不能合并。

边界判断：

• 同一条链内部的中间步骤，归进这条工序，不单拆（比如做海报时先生成背景图，背景图是中间步骤，不是独立工序）。
• 只展示了成品、完全没讲输入和做法的，不算工序。
• 产物类似但做法不同 → 算两个工序。不能因为"产物类型相同""方法论相似"就合并。

1.1 计划（understanding）要想清楚到什么程度——这就是你交给 plan_procedures 的内容

下面这些就是 §1.0 那份"计划"的全部内容——它直接决定 workflow.json 切几个工序、每工序几步。想得越细，workflow 步骤越完整，别压成单步。核心是第 3、4、6 条（多工序判断 + 每工序逐步展开 + 章节认领），它们一对一变成 plan_procedures 的 procedures[]（每工序的 steps[] 四要素、source_sections）。Cyber 引擎把它作为工具参数交上去；其他引擎写进 understanding.md：

1. 原文信息：标题 / 来源平台 / 作者 / 发布时间。
2. 内容概述：2-4 句说清这篇在教什么、分几大板块（→ 工具的 summary）。
3. 多工序判断：以每个成品图 / 最终产物为起点列一张扫描表（产物 | 有无独立做法 | 有无完整 输入→输出 链 | 判断），最后给"共 N 个工序"的结论。
4. 每个工序一节，每节都要有：
   • 终态产物：这个工序最后交付什么（→ final_product）。
   • 工艺类型：产物创造 / 资产建设 / 自动化 / 分析 / 学习（→ category）。
   • 步骤逐条展开：不要只写"4 步"，要把每一步列出来，每步讲清「用什么工具 · 对什么输入 · 做什么动作 · 得到什么输出」（→ 每个 step 的 tool/input/does/output 四要素，input/output 写短标签会变成步骤的输入/输出 type；does 只是自由描述、不是 taxonomy 动作词）；有循环 / 并行的，点明"对每个 X 重复""同时跑 N 路"。
   • 关键工具：这个工序用到的具体工具 / 产品名。
   • 隐含工艺规约：原文没明说但工艺上必然存在的前置 / 约定（如"生成要带参考图""多模型并行降随机性"）——这是第二阶段补 inferred 输入的依据。
5. 关键发现：3-5 条这篇最值得记的方法论 / 工具选型 / 工序结构洞察。
6. 章节认领：原文每个 0N 章节，判断它归哪个工序（独立做法→单独工序；纯展示/补充→并进相邻工序）——每个章节都要被某工序的 source_sections 认领，这是工具卡"整段漏抽"的依据。最易漏：没有独立成品图的方法论/框架章节（如"结构化 Prompt 框架""更多案例"），它们也是工序，别因为没配成品图就跳过。

颗粒度对照：一步要写成"用豆包对〔题材思路〕生成〔剧本大纲+分集剧情+台词〕"这种程度（工具+输入+动作+输出俱全），而不是"写剧本"这种一个词。多步时各步侧重不同，别都写成一个模子。

1.2 哪些"没写出来"的要主动补

真实教程经常会省略一些理所当然的中间产物。比如某步要"自己写动作序列"，原文没提它得先有一张主角图当参考——但工艺上这张图必不可少。这种该有却没写出来的输入/输出，要主动补上并标注推断原因；某个字段实在判断不出就留空，不要硬编一个假的。

原文常省略的几类：

• 工具常识：生成模型一般要带模型/参数；召回要有检索依据；视频生成要有主角图/分镜图当参考。
• 前后对不上：下游用到了 X 但上游没产出 X → 是不是漏抽了？某个输出后面没人用 → 是不是漏了使用它的步骤？
• 工艺常识：短剧 = 分镜图 → 视频片段 → 拼接；建素材库 = 收集 + 入库 + 建索引。

补出来的输入输出标上 inferred: true 和原因（让后面复核），别悄悄塞进去：

{
  "type": "参考图",
  "value": "<一张主角肖像>",
  "anchor": "← s2o1",
  "inferred": true,
  "inferred_reason": "原文只说'自己写动作'，没提主角图；但写动作序列需要它当角色参考"
}

• ✅ 该补：工艺上必然需要的中间产物；原文用了复数（"这些素材库"）但只列了一个，把其余补全。
• ❌ 不用补：归一化分类（那是第二阶段的常规活）；只是把原文换个说法；原文细节确实没写全（那是信息缺失，不算"推断"）。
• ⚠ 推断标记只能加在步骤的输入/输出上，不要加在工序的 declarations 上（那里只收 type/name/desc 三个字段）。

1.2 有循环/并行/分支怎么切

原文里如果有"对每个 X 重复""同时做几个版本""分情况"，切步骤时要展开成控制块 + 子步，别硬压成一个步骤：

• 块本身（"kind": "block"）：via 写 -，块的输入输出表达"整个循环在做什么"。
• 块里的每一步（"kind": "nested"，并写上 "group": "块的编号"）：编号带点号（块是 s5，子步就是 s5.1），表达"每一次具体怎么做"。

{ "id":"s5", "kind":"block", "via":"-",
  "inputs": [{"type":"分镜脚本","value":"...","anchor":"← s4o1"}],
  "outputs":[{"id":"s5o1","type":"分镜图列表","value":"...","anchor":"→ s6"}] }
{ "id":"s5.1", "kind":"nested", "group":"s5",
  "via":"nano_banana", "directive":"按场景提示词生成，保持主角一致",
  "inputs": [{"type":"提示词","value":"...","anchor":"← s4o1[i]"},
             {"type":"参考图","value":"...","anchor":"← s5o1[-1]"}],
  "outputs":[{"id":"s5.1o1","type":"分镜图","value":"...","anchor":"→ 分镜图列表.追加"}] }

• 循环里取数据：来源写 ← s4o1[i]（逐个取）、← s5o1[-1]（取上一次的产出，做"接力"参考）。
• 往列表里攒结果：去处写 → 分镜图列表.追加。
• 一步产出好几样东西：就写好几个输出（每个都有自己的编号），别合并成一个。
• 抽样、重试这类小修饰，直接写进 directive 里说明即可。

1.3 连数据流时自查这几条

• 每个输入的"来源"（← 某编号）都能找到已存在的输出编号，或是 ← 工序输入、字面量。
• 输入的类型，和它"来源"指向的那个输出的类型一致。
• 循环索引用在合理位置（[i] 在循环里，[-1] 指最近一项）。
• 接力/链式引用关系正确。
• 逐个输入/输出按模态查 value：文本类（提示词/数据/报告，或 type_registry 挂靠到它们的 case 类型）必须填从原文匹配到的【完整逐字内容】——整段 prompt / 整段 JSON 都要原样搬全，别概括、别截断、别只填一句（用 @quote|<起锚>|<止锚> 框出整段 + wf-patch --resolve-quotes 让工具从原文/OCR 逐字回填，长内容你只写两个短锚点）；原文确实没有 → value 写成 <占位>(原文未提供)（或标 inferred: true + 原因）；媒体类（图/视频/音频）用 <具体描述>。
  • 🔒 值强制（防"开头逐字后就缩写"）：一段真·逐字 value 应该是原文里一整段连续文本。最常见的偷懒是抄了开头第一句、后面用原文小标题拼盘——比如原文提示词是「主题：…登山者…。人物：一名年轻的登山者，表情坚毅…。产品：…水珠滚落…压胶细节…。环境：…乌云密布…」整整 ~350 字，却写成「主题：…登山者…。核心要素：人物、产品、环境、视觉风格」。后半「人物、产品、环境…」这些词单看都在原文里，但连起来不是任何一段原文——逐字细节全丢了。这种必须用 @quote|主题|<止锚> 把整段拽进来。Phase 3 lint-case.py --source 会算"最长连续命中原文"比例，<80% 判缩写并报出，到时还得回来用 @quote 重填。
  • ⚠️ 第三阶段 render-case.py 对文本类 <占位> value 会直接拒绝出 HTML——必须回填真内容、或标「原文未提供」/inferred 才放行（媒体描述不受限）。

1.3 怎么批量连（重要）

workflow.json 由你直接演化，绝不写 Python 脚本去生成/批改它（脚本拼 JSON 容易踩转义坑、把文件弄坏）。几十处"来源/去处"用 wf-patch.py 一次搞定：

1. 把要改的清单写到 _scratch/anchors.json —— [{"path":"p1.s1.inputs[0].anchor","value":"← s0o1"}, ...]，每条都是你的判断（连到哪个编号是语义决定，不是机械套用）；
2. 跑 python spec/tools/wf-patch.py --workflow workflow.json --patch _scratch/anchors.json。

工具负责安全写 JSON + 检查格式（有一条不合法就整批不写），你从不直接碰 JSON 文本。零星单处改，用 Edit 就行。路径写法见 tools.md。

1.3 内容自动抄写

"来源"连好后，跑一次 python spec/tools/wf-patch.py --workflow workflow.json --resolve-passthrough。对那些"原样接收上游输出"的输入（来源是 ← 某编号），你不用手抄上游内容——只在源头那个输出里填一次真内容，工具会顺着编号把它逐字抄到所有引用处（"值"先留空即可）。别把"（同上）"这种引用当最终内容留着（检查会报）。

输出格式要求

Cyber 引擎：骨架由 plan_procedures 工具自动生成，你不用手建——工具按你的计划把 procedures/steps（含 id、via、输入/输出 type 标签）都搭好了，你只在它上面用 wf-patch.py 填 value/directive/anchor。下面模板只是让你看清生成出来的结构长什么样。

其他引擎（无 plan 工具时）用 wf-patch.py --create 建骨架：把下面模板里要填的字段写成扁平 [{"path":...,"value":...}] 清单（如 p1.s1.inputs[0].type / p1.s1.outputs[0].anchor），一条 --create --patch 命令拼成合法 JSON（缺的 procedure/step/IO 自动建、output 的 id 自动补；见 tools.md §1）——扁平清单好写、不会漏逗号崩 JSON。下面模板供参考结构，也可直接复制 Write（但手写长嵌套 JSON 易出错）。

{
  "source": {
    "platform": "<填:原文平台 e.g. wechat-gzh>",
    "author":   "<填:原文作者>",
    "date":     "<填:发布日期 e.g. 2026 上半年>",
    "url":      "<填:原文 URL>",
    "title":    "<填:原文标题>",
    "excerpt":  "<填:摘要 1-3 句>"
  },
  "procedures": [
    {
      "id":       "p1",
      "name":     "<填:工序名 e.g. 产品场景图生成>",
      "purpose":  "<填:一句话目的>",
      "category": "<填:产物创造|资产建设|自动化|分析|学习>",
      "platform": "<填:平台>",
      "author":   "<填:作者>",
      "declarations": {
        "inputs":    [{ "type": "<填:类型>", "name": "<填:声明名>", "desc": "<填:说明 (可选)>" }],
        "resources": [],
        "returns":   { "type": "<填:返回类型>" }
      },
      "steps": [
        {
          "id":        "s1",
          "kind":      "step",
          "via":       "<填:工具名 e.g. human / nano_banana / (AI 生图工具)>",
          "directive": "<填:给工具的 prompt 文本 (可选；人工/控制流步留空)>",
          "inputs": [
            {
              "type":   "<填:类型>",
              "value":  "<填:数据内容本身>",
              "anchor": "<填:← 工序输入 / ← s1o1>"
            }
          ],
          "outputs": [
            {
              "id":     "s1o1",
              "type":   "<填:类型>",
              "value":  "<填:数据内容本身>",
              "anchor": "<填:→ s2 / → 返回 X>"
            }
          ]
        }
      ]
    }
  ]
}

有循环 / 并行 / 分支时，用控制块写法（无则不需要）：

{
  "id":   "s1",
  "kind": "block",
  "via":  "-",
  "inputs":  [{ "type": "<填:类型>", "value": "<填>", "anchor": "<填:← 上游 id>" }],
  "outputs": [{ "id": "s1o1", "type": "<填:类型>", "value": "<填:累积结果>", "anchor": "<填:→ sN>" }]
},
{
  "id":    "s1.1",
  "kind":  "nested",
  "group": "s1",
  "via":       "<填:工具名>",
  "directive": "<填:给工具的 prompt (可选)>",
  "inputs":  [{ "type": "<填:类型>", "value": "<填>", "anchor": "<填:← 被遍历序列 id[i]>" }],
  "outputs": [{ "id": "s1.1o1", "type": "<填:类型>", "value": "<填:单次产出>", "anchor": "<填:→ 累积结果.追加>" }]
}