分院帽

分院帽人格测试（随机抽卷 + 麻瓜词典）。当用户说「给我分院」「我是哪个学院」「测测我适合哪个学院」「戴帽子」「霍格沃茨分院」时使用，用户抱怨「手打答案串太累/怕把题目搞混」时也直接走这里。首选生成单文件点选答题页：一屏一题、随机抽卷、点选即记住、答完点「提交判定」出卡；纯文本通道走三轮闭环，一屏出题 + 卷号 + 答案串回传。

分院帽 Skill

一个只会说话的帽子。它念歌谣、抽一张卷、铺题目、念评语、给出结果卡。

有两条路，题库、权重、阈值、编号、文案完全同源，走哪条结果都一样：

• UI 模式（首选）：生成单文件点选式答题页，每次打开随机抽一张卷，点选作答、自动记忆、一键提交出卡（第 11 节）。
• 纯文本模式（兜底）：开不了页面时走三轮文本对话，不依赖任何题卡/选项按钮组件。

0. 先判环境（三行适配）

检查项	结论	处理
能否执行脚本	有 Python 3 即可	走主路径 scripts/sorting_hat.py
能否读本地文件	能读 data/*.json	文案、题库、试卷、词典全部从配置读取，脚本内不含任何判词
是否需要降级	仅当无法执行脚本	见第 7 节「降级方案」，结果表与阈值与脚本完全同源

1. 交互协议（三轮内闭环）

两条路，优先走 UI 路

通道	何时用	怎么走
UI 模式（首选）	能在界面上打开本地 HTML	生成单文件答题页，页面自己随机抽卷，点选作答、自动记忆、点「提交判定」出卡。见第 11 节
纯文本模式	纯文本通道，开不了页面	下面这套三轮文本协议

UI 模式与文本模式的题库、试卷库、权重、阈值、平局兜底、编号、文案完全同源，走哪条路结果都一样。 先问一句用户想要哪种，或者按通道能力直接选；用户抱怨「手打答案串太累」时，直接切 UI 模式。

卷：每次都是新的一套题

• data/questions.json 是题库（33 道岔路），data/papers.json 是试卷库（33 张卷）。
• 每张卷从题库里抽 11 道不重复的题，题目顺序与选项顺序都打乱，固化在 papers.json 里。
• 打开页面 / 再测一次 / 跑一次 --questions，都会重新抽一张卷——所以每次看到的题不一样。
• 卷号是复现的唯一钥匙：卡片上会印「卷号 07」，文本模式第 1 轮帽子也会先报卷号。 没有卷号就没法复现，所以 --card 必须带上卷号。
• 运行期不做任何随机抽题，页面只随机决定「用哪一张」。所以同一份答案 + 同一张卷， 在页面里和文本里是同一个编号，可以互相复现。

纯文本模式：三轮内闭环

轮次	触发条件	帽子做什么
第 1 轮	用户表达想被分院	念歌谣（6–10 行，提到四位创始人与各自看重的品质）+ 报卷号 + 一屏铺开 11 道题
第 2 轮	用户回答案串	念评语（2–4 行，点出矛盾但不揭晓学院）+ 判断头名分差；传参时记得带卷号
第 3 轮	仅当头名与次名分差 ≤ 阈值（默认 0.12）	说「这是个艰难的决定」，直接问「你想去哪」，并给出 A/B/C/D 字母映射表

第 3 轮是原著机制，不是对平局的妥协：帽子会考虑戴帽者的意愿（哈利说「不要斯莱特林」，帽子照办了）。

执行动作映射

bash

# 第 1 轮：随机抽一张卷 + 歌谣 + 一屏题目（直接输出给用户）
python scripts/sorting_hat.py --questions
python scripts/sorting_hat.py --questions --paper 7      # 指定卷，便于复现
python scripts/sorting_hat.py --list-papers --limit 5    # 看看有哪些卷、各卷什么场景

# 第 2 轮：把用户的答案串 + 卷号一起传进去
python scripts/sorting_hat.py --card "1A 2B 3C 4A 5B 6C 7A 8B 9C 10A 11B" --paper 7
python scripts/sorting_hat.py --card "#7 1A 2B 3C 4A 5B 6C 7A 8B 9C 10A 11B"   # 卷号写在串前面也行
#   若输出到「这是个艰难的决定」→ 进入第 3 轮，把帽子的话原样发给用户
#   没带卷号 → 退出码 2，并给出「怎么补卷号」的提示（不会硬编一个卷号糊弄过去）

# 第 3 轮：带上用户的意愿
python scripts/sorting_hat.py --card "#7 …" --will "拉文克劳"
python scripts/sorting_hat.py --card "#7 …" --will "C"       # A/B/C/D 字母都认
python scripts/sorting_hat.py --card "#7 …" --will "随便"    # 弃权

分支处理

用户回复	帽子行为
学院名 / A B C D 跳字母	都接受；字母按 meta.houses 的顺序映射
随便 / 你定 / 都行 / 无所谓 / 随你 / 帮我分 / 你决定 / 你看着办 / 你说了算	取归一化分最高者，并在判词后追加一句吐槽（lines.abstain_tease）
坚持一个非头名学院（含分数最低者）	必须让步，卡片学院行追加 lines.yield_note（这是你自己挑的），让步前先吐槽一句 lines.yield_tease
头名分差 > 阈值	跳过第 3 轮，第 2 轮直接出结果
没给卷号	退出码 2 + 明确的补卷号提示。不许替用户猜一个卷号

输出纪律

• 帽子的每一句话都必须是脚本输出的原文，一个字都不许改写、扩写或补充祝福语。
• 脚本只做四件事：解析 → 计分 → 查表 → 渲染。
• 不要向用户展示分数明细（--scores 只用于调试与自测）。
• 卡片渲染完直接整段发出，不要包进代码块，避免截图时带上多余符号。

2. 计分模型

不用二极对立维度。每个选项给四院分别分配权重：

json

{"key": "A", "text": "…", "weights": {"gryffindor": 3, "hufflepuff": 1}}

1. 权重取值 0–3（meta.max_weight），单个选项可以只给一到两个学院加分，其余为 0。
2. 累加得四院原始分 raw[4]。
3. 归一化：score[house] = raw[house] / cap[house]，其中 cap[house] = 卷内各题中该院可获得的最高权重之和。
4. 配平靠题库，不靠逐卷调：只要每道题四院峰值都等于 max_weight，任何一张卷的 cap 都必然等于 paper_size × max_weight（当前 11 × 3 = 33），四院天然相等。 --audit 会逐题、逐卷双重检查这一条；不要用「给某道题补点权重」的方式去凑单张卷的配平。
5. 头名与次名差值 ≤ meta.threshold（默认 0.12）时触发第 3 轮。
6. 平局必须确定性兜底：用户弃权且并列时，按 meta.tie_break_priority 的固定顺序裁决。 该顺序可直接改，改完同一份答案仍然恒定得同一结果。

阈值与触发率

--audit 会打印「第 3 轮触发率」（逐卷枚举随机作答基准）。当前题库 + 阈值 0.12 下约为 53%–56% （单卷归一化分差 ≤ 0.12 等价于 raw 差 ≤ 3 分）；把 meta.threshold 调到 0.09 约降到 1/3， 调到 0.06 约降到 1/5。阈值越大第 3 轮越常见，越接近原著里帽子反复犹豫的样子； 越小则越快出结果。改阈值不需要动题目，改一个数字即可。

3. 题库与题干设计规则

场景落在魔法世界的日常：魔药课、魁地奇看台、图书馆禁书区、公共休息室、霍格莫德、 有求必应屋、禁林边缘、霍格沃茨特快、大礼堂、厨房旁走廊、天文塔、药草学温室、 猫头鹰棚屋、校医室、挂毯后的走廊、学院杯积分榜、圣诞舞会前夜、决斗练习场、 图书馆借书台、占卜课教室、飞行课草坪、塔楼宿舍、三把扫帚酒吧、考试周自习区、 级长会议、神奇动物保护课、移动楼梯上、下雪的门厅、魔咒课教室、湖边、 圣诞假期的宿舍、猪头酒吧后门、石像前的走廊。

• 题库当前 33 道，每题 3 个选项，三选都要「选得下去」，不许有凑数项。
• 硬约束（改题库必守）：每道题里，四个学院各自的最高权重都必须正好等于 max_weight。 这是「任何一张卷 cap 都配平」的唯一前提；--audit 会拦。
• 题干与选项里不许出现四院名称，也不许出现「勇气」「野心」「智慧」「忠诚」这类直白品质标签—— 否则用户会猜到在考什么，故意做选择偏差，测出来就不准。
• 考的是真实的人性抉择，不是原著冷知识。
• 四个学院没有优劣，全程不做价值判断。
• 上述禁词与学院名由 --audit 自动扫描拦截。

抽卷规则（scripts/make_papers.py）

• 均衡发牌：题库里每道题在全部试卷中被抽中的次数完全相同（当前 33 张卷 × 11 槽 ÷ 33 题 = 每题 11 次）。
• 同一张卷内不出现重复的题；两张卷的题集不会完全相同。
• 每题选项顺序独立打乱；default（漏答补入用的那项）跟着选项一起搬家， 所以「中间项」在页面上不一定是 B。
• 生成用的是固定种子（默认 20260915），同种子输出完全一致；改完题库重跑 python scripts/make_papers.py 即可，--check 只校验不重写。

4. 结果卡（为截图分享设计）

纯文本、等宽友好。固定区块：帽檐标题（分隔线 + 判定标题 + 卷号 · 编号）、学院（学院名 + 书版配色）、 帽子判词（4–6 行韵文）、创始人与遗物、学院档案（元素/院徽动物/常驻幽灵/公共休息室入口）、 你在这里会发光（2–3 条）、室友会怎么形容你（1–2 条）、相性/相克（各一个学院 + 一句理由）、 帽子的最后一句、转发语、同人创作声明 + 娱乐声明。

text

════════════════════════════════════════════════════════════════
                          分院帽的判定
════════════════════════════════════════════════════════════════
卷号 01 · 编号 019022B8

• 编号 = CRC32(答案串 + 学院表 + 卷号)，同一份答案在同一张卷上永远是同一个编号。 换一张卷，同一串字母会得到不同的编号——这是对的，那是另一份卷。
• 用户想复现，需要「卷号 + 答案串」两样东西，两样都印在卡片上，所以截图直接发给别人就够。
• 卡片行宽不超过 card.width（64），--selftest 会断言。

5. 角色语气（决定这个 Skill 好不好玩）

从头到尾只有分院帽一个角色在说话：第一人称、爱卖弄、有点自恋、押韵、偶尔损人但友善。 帽子主动跟用户互动：念完判词问一句「你想去哪」，用户坚持己见时让步并吐槽。

• 不要出现 MBTI 四字母，不要出现 16 型编号，只输出学院。
• 文案里禁止嵌套引号（「他说「随便」」这种），截图会很难看；--audit 会拦。
• 枚举值用分隔符连接，如 gryffindor-slytherin，不要拼成 GRSY 这类连读串；--audit 会拦。

6. 解析容错、返回码与自检

答案解析要宽容

以下写法全部识别为同一份答案（--selftest 逐条回归）：

text

1A 2B 3C …      1a2b3c…      1.A 2.B 3.C …      A B C …      ABCABC…      A,B,C,…
#7 1A 2B 3C …   ＃7 ABCABC…                     ← 卷号前缀

全角字符（Ａ Ｂ １）、中文顿号、逗号、空格、点号一律先归一化再解析。

缺答不追问

漏答的题用该题编译后的默认项补齐（默认项随选项顺序搬过家，不一定是 B）， 只在卡片末尾注一句「第 X 题未作答，已按中间项补入」。绝不逐题推进、绝不分批出题、绝不为漏答追问。

返回码

码	含义	表现
0	成功	正常输出（含「进入第 3 轮」这种中间态）
1	配置错误	[配置缺失] / [配置损坏] / 自检 FAIL
2	认不出答案、卷号或意愿	[认不出答案] / [认不出卷号] + 一句友好提示 + 示例
3	没给动作	打印可用动作清单

不静默失败：任何非零退出码都伴随一句人能读懂的话。

缺卷号时不许一律甩「你没给我卷号」。 先做一次纯语法盲判，把三种错分开报：

用户给了什么	报什么
???（根本不是答案）	[认不出答案] 这串字符我认不出来。回我字母就行…
1D 2D 3D（字母越界）	[认不出答案] 第 1 题只有 A/B/C 三个选项，你给了我 D。
1A 2B 3C（是答案，缺卷号）	[认不出卷号] 你回了我一串答案，但没告诉我是哪张卷。 + 三种补卷号写法

实现见 probe_answers()：拿「题号 1~64、每题三选项」的探针题库跑一遍解析， 不依赖真卷就能判断这段文本的语法是否成立。

自检命令

bash

python scripts/sorting_hat.py --audit                 # 结构全量检查 + 抽 6 张卷枚举 3^11
python scripts/sorting_hat.py --audit --audit-papers 0   # 33 张卷全枚举（约 70 秒）
python scripts/sorting_hat.py --audit --audit-papers 0 --config alt
python scripts/sorting_hat.py --selftest              # 18 项：四种结局 + 确定性 + 卷号 + 解析容错 + 版心
python scripts/sorting_hat.py --list                  # 打印四院配置
python scripts/sorting_hat.py --list-papers           # 打印试卷库（卷号 + 各卷场景）
python scripts/sorting_hat.py --random --seed 20260911   # 带种子随机（卷号也由种子决定）
python scripts/sorting_hat.py --scores "…" --paper 7  # 调试：四院归一化分与分差
python scripts/make_papers.py --check                 # 校验试卷库结构、cap、覆盖均衡

--audit 覆盖：逐题四院峰值 = max_weight、逐卷 cap 配平、试卷结构与覆盖均衡、 词典字段完整与无死词条、四院可达、字段完整、题干无禁用词、引号与枚举值格式。 结构类检查是全量的；3^11 组合枚举只是抽样观测（可达性与触发率本源于题库设计， 不是靠枚举证明的），默认抽 6 张卷。

UI 模式专用（需要 node）：四段对拍

bash

python scripts/build_quiz_html.py --verify --node <node 路径>
python scripts/build_quiz_html.py --config alt --verify --node <node 路径>

四段依次是：

1. 编译对拍：全部 33 张卷的「题库 → 卷」编译结果逐字段比对（题序、题干、选项文本、权重、默认项位置）；
2. 组合对拍：抽样卷遍历全部 3¹¹ = 177147 种作答，比对 JS 与 Python 的汇总校验和（--verify-papers N 调样本数，--verify-all 跑全部）；
3. 文字卡对拍：全部试卷 × 4 种结局 + 缺答补默认项 1 例，逐字比对；
4. 界面链路：用最小 DOM 桩驱动页面脚本，两张卷各跑三条作答路径到出卡，并检查词典标注范围与抽屉内容。

7. 降级方案（目标环境不能执行脚本时）

结果表与阈值与脚本完全同源，只少了自动解析：

1. 用 --questions 的输出原文（或按 data/papers.json 手工拼卷）把 11 题一屏铺开，并把卷号写明。
2. 收下用户的答案串（含卷号），人工按第 2 节规则逐题累加： 每题取所选选项的 weights，四院分别累加得 raw；cap 固定为 33（四院相同）。
3. score = raw / 33，排序取头名与次名，分差 ≤ 0.12 触发第 3 轮，否则直接查表。
4. 从 data/houses.json 原样搬运该院文案，版式照 --card 的输出格式逐行对齐； 编号用 CRC32(答案串 + 学院表 + 卷号) 复算，或直接留空并说明「没跑脚本，编号欠奉」。
5. 代价只是解析容错要自己写；结果表、阈值、平局兜底顺序都是同一份配置。

8. 去 IP 化（商用前必须做）

《哈利·波特》是受版权保护的商业作品。data/houses.alt.json 把四院名称、创始人、遗物、幽灵、 公共休息室设定整体替换为自创设定（焰炉堂 / 深流堂 / 高风堂 / 沃土堂 + 焰炉回音塔的择堂冠）， data/glossary.alt.json 是配套的名词表，计分逻辑与交互协议完全不变（学院 key 沿用同一套 id， 权重与试卷无需改动）。

bash

python scripts/sorting_hat.py --config alt --questions
python scripts/sorting_hat.py --config alt --card "#7 …" --will "深流堂"
python scripts/sorting_hat.py --config alt --audit --audit-papers 0
python scripts/build_quiz_html.py --config alt --out 择堂冠.html

已知缺口（还没补）：--config alt 目前只换了学院文案与名词表，题库本身仍是原著场景 （魔药课、魁地奇、霍格沃茨特快…），所以 alt 还没真正去 IP 化。真要用在商业产品上， 需要独立写一份 alt 题库 + 重跑 make_papers.py + 补全 glossary.alt.json， 并且把本 SKILL.md 里的书名、人名示例一并清理。

9. 文件清单

text

sorting-hat/
├── SKILL.md                 # 交互协议、计分规则、角色语气规范、麻瓜注释规范、降级方案
├── data/
│   ├── questions.json       # 题库 33 题（题干 + 选项 + 四院权重 + 默认项 + 阈值 + 平局优先级）
│   ├── papers.json          # 试卷库 33 张（每张 = 11 个 {qid, order}，由 make_papers.py 生成）
│   ├── houses.json          # 主配置：歌谣、评语、四院完整文案库、声明
│   ├── houses.alt.json      # 去 IP 化替代配置（学院文案层）
│   ├── glossary.json        # 麻瓜词典 73 条（术语 + 解释 + 是否带学院信息）
│   └── glossary.alt.json    # 配套 alt 名词表 27 条
├── scripts/
│   ├── sorting_hat.py       # --card / --questions / --list / --list-papers / --audit
│   │                        #   / --selftest / --random --seed / --scores
│   ├── make_papers.py       # 构建期：生成 / 校验 papers.json
│   └── build_quiz_html.py   # UI 模式：生成点选式单文件答题页（--out / --config / --verify）
└── references/
    ├── canon.md             # 书版考据要点（按书，不按电影）
    └── test-prompts.md      # 回归用例与预期结果

10. 最容易翻车的六处

1. 每道题四院峰值必须等于 max_weight——这是「任何一张卷 cap 都配平」的唯一前提。 逐卷去凑配平是错的方向，--audit 会拦。
2. 卷号必须跟着卡片走——随机抽卷之后，没有卷号就无法复现。卡片要印卷号，--card 要收卷号， 页面的「复制文字版」要含卷号。少了它，用户拿着同一串字母换张卷会得到另一张卡，然后来问你为什么。
3. 平局必须确定性兜底——同一份答案 + 同一张卷永远同一个结果；随机只允许出现在「抽卷」 和 --random --seed 的模拟作答里，且种子必须显示给用户。
4. 拉文克劳的院徽是鹰，不是渡鸦；配色是蓝与青铜，电影改成了蓝与银，这是最常见的错。
5. 禁词扫描——题干与选项里一旦出现学院名或直白品质标签，测试就失去意义。 词典里带学院信息的词条（house: true）只在封面歌谣与结果页标注，绝不在题干与选项里标注， 否则等于泄题；这条由 --verify 的界面链路断言守着。
6. UI 模式与文本模式是两份实现，必须对拍——页面里的 JS 抄了一份编译、计分与卡片渲染逻辑， 一旦有人只改了一边就会静默分叉。改题目 / 改权重 / 改阈值 / 改试卷后必跑 build_quiz_html.py --verify。改题库后还要重跑 make_papers.py，否则页面用的还是旧卷。

11. UI 模式（点选式答题页）

一条命令

bash

python scripts/build_quiz_html.py --out <输出路径>.html
python scripts/build_quiz_html.py --config alt --out <输出路径>.html   # 去 IP 化版本

产出是单文件自包含 HTML：无外链、无网络请求、无依赖，双击即开，可直接发给别人。 生成后必须 present_files 把页面推给用户，让他在预览里直接点。

页面里的作答流程

1. 封面念歌谣 + 显示本卷卷号，点「把帽子戴上」进第一题。
2. 一屏一题，点选项即选中并自动翻到下一题（220ms，可键盘 A/B/C 或 1/2/3，←/→ 翻页）。
3. 顶部进度点显示已答/当前题，可点击直接跳到任意题；已答的题随时可改。
4. 十一题答完，最后一题的下一个按钮变成「提交判定」；没答完时禁用并提示还差几题。
5. 触发第 3 轮（头名分差 ≤ 阈值）时给四个学院按钮 + 一个「你替我定」（弃权）； 选非头名学院会让步并标注「这是你自己挑的」。
6. 结果页按 house 文案分区渲染，抬头是「卷号 · 编号」；底部两个按钮：复制文字版 / 再测一次。
7. 「再测一次」= 换一套题：重新抽一张卷、卷号与编号都跟着换。

契约（改动时必须守住）

• 页面里所有「帽子说的话」原样取自 houses.json；build_quiz_html.py 的 JS 里 不含任何一句可展示给用户的判词。只有按钮与状态文案属于界面层（UI_LABELS）。
• 编译 / 计分 / 排序 / 平局兜底 / 编号 / 文字卡必须与 sorting_hat.py 一致，由 --verify 四段守住。
• 编号用同一套 CRC32 与同一份 profile 串 + 卷号，所以同一份答案在同一张卷上， 页面里和文本里是同一个编号。
• 结果页除了视觉化卡片，还提供「复制文字版」，复制出来的就是文本模式那张卡（含帽子评语与卷号）。
• 配色只按 house key 取色（--gryffindor 等 CSS 变量），因此 alt 配置同样可用。

12. 麻瓜注释规范

给不熟悉原著的人用的。写在 data/glossary.json：{"term": 词, "gloss": 一句话解释, "house": 真假}。

• house: true 表示这个词条本身带有学院信息（四院名、创始人、遗物、幽灵、休息室入口）。 这类词条只在封面歌谣与结果页标注；题干、选项、场景标签一律用 annotate(text, false)， 否则答题的人还没选就先被剧透了。
• 一个词条在同一段文字里只标第一处；词条按词长降序匹配（glossary.match）， 避免「戈德里克·格兰芬多」被切碎成「戈德里克」+「格兰芬多」；匹配位置不重叠。
• 解释要短、要说明「那是什么」，不要剧透剧情、不要评价高低。
• 词典里的每个词条必须真的在题库或学院文案里出现过，--audit 会拦死词条 （语料含词典自己的标题与说明，所以「麻瓜」这种只出现在说明里的词不会被误判）。
• 页面上：正文里的词条带虚线下划线，点一下弹出解释；顶部「麻瓜词典」按钮打开全量抽屉； 「注释」按钮可整体开关（默认开）。复制文字版不含任何标注，是干净文本。
• 词典解释属于资料层，可以写在 glossary.json 里；不要往 houses.json 里塞解释， 那个文件的每一句都是帽子在说话。