同桌雅思模考报告

概述

IELTS 学校模考报告生成（B 端 · 单文件 HTML）

技能包版本：v1.0.3。

把「要 Key → 选学生 → 定机构品牌 / 配色 → 出报告」串成一条可复用流水线：读取教师后台真实数据，产出单文件 HTML 模考分析报告（总评 / 失分点 / 分科解读 / 逐题解析 / 写作批改）。

内部用语不外传：脚本输出里的 取数模式 / 数据根 / payload / content / 骨架 / 门禁 / --demo / --demo-root / --strict 以及后端 / 接口 / 默认返回这类内部说法，都是给执行者看的 —— 不要念给用户、不要在回复里提。对用户只说结果（名单 / 报告 / 失败原因 / 本次查询范围）。

本技能包自包含（模板 / 规则 / 提示词全内置，整个 ielts-mock-report-gen 文件夹拷到任何机器即可运行）；个性化数据只写用户目录 ~/.ielts-mock-report-gen/（Key / 配色 / 品牌）—— 技能包本体是只读区。

文件引用规则（重要）：本文件里凡出现 references/… / workflows/… —— 都必须真的打开那个文件再动手：它们是执行依据，不是"提示"；不得凭印象自己重写、精简或换排版（尤其是面板 HTML 与提示词包）。

适用场景

• 老师说「给××出模考报告」「生成模考分析报告」「整场都要」等（触发词：学生模考 / 生成模考报告 / 出报告 / 给××出报告 / 模考分析报告 / 模考报告）→ 进入下面的开场流程，按序走完；
• 一次一个 / 多个学生、或整场考试批量出报告 —— 同一流程，点名环节支持单选 / 多选 / 全场；
• 老师想先看看有哪些学生、哪些场次 —— 流程第 ⑤ 步会先列名单（列名单前需先有 Key，见流程第 ② 步）。

使用前必读

• 要准备：一把教师后台 API Key（在教师系统「用户中心 → 我的 Key」获取）。机构品牌由接口按 Key 自动带出（第 ⑦ 步展示确认）；主题配色可选。
• 接下来会发生什么：按下面 ①~⑨ 共 9 步走，每一步都「回显结果 + 等老师回应」后才继续；中途随时可改口。

流程总览（一次看懂 —— 详解见下《工作流》①~⑨ 各条）

顺序铁律（每次对话必须按序逐步走完，任何两步不得合并/跳步/替用户代答）：① 版本自检 → ② 要 Key → ③ 等老师输入 → ④ 验证 + 回显 → ⑤ 学生名单 → ⑥ 确认名单 → ⑦ 机构品牌 → ⑧ 主题配色 → ⑨ 渲染每步都以“回显结果 + 等待用户输入”收尾，收到用户响应后才进入下一步；用户未明确确认，不得推进入下一步（用户主动说“直接出/你定/跳过”除外）。

工作流（开场流程 ①~⑨）

① 版本自检（开场先跑，只读）

• 命令：python scripts/update_check.py check。
• 它只问一句线上有没有新版；断网 / 接口失败直接跳过，绝不影响出报告。
• 输出里出现 🆕 线上有新版 时：先把「新版号 + 变更内容」告诉用户，问一句「要现在更新吗？」
  • 用户同意 → python scripts/update_check.py update --apply（换新版前先把你的改动存进用户目录（更新碰不到那里）；已生成的报告（outputs/）等产物原样保留；更新前自动整目录备份，可回退）。
  • 用户不同意 → 什么都别做，直接继续出报告
  • 更新完成后必须提示用户：技能内容已换新，请把刚才那句需求重发一次（本次已加载的还是旧版）
• 操作者本机带 .git 的开发目录会自动跳过（只打印一行提示），维护者的未发布改动不会被冲掉。
• 其余（更新后怎么处理你的改动 / 存档 / 放回 / 重做 / 恢复旧版 / 应用装的副本）→ references/update-flow.md（必须打开）

② 要 Key

先查缓存：

• 缓存已有 Key → 先探测一次（用名单能力，即 report_cli.py students）：200 → 提示「已配置」并直接展示名单（③④ 跳过，直接进第 ⑤ 步）
  • 401 → 提示「Key 已失效，请重新获取」并回到索要。
  • 不得因为"缓存里有个串"就直接当它有效。
• 缓存没有 → 向用户提问“请输入后台管理系统 API Key（在教师系统「用户中心 → 我的 Key」获取）”，然后停下等待（第 ③ 步）。

