v0.6.2

版本语义判断（每次发版重做一遍，不照抄上次）：本轮未新增契约字段、未改落盘布局、.progress.json 格式不变，存量教材项目照常续写 → 不是 MAJOR；未新增 skill、未新增能力，5 个 SKILL.md 的正文一字未动 → 不是 MINOR。改的是 5 份 frontmatter description（触发文案兼平台展示文案）与一处边界收紧，属"指令修正" → PATCH。

Changed

• 5 个 skill 的 description 从中英混排改写为中文。起因是 SkillHub 上的卡片读起来是半英文半中文——网页端逐项核对后发现列表卡片与 skill 详情页展示的都是 frontmatter 的 description，而它原本是英文句子里嵌中文触发词的写法。同时修正一处此前记错的事实：CLAUDE.md 与 ADR 0011 都写着"平台列表页展示的 description 取自 summary"，实测不成立——summary 只出现在搜索 API 把两者拼接的那个串里，卡片上看不到。这条错误认知有实际后果：5 份 summary 里那句"需与其余 skill 同级安装"是断链的唯一提示，写在用户看不到的地方等于没写，本轮已同时写进 5 份 description
• 改写保持 description 的全部原有职责（何时用 + 干什么 + 何时不用 + 触发词示例），只是换成中文并把最要紧的信息前置——卡片会截断，开头一句要能说清这个 skill 是什么。textbook-chapter 另补一句边界：只是问一个知识点、要一段解释而不是成篇教材内容时也不要用它
• description 现在同时承担宿主触发与平台展示两个职责，这一点写进了 CLAUDE.md 的 SkillHub 一节与 ADR 0011——以后改它要同时想两件事：模型据此判断触发，人据此在卡片上决定装不装

Notes

• 未跑完整 evals，改跑针对性触发实测，理由：description 只决定 skill 会不会被选中，不决定选中之后的行为（那是 SKILL.md 正文，本轮一字未动），所以风险面就是触发本身。做法是在隔离目录用 claude -p 起独立会话、用不点名 skill 的自然语言探测首个 Skill 调用——evals 的 prompt 大多显式写着"用 textbook-outline …"，反而测不出 description 的触发质量
• 结果：5 条正向触发全部准确命中（写整本教材 → textbook、设计教学大纲 → textbook-outline、按大纲写第三章 → textbook-chapter、出练习题 → textbook-exercises、建教材工作目录 → textbook-init）。负向「写一篇 Python 装饰器的入门教程」新旧都触发 textbook-chapter，符合设计（两版 description 都写明可单独运行写一篇带完整例题的深度技术文章），是我的期望设错了，不是缺陷
• 边界 prompt「给我讲讲矩阵乘法是怎么算的」做了新旧各 4 次采样对照：旧（英文）4 次中触发 1 次，新（中文）补边界句前 2 次中触发 1 次、补句后 2 次均未触发。两版都会偶发触发，是模型的非确定性，不是中文改写引入的回归；补边界句后重验正向触发不受影响。样本量小，如实记录，不当作定论

v0.6.1

版本语义判断（每次发版重做一遍，不照抄上次）：本轮未改任何 skill 的指令正文，name 与 description 一字未动，.progress.json 格式与落盘布局不变，存量教材项目照常续写 → 不是 MAJOR。含 SkillHub 第四个分发渠道接入，按 [0.2.0]（plugin 化分发）、[0.3.0]（新增 Codex 与 WorkBuddy 两宿主）的先例本可定 MINOR；定 PATCH 是明确选择，记下依据备查：那两轮改的是仓库如何被装载（新增六份清单、装法与目录对照全变），本轮 skills/ 主体只多了四个在三宿主处被静默忽略的 frontmatter 字段，skill 能力零增量、用户侧行为完全不变；且十处版本号已随 displayName 修复升至 0.6.1 并在平台上架生效，改判 MINOR 需重发一轮审核。

Added

• SkillHub（skillhub.cn）作为第四个分发渠道——决策与被否决的替代方案见 ADR 0011。它与前三个宿主的机制不同：元数据只从 SKILL.md frontmatter 读（slug/version/displayName 缺一个就拒绝发布），且一次只发一个 skill 文件夹、平台侧没有"整体安装"概念。5 个 skills/*/SKILL.md 各加 slug/displayName/version/summary 四个字段；skillhub publish 对 5 个 skill 的 --dry-run 本地预检全部通过（textbook@0.6.0 等），2026-09-02 5 个全部上架并过审生效（@user_6733bad6 命名空间；发布依赖账号实名认证与 API Token，这两步只能由人在浏览器完成，无法纳入 CI）
• slug 必须逐字等于目录名，这是本轮唯一不可逆的约定。CLI 安装落盘为 <install_root>/<slug>/（同级目录），只有 slug 与目录名一致，仓库里 45 条 ../<skill-name>/references/xxx.md 跨 skill 引用才解析得到；5 个 slug 上架前经查询全部未被占用，不需要加 handle 后缀。ADR 0008 的"整体安装不可拆分"在该平台无法由机制保证，降级为 5 份 summary 里的一句"需与其余 skill 同级安装"——这是接受该渠道的已知代价
• validate_skills.py 新增 validate_skill_versions：把 5 个 SKILL.md 的 version 钉在 .claude-plugin/plugin.json 上。版本真相的副本因此从 5 处涨到 10 处（SkillHub 从 SKILL.md 读、其余三宿主从清单读），不锁住就会出现"清单升了、SkillHub 上还是旧版且无人报错"。配套 4 个单测（版本一致 / 单个漂移 / 缺 version / 无 skills 目录不报错），单测总数 52 → 56

Changed

• frontmatter 白名单从"Claude Code 会读的字段"扩为四宿主并集，加入 slug、displayName、summary。这三个字段对其余三宿主无副作用（被静默忽略）；白名单的原意是"防手误写入无效字段"，而它们不是手误，是第四个渠道的必填项

• 发版流程的升版口径从"五处"改为"十处"（CONTRIBUTING.md 发版流程、CLAUDE.md 分发与硬约束两节同步）。README 的 version badge 仍是唯一没有脚本守着的那一处

• 5 个 skill 全部过审后补上 README 的 SkillHub 安装入口，并把首次上架的端到端实测结论写进 ADR 0011 与 CLAUDE.md。实测（CLI 2026.8.5）确认了两件此前只从源码推断的事：5 个装进同一个 --dir 后 18 条唯一跨 skill 引用全部解析成功；装回来的内容与仓库 skills/ 逐字一致（平台只多塞一个记录 slug/version/ownerId 的 _meta.json），ADR 0011 拒绝"临时注入"那条路的理由由此成立。只装 2 个时 ../textbook-chapter/references/chapter-template.md 当场解析失败——断链是实测可复现的默认结果，不是理论风险

• 记下两个官方文档没写的坑：skillhub install 加 --namespace 会多套一层 @<handle>/ 目录，而宿主只扫 skills/*/SKILL.md 这一层，多一层就一个都发现不到且无任何报错（与 README 早先记下的 WorkBuddy「别把 skills/ 整体套进去」同类）；重复安装报 Target exists，更新需 --force 或 skillhub upgrade

• 4 个子 skill 的 displayName 统一改为「教材写作·」前缀（教材大纲设计 → 教材写作·大纲设计，单章正文 / 习题生成 / 项目初始化同理；主 skill 保持 教材写作流水线）。上架后发现搜「教材写作」只搜得到主 skill 一个，其余 4 个连 top-100 都不进——直接探测 api.skillhub.cn/api/v1/search 测出了机制：只有 slug 与 displayName 参与召回（summary/description/tags 全部不参与，实测搜只写在 summary 里的「四段式」「UbD」「独立习题」「目录骨架」一律 0 命中，搜别人 tags 里的 k12 同样 0 命中），中文不分词、按整串子串匹配（教材 写作 带空格 0 命中，教材写作技能 也 0 命中），前缀匹配得分远高于中间子串（写作流水线 命中 textbook 但 score 0.038 排 #56，教材写作 前缀命中得 0.0486 排 #3）。所以能动的杠杆只有 displayName 一个——slug 按 ADR 0011 已发布不可改，改了所有已装用户的跨 skill 引用当场断链

• 排序 score 主要吃下载量，召回不足时平台用热门 skill 填充列表（搜「教材写作」的 #1 是与教材无关、下载 115 万的 self-improving-agent）。按实测分数分布预测：改名后 5 个落在 #3 与 #7–#10，默认 20 条一屏可见。两件做不到的写在这里免得下次重试：那几个热度填充项挤不掉；搜「教材」仍进不了前 20（我们 dl=2~4，纯热度压制，只能靠真实使用量涨）。搜「写教材」也放弃了——要同时含「写教材」和「教材写作」两个连续串，名字会变得没法看

• 由此新增一条命名规矩：新增 skill 的 displayName 必须以「教材写作」开头，且这四个字连续不被分隔符打断（用 ·，写成「教材·写作大纲」即前功尽弃）。校验脚本没有守这条，靠 CLAUDE.md 与 ADR 0011 记着

• tags 虽在 skillhub publish 的 payload 里（读 frontmatter 的 tags 列表），但实测不参与检索，故未加——为零收益给 frontmatter 白名单开第 11 个字段不划算。顺带记一笔：平台把主 skill 自动归到 category: ai-agent（其余 4 个是 education），分类浏览里找不到它，暂未处理

Notes

• 本轮未改任何 skill 的指令正文，description 与 name 一字未动，新增字段在三宿主处均被静默忽略——无行为变更，故未重跑 evals（按 CLAUDE.md 影响半径表，改动落在 scripts/、docs/ 与元数据层，CI 绿即可）
• displayName 改动同理未重跑 evals：该字段只被 SkillHub 读取用于展示与检索，三宿主静默忽略，既不参与 skill 行为也不参与宿主触发（宿主读的是 name/description，二者一字未动）

v0.6.0

