textbook
写一整本多章节教材或成体系的课程讲义(含习题)时用它:按 UbD 逆向设计调度五个阶段——教学定位 → UbD 预期结果(gate)→ 章节树(gate)→ 逐章写作 → 审核定稿;进度落盘 .progress.json,中断后可从断点续写。触发语如"写教材"、"写一本教材"、"编写课程讲义"、"系统教材"、"textbook"。只写单篇教程、只写一章(用 textbook-chapter)、只出习题(用 textbook-exercises)时不要用它。需与 textbook-outline、textbook-chapter、textbook-exer
Install
npx skills add https://github.com/cabbage2000-lab/textbook-writer-skills/tree/main/skills/textbook
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install cabbage2000-lab-textbook-writer-skills@llmmart
git clone https://github.com/cabbage2000-lab/textbook-writer-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole cabbage2000-lab/textbook-writer-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
textbook
写教材的主 skill(orchestrator):驱动五阶段流程,管理 .progress.json 状态实现中断可续,在阶段间传递交接契约,最终交付一本有主线、有梯度、可评估的多章节 Markdown 教材。契约、落盘布局、状态机的权威定义见 references/handoff-contract.md(下称"契约文档")。
学科差异(题型集、验证手段、认知动词、章内段义)不在本 skill 里分支,收拢在学科档案中:阶段 1 判定一次,落盘为 .progress.json 的 subject_profile,逐章原样透传。规格与索引见 references/subject-profile-spec.md。
何时不触发
- 单篇教程/图文教程(用 tutorial-writer)
- 只写一章或一篇深度文章(用 textbook-chapter)
- 只要例题/习题(用 textbook-exercises)
- 只做大纲不写正文(直接用 textbook-outline)
工作流总览
| 阶段 | 名称 | 执行者 | 产出 | Gate? |
|---|---|---|---|---|
| 1 | 教学定位确认 | textbook-outline | 学科/读者起点/深度/篇幅 → 00-教材设计.md | 否(一轮提问) |
| 2 | UbD 预期结果设计 | textbook-outline | UbD 五件套 | 是(核心 gate) |
| 3 | 评估与章节设计 | textbook-outline | 章节树+例题计划+梯度报告+表现性任务 | 是(次要 gate) |
| 4 | 章节正文编写 | textbook-chapter(逐章) | NN-章.md × N + 术语表增量 | 否 |
| 5 | 审核定稿 | 本 skill | 自检报告 + 00-前言.md + 99-表现性任务.md + 交付摘要 | 否 |
gate 之外的阶段只打印一行进度(格式见契约文档第 5 节),不打断作者。
启动与重入(每次触发的第一件事)
确定教材项目目录:用户指定则用之;未指定则询问一次(默认
./<教材名>/)。找
.progress.json:- 不存在 → 全新项目:确认教材名 → 建目录 → 初始化
.progress.json(schema 见契约文档第 4 节,current_stage=1,gates 全 false,answer_layout="separate",subject_profile待阶段 1 判定后补写)→ 从阶段 1 开始; - 存在 → 按契约文档第 4 节重入规则表定位续点,打印续写行:阶段 4 用
▶ 续写:<教材名>,从第 N 章继续,其余阶段用▶ 续写:<教材名>,从阶段 N 继续;同时读出subject_profile与answer_layout供后续透传,字段缺失时按存量语义兜底并在续写行后各补一句说明,不阻塞:subject_profile缺失(v0.3.x 及更早)按stem处理、补「按 stem 学科档案续写」;answer_layout缺失(v0.4.x 及更早)按inline处理、补「按内嵌答案排版续写」——已写的章不迁移答案,一本书两种排版比统一用旧排版更糟。特别地:current_stage=2/3且对应 gate 未确认时,从00-教材设计.md读出已有产出(阶段 2 为五件套、阶段 3 为章节树/例题习题计划/梯度报告/表现性任务四项)重新呈现并等确认,不推倒重做;作者提出修改时委托 textbook-outline 执行修改与再确认循环。
- 不存在 → 全新项目:确认教材名 → 建目录 → 初始化
状态纪律:
.progress.json只由本 skill 读写(子 skill 一律不碰);每完成一个阶段、每完成一章立即更新写盘,绝不批量延迟。
阶段 1–3:委托 textbook-outline
打印 ▶ 阶段 1/5:教学定位确认(阶段 2、3 进入时同格式)。
使用 Skill 工具调用 textbook-outline(传入 {教材项目目录, 教材名});若 Skill 工具不可用或未注册,直接读取 ../textbook-outline/SKILL.md 并严格遵循其指令执行。
- 其内部两个 gate 就是本流程的 gate——gate 由该子 skill 面向作者执行,本 skill 绝不越过未确认的 gate 推进状态;
- 阶段 1 完成后(子 skill 回报
学科档案):置subject_profile=<档案 id>、current_stage=2,写盘。此后不再改动该字段——换档案等于换验证纪律与章内段式,已写的章会与后写的章不是一本书; - 阶段 2 确认后:置
gates.stage2_ubd_confirmed=true、current_stage=3,写盘; - 阶段 3 确认后:置
gates.stage3_outline_confirmed=true、current_stage=4、chapters.total=章节树章数、chapters.next=1,写盘。
阶段 4:逐章循环
打印 ▶ 阶段 4/5:章节正文编写。
对 章号 N 从 chapters.next 到 chapters.total 逐章执行(严格顺序,前章完成才写后章):
- 提取该章大纲切片:从
00-教材设计.md的「## 三、章节树与梯度规划(已确认)」取该章的章节树条目 + 例题习题计划;再按该条目的承载的学习目标编号[]到「## 二」逐条取出学习目标原文(含 Bloom 标注)一并放进切片——只取该章那几条,不把全书目标清单塞进去; - 读跨章载体:术语表.md 当前版 + 前一章文件的「## 本章小结」全节(N=1 时前章小结为空);
- 组装输入契约调用 textbook-chapter:
{章号, 章标题, 该章大纲切片, UbD五件套, 术语表, 前章小结, 学科档案, 答案排版}(五件套从「## 二、UbD 五件套(已确认)」提取{大概念[], 持久理解[], 核心问题[]};学科档案取.progress.json的subject_profile、答案排版取answer_layout,均原样透传,不重新判定)。调用方式同上:Skill 工具优先,降级读 ../textbook-chapter/SKILL.md; - 收输出契约
{章文件路径, 新增术语[], 新增符号[], Bloom标注回写[], 本章独立习题答案[]}:新增术语追加进术语表.md 的「## 术语」节、新增符号追加进「## 符号约定」节(术语表.md 不存在则先建,两节标题都写上,即使某节暂时为空——节标题是逐章追加的落点,缺标题下一章就没处可追);追加符号前先比对已登记条目:同一含义已用别的符号登记过,说明本章与前章不一致,退回该章统一符号后再追加(这正是符号表要存在的理由);Bloom 标注回写记入00-教材设计.md该章例题习题计划条目旁的"实际"标注(与"计划"并排,供阶段 5 对比);本章独立习题答案追加进98-参考答案.md(answer_layout=separate时;文件不存在则先建,含首行说明"建议先独立完成习题再对照",每章一个## 第 N 章 <章标题>小节,结构见契约文档 3.1 节)——追加前先数一遍:条目数与章内独立习题数不等、或题号对不上,当场退回该章重做,不许带着缺口往下写; - 更新状态:
chapters.done加入 N、chapters.next=N+1,写盘.progress.json。
全部章完成后置 current_stage=5,写盘。任何一章中途中断,重入时从 chapters.next 无缝继续,已完成章不重写。
阶段 5:审核定稿(自检清单,非 gate,必须全跑)
打印 ▶ 阶段 5/5:审核定稿。逐项检查并输出报告,每项给出:通过/不通过 + 具体位置 + 修改建议。
章节对齐走查:逐章读「## 本章小结」的"与持久理解的呼应",对照
00-教材设计.md的承载计划——每章至少承载一条持久理解,每条持久理解至少被一章实际承载;Bloom 梯度复核(看实际不看计划):用各章"实际"标注重算层级×章节矩阵,按 ../textbook-outline/references/bloom-levels.md 第 5 节三条规则复核,输出第 6 节格式的报告;
术语与符号一致性:对照术语表.md 抽查各章(每章至少查引言与小结两处)用词是否一致,发现不一致列出位置;符号另查两件——各章正文与题目里出现的符号是否都在「## 符号约定」节登记(漏登记的补登)、同一含义是否全书只用一个符号(一义两符的列出两处位置,由作者定统一用哪个)。学科不使用形式符号时,确认该节写着「本书不使用形式符号」而非空表;
例题验证残留与答案落位对账:搜索范围为全部章文件 加
98-参考答案.md,三件事一起查——- 验证残留:搜
⚠️ 需作者确认汇总成清单呈现。带此标注是合规的(红线允许"明确标注不能验证"),但必须让作者全部看见; - 验证行清点(
answer_layout=separate时分两处数,一把总数对不上账):章内「示范例题 + 引导练习」题数 = 章内验证行数;各章独立习题题数 =98-参考答案.md对应章节下的验证行数,且题号逐一对得上。缺验证行、缺答案条目、题号错位的逐条列出——漏行不是"合规的未验证",而是违反契约第 2 节「验证状态无第三种」,须报为不通过项; - 落位泄底检查:在各章 N.4 段内搜
参考答案、解题路径、参考要点,命中即是答案没搬干净,报为不通过项(answer_layout=inline的存量项目跳过本条);
- 验证残留:搜
循序渐进走查:逐章检查引言是否衔接前章小结、是否使用了后文才定义的概念(前置知识跳跃);
学习目标覆盖矩阵(三列对账):对照
00-教材设计.md「## 二」的学习目标清单,输出「学习目标 × 章」矩阵,每条目标查三件——- 设计侧:有章节树条目的
承载的学习目标编号[]认领它吗?(无人认领 = 阶段 3 的对齐检查漏了) - 读者侧:认领它的章,章首「本章学习目标」里真写出对应那条了吗?章末自检里有对应的复选项吗?(认领了没写 = 学生仍然看不到)
- 检验侧:至少有一道题检验它吗(题目主题与该目标的对象一致即算覆盖)?
三列任一为空的逐条列出,并给可操作建议("建议在第 N 章补 X 层级题目"/"第 N 章章首漏了这一条,补写")。动机:ubd-framework.md 2.5 节要求每条学习目标"能想象出一道题来检验它",设计时查了、交付时不查等于只查一半;上面第 2 项统计的是层级分布,看不出哪条目标没人管。加设计侧与读者侧两列的理由是同一条目标可以在三个环节各自掉队——设计文档里有、章节树没认领;认领了、章首没写;章首写了、没有题检验——只查最后一环,前两种漏法会一路漏到读者手上;
- 设计侧:有章节树条目的
表现性任务复核与落盘:核对「## 四、表现性任务」——每条迁移目标至少被一个任务覆盖、每个任务附评价标准表(维度从持久理解或迁移目标推出,每格为可观察的表现描述);核对通过后从「## 四」派生生成
99-表现性任务.md(学生可读版:任务说明 + 评价标准表,去掉迁移目标编号一类设计元信息;写法见 ../textbook-outline/references/performance-task-rubric.md)。动机:表现性任务是迁移目标在全书唯一的检验落点,留在设计文档里等于没交付。成书前页生成与走查:生成
00-前言.md(固定三节「本书写给谁 / 怎么用这本书 / 目录」,各节来源与改写要求见契约文档 3.2 节),然后逐条核对目录里的每个链接指向的文件真实存在、章号与章标题与磁盘文件逐字一致——指不到的链接当场修掉,不作为"待作者处理"的不通过项放过(这一项是主 skill 自己能修的,报给作者没有意义)。动机:前面七项保的是内容质量,这一项保的是读者进得来——一本没有前言和目录的教材,读者要靠猜才知道从哪读起、答案在哪查。
报告完毕后:不通过项由作者决定修不修;作者要求修 → 定位到章,重新组装该章输入契约调用 textbook-chapter 修订(修订后相关项复查)。全部处理完写盘 stage5_passed:无遗留不通过项(全过或均已修复)置 true;作者决定不修的不通过项仍存在置 false,并在交付摘要中列明遗留项。
交付
输出交付摘要:章数 / 三类题总数 / 已验证题数 / ⚠️ 需作者确认 条数 / 梯度复核结论 / 学习目标覆盖率(已覆盖 ÷ 总数,零覆盖的逐条列出)/ 表现性任务数与迁移目标覆盖情况 / 未修复项清单(如有)。
交付物为教材项目完整目录(布局见契约文档第 3 节):00-前言.md、00-教材设计.md、NN-<章标题>.md × N、98-参考答案.md、99-表现性任务.md、术语表.md、.progress.json。摘要里向作者点明两句:读者从 00-前言.md 进入(前言 + 怎么用 + 带链接的目录),00-教材设计.md 是作者向设计文档、不必给读者;独立习题的答案与验证在 98-参考答案.md,章内只留题干,读者可先做后对(answer_layout=inline 的存量项目不提后一句)。
边界说明(须向作者说明):定稿指文字与结构层面完成;若正文含人工截图标注块,需作者按标注自行补图后才算可发布。
Files (textbook-writer-skills)
-
references
-
profiles
-
economics.md 16.2 KB
# 学科档案:economics 本档案的结构与边界由 [../subject-profile-spec.md](../subject-profile-spec.md) 规定:这里只写经济学相对内核的**增量**,内核规则(三类题定位、验证状态二值化、Bloom 判定原则、四段式脚手架逻辑、通用文体规范、UbD 五件套与表现性任务写法)不在此重述。 一句话定位:经济学是**混合可验证**学科——模型求解能像 `stem` 那样复算,统计数据只能像 `humanities` 那样核对来源,政策论述两者都不适用而要给论证要点与评价标准。三类手段在同一本教材里交织出现,任何一份单档案都只覆盖其中一段,这是本档案存在的理由。 ## 1 适用范围与判定 适用于**同一门课里既有可复算的模型题、又有须核对来源的数据题**的学科:经济学各分支(微观、宏观、计量、国际经济学、发展经济学、产业组织)与金融学。 与相邻档案的分界: - **纯数理推导为主体**(数理经济学、金融工程、随机分析)——题目几乎全是求解与证明,实证数据只作背景,走 [stem.md](stem.md); - **以论证与文本为主体**(经济思想史、比较经济制度、政治经济学)——答案取决于学派立场与文献解读,走 [humanities.md](humanities.md); - **两类题在同一本书里交织**(绝大多数经济学原理、中级微观/宏观、计量入门教材)——走本档案。 判定法:翻一遍拟定的例题计划,如果既有「求均衡/算弹性」这类可复算题,又有「用某年真实数据说明」这类须查证题,就是本档案。 **心理学、地理学等同构学科可参照使用**,已知差异写在前面:第 2 节的「实证数据题」「计量与统计推断」两型通用(同样是查权威来源 + 实跑数据),「模型求解」「比较静态与图形分析」是经济学特有的形态,这两型在心理学里多退化为实验设计与效应量计算。参照使用时按 spec 第 7 节向作者说明后再决定,不得静默套用。 **前置输入要求**:本档案有一半题型指向「核对来源」,因此阶段 1 应建议作者提供数据来源清单(用哪个统计年鉴、哪个数据库、口径以谁为准)与指定教科书版本。作者未提供且当前环境无法查证时,数据类题一律走 `⚠️ 需作者确认`——**绝不凭记忆写出具体统计数值**。这是本档案最重要的一条纪律:一个凭印象写出的「2023 年 GDP 增速 5.4%」比一道算错的题更难被读者发现,而它会让整本书的数据都变得不可信。 **这条纪律必须落盘**(索要材料与落盘的动作在 [../../../textbook-outline/SKILL.md](../../../textbook-outline/SKILL.md) 阶段 1):作者未提供数据来源清单时,把三点写进 `00-教材设计.md`「## 一、教学定位」的子节——① 本书未获指定的统计口径与数据库,各章数据题按"核不实即标注、绝不凭印象写数值"处理;② 数据类题预期一律挂 `⚠️ 需作者确认(数据未核)`,**模型题与概念题不受影响**(它们可复算,不依赖外部来源)——这条要写明,否则作者会以为整本书都待核;③ 作者中途补充来源清单时,已写章节的 ⚠️ 条目按数据来源台账回溯核对。理由同 `humanities`:写第 3 章是另一个会话,对话里说过的口径传不过去。 ## 2 题型集与验证方式 | 题型 | 示例 | 验证手段 | 无法验证时的降级 | | ------ | ------ | ---------- | ---------------- | | 模型求解 | 求市场均衡、消费者最优选择、IS-LM 联立均衡 | 写一段与解答路径不同的 Python(sympy/numpy)复算,用 Bash 实际执行并比对结果(解答用代数消元,验证就用 `sympy.solve` 直接解) | 环境无 Python 时手算两遍交叉核对,验证状态注明「手算交叉核对」 | | 比较静态与图形分析 | 需求右移对均衡的影响、税负归宿、最低工资的福利效应 | 两步:符号求导核验方向(如用 sympy 求 $\partial P^*/\partial t$ 的符号)+ **图文一致性核对**(曲线移动方向、交点位移、面积增减与文字结论逐项对齐) | 模型无解析解 → 代入两组具体参数数值比对方向;仍不可得 → `⚠️ 需作者确认(比较静态方向待复核)` | | 指标计算与核算 | 计算 GDP、CPI、基尼系数、弹性、乘数 | 复算 + **口径核对**:定义式来源(教材设计文档的约定或统计口径文件)、单位、基期、名义与实际是否混用,四项逐项过一遍 | 口径来源不明确 → `⚠️ 需作者确认(核算口径待确认:<项>)` | | 实证数据题 | 用真实统计数据说明某趋势、解读一张统计表 | 核对权威数据源的原始发布值(国家统计局、世界银行、FRED、IMF 等),答案后标明指标全称、发布机构、口径、单位与年份;作者提供了材料时以材料为准 | 取不到原始数据 → 改用作者材料内已有的数据;仍不可得 → `⚠️ 需作者确认(数据未核)`,且**不得凭记忆写出具体数值** | | 计量与统计推断 | 解读回归结果、检验假设、判断识别问题 | 给出数据的题实际跑一遍(statsmodels/numpy)核对系数、标准误与结论;纯解读题核验推断链条:识别假设是否成立、有无把相关当因果、样本能否支撑该结论 | 无数据或环境不可执行 → `⚠️ 需作者确认(回归结果未实跑)`;识别假设无法判断 → `⚠️ 需作者确认(识别策略待复核)` | | 概念辨析 | 区分「需求变动」与「需求量变动」、区分帕累托改进与卡尔多-希克斯改进 | 核对定义来源:教材设计文档的约定,或学科公认定义(注明所据教科书/学派) | 学派界定有实质分歧 → `⚠️ 需作者确认(学派分歧,已列主要界定)`,同时列出两到三种界定 | | 政策分析与论述 | 评价某项产业政策、比较两种货币政策工具 | 不设标准答案:给**论证要点**(须触及哪些传导机制、哪些经验证据、哪些反方意见)+ 一张**评价标准表**(维度与写法见 [../../../textbook-outline/references/performance-task-rubric.md](../../../textbook-outline/references/performance-task-rubric.md) 第 3 节) | 恒为 `⚠️ 需作者确认(开放题,不设标准答案)`,并标注「开放题」 | 三条最容易被绕过的地方: - **复算路径必须与解答路径不同**:解答用代数消元求的均衡,验证就用 `sympy.solve` 直接解。沿同一条路径再走一遍,重复的是同一个错误,等于没验证; - **「这道题只是引个数据,不算题目」是误读**:正文里的数据同样受第 4 节文体条款第 2 条约束,题目里的数据走「实证数据题」核对。数据不像算错那样能被读者当场发现,所以它更需要来源; - **论述题的开放性只免除标准答案,不免除验证**:题干里引用的每个数据、每份政策文本仍走上表对应题型核过,且必须附论证要点与评价标准。没有评价标准的政策论述题是一句口号——作者无法评,学生不知道「好」长什么样。 ## 3 认知动词、层级示例与章内分布 通用动词基线见 [../../../textbook-outline/references/bloom-levels.md](../../../textbook-outline/references/bloom-levels.md) 第 2 节,对所有学科有效。本档案补充经济学特有动词: | 层级 | 本学科特有动词 | | ------ | ------------- | | 记忆 | 写出定义式、指出曲线与坐标轴的含义、列举政策工具 | | 理解 | 解释传导机制、把模型结论翻译成经济含义、区分名义量与实际量 | | 应用 | 求解均衡、计算弹性与乘数、按口径核算指标、把模型套用到一个新市场 | | 分析 | 做比较静态、拆解传导链条、区分相关与因果、辨识识别假设、诊断口径混淆 | | 评价 | 评估政策的效率与分配后果、权衡两种政策工具、检验实证证据的说服力 | | 创造 | 建立简化模型、设计政策方案、提出可检验的经验假说 | 同一知识点在六个层级各长什么样(以「弹性与税负归宿」为例;这是判定标尺的示意,不宜原样搬进教材当正式题目——至少换数据、换市场): | 层级 | 题目示例 | | ------ | --------- | | 记忆 | 写出需求价格弹性的定义式,并说明弹性绝对值大于 1 时该商品称作什么。 | | 理解 | 用自己的话解释:同样一笔单位税,为什么在需求越缺乏弹性的市场上,消费者承担的份额越大? | | 应用 | 某商品需求为 $Q_d = 100 - 2P$、供给为 $Q_s = 20 + 2P$。政府向卖方每单位征税 4 元,求征税后的均衡价格、成交量与消费者实际承担的税额。 | | 分析 | 承上题,把需求改为 $Q_d = 100 - 6P$(其余不变),税负在买卖双方之间的分担比例如何变化?指出这一变化由哪个参数决定,并说明理由。 | | 评价 | 有观点认为「提高最低工资必然增加低技能劳动者失业」。分别在完全竞争劳动力市场与买方垄断市场两种设定下评估该论断,说明它在什么条件下成立、什么条件下不成立。 | | 创造 | 为「某城市对网约车实行牌照限量」建立一个简化的供求模型:写出你的假设、待检验的命题、检验它需要哪些数据,并说明模型的适用边界。 | **章内 Bloom 分布(非硬规则,消费者:阶段 3 例题习题计划)**: 本学科的分布是**双峰**的——模型题与政策题的认知路径不同,不要按单一区间去平: - 示范例题:模型求解类落记忆~应用层(先完整示范一次求解,并把每步的经济含义读出来);比较静态类可直接落分析层("结论依赖哪个参数"本身就是分析动作); - 引导练习:应用~分析层。本学科最好的引导变式是**换参数符号**(把弹性从大改小,看结论如何翻转),这类题表面是代入计算、实质是分析,判层按认知操作不按表面难度; - 独立习题与论述:计算与实证题落应用~分析;**政策论述题落评价层,且评价层在本学科是常规而非点缀**——"这项政策该不该做"是本学科的基本问法; - 创造层:建模题(建立简化模型、提出可检验的经验假说)是自然落点,但依赖前置的模型工具,通常出现在中后段章节。 数据与实证类题目有一处最容易判错:**查出一个统计数值是记忆层,用它去检验一个命题是评价层**——同一道题多问时按内核规则取最高层。 ## 4 章内段义与载体扩展 **四段标题文案**(可直接复制,N 为章号;不得改名、不得增删段、不得调换顺序): ```markdown ## N.1 概念与模型讲解 ## N.2 示范例题 ## N.3 引导练习 ## N.4 独立习题与论述 ``` 段位语义与其他档案一致(讲 → 教 → 扶 → 放)。首段与末段的文案点出经济学的两个特征:概念要落到**模型**上才算讲完,而末段除算题外还要容纳**政策论述**。 **后三段的教学动作**(支撑程度、数量配额与纪律见 [../../../textbook-chapter/references/chapter-template.md](../../../textbook-chapter/references/chapter-template.md) 第 3 节,此处只定义「具体做什么」): - **N.2 示范例题**:完整解题过程,每步给一行理由;经济学的增量是**每步除了「数学上做了什么」还要给一句经济含义**——算出 $\partial P^*/\partial t = 1/3$ 之后要说「消费者承担三分之一税负」。缺了这一句,例题就退化成解方程,读者学会了算却不知道算出来的东西意味着什么。每题末尾加一句「回顾:这道题用到了<模型>的<哪个机制>」,把题拉回概念主线; - **N.3 引导练习**:与某道示范例题**同构**,换数据、换市场或**换参数符号**(把需求弹性从大改小,看结论如何翻转)——最后一种是经济学特有的好变式,因为它练的正是「结论依赖哪个参数」这个判断;提示 1 给切入的模型或该画哪张图,提示 2 给关键方程或关键位移; - **N.4 独立习题与论述**:三种构成——**变式题**(换条件、同模型)、**组合题**(跨模型综合,如把弹性与税负归宿接到福利分析上)、**政策论述题**(少量,附论证要点与评价标准表,标注「开放题」)。按 Bloom 阶梯先低后高排列。 **必配图示类型**:供需图与曲线移动图是经济学最核心的直观载体,纯概念章至少一图。载体分两类——**坐标类图示(供需图、IS-LM 图、无差异曲线、洛伦兹曲线)用内嵌 SVG**,mermaid 画不出坐标系与曲线相交;**传导机制、决策流程、市场结构分类用 mermaid**。标注约定全书统一:纵轴价格、横轴数量,曲线标 $D$ / $S$ 且移动前后用下标 0 与 1 区分,均衡点标 $E$。 **术语表结构扩展两条**(契约规定的两节与其列定义不变,见 [../handoff-contract.md](../handoff-contract.md) 第 3 节): 1. **`## 符号约定` 节必须写满**(同 `stem` 档案):同一个量全书用同一符号(需求 $Q_d$、均衡价格 $P^*$、弹性 $\varepsilon$),逐章由回报字段 `新增符号[]` 追加; 2. **数据来源台账**,附在两节之后: ```markdown | 数据指标 | 来源与发布机构 | 口径/基期/单位 | 首次引用章节 | 核对状态 | ``` **动机**:各章在不同会话里独立写成(上下文隔离),术语表只管术语与概念,管不到统计口径。没有台账,第 3 章的 GDP 用 2020 年不变价、第 8 章换成当年价,读者会以为数据自相矛盾;而同一指标两处取自不同机构、数值对不上,比算错一道题更伤全书可信度。 **台账落在哪**:被 `textbook` 调度时并入 `术语表.md`,跟在两节之后,由各章逐章追加;`textbook-chapter` **独立触发**写单章时没有项目目录,台账随章附在「本章小结」之后,二级标题写 `## 数据来源台账`。两种情形都必须有,变的只是落点。 **文体附加条款**([../../../textbook-chapter/references/writing-style.md](../../../textbook-chapter/references/writing-style.md) 第 13 节数学公式规范**全节适用**——经济学模型全是公式,题干、解答与正文出自同一本书,公式语法两套会让读者以为换了本书): 1. **数据必带来源与口径**:正文与题目里的每个具体统计数值,紧跟来源标注(如「(来源:国家统计局,2023 年,当年价,亿元)」),含指标全称、发布机构、年份、口径(名义或实际、基期、单位)。无来源的数值等同未验证,不得进入正文; 2. **模型假设先行**:给出任何模型结论前先写明假设(完全竞争还是垄断?信息对称吗?短期还是长期?),并随结论写明适用边界。经济学结论对假设极其敏感——抹掉假设的结论不是简化,是错的; 3. **实证与规范分开写**:「最低工资使就业下降 2%」是实证命题,「应当提高最低工资」是规范命题,不混在同一句里;规范判断须写明所依据的价值标准(效率、公平,以及哪一种公平); 4. **相关不等于因果**:陈述经验规律时写明识别策略(随机实验、双重差分、工具变量……),拿不出识别策略就明确标注这是相关性,不用「导致」「使得」一类因果动词描述相关关系; 5. **学派归属清楚**:凡属某学派的论断(凯恩斯主义、货币主义、新古典、奥地利学派)写明是谁的论断;存在实质分歧的问题列出主要立场,教材自身的立场也要可辨识,不假装叙述中立; 6. **图形标注统一**:坐标轴、曲线、均衡点按上文约定标注;曲线移动必须在正文说明「移动的是哪条、往哪个方向、由什么驱动」——只画不说,读者看到的是两条线换了位置,不是一次经济学推理; 7. **单位与量纲一致**:同一章内不混用「亿元/万亿元」「百分比/百分点」;增长率与水平量分别标注,「上升 2 个百分点」与「上升 2%」不得互换使用。 -
humanities.md 14.6 KB
# 学科档案:humanities 本档案的结构与边界由 [../subject-profile-spec.md](../subject-profile-spec.md) 规定:这里只写人文社科相对内核的**增量**,内核规则(三类题定位、验证状态二值化、Bloom 判定原则、四段式脚手架逻辑、通用文体规范、UbD 五件套与表现性任务写法)不在此重述。 一句话定位:STEM 教材最致命的失真是**算错**,人文社科教材最致命的失真是**引文伪造与史实错位**——虚构文献、张冠李戴的名言、错乱的纪年。两者是同一类信任杀手,所以本档案保留同一条纪律(每题必验、状态二值),只把"复算"换成"**核对来源**"。 ## 1 适用范围与判定 适用于**答案取决于论证与立场、但事实性断言可核查**的学科:历史、哲学、文学、政治学、社会学、艺术史、宗教研究。 与 `stem` 档案的分界是一句话:**这门学科的典型习题,答案能不能由一条与解答不同的路径重新算一遍并比对结果?**能,走 [stem.md](stem.md);不能——答案随论证质量与视角变化——走本档案。 三类容易站在边界上的学科,判定如下: - **语言学习、法学、会计**:语法规则、法条、判例、准则都是确定性可核查事实,其习题接近"有标准解"。以规则应用题为主时走 `stem` 档案(把"复算"读作"查条文原文并比对");以案例论证、法理辨析为主时走本档案; - **经济学、金融学**:有专属档案 [economics.md](economics.md)——模型题复算、数据题核来源、政策题给论证要点,三类手段在一本书里交织;只有经济思想史、比较经济制度这类以论证与文本为主体的,才走本档案; - **心理学、地理**:计算题与实证数据题走 [stem.md](stem.md) 档案,理论论述与政策讨论部分按本档案第 2 节的"论述/小论文"处理; - **交叉主题**(如科学史、数字人文):以哪一类题为主体就走哪份档案,另一类按对方档案的对应题型处理,并在教材设计文档里写明这个分工。 **前置输入要求(比 `stem` 严格)**:本档案的验证手段全部指向"核对来源",因此阶段 1 应强烈建议作者提供学科材料(教材、史料选编、课程标准、指定文献版本)。作者未提供且当前环境无法查证时,第 2 节的降级路径一律走 `⚠️ 需作者确认`——**绝不凭记忆编造引文、出处、年份或页码**。这是本档案最重要的一条纪律:一个编出来的出处比一个算错的数字更难被读者发现,伤害也更大。 **这条纪律必须落盘**(索要材料与落盘的动作在 [../../../textbook-outline/SKILL.md](../../../textbook-outline/SKILL.md) 阶段 1):作者未提供材料时,把三点写进 `00-教材设计.md`「## 一、教学定位」的子节——① 本书未获作者指定的史料与文献版本,各章引文按"核不实即标注、绝不逐字编造"处理;② 预期约三分之一的题会挂 `⚠️ 需作者确认(引文未核)`,作者须在定稿前逐条核定;③ 作者中途补充材料时,已写章节的 ⚠️ 条目按引文台账回溯核对。**写下来才算数**:写第 3 章是另一个会话,那时读得到的只有这个文件。 ## 2 题型集与验证方式 | 题型 | 示例 | 验证手段 | 无法验证时的降级 | | ------ | ------ | ---------- | ---------------- | | 事实性/年表 | 排列事件先后、指出人物与事件的对应 | 核对作者提供的材料或学界公认年表,答案后标出所据来源 | 来源不可得 → `⚠️ 需作者确认(史实出处待核:<项>)` | | 引文辨识与文本细读 | 分析一段原文的论证或修辞 | **引文逐字核对原文**,记明版本/篇目/位置(如「中华书局点校本《史记·项羽本纪》」);核对无误才输出 | 取不到原文 → 改用作者材料内已有的引文;仍不可得 → `⚠️ 需作者确认(引文未核)`,且**不得凭记忆写出引文原文** | | 概念辨析 | 区分"民族主义"与"爱国主义" | 核对定义来源:教材设计文档的约定,或学界主流界定(注明所据学派/作者) | 学界有实质分歧 → `⚠️ 需作者确认(学界有争议,已列主要分歧)`,同时列出两到三种主要界定 | | 史料/文本评析 | 判断一则材料的可靠性与局限 | 两步:核实材料真实存在(同"引文辨识"的核对方式)+ 核验评析逻辑自洽(无循环论证、无以今律古、无孤证立论) | 材料无法核实 → `⚠️ 需作者确认(材料出处待核)`;逻辑核验不过 → 修改评析后重新核验 | | 因果解释与论证 | 解释某事件的多重成因并排序 | 逐步核验论证链条:每步所引事实是否已按上列题型核过、推论有无跳步;**并附一段反方视角**(最强的相反解释是什么、为何本文仍取此解) | 链条存在无法核验的环节 → `⚠️ 需作者确认(论证链条待复核:<环节>)` | | 论述/小论文 | 800 字论述某命题 | 不设标准答案:给**论证要点**(须触及哪些证据与哪些反驳)+ 一张**评价标准表**(维度与写法见 [../../../textbook-outline/references/performance-task-rubric.md](../../../textbook-outline/references/performance-task-rubric.md) 第 3 节) | 恒为 `⚠️ 需作者确认(开放题,不设标准答案)`,并标注「开放题」 | 两条最容易被绕过的地方: - **"论述题反正没有标准答案,所以不用验证"是误读**。论述题的开放性只免除"标准答案",不免除验证——题干里引用的每则材料、每个年份、每处引文仍走上表对应题型的核对,且必须附论证要点与评价标准。没有评价标准的论述题是一句口号:作者无法评,学生不知道"好"长什么样; - **核对必须走独立路径**:判断一处引文是否属实,要回到原文核,不是"读一遍觉得像"。凭印象确认与凭印象编造之间只差一步。 **本学科最常遇到题内局部 ⚠️ 的形态**(规矩见 [../../../textbook-exercises/references/exercise-design.md](../../../textbook-exercises/references/exercise-design.md) 第 3 节第 4 条的边界段):题干为交代背景顺带提了一个未核的年份或人物细节,而设问针对的是材料的论证结构——此时给该项就地标 `⚠️` 并注明「不参与本题结论」,整题仍可 ✅。**自查一句就够**:把这句背景整个删掉,设问还成不成立?成立才留 ✅,不成立就是整题 `⚠️`。 ## 3 认知动词、层级示例与章内分布 通用动词基线见 [../../../textbook-outline/references/bloom-levels.md](../../../textbook-outline/references/bloom-levels.md) 第 2 节,对所有学科有效。本档案补充人文社科特有动词: | 层级 | 本学科特有动词 | | ------ | ------------- | | 记忆 | 指出时间与人物、列举史实、说出文献出处 | | 理解 | 转述材料大意、用自己的话概括某派观点、把史料译为今语 | | 应用 | 把某分析框架用于一则新材料、按体例作注、在新材料中识别同一修辞 | | 分析 | 辨析材料的立场与局限、还原论证结构、比较两种解释、区分史实与史论 | | 评价 | 评估证据是否充分、检验因果链条、权衡不同解释的说服力、判断史料的可靠性等级 | | 创造 | 建构一种解释、撰写论证、设计探究方案、为某命题拟出可检验的问题 | 同一知识点在六个层级各长什么样(以"工业革命为何首先发生在英国"为例;这是判定标尺的示意,不宜原样搬进教材当正式题目——至少换材料、换角度): | 层级 | 题目示例 | | ------ | --------- | | 记忆 | 列举英国工业革命起步阶段的三项关键技术发明及其大致年代。 | | 理解 | 用自己的话说明"圈地运动为工业化提供了劳动力"这一说法的含义。 | | 应用 | 用课文给出的"要素禀赋"框架,分析一则关于英国煤矿分布的新材料。 | | 分析 | 阅读两段分别强调"制度保障"与"殖民市场"的史学论述,指出二者在证据选择上的差异,并说明各自最薄弱的一环。 | | 评价 | 有学者认为"英国的专利制度是工业革命的决定性条件"。评估这一论断的证据是否充分,并说明你的判断依据。 | | 创造 | 就"为何工业革命没有首先发生在荷兰"提出一个可检验的解释,列出你需要哪些证据来支持它。 | **章内 Bloom 分布(非硬规则,消费者:阶段 3 例题习题计划)**: - 范例研读(三类题里的示范例题):理解~分析层。本学科的"示范"不是示范一套可执行程序,而是示范一次材料研读——把一段史料或文本读出立场、结构与局限,这个动作本身就在分析层;压到记忆层就示范不出任何东西了; - 引导分析:主落分析层(给定材料与提示,半独立地做一次辨析); - 独立论述与探究:分析~评价为主。**评价层在本学科是常规而非点缀**(评估证据是否充分、权衡两种解释的说服力); - 创造层:同样不是稀客。建构一种解释、撰写一篇论证、拟出可检验的问题都是本学科的常规作业形态,中后段章节每章有 1 道并不异常。 因此本学科的全书梯度天然重心偏高:**分析层占到三成上下是正常结果,不是梯度失衡**。若梯度报告因低层占比不足而告警,先核对是不是"列举史实、说出文献出处"这类记忆层题目给得过少,而不是回头把分析层的题降级——降级会把研读变成默写,正是本学科最该避免的那种题。 ## 4 章内段义与载体扩展 **四段标题文案**(可直接复制,N 为章号;不得改名、不得增删段、不得调换顺序): ```markdown ## N.1 概念与脉络讲解 ## N.2 范例研读 ## N.3 引导分析 ## N.4 独立论述与探究 ``` 段位语义与 `stem` 档案一致(讲 → 教 → 扶 → 放),换的是每段的教学动作:本学科要示范的不是"怎么算",而是**怎么读一则材料、怎么搭一条论证**。 **后三段的教学动作**(支撑程度、数量配额与纪律见 [../../../textbook-chapter/references/chapter-template.md](../../../textbook-chapter/references/chapter-template.md) 第 3 节,此处只定义"具体做什么"): - **N.2 范例研读**(全脚手架):给出一段原始材料(史料、文本、案例)+ 完整分析示范,**每一步都标出这一步在做什么推断动作**——识别材料性质与来路 → 提取核心主张 → 检验其证据 → 指出立场与局限 → 得出有边界的结论。每则研读末尾加一句「回顾:这段分析用到了<方法>的<哪一步>」,把它拉回本章方法主线; - **N.3 引导分析**(部分脚手架):给一则**新材料**,与某则范例研读同构——练的是同一套阅读程序;提示 1 给切入视角(从哪个角度读这则材料),提示 2 给关键证据链(该盯住哪几处文字),之后附完整分析供对照; - **N.4 独立论述与探究**(无脚手架):三种构成——**变式题**(换材料、同方法)、**综合题**(跨概念或跨材料对比)、**论述题**(少量,附论证要点与评价标准表,标注「开放题」)。按 Bloom 阶梯先低后高排列。 **必配图示类型**:时间轴(分期与并置)、流派或谱系图(学说传承)、概念关系图(对立与派生),用 mermaid 代码块或内嵌 SVG,随正文直接产出。纯概念章至少一图——人文社科的"直观"靠时序与关系的可视化,不靠公式。 **术语表结构扩展**:契约规定的两节(`## 术语` / `## 符号约定`,见 [../handoff-contract.md](../handoff-contract.md) 第 3 节)中,**`## 符号约定` 节在本档案下保留标题、正文写一行「本书不使用形式符号」**(计量史学、形式逻辑一类确有符号的章节按需填写)——节不删,是为了让阶段 5 能区分"这门学科没有符号"与"符号漏登记了"。除两节外,另附一张**引文台账**表: ```markdown | 引文出处 | 版本/译本 | 首次引用章节 | 核对状态 | ``` 同一文献全书只用一个版本,同一段引文全书只用一种译法。**动机**:各章在不同会话里独立写成(上下文隔离),术语表只管术语与概念,管不到版本与译名。没有台账,第 3 章引的《论语》是杨伯峻译本、第 8 章变成理雅各译本,专业读者一眼看出这不是同一本书;而"同一句话两处译得不一样"会让读者以为是两句话。 **台账落在哪**:被 `textbook` 调度时并入 `术语表.md`,跟在上述两节之后,由各章逐章追加——与术语、符号同一个落点,作者只需翻一个文件;`textbook-chapter` **独立触发**写单章时没有项目目录,台账随章附在「本章小结」之后,二级标题写 `## 引文台账`。两种情形都必须有台账,变的只是它落在哪个文件。 **文体附加条款**([../../../textbook-chapter/references/writing-style.md](../../../textbook-chapter/references/writing-style.md) 第 13 节数学公式规范**不适用**本档案,除计量史学、形式逻辑一类确有公式的章节按需启用): 1. **引文必带出处**:引文用引用块呈现,紧跟一行出处(`——<作者>《<篇名>》,<版本>,<卷/页>`)。无出处的引文等同未验证,不得进入正文; 2. **原文与今译分列**:古汉语或外语原文先给原文,再给今译;只给译文时须注明译者或"本书译"; 3. **纪年统一**:正文用公元纪年,首次出现的朝代纪年、年号纪年在括号内附公元年(如"崇祯十七年(1644)");跨文明章节涉及不同历法时,在章首统一说明换算口径; 4. **译名统一**:人名、地名、著作名首次出现附原文(如"韦伯(Max Weber)"),此后全书只用一种译法,登记进术语表; 5. **史实与史论分开写**:陈述事实与作出评判不混在同一句里——"1789 年三级会议召开"是事实,"这标志着旧制度的破产"是判断,判断须给出依据或指明这是谁的判断; 6. **不以今律古**:用当代概念解释历史现象时明确标注这是后设视角(如"用今天的'民族国家'概念来看……"),避免把现代范畴当作当时人的自觉; 7. **观点归属清楚**:凡属某学派或某学者的论断,写明是谁的论断;教材自身的立场也要可辨识,不假装叙述中立。 -
stem.md 7 KB
# 学科档案:stem 本档案的结构与边界由 [../subject-profile-spec.md](../subject-profile-spec.md) 规定:这里只写 STEM 学科相对内核的**增量**,内核规则(三类题定位、验证状态二值化、Bloom 判定原则、四段式脚手架逻辑、通用文体规范)不在此重述。 ## 1 适用范围与判定 适用于**题目有确定解、答案能被独立复算**的学科:数学各分支、物理、化学、工程、计算机科学与算法。 判定标准是一句话:**这门学科的典型习题,能不能由一条与解答不同的路径重新算一遍并比对结果?**能,走本档案;不能(答案取决于论证与立场,如史论、文学评论),本档案的第 2 节验证手段对它无效,按 spec 第 7 节处理——向作者说明后再决定,不得静默套用。 **经济学与金融学有专属档案** [economics.md](economics.md)(模型题可复算、数据题只能核对来源,两类在同一本书里交织)——只有纯数理推导为主体时(数理经济学、金融工程)才走本档案。其余半可验证学科(心理学、地理等)的计算题与实证数据题适用本档案;其中的论述与政策讨论部分,按本档案第 2 节的「开放/探究题」处理。 ## 2 题型集与验证方式 | 题型 | 示例 | 验证手段 | 无法验证时的降级 | | ------ | ------ | ---------- | ---------------- | | 数值计算 | 解方程组、求行列式、数列求和 | 写一段与解答路径不同的 Python(sympy/numpy)复算,用 Bash 实际执行并比对最终结果 | 环境无 Python 时手算两遍交叉核对,验证状态注明「手算交叉核对」 | | 符号推导 | 化简、求导、证明恒等式 | sympy 符号验证 + 逐步核验每步依据 | 符号工具不可用时逐步核验每步依据,验证状态注明核验方式 | | 证明题 | 证明某性质或定理 | 逐步核验证明链条:每步引用的定义/定理是否成立、是否已在教材前文出现 | 链条存在无法核验的环节 → `⚠️ 需作者确认(证明链条待复核:<环节>)` | | 代码题 | 实现算法、复现数值实验 | 实际运行代码,核对输出与题目声称的结果一致 | 环境无法执行 → `⚠️ 需作者确认(代码未实际运行)` | | 概念辨析 | 判断正误并说明理由 | 核对定义来源:教材设计文档的约定,或学科公认定义 | 来源不明确 → `⚠️ 需作者确认(定义来源待确认)` | | 开放/探究题 | 数值实验设计、建模讨论 | 不设标准答案,给参考要点并标注「开放题」 | 恒为 `⚠️ 需作者确认(开放题,不设标准答案)` | 「复算路径必须与解答路径不同」是本档案最容易被偷懒绕过的一条:解答用行变换求的,验证就用 `numpy` 直接求;沿着同一条路径再走一遍,重复的是同一个错误,等于没验证。 ## 3 认知动词、层级示例与章内分布 通用动词基线见 [../../../textbook-outline/references/bloom-levels.md](../../../textbook-outline/references/bloom-levels.md) 第 2 节,对所有学科有效。本档案补充 STEM 特有动词: | 层级 | STEM 特有动词 | | ------ | ------------- | | 应用 | 计算、求解、代入检验、按算法执行一遍 | | 分析 | 推导、化归、诊断错误解法 | | 评价 | 检验证明的严密性、评估数值方法的稳定性 | | 创造 | 证明新命题、设计算法、建模、把方法推广到新对象 | 同一知识点在六个层级各长什么样(以「等差数列求和」为例;这是判定标尺的示意,不宜原样搬进教材当正式题目——至少换数据、换场景): | 层级 | 题目示例 | | ------ | --------- | | 记忆 | 写出等差数列前 n 项和公式。 | | 理解 | 解释为什么求和公式里有 (首项 + 末项):它对应哪个配对操作? | | 应用 | 求 3, 7, 11, …, 399 的和。 | | 分析 | 某同学计算 3+7+11+…+399 时,先求项数 n = (399−3)/4 = 99,再代入求和公式得 S = 99×(3+399)/2 = 19899。找出错误所在并改正。 | | 评价 | 比较「配对法」和「倒序相加法」两种推导,哪种更容易推广到等比数列?说明理由。 | | 创造 | 构造一个现实场景问题,其解需要用到等差数列求和,并给出完整解答。 | **章内 Bloom 分布(非硬规则,消费者:阶段 3 例题习题计划)**: - 示范例题:记忆~应用层——教一套新程序时先低后中,先让读者看懂一次完整执行; - 引导练习:主落应用层(半独立地练刚学的程序); - 独立习题:应用~分析为主; - 评价/创造:全书少量点缀即可(1–3 题,常放在末章或表现性任务中),不必每章都有——本学科的评价/创造题(检验证明的严密性、设计算法、建模)依赖的前置工具多,早章往往还不具备。 ## 4 章内段义与载体扩展 **四段标题文案**(可直接复制,N 为章号;不得改名、不得增删段、不得调换顺序): ```markdown ## N.1 概念讲解 ## N.2 示范例题 ## N.3 引导练习 ## N.4 独立习题 ``` **后三段的教学动作**(支撑程度、数量配额与纪律见 [../../../textbook-chapter/references/chapter-template.md](../../../textbook-chapter/references/chapter-template.md) 第 3 节,此处只定义「具体做什么」): - **N.2 示范例题**:完整解题过程(worked example),每步给一行理由——读者应能看懂「为什么这么做」而不只是「做了什么」;每题末尾加一句「回顾:这道题用到了<概念>的<哪个性质>」,把题拉回概念主线; - **N.3 引导练习**:与某道示范例题**同构但换数据或换场景**,练的是同一认知程序;提示 1 指出从哪入手,提示 2 给出中间关键变形; - **N.4 独立习题**:变式题(示范例题换条件)+ 组合题(跨概念综合)+ 少量开放题。 **必配图示类型**:抽象概念、几何直观、算法流程用 mermaid 代码块或内嵌 SVG,随正文直接产出,不依赖外部渲染工具。 **术语表结构扩展**:契约规定的两节(`## 术语` / `## 符号约定`,列定义见 [../handoff-contract.md](../handoff-contract.md) 第 3 节)**在本档案下第二节必须写满**——数学符号是 STEM 教材的半壁语言,读者查不到符号就读不下去。同一个量全书用同一符号(矩阵用大写 $A$、向量用粗体、标量用小写希腊字母),逐章由回报字段 `新增符号[]` 追加,全书据此对齐。 **文体附加条款**:[../../../textbook-chapter/references/writing-style.md](../../../textbook-chapter/references/writing-style.md) 第 13 节「数学公式规范」全节适用(定界符唯一约定、行内与行间的选择判据、公式编号体例、矩阵环境统一 `bmatrix`、多行推导用 `aligned`、公式内不写中文、中文与行内公式之间加空格)。题干、解答、提示与正文出自同一本书,公式语法两套会让读者以为换了本书。
-
-
handoff-contract.md 19.4 KB
# 阶段交接契约与状态机规范 本文档是 textbook-writer skill 组合中所有交接契约、落盘布局与状态机的**唯一权威定义**。四个 SKILL.md 一律引用本文件,不得各自重复定义或改动字段名。 学科差异不在本文件定义:题型集、验证手段、认知动词与章内段义四处随学科变化的内容,收拢在**学科档案**里,规格与索引见 [subject-profile-spec.md](subject-profile-spec.md)。本文件只负责把「用哪份档案」作为契约字段一路传下去。 ## 1. 契约写法约定 - 契约用 `{字段, 字段}` 写法,形如函数签名;**上游产出 = 下游输入,字段名逐字一致**,不得同义改写(如"章节树"不得写成"章节列表"); - 标注"已确认"的产出,必须经过作者 gate 确认后才可传递——未确认的版本传下去即违规; - 数组字段以 `[]` 结尾(如 `大概念[]`),单值字段不带。 ## 2. 五阶段交接契约 ### 阶段 1 → 阶段 2 `{学科, 学科档案, 读者认知起点, 教材深度, 篇幅规模}` - 学科:具体到分支(如"线性代数"而非"数学"); - **学科档案**:由学科判定出的档案 id(合法取值见 [subject-profile-spec.md](subject-profile-spec.md) 第 5 节索引表),阶段 1 判定一次、全流程沿用,不在后续阶段重判;匹配不到时按该文档第 7 节处理; - 读者认知起点:零基础 / 有先修(注明先修什么); - 教材深度:入门 / 进阶; - 篇幅规模:章数区间(如 8–12 章)。 ### 阶段 2 → 阶段 3(已确认) `{大概念[], 持久理解[], 核心问题[], 迁移目标[], 学习目标[]}` - 学习目标每条带 Bloom 层级标注(格式:目标句 +(Bloom:应用)); - 五项合称 **UbD 五件套**,其中 `{大概念[], 持久理解[], 核心问题[]}` 三项子集在阶段 4 逐章下传。 ### 阶段 3 → 阶段 4(已确认) `{章节树[], 例题习题计划[], 表现性任务[], 梯度报告}` - 章节树每项:`{章号, 章标题, 一句话定位, 承载的持久理解编号[], 承载的学习目标编号[]}`;编号前缀与"编号不重排"纪律见 [../../textbook-outline/references/ubd-framework.md](../../textbook-outline/references/ubd-framework.md) 第 2 节编号约定(持久理解 `U`、学习目标 `O`)。**两组编号都是双向对齐的锚**:持久理解定这一章讲什么,学习目标定这一章的读者读完能做什么——后者此前没有落章机制,学习目标写在设计文档里、学生从头到尾看不到,等于没有对读者兑现; - 例题习题计划每项:`{章号, 示范例题[], 引导练习[], 独立习题[]}`,每题条目 `{主题, Bloom层级}`; - 表现性任务每项注明对应的迁移目标,并附评价标准表(六要素与 rubric 写法见 [../../textbook-outline/references/performance-task-rubric.md](../../textbook-outline/references/performance-task-rubric.md)); - 梯度报告:层级×章节矩阵 + 告警处理结果。 ### 主 skill → textbook-chapter(逐章调用) `{章号, 章标题, 该章大纲切片, UbD五件套, 术语表, 前章小结, 学科档案, 答案排版}` - 该章大纲切片 = 章节树中该章条目 + 该章例题习题计划 + **该章承载的学习目标原文**(按章节树条目的 `承载的学习目标编号[]` 从「## 二」逐条取出原文,含 Bloom 层级标注一并带上,供章 skill 判断该写到什么认知高度)。**只传该章那几条,不传全书清单**——上下文隔离对学习目标同样成立,而章 skill 需要原文才能改写成学生版,逼它回头查 `00-教材设计.md` 等于放开了读全书设计文档的口子; - UbD五件套 = `{大概念[], 持久理解[], 核心问题[]}`; - 术语表 = 术语表.md 当前全文; - 前章小结 = 前一章文件的「## 本章小结」全节内容;第 1 章传空; - 学科档案 = 阶段 1 判定的档案 id(原样透传,不重判)——章内段义与文体附加条款取自该档案第 4 节; - **答案排版** = `.progress.json` 的 `answer_layout` 原样透传(`separate` / `inline`)——决定本章独立习题的答案留在章内还是回报给主 skill 另行落盘,规则见第 3.1 节。 **上下文隔离口径**:学科档案与答案排版都是枚举值,不是新增的跨章载体——跨章一致性仍只靠术语表、前章小结、UbD 五件套三件(第 6 节)。两者决定的是本章怎么写、答案往哪放,不携带其他章的内容。 ### textbook-chapter → 主 skill `{章文件路径, 新增术语[], 新增符号[], Bloom标注回写[], 本章独立习题答案[]}` - 新增术语:本章首次引入、已按术语表格式写好的词条(主 skill 负责追加进术语表.md 的「## 术语」节); - **新增符号**每项:`{符号, 读法, 含义与约定, 首次出现章节}`——本章首次约定的符号(主 skill 负责追加进术语表.md 的「## 符号约定」节)。**动机**:`stem`、`economics` 档案都要求「同一个量全书用同一符号,符号选择记下来全书据此对齐」,但此前没有任何字段承载它,这条纪律实际上没有落点;各章在不同会话里独立写成,没有登记表,第 2 章用 $\mathbf{x}$ 表示列向量、第 7 章换成 $\vec{x}$,读者会以为是两个东西。本学科不用符号时(如 `humanities`)此数组为空; - Bloom标注回写每项:`{题目编号, 类型, Bloom层级}`(类型 ∈ 示范例题/引导练习/独立习题)——供阶段 5 复核**实际**梯度; - **本章独立习题答案**每项:`{题目编号, 参考答案或解题路径, 验证状态, 验证过程}`(主 skill 负责追加进 `98-参考答案.md`,写法同术语表)——独立习题的答案不留在章文件里,落位规则与动机见第 3.1 节。示范例题与引导练习**不进此数组**,其解答留在章内。 ### textbook-chapter → textbook-exercises `{章上下文, 题目计划, 术语表, 学科档案}` - 章上下文 = `{章号, 章标题, 本章概念清单, 本章学习目标}`; - 题目计划 = 该章例题习题计划条目(`{主题, Bloom层级}` 列表 × 三类); - 学科档案 = 档案 id(原样透传)——题型集与每型的验证手段取自该档案第 2 节。 ### textbook-exercises → textbook-chapter `{题目[]}`,每题 `{编号, 类型, 题干, 解答或提示, Bloom层级, 验证状态}` - 验证状态 ∈ `✅ 已验证(<方式>)` / `⚠️ 需作者确认(<原因>)`,无第三种。 ## 3. 教材项目落盘布局 ```text <教材名>/ ├── 00-前言.md # 阶段 5 产出(主 skill 生成的读者向前页:写给谁 + 怎么用 + 目录,见 3.2) ├── 00-教材设计.md # 阶段 1–3 产出(textbook-outline 写入) ├── 01-<章标题>.md # 阶段 4 产出,逐章生成 ├── 02-<章标题>.md ├── 98-参考答案.md # 阶段 4 产出,逐章追加(主 skill 写入,见 3.1) ├── 99-表现性任务.md # 阶段 5 产出(主 skill 由 00「## 四」派生的学生可读版) ├── 术语表.md # 全程维护(主 skill 追加写入),固定两节:术语 / 符号约定 └── .progress.json # 主 skill 维护的状态文件 ``` **两个 `00-` 文件的分工**:`00-前言.md` 面向**读者**(这本书写给谁、怎么用、章节在哪),`00-教材设计.md` 面向**作者**(教学定位、UbD 五件套、章节树与梯度)。前者是后者的读者可读派生物,同 `99-表现性任务.md` 的口径——设计文档不交给读者读。 - 章文件命名:`NN-<章标题>.md`,NN 从 01 起两位数字(如 `03-矩阵乘法.md`); - `00-教材设计.md` 固定二级标题(重入与阶段 5 走查按标题定位;标题是**固定锚点,不随 gate 状态改名**——「(已确认)」表示该节内容必须经作者确认方可作为下游输入,重入时若对应 gate 未确认,须重新走确认流程后才可使用): - `## 一、教学定位` - `## 二、UbD 五件套(已确认)` - `## 三、章节树与梯度规划(已确认)` - `## 四、表现性任务` - `99-表现性任务.md`:阶段 5 由主 skill 从「## 四、表现性任务」**派生生成**的学生可读版——只含任务说明(GRASPS 情境叙述)与评价标准表,去掉迁移目标编号一类教学设计元信息。单一来源是「## 四」,两处出入以「## 四」为准;v0.2.0 及更早创建的存量项目重入时此文件不存在,阶段 5 补生成即可,不影响续写; - 术语表.md 固定两节,标题逐字固定(阶段 5 按标题定位,逐章追加也按标题找落点): - `## 术语`,表格列 `| 术语(中文) | 英文 | 定义/约定 | 首次出现章节 |`; - `## 符号约定`,表格列 `| 符号 | 读法 | 含义与约定 | 首次出现章节 |`——由回报字段 `新增符号[]` 逐章追加。**不使用形式符号的学科(如 `humanities`)该节保留标题、正文写一行「本书不使用形式符号」**,节不删:删了标题,阶段 5 就无法区分"这门学科没有符号"与"符号漏登记了"。「读法」列是给读者的($\langle x,y\rangle$ 读作"x 与 y 的内积")——符号表最常被翻开的时刻是读者遇见一个不知道怎么念的记号; - 两节的列定义任何档案都不得改动;本学科附加的结构(如 `humanities` 的引文台账、`economics` 的数据来源台账)见所用档案第 4 节,作为额外表附在两节之后。 ### 3.1 独立习题答案落位 **动机**:全书投入最大的产出是三类题及其验证,而这份投入只有在读者能"先自己做一遍"时才兑现。答案紧跟题干的排版会让独立习题一眼看到底,"独立"名存实亡——所以独立习题的答案单独落盘,读者做完再翻。 **搬走三件**(写进 `98-参考答案.md`):参考答案 / 解题路径 / 开放题的参考要点、**验证状态行**、**验证过程**(代码块或核验记录)。三件必须整体同行,拆开搬等于泄底——验证代码几乎必然含答案数值。 **留在章内四件**:题干、Bloom 标注、开放题的「开放题」标记、论述类题的**评价标准表**。评价标准表是任务说明不是答案(同 `99-表现性任务.md` 把 rubric 交给学生的口径),读者动笔前就该知道按什么标准写。 **不搬**:示范例题、引导练习的解答与验证全部留在章内——前者是 worked example 先行的教学内核,后者的提示阶梯必须紧邻题干才成立(折叠写法见 [../../textbook-chapter/references/chapter-template.md](../../textbook-chapter/references/chapter-template.md) 3.3 节)。 `98-参考答案.md` 结构(按章分节,题号与正文逐一对应): ```markdown # 参考答案 > 建议先独立完成习题再对照。示范例题与引导练习的完整解答在各章正文内。 ## 第 1 章 <章标题> #### 习题 1-1【Bloom:应用】 **参考答案**:…… **验证**:✅ 已验证(<方式>) <验证过程代码块或核验记录> ``` **适用范围**:仅当 textbook-chapter 被主 skill 调度、且 `.progress.json` 的 `answer_layout` 为 `separate` 时执行分离。独立触发 textbook-chapter(写单篇深度文章)或独立触发 textbook-exercises(只要题)时**不分离**——此时没有教材项目目录,答案搬无可搬,一律按内嵌格式输出。 ### 3.2 成书前页 `00-前言.md` **动机**:读者拿到的是一个目录和十几个 `.md` 文件。没有前页,他要自己猜:这本书是不是写给我的、该先读哪个文件、习题答案去哪找、这一堆符号有没有对照表。一本纸质教材靠封面、前言、目录解决这三件事,Markdown 教材里没人替它们操心——章正文写得再好,读者进不了门,投入就传不到人身上。 **生成时机**:阶段 5,由主 skill 生成。放在阶段 5 而非阶段 3 的理由:目录要带章文件的真实路径与真实章标题,写作中途章标题仍可能被修订,早写的目录会指向不存在的文件——**一个点不开的链接比没有目录更糟**。 **固定三节,标题逐字固定**(阶段 5 走查按标题定位): ```markdown # <教材名> ## 本书写给谁 <读者对象与认知起点、需要的先修、深度定位;再一句「读完这本书,你应该能……」> ## 怎么用这本书 <四段式怎么读、答案在哪、术语与符号去哪查、表现性任务是什么> ## 目录 - [第 1 章 <章标题>](01-<章标题>.md) — <一句话定位> - [第 2 章 <章标题>](02-<章标题>.md) — <一句话定位> 附:[参考答案](98-参考答案.md) · [表现性任务](99-表现性任务.md) · [术语与符号表](术语表.md) ``` **三节的单一来源**(前页只做改写,不新增任何教学设计;与来源冲突一律以来源为准): | 节 | 来源 | 改写要求 | | ---- | ------ | -------- | | 本书写给谁 | `00-教材设计.md`「## 一、教学定位」+「## 二」的迁移目标 | 第二人称、去掉"读者认知起点""教材深度"这类设计术语;不列 Bloom 层级、不列学习目标编号 | | 怎么用这本书 | 本文件第 3 节落盘布局 + 3.1 节答案落位 + 章模板的四段式与首尾件 | 讲怎么用,不讲流水线怎么运作。至少覆盖四件:每章开头有学习目标、结尾有自检清单(读者据此判断学会没有);示范例题要跟着算一遍,引导练习先自己想再逐层展开提示;独立习题做完再翻参考答案;不认识的词与记号查术语表。`answer_layout=inline` 的存量项目不写"答案在 98",改写为"答案紧跟在题目之后" | | 目录 | `00-教材设计.md`「## 三」的章节树(章号、章标题、一句话定位)+ 章文件实际路径 | 链接必须逐字对应磁盘上的真实文件名;**生成后逐条核对文件存在**,指不到的链接当场修掉 | **不列进目录**:`00-教材设计.md` 与 `.progress.json`。前者是作者向设计文档(同 `99-表现性任务.md` 的口径:设计文档不交给读者读),后者是状态文件。 **存量项目**:v0.4.x 及更早创建的项目重入时此文件不存在,阶段 5 补生成即可,不影响续写。 ## 4. `.progress.json` 状态机 只由主 skill textbook 读写;子 skill 一律不碰(独立使用子 skill 时不产生此文件)。 ### Schema(示例值) ```json { "textbook_name": "线性代数入门", "subject": "线性代数", "subject_profile": "stem", "answer_layout": "separate", "created_at": "2026-07-14", "updated_at": "2026-07-15", "current_stage": 4, "gates": { "stage2_ubd_confirmed": true, "stage3_outline_confirmed": true }, "chapters": { "total": 10, "done": [1, 2, 3], "next": 4 }, "stage5_passed": null } ``` ### 字段规则 - `current_stage` ∈ 1–5,语义为"当前待完成的阶段";一个阶段完成即推进到下一阶段并**立即写盘**; - `subject_profile` = 契约字段 `学科档案` 的落盘形态,阶段 1 判定后写入,**此后不改**(改档案等于换验证纪律与章内段式,已写的章会与后写的章不是一本书;作者确实要换,按换项目处理);逐章调用时从此处读出透传,不重新判定;**存量项目无此字段时按 `stem` 处理**(v0.3.x 及更早创建的项目都是 STEM 教材),并在续写行后补一句说明,不阻塞续写; - `answer_layout` ∈ `separate`(独立习题答案落 `98-参考答案.md`,见 3.1 节)/ `inline`(答案紧跟题干,v0.4.x 及更早的排版);**新项目一律初始化为 `separate`**,此后不改;**存量项目无此字段时按 `inline` 处理**并在续写行后补一句说明——已写的章不迁移,一本书两种答案排版比统一用旧排版更糟; - `chapters.next` = 最小未完成章号;`chapters.done` 为已完成章号数组; - `stage5_passed` ∈ null(阶段 5 未跑)/ true(自检全过或不通过项均已修复)/ false(自检已跑完,但存在作者决定不修的不通过项,交付摘要须列明遗留项); - **写盘时机纪律**:每完成一个阶段、每完成一章,立即更新写盘,绝不批量延迟——中断可能随时发生;每次写盘同时把 `updated_at` 刷新为当日日期。 ### 重入规则表(主 skill 启动时执行) | 读到的状态 | 动作 | | ----------- | ------ | | 无 `.progress.json` | 全新项目:问教材名 → 建目录 → 初始化状态文件 → 从阶段 1 开始 | | 有 `.progress.json` 但无 `subject_profile` | 存量项目:按 `stem` 处理,续写行后补一句「按 stem 学科档案续写」,然后按下表其余规则定位续点 | | 有 `.progress.json` 但无 `answer_layout` | 存量项目:按 `inline` 处理(答案紧跟题干,不生成 `98-参考答案.md`),续写行后补一句「按内嵌答案排版续写」;本行与上一行可同时命中(v0.3.x 及更早两个字段都没有),两句说明并列输出,然后按下表其余规则定位续点 | | `current_stage=1` | 重跑阶段 1(一至两轮提问——所用档案第 1 节有前置输入要求时多一轮索要材料,产出轻,直接重来;`00-教材设计.md` 已有「## 一」内容时向作者复述并确认沿用或更新) | | `current_stage=2` 且 `stage2_ubd_confirmed=false` | 从 `00-教材设计.md`「## 二」读出五件套重新呈现,等确认 | | `current_stage=3` 且 `stage3_outline_confirmed=false` | 重新呈现阶段 3 全部四项产出(章节树、例题习题计划、梯度报告、表现性任务),等确认 | | `current_stage=4` | 从 `chapters.next` 继续逐章写作(已完成章不重写) | | `current_stage=5` | 重跑阶段 5 自检 | gate 重入的补充规则:重新呈现由主 skill 执行;作者提出修改时,委托 textbook-outline 执行修改并重新走确认循环(gate 的修改-再确认始终由该子 skill 负责),确认后由主 skill 更新状态。 ## 5. 进度打印与 gate 停点格式 - 阶段级进度:`▶ 阶段 N/M:<名称>`——M 为**当前 skill 自身的阶段总数**(textbook 为 5,textbook-outline 为 3)。被调度时两级并存、各有归属:全局阶段行(N/5)由主 skill 在进入阶段时打印,子 skill 打印自己的内层阶段行(N/3),不冲突、不互替。 - 章级进度:`▶ 第 N/M 章:<章标题>` - gate 停点(必须显式说明在等什么):`⏸ 等待确认:<等什么>(回复"确认"<下一步>,或直接提出修改)`——`<下一步>` 由具体 gate 实例化(如"进入章节设计")。 gate 之后的规则:作者提出修改 → 改后**重新完整呈现**再等确认,循环直到明确确认;确认前绝不推进阶段。**明确确认**指明确表示通过且未附带任何修改要求的答复(如"确认/通过/OK");"确认,但把 X 改一下"这类混合答复按修改分支处理(修改优先于确认)。非 gate 阶段只打印进度行,不打断作者。 ## 6. 上下文隔离原则 - 单章写作**不得读入其他章正文**;跨章一致性只靠三个轻量载体传递:**术语表、前章小结、UbD 五件套**; - 例题生成只接收 `{章上下文, 题目计划, 术语表}`,不接收章正文草稿全文; - 这是长教材(10+ 章)不爆上下文的根本保证,任何"顺便把前几章也读进来看看"的行为都是违规。 -
subject-profile-spec.md 8.4 KB
# 学科档案规格(subject profile spec) 本文档定义**学科档案**这一构件:它必须回答哪些问题、写成什么结构、由谁消费、如何新增一份。契约字段与状态机的权威定义在 [handoff-contract.md](handoff-contract.md),本文档是它在「学科差异」这一维度上的展开。 ## 1 为什么要有档案层 这条流水线的绝大部分与学科无关:五阶段调度、双 gate、状态机、上下文隔离、UbD 五件套、章节树双向对齐、Bloom 六层骨架、表现性任务与评价标准、阶段 5 的全套走查项——换一个学科,这些一字不改。 真正随学科变化的只有四处:**题型集、验证手段、认知动词与层级示例、章内段义**。这四处曾以「STEM 假设」的形式弥散在四个文件里(例题题型表、Bloom 动词表、章节模板段标题、文体规范),后果有两个:加一个学科门类要同时改四处,而且两套规则改完各自漂移,没有任何机制拦得住。 档案层把这四处收拢成一个可插拔构件:**内核只写学科无关的规则,档案只写本学科的增量**。于是加一个学科 = 加一个档案文件 + 在第 5 节索引登记一行,内核零改动。 ## 2 不变内核(绝不写进档案) 以下内容属于内核,档案不得重复定义、不得覆盖: - 五阶段流程、双 gate 规则、`.progress.json` 状态机与重入规则([handoff-contract.md](handoff-contract.md)); - UbD 五件套的定义、质量标准与一致性检查([../../textbook-outline/references/ubd-framework.md](../../textbook-outline/references/ubd-framework.md)); - 章节树双向对齐、梯度报告三条检查规则、GRASPS 六要素与评价标准的写法; - 三类题的「支撑程度」定位(教 / 扶 / 放)及其与 Bloom 认知高度的正交关系; - Bloom 六层的判据、通用动词基线、判定原则(同题多问取最高、歧义就低不就高); - 四段式「教 → 扶 → 放」的脚手架递减逻辑、题目编号规则、各段输出契约字段名; - **验证状态二值化**:每题必有验证状态行,取值只有 `✅ 已验证(<方式>)` / `⚠️ 需作者确认(<原因>)`,无第三种。 最后一条是红线的落点,边界必须说清:档案定义的是「**用什么方式**验证」,不是「**是否需要**验证」。档案第 2 节里每个题型都必须填出验证手段,填不出验证手段的题型不能写进档案(`scripts/validate_skills.py` 会拒绝空的验证手段列)。任何学科都不存在「这类题不用验证」这个选项——学科可以换,纪律不换。 ## 3 档案的固定结构 每份档案是 `profiles/<id>.md`。`<id>` 用 kebab-case,与契约字段 `学科档案` 的取值、`.progress.json` 的 `subject_profile` **逐字一致**。固定四个小节,标题文案不得改动,每节恰有一个消费者: | 小节(标题固定) | 内容 | 唯一消费者 | | ---------------- | ------ | ---------- | | `## 1 适用范围与判定` | 哪些学科走这份档案,以及与相邻档案的分界线 | 阶段 1(选定档案) | | `## 2 题型集与验证方式` | 本学科的题型全集,每型的验证手段与降级路径 | textbook-exercises | | `## 3 认知动词、层级示例与章内分布` | Bloom 六层的本学科特有动词 + 一组同知识点六层示例 + 三类题的章内层级分布建议 | textbook-outline | | `## 4 章内段义与载体扩展` | 四段标题文案、后三段的教学动作、必配图示类型、术语表结构扩展、文体附加条款 | textbook-chapter | 第 2 节的表格表头固定为: ```markdown | 题型 | 示例 | 验证手段 | 无法验证时的降级 | ``` 表头固定是为了能机械校验——「验证手段」列一旦留空即校验失败,红线因此不靠自觉,靠结构。 **两个易混的名字必须分清**:档案第 4 节定义的是**章内段标题文案**(`## N.2 示范例题` 这一行怎么写);而契约里三类题的**类型名**(`类型 ∈ 示范例题/引导练习/独立习题`,见 [handoff-contract.md](handoff-contract.md) 第 2 节)属于内核,任何档案都不得改动——Bloom 标注回写、全书梯度统计、验证行清点全都按类型名对账,改一个字这些统计就全断。段标题可以随学科换说法,类型名不行。 ## 4 写档案的第一原则:增量,不是全量 档案是内核的**增量补丁**,不是内核的学科特化副本。三条具体约束: - **第 3 节不复制通用动词,也不重述梯度检查规则**。[../../textbook-outline/references/bloom-levels.md](../../textbook-outline/references/bloom-levels.md) 第 2 节的通用动词基线(列举、解释、比较、论证……)对所有学科有效,档案只补本学科特有的动作动词、一组同知识点的六层示例,以及本学科的**章内层级分布建议**。分布建议属于档案而非内核,是因为同一套「教 → 扶 → 放」脚手架在不同学科落到的认知高度不同(bloom-levels.md 第 7 节说明了理由);而全书梯度的三条检查规则、先低后高的排列纪律仍属内核,档案不得改写。 - **第 4 节不复制通用文体规范**。[../../textbook-chapter/references/writing-style.md](../../textbook-chapter/references/writing-style.md) 的单线结构、认知负荷控制、措辞禁忌、中文排版对所有学科有效,档案只写本学科附加的排版体例(如公式规范、引文体例)。 - **第 2 节的题型表是全量**(题型集本身就是学科专属),但三类题定位、验证流程纪律、编号与输出格式在 [../../textbook-exercises/references/exercise-design.md](../../textbook-exercises/references/exercise-design.md),档案不重述。 判断法:如果一段话换个学科照样成立,它属于内核,不该出现在档案里。 ## 5 档案索引 | id | 适用学科 | 档案 | | ---- | -------- | ------ | | `stem` | 数学、物理、化学、工程、计算机等有确定解与可复算答案的学科 | [stem.md](profiles/stem.md) | | `humanities` | 历史、哲学、文学、政治学、社会学、艺术史等答案取决于论证与立场、但事实性断言可核查的学科 | [humanities.md](profiles/humanities.md) | | `economics` | 经济学各分支与金融学等模型题可复算、数据题须核对来源、政策题须给论证要点的混合学科 | [economics.md](profiles/economics.md) | `学科档案` 字段的合法取值就是本表的 id 列。分界从同一个问题问起:**这门学科的典型习题,答案能不能由一条与解答不同的路径重新算一遍并比对结果?**基本都能走 `stem`,基本都不能走 `humanities`;一半能一半不能——模型题可复算、统计数据只能核来源——走 `economics`。站在边界上的学科(语言学习、法学、心理学、地理等)各档案第 1 节都写了判定口径,以那里为准。 ## 6 新增一份档案 1. 按第 3 节结构写 `profiles/<id>.md`,四节齐全,第 2 节每型都填出验证手段; 2. 在第 5 节索引表登记一行; 3. 跑 `python3 scripts/validate_skills.py`(校验四节齐全、验证手段非空、索引与文件一一对应); 4. 在 [../../../evals/evals.json](../../../evals/evals.json) 追加至少一个用例,断言锚定**形式性可判定项**(每题是否有验证状态行、题目数是否等于验证行数、开放题是否附评价要点),不要写「内容质量好不好」这类无法客观判定的断言; 5. 内核文件(本文档第 2 节所列)不需要任何改动——如果发现必须改内核才能容纳新学科,说明第 3 节的四个可变点划分不够,先讨论再动手,不要在内核里加学科分支。 ## 7 匹配不到档案时 阶段 1 判定学科后在第 5 节索引里找档案。找不到匹配项时,**不得静默套用**某份档案:向作者说明「本学科暂无专属档案,将按 `<最接近的 id>` 档案处理」,并指出已知差异(哪些题型在该档案里没有对应验证手段、章内段义是否需要调整),由作者决定继续还是改学科范围。作者继续则照该档案执行,`subject_profile` 记录实际使用的 id。 理由:档案决定了全书的验证纪律与章内段式,选错一次会歪一整本书;而作者是唯一有资格判断「这个近似可以接受」的人。
-
-
SKILL.md 14 KB
--- name: textbook description: 写一整本多章节教材或成体系的课程讲义(含习题)时用它:按 UbD 逆向设计调度五个阶段——教学定位 → UbD 预期结果(gate)→ 章节树(gate)→ 逐章写作 → 审核定稿;进度落盘 .progress.json,中断后可从断点续写。触发语如"写教材"、"写一本教材"、"编写课程讲义"、"系统教材"、"textbook"。只写单篇教程、只写一章(用 textbook-chapter)、只出习题(用 textbook-exercises)时不要用它。需与 textbook-outline、textbook-chapter、textbook-exercises 装在同一 skills 目录下。 slug: textbook displayName: 教材写作流水线 version: 0.6.2 summary: UbD 逆向设计驱动的多章节教材写作主流程——五阶段调度、阶段 2/3 双 gate 作者确认、.progress.json 中断可续。需与 textbook-outline、textbook-chapter、textbook-exercises 装在同一 skills 目录下。 --- # textbook 写教材的主 skill(orchestrator):驱动五阶段流程,管理 `.progress.json` 状态实现中断可续,在阶段间传递交接契约,最终交付一本有主线、有梯度、可评估的多章节 Markdown 教材。契约、落盘布局、状态机的权威定义见 [references/handoff-contract.md](references/handoff-contract.md)(下称"契约文档")。 学科差异(题型集、验证手段、认知动词、章内段义)不在本 skill 里分支,收拢在**学科档案**中:阶段 1 判定一次,落盘为 `.progress.json` 的 `subject_profile`,逐章原样透传。规格与索引见 [references/subject-profile-spec.md](references/subject-profile-spec.md)。 ## 何时不触发 - 单篇教程/图文教程(用 tutorial-writer) - 只写一章或一篇深度文章(用 textbook-chapter) - 只要例题/习题(用 textbook-exercises) - 只做大纲不写正文(直接用 textbook-outline) ## 工作流总览 | 阶段 | 名称 | 执行者 | 产出 | Gate? | | ------ | ------ | -------- | ------ | ------- | | 1 | 教学定位确认 | textbook-outline | 学科/读者起点/深度/篇幅 → 00-教材设计.md | 否(一轮提问) | | 2 | UbD 预期结果设计 | textbook-outline | UbD 五件套 | **是(核心 gate)** | | 3 | 评估与章节设计 | textbook-outline | 章节树+例题计划+梯度报告+表现性任务 | 是(次要 gate) | | 4 | 章节正文编写 | textbook-chapter(逐章) | NN-章.md × N + 术语表增量 | 否 | | 5 | 审核定稿 | 本 skill | 自检报告 + 00-前言.md + 99-表现性任务.md + 交付摘要 | 否 | gate 之外的阶段只打印一行进度(格式见契约文档第 5 节),不打断作者。 ## 启动与重入(每次触发的第一件事) 1. **确定教材项目目录**:用户指定则用之;未指定则询问一次(默认 `./<教材名>/`)。 2. **找 `.progress.json`**: - 不存在 → 全新项目:确认教材名 → 建目录 → 初始化 `.progress.json`(schema 见契约文档第 4 节,`current_stage=1`,gates 全 false,`answer_layout="separate"`,`subject_profile` 待阶段 1 判定后补写)→ 从阶段 1 开始; - 存在 → 按契约文档第 4 节**重入规则表**定位续点,打印续写行:阶段 4 用 `▶ 续写:<教材名>,从第 N 章继续`,其余阶段用 `▶ 续写:<教材名>,从阶段 N 继续`;同时读出 `subject_profile` 与 `answer_layout` 供后续透传,**字段缺失**时按存量语义兜底并在续写行后各补一句说明,不阻塞:`subject_profile` 缺失(v0.3.x 及更早)按 `stem` 处理、补「按 stem 学科档案续写」;`answer_layout` 缺失(v0.4.x 及更早)按 `inline` 处理、补「按内嵌答案排版续写」——已写的章不迁移答案,一本书两种排版比统一用旧排版更糟。特别地:`current_stage=2/3` 且对应 gate 未确认时,从 `00-教材设计.md` 读出已有产出(阶段 2 为五件套、阶段 3 为章节树/例题习题计划/梯度报告/表现性任务四项)**重新呈现并等确认**,不推倒重做;作者提出修改时委托 textbook-outline 执行修改与再确认循环。 3. **状态纪律**:`.progress.json` 只由本 skill 读写(子 skill 一律不碰);每完成一个阶段、每完成一章**立即更新写盘**,绝不批量延迟。 ## 阶段 1–3:委托 textbook-outline 打印 `▶ 阶段 1/5:教学定位确认`(阶段 2、3 进入时同格式)。 使用 Skill 工具调用 `textbook-outline`(传入 `{教材项目目录, 教材名}`);若 Skill 工具不可用或未注册,直接读取 [../textbook-outline/SKILL.md](../textbook-outline/SKILL.md) 并严格遵循其指令执行。 - 其内部两个 gate 就是本流程的 gate——**gate 由该子 skill 面向作者执行,本 skill 绝不越过未确认的 gate 推进状态**; - 阶段 1 完成后(子 skill 回报 `学科档案`):置 `subject_profile=<档案 id>`、`current_stage=2`,写盘。此后**不再改动该字段**——换档案等于换验证纪律与章内段式,已写的章会与后写的章不是一本书; - 阶段 2 确认后:置 `gates.stage2_ubd_confirmed=true`、`current_stage=3`,写盘; - 阶段 3 确认后:置 `gates.stage3_outline_confirmed=true`、`current_stage=4`、`chapters.total=章节树章数`、`chapters.next=1`,写盘。 ## 阶段 4:逐章循环 打印 `▶ 阶段 4/5:章节正文编写`。 对 章号 N 从 `chapters.next` 到 `chapters.total` 逐章执行(严格顺序,前章完成才写后章): 1. **提取该章大纲切片**:从 `00-教材设计.md` 的「## 三、章节树与梯度规划(已确认)」取该章的章节树条目 + 例题习题计划;再按该条目的 `承载的学习目标编号[]` 到「## 二」逐条取出**学习目标原文**(含 Bloom 标注)一并放进切片——**只取该章那几条**,不把全书目标清单塞进去; 2. **读跨章载体**:术语表.md 当前版 + 前一章文件的「## 本章小结」全节(N=1 时前章小结为空); 3. **组装输入契约调用 textbook-chapter**:`{章号, 章标题, 该章大纲切片, UbD五件套, 术语表, 前章小结, 学科档案, 答案排版}`(五件套从「## 二、UbD 五件套(已确认)」提取 `{大概念[], 持久理解[], 核心问题[]}`;学科档案取 `.progress.json` 的 `subject_profile`、答案排版取 `answer_layout`,均原样透传,不重新判定)。调用方式同上:Skill 工具优先,降级读 [../textbook-chapter/SKILL.md](../textbook-chapter/SKILL.md); 4. **收输出契约** `{章文件路径, 新增术语[], 新增符号[], Bloom标注回写[], 本章独立习题答案[]}`:新增术语追加进术语表.md 的「## 术语」节、**新增符号追加进「## 符号约定」节**(术语表.md 不存在则先建,两节标题都写上,即使某节暂时为空——节标题是逐章追加的落点,缺标题下一章就没处可追);追加符号前先比对已登记条目:**同一含义已用别的符号登记过**,说明本章与前章不一致,退回该章统一符号后再追加(这正是符号表要存在的理由);Bloom 标注回写记入 `00-教材设计.md` 该章例题习题计划条目旁的"实际"标注(与"计划"并排,供阶段 5 对比);**本章独立习题答案追加进 `98-参考答案.md`**(`answer_layout=separate` 时;文件不存在则先建,含首行说明"建议先独立完成习题再对照",每章一个 `## 第 N 章 <章标题>` 小节,结构见契约文档 3.1 节)——追加前先数一遍:条目数与章内独立习题数不等、或题号对不上,**当场退回该章重做**,不许带着缺口往下写; 5. **更新状态**:`chapters.done` 加入 N、`chapters.next=N+1`,写盘 `.progress.json`。 全部章完成后置 `current_stage=5`,写盘。任何一章中途中断,重入时从 `chapters.next` 无缝继续,已完成章不重写。 ## 阶段 5:审核定稿(自检清单,非 gate,必须全跑) 打印 `▶ 阶段 5/5:审核定稿`。逐项检查并输出报告,每项给出:通过/不通过 + 具体位置 + 修改建议。 1. **章节对齐走查**:逐章读「## 本章小结」的"与持久理解的呼应",对照 `00-教材设计.md` 的承载计划——每章至少承载一条持久理解,每条持久理解至少被一章实际承载; 2. **Bloom 梯度复核(看实际不看计划)**:用各章"实际"标注重算层级×章节矩阵,按 [../textbook-outline/references/bloom-levels.md](../textbook-outline/references/bloom-levels.md) 第 5 节三条规则复核,输出第 6 节格式的报告; 3. **术语与符号一致性**:对照术语表.md 抽查各章(每章至少查引言与小结两处)用词是否一致,发现不一致列出位置;**符号另查两件**——各章正文与题目里出现的符号是否都在「## 符号约定」节登记(漏登记的补登)、同一含义是否全书只用一个符号(一义两符的列出两处位置,由作者定统一用哪个)。学科不使用形式符号时,确认该节写着「本书不使用形式符号」而非空表; 4. **例题验证残留与答案落位对账**:搜索范围为全部章文件 **加 `98-参考答案.md`**,三件事一起查—— - **验证残留**:搜 `⚠️ 需作者确认` 汇总成清单呈现。带此标注是合规的(红线允许"明确标注不能验证"),但必须让作者全部看见; - **验证行清点**(`answer_layout=separate` 时分两处数,一把总数对不上账):章内「示范例题 + 引导练习」题数 = 章内验证行数;各章独立习题题数 = `98-参考答案.md` 对应章节下的验证行数,且题号逐一对得上。缺验证行、缺答案条目、题号错位的逐条列出——漏行不是"合规的未验证",而是违反契约第 2 节「验证状态无第三种」,须报为不通过项; - **落位泄底检查**:在各章 N.4 段内搜 `参考答案`、`解题路径`、`参考要点`,命中即是答案没搬干净,报为不通过项(`answer_layout=inline` 的存量项目跳过本条); 5. **循序渐进走查**:逐章检查引言是否衔接前章小结、是否使用了后文才定义的概念(前置知识跳跃); 6. **学习目标覆盖矩阵(三列对账)**:对照 `00-教材设计.md`「## 二」的学习目标清单,输出「学习目标 × 章」矩阵,每条目标查三件—— - **设计侧**:有章节树条目的 `承载的学习目标编号[]` 认领它吗?(无人认领 = 阶段 3 的对齐检查漏了) - **读者侧**:认领它的章,章首「本章学习目标」里真写出对应那条了吗?章末自检里有对应的复选项吗?(认领了没写 = 学生仍然看不到) - **检验侧**:至少有一道题检验它吗(题目主题与该目标的对象一致即算覆盖)? 三列任一为空的逐条列出,并给可操作建议("建议在第 N 章补 X 层级题目"/"第 N 章章首漏了这一条,补写")。**动机**:ubd-framework.md 2.5 节要求每条学习目标"能想象出一道题来检验它",设计时查了、交付时不查等于只查一半;上面第 2 项统计的是层级分布,看不出哪条目标没人管。加设计侧与读者侧两列的理由是同一条目标可以在三个环节各自掉队——设计文档里有、章节树没认领;认领了、章首没写;章首写了、没有题检验——只查最后一环,前两种漏法会一路漏到读者手上; 7. **表现性任务复核与落盘**:核对「## 四、表现性任务」——每条迁移目标至少被一个任务覆盖、每个任务附评价标准表(维度从持久理解或迁移目标推出,每格为可观察的表现描述);核对通过后从「## 四」派生生成 `99-表现性任务.md`(学生可读版:任务说明 + 评价标准表,去掉迁移目标编号一类设计元信息;写法见 [../textbook-outline/references/performance-task-rubric.md](../textbook-outline/references/performance-task-rubric.md))。**动机**:表现性任务是迁移目标在全书唯一的检验落点,留在设计文档里等于没交付。 8. **成书前页生成与走查**:生成 `00-前言.md`(固定三节「本书写给谁 / 怎么用这本书 / 目录」,各节来源与改写要求见契约文档 3.2 节),然后逐条核对目录里的**每个链接**指向的文件真实存在、章号与章标题与磁盘文件逐字一致——**指不到的链接当场修掉**,不作为"待作者处理"的不通过项放过(这一项是主 skill 自己能修的,报给作者没有意义)。**动机**:前面七项保的是内容质量,这一项保的是读者进得来——一本没有前言和目录的教材,读者要靠猜才知道从哪读起、答案在哪查。 报告完毕后:不通过项由**作者决定修不修**;作者要求修 → 定位到章,重新组装该章输入契约调用 textbook-chapter 修订(修订后相关项复查)。全部处理完写盘 `stage5_passed`:无遗留不通过项(全过或均已修复)置 `true`;作者决定不修的不通过项仍存在置 `false`,并在交付摘要中列明遗留项。 ## 交付 输出交付摘要:章数 / 三类题总数 / 已验证题数 / `⚠️ 需作者确认` 条数 / 梯度复核结论 / 学习目标覆盖率(已覆盖 ÷ 总数,零覆盖的逐条列出)/ 表现性任务数与迁移目标覆盖情况 / 未修复项清单(如有)。 交付物为教材项目完整目录(布局见契约文档第 3 节):`00-前言.md`、`00-教材设计.md`、`NN-<章标题>.md × N`、`98-参考答案.md`、`99-表现性任务.md`、`术语表.md`、`.progress.json`。摘要里向作者点明两句:**读者从 `00-前言.md` 进入**(前言 + 怎么用 + 带链接的目录),`00-教材设计.md` 是作者向设计文档、不必给读者;独立习题的答案与验证在 `98-参考答案.md`,章内只留题干,读者可先做后对(`answer_layout=inline` 的存量项目不提后一句)。 **边界说明**(须向作者说明):定稿指文字与结构层面完成;若正文含人工截图标注块,需作者按标注自行补图后才算可发布。
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.