图像与文件序列 (Sequences)

Griptape Nodes 能够将包含数字序号的文件目录智能扫描识别为有序序列 (Sequences)——例如渲染产出的影视级序列帧 render.0001.exr、render.0002.exr… render.0100.exr，亦可涵盖配音录制片段（take_##.wav）、文本章节切片（chapter_###.md）或任何以文件名数字作为排序键的资产集合。

创作者只需将支持序列的算子节点指向一个路径或通配模式 (Path or Pattern)，底层引擎便会自动在磁盘上查找匹配的文件、智能处理中间缺失的跳帧缺口，并向节点返回由整型数字与前导零补齐字符串构成的规范序列清单。

序列帧通配模式语法 (Pattern syntax)

序列模式表现为一个将数字序号替换为占位符标记的文件名。系统原生支持四种主流的工业标准记号：

通配标记	默认位宽	说明与适用体系
`####`	4	推荐标准。每一个 `#` 代表一位数字。`##` = 2 位，`####` = 4 位。
`%04d`	4	C 语言 printf 风格。`%04d` 代表 4 位前导零补齐。
`@@@@`	4	Houdini / RV 风格。语义与 `####` 完全一致。
`$F4`	4	Houdini 变量风格。语义与 `####` 完全一致。

这四种标记在引擎内部完全等价。推荐在新建模板时优先选用 #### 或 %04d，它们在绝大多数数字内容创作 (DCC) 软件中兼容性最佳。

示例： - render.####.exr $\rightarrow$ 第 5 帧对应 render.0005.exr - render.%04d.png $\rightarrow$ 第 12 帧对应 render.0012.png - take_##.wav $\rightarrow$ 第 7 条音频对应 take_07.wav

通配标记只能置于文件名中

通配标记必须且只能出现在文件名部分。系统严禁在目录路径层级中使用序列标记（例如 render/####/beauty.exr 是非法模式）。

当路径中未提供序列标记时的二义性仲裁

当传入的路径缺乏任何序列通配符时（例如 /work/photo.png、{inputs}/poster.png 或 render.0002.png），可能代表三种截然不同的意图：

确切指名单一具体文件：我确实只要 render.0002.png 这一张图；
隐式序列的其中一帧：用户随手选了一帧，希望系统自动推演扫描同目录下所有的连续兄弟帧；
书写笔误：创作者遗漏了输入 ####，系统应当立即严肃报错阻断。

引擎通过 NoTokenBehavior 枚举向调用方暴露了仲裁选择权：

仲裁枚举值	前端下拉选项	行为表现
`SINGLE_FILE` (默认)	Treat as a single file	视作单一文件。若该文件存在，返回仅含该单项的序列（`first=last=1`）；若不存在返回空。彻底忽略同目录下的其他兄弟文件（即使旁边并排存在 0001–0005）。
`EXPLORE_SEQUENCE`	Treat as part of a sequence	视作序列的一部分。自动将文件名中的数字推演为隐式通配符，遍历扫描同目录下所有匹配格式的兄弟帧。适合下游工具只吐出了单一帧名、但你希望加载整条镜头的场景。
`REJECT`	Fail unless a token is present	严格模式报错。直接抛出 `INVALID_TEMPLATE` 异常，提示创作者显式补全序列标记，杜绝任何意图扩大化。

宏模板与序列的完美融合

序列路径能够与工程系统的宏模板语言 (Macros) 完美无缝融合。引擎在底层会自动解析宏的头部目录以扫描真实磁盘，但向上层节点吐出的序列路径依然完整保留原始的宏占位符结构：

输入路径: {inputs}/shot_a/render.####.exr
输出对象: Sequence(directory="{inputs}/shot_a",
                  entries=[{path: "{inputs}/shot_a/render.0001.exr"},
                           {path: "{inputs}/shot_a/render.0002.exr"}, ...])

这是实现工程资产绝对可移植性的关键所在：在 macOS 上构建的工作流（{inputs} 映射为 /Volumes/Renders）其序列产物依然以 {inputs} 标记；直接将工作流移至 Windows 机器打开（{inputs} 映射为 C:\renders），整个序列无需任何重定向重新打通，完全由下游节点实时按本机的工程模板自适应解析。

位宽匹配严格性约束 (Width matching)

# 标记的个数（或 %0Nd 的数值）对数字的位宽构成了严格的字符数约束：

若声明了 ####，引擎仅匹配位宽严格为 4 位的文件——render.0001.exr 完美命中，但 3 位的 render.001.exr 与 5 位的 render.12345.exr 会被直接忽略剔除。如果一个目录中混合存放了不同补零位宽的文件，它们会被视为相互独立的孤立序列。

缺帧与跳帧容错策略 (Missing-item policies)

在真实的 CG 渲染流水线中，序列帧经常存在缺口——例如 47 帧渲染中途崩溃、分段式挑帧导出等。扫描序列时，你可以指定以下策略之一来应对缺帧：

容错策略	行为与产物表现	最佳适用场景
`ABORT`	遇缺阻断。一旦在 `[first, last]` 范围内检测到第一个缺帧，立即终止并报错抛出该缺失帧号。不返回任何序列。	核心渲染质检：绝对不允许带着坏帧或缺帧继续向下游流转。
`SPLIT` (默认)	按连续区间切分。将离散碎片按连续帧区间切分为多个独立的子序列。例如帧号 1–5、8–12、15 会切分为 3 个独立的序列。	资产打包：每个连续片段本身具有独立剪辑语义。
`SKIP`	跳过缺失项。返回单一稀疏序列，仅包含磁盘上真实存在的文件（缺失的帧号记录在 `missing_numbers` 集合中）。	挑帧合成：由节点按需决定是否在空缺处填充纯黑或棋盘格。
`FILL_NEAREST`	就近邻帧填充。返回贯穿 `[first, last]` 的完整致密序列。对于缺失的帧，自动沿用其物理时间轴上距离最近的上一个有效帧进行填补。	影视播放兜底：防止播放器在缺帧时发生黑屏闪烁。

序列对象数据结构 (Sequence)

在代码层面，Sequence 是一个标准的 Pydantic 模型，算子节点通常将其输入声明为 type="Sequence"。核心字段包含：

first / last：经过区间裁剪后的活跃起止序号；
discovered_first / discovered_last：磁盘上实际探测到的原始起止序号（忽略范围截断）；
padding：声明的前导零字符位宽（例如 #### 为 4）；
pattern：规范化的标准模式字符串（如 render.####.exr）；
directory：源目录字符串（保留传入时的宏形态）；
policy：生效的缺帧策略；
entries：有序条目列表 list[SequenceEntry]，每项包含整型数字 number、补零字符串 padded_number 以及物理路径 path；
present_numbers：磁盘上真实存在的数字集合；
missing_numbers：在当前有效区间内缺失的数字集合。

底层技术实现与请求总线

序列解析底层基于工业级开源库 fileseq 构建。所有的目录扫描与文件枚举均通过引擎的异步事件总线分发（派发 ScanSequencesRequest 事件并在 Worker 独立线程池中执行），杜绝了在极深目录或高延迟 NAS 共享存储上扫描万级大序列帧时阻塞主事件循环的隐患。