# card-toolkit · RP-Hub 制卡工具箱

> 当前版本 **v2.3**。一个目录装齐「做一张角色卡所需的全部知识 + 能跑的工具 + 能判死的闸门」。
> 拷走整个文件夹就能在别的机器上用，不依赖任何私有路径。

---

## 这是什么

如果你在做 RP-Hub（角色扮演平台）的角色卡，这个工具箱解决三件事：

| 你的困境 | 它怎么解决 |
|---|---|
| 「世界书为什么不触发？」 | 关键词可达性五档审计，能告诉你这个键**根本没人会写** |
| 「写着写着人物就崩了」 | 人设内核 + 防漂移锚点 + 面具状态机，一套造人方法 |
| 「这次改完到底行不行？」 | 4 个脚本直接跑出 `exit 0 / exit 1`，不靠感觉 |

一句话：**它不只告诉你「应该怎么写」，还能在你写完之后告诉你「这卡到底过没过」。**

---

## 里面有什么

### 一、两个能直接跑的工具（纯 Python 标准库，不用装任何包）

```bash
# 生图（中文提示词也行，脚本自己转 tag）
python3 scripts/sta1n_image.py "金发大小姐，校服，落地窗，午后逆光"

# 生图并拿图床直链（可直接写进卡里）
python3 scripts/sta1n_image.py "提示词" -o cover.png --upload

# 卡 JSON ⇄ PNG 互转（RP-Hub 认的 chara / ccv3 双块格式）
python3 scripts/pack_card_png.py --card 卡.json --cover 封面.png -o 卡.png
python3 scripts/pack_card_png.py --extract 卡.png -o 还原.json
```

密钥三选一：`--key sk-xxx` / `export STA1N_API_KEY=sk-xxx` / 复制 `config.example.yaml` 改成 `config.yaml`。
不配也能用别的功能，只有生图需要。

---

### 二、四个闸门脚本（v2.3 新增，这是本轮最大的增量）

在此之前，这个包里的知识全是「规范」——写得再细，也是靠 AI 自觉对照清单。
这四个脚本补上了**硬判定**：

```bash
cd bundle/rphub-card-flow/scripts

# ① 读骨架：这张卡自己的分段、类别、字数分布
node skeleton.mjs 你的卡.json

# ② 过闸门：exit 0 = 过，exit 1 = 没过，必须修
node gate.mjs 你的卡.json --segment=1

# ③ 关键词可达性：A/B/S/C/D 五档 + 列出缺裸名的条目
node key-audit.mjs 你的卡.json
node key-audit.mjs 你的卡.json --list-bare

# ④ 正则体检：空容器、正文外壳守卫
node regex-doctor.mjs 你的卡.json
```

**为什么 `skeleton.mjs` 重要**：它不给你模板，它**从你那张卡里读**。
实测三张真实卡的 order 区间分别是 `100~1,200,260`、`0~12,001`、`1,000~18,680`——
段位进制从百万级到千级不等。**任何「通用模板」套上去都会毁卡。**

自带 38 项测试，全绿：
```bash
node bundle/rphub-card-flow/tests/run-tests.mjs
```

---

### 三、34 个专项知识库（`bundle/`）

不是 34 个独立技能，是**随身知识库**。按需读对应目录的 `SKILL.md`，别全读。

#### 平台与架构
| 目录 | 管什么 |
|---|---|
| `rphub-master-skill` | 平台底层：渲染管线、Protection 分片、世界书注入算法、iframe、PNG tEXt。**679K，全包最大，平台问题看它** |
| `rph-card-architecture` | 总架构选型：模式 A 多脚本渲染型 vs 模式 B 自包含应用型 |
| `rph-advanced-design` | 高级工程：四维驱动、变量持久化、事件池、抗注意力漂移 |
| `rph-fanworld-theme` | 二游／同人大世界卡：层级导引、父主题注入 |
| `rph-version-contract` | 平台版本边界：1.8.1 / 1.8.3 / 1.9.x 差异与迁移 |
| `rph-migration-terms` | 变量UI ↔ 正则UI 切换、术语消歧 |

