@chengzhao-dev/dsh-quarto-book 0.6.17 → 0.6.19

package/skills/writing-quarto/references/rules-cards.md

@@ -53,7 +53,7 @@
 - 步骤：`steps/02-structure.md`
 
 **C10 章节按五步走。** 现象 → 最小例子 → 机制 → 边界 → 自测。
-- 正：`03-board.qmd` 依次讲空棋盘、落子、越界、判胜、自测。
+- 正：章文件依次讲空棋盘、落子、越界、判胜、自测。
 - 反：先给完整类声明，再逐行解释。
 - 步骤：`steps/02-structure.md`
 
@@ -63,8 +63,8 @@
 - 步骤：`steps/03-blocks.md`
 
 **C12 一节一个关键。** 一章只解决一个问题，多出来的挪到下一章。
-- 正：03 章只讲棋盘；游戏流程留给 04 章。
-- 反：03 章顺手把 `Game` 的状态机也讲了。
+- 正：讲棋盘的章只讲棋盘；游戏流程留给下一章。
+- 反：讲棋盘的章顺手把 `Game` 的状态机也讲了。
 - 步骤：`steps/02-structure.md`
 
 **C13 章首导语 60–146 字。** 一段说清这章解决什么、读者读完能做什么。

package/skills/writing-quarto/references/token-budget.md

@@ -18,11 +18,11 @@
 | `assets/**/meta.md` | 2000 |
 | 全部技能 Markdown 合计 | 140000 |
 
-单次激活上限：`SKILL.md` + 1 个步骤 + 1 个被点名文件（案例、条文或脚本路径）。**九步同走**只用于新章、新阶段或用户明确要求全章重构；同轮不把同号案例与条文一起打开。
+单次激活上限：`SKILL.md` + 1 个步骤 + 1 个被点名文件（案例、条文或脚本路径）。**九步同走**只用于新章、整章改写或用户明确要求全章处理；同轮不把同号案例与条文一起打开。
 
 ## 怎么用
 
 - 新增规则先判断属于哪一层，再写进已有文件；同一判定只成文一处，其他位置写引用。
 - 文件将超限时，先删重复、合并同源条目，再考虑拆成同目录的新文件；拆文件后同步入口和 `scripts/checking-skill-links.mjs`。
-- 增量任务只加载 `SKILL.md`、当前一步与该步点名的一个文件；不要为了省 token 把整本书的规则塞进 `SKILL.md`。
+- 单点修改只加载 `SKILL.md`、当前一步与该步点名的一个文件；不要为了省 token 把整本书的规则塞进 `SKILL.md`。
 - 预算不是目标：没必要的条文直接删，不靠缩写把句子压成暗语。

package/skills/writing-quarto/scripts/testing-content.py

@@ -122,7 +122,7 @@ title: 入门
 下面是一张只画类型和边的类图，读者可以对照箭头理解类型之间的依赖。
 
 ::: {.class-diagram}
-```{mermaid}
+```{mermaid role="img" aria-label="类型 A 依赖类型 B"}
 %%| fig-cap: "类型 A 依赖类型 B。实线箭头从使用者指向被使用者。"
 %%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif", "class": {"hideEmptyMembersBox": true}}}%%
 classDiagram
@@ -178,12 +178,17 @@ def main() -> int:
         needle: str,
         project: bool = False,
         checks_json: str | None = None,
+        files: dict[str, str] | None = None,
     ) -> None:
         nonlocal passed_cases
         passed_cases += 1
         with tempfile.TemporaryDirectory() as raw:
             root = Path(raw)
             make_book(root, chapter)
+            for relative, content in (files or {}).items():
+                target = root / relative
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(content, encoding="utf-8")
             if project:
                 skill_dir = root / ".agents" / "skills" / "quarto-book-project"
                 skill_dir.mkdir(parents=True)
@@ -293,6 +298,18 @@ def main() -> int:
         "---\ntitle: 入门\n---\n\n## 目标\n\n```mermaid\ngraph LR\n```\n",
         1, "plain mermaid",
     )