版本语义判断（每次发版重做一遍，不照抄上次）：本轮未新增契约字段、未改落盘布局、.progress.json 格式不变，存量教材项目照常续写 → 够不上 MAJOR（MAJOR 的判据是老项目的 .progress.json 不能续用）。但阶段 1 多了一轮作者可见的材料征询，且学科档案第 3 节标题改名（## 3 认知动词与层级示例 → ## 3 认知动词、层级示例与章内分布）——按 subject-profile-spec.md 第 6 节写过自定义档案的人需同步改标题，否则结构校验会拒绝 → 也不是 PATCH。故定 MINOR。

Changed

• 章内 Bloom 层级分布从内核下移到各学科档案第 3 节——清的是 [0.4.0] 段末留下的第 1 条待改项，也是学科档案层漏掉的第五个可变点。bloom-levels.md 第 7 节此前给的四条经验分布（示范例题落记忆～应用、引导练习"半独立地练刚学的程序"、独立习题应用～分析、评价/创造全书 1–3 题点缀）是按 STEM 写的，却留在学科无关的内核里。eval 7、8 两次独立运行都撞上这一处：eval 8 自行把范例研读放在分析／评价层，eval 7 在梯度备注里写"分析层 35% 是人文社科的自然结果"——两次都是模型现场纠正内核，理由同源。危害不在"建议不准"，而在下游动作：一份按内核默认判读的梯度报告会把文科的正常章节读成梯度异常，作者照着告警把分析层的题降级，研读就变成了默写

• 拆分口径按 subject-profile-spec.md 第 4 节的判断法（换个学科照样成立即属内核）逐句判定：留内核的是三类题「支撑程度」与 Bloom「认知高度」的正交关系（规格第 2 节已明列）、独立习题先低后高的排列纪律、"偏离不是错误"与"梯度以全书为单位检查"两条元规则；下移的是每类题各自落在哪几层。内核第 7 节改为指路 + 说明为什么这件事必须随学科变

• 三份档案第 3 节据此各写一份分布：stem 沿用原措辞（它本就是按 stem 写的）；humanities 整体上移一档（范例研读理解～分析——本学科的"示范"是示范一次材料研读而非一遍可执行程序，压到记忆层就示范不出东西；独立论述分析～评价，评价与创造层是常规而非点缀），并写明"分析层占三成上下是正常结果"以及告警时该先查什么；economics 写成双峰（模型题应用～分析、政策论述题评价层），另记一处最易判错的地方——查出一个统计数值是记忆层，用它检验一个命题是评价层

• 档案第 3 节标题随之改为 ## 3 认知动词、层级示例与章内分布（原 ## 3 认知动词与层级示例）。标题是写下一份档案的人唯一的路标，名不副实就会漏掉这一块——本轮的教训正是"内容留在内核里，没人发现它是学科相关的"。同步改 validate_skills.py 的 PROFILE_REQUIRED_SECTIONS、单测 fixture 与缺节负向用例、规格第 3 节的四节表格

• eval 7 的实测分布（10/15/12/29/13/3，分析层 35%）只作为"stem 分布不适用于文科"的反证，没有写进档案。它是模型自己生成的一本书，拿它反过来定义规范是循环论证；且内核原文本来就是定性描述，不给百分比，档案保持同一形态

• 连带修好两处引用点：textbook-outline/SKILL.md 阶段 3 例题习题计划的"层级分布参考 bloom-levels.md 第 7 节的经验默认"改指所用档案第 3 节；performance-task-rubric.md 原文把表现性任务与第 7 节"评价/创造常放末章"称作同一件事的两面，而那句正被下移——改写为限定在"评价/创造属少量点缀的学科"并指路档案，否则文科作者会读到一条与本学科档案相反的话

• 阶段 1 新增条件性材料轮，并把降级纪律落盘固化为要求——清的是 [0.4.0] 段末第 2、3 条待改项，两条本是同一件事的两半（问材料 / 没材料时写下纪律）。第 3 条的病因与原记录不同：textbook-outline/SKILL.md 的「写完不停顿直接进阶段 2」与档案第 1 节的「强烈建议作者提供材料」并非字面矛盾——前者说的是产出写盘之后，而阶段 1 本就有一轮 AskUserQuestion 四问。真正的缺口是顺序：四问里第 1 问才问到学科，问完才判定得出档案，届时才知道本学科要不要材料，所以索要材料只能发生在第一轮之后，而内核没有任何动作承接档案里那句话。eval 7 当时靠现场权衡补上了这一步（自行并入提问），规范里始终是空的

• 新分支写在内核（换个学科照样成立）：判定档案 → 该档案第 1 节有「前置输入要求」吗 → 有则追加一轮索要材料，作者给了就把材料清单落 00-教材设计.md「## 一、教学定位」子节、没给就把降级纪律与预期代价落同一子节；无前置输入要求的档案（stem）原样不停顿。明写「这一轮不是 gate」：作者答"没有"、答不全、直接跳过一律照常放行，绝不等待确认——不写死这句，模型很可能把它当第三个停点停死，那就动了双 gate 设计。要什么材料、纪律内容与代价是什么留在档案（humanities：约三分之一的题挂 ⚠️；economics：数据类题一律 ⚠️ 而模型题与概念题不受影响，这句要写明，否则作者会以为整本书都待核）

• 落盘而非只在对话里说一句，理由是上下文隔离：各章在不同会话里独立写成，00-教材设计.md 是唯一能传到阶段 4 的载体，只说过没写下的纪律，写第 3 章时等于不存在。没有给契约新增「材料」字段——落在「## 一」子节即可被下游读到，加字段要牵动全部 5 个 skill，超出这三条的范围；handoff-contract.md 只改了重入规则表里的措辞（current_stage=1 由「一轮提问」改为「一至两轮提问」）

• 题内局部 ⚠️ 的合法边界写进内核（exercise-design.md 第 3 节，作为第 4 条的无编号补充段——第 6 条被 textbook-exercises/SKILL.md 按编号引用，插入新编号会打断它）。eval 8 自发出现「整题 ✅、题面内某数据标 ⚠️ 且声明不参与结论」这种档案未规定的形态，它合理但危险：不写死条件就会变成漂白手段（把核不实的材料都标成"不参与结论"，整题照打 ✅）。定的硬条件是把这一项整个删掉、题目与答案依然完全成立——成立才可 ✅，不成立说明结论其实依赖它，整题必须 ⚠️。humanities 第 2 节补本学科最常见的那种形态与一句自查

• 两份档案的台账落位一起补齐：humanities 的引文台账与 economics 的数据来源台账此前都只写了「附在两节之后」，没说 textbook-chapter 独立触发（无项目目录、无 术语表.md）时落哪。两份各补一句：被调度时并入 术语表.md 逐章追加，独立触发时随章附在「本章小结」之后。原待改项只点了 humanities，economics 是这次读文件时撞见的同构缺口——档案是复制同一套结构长出来的，一份有的毛病另一份多半也有，改一份就得回头扫一遍相邻档案

• 至此 [0.4.0] 段末的五条遗留待改项全部清空（第 5 条 README 文科成本预期实际已随 1dabea0 做掉，本轮核对时才发现）

• evals 断言 77 → 90，补的是本轮四项新规范的验证位：核对后发现现有断言对本轮改动一条都验不到——阶段 1 的材料轮与降级落盘在 eval 7/9 零覆盖，章内 Bloom 分布在 eval 7/9 只查了动词不查分布，题内局部 ⚠️ 在 eval 8/10 只查了「状态只有两种」，台账落位则完全没查。不补就跑，八个用例只能证明没回归，证明不了改动生效。新增 13 条：eval 1 一条反向断言（stem 无前置输入要求，阶段 1 不得追加材料轮——锁住条件分支不退化成无条件）；eval 7/9 各四条（材料轮触发、该轮不是 gate、降级纪律真落进「## 一」子节、章内分布取自档案）；eval 8/10 各两条（台账在独立触发时随章附章末、题内局部 ⚠️ 须满足「删掉该项设问仍成立」）

• 其中「材料轮不是 gate」与「局部 ⚠️ 的硬条件」两条是防退化断言：前者若失守就多出第三个停点、破坏双 gate 设计，后者若失守局部标注就成了给核不实材料换 ✅ 的漂白手段。判定时都必须查产物取证，不能采信会话自述

Eval 预检（2026-08-31，宿主 Claude Code 2.1.251，claude -p 独立进程）

• 跑了 5 个用例（1、7、8、9、10），48 条断言：46 通过、2 未触发、0 不通过。 成本 $26.15 / 183 turns。判定记录在 evals/workspace/（gitignored）各用例 outputs/judgment.md。性质必须说清：每个用例由 claude -p 起独立进程、全新上下文、只喂 prompt 原文，「新开会话」这条满足；但判定人是本轮改动的作者本人，非独立第三方——因此是预检，不是正式验收，README 里程碑表不据此回填
• 第五个可变点（章内 Bloom 分布下移档案）拿到直接证据：eval 1 产出的原文写着「层级分布依据 stem 档案第 3 节」——它去档案查分布，不再查 bloom-levels.md 第 7 节。三份档案实测分布分别是 stem 应用 50.0%／分析 25.6%、humanities 应用 6.7%／分析 44.2%、economics 应用 26%／分析 37%（双峰）；逐类型对照更清楚：同是「引导练习」，stem 下应用 10/15、humanities 下分析 11/21 而应用仅 2；同是「评价+创造」，stem 下 3 题（档案写「1–3 题点缀」）、humanities 下 14 题（档案写「常规非点缀」）。同一套内核跑出三种分布，说明这一层差异确实属于档案而非内核
• 材料轮四条断言全部实测通过，其中两条是压测出来的：① eval 9 被拿「没有」去撞 gate 时主动拒绝放行——「你这句「没有」我读作是回答材料征询，不能替代五件套的确认，按 gate 纪律我不能自行判定放行」，证明新增的一轮没有稀释双 gate；② eval 1 的反向断言通过——stem 下材料轮未出现（索要材料关键词命中 0、无降级子节、全程 3 轮 vs humanities/economics 的 4 轮），条件分支没有退化成对所有学科都问
• 降级纪律落盘两个用例都到位，economics 侧原样写出了档案里那句「模型题与概念题不受影响」，并自行补了「待核范围仅限实证数据题，不是整本书」；两份台账各自落位（## 引文台账 / ## 数据来源台账 均随章附在小结之后）
• 未触发的 2 条是两个单章用例的「题内局部 ⚠️ 硬条件」：逐题检查确认题干内均无局部标注，按判定口径记未触发、不计入不通过。但 eval 8 暴露了一个规范缺口线索：局部标注的真实落点是台账行（✅ 已核归属；⚠️ 页码转引待核原书），而本轮写进 exercise-design.md 的边界只覆盖「题干某项核不实、整题仍 ✅」。台账「核对状态」列本就该表达这种精度差异，不算违规，但规范对它一个字没写——下一轮值得考虑给台账行的混合状态定个写法
• 未跑 eval 2、3、4（纯回归位，本轮无新增断言落在其上），欠账如实留着

