学习通题库导入 · XLS 生成（手册 v4）

> 本手册由本项目多轮「生成 → 平台导入 → 报错 → 定位 → 修复 → 再验证」的实测沉淀而成，覆盖 8 档约 1 万道题。
> 所有规则都是平台实测结论，不是推测。凡标注「⚠️」的为会导致导入失败或静默丢题的高危项。
> 版本：手册 v4 ≡ 包版本 v1.2.0（发布包 xuetang-question-bank-import_v1.2.0.zip；frontmatter version 与本文「手册 vN」一一对应，改动一处必须同步另一处）。
> 手册 v4 内容（2026-09-25 深夜，补 A18「删备份前先 grep 谁在读它」+ A19「备份四种定性」，A17 补一次实例；主干：补 A17 清理类「假绿」陷阱；新增：题干出处/版权/水印残留自动清洗 strip_source_tags()、答案文档自动配对比对（verify 第 24 项）、平台题量口径（大题数）、selftest_neg.py 反向自测）

0. 铁律速查（开工前 60 秒读完）

1. 触发场景与支持的题源类型

1.1 何时调用本 skill

不适用场景（必须先转述给用户）：
- 需要音频列——学习通导入模板无音频列，听力题只能导入后在题目编辑页手动挂接。
- 需要图片选项——图片二进制不能塞 XLS，只能写占位并在报告里列「需人工补图」清单。

1.2 支持的题源类型与解析通道

2. 输入规范：格式要求、预处理与清洗

2.1 题源材料的最低格式要求

2.2 预处理清洗规则（在切题之前一次性做完）

2.3 答案材料的预处理

官方《答案》文档是给人看的排版，val.parse_answers 只认三种形态：

• 1-5 BACBC（区间 + 纯字母）
• 1-5 a; b; c（区间 + 分号拆分）
• 1) B 2) C（同行多题）

必须先跑「只改排版、不改内容」的规范化脚本，产出 {KEY}_ans2.txt 再比对。典型病态行与补丁见附录 B 第 8 步表。

两条口径红线：
- XLS 交付用 ;，校验对照文档用空格（val.norm 会把 ; 拆成 2 个单元，口径错位会报「答案序列不一致」）。
- 规范化只做：补题号、拆行、逗号/空格→分号、删行标。任何答案内容改动都是红线。

3. 执行流程（S1–S10，严格按序）

S1 · 核对模板（不可跳过）

读模板第 1 行表头 + 第 2 行说明行，确认 20 列字段与顺序。不同版本模板列数可能不同，不许凭记忆写死。

• 模板第 2 行「导入前请删除此行」必须移除（导入器不会自动跳）。
• 模板自带示例行（如纯文本 作者是赵崇祚）就是「不带字母前缀」的基准，照它写。

S2 · 解析题源

按第 1.2 表选通道。docx 用保序读取；xls 用 xlrd；网页直连下载；OCR 走离线引擎。

> ⚠️ 写校验脚本前先 dump 前 6 行逐列打印（列号 + 表头 + 值）确认真实列映射，再写统计。
> 常见错法：「按 B 列是否为空区分大题/小题」——大题行 A/B 都填、小题行 A/B 都空，判定小题应用 B=='' and E!=''；取答案本体用 M 列（不是 G 列）。

S3 · 题目切分

自检：题号 1..N 连续无缺漏、无重号。

S4 · 题型归一（映射表）

> 遇到模板未覆盖或用户未明确的映射，先问用户，不要自创题型。

S5 · 字段提取与填列

按第 4 章的 20 列表逐个填。要点：

1. 独立题（单选/简答/填空）：题干 → D 列；E/F 列留空。
2. 组合题大题行：题型 → B 列；材料 → D 列；除 A/B/D/I/J/K 外全部留空（含 col2 自定义题型、col4 小题题型必须清空）。
3. 组合题小题行：A（目录）与 B（题目类型）留空；填 E 小题题型 / F 小题题干 / G 正确答案 / L 选项数 / M–T 选项。
4. 完形填空小题行不填「小题题干」，空位靠大题题干里的 ##n## 标记。
5. 组合题「填空题」小题的「正确答案」必须填选项列字母序列（单空 = A），答案本体写进「选项A」。
   （把真题词库字母 G / 段落字母 K 直接填进「正确答案」= 引用一个不存在的选项 → 越界。）