+    expect(
+        "mermaid 围栏带前导点",
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        '```{.mermaid role="img" aria-label="流程"}\ngraph LR\n```\n',
+        1, "不会载入图表脚本",
+    )
+    expect(
+        "mermaid 围栏正确写法",
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        '```{mermaid role="img" aria-label="流程"}\ngraph LR\n```\n',
+        0, "OK",
+    )
     expect(
         "未声明围栏",
         "---\ntitle: 入门\n---\n\n## 目标\n\n```\nprint(1)\n```\n",
@@ -316,6 +333,67 @@ def main() -> int:
         0, "OK",
     )
 
+    excerpt_url = "https://github.com/your-org/your-book/blob/main/games/board.h"
+    excerpt_source = (
+        "/// 判断两个坐标是否相同。\n"
+        "///\n"
+        "/// @param lhs 左操作数。\n"
+        "/// @return 相同返回 true。\n"
+        "bool Same(int lhs, int rhs);\n"
+    )
+    excerpt_chapter = VALID_CHAPTER + (
+        f"\n声明见 [board.h]({excerpt_url})。\n\n"
+    )
+    expect(
+        "正文讲解文件头",
+        VALID_CHAPTER + "\n每个源文件开头都有一段 Doxygen 文件头。\n",
+        1, "文件级",
+    )
+    expect(
+        "围栏摘录 @file",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n/// @file board.h\n/// @brief 棋盘。\n```\n",
+        1, "文件级",
+    )
+    expect(
+        "围栏注释截断",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n"
+        "/// 判断两个坐标是否相同。\n"
+        "bool Same(int lhs, int rhs);\n"
+        "```\n",
+        1, "只摘了",
+        files={"games/board.h": excerpt_source},
+    )
+    expect(
+        "围栏注释整段一致",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n"
+        + excerpt_source
+        + "```\n",
+        0, "OK",
+        files={"games/board.h": excerpt_source},
+    )
+    expect(
+        "围栏整段不摘注释",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n"
+        "bool Same(int lhs, int rhs);\n"
+        "```\n",
+        0, "OK",
+        files={"games/board.h": excerpt_source},
+    )
+    expect(
+        "输出围栏不比对注释",
+        VALID_CHAPTER
+        + "\n```text filename=\"运行效果\"\n"
+        "/// 判断两个坐标是否相同。\n"
+        "bool Same(int lhs, int rhs);\n"
+        "```\n",
+        0, "OK",
+        files={"games/board.h": excerpt_source},
+    )
+
     expect("目录树合格", TREE_CHAPTER, 0, "OK")
     expect("原生 SVG 缺图注", HTML_FIGURE_BAD, 1, "figcaption")
     expect("原生 SVG 图注合格", HTML_FIGURE_GOOD, 0, "OK")
