Agent/examples/process_pipeline/script/procedure-dsl/spec/extraction/fields.md

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

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

推断补全标记 (重要)

抽取时, 主 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 是推断补全的 (源文本完全没列, 但工艺需要):

{
    '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 占位):

{
    '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.

{
    '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). 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 个维度: 审美/运镜/拍摄/..."	"上传文件, 让 manus 反推" (这是步骤说明 ❌); "智能体外层 prompt: 按..." (描述工艺逻辑 ❌). 人工 / 控制流 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} (执行特征是内部属性, 不在用户面向描述里出现)