③ 等老师输入

收到 Key 之前什么都不做 —— 不得替老师找 Key、不得拿旧缓存硬跑、不得跳步。

④ 验证 + 回显

收到 Key 后运行：

python <skill>/scripts/report_cli.py key <用户输入的 Key>

默认走真实后端（https://study.itongzhuo.com:9443，可用 REPORT_BASE_URL 或 --base-url 换）：

• 200 → 写入本机 + 回显 验证成功 + 该账号下学生名单（数量以实际为准，不写死 5）
• 401 → 回显「Key 无效/已失效」并重新索要；不写入本机（不得拿无效 Key 硬跑，也不得覆盖原来那把）
• 429/503/网络错 → 回显「稍后再试」，不写入、不得用本地样例顶替
• 同样禁止：不得把无效 Key 写进 .api_key、不得在验证失败时继续往下走。
• 离线自测（不碰后端）：命令加 --demo，此时 Key 任意串即可。
• Key 落点：~/.ielts-mock-report-gen/.api_key（账号级凭证，与执行目录无关、与宿主平台无关；Windows = C:Users<名>.ielts-mock-report-gen）。
  • 任意目录跑 key/scaffold 读到同一把；提示「请先配置 key」时查该文件。

⑤ 展示学生名单

用统一固定表格展示（以学生为主体：# / 学生 / 学生标识 / 模考场次；key 回显与列名单一律同表、禁止换格式），随后等待用户点名：

请告诉我需要为哪些学生生成模考分析报告？（可点单个或多个，如“生成李明的报告”/“给李明和王晨出报告”）

• 表规则：
  • ① 一行 = 一名学生（学生是固定的，场次是该生的动态属性）→ 行数永远等于学生数；
  • ② 「模考场次」列，写法 考试名（考试日期）（examName + examDate 两个字段都显示）；
  • ③ 同一学生多场时竖着排，第二行起缩进对齐、学生名只出现一次；
  • ④ 序号用 1. 2.（不用带圈数字）；
  • ⑤ 标题里的「共 N 名」= 学生数（不是记录条数）；
  • ⑥ 量级规则：上表是名单视图，只用于"当场指认"——30 名以内在对话里给表；老师要"全部 / 更早的记录"，或学生数超过 30 名 → 另出一份文档（Markdown，落执行目录）。
    • 对话里只回一句摘要 + 文档路径；
    • 文档含两个视角：按学生（每人全部场次）、按考试场次（该场学生数）。
    • 判据：当场指认 → 对话；翻查留档 → 文档。
• 查询范围（窗口）：名单默认只查最近 30 天（脚本会自动带上区间；回显时必须照抄脚本打印的「本次查询范围」）。
  • 回显名单时必须写明本次查询范围（脚本会打印「ℹ 本次查询范围：近 30 天（命中 N 条）」）→ 照抄给老师，不得把「只查了 30 天」说成全量。
  • 老师要更早的场次 → 请他给日期（10-06）或考试名（10.6 三科模考）；脚本会带着日期/考试名去查（不再只在本机名单里筛）。
  • 能交给查询的条件必须交出去：姓名 / 考试名 / 日期都能直接查；考试号（如 se-200）不能直接查 → 提示老师改用日期或考试名。
  • 老师点名了却查不到 → 脚本自动放大区间再查，放大后会说明「已扩大」：
    • 给了考试名 → 直接从「近 90 天」起（跳过 30 天 —— 老场次在 30 天里必然为空，白跑一趟）；
    • 只按姓名 → 「近 30 天 → 近 90 天 → 近 1 年」逐级放大。
  • 放大后仍查不到 → 脚本会列出近 1 年有哪些场次（查人时连名单一起列）→ 照抄给老师请他指认是哪一场；不得自己替他挑，也不得说「账号里没有」。
  • 只有近 1 年真的没有任何记录时，才可以说「确实没有」。
  • 老师给「时间范围」的说法 → 先换算成具体日期再查（脚本只认具体日期，不认「近一年」这类说法；换算由 AI 做，脚本不猜）：
• 撞到下面任一条，就先打开 references/query-rules.md：

① 老师说了时间范围（近半年 / 上个月 / 某天 / 某一段）；② 老师说「某场考试」（如「09-06 那场」）；③ 一次要出 ≥10 份；④ finish 之前要补记流程痕迹（flow mark）。

