## 提取字段定义与标注约定 (三阶段共享)

> 本文是**跨阶段共享的字段引用** —— 每行 23 个字段的语义 + 推断补全标记约定。Phase 1 起手加载,之后累积在 context;phase2/3 填字段(effect/action/type/substance/form/intent)时都依据本表。各字段在哪个 phase 填,见 [README](../README.md) 加载指南。

### 推断补全标记 (重要)

抽取时, 主 Agent **必须补全自然语言中的逻辑疏漏** — 主要指**原文未列出但工艺必经的输入 / 输出**.

> 典型场景: 某一步实际需要中间产出 A 和 B, 但原始帖子只提到了 A; 抽取时要补出 B, 并显式标注它是推断来的.

> ⚠ **`inferred` / `inferred_reason` 只能标在 step 的 IO item 上 (`steps[].inputs/outputs[]`)**, **不要标在 `declarations.inputs/resources/returns` 上** —— schema 的 DeclareItem 是 `additionalProperties:false`, 只收 `type/name/desc`, 加 inferred 会校验失败. 工序级声明若是推断的, 把推断说明写进 `desc`, 或在对应的 step IO 上标 inferred.

**两种推断标记方式** (按粒度):

#### A. IO 级 (主要场景, 推荐) — 标在 IO item 上

整个 input / output item 是推断补全的 (源文本完全没列, 但工艺需要):

```python
{
    'id': 's5', 'kind': 'step',
    'via': 'human',
    'action': '生成/关系生成/数组生成',
    'inputs': [
        {
            'substance': '...', 'form': '...',
            'type': '参考图', 'name': '主角图',
            'value': '<AI 生成的人物肖像静态图: 中景特写, 年轻亚洲女性...>',
            'anchor': '← s2.主角图',
            'inferred': True,  # ← 整个 IO item 是推断的
            'inferred_reason': '原文方法 3 只说"自己写动作", 没明示主角图是输入; 但写动作序列需要主角图作角色 context, 属工艺补全',
        },
    ],
    # ...
}
```

#### B. field 级 (次要场景) — 标在 step.inferred_marks dict

某个字段值是推断的, 但所属 IO item 本身源文本已列出 (如工具名未指名只给 generic 占位):

```python
{
    'id': 's2',
    'via': '(AI 生图工具)',
    # ...
    'inferred_marks': {
        'via': '原文用"AI 生图"未指名具体工具',
    },
}
```

**field_key 命名规则** (IO 级用 `inferred: True` 标在 item 上即可, 不用 field_key):
- step 级字段: `'intent'` / `'effect'` / `'via'` / `'action'` / `'directive'` / `'config'` / `'decorator'` / `'memo'` / `'control'` / `'feature'`
- IO 子字段 (仅在需要标某个 IO item 中特定字段时, 如 inferred 整 item 太重): `'in-substance-N'` / `'in-form-N'` / `'in-type-N'` / `'in-name-N'` / `'in-value-N'` / `'in-anchor-N'` (out-)

#### C. 低置信度推断 — 留空 + 「推?」

整个 IO item 标了 `inferred: True`, 但某个字段判断不出 (原文无线索, 工艺也没有强约束), **不要硬编值**. 把该字段设为 `None` 或不填即可 — 渲染时该 cell 显示空 + `推?` 角标 (vs. 高置信度的 `推`), hover 仍显示 `inferred_reason`.

```python
{
    'id': 's7',
    'inputs': [
        {
            'substance': '/表象/视觉/...',
            'form': None,                       # ← 低置信: 形式不明, 留空
            'type': '参考图',
            'name': '主角图',
            'value': None,                      # ← 低置信: 值不明, 留空
            'anchor': '← s2.主角图',
            'inferred': True,
            'inferred_reason': '原文未说本步用什么参考; 可能是 s2 主角图也可能没用, 留空待人工确认',
        },
    ],
}
```

**渲染规则**: cell 显示 `空 + 推?` 当且仅当 `(item.inferred=True 或 field 在 inferred_marks 中)` **且** 字段值为 `None/''`. 填了值则仍是普通 `推`. 这给读者明确信号 — "AI 知道这里该有东西但选择不猜", 既不是数据缺失也不是高置信补全.

**何时用 C 而非 A**: A 是"原文没说但工艺必然" (高置信, 该补); C 是"原文没说且工艺也不必然" (低置信, 不该猜). 不确定就用 C, 不要为了消除"空 cell"硬填一个貌似合理的值.

