@chengzhao-dev/dsh-quarto-book 0.5.0 → 0.6.0

package/skills/writing-quarto/steps/02-structure.md

@@ -37,12 +37,12 @@
 
 读者在正文里依次确认来对了地方、完成可验证的动作、理解关键关系并确认获得的能力。各段服务一个认知结果，顺序由「读者先要知道什么才能看懂下一步」决定。
 
-**章际衔接（定结构检查项）**：第 N 章的引言、任务节与自测题只用第 1..N-1 章已建立的名字与概念；本章新术语在首次真正使用处就近落术语卡或行内括号；术语卡的升级判据见 `writing-quarto` 技能 `quarto/authoring.md`「Callout 升级判据」，写法见`steps/03-blocks.md`。某概念接不上前章已建立的名字时，把它下沉回首次使用它的章建立，不在本章临时补课。
+**章际衔接（定结构检查项）**：第 N 章的引言、任务节与自测题只用第 1..N-1 章已建立的名字与概念；本章新术语在首次真正使用处就近落术语卡或行内括号；术语卡的升级判据见 `writing-quarto` 技能 `quarto/authoring.md`「Callout 升级判据」，写法见 `steps/03-blocks.md`。某概念接不上前章已建立的名字时，把它下沉回首次使用它的章建立，不在本章临时补课。
 
-- **无标题引言**：第一个 `##` 之前，写成**连贯读者文**回答读者三问——从哪来（承接上一章已成立的结果）、这一章做什么（本章要解决的问题与读者将获得的能力，正面陈述；范围能并则并，不写否定式后章预告）、代码在哪（可选：若本章有主源文件，用**同段末句**自然语言点名并挂全章 blob 链接，不另起「代码写在…里」独立段）。第一句写出谁在什么情况下做本章这件事，类章同时写出类名；类型怎么实现放到后面的句子。不另开背景节。**形态硬限（用户决定）**：首选**恰好 1 个自然段**（通常 2–4 句）；必要时允许 **1 个自然段 + 1 个列表**（列表前引导句写在同一段末，或段落后紧跟列表；列表不算第二散文段）；**禁止**出现两个散文自然段并立，更禁止 ≥3 段、单句孤儿段、结尾导航段。列表仅用于并列范围/对象，任务细节下沉正文 `##`，不用顿号串交付物冒充散文。**摘录免责句永不写进读者正文**：「本章摘录源码服务于讲解」「片段不保证与源文件逐字一致」「不等于文件内顺序」类作者旁白一律删除（旧「示例位置句开口子」已废止），同源保证交给 `verifying-content.py`；摘录免责只保留在 技能的权威文件与检查脚本里。不放 Callout，不写后续章节内容，不用「后面的 X」式前向指称引入后续章节才建立的结构件（如「实现放在后面的编号目录里」）。引言容纳多个独立概念时**并段或改列表**，禁止拆成两个散文段；拆分判据见`steps/04-paragraphs.md`「拆分判据」。内容量硬限：token 预算见本文件「分层上限」；范围边界能并入承接段时不成列表。承接中引用其他章节一律用章节标题链接，不用「第 N 章」；本章回顾的下一章预告不写链接，直述预告一句（页面导航已有前进按钮），两者均见`steps/06-wording.md`。任务概览默认并入承接句，正文小节就是任务的展开；预览列表仅当任务没有对应正文小节时使用（示例章四项工作列表已按此删除）。原 front matter `description` 的定位信息并入引言承接句，信息只保留引言一处、不同义两存；章节 qmd 不写 `description`（字段出处见 basics.md）。着陆页 `index` 按 landing 规则组织，不硬套本契约。
-- **任务序列**：每节一个可验证结果。判定标准是任务结束时存在一个读者能自己复述的检查动作；只有「读完了解释」的内容并入相邻任务。概念 → 最小示例 → 操作 → 验证 → 边界，先让读者看到行为再解释规则。各章的任务节以该章标题里的对象为准，不把每一章都写成「目录、设计、构建、测试」四节。设计范围以这一章能在 `src/` 里核对的源文件收束。内容量硬限：任务级 `##` 通常不超过 4 个；`##` 与 `###` 开头的承接句数见本文件「分层上限」，写完直接进入代码、命令或列表；超出即为凑字数信号，禁令见`steps/04-paragraphs.md`「凑字数禁令」。有 `###` 子节时，二级标题（`##`）的引言须承接上文；恰好 2 个子节时一句点一个，3 个或 4 个时不再逐个点名，点名交给三级标题的句式见本文件「标题分层」，点名用读者已认识的词，不点后文才定义的类型名；一句之内禁止把两个子节对象配成「由 X 定位，并保存 Y」「分别交给」式的两组对应（对照见`examples/05-sentence-frame.md`「拉链句」）。交付清单或纯边界说明不单独设 `##`，并入引言或相邻工程总览节；同一头文件中连续的值类型优先按一个可验证结果归并到同一任务节。任务节内的讲述顺序按「类型 → 简单函数 → 更难的函数」排列，最难的组装放在最后，并满足先定义后调用：读者要跟着读懂的行内代码标识符，其行为必须已经出现过——上一章、上文，或同一小节里紧挨着的声明和一句行为——上一章已建立的名字视为已知；未定义名字的调用链、节首概览与编号步骤整段删除。`##` 导语只用白话，不点后文才定义的函数名。章内顺序的章内顺序的依据见 `SKILL.md`「九步」的定结构一条，本文件不复述。
+- **无标题引言**：第一个 `##` 之前，写成**连贯读者文**回答读者三问——从哪来（承接上一章已成立的结果）、这一章做什么（本章要解决的问题与读者将获得的能力，正面陈述；范围能并则并，不写否定式后章预告）、代码在哪（可选：若本章有主源文件，用**同段末句**自然语言点名并挂全章 blob 链接，不另起「代码写在…里」独立段）。第一句写出谁在什么情况下做本章这件事，类章同时写出类名；类型怎么实现放到后面的句子。不另开背景节。**形态硬限（用户决定）**：首选**恰好 1 个自然段**（通常 2–4 句）；必要时允许 **1 个自然段 + 1 个列表**（列表前引导句写在同一段末，或段落后紧跟列表；列表不算第二散文段）；**禁止**出现两个散文自然段并立，更禁止 ≥3 段、单句孤儿段、结尾导航段。列表仅用于并列范围/对象，任务细节下沉正文 `##`，不用顿号串交付物冒充散文。**摘录免责句永不写进读者正文**：「本章摘录源码服务于讲解」「片段不保证与源文件逐字一致」「不等于文件内顺序」类作者旁白一律删除（旧「示例位置句开口子」已废止），同源保证交给 `verifying-content.py`；摘录免责只保留在 技能的权威文件与检查脚本里。不放 Callout，不写后续章节内容，不用「后面的 X」式前向指称引入后续章节才建立的结构件（如「实现放在后面的编号目录里」）。引言容纳多个独立概念时**并段或改列表**，禁止拆成两个散文段；拆分判据见 `steps/04-paragraphs.md`「拆分判据」。内容量硬限：token 预算见本文件「分层上限」；范围边界能并入承接段时不成列表。承接中引用其他章节一律用章节标题链接，不用「第 N 章」；本章回顾的下一章预告不写链接，直述预告一句（页面导航已有前进按钮），两者均见 `steps/06-wording.md`。任务概览默认并入承接句，正文小节就是任务的展开；预览列表仅当任务没有对应正文小节时使用（示例章四项工作列表已按此删除）。原 front matter `description` 的定位信息并入引言承接句，信息只保留引言一处、不同义两存；章节 qmd 不写 `description`（字段出处见 basics.md）。着陆页 `index` 按 landing 规则组织，不硬套本契约。
+- **任务序列**：每节一个可验证结果。判定标准是任务结束时存在一个读者能自己复述的检查动作；只有「读完了解释」的内容并入相邻任务。概念 → 最小示例 → 操作 → 验证 → 边界，先让读者看到行为再解释规则。各章的任务节以该章标题里的对象为准，不把每一章都写成「目录、设计、构建、测试」四节。设计范围以这一章能在 `src/` 里核对的源文件收束。内容量硬限：任务级 `##` 通常不超过 4 个；`##` 与 `###` 开头的承接句数见本文件「分层上限」，写完直接进入代码、命令或列表；超出即为凑字数信号，禁令见 `steps/04-paragraphs.md`「凑字数禁令」。有 `###` 子节时，二级标题（`##`）的引言须承接上文；恰好 2 个子节时一句点一个，3 个或 4 个时不再逐个点名，点名交给三级标题的句式见本文件「标题分层」，点名用读者已认识的词，不点后文才定义的类型名；一句之内禁止把两个子节对象配成「由 X 定位，并保存 Y」「分别交给」式的两组对应（对照见 `examples/05-sentence-frame.md`「拉链句」）。交付清单或纯边界说明不单独设 `##`，并入引言或相邻工程总览节；同一头文件中连续的值类型优先按一个可验证结果归并到同一任务节。任务节内的讲述顺序按「类型 → 简单函数 → 更难的函数」排列，最难的组装放在最后，并满足先定义后调用：读者要跟着读懂的行内代码标识符，其行为必须已经出现过——上一章、上文，或同一小节里紧挨着的声明和一句行为——上一章已建立的名字视为已知；未定义名字的调用链、节首概览与编号步骤整段删除。`##` 导语只用白话，不点后文才定义的函数名。章内顺序的章内顺序的依据见 `SKILL.md`「九步」的定结构一条，本文件不复述。
 - **常见错误**：服务失败后回来的读者。每个症状一个 `###`，标题后第一句写触发条件和可观察现象。误用型条目一段成文写原因与正确做法；原因与做法各需一句完整交代时（如原因牵涉私有段的设计动机），用症状句导语加「出错的原因／正确的做法」引导词列表，列表可作为节导语的合法收尾，导语预算只约束症状句；排查型故障展开定位 → 修复 → 验证三步。形态分野与细则是 `writing-quarto` 技能 `quarto/terminal.md`「常见错误条目形态与三步诊断流」。入门章节只保留最可能遇到的 2-3 项，不是完整 FAQ。