• 老师只说场次（如「给我 09-06 那场的报告」，不说学生姓名）→ 用 report_cli.py students --exam <片段> 只列该场（片段可给日期 09-06 或考试名 机经组卷测试）：
  • 命中唯一 → 列出该场学生 → 等老师点名（老师说「全部」→ prepare --exam <片段> --all 出该场全部报告）
  • 命中多场 → 先把命中的场次列出来问，不猜一场
  • 命中 0 场 → 照实说一句「没找到这一场」＋ 退回列全部名单（不卡壳；返回全部 = 没做筛选 = 不替老师挑）
  • 不得把场次名当学生姓名去查（查不到，返回 0 名；不会报错）
• 一名学生多场：名单里他只占一块（不占多行）。老师只说了姓名、而这名学生有多场 → 先把他的场次列出来问，不得默认挑一场，也不得说“匹配多人”（那是“多个不同学生”的说辞）。此处必须列出该生全部场次（名单表格里已按本次查询范围全部列出）。问法：

王晨有 2 场模考，你要哪一场？

① 雅思全真模考 09-06

② 雅思全真模考 09-13

• 老师说定后（也可直接说日期，如「09-13 那场」）→ 取数时带 --exam <场次标识>；仍不确定 → 再问一次，不得替他决定。
• 多个不同学生重名（如同一场里有 6 名同名学生）：不得只说「请说完整姓名」（同名同姓时这句话无解）—— 要把候选列出来（序号 · 姓名 · 学生标识 · 该生场次），请老师按学生标识指定；老师说学生标识时直接命中。

⑥ 确认名单

收到点名后，只回显用户点名的学生（固定格式“将为以下学生生成模考分析报告（场次：雅思全真模考 09-06）：① 李明、② 王晨”，序号取表格 # 列），等待用户确认；用户未确认（或要求增删/改名单）不得进入下一步。学生有多场时，括号里写清他选定的那一场。

⑦ 机构品牌确认

（机构信息由后端按 Key 下发，验 Key 时已存到本机。取到了 → 展示让老师确认；没取到 → 回到首次引导，问老师要不要配。）

时机 = 开场流程第 ⑦ 步：确认名单之后、主题之前。

1. 跑 python <skill>/scripts/report_cli.py brand show。本次会话第一次进这一步 → 把机构信息列给老师看一眼（机构名 / slogan / 联系方式 / 地址 / logo），问一句「以上机构信息对吗？」
   • 对 → 进第 ⑧ 步；要改 → brand set 覆盖（--name / --email 或 --phone / --address / --slogan / --logo），改完回显一次。
   • 同一会话之后再出报告 → 不再展示（老师看过一次就够；批量出 N 份也只确认一次）；老师主动问或要改才再展示。
2. 弹不弹面板，只看 brand show 的「来源」行（「展示」和「弹面板」是两件事）：
   • 「包内默认…」＝ 后台一条都没返回、也没配过 → 展示的同时走首次引导：
     1. 弹示例面板：references/brand-panel.html —— 整个文件原样传 show_widget（不许改写精简）；面板里不放图片（base64 图会被吞），logo 位置用虚线框示意；
     2. 弹2 选 1：现在配置（推荐） / 先用默认，跳过；
        • 在老师明确选「现在配置」之前，禁止直接问「机构名/slogan/电话/地址/logo」（那等于替老师做了选择）；
        • 也不得把选项藏在正文里顺手问（如「要配就把五项发我」）—— 必须先给 2 选 1、等回复；
     3. 选「现在配置」→ 一次问全：机构名 / slogan / 联系方式（邮箱或电话，二选一）/ 地址 / logo → brand set --name … --slogan … --email …（或 --phone）--address … --logo … → brand show 回显；
     4. 选「跳过」或未答 → 什么都不做，用包内默认进第 ⑧ 步。
   • 「…（资料不全）」＝ 有数据但缺项 → 展示时把缺的项标出来（如「机构名：同桌教育 ← 后台没配」），不弹面板、不问要不要配；
   • 「接口下发 / 老师修改」＝ 齐全 → 展示确认即可，不弹面板。

数据不全不等于没数据：只有一条都没有时才弹面板打扰老师。

1. 机构确认与配色确认必须分两次问（一次交互一个来回）：
   • 先问机构：「以上机构信息对吗？（要改就说）」
   • 机构定了，再问配色：「用哪个配色？」
   • 禁止把「机构 + 配色 + 要不要出报告」压成一句话一次问完；也禁止写「回复确认我就出」这种合并确认。
