权重简介 / Weights (v2 recommended)

v2（推荐） 于 2026-09-25 在云端用真实 MiniMax-H3 文本编码器（Qwen3-VL-32B int8_convrot，embedding dim=5120）对逻辑链 + XYZ 训练对（wushu_pairs_v2_logic_chains.jsonl，615 pairs，DEFAULT_OPS 含 xyz_drift 与六大翻车）编码后训练：

• wushu_bridge_wushu_v2.safetensors — residual semantic bridge（trans 2L d=256）
• wushu_jev_wushu_v2.safetensors — JEV head（val_auc0.997 / val_acc0.984 / ECE~0.001）

v1 文件保留作对照；请优先加载 v2。同路径也在 plugin/ComfyUI-H3-WushuBridge/models/wushu_bridge/。

ComfyUI-H3-WushuBridge · MiniMax H3 武打语义逻辑桥

v1.1.2（XYZ 坐标锁定 + 逻辑链 + 六大翻车差向量）
Hugging Face 仓库现已托管 完整插件 + 权重（原名 h3-wushu-bridge-weights 已重定向到本仓）。
代码功能已到 v1.1.x；已发布的神经网络权重仍为 v1，需本机用 H3 CLIP（5120-d）按 docs/训练流程.md 重训后才能吃满逻辑链 / XYZ。

中文 | English

---

插件简介

它是什么

ComfyUI-H3-WushuBridge 是插在 MiniMax H3 CONDITIONING 节点之间的残差「武打语义逻辑桥」：

CLIPTextEncode(H3) ──► [ H3 武打语义逻辑桥 ] ──► KSampler / H3 采样节点
        │                        ▲
        │                        └─ 只替换 embedding 张量
        └─ conditioning                 minimax_keyframes / minimax_refs /
           [1, T, 5120] + metadata       minimax_frame_count 等 metadata 原样保留

它把「力线、格距、面对面、命中反馈、切镜身份/空间连续、XYZ 站位」等武打逻辑写进 H3 自己的 conditioning 空间，而不是改提示词字面。架构对标社区 MiniMax-H3-Semantic-Bridge，但训练数据、判据、评分头全部换成武打专用，模型极小，可在装了 H3 的 ComfyUI 里原地训练。

为什么需要它

用户实测中，裸 H3（即便叠武打 LoRA）常出现这些逻辑翻车：

1. 无意义跳跃 — 腾空无起落力
2. 未面对面 — 对打却侧身/背对
3. 法术打空气 — 施法方向不对准对手
4. 切镜换人 / 位置瞬变 — 身份与站位跳变
5. 空间逻辑弱 — 左右、间距、朝向混乱（v1.1.2 用显式 xyz= 锁定）
6. 法术击中无反馈 — 命中后无踉跄/灼衣/击退等物理反应

本插件用「正例种子 − 定向降级负例」把上述失败写成训练差向量；评分头也会对正例扣分。另有 BUNNY 风格高动态逻辑链（缴械、撞墙反弹、遮挡再识别、追击、状态继承等）。

架构要点

节点一览

日常出片默认只注册 5 个核心节点（分类 MiniMax H3/Wushu Bridge）：

训练 / 诊断节点（构建数据集、采集训练对、训桥、训 JEV、降级预览、token 段定位等）默认隐藏。需要时：

# Linux / macOS
export WUSHU_BRIDGE_NODES=all
# Windows cmd
set WUSHU_BRIDGE_NODES=all

然后重启 ComfyUI。

逻辑链 · 降级 · CRITICAL

• 逻辑链（logic_chains.py）：打斗完整弧（逼近→攻防→接触→反馈→终结）+ 行为连续性（ownership / occlusion / momentum / pursuit / facing / state_carry …）+ xyz_coord_duel
• 降级算子：经典逻辑 ∪ 高动态 ∪ CRITICAL（facing_break / jump_orphan / spell_miss_target / identity_drift / teleport_cut / spell_no_feedback / xyz_drift）
• 默认档案 DEFAULT_OPS 已混入上述 CRITICAL；详见仓库 docs/逻辑链说明.md

XYZ 坐标约定（v1.1.2）

相机相对地面坐标系（建议每镜开头重申）：

单位：抽象「步」。典型对决：角色A@xyz=(-2,0,0) 与 角色B@xyz=(2,0,0) 面对面。
降级 xyz_drift 会扰动或剥掉坐标；评分 xyz-lock 偏好带 xyz 的多镜对决。

安装路径（全部使用本仓新 URL）

任选其一，放到 ComfyUI/custom_nodes/ComfyUI-H3-WushuBridge/ 后重启：

1. 插件目录（本仓）
   https://huggingface.co/Jojocodex/ComfyUI-H3-WushuBridge/tree/main/plugin/ComfyUI-H3-WushuBridge
2. 发行 zip
   https://huggingface.co/Jojocodex/ComfyUI-H3-WushuBridge/resolve/main/releases/ComfyUI-H3-WushuBridge-plugin.zip
3. GitHub 克隆
   git clone https://github.com/Jojocodex-dotcom/ComfyUI-H3-WushuBridge.git

权重放到 ComfyUI/models/wushu_bridge/（也可直接用插件树内 models/wushu_bridge/ 镜像）。

自检（无需 H3 / 显卡）：

python ComfyUI/custom_nodes/ComfyUI-H3-WushuBridge/tools/selftest.py

仓库布局（本 HF 仓）

ComfyUI-H3-WushuBridge/          ← 本 Hugging Face 仓根
├─ README.md                     ← 本模型卡
├─ wushu_bridge_wushu_v1.safetensors
├─ wushu_jev_wushu_v1.safetensors
├─ *_report.json
├─ datasets/
│  └─ wushu_pairs_v2_logic_chains.jsonl   ← 最新 TEXT 对（重训用）
├─ plugin/ComfyUI-H3-WushuBridge/         ← 完整插件源码树
├─ releases/ComfyUI-H3-WushuBridge-plugin.zip
└─ laya/                                  ← 可选 Laya 裁判 bundle