-- **自测问题**：服务刚跑通主线、需要确认理解的读者。每章 0-7 道题，题目问本章已经写明的一件可观察结果（会怎样、是哪一个、从几开始），没有这种结果就不设题；只有本章写了原因、而且情景已经说全时，才用「为什么」。题面用本章已经用过的词说全，不用本章未定义的概念，不问「为什么不做成另一种」；题干是合上书的一问，只看本题题干、不看答案与上一题；题干代词的判法见`steps/05-sentences.md`「代词不能代替未写出的对象」，允许「什么」——它在要一个名字或一句文字，不是指上文没出现的东西；题面里每个细节都要改变答案，答案不受细节影响时不单点某一种情形。题面只描述一个自洽局面，每个事实都要能同时成立，禁止把互相矛盾的局面写成题干（同一句里先说轮到甲方、又说这一步的用户是 O，读者听到的是程序自相矛盾，不是一次非法调用）——「轮到谁」和「这一步的用户」若是同一个对象，只写一次。要考拒绝，用正文已经用过的那条规则问可观察结果（正例：「空状态面板开局，轮到甲方。没轮到的一方来操作时，状态面板会改变吗？」，答案首句「不会。操作的用户不是当前用户，`Place` 返回 `kRejected`，状态面板和轮次都保持原样。」）；不为了出题制造正文没走过的矛盾局面。一道题只问一件可观察结果，不把两个观察捆进同一题（如「状态面板是空的吗」与「轮到谁」并列），拆开或删去一个。固定导语「不要展开答案，试着自己把回答完整说出来，写完之后展开对照；说不出来的部分，回到对应小节对照正文。」；答案写在 `::: {.answer}` 围栏 div 内，由 `scripts/answering-disclosure.lua` 渲染为默认收起的原生 `<details>`；答案只使用本章已讲过的概念。题目同样必须能由本章正文回答：答案依据须是正文已写明的内容，正文没讲的概念不设题；若问题值得问，先在正文补上依据再设题。答案先答所问：首句直接回答题面，一到两句，不补题面之外的对比、延伸或重复题面（对照与归属由正文承载）。问答中的文件、路径与标识符指称统一用行内代码，不挂链接（`verifying-content.py` 对自测节链接记 WARN）；所属目录在答案前文已确立时，路径可省去重复的顶层前缀（如先写 `example/`，后文写 `include/state.h`）。
+- **自测问题**：服务刚跑通主线、需要确认理解的读者。每章 0-7 道题，题目问本章已经写明的一件可观察结果（会怎样、是哪一个、从几开始），没有这种结果就不设题；只有本章写了原因、而且情景已经说全时，才用「为什么」。题面用本章已经用过的词说全，不用本章未定义的概念，不问「为什么不做成另一种」；题干是合上书的一问，只看本题题干、不看答案与上一题；题干代词的判法见 `steps/05-sentences.md`「代词不能代替未写出的对象」，允许「什么」——它在要一个名字或一句文字，不是指上文没出现的东西；题面里每个细节都要改变答案，答案不受细节影响时不单点某一种情形。题面只描述一个自洽局面，每个事实都要能同时成立，禁止把互相矛盾的局面写成题干（同一句里先说轮到甲方、又说这一步的用户是 O，读者听到的是程序自相矛盾，不是一次非法调用）——「轮到谁」和「这一步的用户」若是同一个对象，只写一次。要考拒绝，用正文已经用过的那条规则问可观察结果（正例：「空状态面板开局，轮到甲方。没轮到的一方来操作时，状态面板会改变吗？」，答案首句「不会。操作的用户不是当前用户，`Place` 返回 `kRejected`，状态面板和轮次都保持原样。」）；不为了出题制造正文没走过的矛盾局面。一道题只问一件可观察结果，不把两个观察捆进同一题（如「状态面板是空的吗」与「轮到谁」并列），拆开或删去一个。固定导语「不要展开答案，试着自己把回答完整说出来，写完之后展开对照；说不出来的部分，回到对应小节对照正文。」；答案写在 `::: {.answer}` 围栏 div 内，由 `scripts/answering-disclosure.lua` 渲染为默认收起的原生 `<details>`；答案只使用本章已讲过的概念。题目同样必须能由本章正文回答：答案依据须是正文已写明的内容，正文没讲的概念不设题；若问题值得问，先在正文补上依据再设题。答案先答所问：首句直接回答题面，一到两句，不补题面之外的对比、延伸或重复题面（对照与归属由正文承载）。问答中的文件、路径与标识符指称统一用行内代码，不挂链接（`verifying-content.py` 对自测节链接记 WARN）；所属目录在答案前文已确立时，路径可省去重复的顶层前缀（如先写 `example/`，后文写 `include/state.h`）。
 - **本章回顾**：服务已经成功的读者。1-2 句段落（不是 bullet 列表）：「你已经能 <能力>」中的能力必须对应本章任务节交出的结果，可复用任务节关键词，不写正文没有的抽象总称（如「按输入、输出和终局」）；「下一章 <预告>」不写链接，直述预告一句（页面导航已有前进按钮），预告不引入下一章才建立的术语。回顾的每个说法都要能在正文找到出处，禁止空泛能力句或只写预告；正文任务节变化时同步改写回顾。
 
 ### 有 class 的章的任务节
@@ -58,10 +58,10 @@
 
 ### 术语与验证策略
 
-- 术语 callout 就近放置的写法见`steps/03-blocks.md`；一个同位短语就能说清的（如 CTest（CMake 自带的测试运行工具））可保留行内括号。面向新人的正文不堆砌入门前置名词（walking skeleton 这类术语直接删除）。
+- 术语 callout 就近放置的写法见 `steps/03-blocks.md`；一个同位短语就能说清的（如 CTest（CMake 自带的测试运行工具））可保留行内括号。面向新人的正文不堆砌入门前置名词（walking skeleton 这类术语直接删除）。
 - 页面写出的验证结论必须与证据强度匹配：命令能定位、版本能输出、程序能编译运行是不同层级，不能用弱观察替代强证明。