6. 简答/翻译/写作的答案与范文只能写进「选项A」，绝不能写进「答案解析」（会印到学生卷面上）。

S6 · 清洗与布局修复（自动化钩子）

在写文件时依次调用，顺序不可换：

regroup_xuanci → normalize → fix_cloze_markers → fill_cloze_substems
  → fix_simple_layout → strip_source_tags → fix_subjective_answer
  → pad_substem_opts → dedup_units → assert_clean

> ⚠️ 顺序铁律：strip_source_tags 必须在 dedup_units 之前——同题双份入库的副本往往只差一个水印/出处标注，不先清洗就判重会漏掉全部克隆。2026-09-25 实测：清洗前 16 件全绿，清洗后立刻暴露 14 行隐藏重复。

S6-a 简单题布局归位 fix_simple_layout()（2026-09-24 新增，最高优先级）

> ⚠️ 这是本 skill 最贵的一条经验：学习通规定简单题的题干必须在「大题题干」列；把真题干写在「小题题干」列、D 列写占位，解析器会把它判成「声明了小题却没有小题行」的组合题，于是整行静默丢弃、平台不报错、界面只显示题数变少。2026-09-24 初中两分包共 1000 道单选全部消失，排查数轮才定位。

S6-b 组合题小题题型归一 fill_cloze_substems()

• 小题题型只认『单选题』（学习通支持的词）。写『完型填空』会被判「小题题型为空或不支持」，整组拒收。
• 该钩子对已有值也要强制归一（只补空值会漏掉 540 行同病）。

S6-c 空位标记 fix_cloze_markers()

• 完形大题题干空位写成 ##1##…##M##，按下标编号，不用全卷题号。
• 空位来源格式多源不一：半角/全角空格包数字、数字粘词（not2enough）、编号 16-30 / 46-60 / 61-75。
• 用「独立数字候选的连续递增子序列唯一命中」算法定位，⚠️ 不能简单 find()：正文里 Oct. 11 / 45 / 50 / 95 是真实数字，会被误转。
• 非完型材料里的空位写成真题印刷形态 26 ______ / ______，不得写 ##n##。