**可视化效果** (spec/tools/renderer.py 自动渲染):
- 推断 cell 加「推」角标 (右上); 低置信留空的 cell 角标变成「推?」
- hover 角标显示推断理由 (tooltip), 高 / 低置信用同一个 `inferred_reason` 字段
- legend "高亮推断" 一键开关: body 加 `.show-inferred` 类, 所有推断 cell 加重底色 + 边框
- IO 级推断: 整行 6 个 cell 同时染色, 一眼看出"这条输入 / 输出是补出来的"

**何时标 vs 不标**:
- ✓ **标 A (IO 级, 高置信)**: 原文未列的中间产出输入 / 必然输出 (如 s5 写动作时需要主角图作 context, 源未说)
- ✓ **标 A (IO 级, 高置信)**: 源文本用了复数指代 ("这些知识库") 但具体列了一个, 补出其他的 (如 s4 加 人物库 + 运镜库)
- ✓ **标 B (field 级)**: 工具未指名只给 generic 描述 (`(AI 生图工具)`)
- ✓ **标 C (低置信留空)**: IO item 整体确定要标 inferred, 但内部某字段拿不准 — 留空比硬编更诚实
- ✗ **不标**: 归一化标注 (实质 / 形式 / 作用 / 动作 / 类型 映射到 taxonomy) — 这是 Phase 2 的常规工作, 不属于"逻辑疏漏补全"
- ✗ **不标**: 直接 paraphrase 原文 (原文已明示, 只是换了说法)
- ✗ **不标**: prompt 文本细节缺失但已尽力描述 (这是 content extraction limitation, 不是 logical 补全)

---

### 字段定义与提取指示 (canonical)

抽取每一行 23 个字段时, 严格按下表语义填. **字段语义被反复误用是抽取阶段最大坑**: 把步骤说明塞进 `指令`, 把工具账户事实塞进 `配置`, 把分析评论塞进 `备注`, 把来源引用塞进 `值` 等. 此表为权威定义.

#### 需求组 (3 列, 灰)

| 列 | 含义 | 取值来源 | 提取规则 | 反例 |
|---|---|---|---|---|
| **#** (idx) | 步骤编号 | 顺序生成 | `s1` / `s2` / `s6.1` (块下嵌套用点号) | — |
| **目的** (intent) | 这一步在做什么的简短自然语言句 | 该行其他 cells 的值 | 句中能 token 化的概念都做成 `{kind:value}` token (色底对应所引用的列, 见 procedure-table 目的列规则); 胶水文字 ≤ 8 字 | dataflow 公式; case-specific 简写 (锚/链); 变量名 token |
| **作用** (effect) | 这一步在 AIGC 工序链中的位置 + 角色 | §A.1 字典树叶子 | 主 Agent 选最贴近叶子 (预处理/主体生成/装配/后期/工艺规约 等) | 自造词; 把动作当作用 (反推 ≠ 作用) |

#### 数据流·输入 / 输出 (各 6 列, 黄 / 蓝, 输入输出**字段语义完全一致**)

| 列 | 含义 | 取值来源 | 提取规则 | 反例 |
|---|---|---|---|---|
| **实质** (substance) | 数据内容是什么 (理念 / 表象 层面) | 外部词表 `分类库导出_实质_*.json` | 找最匹配的叶子路径; 不命中叶子选高层抽象 | 自由文本; 非合法路径 |
| **形式** (form) | 内容怎么呈现 (呈现 / 架构 层面) | 外部词表 `分类库导出_形式_*.json` | 同上 | 同上 |
| **类型** (type) | 领域语义类型 (按功能角色分类) | §A.3 字典树叶子 或 case-specific extends | 命中叶子优先; 否则用 case extends 桥接 | 不在字典树且无 extends 桥接的自造名 |
| **变量名** (name) | 该步内的数据流标识 | case-specific 命名, 按内容含义起 | 同一概念在不同 step 必须用同一名 (lint: 命名归一) | 同名变量在不同 step 类型不一致 |
| **值** (value) | **数据本身的内容** | 原文 / 上下文中的实际数据 | 文本数据写完整 prose; **关于内容本身的提示词**（如具体的画面描述、场景风格、角色特征、服装细节等）作为数据本身内容，**必须**在此回填；非文本数据用 `<整段描述>` 包起 | 含 meta ("同 sX:" / "(从 X 切出)" / "供后续复用" / "保连续" / "人工挑 1") — 这些归 anchor / decorator / memo / config; **与内容本身不相关的工具指令/工作流命令**（该归入指令列 ❌） |
| **来源** (anchor, 输入) / **去处** (anchor, 输出) | 输入侧: 上游引用 + 容器索引; 输出侧: 下游去向 + 容器索引 | 上游 step output / declare / 字面量 / 下游 step | 输入: `← 工序输入` / `← sN.varname` / `← s6 (链, 上一张)` / `← 分镜序列[i]`; 输出: `→ s7` / `→ 视频片段列表.追加` / `→ 返回 短剧` | 描述内容 (那是 value); 描述用法 |

