danbooru-tags

name: danbooru-tags description: | Validate Danbooru hard anchors for Anima generation: artists, characters, series/IP, appearance, clothing, props, poses, expressions, scenes, and random candidates. Not for composition, prompt writing, or workflow execution.

danbooru-tags

纯标签检索工具。不决定构图、不写 prompt、不执行 workflow。

硬约束

• 始终使用本地 bin/danbooru-tags.exe，不搜索、不递归。
• 默认先用已知/推断出的 Danbooru canonical tag 精确查询。
• 精确查询查不到时，才进入同组别名、拆分词、候选词补查。
• 候选池和随机池不是默认入口；仅在用户要求随机/抽卡，或精确补查仍缺失时使用。
• confirmed_tags 可用于回填（仍需意图筛选）；candidate_tags 仅作候选，必须筛选。
• missing → 写入 nltags。
• 不决定构图、镜头、光影、workflow 执行。
• 不写完整 prompt。
• 非 artist category 的 tag 不加 @，不作为画师。
• 随机角色/服装/姿势/场景候选不使用 --for-prompt。

CLI 位置

$SKILLS_ROOT = $env:COMFYUI_GOOD_ANIMA_SKILLS_DIR
if (-not $SKILLS_ROOT) { throw "COMFYUI_GOOD_ANIMA_SKILLS_DIR is required" }
$TAG_ROOT = Join-Path $SKILLS_ROOT "danbooru-tags"
$cli = Join-Path $TAG_ROOT "bin/danbooru-tags.exe"

不搜索递归。不使用旧路径。

检索优先级

按顺序执行：

1. 精确验证：先用模型已知、用户给定或已解析的 canonical tag 查询。
   • 默认 --match-mode auto：先 exact，exact 无命中才 fuzzy。
   • 只允许直接命中时使用 --match-mode exact。
   • artist：--group artist --prefix "@artist name"
   • character：--group character --keyword "character name"
   • series/IP：--group series --keyword "series name"
   • general hard anchor：--group <group> --keyword "tag phrase"
2. 小范围补查：精确验证无命中时，只补同一语义锚点的别名、英文名、拆分词。
3. 候选池：补查仍无命中，且该锚点必须落成 tag 时，才取同 group 候选。
4. nltags：复合概念、关系、构图、光影、查不到的自然语言描述写入 nltags。
5. 随机池：仅用户明确要求随机/roll/抽卡时调用。

禁止：

• 不先精确验证就直接查候选池。
• 不把 group 候选整批塞进 prompt。
• 不为普通描述扩展大候选池。
• 不为同一锚点连续循环补查。

批量查询（生图前默认）

默认批量只放精确验证项和必要的小范围补查项。JSON 必须 UTF-8 without BOM：

$json = @{
  queries = @(
    @{ id = "character"; group = "character"; keyword = "kanade tachibana"; limit = 5 },
    @{ id = "series"; group = "series"; keyword = "angel beats"; limit = 5 },
    @{ id = "artist"; group = "artist"; prefix = "@mignon"; limit = 5 }
  )
} | ConvertTo-Json -Depth 20
$file = Join-Path $env:TEMP "danbooru_batch.json"
[System.IO.File]::WriteAllText($file, $json, [System.Text.UTF8Encoding]::new($false))
& $cli --batch-file $file --batch-workers 8 --for-prompt --json --compact

单查

# 画师
& $cli --group artist --prefix "@mignon" --limit 5 --for-prompt --json --compact

# 角色
& $cli --group character --keyword "hakurei reimu" --limit 5 --for-prompt --json --compact

# 只做直接命中验证，不返回模糊候选
& $cli --group character --keyword "hakurei reimu" --match-mode exact --limit 5 --for-prompt --json --compact

随机

规则：

• 候选池用 --random N --json，生图回填用 --random N --for-prompt（只返回 1 条），不混用。
• --for-prompt 不允许与 --group 一起用。
• N 使用 10–50，上限 300。只调用一次，不循环。
• 不向用户复述完整候选 JSON。

批量规则

• 同一锚点优先放 canonical 主词；别名、拆分词只在主词不稳或无命中风险高时加入。
• 精确 artist/character/series 查询 limit=5。
• 服装/动作/场景/俗称 limit=10–20。
• 普通生图 ≤4 语义锚点；稳定 canonical 每锚点 1 个 query，不稳定锚点最多 2–3 变体，总 query 4–12。
• 最多 1 次批量 + 1 次补查。
• group 漏匹配时同批加 category=general 变体。
• general 命中仅作 candidate_tags。

查 vs 不查

查： 用户指定角色/作品/画师、关键服装/道具/姿势、随机候选、已解析 canonical 候选需确认。

不查（写 nltags）： 普通自然语言描述、光源方向、前景/中景/背景、脸部清晰/故事关系/氛围。

输出读取

• confirmed_tags — 可回填，仍需意图筛选。
• confirmed_tags 只来自 exact_tag、exact_alias、artist prefix。
• candidate_tags — 模糊补查或回退候选，必须筛选，不直接回填。
• missing — 写 nltags。
• 不向用户复述完整搜索过程。

JSON 输出 schema

单查 --for-prompt --json --compact

{
  "found": true,
  "confirmed_tags": {
    "characters": [
      {
        "tag": "hakurei_reimu",
        "prompt_tag": "hakurei reimu",
        "category": "characters",
        "source_category": "characters",
        "count": 65105,
        "match_score": 1000,
        "match_layer": "exact_tag"
      }
    ]
  },
  "candidate_tags": {}
}

批量 --batch-file ... --for-prompt --json --compact

{
  "found": true,
  "results": {
    "character": {
      "found": true,
      "confirmed_tags": {},
      "candidate_tags": {}
    }
  },
  "missing": [],
  "usage": {
    "confirmed_tags": "...",
    "candidate_tags": "...",
    "nltags_hint": "...",
    "empty_result": "..."
  }
}

字段规则：

• found=false → 不回填 tag。
• confirmed_tags.<category>[] → 可作为 hard tag 候选，仍按用户意图筛选。
• candidate_tags.<category>[] → 只用于人工/模型筛选，不直接写入 hard_tags。
• missing[] → 对应 query 没有可确认 tag；停止补查或改写为 nltags。
• match_layer=exact_tag → tag 直接命中。
• match_layer=exact_alias → alias 精确命中。
• match_layer=prefix → artist prefix 命中。
• match_layer=fuzzy / group_general_fallback → 候选，不是 confirmed。

硬性规则

• Artist tag 必须来自 artist category，保留 @。
• Character/series/general tag 不带 @，不作为画师。
• confirmed_tags 不证明默认服装/发色稳定。
• 不伪造 Danbooru tag。
• CLI 不可用/非 0/非 JSON/字段缺失 → 停止，不切换旧实现。
• newest/recent/mid/early/old 和 year XXXX 是 Anima 年代控制词，不需 tag 命中证明。

分组速查