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

Procedure DSL · 语法 + 提取 SKILL

Procedure DSL 的语法 reference 和从原始 case 提取的操作 SKILL。

两部分: 语法定义 (顶层 syntax.md, 干货不论证) + 提取流程 (子目录 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 §11 结构)
• .html — 可视化 (按 format/procedure-table.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)	§6

提取 SKILL (extraction/)

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

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

Output · 产物规约 (format/)

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

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

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

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

文件	维度	规模	Agent 加载方式
taxonomy/README.md	—	—	Phase 2 起手读一遍
effect.json	作用	9 叶子 (制作 → 准备/加工/收尾阶段)	整树进 LLM context (Phase 2 Read)
action.json	动作	30 叶子 + 5 control	同上
type.json	类型	50 叶子 (程序控制/数据复用/内容/知识 四大类)	同上. 每节点含 分类说明 (边界/同义词); case-specific 类型走 workflow.json 的 procedures[i].type_registry (extends 一个叶子, Agent 写)
type_suggestions.md	类型升级提案	append-only	Agent 走 §2A 候选→extends 桥接时 append, spec 维护者审阅决定升级到 type.json
taxonomy/分类库导出_实质_*.json	实质	911 路径 (1.1 MB)	走 spec/tools/taxonomy-lookup.py query — 整文件不进 context
taxonomy/分类库导出_形式_*.json	形式	565 路径 (764 KB)	同上

⚠ 实质/形式 JSON 不要直接 Read — 大词表 bundled 在这只是为让 taxonomy-lookup.py 找得到. 整文件进 context 会吃 30k+ tokens. Phase 2 2B 子 Agent 走 tool funnel API (--list-l2 / --subtree / --match / --validate).

Templates · 渲染模板 (templates/)

文件	用途
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/)

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

工具	用途
tools/taxonomy-lookup.py	实质/形式 词表查询 (阶段二 2B 用)
tools/render-case.py	case_data → HTML 渲染 + JSON Schema 校验 (阶段三用)
tools/renderer.py	render-case.py 内部 import 的渲染主模板 (Agent 不要 Read 源码, 通过 render-case.py 间接调用)
tools/styles.css + tools/script.js	renderer 注入到 HTML 的样式 + 交互. 视觉规范见 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 读一遍 — 你后续要调的外部脚本接口都在那, 之后不要重读.

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

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

必读 (尚未读过)	用途
syntax.md	DSL 概念模型 + 字段语义
extraction/fields.md	23 字段定义 + 推断补全标记 (三阶段共享)
extraction/control-flow.md	控制流 → block/nested 建模 (循环/并行/分支怎么表达, 必读 — 切片时就要会)
extraction/phase1-skeleton.md	阶段一执行 (1.1/1.2/1.3 骨架提取 + 多工序判断)
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	阶段二 2A + 2B 执行细节
taxonomy/effect.json	作用树 + 边界判断 (节点 分类说明)
taxonomy/action.json	动作树 + 边界判断 (节点 分类说明)
taxonomy/type.json	类型树 + 边界判断 (节点 分类说明)
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	lint 清单 + 目的列填法
format/procedure-table.md	工序表创作规范 (字段语义 + intent + chip 视觉 + 审美)
format/case-data.schema.json	workflow.json 的契约 (顶层 procedures 数组, 每 procedure 含 declarations/steps/type_registry)

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

工具调用:

# 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 (已读), 不要去 Read 脚本源码

转移失败处理

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