S6-d 控制字符与非法字符：全表断言 \x01 == 0、'##' == 0（完型除外）、''' == 0、'【' == 0、选项内无 ___ / # / &。

S6-e 目录归一：目录列值统一形如 /高中/单项选择。⚠️ 残留 /高中英语/、/高职英语/ 会生成独立公开目录；/初中//初中/ 双前缀会被拼成怪路径。修源库 + 修生成器，两边都要。

S6-f 出处/版权/水印残留清洗 strip_source_tags()（2026-09-25 新增）

只处理题干两列（大题题干 D / 小题题干 F），不动解析列（G 的【评分维度】【词库】是合法标注）。清洗四类，保留三类：

> ⚠️ 实测坑：① 不能用「含【】才处理」做短路——裸水印没有【】；② 括号出处必须带出处关键词（届/期末/一模/联考/中学/卷…）才删，否则会误杀内文引用；③ 水印变体极多（21教育网 / 21cnjy / 2-1-c-n-j-y / www-2-1-cnjy-com / 中小学教育资源及组卷应用平台…），全档扫过一轮后必须再扫一轮确认清零。

S7 · 去重（平台视角，必须自己做）

因此导入前必须做单元原子级去重：

COMBO_TYPES = {"完型填空", "阅读理解", "共用选项题", "选做题"}

def row_sig(row):
    """平台视角指纹：只取平台判重相关的列"""
    nrm = lambda x: re.sub(r"\s+", "", str(x)).lower()
    cols = [row[1], row[3], row[4], row[5], row[6]]
    cols += [row[c] for c in range(12, min(29, len(row)))]
    return "\x01".join(nrm(c) for c in cols)

def dedup_units(rows):
    """组合题整单元原子去重；简单题行级去重。返回 (去重后行列表, 丢弃行数)"""
    seen_u, seen_r, out, i = set(), set(), [], 0
    while i < len(rows):
        if str(rows[i][1]).strip() in COMBO_TYPES:
            j = i + 1
            while j < len(rows) and not str(rows[j][1]).strip():
                j += 1                      # 扫到下一个大题行为止 = 一个完整单元
            ukey = "\x02".join(row_sig(r) for r in rows[i:j])
            if ukey not in seen_u:
                seen_u.add(ukey); out.extend(rows[i:j])
            i = j
        else:
            h = row_sig(rows[i])
            if h not in seen_r:
                seen_r.add(h); out.append(rows[i])
            i += 1
    return out, len(rows) - len(out)

> ⚠️ 行级去重会截断组合题：小题行被 fill_cloze_substems 清空小题题干后，兄弟小题指纹可能碰撞 → 跨组误删，一组只留 2/9/1/6 个小题而不报错。必须整单元判等。
> ⚠️ 指纹不能包含目录/标签/知识点/难度/解析——否则克隆题（仅这些列不同）漏放，被平台过滤掉反而丢题。

补充判重：跨批次并入同一题库时，除 id 判重外再加「正文前缀指纹」re.sub(r"[^a-z]","",p.lower())[:120]，并用 difflib.SequenceMatcher(...) > 0.85 做模糊兜底（实测漏检过 Jenifer / Jennifer 差一个字母的同篇）。断言：len({key(e["passage"]) for e in items}) == len(items)。

S8 · 切分包

• 单文件 ≤ 999 题（平台硬限 1000，取 999 留余量）。
• 优先按「目录 / 题型维度」切，好处是各分包目录列一致，导入后自动归并到同一目录树。
• 题量 = 独立题数 + 组合题组数（组合题整组只算 1 题，其下辖小题不单独计数）。
• 交付时主动分成多个文件并逐个标注题数，不给一个超限单文件。

S9 · 写出 .xls（五步原子写，缺一步不得收工）

• 用 xlwt 写 .xls（与模板同格式）；读用 xlrd。装包：pip install xlwt -i https://pypi.tuna.tsinghua.edu.cn/simple
• sheet 名固定 Sheet1；单元格内换行用 \n 并设 alignment.wrap=1
• 不要合并单元格、不要超链接、不要公式
• 目标目录名：学习通题库导入分包的命名规范 见第 4.4 节

> ⚠️ Workbook() 新建 + save() = 整表覆写，不是「追加」。补源/改库时若直接
> wb = xlwt.Workbook(); ...; wb.save(Path)，原库会被整表冲掉，只剩本次写进去的
> 内容，且不报错（2026-09-25 事故：高职阅读真源 100 单元/500 小题被冲成 53 单元）。
> 任何写 bank 真源 / 已有导入件的动作都必须走下面五步（内核已实现，直接调用，
> 不要自己再造一遍：from xls_common import write_atomic; write_atomic(path, rows)）：

# S9 标准写入模板：读现有 → 改 → 写临时 → 回读校验 → 原子替换
def write_atomic(path, rows, header, ncol=20):
    tmp = path + ".tmp_write"
    wb, ws = xlwt.Workbook(encoding="utf-8"), None
    ws = wb.add_sheet("Sheet1")
    for c, h in enumerate(header):
        ws.write(0, c, h)
    for ri, row in enumerate(rows, start=1):
        for ci, v in enumerate(row):
            if v == "" or v is None:
                continue                      # 跳过空值，别写 None
            ws.write(ri, ci, v)
    wb.save(tmp)
    # ① 回读：行数 + 逐格比对，任一对不上立刻删临时文件、放弃写入
    sh = xlrd.open_workbook(tmp).sheet_by_index(0)
    back = [[sh.cell_value(r, c) for c in range(sh.ncols)] for r in range(1, sh.nrows)]
    if len(back) != len(rows) or any(
            str(a[c]) != str(b[c])
            for a, b in zip(back, rows) for c in range(ncol)):
        os.remove(tmp)
        raise SystemExit("回读校验失败，已放弃写入 " + path)
    # ② 原子替换：避免写一半被打断留下坏文件
    os.replace(tmp, path)                     # 成功 → 删掉 .bak 之外的旧文件
    return len(back)

配套三条硬要求：

1. 写之前 shutil.copy2(path, path + ".bak_<日期>")，且备份要在改动前做。
2. 幂等：脚本能重复跑（已存在则跳过；drop_clones 之类的剔除要「再跑一次剔除 0」），
   否则下次重跑会重复追加或重复剔除。
3. 改完必须回读复核一次真实结果（单元数 / 小题数 / 关键列），不要相信内存里的 rows。

> 顺带：行序变了要同步重建伴生文件（答案 txt、溯源 md），见 A9。

S10 · 校验（第 5 章）

4. 输出规范

4.1 20 列结构与表头命名

标准表头（顺序不可变，与 importQuestionTemplateNew（题库导入模板）.xls 一致）：

目录 | 题目类型 | 自定义题型 | 大题题干 | 小题题型 | 小题题干 | 正确答案 | 答案解析
| 难易度 | 知识点 | 标签 | 选项数 | 选项A | 选项B | 选项C | 选项D
| 选项E | 选项F | 选项G | 选项H

> 模板无音频列、无图片列。

4.2 单元格填写规则（高频，逐条对照）

通用填充细则

1. NBSP（U+00A0）：平台渲染选项时按「字母 + .」与正文直接拼接、不补空格，所以必须自己在正文前补 1 个 NBSP。
   - ❌ 普通半角空格：浏览器按 HTML 空白折叠规则吃掉前导空格
   - ❌ 全角空格 U+3000：Java String.strip() 视其为空白，导入解析时剥掉
   - ✅ NBSP：浏览器不折叠；Character.isWhitespace('\u00a0') 为 false
   - 例外：填空题、简答题的「选项 A–H」列存的是答案/范文本体，补前导空格会污染参考答案、导致判错 → 必须跳过。
2. 多空答案字母序列：每位都要有对应选项列；某空多解时在该格用 ; 分隔。
3. 组合题小题行留空属合法（继承大题），校验报告里单独说明，不算空缺项。
4. 参考答案/范文只能进「选项A」，解析里放采分点、评分维度、句式得分点。

4.3 字符与编码

4.4 文件与目录命名

> 平台内目录 = 「目录」列的值，建议一个档位只保留一棵目录树；重导前先删平台旧目录（私有 高中 + 公开 高中英语 之类），否则叠加。

5. 校验清单（交付前自检 + 报错修正）

5.1 必跑自检（逐条断言，任一不过不得交付）

> 21~24 已并入 verify.py，与 1~20 一次跑完；val.py 不再单独使用（逻辑已迁入）。

5.2 常见报错与修正办法

6. 异常兜底与必须确认项

6.1 处理策略（按优先级）

6.2 必须向用户确认的问题（不确认不得自行决定）

1. 模板版本与列序（20 列是否一致）
2. 未覆盖的题型映射（如连线题、排序题、自定义题型）
3. 超 8 个选项（I–O）的选词填空/连线题如何落地
4. 音频、图片的挂接方式
5. 是否存在历史目录需先删除 / 是否需要先清空平台旧题库
6. 「知识点」列是否已在课程里建好同名节点
7. 答案与原卷冲突时的取舍
8. 某篇无可靠答案键时是「整篇剔除」还是「保留题干待人工补答」
9. 难度配比口径（如本科 3:5:2、大二 2:5:3 之类分档要求）

7. 最小示例：输入 → 输出字段映射

7.1 输入素材（节选）

(a) 单选题（原卷排版）

1. The earth _____ around the sun when I was eight.
   A. went     B. goes     C. will go     D. has gone
答案 B

(b) 完形填空题（原卷排版）

Complete the passage. Each blank has four choices.
It was a cold morning. She ______ early and lit the stove.
1. A) got up  B) get up  C) getting up  D) gets up    → 答案 A
2. A) lights   B) light    C) lit        D) luminous   → 答案 C

(c) 英译汉简答题

Part V Translation
1) As you have done the market survey, I'd like to discuss with you the possibility of selling our products in the US.
（无参考答案）

7.2 输出（XLS 前 20 列，索引 0–19）

> 说明：
> - <NBSP> = U+00A0。行 1/3 的题干里也加了 NBSP（题干空白占位不影响渲染，但选项列必须有）。
> - 行 2 是干扰行，不应存在——独立题只占 1 行（此题若写成两行即触发「声明小题却无小题行」，会被静默丢弃）。
> - 行 3–5 是完型单元：大题行 ##1##/##2## 与两个小题行一一对应；小题行 A/B 两列留空，答案写在「正确答案」列、选项写在选项列。
> - 行 6 英译汉：正确答案=A、选项A=译文、选项数=1，译文放选项A 而非答案解析（放解析会印到卷面）。

7.3 校验对照

附录 A：规则库索引（历史坑集，已去重编号）

> 以下条目为历次实测沉淀，与正文规则一致但更具体，遇到对应症状时查这里。

A1 · 平台会补什么，你就不写什么（同源于坑 1/2/3）
选项列补字母 → 不写字母；题干补题号 → 不写题号；空格不补 → 自己补 NBSP。最省事的自检是把模板示例行当基准逐字比对。

A2 · 题库题量口径（2026-09-12 B3 全库实测，10/10 零误差）
共 N 题 = 独立题数 + 组合题组数，组合题整组算 1 题。用户报「题数变少」时的诊断顺序：① 先用该口径复算；② 再查是否组合题被拒收；③ 最后去原卷确认分节数差异。不要凭「同一套卷应该一样」回改数据。

A3 · 大编号题源（空位全局连续编号）三条铁律（2026-09-13）
① 篇章切分靠「编号按每篇空数成组」的全局不变量，不靠分隔句；
② 锚定用「逐号顺搜」(?<![\d．\.])N(?![\d]) 跳过正文数字；OCR 把编号变裸下划线时按「裸下划线(≥3) + 紧跟 (word) + gap>1」回补；
③ 渲染只能「按已知坐标替换」，绝不用正则扫全文数字（会把 2025、16th-century、1960s 吞成空位）。
附：Passage N 标题行必须整行剥除；sentence_bounds 需先跨过空位标记再找句末标点；OCR 重复块按「不同编号集合覆盖率 ≥ 70%」裁掉。

A4 · 语法填空编号区间按卷型不同（2026-09-13）
| 卷型 | 编号 | lo/hi/off |
|---|---|---|
| 新高考 I/II、浙江卷 | 56–65 | 56/65/55 |
| 全国甲/乙卷、2014–2020 全国卷 | 61–70 | 61/70/60 |
| 北京卷 2021+ | 11–20 | 11/20/10 |
| 北京卷 2019/2020 | 1–10 | 1/10/0 |
⚠️ 区间逐卷核对原卷，不能按卷种想当然。北京卷 2021 起由 1–10 改为 11–20。

A5 · 公网抓取通道分级（2026-09-13）
| 通道 | 可用性 |
|---|---|
| zy.21cnjy.com/<id> | ✅ 首选（原文+选项+答案+解析一次拿全） |
| mip.21cnjy.com/P/<id>.html、m.51jiaoxi.com/doc-*.html | ✅ |
| bigxun.com、zxxk.com | ✅ 作第二源 |
| renrendoc.com、wenku.baidu.com | ⚠️ 抓不到正文，但搜索片段常带完整答案键 |
| gzyy.cooco.net.cn | ❌ |
大批量补源时拆给多个检索子代理并行（每篇 ≥2 独立源、失败如实报、严禁编造）。

A6 · 答案冲突裁决（2026-09-13 Zafirakou 篇）
汇编类/精校类文档最爱把相邻段落信息安错人安错题。冲突时：① 比对选项原文（不一致 ⇒ 弃非真题那一方）；② 一致则拿原文定位句判定；③ 仍无法调和 ⇒ 整篇剔除。

A7 · 双栏 PDF 抽取的交叉核验陷阱（2026-09-15）
用盘上解析 txt 做自动比对前先 re.sub(r"【\s*\d+\s*】", " ", disk)；命中率低时按区域 dump 人工逐句核，严禁据自动指标判错。汉译英的盘上答案只有英文译文，不能用中文原文特征串做覆盖检测。

A8 · 规模化抓题必须配独立答案审计代理（2026-09-15 CET-4 Sprint3）
随机抽检发现 1 处真错 ⇒ 全量复核。每个审计代理「先自行求解、不看已记录答案」，再与 ≥2 独立源比对，只输出 {source, stem_head, recorded, verdict, confidence, evidence}；low 一律 DROP 而非改字母。定位键统一用「题干 strip() 后前 40 字符」——先截断再 strip 会因换行造成静默失配。反例警示：假订正与漏订正同样有害。

A9 · 伴生文件必须按「XLS 输出行序」生成（2026-09-15）
症状：Gate1 报「答案序列不一致」，肉眼逐题却全对。根因：XLS 按目录/维度分组写出，答案 txt 按取数顺序写 → 整体错位。生成答案文档时直接遍历最终写出的行。

A10 · 难度配比
主观题无难度公式，用分位法（25%/75%）按题量切易/中/难；⚠️ 分数离散时改用「秩次法」（按 (score, 序号) 排序后取秩位切点），否则分位法会落在一堆同分值中间（实测从 23/40/37 修到精确 0.25/0.5/0.25）。

A11 · 自建校验器的坑（两条都实测过）

① 用 _{2,}(?!\s*[（(]) 判「该空无提示词」会失效——负向前瞻失败后 _{2,} 回溯到更短匹配使 (?!) 成立，产出大量假告警。正解：两遍法，先收集「带括注」的空号集合，其余即无提示词。

② 判 NBSP 前只能用 ASCII 空白 strip：str.strip() / lstrip() 默认会把 \xa0 当空白剥掉，于是「已正确加 NBSP」被判成「缺 NBSP」，全表假告警（2026-09-25 verify.py 首测即中招）。正解：v.lstrip(" \t\r\n")，空判定用 v.strip(" \t\r\n")。

③ 「跳过后续小题行」必须另用游标 j 从 i+1 起，不能拿已有的 i 做自增循环变量——写成

while i < len(rows) and not rows[i][1].strip(): i += 1   # ← 错：题型非空时立即为 False，i 不前进

会让外层 while i < len(rows) 空转死循环（2026-09-25 实测 verify.py 卡死 3 分钟、faulthandler 才定位到行号）。正确写法是

j = i + 1
while j < len(rows) and not rows[j][1].strip(): j += 1
i = j

A12 · 「已有标签」会误导你以为某卷空白（2026-09-15）
已入库条目可能标注为「全国」「海南」却实为「2020 新高考I 卷 C/B 篇」。抓取整卷前先拉现有 id 清单逐条核对卷别，合并时把疑似重复全打 skip 人工过目，绝不直接覆盖。

A13 · write_xls() 的表头会被写两遍（2026-09-25）
入参既可能是「已含表头」（build() 的返回形态），也可能是「纯数据行」。三处必踩：
① 无条件写表头 + 数据从 enumerate(rows, start=1) → 表头重复、整表行号 +1；
② 只改 start 不改 body → 多出一行空白、表头被推到第 2 行；
③ 判断出「已含表头」却只写数据不写表头 → 表头行全空。
正解：has_hdr = rows[0] == HEADER，body = rows[1:] if has_hdr else rows，
表头行单独写一行（取值优先用原表头），数据 enumerate(body, start=1)。
症状：某文件突然多 1 行、行号整体错位、题量虚高 1，进而误判「1000 > 999 超限」。

A14 · 答案文档与导入件的「同名配对」几乎永远失败（2026-09-25）
答案文档按单题库拆（初中_单项选择_ans.txt 之类），导入件按档/分包切，
名字天然对不上 —— 16 件交付件当初全部报「未配对、跳过比对」，等于第 24 项在真实
交付上从没跑过。且按下标硬比必然报「首个差异 #1」：单库答案在整卷里只是中间一块。
正解：用 difflib.SequenceMatcher 把「题库序列」当 a、「文档序列」当 b 求 opcodes，
只在 replace/insert/delete 里逐格比并带上该单元对应的物理行号，
覆盖率 ≥50% 才判配对成功，≥0.9 的差异才判 FAIL（配对可信），低覆盖只 WARN。

A15 · 「整表覆写」事故：xlwt.Workbook() 新建 + save() 不是追加（2026-09-25）
症状：不报错，但被写的库从 100 单元/500 小题变成 53 单元/318 行，题量凭空少一半，
且「少了的那一批」查无遗迹（内存里的 rows 看着是对的，只有落盘结果不对）。
根因：xlwt.Workbook() 起的是一张空表，save() 直接覆盖目标文件，少了「读旧 + 合并」一步。
正解：五步原子写（读现有 → 改 → 写临时 → 回读校验 → os.replace，模板见 S9），
外加三条配套：.bak_<日期> 备份、脚本幂等、落盘后立刻 xlrd 回读断言单元数/小题数/关键列。

> 同类错误的另一面：只删导入件不动 bank 真源 → 下次重跑生成器原样带回；
> 只删 bank 真源不重跑生成器 → 导入件与真源不一致。二者必须同批落地，
> 并以「真源再跑 drop_clones 剔除 0」验证幂等（高职阅读 / 大三语法填空两轮均照此执行）。

A16 · 删克隆要按「小题集合指纹」，不是「全单元指纹」（2026-09-25）
克隆对只在篇章/解析/篇号上有差异 → 用「小题题干+答案+选项」排序后的集合指纹判重
（_sub_fp），而不是整单元拼接指纹。顺序铁律：先 drop_clones()，再 dedup_units()，
反了会被行级去重截成半截组合题。判完必须人工抽验 8–10 篇，确认每篇小题数与空位数一致。

A17 · 清理类操作的「假绿」陷阱：命中数 vs 归档条目数必须双印证（2026-09-25）
批量删 .log / .bak 类脏数据时，若「扫描清单」与「执行脚本」相隔数分钟（跨工具调用很常见），
目标可能已被外部删除（手工清理 / 同步盘 / 其它进程），脚本会静默命中 0 并在报告里写成已清理。
两条硬要求：① 归档 zip 的条目数与命中数必须一致——zipfile.ZipFile(z).namelist() 自查；
② 执行前再 os.path.exists() 复测一次总数。任一项不符即如实上报「该批未被本轮删除」，
不得含糊写成「已清理」。另：匹配备份别只写 .bak_20260925，…_xls.bak_item17_20260925
这类前后缀变体要单独列，否则会漏。
再次命中（09-25 夜间）：dry-run 报「可删 56 个」，执行时归档只收进 38 条，差 18 个。
这一批同样是被外部删的。凡 dry-run 数与归档条目数不等，一律按「有文件在本轮之外消失」上报，
不要解释成"预估误差"。

A18 · 删备份前先 grep「谁在读取它」（2026-09-25）
.bak 不一定只读不写——有些脚本把它当输入基表。09-25 实测：bank_quota.json.bak_20260920_大二入账
被 _work/_quota_fix_daer.py 读取、…_p3b 被 patch_ledger_p3b.py 读取、…_p6_junior 被
patch_ledger_p6.py/p6b.py 读取。删了不会报错，只会让这些脚本下次崩在文件打开上。
删除任何 .bak 前必做：grep -rn "\.bak" --include="*.py" 全库扫一遍，命中的一律进保留清单。

A19 · 备份的四种定性（决定删/留，别只看后缀）（2026-09-25）

判定脚本自身两个反直觉陷阱（都真实踩过，会直接误判）：
① os.path.splitext('x.json.bak_20260920') 拿不到基名 → 所有条目被当成"无同族正式件"（误判 B）；
改用 split 法：name.split('.bak')[0] 之类逐令牌剥离。
② 修好基名后又出现自匹配——怪名文件把自己的变形当成同族正式件，判成 A1 冗余被误删；
必须显式排除自身路径：if os.path.abspath(sib) == os.path.abspath(p): sib = None。
③ 易误判为 B 的一类：_work/backup_20260924/*.xls（"前目录归一"快照，正式件已迁移到别处）——
这类是真唯一副本，必须留。

参考脚本（本 skill 的 scripts/ 目录）

按「先取素材 → 再构建 → 后校验 → 出报告」的顺序使用。

收工前 checklist（照抄执行）

1. 自检清单 1~24 项全部通过，输出报告。
2. 逐份清点题量（本地口径 + 学习通口径并列），与官方答案键比对「0 错 0 警」。
3. 报告固定包含三块：① 逐份清单；② 需人工补全（音频 / 图片挂接）；③ 原卷疑点与异常题目。
4. 明确告知用户：图片/音频需在学习通题目编辑页手动挂接；知识点列需课程里先建同名节点。
5. 提醒用户：重导前先删平台旧目录；组合题文件不可重复导入（平台不去重）。
6. 凡写过 XLS 的，落盘后回读复核一次（行数 / 单元数 / 关键列），并把备份路径写进报告；
   改过行序的，同步重建答案 txt 等伴生文件。