@@ -379,7 +457,10 @@ def main() -> int:
     expect("类图图注写在 init 之后", wrong_order, 1, "init 之前")
     expect(
         "类图缺少页面容器",
-        MERMAID_CHAPTER.replace("::: {.class-diagram}\n```{mermaid}", "```{mermaid}").replace(
+        MERMAID_CHAPTER.replace(
+            '::: {.class-diagram}\n```{mermaid role="img" aria-label="类型 A 依赖类型 B"}',
+            '```{mermaid role="img" aria-label="类型 A 依赖类型 B"}',
+        ).replace(
             "```\n:::", "```"
         ),
         1, ".class-diagram",

package/skills/writing-quarto/scripts/verifying-content.py

@@ -78,6 +78,12 @@ TEST_RE = re.compile(r"测试|断言|用例|gtest|CTest")
 # 围栏与正文的配对：声明围栏只配契约文字。正文出现实现词而小节里没有定义围栏时
 # 报 decl-without-def，规则与正反例见 references/fence-semantics.md。
 FENCE_FILENAME_RE = re.compile(r'filename="([^"]+)"')
+# 读者正文不摘文件级 Doxygen 头；成员注释的 @param、@return 不受这条限制。
+EXCERPT_HEADER_RE = re.compile(r"@file\b|@brief\b|Doxygen\s*文件头")
+REF_DEFINITION_RE = re.compile(r"^\s*\[([^\]]+)\]:\s*(\S+)\s*$")
+REF_USE_RE = re.compile(r"\]\[([^\]]+)\]")
+BLOB_URL_RE = re.compile(r"^https://github\.com/[^/]+/[^/]+/blob/[^/]+/(.+)$")
+DOC_COMMENT_RE = re.compile(r"^\s*///")
 IMPL_MARKER_RE = re.compile(r"复用|委托给|扫描|遍历|对每个|短路|表达式|状态位|缓存|不再单独|递归")
 FENCE_SKIP_SECTION_RE = re.compile(r"常见错误|自测|回顾|练习|小结")
 DECL_SUFFIXES = (".h", ".hpp", ".hh", ".hxx")
@@ -105,6 +111,8 @@ HEADING_PERSONAL_RE = re.compile(r"自己|咱们|我们|你|您|跟我|试试|
 FENCE_RE = re.compile(r"^\s*(```+|~~~+)\s*(\{[^}]*\}|[^\s`]*)?")
 LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
 LINK_LABEL_RE = re.compile(r"\[([^\]]*)\]\([^)]*\)")
+LIST_LINE_RE = re.compile(r"^\s*(?:[-*+]|\d+\.)\s+")
+GUIDED_ITEM_RE = re.compile(r"^\*\*[^*\n]{1,30}\*\*：")
 CJK_RE = re.compile(r"[\u3400-\u9fff]")
 TITLE_RE = re.compile(r"^title:\s*(.+?)\s*$", re.MULTILINE)
 
@@ -295,6 +303,70 @@ def check_prose_block(
                 ))
                 break
 
+    if not is_list and CJK_RE.search(compact):
+        sentences = [
+            sentence.strip()
+            for sentence in re.split(r"(?<=[。！？])", compact)
+            if sentence.strip()
+        ]
+        seen_names: set[str] = set()
+        for index, sentence in enumerate(sentences):
+            if index > 0:
+                if sentence.startswith("它") and len(sentence) > 1 and sentence[1] != "们":
+                    issues.append(Issue(
+                        path, start_line,
+                        "过简断裂：「它」开头的句子没有接住前句句末的对象；写回原对象名",
+                    ))
+                    break
+                lead = INLINE_NAME_RE.match(sentence)
+                if lead and lead.group(1) not in seen_names:
+                    issues.append(Issue(
+                        path, start_line,
+                        f"过简断裂：后句以新标识符「{lead.group(1)}」开头，前句没有承接；先用回指词接住",
+                    ))
+                    break
+            for match in INLINE_NAME_RE.finditer(sentence):
+                seen_names.add(match.group(1))
+
+
+def visible_length(text: str) -> int:
+    visible = LINK_LABEL_RE.sub(r"\1", text)
+    visible = re.sub(r"[*`]", "", visible)
+    return len(re.sub(r"\s+", "", visible))
+
+
+def check_list_block(
+    path: Path, items: list[tuple[int, str]], issues: list[Issue], landing: bool = False
+) -> None:
+    if len(items) < 2:
+        return
+    guided = [bool(GUIDED_ITEM_RE.match(text)) for _, text in items]
+    if any(guided) and not all(guided):
+        issues.append(Issue(
+            path, items[0][0],
+            "同一列表混用普通句子和「**引导词**：」句式；统一成多数项使用的那一种",
+        ))
+        return
+    lengths = [
+        (line, visible_length(text))
+        for line, text in items
+        if text.strip()
+    ]
+    lengths = [(line, length) for line, length in lengths if length > 0]
+    if len(lengths) < 2 or landing:
+        return
+    joined = "".join(text for _, text in items)
+    if "出错的原因" in joined and "正确的做法" in joined:
+        return
+    longest = max(lengths, key=lambda pair: pair[1])
+    shortest = min(lengths, key=lambda pair: pair[1])
+    if longest[1] < 2 * shortest[1]:
+        return
+    issues.append(Issue(
+        path, longest[0],
+        f"列表项字数失衡：最长 {longest[1]} 字，最短 {shortest[1]} 字；删长项多余中心或把长项收成一句",
+    ))
+
 
 def display_width(text: str) -> int:
     return sum(2 if unicodedata.east_asian_width(char) in {"W", "F"} else 1 for char in text)
@@ -653,6 +725,159 @@ def check_fence_semantics(path: Path, lines: list[str]) -> list[Issue]:
     return issues
 
 
+def normalize_code(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def collect_excerpt_links(lines: list[str]) -> list[tuple[int, str]]:
+    """Return GitHub blob links in reading order, including reference-style uses."""
+    definitions: dict[str, str] = {}
+    for raw in lines:
+        definition = REF_DEFINITION_RE.match(raw)
+        if definition:
+            definitions.setdefault(definition.group(1), definition.group(2))
+    links: list[tuple[int, str]] = []
+    for number, raw in enumerate(lines, start=1):
+        for match in LINK_RE.finditer(raw):
+            links.append((number, match.group(1).strip()))
+        for match in REF_USE_RE.finditer(raw):
+            target = definitions.get(match.group(1))
+            if target:
+                links.append((number, target))
+    links.sort()
+    return links
+
+
+def excerpt_fence_blocks(lines: list[str]) -> list[tuple[int, str, list[tuple[int, str]]]]:
+    """Return (opening line, filename, body) for every fence with a filename."""
+    blocks: list[tuple[int, str, list[tuple[int, str]]]] = []
+    in_fence = False
+    start = 0
+    filename = ""
+    body: list[tuple[int, str]] = []
+    for number, raw in enumerate(lines, start=1):
+        fence = FENCE_RE.match(raw)
+        if fence:
+            if not in_fence:
+                in_fence = True
+                start = number
+                opening = FENCE_FILENAME_RE.search(raw)
+                filename = opening.group(1) if opening else ""
+                body = []
+            else:
+                in_fence = False
+                if filename:
+                    blocks.append((start, filename, body))
+                filename = ""
+                body = []
+            continue
+        if in_fence:
+            body.append((number, raw))
+    return blocks
+
+
+def source_doc_above(source: list[str], index: int) -> list[str]:
+    """Collect the contiguous `///` block that sits directly above index."""
+    block: list[str] = []
+    cursor = index - 1
+    while cursor >= 0:
+        raw = source[cursor]
+        if not DOC_COMMENT_RE.match(raw) or raw.lstrip().startswith("///<"):
+            break
+        block.append(raw)
+        cursor -= 1
+    block.reverse()
+    return block
+
+
+def check_excerpts(path: Path, root: Path, lines: list[str]) -> list[Issue]:
+    """Reader text carries no file headers; kept doc comments match the source."""
+    issues: list[Issue] = []
+    for number, raw in enumerate(lines, start=1):
+        if EXCERPT_HEADER_RE.search(raw):
+            issues.append(Issue(
+                path, number,
+                "读者正文不摘文件级 Doxygen 头（@file、@brief、文件范围段）；"
+                "删掉这段，围栏从它之后开始",
+            ))
+
+    links = collect_excerpt_links(lines)
+    for start, filename, body in excerpt_fence_blocks(lines):
+        candidates = [
+            (number, target)
+            for number, target in links
+            if number < start and target.rsplit("/", 1)[-1] == filename
+        ]
+        if not candidates:
+            continue
+        target = candidates[-1][1]
+        blob = BLOB_URL_RE.match(target)
+        if not blob:
+            continue
+        relative = blob.group(1)
+        source_path = (root / relative).resolve()
+        if root not in source_path.parents or not source_path.is_file():
+            continue
+        source = read_text(source_path).splitlines()
+
+        pending: list[tuple[int, str]] = []
+        pending_start = start
+        for number, raw in body:
+            stripped = raw.strip()
+            if DOC_COMMENT_RE.match(raw) and not stripped.startswith("///<"):
+                if not pending:
+                    pending_start = number
+                pending.append((number, raw))
+                continue
+            if not pending:
+                continue
+            if not stripped:
+                pending = []
+                continue
+            declaration = normalize_code(raw)
+            fence_block = [item.strip() for _, item in pending]
+            pending = []
+            if not declaration or declaration.startswith(("#", "}", "{", "...")):
+                continue
+            matches = [
+                index for index, item in enumerate(source)
+                if normalize_code(item) == declaration
+            ]
+            if not matches:
+                continue
+            # 同一行声明可能在多个类里重复（如各实现类的 override）；任一处注释
+            # 与围栏整段一致即通过，避免把第一个同名声明当成唯一出处。
+            source_blocks = [
+                [item.strip() for item in source_doc_above(source, index)]
+                for index in matches
+            ]
+            if any(block == fence_block for block in source_blocks):
+                continue
+            if not fence_block:
+                continue
+            prefixes = [
+                block for block in source_blocks
+                if len(block) > len(fence_block) and block[: len(fence_block)] == fence_block
+            ]
+            if prefixes:
+                issues.append(Issue(
+                    path, pending_start,
+                    f"围栏只摘了 {filename} 注释的前 {len(fence_block)} 行；"
+                    "整段补上 @param、@return 与空 /// 行，或整段不摘",
+                ))
+            elif all(not block for block in source_blocks):
+                issues.append(Issue(
+                    path, pending_start,
+                    f"围栏带有注释，但 {filename} 对应声明上方没有 /// 注释；整段删掉",
+                ))
+            else:
+                issues.append(Issue(
+                    path, pending_start,
+                    f"围栏注释与 {filename} 对应声明上方的不一致；整段照抄或整段不摘",
+                ))
+    return issues
+
+
 def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> list[Issue]:
     issues: list[Issue] = []
     text = read_text(path)
@@ -682,7 +907,9 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
     fence_is_html = False
     paragraph: list[str] = []
     paragraph_start = 0
+    list_items: list[tuple[int, str]] = []
     last_fence_end: int | None = None
+    landing = path.resolve() == (root / "index.qmd").resolve()
 
     def flush_paragraph() -> None:
         nonlocal paragraph
@@ -690,10 +917,17 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
             check_prose_block(path, paragraph_start, " ".join(paragraph), issues)
             paragraph = []
 
+    def flush_list() -> None:
+        nonlocal list_items
+        if len(list_items) >= 2:
+            check_list_block(path, list_items, issues, landing=landing)
+        list_items = []
+
     for number, raw in enumerate(lines, start=1):
         fence = FENCE_RE.match(raw)
         if fence:
             flush_paragraph()
+            flush_list()
             if not in_fence:
                 in_fence = True
                 fence_start = number
@@ -712,7 +946,12 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                 elif fence_lang.startswith("{"):
                     inner = fence_lang.strip("{}").strip()
                     fence_is_html = inner == "=html"
-                    if inner and not inner.startswith((".", "=")) and "mermaid" not in inner:
+                    if inner.startswith(".") and "mermaid" in inner:
+                        issues.append(Issue(
+                            path, number,
+                            "Mermaid 围栏写成 `{.mermaid}`，Quarto 不会载入图表脚本，图会退化成代码块；改成 `{mermaid ...}`",
+                        ))
+                    elif inner and not inner.startswith((".", "=")) and "mermaid" not in inner:
                         # ```{python} style attribute fences are valid.
                         pass
             else:
@@ -742,6 +981,7 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
         heading = HEADING_RE.match(raw)
         if heading:
             flush_paragraph()
+            flush_list()
             level = len(heading.group(1))
             heading_text = heading.group(2)
             if level == 1:
@@ -760,26 +1000,33 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
 
         if raw.lstrip().startswith("|"):
             flush_paragraph()
+            flush_list()
             # 表格行按列组织，不套散文句长阈值；列数与表头一致性由表格检查负责。
             continue
 
         if raw.lstrip().startswith((">", "-", "*", "+", "1.")):
             flush_paragraph()
-            check_prose_block(
-                path, number, re.sub(r"^\s*(?:[>|]|[-*+]|\d+\.)\s*", "", raw), issues, is_list=True
-            )
+            item_text = re.sub(r"^\s*(?:[>|]|[-*+]|\d+\.)\s*", "", raw)
+            if LIST_LINE_RE.match(raw):
+                list_items.append((number, item_text))
+            else:
+                flush_list()
+            check_prose_block(path, number, item_text, issues, is_list=True)
             continue
 
+        flush_list()
         if not paragraph:
             paragraph_start = number
         paragraph.append(raw.strip())
 
     flush_paragraph()
+    flush_list()
 
     if in_fence:
         issues.append(Issue(path, fence_start, "代码围栏未闭合"))
 
     issues.extend(check_fence_semantics(path, lines))
+    issues.extend(check_excerpts(path, root, lines))
 
     for block in fence_blocks:
         issues.extend(check_tree_block(path, block))

package/skills/writing-quarto/steps/01-task.md

@@ -1,65 +1,48 @@
 # 第 1 步：定任务
 
-产出：一句读者做完能完成的事，加上这一章要覆盖的任务清单。
-这一步不动标题层级，也不改句子。
+产出：一句读者做完能完成的事，加上本章要覆盖的任务清单。
+这一步不动标题层级，也不改句子；两条规则冲突时按 `references/priority.md` 排级，本步先让位给读者任务与事实。
 
 ## 通用情况
 
-### 读者
+### 读者与术语门槛
 
-读者有编程基础，可能第一次接触本书使用的语言、构建工具或自动化测试。每页只解决一个任务。正文按书的实际技术栈写，不预设某一种语言或操作系统；需要环境差异时在页面里就地交代。
+读者有编程基础，可能第一次接触本书使用的语言、构建工具或自动化测试。每页只解决一个任务；正文按书的实际技术栈写，不预设某一种语言或操作系统，需要环境差异时在页面里就地交代。
+
+- 不假设读者知道工具名、命令参数、目录布局或错误输出代表的含义。
+- 标准术语首次出现时用一句话解释或就近术语卡，再进入命令；解释写成可观察行为，缩写先写全称（写法见 `quarto/readability.md`）。
+- 只保留判断成功所需的输出，不解释对当前操作没有影响的内部格式。
+- 面向新人的正文不堆砌入门前置名词；标题只用读者此刻已认识的词。
 
 ### 叙事范围（硬边界）
 
-本书定位是可用工程的用法与验收；编程语言机制的系统讲解不属于正文。`content/**` 正文因此只写五类内容：领域语义、分层与依赖、接口契约、构建与测试验收、可验证动作。
+本书定位是可用工程的用法与验收；编程语言机制的系统讲解不属于正文。`content/**` 正文只写五类内容：领域语义、分层与依赖、接口契约、构建与测试验收、可验证动作。
 
-- **禁止**用正文讲解编程语言机制（枚举、结构体、命名空间、`inline`、`constexpr`、翻译单元、ODR 等），也禁止风格指南逐条教学（命名大小写、前缀、include guard 对比等）。
+- **语言机制与风格指南的取舍先看项目技能**：项目技能写明禁止时，正文不展开枚举、结构体、命名空间、`inline`、`constexpr`、翻译单元、ODR，也不逐条教命名大小写、前缀或 include guard。项目没写时按读者门槛判断，不要默认开语言课。
 - 枚举取值列表的位置见 `steps/03-blocks.md`「三级标题最小模块」。
 - **禁止**在工程章（非设计章）展开数值选型旁白：不写「用有符号整型承载…」「某字段为什么选定宽有符号整型…」，也不为选型链到外部语言笔记。`int` 可出现在代码摘录中，旁白不解释「为什么有符号」。
-- **禁止课堂类比**：工程坐标系、API 与数据结构只用程序事实与可观察行为表述，不写「数学课」「平面直角坐标系」等跨学科课堂对照（如「与数学课的直角坐标系正好相反」）。作者构思时可借类比想问题，落盘到 qmd 前必须换成工程对象与可观察行为；图注已交代原点与轴向的，正文不复述对照。
-- **禁止突兀跨仓依据句**：不写「写法依据见 / 依据见 / 机制见 / 选型见 / 承诺见 / 用法见 / 陷阱见」+ 外部语言笔记。工程约定由本书拥有；外部教材不是工程写法的依据机关。
-- **跨仓外链默认零条**。工程叙事须自洽。仅当本小节工程点已讲完、且确有系统学语法需求时，可在小节末**单独成句**尾置可选深潜，口吻为「若要系统阅读…，见对应章节（GitHub 绝对 URL）。」同一章此类深潜宜 ≤2，能删则删。仅设计章可保留一次分册级链接。本书固定采用外部章节的构建约定时，用「本书固定采用…」陈述，仍放工程点之后，禁用「写法依据见」。
+- **禁止课堂类比**：工程坐标系、API 与数据结构只用程序事实与可观察行为表述，不写「与数学课的直角坐标系正好相反」这类跨学科课堂对照；图注已交代原点与轴向的，正文不复述对照。
+- **禁止突兀跨仓依据句**：不写「写法依据见 / 依据见 / 机制见 / 选型见 / 承诺见 / 用法见 / 陷阱见」+ 外部语言笔记。工程约定由本书拥有，外部教材不是工程写法的依据机关。
+- **跨仓外链默认零条**：工程叙事须自洽。仅当本小节工程点已讲完、且确有系统学语法需求时，可在小节末单独成句尾置可选深潜，口吻为「若要系统阅读…，见对应章节（GitHub 绝对 URL）」，同一章宜 ≤2，能删则删；仅设计章可保留一次分册级链接。本书固定采用外部章节的构建约定时，用「本书固定采用…」陈述，仍放工程点之后。
 - **允许**代码块逐字展示源码（关键字照抄真实代码）；旁白回答工程问题：这段公共定义解决什么问题、谁读取或调用它、如何验证。
-- **禁止接口清单压缩段**：不得把私有成员、公开成员名单、`const`、`[[nodiscard]]` 等接口属性压进同一段旁白；定稿形态为场景（动作 → 点名 → 边界）→ 代码 → 块后只补注释未覆盖的工程信息；语言属性不进旁白讲义（对照见 `examples/04-paragraph-opening.md`「接口清单压缩段」）。
+- **禁止接口清单压缩段**：不把私有成员、公开成员名单、`const`、`[[nodiscard]]` 等接口属性压进同一段旁白；定稿形态为场景（动作 → 点名 → 边界）→ 代码 → 块后只补注释未覆盖的工程信息（对照见 `examples/04-paragraph-opening.md`「接口清单压缩段」）。
 - 判定口诀：句子的主语应是工程对象（模块、接口、数据、文件），不是语言构造（`enum class`、翻译单元）。反例与改写对照见 `examples/01-language-scope.md` 与 `examples/04-paragraph-cases.md`。
 
-### 内容优先级
-
-章节出现取舍时，按下面的顺序判断，不用较低层级的格式或样式要求覆盖较高层级的教学目标：
-
-1. 读者任务与章节边界
-2. 信息顺序和渐进披露
-3. 页面块与段落布局
-4. 技术正确性和可验证性
-5. 标题、列表、Callout 和代码块等表达形式
-6. 句子精简、术语和标点
-7. 视觉样式与装饰
-
-新增内容先确定它在既有页面块序列中的位置，再写入相邻小节。修改后回读完整小节及前后切口，确认动作、结果和下一步仍然相邻。只有步骤存在先后依赖时使用有序列表；同级选项使用无序列表；连续因果解释保留为短段落。
+### 定任务的做法
 
-目录树先核对磁盘，再只保留当前任务需要的文件；注释、排列顺序与树后读法句统一见 `steps/03-blocks.md`「情况：目录树」。GitHub blob 链接嵌进同节导语句子里，不单独成行贴在代码围栏上方。线性构建流程用标题和文字说明，不用 Mermaid 代替。
-
-### 术语门槛
-
-- 保留编译、链接、目标、状态、回合等标准术语；首次出现时用一句话解释或就近术语卡，再进入命令。解释写成可观察行为，缩写先写全称；细则见 `quarto/readability.md`。
-- 不解释对当前操作没有影响的内部格式。只保留判断成功所需的输出。
-- 面向新人的正文不堆砌入门前置名词；标题只用读者此刻已认识的词。
-
-### 定任务：先让新人完成任务
-
-- 开篇场景的写法见 `steps/02-structure.md`「六段块序列」。
-- 每页一条成功路径与后置内容的判定见 `steps/06-wording.md`；主线闭合见 `steps/02-structure.md`。
-- 标准术语的首次解释与术语卡落点见 `steps/02-structure.md`（写法见 `quarto/authoring.md`）；缩写先写全称。
-- 不假设读者知道工具名、命令参数、目录布局或错误输出代表的含义。
-- 目录式堆砌禁令与清单下沉判据见 `steps/02-structure.md`。
-- 标题与引言的单事承诺、承诺用词与 title 变更同步见 `steps/02-structure.md`。
-- 语言课禁令、否定式预告、不写「下一节」都在这一步判：它们决定本章能不能出现某句，不是措辞问题（细则见 `steps/05-sentences.md`「句子规则」、本文件「叙事范围」）。
+- 任务写成读者做完能完成的一件事，不写成语法清单或功能列表；每页一条成功路径。
+- 开篇场景的写法见 `steps/02-structure.md`「六段块序列」；标准术语的首次解释与术语卡落点同见该节（写法见 `quarto/authoring.md`）。
+- 目录式堆砌禁令与清单下沉判据见 `steps/02-structure.md`；标题与引言的单事承诺、承诺用词与 title 变更同步同见该文件。
+- 语言课禁令、否定式预告、不写「下一节」在这一步判：它们决定本章能不能出现某句，不是措辞问题（细则见 `steps/05-sentences.md`「句子规则」与本文件「叙事范围（硬边界）」）。
+- 新增内容先确定它在既有页面块序列中的位置，再写入相邻小节；修改后回读完整小节及前后切口，确认动作、结果和下一步仍然相邻。
+- 只有步骤存在先后依赖时用有序列表；同级选项用无序列表；连续因果解释保留为短段落。
+- 目录树先核对磁盘，再只保留当前任务需要的文件，注释与读法句见 `steps/03-blocks.md`「情况：目录树」。GitHub blob 链接嵌进同节导语句子，不单独成行贴在围栏上方。线性构建流程用标题和文字说明，不用 Mermaid 代替。
 
 ## 情况
 
 ### 情况：语言课
 
-讲语言特性时，任务写成「读者能读懂一段真实代码」，不写成语法清单。叙事范围跟着读者的语言门槛收窄。对照 `examples/01-language-scope.md`。
+讲语言特性时，任务写成「读者能读懂一段真实代码」，不写成语法清单；叙事范围跟着读者的语言门槛收窄。对照 `examples/01-language-scope.md`。
 
 ### 情况：否定式预告
 
@@ -71,7 +54,7 @@
 
 ### 情况：没有项目技能
 
-书里没有 `.agents/skills/quarto-book-project/` 时跳过书名、读者和章节表，不猜也不补。任务只从当前文件和 `_quarto.yml` 读到的内容定。
+书里没有 `.agents/skills/quarto-book-project/` 时跳过书名、读者和章节表，不猜也不补；任务只从当前文件与 `_quarto.yml` 读到的内容定。
 
 ## 正反例