#### 世界书与关键词
| 目录 | 管什么 |
|---|---|
| `rp-worldbook` | 条目内容与架构：七大分层、order 区间、常驻预算、条目粒度 |
| **`rph-keyword-review`** | **关键词写/审/修唯一入口**。含 12 题错题分册（合成死入口、剧情发射链、逗号拆键、order 伪隔离…） |
| **`rphub-card-flow`** | **带脚本的闸门层**。裸名保底铁律、可达性五档、主线令牌往返、position 陷阱、正则空容器 |
| `rp-worldbook-position` | 插入位置/深度/排序号/扫描深度四参数 |
| `rp-card-mechanics` | 「写进去了到底会不会生效」机制五问 |
| `rp-pitfalls` | 错题集：正则类/世界书类/UI类/角色类，按症状查 |

#### 正则与 UI
| 目录 | 管什么 |
|---|---|
| `rp-regex` | 正则脚本本身：保护分片精确判据、双字段同步、性能 |
| `rp-ui` | UI 工程机制：三种实现方式、状态栏/面板/按钮、iframe 高度 |
| `rph-ui-style` | UI 信息架构与视觉预算：信息域三分、配色槽位 |

#### 流程与验收
| 目录 | 管什么 |
|---|---|
| `rp-card-flow` | 生产流程编排（完整版）：阶段/闸门/账本/双防线/断点续接 |
| `card-workflow` | 同上，精简执行版 |
| `rph-release-gate` | 交付前正向门禁清单（127K，最全的验收表） |
| `rph-toolchain` | API 生成、流式解析、Python 批量改卡、调试 |

#### 角色与文风
| 目录 | 管什么 |
|---|---|
| `char-core` | 单人角色内核：从零造一个人，且立得住 |
| `char-multi` | 多人卡：不混色、不炸预算 |
| `char-mask-state` | 面具状态机人设模板 |
| `char-scene` | 场景 / 地点 / NPC 配角 |
| `char-anti-drift` | 防漂移：演久了不歪、不回到过去 |
| `char-nsfw` | 亲密向写法：每次亲密都落回人设 |
| `nsfw-style` | 特化文风与文风世界书（写法层 / 特化层） |
| `writing-principles` | 读者要什么、LLM 训练怎么伤害它 |
| `creative-writing-craft` | 散文 / 场景 / 文体技法 |
| `story-review` | 稿后评审、连续性、校对 |
| `reader-sim` / `character-sim` | 读者体感 / 角色试演 |
| `character-creation` | 不知道找哪个时用的索引 |

#### 生图
| 目录 | 管什么 |
|---|---|
| `guofeng-director` | 国风视觉、电影感构图、双人互动、角色一致性诊断 |
| `nai-imagegen` | NovelAI 出图链路（走 STA1N 中转 + imgbb 图床） |

---

## 这轮（v2.3）到底加了什么