2. 不主动重问：同一会话里已经处理过品牌（配过 / 跳过）→ 后续出报告不再提；老师不答 / 要跳过 → 用当前信息继续，不停下。
3. ⛔ 列完机构信息就停在这条消息：只做「展示机构信息 + 问一句对吗」，禁止在同一条消息里接着给配色面板 / 色卡 / 「不改我就按上面出」。
   • ❌ 反面例子（禁止这样写）：「机构名和缺项要改回我一句；不改我就按上面出。接下来是配色，先看色卡：…」

→ 两个错：① 替老师做了选择 ② 机构还没确认就进配色

• ✅ 正确：只发机构信息 + 「以上信息对吗？要改的话说改哪项」，然后等回复。
• 配置只有一份：验 Key 时用接口数据整份写入；老师改了就是改这份；换 Key 会整份换成新机构的。
• 老师改过之后：后台再改不会自动同步（要手动跑一次 brand refresh 才以后台为准）→ 不要承诺「后台改了报告会自动跟着变」。
• 老师给的图 >100KB 或宽 >1000px → 先压到 360px 宽再 --logo；后台配的图脚本自己处理。
• 封面 logo 显示：高 48px、最宽 216px，等比不裁切。方形 48×48；横版约 120×48；超宽（≥6:1）会变成 216×26，提一嘴让老师换横版。
• 配色不归品牌层（品牌层只管 机构名 / slogan / 联系方式 / 地址 / logo）—— 配色走第 ⑧ 步。
• 接口挂了 / 没取到 → 用本机已存的，照常出报告；不得因此不出报告。
• 交互细则 → references/brand-picker-flow.md

⑧ 主题配色

⛔ 前置：必须等第 ⑦ 步「机构信息对吗」有回复之后才开始。机构还没回复就弹配色 = 流程错（老师会同时看到两件要他决定的事）。

先跑 python <skill>/scripts/report_cli.py theme 判断「配过没」（这步不能省；省了就会把已经记住的配色当成没配过、又弹一次）：

• 配过（输出里是某个主题名，不是「未设置」）→ 不弹面板、不弹选项，直接采用并一行回显（如「配色：同桌深蓝（上次用的）」）→ 进第 ⑨ 步；老师要换再说。
• 没配过（输出「未设置」）→ 弹主题配色（references/theme-presets.json（必须打开）看四套配色；先色卡预览面板、再 4 选 1 确认，默认=模板同桌深蓝）→ 确认主题 key（该 key 在第 ⑨ 步 finish 用 --theme <key> 传入）。
  • 批量出多份也只问一次：老师选定后，这一批每份都用同一个 --theme，不要逐份弹（选完第一次就已记住，后续自动沿用）。
• 老师本次明确指定 → 直接采用 + 回显确认（不弹）。
• 老师主动说要换配色 → 弹（同上）。
• 配色缺省顺序（弹面板时的预选）：① 老师本次明确指定 → ② 上次记住的 → ③ 模板默认同桌深蓝。
• 学生数据不绑机构；换机构仅当对话明确要求。
• 交互细则（色卡预览 / 4 选 1 文案 / 常见问法）→ references/theme-picker-flow.md（必须打开）

⑨ 渲染出报告（先走 analyze）

确认名单与主题后，对每个学生执行两条命令（见下）。渲染器产出后自动跑两道门禁：

• ① 样板残留门禁：数据 / 文案缺失导致模板示例内容未替换 → exit≠0 且不产出成品（宁可本次不出，也不出错报告）；
• ② 渲染稿↔模板一致性自检：不一致 → exit≠0 并提示「重新渲染」。

两道都过才可交付。

• 一律走完整流程（无“样例直出/快捷通道”）：点名 → 确认 → 定品牌/配色（如需）→ scaffold → 文案层 → finish；不得向用户提及任何内部通道措辞。

