# Procedure DSL · 语法 + 提取 SKILL

> Procedure DSL 的语法 reference 和从原始 case 提取的操作 SKILL。
>
> 两部分: **语法定义** (顶层 [`syntax.md`](syntax.md), 干货不论证) + **提取流程** (子目录 [`extraction/`](extraction/), 三阶段操作步骤)。
>
> 本目录各文件完整自洽; 需要 .md 样板时参考 `outputs/` 下已产出的 case-*.md。
>
> ⚠ **路径提示**: 语法在 `spec/syntax.md` 顶层文件 (不在 `spec/part1-syntax/`!), 提取流程在 `spec/extraction/` 子目录. 没有 `part1-` / `part2-` 这种命名 — 不要脑补对称目录.

---

**本目录 = 一个自包含 skill**: Agent 跑提取流程时, **所有 spec 信息都在本目录内**. 外部 case 数据 (`input/case-N-raw.json`) 和工作产物 (`outputs/case-N/`) 由 Agent 各自读写, 不算 spec.

## 输入 / 输出

**输入** — 任一原始 case 素材: 公众号 / 小红书 / 推文 / 博客 (正文 + 配图)、视频教程 (含转写)、自己的工作回顾。

**输出** (两份, 路径 `outputs/case-{N}/case-{N}-<slug>.{md,html}`):
- `.md` — DSL 文本版 (按 [format/md-structure.md](format/md-structure.md) §11 结构)
- `.html` — 可视化 (按 [format/procedure-table.md](format/procedure-table.md) 工序表规范)

## 章节地图

### 概念模型 ([syntax.md](syntax.md))

DSL 的**概念模型 + 字段语义速览** (Phase 1 一次性加载). 不含逐构造的文本语法 —— 产物是 workflow.json + HTML, 不手写 DSL 文本.

| 内容 | § |
|---|---|
| 5 层架构 (L0 类型库 / L1 外部函数 / L2 抽象动作 / L3 工序模板 / L4 工序实例) + workflow.json 字段映射 | §1 |
| 类型系统 (字典树叶子命名 + case-specific extends; 实质/形式 挂 IO item) | §2 |
| 动作模型 (`via / action / feature / control / effect` 五字段) | §3 |
| 工序结构 (L3 模板 = procedure; L4 实例 = 实际值回填) | §4 |
| 命名规范 | §5 |
| 标注速览 (step + IO 字段, 详见 [extraction/fields.md](extraction/fields.md)) | §6 |

### 提取 SKILL ([extraction/](extraction/))

从 case 原文到 DSL + 可视化的提取流程. 按 phase 加载.

| 文件 | 内容 | 加载时机 |
|---|---|---|
| [extraction/fields.md](extraction/fields.md) | 23 字段定义 + 推断补全标记 (三阶段共享) | Phase 1 起手 |
| [extraction/control-flow.md](extraction/control-flow.md) | 控制流 → block/nested 结构建模 (循环/并行/分支怎么不拍平) | Phase 1 |
| [extraction/phase1-skeleton.md](extraction/phase1-skeleton.md) | 阶段一执行 (1.1/1.2/1.3 骨架提取 + 多工序判断) | Phase 1 |
| [extraction/phase2-normalize.md](extraction/phase2-normalize.md) | 阶段二归一化与标注 (fan-out 2A / 2B 子 Agent) | Phase 2 |
| [extraction/phase3-finalize.md](extraction/phase3-finalize.md) | 阶段三检查收尾 (lint + 目的列 + 落盘) | Phase 3 |

### Output · 产物规约 ([format/](format/))

`.md` 和 `.html` 两种产物的固定结构 + 数据契约.

| 文件 | 内容 |
|---|---|
| [md-structure.md](format/md-structure.md) | .md 输出固定章节 (工序梗概 / 引用类型 / L1-L4 / 关键启发) |
| [procedure-table.md](format/procedure-table.md) | 工序表创作规范 (23 列字段语义 + intent token 规则 + chip 视觉 + 审美约束) |
| [case-data.schema.json](format/case-data.schema.json) | `render-case.py` 的输入 JSON Schema (Draft 2020-12) |

### Taxonomy · 字典树受控词表 ([taxonomy/](taxonomy/))