v0.5.0

Added

• 第三份学科档案 economics（profiles/economics.md，经济学各分支与金融学）：填的是前两份档案之间的一个具体缺口——经济学此前被当作「边界学科」分流（stem 第 1 节说计算题走它、humanities 第 1 节说论述走它），但两份档案的题型集里都没有一行管「统计数据的出处核对」。GDP 增速、CPI、基尼系数这类答案不是算出来的而是查出来的，走 stem 时最接近的「概念辨析 → 核对定义来源」并不贴。红线不会因此被绕过（验证状态二值化属内核，填不出手段就落 ⚠️），代价是一本数据密集的教材会攒下一堆待确认标记压给作者。本档案把经济学的真实形态——模型题可复算、统计数据只能核来源、政策题两者都不适用而要给论证要点——正面建模成三类手段并存，这也是首份「混合可验证」档案

• economics 档案第 2 节七个题型：模型求解（与解答不同路径的 sympy/numpy 复算并实际执行）、比较静态与图形分析（符号求导核验方向 + 图文一致性核对，曲线移动方向与面积增减须与文字结论逐项对齐）、指标计算与核算（复算 + 口径核对：定义式来源/单位/基期/名义与实际是否混用）、实证数据题（核对权威数据源原始发布值并标明指标全称、机构、口径、单位、年份；取不到 → ⚠️ 需作者确认（数据未核），不得凭记忆写出数值）、计量与统计推断（给出数据的实际跑一遍核对系数，纯解读题核验识别假设与相关/因果混淆）、概念辨析、政策分析与论述（论证要点 + 评价标准表，恒标「开放题」）。第 1 节另写明前置输入要求：阶段 1 应建议作者提供数据来源清单与统计口径——一个凭印象写出的统计数值比一道算错的题更难被读者发现

• economics 档案的章内段义：四段标题为「概念与模型讲解 / 示范例题 / 引导练习 / 独立习题与论述」，首末两段的文案点出经济学的两个特征（概念要落到模型上才算讲完，末段除算题外要容纳政策论述）；示范例题的增量是每步除数学操作外必须给一句经济含义（算出 $\partial P^*/\partial t = 1/3$ 之后要说「消费者承担三分之一税负」，缺了这句例题就退化成解方程）；引导练习特有的好变式是换参数符号（把弹性从大改小看结论如何翻转，练的正是「结论依赖哪个参数」）；载体扩展为数据来源台账（| 数据指标 | 来源与发布机构 | 口径/基期/单位 | 首次引用章节 | 核对状态 |）+ 符号约定附注行——动机同 humanities 的引文台账：上下文隔离让各章在不同会话写成，术语表管不到统计口径，第 3 章用不变价、第 8 章用当年价，读者会以为数据自相矛盾。文体附加条款七条（数据必带来源与口径、模型假设先行并写明适用边界、实证与规范分开写、相关不等于因果、学派归属清楚、图形标注统一、单位与量纲一致），并声明 writing-style.md 第 13 节数学公式规范全节适用。坐标类图示（供需图、IS-LM 图）明确用内嵌 SVG 而非 mermaid——mermaid 画不出坐标系与曲线相交

• evals 新增用例 9、10（M8）：9 验档案路由——《微观经济学导论》须判定为 economics、题型全落在七型内，且有一条断言专查题型分布同时覆盖两类验证手段（至少一处可复算题型 + 至少一处须核来源的题型），否则这份档案就只是 stem 的换皮；10 验混合验证纪律——prompt 硬性要求含一道真实统计数据题（不要求就可能整章只出模型题，验不到新增的那半边），断言四段标题逐字一致、题目数等于验证行数、模型题附逐题可运行且路径不同的复算代码、数据题「带来源标注」与「标 ⚠️ 需作者确认（数据未核）」二者必居其一、论述题给论证要点与评价标准

• 两份 README 新增「能写哪些学科」/「Which subjects it can write」一节（紧跟「能做的 / 不做的」之后）：「都能写哪些学科」是用户最关心的第一个问题，此前的回答散在开篇概括段与三份档案文件里，没有一处可直接扫读。新章节收拢为一张三档案覆盖表（覆盖学科、验证方式、实测状态三列，实测口径与里程碑表一致）+ 三分法判定句（全能复算走 stem、全不能走 humanities、一半一半走 economics）+ 边界学科分流口径（语言学习/法学/会计、心理学/地理、经济学内部三分、交叉主题，均摘自各档案第 1 节，不另立口径）+ 清单外学科的兜底机制（spec 第 7 节：不静默套用、列出已知差异、作者拍板）。纯文档改动，不触碰 skill 行为

• 独立习题答案与题目分离（落盘新增 98-参考答案.md，规则见 handoff-contract.md 3.1 节）：这是从教材使用者角度补的第一个缺口。此前答案紧跟题干排版，读者眼睛一扫就看到底，「独立习题」的独立性名存实亡——全书投入最大的产出（三类题 + 逐题验证）在使用侧直接失效，而这恰恰是四段式「教 → 扶 → 放」最后一步要换来的东西。搬走三件：参考答案/解题路径/开放题参考要点、验证状态行、验证过程；三件必须整体同行——验证代码几乎必然含答案数值，只搬答案会从验证过程泄底。留在章内四件：题干、Bloom 标注、「开放题」标记、论述类题的评价标准表（那是任务说明不是答案，同 99-表现性任务.md 把 rubric 交给学生的口径，读者动笔前就该知道按什么标准写）。示范例题一动不动（worked example 先行是四段式的教学内核，藏起来等于毁掉第二段），引导练习的提示阶梯改用 <details> 折叠留在原位——提示离开题干就失去意义，而线性 Markdown 下「读者自行决定看到哪层」本就是句空话

• 契约新增字段 答案排版 / .progress.json 新增 answer_layout（separate / inline）：沿用 subject_profile 那套单点决策 + 存量兜底的成熟模式——新项目一律 separate，字段缺失（v0.4.x 及更早创建的项目）按 inline 处理并在续写行后补一句说明，已写的章不迁移答案。一本书两种答案排版比统一用旧排版更糟，所以兜底选的是「整本沿用旧排版」而不是「从下一章起改新排版」。分离只在被主 skill 调度时执行：独立触发 textbook-chapter（写单篇文章）或 textbook-exercises（只要题）时没有教材项目目录，答案搬无可搬，一律照旧内嵌——textbook-exercises 只管产出、不管落位，输出契约一字未改

• evals 断言随规格更新（用例数不变，仍 10 个）：4 补三条（answer_layout=separate 落盘、98-参考答案.md 按章分节且题号与 N.4 段逐一对账、章内搜不到答案且引导练习三层已折叠）——答案分离的验收压在这个走完整调度链的 e2e 用例上；5 的「全书题目数等于验证行数」改为分处清点并补一条落位泄底检查；6 的「未创建任何流水线文件」清单补 98-参考答案.md；2、3 各补一条反向断言，锁住「独立触发不分离」这条边界，防止 skill 把落位规则过度泛化

• 成书要件：读者向前页 00-前言.md（固定三节「本书写给谁 / 怎么用这本书 / 目录」，来源与改写要求见 handoff-contract.md 3.2 节）：接着答案分离往下补使用者侧的缺口。此前交付物里读者能直接用的入口一个也没有——打开目录看到十几个 .md，得自己猜这本书是不是写给我的、先读哪个文件、答案去哪找。纸质教材靠封面前言目录解决这三件事，Markdown 教材没人替它们操心。生成放在阶段 5 而不是阶段 3：目录要带章文件的真实路径与真实标题，而章标题在写作途中仍可能被修订，早写的目录会指向不存在的文件——一个点不开的链接比没有目录更糟；相应地阶段 5 走查要求逐条点开核对，失效链接由主 skill 当场修掉，不作为"待作者处理"的不通过项放过（这一项它自己能修，报给作者没有意义）。前页与 00-教材设计.md 的分工是读者向 / 作者向，同 99-表现性任务.md 的既有口径：设计文档不交给读者读，因此目录里也不列它

• 章首学生版学习目标 + 章末自检（章模板 3.0 与 3.5 节）：这是路线图里成本最高的一条，因为它要动契约——章节树条目新增 承载的学习目标编号[]。做它的理由是一处内核断链：UbD 全套逆向设计从五件套一路推到章节树、例题梯度、表现性任务，唯独学习目标从头到尾只活在 00-教材设计.md 里，学生一次也看不到。看不到目标的读者只能边读边猜这章重点，读完也无从判断自己学会了没有。现在章首把该章承载的目标摊开成学生版（第二人称、去编号、去 Bloom 标注、保留可判断的动词），章末自检把同几条原句搬下来写成 - [ ] 复选项，每条给「回看 N.x」与「自测：习题 N-y」两个出口——目标 → 自问 → 回看 → 自测，读者自己就能闭环。上下文隔离不放松：大纲切片只带该章那几条目标的原文，不带全书清单；逼章 skill 回头查 00-教材设计.md 等于放开读全书设计文档的口子，所以原文由主 skill 提取后随切片下传