> ⚠ **value 必须逐字回填数据本身, 禁止引用占位**: 即使某输入就是上游输出**原样透传** (anchor 已是 `← sN.x`), value 也要填该数据**全文**, 不能写「(同 sN 输出)」「见 sN」「← sN」这类引用 —— 那是 anchor 的活, value 写了占位等于丢内容 (directive 同理: 必须是实际喂给工具的 prompt 原文). **不想手抄 N 遍**: 只在源头 (sN 的 output) 填一次真值, 透传位置设好 anchor 后跑 `wf-patch.py --resolve-passthrough`, 工具顺 anchor 把源 value 逐字抄到所有透传 value/directive (见 [tools.md §2](../tools.md)). lint 会扫这类占位报警.

#### 实现组 (8 列, 绿)

| 列 | 含义 | 取值来源 | 提取规则 | 反例 |
|---|---|---|---|---|
| **外部工具** (via) | L1 canonical 工具名 | 工序作者指定 | `manus` / `nano_banana_pro` / `<llm-agent>` / `human`; 原文未指名用 `(generic 描述)` 占位 (如 `(AI 生图工具)`); 控制流块用 `-` | 描述性短语 (该归 directive) |
| **动作** (action) | 工具的内容动作 kind | §A.2 字典树路径 | `提取/化学提取/反推`, `生成/元素生成`, `修改/增/添加`; 控制类已分流到 `逻辑控制`, 这里不放 | 自造动词 |
| **指令** (directive) | **字面 prompt 文本** — 真正喂给工具的 prompt 字符串 | 原文中的 prompt 引文; 没引文则按工艺反推一段合理 prompt | 祈使句, 像直接复制粘贴的 prompt. 引号包裹原文 quote: `"反推这个视频的提示词, 拆解出 9 个维度: 审美/运镜/拍摄/..."`. **关于工具指令、流程控制、或者和生成内容本身没有直接关系的指示**（如 “反推提示词”、“请用 SD 进行重绘”、“比例 2:3”、“帮我生成图片：”等命令描述）作为实现手段，**必须**归入此列而非输入 value 列 | "上传文件, 让 manus 反推" (这是步骤说明 ❌); "智能体外层 prompt: 按..." (描述工艺逻辑 ❌); **纯画面内容描述词**（应归入输入数据流的值 value ❌）. **人工 / 控制流 step 无 prompt, directive 应空** |
| **配置** (config) | **工具运行参数** (单次调用可设的数值/枚举) | 工具 UI / API 参数 | 例: `{ 2K · 1:1 · 4 张 · 模式=智能参考 }` / `aspect=16:9, dur=12s` / `UI audio=开` | "免费配额: 免登录视频 4 / 图片 10" (账户层事实, 非运行参数 ❌, 该归 memo 或工序级 declarations); 描述性句子 |
| **运行** (decorator) | **caller-side 调用修饰** — `@` 装饰器 | 工序作者添加 | `@采样(n=4, pick=人工)` / `@重试(max=3)` / `@缓存` / `@限流` | 工具本身参数 (那归 config); 描述工艺 |
| **备注** (memo) | **其他列没承载的实现方式信息** — 工艺级 wisdom | 工艺经验总结 | (1) 经验性招法 trick: "动作不连贯时优先用上一张作链参考"; (2) 替代 variant 说明: "本 case 走方法 3 手写; 替代: 方法 1 让 manus 拆视频"; (3) 工具选型理由: "工具选型唯一硬约束: 必须免费"; (4) 适用条件 / 边界 / 已知坑 | "本步独立, 不进入主流程" (analytical commentary ❌); "原文: '...'" (溯源引文 ❌); "拆 3 维度的本质是 prompt 块复用" (analytical, 非实现方式 ❌); 工具账户层运营事实 (那是工序级别, 非本 step 实现) |
| **逻辑控制** (control) | 本步的控制流类型 | 工艺分析 | `并行` / `遍历` / `分支` / `请求` / `等待`; 普通 step 留 `-`. **可在目的列引用** (`{control:并行}` 等), 因为控制流形塑步骤外观 | 把控制流塞进 `动作` 列 ❌; 把控制流塞进 `特性` ❌ |
| **特性** (feature) | **执行特征** (仅) — 内部执行属性 | 工艺分析 | `随机` / `幂等` / `人工` / `本地` / `写外部` / `读外部`; 普通块 step 留 `-` | 混入控制流 (那归 `逻辑控制`) ❌; **目的列不允许引用 `{feature:X}`** (执行特征是内部属性, 不在用户面向描述里出现) |