5 维标注体系 (作用 / 动作 / 类型 / 实质 / 形式) 全部 bundled 在本目录, skill 自包含.

| 文件 | 维度 | 规模 | Agent 加载方式 |
|---|---|---:|---|
| [taxonomy/README.md](taxonomy/README.md) | — | — | **仅子 Agent 读取**（主 Agent 绝对禁止加载） |
| [effect.json](taxonomy/effect.json) | 作用 | 9 叶子 | **仅 `phase-2a-normalizer` 自动加载并读取**（主 Agent 绝不加载，以维持极简 Context） |
| [action.json](taxonomy/action.json) | 动作 | 30 叶子 + 5 control | 同上 |
| [type.json](taxonomy/type.json) | 类型 | 50 叶子 | 同上。每节点含 `分类说明`；case-specific 类型自动写入 `workflow.json` 的 `type_registry` |
| [type_suggestions.md](taxonomy/type_suggestions.md) | 类型升级提案 | append-only | 阶段三跑 `lint-case.py` 时**由工具自动同步 append**，Agent 无需手工编辑 |
| `taxonomy/分类库导出_实质_*.json` | 实质 | 911 路径 | **仅由 `phase-2b-matcher` 内部通过脚本查询**（主 Agent 绝不读取和查询） |
| `taxonomy/分类库导出_形式_*.json` | 形式 | 565 路径 | 同上 |

> ⚠ **主 Agent 绝对隔离原则**：上述所有分类树文件和查询脚本均**只对子 Agent 开放**。主 Agent 在整个流程中**绝对不要直接 Read 它们，也绝对不要直接调用 `taxonomy-lookup.py`**！主 Agent 唯一的职责是运行物理切片脚本 `prepare-subtask.py` 并分发 `Agent` 任务，以此彻底杜绝主 Agent 发生 Context 膨胀或违背隔离架构手动通关。

### Templates · 渲染模板 ([templates/](templates/))

| 文件 | 用途 |
|---|---|
| [templates/workflow.template.json](templates/workflow.template.json) | `workflow.json` 填充骨架 (多工序 `procedures:[]`). 复制到 `outputs/case-{N}/workflow.json` 后填 `<填:...>` 占位符, 各 phase in-place Edit, Phase 3 跑 `spec/tools/render-case.py --workflow` 校验+渲染 |

### Tools · 工具脚本 ([tools/](tools/))

Agent 跑提取时**通过 Bash 调用**的脚本. **Agent 不需要 Read 这些脚本源代码**, 接口手册见 [tools.md](tools.md).

| 工具 | 用途 |
|---|---|
| [tools/taxonomy-lookup.py](tools/taxonomy-lookup.py) | 实质/形式 词表查询 (阶段二 2B 用) |
| [tools/render-case.py](tools/render-case.py) | case_data → HTML 渲染 + JSON Schema 校验 (阶段三用) |
| [tools/renderer.py](tools/renderer.py) | render-case.py 内部 import 的渲染主模板 (**Agent 不要 Read 源码**, 通过 render-case.py 间接调用) |
| [tools/styles.css](tools/styles.css) + [tools/script.js](tools/script.js) | renderer 注入到 HTML 的样式 + 交互. 视觉规范见 [format/procedure-table.md](format/procedure-table.md), 实施以这两文件为准 |

---

## 三语言协作原则

本目录内不同类型内容按读者类型分语言:

| 语言 | 负责 | 文件示例 | 谁读 |
|---|---|---|---|
| **JSON** | 结构化定义 (字段 / 受控词表 / 树结构) | `taxonomy/*.json`, `format/case-data.schema.json` | 程序 + LLM (直接 import 当 context) |
| **Python** | 程序性校验 + 规则定义 (lint, 路径合法性) | `taxonomy/validate.py` (TBD), `tools/taxonomy-lookup.py` | 程序 + 程序员 |
| **Markdown** | 内容定义 (设计动机 / 边界判断 / 跨模块关系 / narrative) | 本目录绝大多数文件 | 人 + LLM (吸收 narrative context) |

数据流单向: JSON (ground truth) → Python (import + 加规则) → MD (人写, 解释 why). 不三方互改。

> 当前只有 `taxonomy/` 完全实施了三语言分工; `syntax.md` / `extraction/` / `format/` 是纯 markdown 规范, 内部尚未做 JSON/Python 抽离 — 这些内容主要是 prose, 没有需要程序消费的结构.