GitHub 源码树布局见项目 README「目录结构」一节。

---

权重简介

重要：下列 v1 safetensors 在完整逻辑链 / XYZ / 六大翻车差向量落地之前训成。
代码已是 v1.1.2，但神经网络权重尚未用 wushu_pairs_v2_logic_chains.jsonl + H3 CLIP 5120-d 重训。
要吃满新逻辑，请在本机按 plugin/.../docs/训练流程.md 重训后替换。

wushu_bridge_wushu_v1.safetensors（~16 MB）

wushu_jev_wushu_v1.safetensors（~6.7 MB）

*_report.json

训练指标快照（参数量、验证 sem / accuracy / AUC / ECE、漂移、逐轮 history）。便于对照复现，不是推理必需。

datasets/wushu_pairs_v2_logic_chains.jsonl（~615 对）

laya/（若存在）

可选 Laya 裁判 bundle（english + multilingual）。装完插件后：

python tools/setup_laya.py --from ours

即可从本仓 laya/ 装配，无需手抠文件。

已移除（obsolete）

以下文件已从本仓删除，请勿再引用旧链接：

• wushu_bridge_cloud.safetensors / wushu_jev_cloud.safetensors（早期云端对照）
• wushu_pairs_v1_pairs.jsonl / wushu_pairs_v1.json（旧对清单；请改用 v2 logic_chains）

旧仓名 Jojocodex/h3-wushu-bridge-weights 已重定向到 Jojocodex/ComfyUI-H3-WushuBridge。

---

快速开始

# 1) 装插件（zip 示例）
cd ComfyUI/custom_nodes
curl -L -o plugin.zip \
  https://huggingface.co/Jojocodex/ComfyUI-H3-WushuBridge/resolve/main/releases/ComfyUI-H3-WushuBridge-plugin.zip
unzip plugin.zip   # 得到 ComfyUI-H3-WushuBridge/

# 2) 装权重（若 zip/插件树里尚未带上）
mkdir -p ComfyUI/models/wushu_bridge && cd ComfyUI/models/wushu_bridge
BASE=https://huggingface.co/Jojocodex/ComfyUI-H3-WushuBridge/resolve/main
curl -L -O $BASE/wushu_bridge_wushu_v1.safetensors
curl -L -O $BASE/wushu_jev_wushu_v1.safetensors

# 3) 重启 ComfyUI → 接线
# CLIPTextEncode(H3) → H3武打语义逻辑桥 → 采样
# bridge = wushu_bridge_wushu_v1.safetensors
# judge  = wushu_jev_wushu_v1.safetensors（可选）

提示词里可写 XYZ，例如：角色A@xyz=(-2,0,0) / Fighter A at xyz=(-2,0,0)。

---

链接

引用 / 许可

• 本插件与本仓发布的 wushu v1 权重：Apache-2.0
• 内嵌 Laya 源码副本：Apache-2.0（见 plugin/.../wushu_bridge/vendor/laya/LICENSE）
• MiniMax H3 及衍生模型：遵循上游 MiniMax H3 Community License

@misc{comfyui-h3-wushubridge,
  title        = {ComfyUI-H3-WushuBridge: MiniMax H3 Wushu Semantic Logic Bridge},
  author       = {Jojocodex},
  year         = {2026},
  howpublished = {\url{https://github.com/Jojocodex-dotcom/ComfyUI-H3-WushuBridge}},
  note         = {Weights: \url{https://huggingface.co/Jojocodex/ComfyUI-H3-WushuBridge}}
}

---

English

What this is

ComfyUI-H3-WushuBridge is a residual wushu (martial-arts fight) semantic logic bridge for MiniMax H3. It sits between CONDITIONING nodes:

CLIPTextEncode(H3) → [ Wushu Bridge ] → sampler

It only replaces the embedding tensor and preserves minimax metadata (minimax_keyframes, minimax_refs, minimax_frame_count, …). Default architecture is a 2-layer Transformer bridge (d=256); an MLP option matches the community Semantic Bridge for A/B loading.

Why

Bare H3 often breaks fight logic: meaningless jumps, fighters not face-to-face, spells missing the opponent, identity/position jumps on cuts, weak spatial logic, weak spell-hit feedback — plus XYZ coordinate locking in v1.1.2.

Six CRITICAL failure modes are encoded as degrade ops (facing_break, jump_orphan, spell_miss_target, identity_drift, teleport_cut, spell_no_feedback, xyz_drift).

Nodes

Core (default): bridge, h3lint, JEV score, choreography, clear-cache.
Train/dev nodes appear when WUSHU_BRIDGE_NODES=all.

XYZ convention

Camera-relative ground frame: X left(−)/right(+), Y near(−)/far(+), Z height (0 = standing). Example: A@xyz=(-2,0,0) facing B@xyz=(2,0,0).

Install

• Plugin tree: plugin/ComfyUI-H3-WushuBridge
• Zip: releases/ComfyUI-H3-WushuBridge-plugin.zip
• GitHub: https://github.com/Jojocodex-dotcom/ComfyUI-H3-WushuBridge

Weights (detail)

Explicit: v1 weights predate full logic-chain / XYZ retrain. Code is v1.1.x; neural weights need a local retrain with H3 CLIP 5120-d (see docs/训练流程.md).

Removed: cloud weights and v1 pair dumps — use latest files only. Old repo id h3-wushu-bridge-weights redirects here.

License

Apache-2.0 for this plugin and published wushu v1 weights. Upstream MiniMax H3 follows its own community license.