• 五件套编号约定（ubd-framework.md 第 2 节）：顺带补上一个从未定义过的隐性约定。契约从 v0.1.0 起就在用 承载的持久理解编号[]，但「编号怎么编」全流程一个字都没写，靠模型每次自发编——再加一组学习目标编号，两串数字并列就会混。现定为前缀制（大概念 B、持久理解 U、核心问题 Q、迁移目标 T、学习目标 O），并写死两条纪律：编号一经确认不重排（中途删条则空号作废——章节树和各章都已引用它们，重排一次全书引用集体错位）；编号只在作者向文档出现，读者向产物（章首目标、00-前言.md、99-表现性任务.md）一律不带，学生读到"O3"只会困惑

• 符号表：术语表新增 ## 符号约定 节 + 回报字段 新增符号[]：这一项修的是一条悬空的纪律。stem 与 economics 档案都写着"同一个量全书用同一符号，符号选择记下来全书据此对齐"，但契约里没有任何字段承载符号、主 skill 也没有写符号的动作——这句话此前只是一句期望，没有落点。各章在不同会话里独立写成，没有登记表，第 2 章的列向量写 $\mathbf{x}$、第 7 章写 $\vec{x}$，读者会以为是两个东西。现在符号与术语同文件、同追加机制（列为 符号 / 读法 / 含义与约定 / 首次出现章节——「读法」列是给读者的，符号表最常被翻开的时刻正是遇见一个不知道怎么念的记号），主 skill 追加前先比对已登记条目：同一含义已用别的符号登记过就退回该章统一符号，这正是符号表要存在的理由。不用形式符号的学科（humanities）保留节标题、正文写一行「本书不使用形式符号」——节不删，是为了让阶段 5 能区分"这门学科没有符号"与"符号漏登记了"

• evals 断言随成书要件更新（用例数仍 10 个，断言 71 → 77 条）：3 改三条并补一条（章首目标为学生版、章内搜不到 O1 与「（Bloom：」、自检指向的题号真实存在）；4 补一条跨阶段编号传递的对账（每章章首目标条数 = 00-教材设计.md 该章 承载的学习目标编号[] 条数，验证编号一路传下来没丢条没加码）；5 补两条（00-前言.md 三节齐全且目录零失效链接、术语表两节且符号节非空）并把七项自检改为八项、覆盖矩阵改为三列对账；1、7、9 的章节树断言扩为两组编号各自双向对齐；6 的「未创建任何流水线文件」清单补 00-前言.md；8、10 补章首与章末件断言，8 另查 humanities 的符号节写着「本书不使用形式符号」而非留空表

Changed

• 章内自查清单第 3 条由「题目数必须等于验证行数」改为分类清点 + 题号对账（chapter-template.md 第 5 节），阶段 5 自检第 4 项同步由一条拆成三条（验证残留 / 分处清点 / 落位泄底检查）：答案分居两个文件后，一把总数对不上账，而题号成了唯一的对账凭据——多出的这层对账能抓住「搬丢一道」「搬错章」这类新错误，检查是被加强而不是削弱。自查清单另加第 7 条：在章文件里动手搜 参考答案、解题路径、参考要点，N.4 段内一处都不该有

• 红线未松动：「每题必附参考答案或解题路径」「每题必经验证」原样保留，改的只是答案落在哪个文件；相应地 exercise-design.md 第 3 节的「就地复核」纪律补写了新的「就地」口径——独立习题的就地指 98-参考答案.md 里题号对应处，三件同处

• stem 与 humanities 两份档案第 1 节的分流规则改为指向 economics：此前它们各写了一句「经济学怎么办」，索引里多出第三份档案后，旧分流规则会让阶段 1 读到两套互相矛盾的判定口径。校验脚本查不出这种矛盾（它只查四节结构、验证手段非空、索引与文件对应），因此在 CONTRIBUTING.md 的「新增学科档案清单」里把「回头改相邻档案第 1 节的分流规则」补成独立一步。规格第 5 节的分界句同步从二分改写为三分（全都能复算走 stem、全都不能走 humanities、一半能一半不能走 economics）

• 本轮对既有两份档案的项目是纯增量：内核与 stem/humanities 的题型集、段式、验证纪律一字未动，eval 1–8 的既有结论不受影响

• 本章小结由固定三件改为固定四件（新增「自检」，插在持久理解呼应之后、下一章预告之前）：原三件全是作者向与机制向的——给下一章作者的核心结论、给阶段 5 走查的持久理解呼应、给章间钩子的预告，学生读完一章最想知道的「我学会了没有」没人回答。这条正是使用者视角下最刺眼的一处：连模板原文都写着核心结论"写的时候面向下一章的作者"。四件里第 3 件是唯一面向学生的

• 章首与章末两件的标题不随学科档案变（## 本章学习目标 / ## 本章小结 任何档案下逐字固定）：四段的标题文案由档案第 4 节定（stem 与 economics、humanities 各不同），但首尾件是读者向的——学生翻开任何一章都该在同一位置找到"这章要我学什么"和"我学会了没有"。相应地档案的四个可变点未增加，第 4 节仍只管四段标题与教学动作

• 阶段 5 自检由 7 项增至 8 项，另有两项内部扩展：第 3 项「术语一致性」扩为「术语与符号一致性」（新查两件：各章出现的符号是否都已登记、同一含义是否全书只用一个符号）；第 6 项「学习目标覆盖矩阵」由单列改为三列对账——设计侧（有章节树条目认领）、读者侧（认领章的章首与章末自检真写了）、检验侧（至少一道题检验）。加两列的理由是同一条目标可以在三个环节各自掉队：设计文档里有、章节树没认领；认领了、章首没写；章首写了、没有题检验——只查最后一环，前两种漏法会一路漏到读者手上。新增的第 8 项是成书前页生成与走查

• 章节树条目与 UbD 一致性检查同步扩展：章节树每项由 {章号, 章标题, 一句话定位, 承载的持久理解编号[]} 扩为再加 承载的学习目标编号[]；阶段 3 的双向对齐检查由一组变两组（一条学习目标都不承载的章"章首写不出读完你能做什么"，要改造或并入相邻章；没有章承载的学习目标要分配进某章或与作者商定删除）；ubd-framework.md 第 3 节一致性检查表加一行「学习目标 → 承载章」（留待阶段 3 校验，同「迁移目标 → 表现性任务」的既有模式），第 5 节自查清单由六问增至七问（新增编号齐备一问）

• 术语表结构由「一张四列表」改为「固定两节」（## 术语 + ## 符号约定，两节的列定义任何档案都不得改动）：三份档案第 4 节的术语表扩展表述随之与内核对齐——stem 与 economics 从"符号约定作为附注行记入"改为"## 符号约定 节必须写满"，humanities 明确该节写「本书不使用形式符号」而非删节；档案各自的附加台账（humanities 引文台账、economics 数据来源台账）改为附在两节之后。档案与内核的口径必须一句话都不矛盾：档案里留着"记在附注行"、内核已改成两节，阶段 4 就会读到两套写法（这类矛盾校验脚本查不出来，和 0.4.0 那次相邻档案分流规则漂移是同一类坑）

• 落盘布局新增 00-前言.md 后，workspace-layout.md 的两处同步更新（目录树 + README 工作说明模板的文件表，并点明"读者从这里进入"、00-教材设计.md 是作者向不必给读者）；两份 README 的交付物清单、五阶段表阶段 5 产出列、「第一次运行会发生什么」、ASCII 流程图第 6 步同步，坑一的解法段补一段"这套设计还要对读者可见才算兑现"

• 对外文案随多学科口径重写（纯文档，不触碰 skill 行为）：GitHub 仓库 About 从"面向数学/物理/计算机等 STEM 学科"改为"学科无关内核 + 可插拔学科档案，理科真算复核、人文社科逐字核对引文出处"，并补上漏写的第三宿主 WorkBuddy；标签新增 humanities、instructional-design、curriculum-design、backward-design、agent-skills、workbuddy 六个（原标签只有 stem，找人文社科用途的人搜不到）；homepage 指向 README

• 两份 README 补齐多学科口径：新增 subject profiles: stem | humanities badge，多学科提到开篇第一段（此前藏在第二段），学科档案段落改写为"四个可变点 + 两份档案共用同一套验证纪律"；「怎么开口说」表后新增「换个学科，说法不用变」一段，讲明阶段 1 判定一次 → 逐章透传 → 中途不重判这条用户可感知的行为

• 清掉两份 README 里的 STEM 单口径残留：英文版「Why you can trust it」首条 "Every answer was actually computed" 与中文版早已改为按档案手段验证的表述不一致（改为 "Every answer was actually checked"），ASCII 流程图第 5 步的「每题真算复核」/"each answer recomputed" 同步改为按档案手段核过并补上学科档案 id 这件输入，textbook-exercises 一行的产出改为「理科附逐题可运行的复算代码，文科附出处与核验记录」

• 补写 0.4.0 遗留的待改项 5（成本预期）：两份 README 的坑二一节写明无史料输入时预期约三分之一的题需作者事后核定（eval 8 实测 3/9），并说明这是 humanities 档案"宁可标注也不逐字引用核不实的话"的必然结果，以及如何在阶段 1 把比例压下去；英文版另补上中文版已有、英文版缺失的 evals 欠账说明（eval 1/3/4 待跑、eval 2 待复验）

• 三份 plugin.json 的 keywords 补 humanities 与 instructional-design；Codex 侧 longDescription 的纪律表述从"计算类例题答案必须真算复核"改为"按所用学科档案定义的手段实际核过"，与内核口径一致

v0.4.0

Added