-- 涉及阶段目录结构的章节：先给目录树，再按树顺序逐项说明（链接格式见`quarto/render.md`）。
-- 全书统一术语与替换规则见`steps/06-wording.md`。
+- 涉及阶段目录结构的章节：先给目录树，再按树顺序逐项说明（链接格式见 `quarto/render.md`）。
+- 全书统一术语与替换规则见 `steps/06-wording.md`。
 
 ### 一章一个关键
 
@@ -86,10 +86,10 @@
 - 标题只用读者此刻已认识的词或字面自明的词，不使用正文之后才解释的术语。
 - 任务级 `##` 承担一个概念组或一项可独立交付的任务：单个类型、单个枚举或单个函数的小节不独占任务级 `##`，与相邻概念并成一组再按 `###` 分步（示例章反例：`定义坐标范围`、`保存格子状态` 曾各自独立成 `##`，粒度低于任务级；现行二级标题只记在本文件的对照里）。
 - 任务级 `##` 只保留读者能单独做完的一件事。只负责解释下一块代码、命令或图的，降为 `###`；短到没有独立观察步骤的，连 `###` 也不留，并进相邻正文。固定收尾「常见错误」「自测问题」「本章回顾」不合并、不降级，常见错误下面的症状继续用 `###`。
-- 一个任务级 `##` 下设 `###` 时至少两个：依据阮一峰[《中文技术文档写作风格指南》](https://github.com/ruanyf/document-style-guide)的标题原则，二级标题是文章的主要部分，三级标题是它下面的步骤，同级标题避免只出现一个；只有 `###` 时删去其标题归回 `##` 正文，或补出真正独立的同级小节。
+- 一个任务级 `##` 下设 `###` 时至少两个：依据阮一峰 [《中文技术文档写作风格指南》](https://github.com/ruanyf/document-style-guide) 的标题原则，二级标题是文章的主要部分，三级标题是它下面的步骤，同级标题避免只出现一个；只有 `###` 时删去其标题归回 `##` 正文，或补出真正独立的同级小节。
 - `##` 导语的句数与 token 上限见本文件「分层上限」，只写这一节交出的结果，不放代码围栏；恰好 2 个 `###` 时一句点一个，3 到 7 个时不再逐个点名，点名交给三级标题（与「个数见本文件」收尾，取代旧「按顺序点名各子节对象」的概览句式）。连续值类型的任务节归并见本文件「任务序列」；一个三级标题可以只讲一个枚举、一个结构体或一个函数。紧挨着的两个值类型可以放在同一个三级标题里，各成一个短模块，示例章「操作与成败」是正例。
 - 标题与内容匹配：标题动词承诺的动作必须是本节正文实际让读者完成的动作——正文只要求观察的行为用「观察、查看、核对」类动词，不用「走完、完成」类只在真实操作节成立的动词；任务级标题不与页面 title 共用核心动词（如页面 title 用「明确」后，任务节不再以「明确」开头），页面 title 已承诺的动作由正文兑现，标题换用更具体的动词；二级标题的宾语要涵盖其下三级标题的宾语，读者从标题序列能看出各节分工，不写比正文更宽或更窄的承诺。改写对照见本文件「反例与改写」。
-- 层级结构遵循阮一峰[《中文技术文档写作风格指南》](https://github.com/ruanyf/document-style-guide)标题章：不跳级（一级标题下不直接出现三级标题）、避免孤立编号（同级标题只有一个时省略）、下级标题不重复上级标题的名字。
+- 层级结构遵循阮一峰 [《中文技术文档写作风格指南》](https://github.com/ruanyf/document-style-guide) 标题章：不跳级（一级标题下不直接出现三级标题）、避免孤立编号（同级标题只有一个时省略）、下级标题不重复上级标题的名字。
 - 标题与导语不写拗口动宾，不用实现细节当主叙事：「得出胜负与平局」这类把两个结果硬拼成一个动宾的标题改写成交付对象（如「终局判定」）；「三连算法」是实现细节，可一句带过，不作章节 title 或 `##` 标题的主叙事（示例章反例：原 `## 得出胜负与平局` 已更名为「终局判定」，正文改说「操作后判定流程是否结束」）。
 
 ### 标题字数
@@ -115,7 +115,7 @@
 - title 留下读者在侧栏里要找的对象：概念、数据、结果用名词；只有这一页的交付就是读者要执行的一个动作时，才用「动词 + 一个宾语」。修饰性定语留给正文，否则「示例项目」「工程」等限定在 title 与二三级标题里连续重复（用户决定：各章 title 收尾为对象名，如流程规则、工程目录、数据存储、一次操作、构建与运行、操作策略、局面快照）。
 - title 不用「并」串联两个动作、不用把字句；两个动作各有任务节承载时择主撰写对象，动作细节留给导语和任务节。
 - 标题与导航不使用行内代码（`CMakeLists.txt` 这类名字不进标题；标题写「构建规则」「一键脚本」等表达）。
-- 标题只用读者此刻已认识的词或字面自明的词，不使用正文之后才解释的术语（统称禁用清单见`steps/06-wording.md`）。
+- 标题只用读者此刻已认识的词或字面自明的词，不使用正文之后才解释的术语（统称禁用清单见 `steps/06-wording.md`）。
 - 二级、三级标题用两组词：要么「限定语 + 对象」（数据项坐标、操作后的结果），要么「动词 + 具体宾语」（检查是否三连、放入一枚元素）；同一个二级标题下的三级标题只用其中一种，数字见「标题字数」。指示（这一步、这次）、过程动词（记下、收进、用到）、方式（用数组、先…再…）、把字句与数量词（三种、四个、九个）不进标题，下放到导语或正文。组词是否带限定语由改标题时逐条对照，不新增正则。导语仍按现规则：恰好两个三级时一句点一个，三个或四个时不逐个点名。
 - 三级标题可以保留本章对象的完整名称（如「数据项坐标」），不拆成「行与列」「空格与标记」。
 - 固定收尾节名固定复用，见本文件。
@@ -175,14 +175,14 @@
 | 普通代码块（围栏内内容行） | 20 行 |
 | `{mermaid}` 图表块 | 40 行 |
 | `{python}` 可执行单元（坐标图等） | 30 行 |
-| 单个正文段落（代码块、表格、列表与标题之外的连续文本段） | 70–220 token；下限拦过短段（70 token ≈ 45 汉字当量），上限保持上限，写作舒适带 90–180。豁免下限：章引言段、`##`/`###` 节导语、紧邻代码/列表/表/图/盒子的单句块前导语、本章回顾、自测固定导语、Callout 盒子内段落；豁免类仍受 220 上限约束。低于下限的补法见`steps/05-sentences.md`「导语衔接」 |
+| 单个正文段落（代码块、表格、列表与标题之外的连续文本段） | 70–220 token；下限拦过短段（70 token ≈ 45 汉字当量），上限保持上限，写作舒适带 90–180。豁免下限：章引言段、`##`/`###` 节导语、紧邻代码/列表/表/图/盒子的单句块前导语、本章回顾、自测固定导语、Callout 盒子内段落；豁免类仍受 220 上限约束。低于下限的补法见 `steps/05-sentences.md`「导语衔接」 |
 | `##` 节导语（标题后、首个代码块/列表/表格/引用/盒子前） | 120 token 且 ≤2 句，不放代码围栏；设 `###` 的任务级 `##` 导语不另设下限，导语点名的句式见本文件「标题分层」 |
 | `###` 节导语（同口径，到首个盒子/代码块/列表前） | 80 token 且 ≤1 句 |
 | 单个 `>` 引用块（连续引用行合并计） | 80 token |
-| 代码片段内注释 | 写法与限额见`steps/03-blocks.md`「代码块 filename 标注」 |
+| 代码片段内注释 | 写法与限额见 `steps/03-blocks.md`「代码块 filename 标注」 |
 | 一章 Callout | 不设下限；超过 8 个失败。写作时常例是 1 到 3 个 |
 
-`{python}` 可执行单元应只含助手调用，绘图逻辑在共享助手库（见`quarto/coords.md`）；超出 30 行说明把绘图逻辑内联进了正文，属于结构违规。
+`{python}` 可执行单元应只含助手调用，绘图逻辑在共享助手库（见 `quarto/coords.md`）；超出 30 行说明把绘图逻辑内联进了正文，属于结构违规。
 
 数字依据：没有规定章节字数的权威国标（GB/T 7713《科技报告编写规则》只管结构格式）；技术写作社区实践是单节对应 3-5 分钟阅读（约 1500-3000 字）、单个功能模块 800-1200 字，超限优先拆分。按 CJK×1.5 换算，整章 5000 token 约合 3300 汉字的正文当量，是「一节一件事、一章四节左右」的自然边界。
 
@@ -191,20 +191,20 @@
 - `verifying-content.py` 第 3 查按上表逐文件、逐节、逐代码块、逐正文段落核对，超限即整体失败；限额调整只改该脚本的常量与本表，两处必须同步。
 - 根目录 `index.qmd` 与 `content/<game>/index.qmd`（YAML 含 `body-classes: index-page`）是着陆页：短引言与卡片网格不是章节引言，只核对整章总量与代码块限额；着陆页不套用标题与骨架限制，见本文件「六段块序列」。
 - 任务级 `##` 数量、固定收尾不计入、`###` 的使用条件与首章「常见错误」豁免的结构判断，见本文件「六段块序列」；数量口径以上表为准。
-- 结构性规则（引言构成、`###` 数量）同时受`steps/02-structure.md`「六段块序列」约束；本表提供量化兜底。
-- 接近上限不是目标：预算是上限，内容仍按凑字数禁令与密度规则精简（见`steps/04-paragraphs.md`「凑字数禁令」）。
+- 结构性规则（引言构成、`###` 数量）同时受 `steps/02-structure.md`「六段块序列」约束；本表提供量化兜底。
+- 接近上限不是目标：预算是上限，内容仍按凑字数禁令与密度规则精简（见 `steps/04-paragraphs.md`「凑字数禁令」）。
 
 ### 页面宽度与垂直节奏
 
 页面“紧凑”通常有两个来源：正文列太窄导致无谓换行，或块之间缺少承接留白。优先小幅放宽 Quarto HTML grid 的 `body-width`，再用共享 CSS 调整正文块间距；不要只放大字体，也不要用局部规则给每个块重复加 margin。正文列仍需保留 `max-width: 100%`，代码和宽表在窄屏上继续滚动或换行。
 
-当前仓库采用 840px 的正文内容列和约 1.55rem 的普通块间距，代码块连续出现时保留更大的间隔。代码块与正文同宽：不再对代码做二次限宽（`--code-max-width` 已删除），宽屏两侧留白属主流文档站（VitePress 1440 壳/688 正文）正常行为，不按显示器拉满正文。872px/840px 的取值依据（100 列代码不折行）见`../designing-theme/knowledge/reading-surface.md`。评估重点是：每个任务是否有清晰的动作与结果、连续盒子之间是否有解释段、移动端是否出现横向溢出。这里不设置依赖浏览器截图的硬阈值，最终以 `quarto render` 后的 HTML 结构和实际阅读抽查为准。
+当前仓库采用 840px 的正文内容列和约 1.55rem 的普通块间距，代码块连续出现时保留更大的间隔。代码块与正文同宽：不再对代码做二次限宽（`--code-max-width` 已删除），宽屏两侧留白属主流文档站（VitePress 1440 壳/688 正文）正常行为，不按显示器拉满正文。872px/840px 的取值依据（100 列代码不折行）见 `../designing-theme/knowledge/reading-surface.md`。评估重点是：每个任务是否有清晰的动作与结果、连续盒子之间是否有解释段、移动端是否出现横向溢出。这里不设置依赖浏览器截图的硬阈值，最终以 `quarto render` 后的 HTML 结构和实际阅读抽查为准。
 
 Quarto 通过 HTML grid 控制正文、侧栏和目录列，代码块的 `filename`、换行和复制行为由代码块配置及 CSS 共同控制；页面宽度与代码标题过长是两个独立问题。
 
 ### 一图一事与同主题相邻
 
-图是读者视觉负荷最高的盒子：一张图同时表达两条关系时，读者要同时在脑子里维护两个对照，图前正文与图后结论也各要写两遍才能闭环。因此一张图只核对一条已讲清的关系，需要两条就拆图或拆节；一图一事与主题错位拆 `###` 的边界见`steps/03-blocks.md`「代码与图的桥接」。代码与图相邻的前提是同一对象：图讲 B 而前后代码讲 A、C 时，读者被迫在三个对象间跳转，这正是「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」式堆叠的成因。主题错位时先用一句正文收束本对象，再另起 `###`。图中的每个框和箭头都应能在图前正文找到出处；图引入正文没有的概念时，读者只能靠猜。写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」。
+图是读者视觉负荷最高的盒子：一张图同时表达两条关系时，读者要同时在脑子里维护两个对照，图前正文与图后结论也各要写两遍才能闭环。因此一张图只核对一条已讲清的关系，需要两条就拆图或拆节；一图一事与主题错位拆 `###` 的边界见 `steps/03-blocks.md`「代码与图的桥接」。代码与图相邻的前提是同一对象：图讲 B 而前后代码讲 A、C 时，读者被迫在三个对象间跳转，这正是「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」式堆叠的成因。主题错位时先用一句正文收束本对象，再另起 `###`。图中的每个框和箭头都应能在图前正文找到出处；图引入正文没有的概念时，读者只能靠猜。写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」。
 
 ### 主线必须先闭合
 
@@ -212,7 +212,7 @@ Quarto 通过 HTML grid 控制正文、侧栏和目录列，代码块的 `filena
 
 主线闭合要求一节只有一个要闭合的目标：标题、第一句、动作和验收输出指向同一个结果，中途出现第二个独立动作时，读者就无法判断当前在等哪一个。任务粒度本身的判定标准属于页面结构，见本文件。
 
-标题对齐同时排除离题辩白：操作小节里与标题无关的工程取舍长论（「为何不跳过某步 / 幂等 / 配置漂移」类）让读者在动作中途读辩白，主线被打断；执行规则见`steps/03-blocks.md`「小节标题与正文对齐」。
+标题对齐同时排除离题辩白：操作小节里与标题无关的工程取舍长论（「为何不跳过某步 / 幂等 / 配置漂移」类）让读者在动作中途读辩白，主线被打断；执行规则见 `steps/03-blocks.md`「小节标题与正文对齐」。
 
 当多个 `###` 共享同一阶段、环境或产物时，可以用父级 `##` 统摄，但父级只负责分组，不能把两个各自可验收的任务压成一个模糊标题。父标题要写清当前阶段或范围，子标题继续使用可执行、可观察的任务名。
 
@@ -220,7 +220,7 @@ Quarto 通过 HTML grid 控制正文、侧栏和目录列，代码块的 `filena
 
 长段的问题不在于占据多少行，而在于它要求读者同时记住多个职责。主线动作、成功判据和可跳过说明压在同一段时，只读必要内容的读者必须重新寻找下一步，逐字阅读的读者又无法判断哪些细节可以跳过。按职责拆成短段，能让首次执行和回看细节两条路径自然分开。
 
-普通 Callout 不能成为细节垃圾桶。把可以跳过的内容集中进提示框后，读者仍要判断这段是否影响当前任务，而且视觉上独立的盒子容易像必经步骤。只有删除后不影响首次成功和验收的信息才适合下沉，并且一个最小模块最多一个 Callout，一章的个数见本文件；术语解释型 Callout 是就近放置的例外，写法与限制见`steps/03-blocks.md`。稳定界面判据与它的解释同框时，另见下节约束。
+普通 Callout 不能成为细节垃圾桶。把可以跳过的内容集中进提示框后，读者仍要判断这段是否影响当前任务，而且视觉上独立的盒子容易像必经步骤。只有删除后不影响首次成功和验收的信息才适合下沉，并且一个最小模块最多一个 Callout，一章的个数见本文件；术语解释型 Callout 是就近放置的例外，写法与限制见 `steps/03-blocks.md`。稳定界面判据与它的解释同框时，另见下节约束。
 
 合并与拆分都按信息职责判断，不按固定字数。同一状态内部的账号创建和正常现象可以合并。成功判据与后续执行范围进入下一个状态时另起一段，即使它们仍属于同一次首次启动流程。
 

package/skills/writing-quarto/steps/03-blocks.md

@@ -7,32 +7,32 @@
 
 ### 内容块前后的闭环
 
-一个段落只推进一个对象；小节内出现代码块、列表或表格时，模块内部的次序见下文「三级标题最小模块」，本段只规定导语怎么写：块前用一句完整导语交代为什么看它（对象、谁调用、做什么）——对象写成读者要在块内观察的代码标识符（常量、类型、函数名），只报出处、不点名块内对象的「X 都定义在 state.h 里：」不算导语，读者对不上句中概念与围栏里的名字（对照见`examples/03-excerpt-lead.md`「摘录导语只报出处」）；点名也不得退化为「`X` 做A、`Y` 做B」式的逐条释义，对象要组织进为什么看它的句子里（对照见`examples/03-excerpt-lead.md`「逐条释义代替动机」）；块后只在有注释未覆盖的新信息时写一句；引言写判断依据，不写「如下：」式的空引导（GitHub 风格指南同款要求：解释文字放在代码块前面，而不是塞进代码注释）。导语预告的对象本体必须出现在导语句里，不得隔着代码块在块后才给出；算式不是例外，换算句式见`steps/07-layout.md`「列表选择」。
+一个段落只推进一个对象；小节内出现代码块、列表或表格时，模块内部的次序见下文「三级标题最小模块」，本段只规定导语怎么写：块前用一句完整导语交代为什么看它（对象、谁调用、做什么）——对象写成读者要在块内观察的代码标识符（常量、类型、函数名），只报出处、不点名块内对象的「X 都定义在 state.h 里：」不算导语，读者对不上句中概念与围栏里的名字（对照见 `examples/03-excerpt-lead.md`「摘录导语只报出处」）；点名也不得退化为「`X` 做 A、`Y` 做 B」式的逐条释义，对象要组织进为什么看它的句子里（对照见 `examples/03-excerpt-lead.md`「逐条释义代替动机」）；块后只在有注释未覆盖的新信息时写一句；引言写判断依据，不写「如下：」式的空引导（GitHub 风格指南同款要求：解释文字放在代码块前面，而不是塞进代码注释）。导语预告的对象本体必须出现在导语句里，不得隔着代码块在块后才给出；算式不是例外，换算句式见 `steps/07-layout.md`「列表选择」。
 
-一个函数小节内部按「声明、一句行为、实现」排列，示例不出现在行为句之前；同一小节出现多个围栏时按阅读顺序排；先定义后调用与未定义名字调用链的处理见`steps/02-structure.md`「六段块序列」。编号步骤、节首概览或章引言用后文才定义的名字串起一条必须看懂的过程的，整段删除，不改写后留在原位；调用方的实现里第一次见到被调用函数、而该函数要到后面小节才讲的，调整顺序；点名后文章节的函数而那一章并不讲解它的，删掉也不补进那一章。允许：用读者已认识的词预告本节要做的事；同一小节内声明和一句行为紧挨代码；上一章已经讲过的名字。
+一个函数小节内部按「声明、一句行为、实现」排列，示例不出现在行为句之前；同一小节出现多个围栏时按阅读顺序排；先定义后调用与未定义名字调用链的处理见 `steps/02-structure.md`「六段块序列」。编号步骤、节首概览或章引言用后文才定义的名字串起一条必须看懂的过程的，整段删除，不改写后留在原位；调用方的实现里第一次见到被调用函数、而该函数要到后面小节才讲的，调整顺序；点名后文章节的函数而那一章并不讲解它的，删掉也不补进那一章。允许：用读者已认识的词预告本节要做的事；同一小节内声明和一句行为紧挨代码；上一章已经讲过的名字。
 
 讲函数体的小节三步固定：导语点名函数并写出头文件上的 `public:` 或 `private:`（如「`Board::HasLine` 声明在 `state.h` 的 `private:` 下」）；第一块围栏是头文件声明，访问说明符那一行留在围栏里；类成员的头文件摘录以源码里的 class 类名 { 或 struct 名 { 开头，接着保留该成员所属的 public:、private: 或 protected: 行，再摘成员，围栏以源码里的 }; 结束。省略的是其他成员，不是类头，也不写省略标记。自由函数、枚举和已经自带 struct 或 enum 的整段定义不另套 class。.cpp 围栏不插入 class 体或访问说明符。声明看不出的步骤才配下一块 `.cpp` 围栏，导语写「实现写在某个 `.cpp` 里」。只讲入口、不讲函数体的小节（如 `Board` 的读写入口）停在头文件声明，不配实现围栏；禁止在 `.cpp` 围栏里插入 `private:`，私有成员身份只由头文件围栏呈现。
 
-同一 `##`/`###` 内 ≥2 个代码围栏时，先看是否是紧邻常量与其直接使用行：常量紧接着被下一行使用时，可放在同一个围栏。类型定义和后一步使用它的函数是两步，即使函数用到该类型也分成两块——一个围栏只放正在讲的那一个声明或函数，不把整份头文件、整份类或整条调用链贴进同一个围栏；后一个函数的函数体里可以调用已经讲过的名字，但不把那些函数的实现再贴一遍。每块前一句导语；`{python}` / `{mermaid}` 图或独立验证盒子打断处保持拆块。旧口径「同一小节递进片段必须合并为一个围栏」收窄到此：只有常量紧接着被下一行使用时才放在同一围栏。改写对照见`examples/03-excerpt-lead.md`「递进片段合并」。
+同一 `##`/`###` 内 ≥2 个代码围栏时，先看是否是紧邻常量与其直接使用行：常量紧接着被下一行使用时，可放在同一个围栏。类型定义和后一步使用它的函数是两步，即使函数用到该类型也分成两块——一个围栏只放正在讲的那一个声明或函数，不把整份头文件、整份类或整条调用链贴进同一个围栏；后一个函数的函数体里可以调用已经讲过的名字，但不把那些函数的实现再贴一遍。每块前一句导语；`{python}` / `{mermaid}` 图或独立验证盒子打断处保持拆块。旧口径「同一小节递进片段必须合并为一个围栏」收窄到此：只有常量紧接着被下一行使用时才放在同一围栏。改写对照见 `examples/03-excerpt-lead.md`「递进片段合并」。
 
-每个围栏在最小模块里的位置见「三级标题最小模块」。仍然禁止块前半句，禁止收束段把列表再讲一遍。可合并的块前与块后并成块前一句；简洁边界仍适用（`steps/05-sentences.md`）。细则与对照见`steps/05-sentences.md`、`examples/03-excerpt-lead.md`「多代码块一句导语」。
+每个围栏在最小模块里的位置见「三级标题最小模块」。仍然禁止块前半句，禁止收束段把列表再讲一遍。可合并的块前与块后并成块前一句；简洁边界仍适用（`steps/05-sentences.md`）。细则与对照见 `steps/05-sentences.md`、`examples/03-excerpt-lead.md`「多代码块一句导语」。
 
-以代码块为中段，导语讲工程语境（这段代码为什么存在、为什么此刻看它）；若有块后句，只讲注释没覆盖的新工程关系。语法细节不逐行展开。导语与块后都禁止关键字释义当开场：不写「X 是 `inline constexpr` 常量」「用 `enum class` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除 01 设计章外工程 qmd 禁选型外链），改写对照见`examples/01-language-scope.md`「语言课旁白与工程旁白」。
+以代码块为中段，导语讲工程语境（这段代码为什么存在、为什么此刻看它）；若有块后句，只讲注释没覆盖的新工程关系。语法细节不逐行展开。导语与块后都禁止关键字释义当开场：不写「X 是 `inline constexpr` 常量」「用 `enum class` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除 01 设计章外工程 qmd 禁选型外链），改写对照见 `examples/01-language-scope.md`「语言课旁白与工程旁白」。
 
 块后四条硬禁令：
 
-- **禁止正文复述围栏内注释**：代码块内 `//` / `#` 注释已写明的意图、产物路径或字段含义，块后正文不得同义再讲一遍；块后只写注释没覆盖的新工程信息（谁调用、如何验证、与邻块或图的关系）。改写对照见`examples/03-block-after.md`「块后复述注释」。
-- **禁止单段夹杂多个并列对象**：一段一对象的通则见`steps/04-paragraphs.md`「段落规则」；块后的递进依赖链不算并列：先按上文递进合并判定并成一块、块后列表分项，不按本条拆段。多代码块小节里每段最多一句 + 一个配套块。改写对照见`examples/03-block-after.md`「单段混并列对象」与`examples/03-excerpt-lead.md`「递进片段合并」。
-- **禁止块后悬空指代围栏内的实体**：块后段落首次提及代码块引入的常量、类型或函数时点名标识符；先行词只出现在围栏里（不在任何句中）时，不得用「这三个常量」「它们」式省称开场。导语或前段已逐一点名后，后文才可用集合指称回指（与`steps/05-sentences.md`「一句不换对象」同界）；建立多个对象的关系时用一句写全谁约束谁、谁派生自谁（模板见`scripts/verifying-content.py`「禁用与替换」的契约链行）。改写对照见`examples/03-block-after.md`「块后悬空指代」。
-- **禁止块后正文逐条释义代替设计动机**：块后散文段落不是成员清单的重写，连续的「`标识符`＋动词短语」释义只回答「是什么」，要写出为什么这样设计、对调用方意味着什么，释义只在服务动机的句子里出现；公式的每一项是否拆成列表项，见`steps/07-layout.md`「列表选择」换算条。改写对照见`examples/03-excerpt-lead.md`「逐条释义代替动机」。
+- **禁止正文复述围栏内注释**：代码块内 `//` / `#` 注释已写明的意图、产物路径或字段含义，块后正文不得同义再讲一遍；块后只写注释没覆盖的新工程信息（谁调用、如何验证、与邻块或图的关系）。改写对照见 `examples/03-block-after.md`「块后复述注释」。
+- **禁止单段夹杂多个并列对象**：一段一对象的通则见 `steps/04-paragraphs.md`「段落规则」；块后的递进依赖链不算并列：先按上文递进合并判定并成一块、块后列表分项，不按本条拆段。多代码块小节里每段最多一句 + 一个配套块。改写对照见 `examples/03-block-after.md`「单段混并列对象」与 `examples/03-excerpt-lead.md`「递进片段合并」。
+- **禁止块后悬空指代围栏内的实体**：块后段落首次提及代码块引入的常量、类型或函数时点名标识符；先行词只出现在围栏里（不在任何句中）时，不得用「这三个常量」「它们」式省称开场。导语或前段已逐一点名后，后文才可用集合指称回指（与 `steps/05-sentences.md`「一句不换对象」同界）；建立多个对象的关系时用一句写全谁约束谁、谁派生自谁（模板见 `scripts/verifying-content.py`「禁用与替换」的契约链行）。改写对照见 `examples/03-block-after.md`「块后悬空指代」。
+- **禁止块后正文逐条释义代替设计动机**：块后散文段落不是成员清单的重写，连续的「`标识符`＋动词短语」释义只回答「是什么」，要写出为什么这样设计、对调用方意味着什么，释义只在服务动机的句子里出现；公式的每一项是否拆成列表项，见 `steps/07-layout.md`「列表选择」换算条。改写对照见 `examples/03-excerpt-lead.md`「逐条释义代替动机」。
 
-渐进披露不进正文：语法细节延后展开是 Agent 侧写作策略，禁止把策略写成对读者的话——「语法细节留到后续章节真正用到时再展开」「本章只需认清……」这类元叙述一律不出现在 `content/**`；正文直接陈述对象和结果（如「这段程序对外可见的结果只有两处：……」），需要延后的内容保持沉默即可。改写对照见`examples/06-wording-cases.md`，禁用词见`steps/06-wording.md`。
+渐进披露不进正文：语法细节延后展开是 Agent 侧写作策略，禁止把策略写成对读者的话——「语法细节留到后续章节真正用到时再展开」「本章只需认清……」这类元叙述一律不出现在 `content/**`；正文直接陈述对象和结果（如「这段程序对外可见的结果只有两处：……」），需要延后的内容保持沉默即可。改写对照见 `examples/06-wording-cases.md`，禁用词见 `steps/06-wording.md`。
 
-列表与表格同律：表格前用一句完整的话交代它回答什么问题，表格后补一行读者该取走的结论；列表通则见`steps/04-paragraphs.md`「段落规则」。命令、输出与正文三分见本文件「命令、输出与细节各司其职」。
+列表与表格同律：表格前用一句完整的话交代它回答什么问题，表格后补一行读者该取走的结论；列表通则见 `steps/04-paragraphs.md`「段落规则」。命令、输出与正文三分见本文件「命令、输出与细节各司其职」。
 
-多命令块：块后逐条讲解的格式见`steps/04-paragraphs.md`「段落规则」，引导词加粗与行内代码不叠加的边界见`steps/07-layout.md`。引言与收束按上段列表通则，不再按命令分段成多个段落。
+多命令块：块后逐条讲解的格式见 `steps/04-paragraphs.md`「段落规则」，引导词加粗与行内代码不叠加的边界见 `steps/07-layout.md`。引言与收束按上段列表通则，不再按命令分段成多个段落。
 
-代码块导语禁用「N 段命令定义」式元计数：直接点名这段规则定义的对象，不用「先…再…最后…」，不叫读者回数段落；改写对照见`examples/03-qmd-elements.md`「代码块导语元计数对照」。
+代码块导语禁用「N 段命令定义」式元计数：直接点名这段规则定义的对象，不用「先…再…最后…」，不叫读者回数段落；改写对照见 `examples/03-qmd-elements.md`「代码块导语元计数对照」。
 
 ### 代码块 filename 标注
 
@@ -55,11 +55,11 @@ int main() {
 - **filename 一律短显示名**：只写 `main.cpp`、`CMakeLists.txt`、`running-build.sh`、`example/` 这类短名；禁止把 `src/...` 或 `shared/...` 深层路径塞进标题栏。完整位置由章引言的 GitHub 链接和目录树提供；`verifying-content.py` 用本章内、代码块之前 basename 匹配的最近一条 blob 链接解析真实路径再做片段核对。
 - **filename 不写链接**：`filename="..."` 是纯文本短名，禁止塞 Markdown 链接；`resolve_fragment_source` 的解析只认正文句子里的链接，标题栏写链接既渲染不出可点样式，也会被 `verifying-content.py` 判失败。
 - **blob 链接嵌进导语句**：GitHub blob 链接写在同节导语的完整句子里（正例：「apps/CMakeLists.txt 用一行目标属性固定运行时库查找」，其中文件名是 GitHub 链接的锚文本），禁止整行仅为链接单独成行贴在代码围栏上方（可夹空行，`verifying-content.py` 判失败）。悬空的裸链接行既不像正文也不像说明，读者扫读时只剩一个锚点。
-- **摘录链接每章每条仓库路径至多一条**：章引言是全章链接位，首次点名源文件并挂链接（如「声明在头文件 `state.h`，实现在源文件 `state.cpp`」，这两个名字是该章仅有的源文件链接）；后文和各节导语改成行内代码，不再包 `[]()`，导语讲块里要看的标识符；同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（对照见`examples/03-excerpt-lead.md`「摘录链接密度」；`verifying-content.py` 对同章同 URL 重复判失败）。本条挂在写作步骤的定版式。
+- **摘录链接每章每条仓库路径至多一条**：章引言是全章链接位，首次点名源文件并挂链接（如「声明在头文件 `state.h`，实现在源文件 `state.cpp`」，这两个名字是该章仅有的源文件链接）；后文和各节导语改成行内代码，不再包 `[]()`，导语讲块里要看的标识符；同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（对照见 `examples/03-excerpt-lead.md`「摘录链接密度」；`verifying-content.py` 对同章同 URL 重复判失败）。本条挂在写作步骤的定版式。
 - 片段内注释硬限：每处实现注释（`//` 或 `#`）不超过 2 行、单行不超过 100 列（与源文件 `ColumnLimit: 100` 同一口径；正文散文的 40 字限不套到代码注释），只写这段代码做什么；CMake/Shell 等命令型片段每条命令保留一行意图注释。Doxygen `///` 声明块（概述、空 `///` 与细节）是声明骨架的一部分，摘录随源保留，不受此限。命名惯例、官方建议、未来演化等规范说理一律不进代码块；术语卡和可跳过的操作提醒可以进 callout，注释怎么写、行尾先写什么、`///` 与 `@` 标签怎么分工只留在 `.agents`，面向作者的进知识文件。
-- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「注释与空行可以省略」只服务后续章节复现已见代码。源码缺注释先按`steps/03-blocks.md`补注释，摘录逐字继承；自明成员按该规范不注，不因「全部注释」补自明行。
+- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「注释与空行可以省略」只服务后续章节复现已见代码。源码缺注释时交给项目 C++ 流程补齐，本技能不替源码补注释。
 - 讲解段只解释片段中实际出现的代码；片段没有展示的内容要么补进片段、要么进 callout，不在正文列表里讲代码外面的东西。
-- include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见`quarto/render.md`）。
+- include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见 `quarto/render.md`）。
 - 手动命令块标注执行位置，如 `filename="WSL Ubuntu（仓库根目录）"`。
 - 输出效果类代码块（运行效果、预期输出）filename 只写场景名（如「运行效果」）；终端样式、颜色等展示细节写进正文，不进 filename。输出摘录用单独一行 `...` 表示省略的工具输出，与源码片段的省略是两回事。
 
@@ -69,13 +69,13 @@ int main() {
 
 **禁止出围栏**：
 
-- 单次比较或直接 `return` 的平凡实现（判例：`IsInRange` 的两行 `return` 比较）——改写入口列表 + 失败策略列表，对照见`examples/05-sentence-brevity.md`「过简实现围栏」。
+- 单次比较或直接 `return` 的平凡实现（判例：`IsInRange` 的两行 `return` 比较）——改写入口列表 + 失败策略列表，对照见 `examples/05-sentence-brevity.md`「过简实现围栏」。
 - 仅为证明「源码有此函数」而贴出的实现。
 - 打断小节中心的硬插块。
 
 ### 类与多函数摘录的垂直空白
 
-摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行（规则与矩阵见`steps/03-blocks.md`「类与多函数摘录的垂直空白」）。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
+摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行（规则与矩阵见 `steps/03-blocks.md`「类与多函数摘录的垂直空白」）。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
 
 ### 三级标题最小模块
 
@@ -96,11 +96,11 @@ int main() {
 代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，两条硬边界：
 
 - 代码块与图之间必须有桥接句，说明图要核对代码已讲清的哪条关系；中间只有空行视为堆叠（`verifying-content.py` 的 DOC-E11 只要求相邻围栏留空行，空行不等于桥接正文）。
-- 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见`quarto/coords.md` 与 `steps/03-blocks.md`。
+- 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见 `quarto/coords.md` 与 `steps/03-blocks.md`。
 - 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（三条边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
 - 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式（「画面上方是列号」式会让读者翻回前章）；调用方行为等第二主题移出图前段（示例章定义坐标范围节两段并一段的改稿对照）。
 
-图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见`examples/03-qmd-elements.md`「代码与图桥接对照」。
+图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见 `examples/03-qmd-elements.md`「代码与图桥接对照」。
 
 ### 状态面板三态在页面上的摆法
 
@@ -116,18 +116,18 @@ int main() {
 
 ### 盒子密度
 
-盒子指代码块、表格、提示框、引用块、图表容器。密度阈值与权衡的唯一出处见`steps/03-blocks.md`，本条不重写数字。
+盒子指代码块、表格、提示框、引用块、图表容器。密度阈值与权衡的唯一出处见 `steps/03-blocks.md`，本条不重写数字。
 
 ### 标题导语
 
-`##` 下不强制写导语。只有导语补充任务顺序、前置条件、范围或标题没有表达的结果时才保留；把标题换一种说法的导语删除。代码块前不固定用冒号，冒号的合法场合见`steps/04-paragraphs.md`「散文伪标签冒号禁令」。
+`##` 下不强制写导语。只有导语补充任务顺序、前置条件、范围或标题没有表达的结果时才保留；把标题换一种说法的导语删除。代码块前不固定用冒号，冒号的合法场合见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」。
 
 ### 小节标题与正文对齐
 
 小节标题用了读者没学过的术语怎么办：标题要么已建立、要么当场用实物建立，做不到就下沉。规则如下：
 
-- 小节标题、首句和正文指向同一个动作或对象；标题说「做什么」，正文就只写怎么做、看到什么算成功。对象是否对齐，按`steps/02-structure.md`「纵向承诺链」第 4、5 条核对。块后许可的新信息不豁免标题对齐：树后或块后补写的内容，主语仍须是本节标题的对象，换成另一对象即视为换节。后文小节专讲的对象不提前交接，判法见`steps/05-sentences.md`「句内骨架」。
-- 标题的词性、空心题与术语禁令见`steps/02-structure.md`「标题分层」；术语要么已被前文章节建立，要么当场用读者可核对的实物（目录、文件、代码）建立；做不到就把内容下沉到概念建立之后的章节，章际下沉见`steps/02-structure.md`「六段块序列」。小节标题用了读者没学过的术语，就是这里要拦的;一句话压缩多个论断而读者无法逐条核对的，拆成可核对表述或删除；首句先给中心判断，再补机制，不先堆名称后给结论。正文论据同受此限：未在正文展示过的代码标识符（如测试概念建立前引用 `BoardTest`）不作论据，验证职责下沉到展示它的章节。改写对照见`examples/02-structure-shape.md`「小节标题抽象与首句无中心」。
+- 小节标题、首句和正文指向同一个动作或对象；标题说「做什么」，正文就只写怎么做、看到什么算成功。对象是否对齐，按 `steps/02-structure.md`「纵向承诺链」第 4、5 条核对。块后许可的新信息不豁免标题对齐：树后或块后补写的内容，主语仍须是本节标题的对象，换成另一对象即视为换节。后文小节专讲的对象不提前交接，判法见 `steps/05-sentences.md`「句内骨架」。
+- 标题的词性、空心题与术语禁令见 `steps/02-structure.md`「标题分层」；术语要么已被前文章节建立，要么当场用读者可核对的实物（目录、文件、代码）建立；做不到就把内容下沉到概念建立之后的章节，章际下沉见 `steps/02-structure.md`「六段块序列」。小节标题用了读者没学过的术语，就是这里要拦的;一句话压缩多个论断而读者无法逐条核对的，拆成可核对表述或删除；首句先给中心判断，再补机制，不先堆名称后给结论。正文论据同受此限：未在正文展示过的代码标识符（如测试概念建立前引用 `BoardTest`）不作论据，验证职责下沉到展示它的章节。改写对照见 `examples/02-structure-shape.md`「小节标题抽象与首句无中心」。
 - 操作小节（如「运行一键脚本」）只保留动作、顺序与可见结果。「为何不跳过某步 / 幂等 / 配置漂移」类工程取舍，删除后不影响首次跑通与验收的，不进该节正文；确需保留时由代码注释或排查节承担。
 - 跨节复述同一取舍视为标题离题的变体：该内容归属最贴合的节（如「修改 CMakeLists 后行为没变」），其余位置只保留一句或链接。
 
@@ -148,21 +148,21 @@ int main() {
 
 ### 豁免与边界
 
-- 块级前后闭环（三级标题最小模块）见`steps/03-blocks.md`；本文件管段落与小节之间的衔接，不重复块内规则。
-- 多命令代码块后的逐条讲解，见`steps/04-paragraphs.md`「段落规则」。
-- 小节承接正文权重与盒子密度见`steps/03-blocks.md`。
-- 散文冒号豁免清单与表格单元格、协议字面量的豁免见`steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式按`steps/05-sentences.md`「情况：围栏里的注释」判。
+- 块级前后闭环（三级标题最小模块）见 `steps/03-blocks.md`；本文件管段落与小节之间的衔接，不重复块内规则。
+- 多命令代码块后的逐条讲解，见 `steps/04-paragraphs.md`「段落规则」。
+- 小节承接正文权重与盒子密度见 `steps/03-blocks.md`。
+- 散文冒号豁免清单与表格单元格、协议字面量的豁免见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式不属本技能。
 
 ### 机械检查
 
-- 引章两个散文段、导语 token 与句数、段落篇幅：`verifying-content.py` 自动执行（限额见`steps/02-structure.md`）。
-- 普通自然段低于 token 下限：`verifying-content.py` 自动执行；豁免清单见`steps/02-structure.md`「分层上限」。
+- 引章两个散文段、导语 token 与句数、段落篇幅：`verifying-content.py` 自动执行（限额见 `steps/02-structure.md`）。
+- 普通自然段低于 token 下限：`verifying-content.py` 自动执行；豁免清单见 `steps/02-structure.md`「分层上限」。
 - 同段连续分句引入新的行内代码标识且无回指词：启发式 WARN，不追清零；高精度过简清单仍靠人工对照 cases。
 - 读者正文「下一节／上一节」、罗列短句信号等高精度项：`verifying-content.py`。
-- 「由…完成」被动交接（句内骨架判定信号之一，见`steps/05-sentences.md`「句内骨架」）：`verifying-content.py` 仅对读者 qmd 围栏外正文硬拦；`.agents` 案例可引用反例，不扫。
-- 拉链句高频词「分别交给」「各说一层」（见`steps/05-sentences.md`「拉链句」）：`verifying-content.py` 仅对读者正文硬拦；宽泛的「分别」不拦，留给人工对照案例。
-- 散文伪标签冒号与段内同义堆叠（见`steps/04-paragraphs.md`）：`verifying-content.py` 启发式 WARN（人工判，不追清零）。
-- 句子模块切分的三类失败（类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定，见`steps/05-sentences.md`「一次对话」）：`verifying-content.py` 全量执行；段中心写不出与对话件数不做正则，留给步骤与案例。
+- 「由…完成」被动交接（句内骨架判定信号之一，见 `steps/05-sentences.md`「句内骨架」）：`verifying-content.py` 仅对读者 qmd 围栏外正文硬拦；`.agents` 案例可引用反例，不扫。
+- 拉链句高频词「分别交给」「各说一层」（见 `steps/05-sentences.md`「拉链句」）：`verifying-content.py` 仅对读者正文硬拦；宽泛的「分别」不拦，留给人工对照案例。
+- 散文伪标签冒号与段内同义堆叠（见 `steps/04-paragraphs.md`）：`verifying-content.py` 启发式 WARN（人工判，不追清零）。
+- 句子模块切分的三类失败（类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定，见 `steps/05-sentences.md`「一次对话」）：`verifying-content.py` 全量执行；段中心写不出与对话件数不做正则，留给步骤与案例。
 
 ### 表格格
 
@@ -184,31 +184,31 @@ int main() {
 
 ### 命令、输出与细节各司其职
 
-命令是输入，输出是观察，正文是判断依据。三者混在同一个代码块或连续多个解释段落中，会让读者自己筛选"哪些行要复制、哪些行只是说明"。因此闭环目标、命令和成功判据各保留一个权威位置，操作小节拥有命令与验收，回顾和相邻段落只补充新增信息。路径、版本号等随环境变化的输出应展示可识别的典型形态，并给出"每项都有非空结果"这类稳定判据，而不是要求逐字匹配示例。成功判据与证据层级相称的要求见`steps/02-structure.md`「术语与验证策略」。
+命令是输入，输出是观察，正文是判断依据。三者混在同一个代码块或连续多个解释段落中，会让读者自己筛选"哪些行要复制、哪些行只是说明"。因此闭环目标、命令和成功判据各保留一个权威位置，操作小节拥有命令与验收，回顾和相邻段落只补充新增信息。路径、版本号等随环境变化的输出应展示可识别的典型形态，并给出"每项都有非空结果"这类稳定判据，而不是要求逐字匹配示例。成功判据与证据层级相称的要求见 `steps/02-structure.md`「术语与验证策略」。
 
 ### 盒子与正文的比例
 
-盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见`steps/03-blocks.md`。
+盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见 `steps/03-blocks.md`。
 
 修法是补承接正文，而不是删盒子。盒子承担可复制性，正文承担判断依据，两者不可互换，代码块删到只剩命令不会自动产生判断依据。
 
-代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见`steps/03-blocks.md`「元素边界」。
+代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见 `steps/03-blocks.md`「元素边界」。
 
 密度比例不设硬阈值。盒子多少、正文长短同时取决于视口宽度、字体度量和 Quarto 版本的 DOM 结构，任何一项变化都会让历史数值失效，基于 DOM 或截图的硬编码门禁只会在与密度无关的改动上误报，仍然禁止。`verifying-content.py` 保留一条软门禁：同一小节内两围栏（含 `{mermaid}` 与 `{python}` 单元）之间只有空行、没有桥接正文时报 WARN，提示人工补承接句；WARN 不判失败，人审与对照案例仍是叙事的主检查。
 
 ### 元素边界
 
-细节升级为标题的门槛见`steps/02-structure.md`。常见错误使用三级结构，是因为目录负责导航、具体症状负责识别、有序步骤负责操作。具体写法见`steps/02-structure.md` 与 `steps/03-blocks.md`。
+细节升级为标题的门槛见 `steps/02-structure.md`。常见错误使用三级结构，是因为目录负责导航、具体症状负责识别、有序步骤负责操作。具体写法见 `steps/02-structure.md` 与 `steps/03-blocks.md`。
 
 这种分层与页面整体的六段块序列并不冲突：它只收束任务段内部的阅读路径，不重新定义引言、任务序列、排查、自测和回顾的页面职责。
 
 ### 行内代码只标记需要逐字识别的对象
 
-命令、参数、文件名、路径、配置键、API 和标识符使用行内代码。Ubuntu、Windows 和 VS Code 作为普通平台名称时不加反引号。标题与导航不使用行内代码，形式规则见`steps/02-structure.md`。
+命令、参数、文件名、路径、配置键、API 和标识符使用行内代码。Ubuntu、Windows 和 VS Code 作为普通平台名称时不加反引号。标题与导航不使用行内代码，形式规则见 `steps/02-structure.md`。
 
 同一对象在同一页保持一种标记方式。链接标签内不再嵌套行内代码。行内标记连续出现时，改用完整句子减少读者来回切换字体。
 
-标记边界与术语节奏的执行规则见`examples/06-wording-cases.md`，本文件只解释为什么需要克制。
+标记边界与术语节奏的执行规则见 `examples/06-wording-cases.md`，本文件只解释为什么需要克制。
 
 ## 情况