---

## Agent 自驱加载指南 (累积式)

> **本节是给 Agent 看的执行手册**. Agent 是 self-driven — 没有 Driver 显式切 phase, 按下面顺序自行加载 + 自行判断转移. 关键原则: **context 累积, 已读不要再读**.

**总览** (单一中间产物 `workflow.json`, Phase 1.2 起 in-place Edit 演化, 不写多个快照):

```
[阶段一] 骨架提取 ── 主 Agent 全程在场
           1.1 心智模型 (多工序判断)  → understanding.md
           1.2 步骤切片 + 单步骨架     → Write workflow.json
           1.3 跨步引用闭合 (anchor)   → Edit workflow.json
[阶段二] 归一化标注 ── fan-out 2 子 Agent, 都 Edit workflow.json
           2A 作用/动作/类型归一化 (字典树整进 context)
           2B 实质/形式 匹配 (走 taxonomy-lookup.py)
           2C case-specific type 注册 → procedures[i].type_registry
[阶段三] 检查收尾 ── 主 Agent 调脚本
           3.1 render-case.py --workflow → HTML
           3.2 lint-case.py --workflow   → type 完整性
           3.3 写 case-N-<slug>.md (md-structure §11)
```

### 起手 (只做一次)

读本 README **一遍**, 之后**永远不要再 Read 本文件**. 你需要 phase 细节时直接读 phase 对应的 spec 模块, 不要回来翻 README.

也请把 [`tools.md`](tools.md) 读一遍 — 你后续要调的外部脚本接口都在那, 之后**不要重读**。

### 🛑 绝对禁止重复读取 (ZERO REPEATED READS RULE)
由于 Context 是持续累积的，**你读取过的所有文件（README.md, tools.md, phase2-normalize.md 等）内容会永远保留在你的 Context 记忆中**。
请**绝对不要**再次调用 `Read` 读取它们！重复读取会导致巨大的 Token 浪费与回合预算超限。
- **严禁**：因为看到 spec 里写了 `详见 [tools.md §2]` 就去重复 `Read(file_path="spec/tools.md")`。
- **严禁**：因为进入了 Phase 2B 就去重复 `Read(file_path="spec/extraction/phase2-normalize.md")`。
- 检索你的前置 Turn 历史，直接从记忆中查找对应规格！

### Phase 1 · 骨架提取 (新增加载)

工作: 通读 case 原文 → 建立工序心智模型 → 切片 → 抽骨架 → 闭合引用.

| 必读 (尚未读过) | 用途 |
|---|---|
| [`syntax.md`](syntax.md) | DSL 概念模型 + 字段语义 |
| [`extraction/fields.md`](extraction/fields.md) | 23 字段定义 + 推断补全标记 (三阶段共享) |
| [`extraction/control-flow.md`](extraction/control-flow.md) | 控制流 → block/nested 建模 (循环/并行/分支怎么表达, **必读** — 切片时就要会) |
| [`extraction/phase1-skeleton.md`](extraction/phase1-skeleton.md) | 阶段一执行 (1.1/1.2/1.3 骨架提取 + 多工序判断) |
| [`format/md-structure.md`](format/md-structure.md) | .md 产物结构 (后面要按这个写) |
| `input/case-{N}-raw.json` (case 原文) | 你的工作素材 |

Phase 1 结束累积: **~30-50k context**

产物 (写到 `outputs/case-{N}/`):
- `understanding.md` (1.1 心智模型, 含多 procedures 判断)
- `workflow.json` (1.2 **Write** 骨架: 顶层 `procedures: [{id, name, purpose, declarations, steps}]`, 之后 1.3 **Edit** 加 anchor)

转移条件: workflow.json 自检通过 (引用闭合 / 命名归一 / 类型一致) → 进 Phase 2.

⚠ **新工作流**: 中间产物从原来"5 个 JSON 快照" → **1 个 workflow.json + understanding.md**. 各 phase 都 in-place Edit workflow.json (不写新文件). 减少冗余 + 降低 LLM 长 JSON 输出错误率.

### Phase 2 · 归一化 + 标注 (新增加载)

