Agent/examples/process_pipeline/script/search_eval/procedure-dsl/spec-back

工序提取 SKILL · 总览

这道 skill 做一件事:读一篇 AI 创作教程/案例,把它背后的"做法"还原成一张工序表,存成 workflow.json,再渲染成一个网页。

三块内容:概念速览(本文下面)+ 格式说明(format/workflow-format.md,workflow.json 每个字段怎么填)+ 操作流程(子目录 extraction/,分三阶段一步步做)。

⚠ 路径提示:概念速览在本文,字段/格式在 spec/format/workflow-format.md,操作流程在 spec/extraction/。没有 syntax.md/fields.md/control-flow.md 这些文件(都已并进 workflow-format.md)。

---

本目录是一个自包含的 skill:跑提取流程时需要的所有说明都在这里。外部的案例原文(input/case-N-raw.json)和你产出的成果(outputs/case-N/)不算 skill 的一部分。

输入 / 输出

输入:任意一篇创作案例——公众号 / 小红书 / 推文 / 博客(正文 + 配图)、视频教程(带转写)、或你自己的工作复盘。

输出:一个网页 outputs/case-{N}/case-{N}-<slug>.html(按 format/workflow-format.md 的工序表规范渲染)。注:纯文本版 .md 已取消,只出网页。

---

概念速览(这是个什么东西)

读懂这几条,就能看懂工序表在表达什么。

工序表把"一步操作"拆成 5 个层面(对应 workflow.json 里的字段):

层面	通俗讲	在 workflow.json 里
数据类型	这份数据算什么角色(参考图/提示词…)	输入输出的 type
用的工具	哪个具体产品(manus/nano_banana…)	步骤的 via
做的动作	干了什么(生成/反推…)	步骤的 action
工序模板	一整套可复用的做法	一个 procedure
实际内容	这次具体填进去的真实值	输入输出的 value

一篇案例可以有多个工序:比如一篇文章同时讲"简单做法"和"进阶做法",那就是两个工序,放在顶层 procedures: [] 数组里(只有一个时也用长度 1 的数组)。

自造的类型要"挂靠":类型词表里没有的词,要在这个工序的 type_registry 里写明它"算作"哪个标准词,例如 主角图 挂靠 参考图。这样既能自由起名,又不弄乱标准词表。

命名约定:类型名、动作名用中文;工具品牌名用英文(nano_banana_pro);每个输出都要有不重复的编号(如 s2o1)供后面引用。其中"作用 / 实质 / 形式 / 动作"是整步一个,"类型 / 值 / 来源 / 编号"是每个输入输出各一个。

后文出现的简称:作用 = effect.json、动作 = action.json、类型 = type.json 这三张分类词表(完整词条以这三个文件为准)。

---

目录里有什么

操作流程(extraction/ —— 分三阶段,按阶段读)

文件	内容	什么时候读
format/workflow-format.md	格式说明:每个字段怎么填(原 fields + control-flow 已并入)	第一阶段起手
extraction/phase1-skeleton.md	第一阶段:搭骨架(判断有几个工序 / 切步骤 / 连数据流)	第一阶段
extraction/phase2-normalize.md	第二阶段:归类标注(分两个子助手并行干)	第二阶段
extraction/phase3-finalize.md	第三阶段:检查 + 渲染出网页	第三阶段

格式与契约(format/)

文件	内容
workflow-format.md	给人看的格式说明(顶层结构 + 14 个字段 + 控制流 + 命名 + 校验;三阶段都依据)
case-data.schema.json	给机器看的字段清单(必填项/可选值的最终裁判)

分类词表(taxonomy/ —— 标注用的受控词表)

文件	维度	规模	谁来读
taxonomy/README.md	—	—	只给子助手读(主流程不碰)
effect.json	作用	9 个词	只由 phase-2a-normalizer 子助手读
action.json	动作	30+ 个词	同上
type.json	类型	50 个词	同上;自造类型写进 workflow.json 的 type_registry
type_suggestions.md	新类型登记	只增不改	第三阶段跑 lint-case.py 时工具自动登记,不用手写
分类库导出_实质_*.json	实质	911 条	只由 phase-2b-matcher 子助手用脚本现查
分类库导出_形式_*.json	形式	565 条	同上

⚠ 主流程别碰词表:上面这些大词表和查询脚本只给子助手用。主流程从头到尾不要直接读它们,也不要自己调 taxonomy-lookup.py——主流程只负责"切任务 + 派给子助手"。这样才不会把主流程的上下文撑爆。

子助手定义(agents/ —— 第二阶段的两个并行助手)

文件	角色
agents/phase-2a-normalizer.md	把"作用/动作/类型"归类到标准词
agents/phase-2b-matcher.md	把"实质/形式"匹配到大词表里的路径

这两个文件的正文就是子助手的完整工作方法(唯一出处)。运行器(run_procedure_dsl.py)启动时自动加载它们,主流程不用读——主流程只管"召唤",方法由运行器装进子助手。extraction/phase2-normalize.md 只讲第二阶段怎么编排(切任务/派活/收结果),不重复这里的方法。