• 学科档案层（subject profile）：新增 skills/textbook/references/subject-profile-spec.md 与首份档案 profiles/stem.md。此前"STEM 假设"弥散在四个文件里——例题题型与验证方式表（exercise-design.md 第 2 节）、Bloom 动词表与六层判定标尺（bloom-levels.md 第 2、4 节）、四段标题文案与各段教学动作（chapter-template.md）、数学公式规范的适用声明——加一个学科门类要同时改四处，且改完两套规则各自漂移，没有机制拦得住。档案层把随学科变化的四个可变点（题型集、验证手段、认知动词与层级示例、章内段义与载体扩展）收拢成一个可插拔构件，规格强制四个固定小节、每节恰有一个消费者（阶段 1 / textbook-exercises / textbook-outline / textbook-chapter）。内核只写学科无关的规则，档案只写本学科的增量：通用 Bloom 动词、三类题支撑纪律、四段式脚手架逻辑、通用文体规范都留在内核，档案不复制
• 契约新增字段 学科档案（handoff-contract.md 第 2 节）：阶段 1 判定一次 → 落盘为 .progress.json 的 subject_profile → 逐章原样透传给 textbook-chapter 与 textbook-exercises，全流程单点决策、不重判。顺带修掉一个隐患：此前作者坚持写文科时只有 textbook-outline 知道要降级，chapter 与 exercises 各自仍按 STEM 假设跑
• 校验脚本新增 validate_subject_profiles（第一层防线覆盖新架构）：每份档案四节齐全、第 2 节题型表表头固定、「验证手段」列不得为空或写成"无"、规格第 5 节索引表与 profiles/ 下文件一一对应；validate_repo_health 另查规格文件与至少一份档案存在。其中验证手段列非空是红线的结构性保障——档案能定义"用什么方式验证"，不能定义"是否需要验证"，于是新增任何学科都绕不过每题必验，绕不过来自结构而不是靠指令里写"不许"
• 配套单元测试 11 项（总数 41 → 52）：合法档案通过、缺小节、验证手段为空、写成"无"、表头不对、表无数据行、档案未登记索引、索引登记但文件缺失、无档案层时静默跳过，以及 references 子目录字节校验与多级相对引用两项
• 第二份档案 humanities（历史、哲学、文学、政治学、社会学、艺术史）：把 ADR 0006 的红线迁移到"答案取决于论证"的学科——理科最致命的失真是算错，人文社科是引文伪造与史实错位（虚构文献、张冠李戴的名言、错乱纪年），同属信任杀手，故沿用同一条纪律，只把"复算"换成"核对来源"。六个题型各有验证手段与降级路径：事实性/年表（核对材料或公认年表并标出来源）、引文辨识与文本细读（引文逐字核对原文，记明版本/篇目/位置）、概念辨析（核对定义来源，学界有实质分歧时列出主要界定并标 ⚠️）、史料/文本评析（核实材料存在 + 核验评析逻辑自洽）、因果解释与论证（逐步核验论证链条并附反方视角）、论述/小论文（不设标准答案，给论证要点 + 评价标准表，恒标"开放题"）。最重一条纪律：无法查证时一律标 ⚠️ 需作者确认，绝不凭记忆编造引文、出处、年份或页码——一个编出来的出处比一个算错的数字更难被读者发现，伤害也更大；因此该档案第 1 节要求阶段 1 强烈建议作者提供学科材料
• humanities 档案的章内段义：四段标题为「概念与脉络讲解 / 范例研读 / 引导分析 / 独立论述与探究」，段位语义仍是讲 → 教 → 扶 → 放，换的是教学动作——要示范的不是"怎么算"而是怎么读一则材料、怎么搭一条论证（范例研读逐步标出推断动作：识别材料性质 → 提取主张 → 检验证据 → 指出立场与局限 → 得出有边界结论）；载体扩展为引文台账（| 引文出处 | 版本/译本 | 首次引用章节 | 核对状态 |，同一文献全书只用一个版本、同一引文只用一种译法——上下文隔离让各章在不同会话写成，术语表管不到版本与译名）；文体附加条款七条（引文必带出处、原文与今译分列、纪年统一、译名统一、史实与史论分开写、不以今律古、观点归属清楚），并声明 writing-style.md 第 13 节数学公式规范不适用
• evals 新增用例 7、8（M7）：7 验档案路由——《中国近代史纲要》须判定为 humanities 且不出现劝退、五件套与双 gate 表现与 stem 项目一致、例题计划题型全落在该档案题型集内、学习目标动词不出现"计算/求解/推导"；8 验引文核查纪律——四段标题与档案逐字一致、题目数等于核查行数、每处引文带出处行、无法核对的标 ⚠️ 需作者确认（引文未核） 而非凭记忆写出、论述题给论证要点与评价标准并标"开放题"。两个用例的断言全部锚定形式性可判定项（学科越偏论述，内容质量越难客观判定，压在形式项上第三道防线才不会失效）

Changed