工作: 归一化 作用 / 动作 / 类型 (查字典树) + 实质 / 形式 (走 `spec/tools/taxonomy-lookup.py` 查外部词表).

| 新增 Read | 用途 |
|---|---|
| [`extraction/phase2-normalize.md`](extraction/phase2-normalize.md) | 阶段二 2A + 2B 执行细节 |
| [`taxonomy/effect.json`](taxonomy/effect.json) | 作用树 + 边界判断 (节点 `分类说明`) |
| [`taxonomy/action.json`](taxonomy/action.json) | 动作树 + 边界判断 (节点 `分类说明`) |
| [`taxonomy/type.json`](taxonomy/type.json) | 类型树 + 边界判断 (节点 `分类说明`) |
| [`taxonomy/type_suggestions.md`](taxonomy/type_suggestions.md) | 跨 case 累积的类型升级提案 (Read 一遍知道格式; 走 §2A 候选→extends 桥接时 **append** 一条) |

**不要 Read**:
- 已读: 全部 Phase 1 list (`syntax.md`, `extraction/fields.md`, `extraction/control-flow.md`, `extraction/phase1-skeleton.md`, `format/md-structure.md`, README, tools.md)
- 永远不要: `分类库导出_*.json` (词表太大, 走 `spec/tools/taxonomy-lookup.py` query — 接口见 tools.md)

Phase 2 结束累积: **~40-60k** (并行子 Agent 各自: 2A ~8-15k, 2B ~5-10k)

产物:
- `outputs/case-{N}/workflow.json` (**Edit** 加 effect/action/type/feature/control + substance/form + procedures[i].type_registry)

⚠ **不写新文件** — Phase 2 是 Read workflow.json + Edit 加字段 in-place. 不要 Write 重写整个 JSON.

转移条件: 每个 step 的 effect/action 命中字典树叶子 + 每个 IO item 的 substance/form 走 `spec/tools/taxonomy-lookup.py --validate` 通过 → 进 Phase 3.

### Phase 3 · 收尾 + 渲染 (新增加载)

工作: 跑 lint + 渲染 HTML (脚本自动) + 写 .md (Agent). renderer 内存组装 case_data 直接渲染, 不落盘中间 JSON.

| 新增 Read | 用途 |
|---|---|
| [`extraction/phase3-finalize.md`](extraction/phase3-finalize.md) | lint 清单 + 目的列填法 |
| [`format/procedure-table.md`](format/procedure-table.md) | 工序表创作规范 (字段语义 + intent + chip 视觉 + 审美) |
| [`format/case-data.schema.json`](format/case-data.schema.json) | workflow.json 的契约 (顶层 procedures 数组, 每 procedure 含 declarations/steps/type_registry) |

Phase 3 结束累积: **~50-78k**

工具调用:
```bash
# 1. lint + 自动 record 新 type (轻量, 不卡 exit)
python spec/tools/lint-case.py --workflow outputs/case-{N}/workflow.json --case-id {N}

# 2. 渲染 HTML (renderer 内存组装 case_data, 不落盘)
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>.md` (DSL 文本版, 你 Write)
- `outputs/case-{N}/case-{N}-<slug>.html` (跑 render-case.py --workflow 自动生成)

⚠ **Phase 3 不落盘中间 JSON** — renderer 在内存组装 case_data = workflow.json + source-input merge + page_title + case_id, 直接渲染.

### 自查清单 (每次 Read 前)

- [ ] 这个文件**之前读过吗**? 如果读过, 不要再 Read (context 累积, 重读浪费 5-15% budget)
- [ ] 我只是想确认某概念**有没有提过**? 用 Grep, 不要 Read 完整文件
- [ ] 我只是想看**目录里有啥**? 用 Glob, 不要 ls 后再 Read
- [ ] resume 后: 用户**改过**的产物 (understanding.md / workflow.json) **要重读**; spec 不变, 不要重读
- [ ] 想知道某外部脚本接口? 看 [`tools.md`](tools.md) (已读), 不要去 Read 脚本源码

### 转移失败处理

任一 phase 的转移条件不过 → **不要硬进下一 phase**. 回当前 phase 修产物再自查. 重做 2 次还过不去 → 在产物里挂 `inferred: true, inferred_reason: "lint 反复不过, 需人工审"` 标记, 再向下推进.