# Taxonomy · 字典树受控词表

本目录是 5 维标注体系 (作用 / 动作 / 类型 / 实质 / 形式) 的受控词表. 作用/动作/类型三棵小树**整树进 LLM context**; 实质/形式两个大词表走 `taxonomy-lookup.py` 按需查.

## 文件结构

```
taxonomy/
├── README.md           ← 本文件 (导航)
│
├── effect.json         ← 作用树 (制作 → 准备/加工/收尾阶段 → 叶子)
├── action.json         ← 动作树 (获取/提取/生成/修改/存储) + $control 控制流维
├── type.json           ← 类型树 (程序控制/数据复用/内容/知识 四大类)
├── feature.json        ← 特性 enum (随机/幂等/人工/本地/写外部/读外部)
│
├── type_suggestions.md ← 跨 case 累积的 case-specific 类型提案 (lint-case.py 自动 append)
│
├── 分类库导出_实质_*.json  ← 实质 大词表 (911 路径, 走 lookup 不进 context)
└── 分类库导出_形式_*.json  ← 形式 大词表 (565 路径, 同上)
```

## 结构约定 (新版)

作用/动作/类型三棵树用统一的**层级树结构** (键为中文): 每个节点是
`{分类名称, 分类说明, 直接元素, 子分类, 分类性质}`, 终端节点 (无 `子分类`) 即叶子.

- **`分类说明` 是边界判断的唯一来源** — 每个节点的判别口诀 / 与兄弟节点的边界 / 同义术语都写在这里.
- **`$leaves`**: 由 `最终分类树` 终端节点自动派生 (见 `scratch/build_taxonomy.py`), 供 `lint-case.py` 校验 + renderer 标 `in_tree`. **不要手改** — 改树后重新派生.
- 完整交互视图见 `阶段_动作_类型字典树.html` (可视化编辑器, 导出即本目录三个 JSON 的 `最终分类树`).

## 三棵树速查

| 树 | 维度 | 字段 | 顶层分类 | 叶子数 | 用在哪 |
|---|---|---|---|---:|---|
| [effect.json](effect.json) | 作用 | step `effect` | 制作 (准备/加工/收尾阶段) | **9** | Phase 2A 归一化 |
| [action.json](action.json) | 动作 | step `action` | 获取/提取/生成/修改/存储 (+5 control 正交维) | **30** + 5 control | Phase 2A 归一化 |
| [type.json](type.json) | 类型 | IO item `type` | 程序控制/数据复用/内容/知识 | **50** | Phase 2A 归一化 |

## 加载策略 (按规模分)

| 维度 | 文件 | 规模 | 怎么取值 |
|---|---|---:|---|
| 作用 / 动作 / 类型 | `effect/action/type.json` | 三棵共 ~小 | **整树进 LLM context** — Phase 2 直接 Read |
| 实质 | `分类库导出_实质_*.json` (1.1 MB) | 911 路径 | **走 `spec/tools/taxonomy-lookup.py` query** — 词表过大不进 context |
| 形式 | `分类库导出_形式_*.json` (764 KB) | 565 路径 | 同上 |

⚠ **Agent 不要直接 Read 实质 / 形式的 JSON** — 它们在 spec/ 内只是为了 skill 自包含 + 让 `taxonomy-lookup.py` 找得到. 整文件进 context 会吃 30k+ tokens. 走 funnel API (`--list-l2 / --subtree / --match / --validate`) 按需查.

## 使用约定

- **取值写法**: action 用根→叶完整路径 (`提取/化学提取/解构`); effect 和 type 直接写叶子名 (`预处理` / `参考图`), 因为叶子在各自树里全局唯一.
- **只终端叶子能作为取值** — 中间分类节点 (准备阶段 / 物理变化 / 素材 等) 是目录, 不直接取值.
- **case-specific 类型 (type 树独有)**: 允许用未在叶子里的名字, 但 `workflow.json` 的 `procedures[i].type_registry` 必须给 `extends` 指向某 stdlib 叶子 + `desc`, 否则 lint 报错.

## 三语言分工 (现状)

| 语言 | 负责 | 文件 |
|---|---|---|
| **JSON** | 结构 + 内容 (树 + 各节点 `分类说明` 边界定义) — 单一真理源 | `*.json` |
| **Python** | 程序性校验 (lint / 路径合法性 / extends 桥接) | `spec/tools/lint-case.py`, `taxonomy-lookup.py` |