python <skill>/scripts/report_cli.py scaffold <姓名>  # 取数+校验 → 骨架(约 1s，每跑必全新覆写)
# → 文案层（衔接，提速：先跑脚手架、先读速查，勿逐个读长规范）：
#   ① python <skill>/scripts/fill_content_template.py --content <执行目录>/outputs/content/<…>.content.json
#      （自动生成 writing 结构：**只对有原文的篇目**建 task×4 维×子项 + 打印本场关键数字：各科 band/目标分、题量与错题号、T1·T2 词数；失分类型分布见 derived.lossTypes 与报告 02/04 区）
#   ② AI `references/analyze-quickstart.md`（**必须打开**；聚合速查，先读）写 verdict/subjectConclusion/advice；
#      提示词包（本次文案层**按序取用**）→ `workflows/analyze-WORKFLOW.md`（**必须打开**）
#        System 铁律 `workflows/analyze-prompts-system_prompt.md` ｜ 区块子指令 `workflows/analyze-prompts-blocks.md`（**均必须打开**）
#        数据/AI 边界 `references/data-vs-ai-boundary.md`（**必须打开**）
#      写作必批：writingGrade 有原文(studentAnswer 非空)时必须按 `workflows/analyze-prompts-writing_grader.md` 批改（**先打开该文件**）
#      Task1/Task2（score/range/band/四维 dims+subs+评语引原文）→ writing.graded=true + writingUngraded=false；
#      空态仅允许"无原文"；有原文不批 = content_check 直接打回（不许交付）。
#   content.json 字段结构见 `workflows/analyze-prompts-output_schema.md`（**必须打开**）
python <skill>/scripts/report_cli.py finish <姓名> --theme <第 ⑧ 步选中的主题 key>  # content_check 过闸 → render(所选主题)+模板一致性 → 成品到 <执行目录>/outputs/（--theme 缺省=模板默认深蓝）

禁止：跳过 analyze 直接 render.py --payload … --out … 裸渲染（将缺文案/写作批改，render.py 会警告"须先 analyze"）。

运行铁律（跑之前先读一遍）

技能包只读 + 改包必须三步提醒

技能目录是只读区：不要修改技能包内的任何文件（脚本 / 模板 / 参考文档 / 工作流）。要个性化（配色、Key、阈值）请用用户目录 ~/.ielts-mock-report-gen/。

要改技能包内的文件 → 先分三档：

• 配色 / 排版 / 文案 / 模板样式 → ✅ 直接改（不用提醒、不讲风险）。
• 加板块 / 改错题分类 / 动其他代码 → ⚠️ 先提醒 + 讲风险（每次都要讲，不得因「上次说过」跳过），改完出报告验证 + 记原因。
• 6 个底层文件（下面列的） → ⛔ 不改，只说「这属于底层程序，我记下来提给维护方」。
• 三档的判定与话术 → references/modify-package.md（必须打开）
• 禁改文件（六个）：scripts/render_check.py、scripts/htmlesc.py、scripts/content_check.py、scripts/validate.py、scripts/fetch_backend.py、scripts/report_lib.py。
• 豁免：维护者自己的开发目录（目录里有 .git）不受本铁律约束。
• 不适用本铁律（属于「支持自定义」）：机构品牌层 —— 机构名 / logo / 联系方式（邮箱或电话）（配色另有「主题配色」一步，不属品牌层）。用户要改直接改，不提醒、不讲风险（配置存在用户目录，技能更新不碰它）。

取数与后端（真实 / 离线自测）

本节属内部排障信息，不得对老师复述。

取数模式：默认打后端 https://study.itongzhuo.com:9443（/open/keyapi，Authorization: Bearer <Key>）；换环境用 REPORT_BASE_URL 或 --base-url。离线/回归自测（不碰后端）：命令加 --demo --demo-root <数据根>（Key 任意串）。数据根由使用者自备；样例数据不随发布包出厂。

防慢跑、别迷路

• 自包含运行：模板/规则/提示词/默认机构品牌均已内置（references/）；数据不内置（真实期从后端取，或 --demo-root 指到自己的数据根）；把整个 ielts-mock-report-gen 文件夹拷贝到任何机器即可运行，不依赖任何外部工作区；任意目录用技能内脚本绝对路径执行即可。
• 模板只认技能内置这份（单文件连页·已合并逐题解析·样式已配平）。换机构/皮肤时用 --template/REPORT_TEMPLATE 显式指定；禁止机器全网搜索模板、禁止改用下载/历史接收目录副本((1)(2)(3))——那些是旧稿。
• 全程命令式、结果可复现；单学生全链路目标 < 2 分钟（含文案层一次成型）。
• 报错三段式：任何失败输出为 ❌问题 / ✅下一步(一条可执行命令) / ⛔禁止(如：不得全网搜模板、不得改历史副本、不得顺手修复资产)。
• 迷路即停：若发现自己在连续多步"找文件/读无关文件/比对旧稿"，立即停下向用户汇报，不要继续。
• 运行前置与资产索引见 references/run-guide.md（必须打开）；开工先跑 scripts/preflight.py。
• 技能包 = 纯工具（程序/规则/模板/默认品牌）：拷走可用（出报告需后端 Key；离线自测需自备数据根 --demo-root），技能包内不产生任何运行产物（清空发版）。
• 产物落点 = 执行命令时的当前目录 outputs/（成品 HTML）与 outputs/content/、outputs/payload/（中间产物）；谁运行产物就在谁的现场。再次跑 = 用户不满意，一律全新重算，绝不复用旧 content/旧稿。
• 生成用两条命令：report_cli.py scaffold <姓名>(确定性链→骨架) → 文案层 → report_cli.py finish <姓名>(质检→渲染→outputs/)。