从 [qq1049323397/rphub-card-flow](https://github.com/qq1049323397/rphub-card-flow)（MIT）并入 v0.8.0，
补齐了「只能讲道理、不能判死活」的短板。五个此前没有的方法论：

1. **裸名保底（铁律）**
   每条非常驻条目的 keys 必须包含它在正文里的自然称呼。
   判据：存在一个键 ⊆ 裸名。因为键是**子串匹配**，键比裸名长就永远匹配不到。
   `地点：货运仓库` 这种键，正文写「我去货运仓库」时匹配不到。

2. **关键词可达性五档**
   - **A 直接**：出现在 first_mes / 已发生的对话 → 唯一「立刻生效」
   - **B 间接**：只在卡面 prompt 字段 → **下一轮**才进扫描窗
   - **S 常驻索引**：被常驻条目点名 → 中
   - **C 链式**：只在别的条目正文里 → 低
   - **D 死**：全卡零出现 → 永不触发
   还揪出了「索引照着键抄」这种**假救活**——所有工具判通过，触发却是死的。

3. **主线阶段机 = 令牌往返**，五件事缺一不可。
   第五件是**阶段之间的交接**：换幕不预写下一幕入场券，必断档。

4. **`position` 两处降级实测**
   - `before_char` / `after_char` 是**同一条 user 消息**，二选一即可
   - `at_depth` 会与相邻同角色消息合并（实测玩家 18 字 → 5150 字一条）
   - **漏写 position 等于默认 `at_depth`**

5. **正则空容器零长匹配**的守卫写法，9 项边界实测全过。

### 本地补丁（与原版不同）

`rphub-card-flow/scripts/rphub-card.mjs` 的 `rawEntries()` 增加了向后兼容：
原版只认 `character_book.entries`，而本工作区导出的**纯世界书**把 `entries` 挂在顶层
（`{name, entries:[...], extensions:{}}`），原版会误报「这张卡没有世界书条目」。
补丁使其在无 `character_book` 外壳时回落到顶层 `entries`。

实测：312 条的纯世界书文件可正常读出 6 段骨架。

---

## 怎么开始

**第一次用，按这个顺序：**

1. **先跑环境自检**（不出图、不花钱）
   ```bash
   python3 scripts/sta1n_image.py --check
   ```

2. **拿到一张卡，先读骨架，别急着写**
   ```bash
   cd bundle/rphub-card-flow/scripts
   node skeleton.mjs 你的卡.json
   ```
   看它自己的分段和字数中位数——那就是你该照着写的模板。

3. **写完一段，立刻过闸门**
   ```bash
   node gate.mjs 你的卡.json --segment=1
   ```
   看到 ❌ 就修，别说「应该没问题」。

4. **交付前全卡体检**
   ```bash
   node gate.mjs 你的卡.json
   node regex-doctor.mjs 你的卡.json
   ```

**做新卡**：先读 `bundle/rp-card-flow/SKILL.md`（流程编排），
再按它给的映射表加载对应专项。
**改旧卡**：先跑 `gate.mjs` 看现在什么状况，再决定动哪。

---

## 四条不许忘的

1. **素材目录只读**。用户投素材的地方永远不许写、不许改名、不许删。
2. **版本号只增不减**。内容有任何变化（含修 bug）就升号。
3. **交付前先列目录确认号没被占用**——交付文件夹里的最新版才是基线，不是制作文件夹的中间产物。
4. **改了就要归档**，归档名写明「改了什么 / 删了什么 / 加了什么」。

---

## 目录结构

```
card-toolkit/
├── SKILL.md                    agent 入口（装成 skill 时读这个）
├── README.md                   本文件
├── INDEX.md                    34 个专项的全量索引
├── CHANGELOG_v2.2.md           关键词专项修订
├── CHANGELOG_v2.3.md           并入 rphub-card-flow（本轮）
├── CREDITS.md                  第三方来源与署名
├── config.example.yaml         密钥模板
├── scripts/
│   ├── sta1n_image.py          一键生图（纯标准库）
│   └── pack_card_png.py        卡 JSON ⇄ PNG（纯标准库）
├── references/                 本包自己的 4 篇（工作区流程/生图/PNG/tag 词库）
└── bundle/                     34 个专项知识库（不会被 DSH 重复注册为技能）
    ├── rphub-card-flow/        ★ 带 4 个闸门脚本 + 38 项自测
    ├── rphub-master-skill/     平台底层（679K）
    └── ... 其余 32 个
```

---

## 许可与致谢

本包自身内容按随包 `LICENSE` 为准。

`bundle/rphub-card-flow/` 来自 [qq1049323397](https://github.com/qq1049323397/rphub-card-flow)，
MIT License，收录时保留完整正文、脚本与测试，仅对 `rphub-card.mjs` 做了一处向后兼容补丁。
其 `references/` 的方法论源自该文作者对 ArC 超越之影、478 条目大世界卡样本、
以及酒馆预设侧写作约束的提炼，完整署名见其 `SKILL.md` 末尾。

完整第三方清单见 `CREDITS.md`。