Files

T

按官方约定放 web/docs/<节点>/<语言>.md，前端「信息」面板直接展示；
WEB_DIRECTORY 声明与目录同时提交，不留下「声明了但文件还没到」的中间态。

2026-10-17 15:12:00 +08:00

滚动角色（Rolling Character）

从角色 CSV（默认 danbooru_character_001.csv）中随机抽取角色，按 角色标签,作品标签,角色描述 逐行输出（多个角色之间用「逗号+换行」分隔），并输出结构化 JSON 与已测数量。输出未被下游使用时节点仍会执行。

输出 1 角色列表（prompt）：每个角色一行，例如
```
hakurei_reimu,touhou,1girl,brown eyes,long hair,
ganyu_\(genshin_impact\),genshin_impact,1girl,horns
```
不带权重，不会出现 (名称:权重) 这种写法。多个角色之间是「逗号 + 换行」：每行末尾补一个逗号（最后一行不补），这样把多行拼成一行时前后的标签不会粘在一起
输出 2 角色 JSON（characters_json）：{"characters": [{"name","copyright","top","count","core_tags"}], "status": "OK"}
输出 3 已测数量（tested_count）：当前数据库里已记录的角色组合数量（字符串，可直接接到文本节点查看）

数据来源与 trigger 拆解

默认读 trigger 列。该列经 34,416 行全量校验是恒定的两段结构：

段	内容	校验结果
第 1 段	角色标签（已转义，可直接使用）	== 转义后的 `character` 列：34,416/34,416
第 2 段	作品标签（如 `touhou`）	== 转义后的 `copyright` 列：34,416/34,416

读取的列固定为 trigger（不可配置）：该列恒为上述两段结构，因此不需要选列参数。

每个角色一行，字段之间用英文逗号连接：

角色标签,作品标签,角色描述

关闭「开启角色描述」开关后变成：

角色标签,作品标签

参数	类型 / 范围	说明
角色数量（`character_count`）	INT 1-10	每次生成的角色数量（1-10），每个角色一行
人气池占比（`character_top_ratio`）	FLOAT 0.01-1.0	人气池占比：按 CSV 行序取前 `ceil(候选数×比例)` 个；候选数 = 作品筛选之后的角色数
人气池抽取数量（`character_top_count`）	INT 1-10	每次至少抽取几个人气池角色
随机种子（`seed`）	INT	随机种子
Top 优先抽样（`use_top_priority`）	BOOLEAN	优先从人气池抽角色
排除角色（`exclude_characters`）	STRING	排除名单，英文逗号分隔
强制包含（`force_include`）	STRING	必定出现的角色；不在 CSV 里的名字也能用，只是没有作品与角色描述
作品（`copyright_pick`）	COMBO	作品下拉，列出 CSV 里的全部作品（默认数据约 3,460 个，按作品热度即 count 总和降序），首项 `(不限)`。下拉可直接打字筛选、忽略大小写
开启角色描述（`describe_character`）	BOOLEAN	是否在每行末尾拼上角色的固定外观标签（`core_tags`，即角色描述）；默认开启
自定义 CSV 路径（`custom_csv_path`）	STRING	自定义角色 CSV 路径；留空使用 `danbooru_character_001.csv`
记录数据库路径（`tested_db_path`）	STRING	记录数据库路径；留空使用 `rollingcharacter.sqlite`（与画师节点分开）

角色节点不做权重分配（因此没有权重相关参数）、不做穷举（角色是单词条）、 没有去重模式参数（重复回避用一个固定规则的窗口，见下）。

下拉列出 CSV 里的全部作品（默认数据约 3,460 个），按作品热度从高到低排列：热度 = 该作品下所有角色的 count 之和（反映「这个作品整体有多热门」，而不是「这个作品里有多少个角色」）。并列时按名字升序，顺序稳定可复现
第一项 (不限) 表示不筛选
下拉可以直接打字筛选，忽略大小写——输入 a 只剩 a 开头的，继续输入 ab 会进一步收窄
同样接受 copyright 列的原始写法（fate_(series)）与 trigger 里转义后的写法（fate_\(series\)）
下拉项来自默认 CSV（danbooru_character_001.csv）：换 custom_csv_path 指向别的文件时，下拉选项不会跟着变
筛选后一个候选都不剩时会报错，而不是默默输出空串

节点不再提供去重模式，改用一个固定规则的内存窗口：

窗口里保存最近 10 条输出记录，每条记录 = 一次生成（可能含多个角色）
抽取前把窗口里出现过的角色名从候选里排除，因此 character_count=1 连抽 10 次会得到 10 个不同的角色；character_count=3 时相当于「最近 30 个角色内不重复」
窗口放在节点实例的内存里：重启 ComfyUI 会清零，同一个工作流里的多个角色节点也各算各的
想要手动清空窗口，可以在外部脚本里调用 node.reset_recent()； node.recent_names() 可以查看当前窗口里的角色名
窗口把候选全部吃掉时（例如只选了个角色数很少的作品），节点会退回「允许重复」并打一条 WARNING 日志，不会报错、也不会卡住不出图

默认数据库位于节点目录：rollingcharacter.sqlite，与画师节点分开（记录带 kind=character 标记，即使被指向画师节点的库也不会互相冒充）
这里只存历史输出记录（供 tested_count 与事后查看），重复回避不依赖这个数据库，因此更换 tested_db_path 不会重置窗口
默认数据库每次启动 ComfyUI 会被清理