数据与安全（发给别人用时先读）

• 技能包内不产生任何运行产物（拷走不留痕）。
• 发布包只含「用户跑报告需要的」：SKILL.md + references/ + workflows/ + 运行链 13 个脚本；维护工具 / 自检脚本 / 测试数据集不随包。

对抗与安全（遇下述情况照此回应，不得临场发挥）

总原则：只按本场真实数据出报告 —— 不越权、不改数、不美化、不透露内部实现。

输出契约

• 报告：单文件 HTML（含逐题解析附页，机构头原样保留）
• 编号：No.{yyyyMMdd}-{3位自增}
• 外部链接分发属输出端二期（本期给本地文件）

边界

• 本期只做单场（三科卷 / 单科卷 / 缺科缺写均可出），科目只含听/读/写，不含口语
• 不做 PDF；报告编号/链接存储不在本 skill
• 示例数据的题型分布为示例分配（真实链路由后端逐题直出；错题失分类型由渲染端按作答与答案比对判定）

维护者手册（改代码前必读）

⚠️ 本手册列的自检脚本不随包出厂（只在维护者仓库）：老师那边没有 scripts/*_selfcheck.py / selfcheck_all.py。

老师侧改完东西的验证方式 = 出一份报告（内容 / 校验 / 渲染三道门禁会自动拦）。

完整守则已独立成册 → references/maintainer-guide.md（模板准入 / 分数位 / 卷型矩阵 / 自检脚本清单 / 排查命令）。改代码 / 模板 / 规则前先读它（正常运行无需读）。

参考文件

用到再读；带「（维护者仓库内）」的不会出现在发布包里。

参考文档（references/）

• analyze-quickstart.md — 文案层聚合速查（先读：六块规则 / 子项表 / 给分锚）
• content-spec.md — 6 类文案规范 + 铁律（含 AI 不算数）+ 空态（analyze 依据）
• data-vs-ai-boundary.md — 数据层 vs AI 层边界
• error-taxonomy.md — 失分类型口径表（唯一权威源 = scripts/loss_classify.py）
• loss-note-templates.json — 失分评语模板
• render-field-map.md — 渲染字段映射表
• run-guide.md — 运行前置清单 / 资产单一真身索引（新窗口先读）
• brand-picker-flow.md — 品牌首次配置交互：示例面板 + 2 选 1 文案 / 常见问法
• theme-picker-flow.md — 主题配色交互：色卡预览 + 4 选 1 文案 / 默认映射
• theme-presets.json — 主题配色注册表（颜色唯一权威源）
• 模考报告_v1.3_连页版.html — 报告模板（单文件连页版）
• org_tongzuo.json — 默认机构品牌（同桌；logo 为文本内嵌）
• assets/ — 素材源（brand-guide.png、logo_tongzuo.png 等；图片不进发布包）
• maintainer-guide.md — 维护者手册（改代码前必读）：模板准入 / 分数位 / 卷型矩阵 / 自检脚本清单 / 排查命令

工作流提示词（workflows/）

• analyze-WORKFLOW.md — 内容生成（AI 文案 → content.json）
• render-WORKFLOW.md — 字段注入渲染（→ 单文件 HTML）
• analyze-prompts-*.md — analyze 提示词（system_prompt / blocks / output_schema / writing_grader）

脚本（scripts/）

• 运行链（随包 13 个）：report_cli / report_lib / fetch_backend / content_builder / content_check / fill_content_template / validate / render / render_check / htmlesc / loss_classify / preflight / update_check
• 维护工具（不随包）：见 references/maintainer-guide.md「发布与维护工具说明」