# 工序提取 SKILL · 总览

> 这道 skill 做一件事:**读一篇 AI 创作教程/案例,把它背后的"做法"还原成一张工序表,存成 `workflow.json`,再渲染成一个网页**。
>
> 三块内容:**概念速览**(本文下面)+ **格式说明**([format/workflow-format.md](format/workflow-format.md),`workflow.json` 每个字段怎么填)+ **操作流程**(子目录 [`extraction/`](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](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](taxonomy/effect.json)、动作 = [action.json](taxonomy/action.json)、类型 = [type.json](taxonomy/type.json) 这三张分类词表(完整词条以这三个文件为准)。

---

## 目录里有什么

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

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

### 格式与契约(format/)

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

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

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

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

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

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

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

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

- [templates/workflow.template.json](templates/workflow.template.json):`workflow.json` 的填空骨架,复制一份改即可。
- [tools.md](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"就又去读一遍 tools.md;**不要**进了第二阶段又去重读阶段文件。需要时从记忆里翻,别重复 Read——那会白白浪费预算。

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

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

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

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

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

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

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

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

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

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

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

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

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

脚本命令:
```bash
# 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: "反复过不去, 需人工看"` 标记,再往下走。