• 引用完整性校验从"只查 SKILL.md"扩展到 skills 下所有 .md，并支持多级 ../ 跨 skill 路径。动机：档案层与内核互引密度高于以往，references/ 之间的断链此前无人拦（既存覆盖缺口）；check_reference_size 的判定同步从 parent.name == "references" 改为 "references" in parts，否则 references/profiles/ 下的档案会漏掉 500 字节校验
• 四个可变点的内容从内核迁入 stem 档案，内核相应位置改为指路：exercise-design.md 第 2 节由题型表改为"查档案第 2 节"并说明表头形状与非空要求、第 7 节反模式 5 从"文科论述题混入（v1 不支持，v2 支持）"改写为"出了档案题型集之外的题"（没有为它定义过验证手段就等于绕过红线，改用档案内最接近的题型并说明替换）；bloom-levels.md 第 2 节动词表标注为通用基线、第 4 节六层标尺迁入档案；chapter-template.md 四段标题与后三段教学动作改为取自档案第 4 节，模板正文仍用 stem 档案文案写成、可直接复制
• textbook-outline 阶段 1 增加档案判定：产出的「## 一、教学定位」必须含一行 学科档案：<id>（不设 gate，展示即可——档案决定全书验证纪律与章内段式，选错一次会歪一整本书，而作者是唯一有资格判断"这个近似可以接受"的人）；索引里匹配不到时按规格第 7 节处理：说明将按最接近的档案处理 + 指出已知差异，由作者决定继续或改学科范围，不得静默套用
• .progress.json 新增 subject_profile 字段，属向后兼容增量：v0.3.x 及更早创建的存量项目无此字段，重入时按 stem 处理并在续写行后补一句说明，不阻塞续写。三类题的类型名（示范例题/引导练习/独立习题）明确留在内核，任何档案都不得改动——Bloom 回写、梯度统计、验证行清点全按类型名对账；档案只定义章内段标题文案
• 对 stem 档案的项目，本轮为纯重构、行为等价：唯一对外可见的新增是阶段 1 多打印一行 学科档案：stem。验收标准即 evals 用例 1–4 全绿且产出与重构前等价
• exercise-design.md 第 3 节末两次修订（由 eval 2 驱动，见下节）：最终措辞要求逐题附这道题自己的、复制即可运行的复算代码，并明确禁止"多题共用一个外部脚本、逐题只附调用命令"——理由写进规范：交付到读者手里的是章文件，而章骨架只有「引言 + 四段 + 本章小结」，没有安放共享脚本的位置，脚本落在章外这条纪律就白立了；同时保留为文科新增的"核验记录"形态，并采纳 eval 8 里自发出现的好做法，要求核验记录标明结论实际依赖哪几条。textbook-exercises/SKILL.md 输出节同步
• 文体规范两处加固（由 eval 2 rerun2 的偶发违规驱动）：writing-style.md 第 13.4 节在"公式内不写中文"下补明替代写法——多行推导的行标签用符号（(AB)_{11}）而非 \text{中文}，并把 \text{第 1 行第 1 列：} 这个具体反例写进去（注明这是该条最常见的破功处，因为"给每行加个说明"看起来无害），\text{} 只留给英文短词；chapter-template.md 第 5 节自查清单第 7 条把该项变成可执行动作——搜一遍 \text{，逐个确认括号内无中文

Eval 验收（2026-08-04，宿主 Claude Code / Opus 5）

本轮触及 handoff-contract.md 与全部 5 个 skill，按 CONTRIBUTING 映射表需重跑 eval 1–4，外加新增档案的 eval 7、8；.progress.json 为向后兼容增量、落盘布局未变，故不补跑 5、6。前两道防线全绿（结构校验通过、52 项单元测试全绿）。已跑两个：

• eval 8（humanities 单章，M7）：通过 7/7。 压测的核心担忧——无史料时会不会编出像真的出处——实测没有发生：三处核不实的文献全部走降级路径且不逐字引用（改为明示的转述），引文台账落地并自拟约定「⚠️ 未核的条目核定前不得逐字引用」。最强的一条证据是核对改变了输出：它查「数千年未有之变局」时发现自己的先验错了（含「三千」的那句在 1872 年另一折，不在 1874 年海防折），据此写成例 1-4——不是先写完再补一句"已核对"。工具账 WebSearch × 8 + WebFetch × 4 全用于核对。另有两条架构级旁证：档案隔离生效（eval 8 读 humanities.md 未读 stem.md，eval 2 反之），文科路径的引用链也通（档案第 2 节把 rubric 写法指向 performance-task-rubric.md 第 3 节，被跟随且产出形状一致）。判定记录：evals/workspace/2026-08-04-eval-8/outputs/judgment.md

• eval 2（stem 出题回归，M3）：三次运行，断言 3 修复但用例未整体通过。 首跑暴露一处由本轮重构引入的行为漂移：为容纳文科的"核验记录"，exercise-design.md 第 3 节末把"附复算代码"从主句降为并列选项，结果同 prompt 下 0.3.0 逐题附 4 个 ```python 块、本轮 0 个（代码集中到文末）。这类漂移是结构校验与单测都拦不住的那一类——文件形态全合规，变的是模型对一句话的理解。第一次修订后重跑仍不通过（改成"共用外部脚本 + 逐题附调用命令"，而章骨架里没有安放共享脚本的位置，脚本落在章外读者就复核不了）；第二次修订禁掉该写法后 rerun2 达成逐题 4 个独立可运行代码块、0 外部脚本文件。rerun2 因另一条偶发违规（例 1-2 在 aligned 里用 \text{第 1 行第 1 列：}，违反第 13.4 节公式内不写中文）仍判不通过——该项首跑与 rerun 均为 0 处，非回归，已按下节加固规范，整体通过留待下一轮验证。判定记录：evals/workspace/2026-08-04-eval-2{,-rerun,-rerun2}/outputs/judgment.md

• eval 7（humanities 大纲，M7）：通过 6/6。 档案路由正确（学科档案：humanities，全文 stem 命中 0、劝退类表述 0），题型与动词无 STEM 残留（stem 专属题型词与动词各 0 命中，实际动词为辨析／评估／还原／建构一类），双向对齐 8 条持久理解全部有章承载，三个表现性任务 GRASPS 六要素齐全且 rubric 无不可判定程度副词。梯度矩阵按文件逐行重算：10 行小计、六列合计（10/15/12/29/13/3）、总计 82、占比和 100% 全部自洽，且 82 等于例题计划实际条目数。判定记录：evals/workspace/2026-08-04-eval-7/outputs/judgment.md

• 首次覆盖 gate 修改分支（eval 1 的判定记录里一直列为未覆盖项）。在 eval 7 的 gate 1 提了一处会牵动追溯网的修改（补经济社会维度的大概念），结果：完整重呈全部五件套而非只回改动处、自查六问与一致性检查重跑（小节标题即「修改可能破坏追溯关系，故重跑一遍」）、追溯网连锁更新做全（补 EQ2 指向、LO7 追溯、新增 LO15、TG1 材料类型）、仍停在 gate 不自行推进。两处超出规范要求的行为：把框架约束冲突交回作者（作者要求配持久理解，它本拟两条 EU 但会超出 4–8 条建议区间，改为合成一条并说明理由、留下"要拆说一声"）、预告下游影响并在阶段 3 兑现（新增 EU8 意味着章节树必须有章承载，预计挤 1 章政治史；阶段 3 果然第 06 章整章给经济社会维度）。三次落盘快照证实修改-再确认循环期间文件始终 26 行不变，未落盘任何未确认内容

剩余待跑：eval 1、3、4（档案层重构影响面）；eval 2 待下一轮整体复验。eval 5、6 为历史欠账，与本轮无关。

本轮 evals 发现的待改项（下一轮处理，均非缺陷而是规范缺口）：

1. bloom-levels.md 第 7 节的章内 Bloom 经验分布是按 stem 写的（"半独立地练刚学的程序""按算法执行"），却留在内核——eval 7、8 两次独立运行都撞上这一处：eval 8 把范例研读放在分析／评价层、eval 7 在梯度备注里写"分析层 35% 是人文社科的自然结果"，理由同源。按 spec 第 4 节的判断法（换个学科照样成立才属内核），该节的分布建议应下移到各档案第 3 节；
2. humanities 档案第 1 节应把"作者未提供材料时，将降级纪律写入 00-教材设计.md「## 一」子节"固化为要求——eval 7 自发做了这一步，而它很关键：写章是另一个会话，该文件是唯一传递载体，纪律不落盘下游看不到；
3. textbook-outline/SKILL.md 阶段 1 与档案的前置输入要求有规范冲突：前者规定"不停顿直接进阶段 2"，后者要求"强烈建议作者提供学科材料"——要建议就得问、问就得停。eval 7 自行权衡为"并入这一轮提问"（正确），但应写进规范而非靠现场判断；
4. humanities 档案第 2 节应补题内局部 ⚠️ 标注的规矩（eval 8 出现"整题 ✅、题面内某数据标 ⚠️ 且声明不参与结论"这种档案未规定的形态），以及第 4 节应明确引文台账在被调度时并入 术语表.md、独立触发时随章附；
5. README 文科说明处应写明「无史料输入时约 1/3 题需事后核定」这个成本预期（eval 8 实测 3/9 挂 ⚠️，是档案第 1 节所预言的必然结果，不是缺陷）。

v0.3.0

Added

• Codex 与 WorkBuddy 支持：三个宿主都能一键装。新增 Codex 的两份分发清单——.codex-plugin/plugin.json（除公共元信息外还有 Codex 摄取必需的 skills: "./skills/" 指针与整块 interface）与 .agents/plugins/marketplace.json（条目的 source 是对象、必带 policy），装法 codex plugin marketplace add cabbage2000-lab/textbook-writer-skills + codex plugin add textbook-writer@textbook-writer-skills；新增 WorkBuddy（CodeBuddy 内核）的两份清单 .codebuddy-plugin/{plugin,marketplace}.json（结构与 Claude 版同构，skills 靠 plugin 根下的 skills/ 自动发现），装法与 Claude Code 相同的 /plugin marketplace add + /plugin install；复制安装同时保留，三宿主的用户级/项目级目录对照写进 README（WorkBuddy 项目级是 .codebuddy/skills/ 而非 .workbuddy/）。动机：跨宿主中立一直是设计约束（skill 只依赖 SKILL.md + references/ + 相对路径这套通用标准，两处宿主专有能力都带纯文本降级），但装法上没兑现——此前只有 Claude Code 能一键装，Codex 侧靠 AGENTS.md 在仓库内兜底、WorkBuddy 连目录说明都没有。三套清单格式不同、合不成一份，只能各写一份 + 用校验守住不漂
• 校验脚本 validate_manifests 从守两份清单扩展为守三宿主六份清单：公共字段（name/version/description/license）跨宿主逐字一致，外加各宿主专有要求——Codex 的 skills 指针必须指向 ./skills/（指错则一个命令都不出现）、interface 七个必填字段齐全（缺任一项官方摄取校验判整个 plugin 非法）、marketplace 条目为 source: local + path: ./ 且 policy.installation: AVAILABLE；CodeBuddy 的 marketplace 必填 owner.name、条目 source 为 ./。仓库健康检查同步扩展：.gitignore 不得忽略 .codex-plugin、.codebuddy-plugin 与 .agents，且三个 .*-plugin/ 目录只放清单文件（skills/ 必须留在仓库根，塞进清单目录会导致装上后一个 skill 都加载不到）。配套单元测试 14 项，总数 24 → 38
• 实测记录（2026-08-03）：Codex 侧在 codex-cli 0.146.0 上跑通完整安装链路——用隔离的 CODEX_HOME 添加本地路径市场、codex plugin add 装入，5 个 SKILL.md 与 8 个 references 全部装载、版本识别为 0.3.0，官方预检脚本 plugin-creator/scripts/validate_plugin.py 亦通过；Claude Code 侧沿用既有清单不受影响；WorkBuddy 侧清单格式已由作者在其他项目实测可用，本仓库按官方 plugin-marketplaces.md 规范、同一格式编写（本仓库清单未单独复测，与已验证版本的差异仅在 name/description 等元信息）；若装上后一个 skill 都不出现，先查 skills/ 是否被误塞进 .codebuddy-plugin/ 而非留在仓库根
• evals/README.md 新增「在哪个宿主跑」：Claude Code 是基线宿主（现有通过记录全部跑自它），同一套用例可在 Codex / WorkBuddy 原样复跑，判定口径相同——assertions 判的是行为红线（gate 停没停、题目验没验、续点定位对不对、落盘齐不齐）而非逐字文本，判定记录须写明宿主与版本；跨宿主结果不一致时先定位是谁错，别默认第二宿主错
• CLAUDE.md 新增「分发与跨宿主」一节：三宿主的清单文件、一键装入口与散装目录对照表、三套清单为何不能合并、跨宿主中立约束及现存两处可选增强的降级路径（Skill 工具 → 直接读对方 SKILL.md；AskUserQuestion → 编号提问等文本回复），并留下上述实测记录
• README「工作原理」补两张互补的原理图，中英各一版（images/how-it-works.svg、images/skill-composition.svg 及 .en.svg）。作者视角图以一条时间线串起「作者一句话 → 教学定位 → UbD 五件套 → 停点 1 → 章节树与 Bloom 梯度 → 停点 2 → 四段式逐章写作 → 通读定稿 → 交付目录」，把两处 gate、例题真算复核、上下文隔离、每章存盘可续写四个作者能感知的承诺画在流程上；skill 视角图画调度关系与三条硬约束——textbook 独占读写 .progress.json、textbook-chapter 只收四件轻量输入且不读别章正文、textbook-exercises 由 chapter 调用且每题真算复核，handoff-contract.md 作为地基横贯其下，textbook-init 以虚线框游离于调度链外。动机：原「工作原理」只有一棵 ASCII 调度树，既答不了作者最关心的"我会经历什么、哪里轮到我拍板"，也画不出契约与状态单写者这两条运行时约束。手写 SVG 而非截图，改文案即改图、可 diff、无二进制包袱
• writing-style.md 新增第 13 节「数学公式规范」：定界符唯一约定（行内 $...$、行间 $$...$$，禁用 \(...\)、GitHub 专属 math 代码块、align 等渲染器方言）、行内与行间的选择判据（分式/求和/矩阵一律行间）、公式编号体例（沿用图注 *图 N-M* 的写法作 *式 N-M*，不用依赖渲染器扩展的 \tag{}）、矩阵环境全书统一 bmatrix、多行推导用 aligned、公式内不写中文（理由写在公式外的正文句子里）、中文与行内公式之间加空格。动机：交付物是 .md，公式写法直接决定它在 GitHub/Obsidian/Typora/Pandoc 能否渲染；而上下文隔离让各章在不同会话写成，术语表只管符号语义、管不到公式语法，无约定必然跨章漂移
• 新增 reference textbook-outline/references/performance-task-rubric.md：表现性任务的 GRASPS 六要素（情境须是教材没直接教过的）与评价标准（rubric）写法——维度 3–5 个 × 水平 3–4 级，维度必须从持久理解或迁移目标推出（禁用"完整性/条理性"这类通用作文评分项），至少一个维度对准迁移，每格写可观察的表现描述而非程度副词；附与例题习题计划、Bloom 梯度的分工说明及 gate 呈现前自查清单。动机：UbD 阶段二的标准配置是「表现性任务 + 评价标准 + 其他证据」三件，本组合的"其他证据"由三类题承担得很充分，缺口一直在评价标准——而表现性任务是迁移目标在全书唯一的检验落点，任务不可评等于迁移目标不可验
• 教材项目落盘布局新增 99-表现性任务.md（契约第 3 节）：阶段 5 由主 skill 从 00-教材设计.md「## 四、表现性任务」派生生成的学生可读版——任务说明 + 评价标准表，去掉迁移目标编号一类教学设计元信息。单一来源仍是「## 四」，两处出入以「## 四」为准。属增量变更而非不兼容变更：v0.2.0 及更早创建的存量项目重入时此文件不存在，阶段 5 补生成即可，不影响续写
• 阶段 5 自检从 5 项增至 7 项：新增「学习目标覆盖矩阵」（输出「学习目标 × 章」矩阵，零覆盖的目标逐条列出并给补题建议——此前只查"持久理解 ↔ 章"与 Bloom 层级分布，后者统计的是层级不是目标，看不出哪条学习目标没题检验）与「表现性任务复核与落盘」（迁移目标覆盖 + 评价标准齐备核对，通过后派生生成 99-表现性任务.md）
• 新增英文版 README（README.en.md），与中文版结构对等；两版顶部互加语言切换链接。开头显著说明「产出为中文教材」这一事实——章节标题在 chapter-template.md 中硬编码为中文且规定不得改名、Bloom 动词表与排版规则均为中文，改成英文输出等于 fork 整个 references/ 层而非切一个开关，不写清楚会让英文用户误装

Changed

• 双语 README 按统一骨架重排，与姊妹项目 paper-tutor-skills 的组织逻辑对齐——读者的问题按顺序答完：这是什么 → 你凭什么这么设计 → 边界在哪 → 一张表看全 → 怎么装怎么跑 → 我该怎么开口、会拿到什么 → 凭什么信它 → 代码在哪。具体：①标题从裸仓库名改为 Textbook-Writer-Skills 教材写作套件，徽章上移到语言切换之前，首段补规模数字（5 个 skill = 1 主调度 + 3 子 + 1 独立辅助）、当前版本与契约文档指路；②新增「✅ 能做的 / ⛔ 不做的」双栏对照表——此前边界只有使用场景末尾一句「v1 明确不覆盖……」，读者带着错误期待读完全文才发现；③新增「五阶段流水线 × skill 能力」总表（阶段 / 执行 skill / 做什么 / 产出 / Gate / 验收用例六列），把此前散落在两张 SVG 的 alt 文字、工作原理正文与里程碑表里的信息合成一张，阶段名、执行者、产出、Gate 四列逐字取自 textbook/SKILL.md 的「工作流总览」，产物文件名取自契约第 3 节；④「使用场景」升级为「怎么开口说：不用背 skill 名」三列表，补上此前缺失的「你会拿到」列（读者原本无从知道产物长什么样），并新增「这些请求会被挡下——但每条都有出口」对照表与「串起来看：一本教材从头到尾」的 0→6 全景流程块；⑤原「质量保障」升格为「为什么可信」，把五条红线转成读者视角的信任论据后再接三层防线命令块，中文版补上此前只有英文版有的「第三层无法自动化」说明段；⑥「解决什么问题」三个坑压缩约四成（3 张截图原位保留，跟在对应的坑后面），「工作原理」两张 SVG 与契约说明保留；⑦里程碑表删去 evals/workspace/…/judgment.md 内部验收路径（对外部读者是噪音，判定证据改为一句话指向 evals/README.md），仓库布局代码块压成一段散文并独立为「仓库结构」一节，「贡献」与「许可」各自独立成节。动机：README 的内容一直是扎实的，缺的是组织——边界埋在末尾、能力表不写产出、没有全流程总表，读者要自己把信息从五处拼起来。两版结构逐节一一对应，后续维护不必再对着两份不同骨架改。纯编辑性改动，不涉及任何 skills/ 文件，不触发 evals 重跑
• 双语 README 的「快速开始」改写为三宿主视角，且安装方式全部改为提示词优先：新增「安装」一节，给出 Claude Code / Codex / WorkBuddy 三段可直接复制粘贴给智能体的提示词（英文版为英文）——克隆到临时目录 → 把 skills/ 下全部 5 个子目录复制进该宿主的 skills 目录 → 删临时目录 → 回报装到哪里、5 个装齐没有，读者不必敲任何命令；提示词内逐条写明 5 个 skill 以相对路径互引、漏装即断链，同名目录覆盖即更新，以及"别清空目录、别动其他来源的 skill"，WorkBuddy 那段另加「别把整个 skills/ 目录套一层」的命名陷阱提醒。四条附注覆盖项目级安装（WorkBuddy 项目级是 .codebuddy/skills/ 而非 .workbuddy/）、换用别的宿主、为何不能只装一个（textbook-exercises 也要读 outline 的 Bloom 动词表与 textbook 的交接契约）、以及 AGENTS.md 免安装路径；装错位置的表现是 skill 一个都不出现且无任何报错。原插件式一键安装（三宿主命令）与仓库内软链试跑降级为「更喜欢自己敲命令？」子节保留，并注明 WorkBuddy 插件清单的格式已由作者在其他项目实测可用。动机：目标读者是想把知识写成教材的教师、学生与内容创作者，不是命令行熟手——「按对照表把 skills/* 复制到正确目录、一个都不能漏」要求读者自己判断路径、自己保证完整性，是新手门槛最高的一步，而这步恰恰是智能体自己就能干的。顶部加 host badge，首段与使用场景表由「Claude Code」改为宿主中立表述；仓库布局补 .codex-plugin/、.codebuddy-plugin/ 与 AGENTS.md
• .claude-plugin/plugin.json 补 homepage / repository，与另两个宿主的 plugin 清单同源
• AGENTS.md 重新定位为「未安装时的兜底路径」——已装插件或已复制 skills/ 的宿主会自行加载 5 个 skill，不必依赖它的路由表；同时不再把降级路径写成 Codex 专属，并补上 AskUserQuestion 的降级说明
• workspace-layout.md 的 README 工作说明模板去掉写死的宿主名（「配合 Claude Code 的 textbook skill 组合使用」→ 宿主中立表述）——textbook-init 生成的教材目录 README 会被 Codex / WorkBuddy 用户看到，写死宿主名会误导。本轮唯一一处 skill 内容改动，按映射表需重跑 eval 6；其余改动只涉及分发清单、校验脚本与文档，不影响任何 skill 的运行行为
• CONTRIBUTING 发版流程：升版从「两处清单」改为「六份清单里带 version 的五处 + README badge」，并新增「跨宿主中立」写作规范条目
• 双语 README 的「工作原理」改为「作者视角图 → skill 视角图 → 契约说明」的顺序，原 ASCII 调度树由 skill 视角图取代（树的信息已被图完整覆盖，且图额外画出了状态单写者与契约地基）
• chapter-template.md 章内自查清单从 6 条增至 7 条（新增公式规范自查）；其 3.1 节与 textbook-chapter/SKILL.md 的文体条款列举同步补入「数学公式规范」，使其在主入口可见而非仅存于 reference 深处
• exercise-design.md 第 6 节补入跨 skill 引用：题干、解答与提示中的公式同样遵循公式规范——此前 textbook-exercises 不读 writing-style.md，题目里的公式不受任何约束，与正文形成两套语法
• textbook-outline/SKILL.md 阶段 3 第 4 项：表现性任务从"注明对应哪条迁移目标"扩充为"GRASPS 六要素 + 评价标准表 + 呈现前自查"，并写明动机
• ubd-framework.md 第 1 节三阶段表的「阶段二 确定评估证据」一行补入指向 performance-task-rubric.md 的链接（该文档自我定位为阶段 2 内核依据，表现性任务属阶段 3 产物，故独立成文而非塞入其中）
• eval 1、eval 2 断言各从 5 条增至 6 条，分别新增表现性任务评价标准与数学公式规范的客观判定项（此前记录的 eval 1/2 通过结果对应加断言前的定义）
• handoff-contract.md 第 2 节：阶段 3 → 阶段 4 契约的「表现性任务每项注明对应的迁移目标」补入「并附评价标准表」；第 3 节落盘布局新增 99-表现性任务.md 及其派生规则与存量项目兼容说明
• textbook/SKILL.md：工作流总览表的阶段 5 产出、交付摘要（新增学习目标覆盖率、表现性任务数与迁移目标覆盖情况）、交付物清单同步
• textbook-init/SKILL.md 与 workspace-layout.md：流水线文件清单、目录树、README 模板的文件构成表补入 99-表现性任务.md——init 对它同样一律不建
• eval 5 断言从 5 条增至 7 条（七项自检齐全、学习目标覆盖矩阵、99-表现性任务.md 落盘与内容）；eval 6 的「未创建任何流水线文件」断言补入 99-表现性任务.md

Fixed

• 题目验证状态行缺失（eval 5 首跑发现）：exercise-design.md 第 3 节第 4 条原文只写「验证状态标注只有两种」，全文从未写死「每道题无一例外都必须带验证状态行」，加之流程第 2 条只强调「计算类必须独立复算」，模型据此形成「计算题标验证、概念题给参考答案即可」的误读。M5 首跑实测：全书 80 题中 26 题（全为概念型独立习题）无任何验证状态标注，违反契约第 2 节「验证状态 ∈ 已验证／需作者确认，无第三种」——漏行构成了事实上的第三种状态。四处收紧：exercise-design.md 第 3 节第 4 条改为「每道题都必须带验证状态行，无一例外」并给出非计算题的具体方式（概念与记忆理解类写 ✅ 已验证（核对定义来源：…），开放探究类写 ⚠️ 需作者确认（开放题，不设标准答案））；chapter-template.md 自查第 3 条补可操作判据「逐题数一遍，题目数必须等于验证行数」；textbook-exercises/SKILL.md 纪律段由「每题必有 Bloom 标注」扩为「Bloom 标注与验证状态行，漏任一即不完整」；textbook/SKILL.md 阶段 5 自检项 4 增加清点，缺行须报为不通过项而非合规项。配套 eval 2 增第 7 条、eval 5 增第 8 条断言固化「题目数 = 验证行数」
• 中文 README 的 version badge 此前停留在 0.1.0（v0.2.0 发版时漏更新，与 plugin.json/marketplace.json 及 CHANGELOG 三处均不一致），本次随发版一并同步至 0.3.0

本轮三步（数学公式规范 → 表现性任务评价标准 → 交付闭环与学习目标覆盖）合并发布。.progress.json 状态机与既有契约字段名均未改动，落盘布局为增量新增而非不兼容变更。影响半径覆盖全部 5 个 skill：按 CONTRIBUTING.md 映射表需重跑 eval 1–6 全部六个用例（触及契约第 3 节落盘布局故补跑 6，触及阶段 5 自检与交付摘要故补跑 5）——六个用例已全部跑完并通过，见下节。

Eval 验收（0.3.0 全案回归，2026-08-03，宿主 Claude Code）

六个用例全部通过，其中 M5、M6 是首次拿到实测结果（此前长期为「⏳ 待跑」）：

用例	结果	关键证据
1	6/6	三个表现性任务各具完整 GRASPS 六要素，情境显式声明「教材从未讲过」；rubric 维度取自学科理解（如「无解情形的处理」）而非通用作文项，程度副词命中 0；3 条迁移目标全被带评价标准的任务覆盖
2	7/7	公式规范六项检查全 0 违规（\( / math 代码块 / pmatrix / 公式内中文 / 中文紧邻 $ 无空格 / \text 均为 0，bmatrix 统一）；verify.py 由判定方独立复现「全部通过」
3	5/5	四段式标题逐字一致；9 题 9 验证行；唯一 ⚠️ 需作者确认 为开放题，符合红线
4	3/3	续写行 ▶ 续写：线性代数入门，从第 2 章继续 逐字匹配契约第 5 节；01 章 SHA-1 中断前后均为 678dcad0… 逐字节一致；术语表 13 → 24 条追加而非覆盖
5	8/8	规划 11 章实写 11 章；全书 85 题 / 85 验证行零漏标；阶段 5 七项自检齐全；学习目标覆盖 14/14；99-表现性任务.md 落盘且 TG 编号出现 0 次
6	6/6	两层结构正确；.git 在工作区层，首次提交信息与规范逐字一致；四个流水线文件（含新增 99-表现性任务.md）均未被 init 预建；宿主中立表述已落到产物 README

过程中发现并修复一个既有缺陷（详见 Fixed 段第一条）：eval 5 首跑判定不通过——断言 4，全书 80 题中 26 题缺验证状态行。该缺陷非 0.3.0 引入，因 M5 从未运行而长期潜伏。修复后重跑对照：

指标	首跑	修复后重跑
题目总数	80	85
带验证状态行	54	85
缺验证行	26（32.5%）	0
⚠️ 需作者确认	0	3（开放题）

同一学科、同一条「主 skill → chapter → exercises」三层调用链、同等规模，唯一变量是四处规范收紧。另一处印证：阶段 5 第 7 项自检抓到了 rubric 里的 3 处软表述（「解释可读」「主要操作」「主要方法」），即 performance-task-rubric.md 第 3 节所禁止的写法——新规范在产出端与审核端两侧均已生效。

新发现的待办（未在本版处理）：11 章中 8 章的「核心结论」写了 6–7 条，超出 chapter-template.md 3.5 节规定的 3–5 条，系统性偏差。成因与上述缺陷同源——模板给了数字却未给可数判据，章内自查第 4 条只问「小结三件齐全」、不问条数。建议下一版按同一思路收紧。

两条判定局限，如实记录：

1. 盲测性质不完整：用例由独立子代理执行（与主会话无上下文继承），但代理具备仓库全部文件读取权限，eval 6 首跑的记录显示它自行读取过 evals.json 的断言。后续重跑已加禁读约束。所有关键判据（SHA-1、题目数与验证行数、公式规范、TG 编号计数）均由判定方在主会话独立脚本化复核，不依赖代理自述。
2. 三处分支未覆盖：① 「确认，但把 X 改一下」的 gate 修改分支（本轮四次 gate 均只回「确认」）；②...

v0.2.0

Added

• plugin 化分发：.claude-plugin/plugin.json + marketplace.json，支持 /plugin marketplace add 安装
• GitHub Actions CI：push/PR 自动跑结构校验与单元测试
• evals/：M2–M6 验收场景固化为 6 个带客观断言的行为测试用例
• CONTRIBUTING.md：架构影响半径、DoD、skill↔eval 映射、新增 skill 清单、发版流程
• 校验脚本新增四类检查：plugin 清单一致性（name/version/description 同步）、SKILL.md 500 行预算、description 1024 字符上限、frontmatter 字段白名单
• 仓库健康检查：防止 .claude-plugin 被 .gitignore 忽略（分发清单必须入库）
• MIT LICENSE，plugin.json / marketplace.json 补充 license 字段并纳入一致性校验
• docs/adr/：8 篇架构决策记录（skill 组合拆分、UbD 双 gate、契约单源、上下文隔离、状态机单一写者、真算验证、三层防线、plugin 分发），固化核心决策的背景与取舍
• Codex 基本支持：仓库根新增 AGENTS.md 作为入口指路文件（触发路由表 + 跨 skill 调用桥接说明 + 三条红线提醒），README 补充「在 Codex 中使用」小节；不改动任何 skill 行为与 handoff-contract.md 契约
• 新增 skill textbook-init（独立辅助，不入调度链）：动笔前规划并创建工作目录——一轮提问 + 方案停点确认后创建单本项目目录或多教材工作区，可选 git 版本管理（.progress.json 明确入库以支持换机续写）与 README 工作说明；只建目录骨架，绝不创建流水线文件（.progress.json/00-教材设计.md/术语表.md）。现有 4 个 skill 与契约零改动；配套 eval 6（M6）行为用例与各文档交叉引用同步
• GitHub Actions：push v* tag 时自动创建/更新对应的 GitHub Release，说明文字取自 CHANGELOG 对应版本段（.github/workflows/release.yml + scripts/extract_changelog_notes.py）

Changed

• README 按「解决什么问题 → 设计理念 → 使用场景」的读者视角重构，术语首次出现均配白话解释；skill 行为与安装方式无变化
• skills 从 .claude/skills/ 迁至顶层 skills/（标准 plugin 布局，.claude/skills 改为本地软链）
• 单元测试从 8 个扩充到 20 个，覆盖全部新增校验逻辑
• 术语更名：UbD 五件套相关表述统一改用仓库固有的描述性叫法（原隐喻沿自调研参照的开源项目，为避免误认沿袭而更换）。属不兼容变更：契约字段 UbD五件套，00-教材设计.md 落盘标题「## 二、UbD 五件套（已确认）」——旧标题落盘的存量教材项目重入前需手工改标题；独立模式改称"轻量版五件套"
• skill 全线改名：统一为 textbook- 名词族——write-textbook → textbook、design-textbook-outline → textbook-outline、write-textbook-chapter → textbook-chapter、generate-textbook-exercises → textbook-exercises（plugin 名 textbook-writer 不变，决策记录见 ADR 0009）。属不兼容变更：旧 skill 名不再存在，已安装用户升级后按新名触发；契约字段、.progress.json 与落盘布局均不变
• evals 用例 4/5 职责拆分：eval 4 收窄为只验证中断-续写机制（写 1 章→中断→续 2 章即可判定，耗时从数小时降到 ~40-60 分钟），不再要求写完整本教材；「整本书写完 + 阶段 5 自检 + 交付摘要」的验收职责移交 eval 5。目的是让日常迭代改动契约时不必每次都陪跑一整本书的写作时间。详见 evals/README.md；此前 2026-07-14 记录的 eval 4 通过结果对应收窄前的旧定义，已按新定义重新跑过（见下方 Eval 验收）

Fixed

• .gitignore 不再忽略 .claude-plugin/——此前该目录新增文件会被静默排除在版本控制外

Eval 验收（handoff-contract 术语更名全案回归）

• 用例 1–4 重跑全部通过（各 5/5 断言，2026-07-14）：M2 双 gate、M3 单章+例题真算验证、M4 端到端含中断续写
• eval 4 中断可续经独立核验：重入后 01/02 章文件 SHA-1 与中断前指纹逐字一致（已完成章未被重写），状态机续点 current_stage=4 → chapters.next=3 定位准确；全书 7 章 58 题 ⚠️ 需作者确认 残留 0 条

Eval 验收（eval 4 收窄后新定义首次运行）

• eval 4 按收窄后的新定义重跑通过（3/3 断言，2026-07-16）：判定见 evals/workspace/2026-07-16-eval-4/outputs/judgment.md
• 独立核验：中断前 .progress.json = chapters.done=[1]/next=2，续写后 = done=[1,2]/next=3；01 章文件 SHA-1 续写前后逐字一致（未被重写）；02 章引言正确衔接 01 章「本章小结」核心结论；术语表.md 由 7 条正确追加至 14 条
• eval 5（M5，全书完成 + 阶段 5 自检 + 交付摘要的新验收责任方）尚未运行，是发版 0.2.0 前唯一剩余的重量级验收项

v0.1.0

Added

• M1 骨架：4 个 skill（write-textbook 主 skill + design-textbook-outline / write-textbook-chapter / generate-textbook-exercises）
• 6 个 references：交接契约与状态机、UbD 框架、Bloom 层级表、章节模板、文体规范、例题设计规范
• 结构校验脚本 scripts/validate_skills.py 及其单元测试
• PRD、调研报告、实施计划（docs/）
• M1 验收：3 项行为冒烟测试通过，修正 15 处指令缺陷