模板 与 工具(templates/ + tools/)

• templates/workflow.template.json:workflow.json 的填空骨架,复制一份改即可。
• tools.md:各脚本(查词表 / 批量改 / 渲染 / 检查)的接口手册。脚本本身不用读源码,会用就行;渲染网页的样式(renderer.py/styles.css/script.js)也不用碰。

---

操作流程(给执行者的手册)

整个流程围绕一个文件 workflow.json 滚动演化——从第一阶段搭好骨架,后面每阶段都在它上面就地补字段,不另存新文件。

第一阶段 · 搭骨架 ── 主流程全程在场
   1.1 读懂案例, 判断有几个工序   → understanding.md
   1.2 切步骤 + 填单步骨架        → 写出 workflow.json
   1.3 把步骤间的数据流连起来      → 改 workflow.json(补"来源/去处")
第二阶段 · 归类标注 ── 派两个子助手并行干, 都改同一个 workflow.json
   2A 作用/动作/类型 归类(查分类词表)
   2B 实质/形式 匹配(查大词表)
   2C 自造类型登记 → 写进 type_registry
第三阶段 · 检查收尾 ── 主流程调脚本
   3.1 填"目的"列 + 渲染出网页
   3.2 跑检查(类型完整性等)

起手(只做一次)

把本文读一遍,之后别再回头读它——需要某阶段细节时直接读对应的阶段文件。再把 tools.md 读一遍(后面要调的脚本接口都在那),也别重读。

重要:读过的文件别重复读

上下文是累积的,你读过的文件内容会一直留在记忆里。不要因为某处写了"详见 tools.md"就又去读一遍 tools.md;不要进了第二阶段又去重读阶段文件。需要时从记忆里翻,别重复 Read——那会白白浪费预算。

第一阶段 · 搭骨架(新读这些)

要做的事:通读案例 → 想清楚有几个工序、每个工序怎么走 → 切步骤 → 填骨架 → 把数据流连起来。

该读(还没读过的)	干嘛用
format/workflow-format.md	格式说明:14 个字段怎么填 + 控制流 + 命名 + 推断补全
extraction/phase1-skeleton.md	第一阶段具体怎么做
input/case-{N}-raw.json	案例原文(你的素材)

产物(写到 outputs/case-{N}/):understanding.md(想清楚有几个工序)+ workflow.json(先 Write 骨架,再 Edit 补"来源/去处")。 过关条件:workflow.json 自查通过(数据流都连上了、类型一致)→ 进第二阶段。

第二阶段 · 归类标注(新读这些)

要做的事:把"作用/动作/类型"归到分类词表的标准词,把"实质/形式"匹配到大词表的路径。

新读	干嘛用
extraction/phase2-normalize.md	第二阶段怎么切任务、派子助手
taxonomy/effect.json / action.json / type.json	三张分类词表(子助手读)
taxonomy/type_suggestions.md	新类型登记格式(看一眼即可)

别读:已读过的第一阶段清单;以及那两张超大词表 分类库导出_*.json(太大,走 taxonomy-lookup.py 现查)。

产物:在 workflow.json 上 Edit 补 作用/动作/类型 + 实质/形式 + 自造类型登记。不要另存新文件。 过关条件:每步的作用/动作都命中标准词、每步的实质/形式都校验通过 → 进第三阶段。

第三阶段 · 检查 + 渲染(新读这些)

要做的事:填"目的"列 → 跑检查 → 渲染出网页(脚本自动组装,不另存中间文件)。

新读	干嘛用
extraction/phase3-finalize.md	检查清单 + "目的"列怎么填
format/case-data.schema.json	字段的机器清单(最终裁判)

(格式说明 workflow-format.md 第一阶段已读过,不用重读。)

脚本命令:

# 1. 检查 + 自动登记新类型(轻量, 不卡流程)
python spec/tools/lint-case.py --workflow outputs/case-{N}/workflow.json --case-id {N}

# 2. 渲染网页(脚本在内存里组装好数据直接出 HTML)
python spec/tools/render-case.py \
    --workflow outputs/case-{N}/workflow.json \
    --source-input input/case-{N}-raw.json \
    --page-title "Case {N} · <主题>" \
    --case-id {N} \
    --out outputs/case-{N}/case-{N}-<slug>.html

产物:outputs/case-{N}/case-{N}-<slug>.html(唯一产物)。

每次 Read 前自查

• 这个文件之前读过吗?读过就别再读。
• 只想确认"提没提过某概念"?用 Grep,别整篇 Read。
• 只想看"目录里有啥"?用 Glob。
• 中断后接着做:用户可能改过的产物(understanding.md / workflow.json)要重读;spec 没变,不用重读。

卡住了怎么办

某阶段的过关条件过不去 → 别硬闯下一阶段,回当前阶段修。修两次还过不去 → 在产物里挂个 inferred: true, inferred_reason: "反复过不去, 需人工看" 标记,再往下走。