@chengzhao-dev/dsh-quarto-book 0.6.3 → 0.6.4

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

@@ -68,6 +68,36 @@ title: 入门
 """
 
 
+HTML_FIGURE_BAD = """---
+title: 入门
+---
+
+## 目标
+
+这一章说明一个可以重复验证的目标。
+
+```{=html}
+<svg class="coords-grid" role="img" aria-label="棋盘坐标。"><rect width="10" height="10"/></svg>
+```
+"""
+
+HTML_FIGURE_GOOD = """---
+title: 入门
+---
+
+## 目标
+
+这一章说明一个可以重复验证的目标。
+
+```{=html}
+<figure class="book-figure">
+<svg class="coords-grid" role="img" aria-label="棋盘坐标。"><rect width="10" height="10"/></svg>
+<figcaption>棋盘坐标图：3 行 3 列。</figcaption>
+</figure>
+```
+"""
+
+
 TREE_GAP_CHAPTER = """---
 title: 入门
 ---
@@ -139,8 +169,11 @@ def main() -> int:
         pass
 
     failures: list[str] = []
+    passed_cases = 0
 
     def expect(name: str, chapter: str, code: int, needle: str, project: bool = False) -> None:
+        nonlocal passed_cases
+        passed_cases += 1
         with tempfile.TemporaryDirectory() as raw:
             root = Path(raw)
             make_book(root, chapter)
@@ -177,6 +210,31 @@ def main() -> int:
         VALID_CHAPTER + "\n`Game` 与 `Board` 之间的组成边表示什么？\n",
         1, "自造关系词",
     )
+    expect(
+        "类型承载",
+        VALID_CHAPTER + "\n坐标由 `CellPosition` 承载，取值由 `CellType` 承载。\n",
+        1, "承载",
+    )
+    expect(
+        "小节导航",
+        VALID_CHAPTER + "\n下一节说明落子顺序。\n",
+        1, "小节导航",
+    )
+    expect(
+        "拉链句",
+        VALID_CHAPTER + "\n两个类型分别交给坐标与取值。\n",
+        1, "拉链句",
+    )
+    duplicate_link = (
+        "https://github.com/chengzhao-dev/cpp-board-games/blob/main/"
+        "games/tictactoe/tictactoe/include/board.h"
+    )
+    expect(
+        "同章重复文件链接",
+        VALID_CHAPTER
+        + f"\n[board.h]({duplicate_link})\n\n[board.h]({duplicate_link})\n",
+        1, "同章重复文件链接",
+    )
     expect("标题口语化", VALID_CHAPTER.replace("## 目标", "## 自己走一局"), 1, "标题带人称")
     expect("标题带行内代码", VALID_CHAPTER.replace("## 目标", "## 运行 `app`"), 1, "标题带行内代码")
     expect("正文 H1", VALID_CHAPTER.replace("## 目标", "# 目标"), 1, "正文出现 H1")
@@ -196,6 +254,12 @@ def main() -> int:
         "---\ntitle: 入门\n---\n\n## 目标\n\n```\nprint(1)\n```\n",
         1, "未声明语言",
     )
+    expect(
+        "相邻围栏缺少空行",
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        "```text\na\n```\n```text\nb\n```\n",
+        1, "DOC-E11",
+    )
     expect(
         "项目禁用词生效",
         "---\ntitle: 入门\n---\n\n## 目标\n\n棋盘格子按行列编号，程序读取当前状态。\n",
@@ -209,6 +273,8 @@ def main() -> int:
     )
 
     expect("目录树合格", TREE_CHAPTER, 0, "OK")
+    expect("原生 SVG 缺图注", HTML_FIGURE_BAD, 1, "figcaption")
+    expect("原生 SVG 图注合格", HTML_FIGURE_GOOD, 0, "OK")
     expect(
         "标记后多空格",
         TREE_CHAPTER.replace("# 读入坐标", "#  读入坐标"),
@@ -325,6 +391,7 @@ def main() -> int:
     )
 
     with tempfile.TemporaryDirectory() as raw:
+        passed_cases += 1
         root = Path(raw)
         make_book(root)
         (root / "content" / "part" / "01-intro.qmd").unlink()
@@ -339,7 +406,7 @@ def main() -> int:
             print(f"  FAIL {line}")
         return 1
 
-    print("PASS：36 个用例全部通过")
+    print(f"PASS：{passed_cases} 个用例全部通过")
     return 0
 
 

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

@@ -51,6 +51,9 @@ TRAILING_SPACE_RE = re.compile(r"[ 	]+$")
 QA_PROSE_RE = re.compile(r"(?:它|只|都|分别|各自)回答|回答(?:四类|整局|这个|哪些|什么)")
 CODE_META_RE = re.compile(r"对应的代码")
 COINED_RELATION_RE = re.compile(r"(?:组成|依赖|继承|调用)边")
+CARRIER_RE = re.compile("承载")
+NEXT_SECTION_RE = re.compile(r"(?:下一节|上一节)")
+LADDER_RE = re.compile(r"(?:分别交给|各说一层)")
 
 TREE_CATEGORY_COMMENTS = frozenset({
     "头文件", "源文件", "源码", "实现", "测试", "配置文件",
@@ -89,7 +92,8 @@ class Issue:
 
 
 def read_text(path: Path) -> str:
-    return path.read_text(encoding="utf-8", errors="replace")
+    # utf-8-sig 兼容带 BOM 的合法 UTF-8 文件；BOM 不进入行号与正文。
+    return path.read_text(encoding="utf-8-sig")
 
 
 def strip_frontmatter(text: str) -> tuple[str, str]:
@@ -139,9 +143,9 @@ def parse_chapters(quarto_yml: Path) -> list[str]:
         if stripped and not raw.startswith((" ", "\t", "-")):
             in_chapters = False
             continue
-        if not stripped.startswith("-"):
+        if not stripped:
             continue
-        item = stripped[1:].strip()
+        item = stripped[1:].strip() if stripped.startswith("-") else stripped
         key, sep, value = item.partition(":")
         if sep and re.fullmatch(r"[a-z_]+", key.strip()):
             # 只接受会落到页面的键：href 与 part 的文件形式。
@@ -153,6 +157,17 @@ def parse_chapters(quarto_yml: Path) -> list[str]:
     return chapters
 
 
+def collect_all_qmd(root: Path) -> list[Path]:
+    excluded = {"node_modules", "_book", ".quarto", ".git", "_freeze", "_site"}
+    found: list[Path] = []
+    for candidate in sorted(root.rglob("*.qmd")):
+        rel_parts = candidate.relative_to(root).parts
+        if any(part in excluded or part.startswith(".") for part in rel_parts):
+            continue
+        found.append(candidate)
+    return found
+
+
 def collect_chapter_files(root: Path, chapters: list[str]) -> list[Path]:
     found: list[Path] = []
     for rel in chapters:
@@ -164,15 +179,8 @@ def collect_chapter_files(root: Path, chapters: list[str]) -> list[Path]:
         found.append(index)
     if chapters:
         return found
-    # No chapter table: audit every tracked .qmd outside generated/vendor dirs.
-    excluded = {"node_modules", "_book", ".quarto", ".git", "_freeze", "_site"}
-    for candidate in sorted(root.rglob("*.qmd")):
-        rel_parts = candidate.relative_to(root).parts
-        if any(part in excluded or part.startswith(".") for part in rel_parts):
-            continue
-        if candidate not in found:
-            found.append(candidate)
-    return found
+    # No chapter table: audit every .qmd outside generated/vendor dirs.
+    return collect_all_qmd(root)
 
 
 def check_heading(path: Path, line: int, level: int, text: str, issues: list[Issue]) -> None:
@@ -425,6 +433,38 @@ def check_tree_block(path: Path, block: list[tuple[int, str]]) -> list[Issue]:
     return issues
 
 
+def check_html_figure_block(path: Path, block: list[tuple[int, str]]) -> list[Issue]:
+    """原生 HTML/SVG 图要用 <figure> 包住，<figcaption> 放在图后。"""
+    issues: list[Issue] = []
+    svg_line: int | None = None
+    figure_line: int | None = None
+    caption_line: int | None = None
+    for number, raw in block:
+        if "<figure" in raw and figure_line is None:
+            figure_line = number
+        if "<svg" in raw and svg_line is None:
+            svg_line = number
+            if figure_line is None:
+                issues.append(Issue(
+                    path, number,
+                    "原生 SVG 图要用 <figure> 包住，并在图后写 <figcaption>",
+                ))
+        if "<figcaption" in raw and caption_line is None:
+            caption_line = number
+    if svg_line is not None and figure_line is not None:
+        if caption_line is None:
+            issues.append(Issue(
+                path, svg_line,
+                "原生 SVG 图缺 <figcaption>（图注要落在图下）",
+            ))
+        elif caption_line < svg_line:
+            issues.append(Issue(
+                path, caption_line,
+                "<figcaption> 要放在图后，不能放在图前",
+            ))
+    return issues
+
+
 def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> list[Issue]:
     issues: list[Issue] = []
     text = read_text(path)
@@ -436,6 +476,10 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
     elif front and not parse_frontmatter_title(front):
         issues.append(Issue(path, 1, "frontmatter 缺少 title"))
 
+    # 保留 frontmatter 的行数，后续行号才是文件里的真实行号。
+    leading = text[: len(text) - len(body)] if body else ""
+    if leading:
+        body = "\n" * leading.count("\n") + body
     lines = body.splitlines()
     in_fence = False
     fence_lang = ""
@@ -443,8 +487,11 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
     fence_lines: list[tuple[int, str]] = []
     fence_blocks: list[list[tuple[int, str]]] = []
     mermaid_blocks: list[list[tuple[int, str]]] = []
+    html_blocks: list[list[tuple[int, str]]] = []
+    fence_is_html = False
     paragraph: list[str] = []
     paragraph_start = 0
+    last_fence_end: int | None = None
 
     def flush_paragraph() -> None:
         nonlocal paragraph
@@ -459,24 +506,35 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
             if not in_fence:
                 in_fence = True
                 fence_start = number
+                if last_fence_end is not None and number == last_fence_end + 1:
+                    issues.append(Issue(
+                        path, number,
+                        "相邻围栏之间至少留一个空行（DOC-E11）；空行不等于桥接正文",
+                    ))
                 fence_lang = (fence.group(2) or "").strip()
                 fence_lines = []
+                fence_is_html = False
                 if not fence_lang:
                     issues.append(Issue(path, number, "代码围栏未声明语言"))
                 elif fence_lang == "mermaid":
                     issues.append(Issue(path, number, "plain mermaid 围栏（改用 ```{mermaid}）"))
                 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:
                         # ```{python} style attribute fences are valid.
                         pass
             else:
                 in_fence = False
+                last_fence_end = number
                 if fence_lines:
                     fence_blocks.append(fence_lines)
                     if "mermaid" in fence_lang:
                         mermaid_blocks.append(fence_lines)
+                    if fence_is_html:
+                        html_blocks.append(fence_lines)
                     fence_lines = []
+                    fence_is_html = False
             continue
 
         if in_fence:
@@ -504,7 +562,12 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
             flush_paragraph()
             continue
 
-        if raw.lstrip().startswith((">", "|", "-", "*", "+", "1.")):
+        if raw.lstrip().startswith("|"):
+            flush_paragraph()
+            # 表格行按列组织，不套散文句长阈值；列数与表头一致性由表格检查负责。
+            continue
+
+        if raw.lstrip().startswith((">", "-", "*", "+", "1.")):
             flush_paragraph()
             check_prose_block(path, number, re.sub(r"^\s*(?:[>|]|[-*+]|\d+\.)\s*", "", raw), issues)
             continue
@@ -515,6 +578,9 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
 
     flush_paragraph()
 
+    if in_fence:
+        issues.append(Issue(path, fence_start, "代码围栏未闭合"))
+
     for block in fence_blocks:
         issues.extend(check_tree_block(path, block))
 
@@ -522,21 +588,41 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
         issues.extend(check_mermaid_block(path, block))
         issues.extend(check_mermaid_wrapper(path, lines, block))
 
+    for block in html_blocks:
+        issues.extend(check_html_figure_block(path, block))
+
+    fenced_lines: set[int] = set()
+    inside_fence = False
+    for number, raw in enumerate(lines, start=1):
+        if FENCE_RE.match(raw):
+            fenced_lines.add(number)
+            inside_fence = not inside_fence
+        elif inside_fence:
+            fenced_lines.add(number)
+
+    blob_links: dict[str, list[int]] = {}
+
     for index, raw in enumerate(lines, start=1):
-        match = LINK_RE.search(raw)
-        if not match:
+        if index in fenced_lines:
             continue
-        target = match.group(1).strip()
-        if target.startswith(("http://", "https://", "mailto:", "#", "data:")):
-            continue
-        clean = target.split("#", 1)[0].split("?", 1)[0]
-        if not clean or "<" in clean:
-            continue
-        if not (path.parent / clean).exists() and not (root / clean).exists():
-            issues.append(Issue(path, index, f"本地链接不可达：{target}"))
-
-    if text.count("```") % 2 != 0:
-        issues.append(Issue(path, len(lines), "代码围栏数量为奇数，存在未闭合围栏"))
+        for match in LINK_RE.finditer(raw):
+            target = match.group(1).strip()
+            if target.startswith(("http://", "https://", "mailto:", "#", "data:", "//")):
+                if target.startswith("https://github.com/") and "/blob/" in target:
+                    blob_links.setdefault(target, []).append(index)
+                continue
+            clean = target.split("#", 1)[0].split("?", 1)[0]
+            if not clean or "<" in clean:
+                continue
+            if not (path.parent / clean).exists() and not (root / clean).exists():
+                issues.append(Issue(path, index, f"本地链接不可达：{target}"))
+
+    for target, numbers in blob_links.items():
+        if len(numbers) > 1:
+            issues.append(Issue(
+                path, numbers[1],
+                f"同章重复文件链接：{target}（首次在第 {numbers[0]} 行）；每章每条仓库路径至多一条",
+            ))
 
     for term in GENERIC_FORBIDDEN_TERMS:
         for index, raw in enumerate(lines, start=1):
@@ -571,6 +657,24 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                 path, index,
                 f"自造关系词「{match.group(0)}」；用组成、调用、依赖、继承等通行词",
             ))
+        match = CARRIER_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                "类型或字段不用「承载」描述；改用表示、保存、记录或对应",
+            ))
+        match = NEXT_SECTION_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"小节导航「{match.group(0)}」；删除后用新节首句承接，章末预告保留",
+            ))
+        match = LADDER_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"拉链句「{match.group(0)}」；拆句或改成一项一行",
+            ))
 
     required = project.get("chapter_titles", {}).get(rel)
     if required:
@@ -605,6 +709,7 @@ def load_project(root: Path) -> tuple[bool, dict]:
 def main() -> int:
     parser = argparse.ArgumentParser(description="检查 Quarto Book 章节源码")
     parser.add_argument("--root", default=".", help="书根目录（默认当前目录）")
+    parser.add_argument("--paths", nargs="+", help="只检查这些 qmd 路径（相对 --root）")
     parser.add_argument("--strict", action="store_true", help="把未列入目录的文件也视为错误")
     parser.add_argument("--quiet", action="store_true", help="只输出汇总")
     args = parser.parse_args()
@@ -621,27 +726,52 @@ def main() -> int:
         return 2
 
     quarto_yml = root / "_quarto.yml"
-    chapters = parse_chapters(quarto_yml)
+    try:
+        chapters = parse_chapters(quarto_yml)
+    except (OSError, UnicodeDecodeError) as exc:
+        print(f"失败  读取目录表失败: {exc}")
+        return 1
     files = collect_chapter_files(root, chapters)
+    issues: list[Issue] = []
+    if args.paths:
+        requested: list[Path] = []
+        for raw in args.paths:
+            candidate = (root / raw).resolve()
+            if root not in candidate.parents and candidate != root:
+                issues.append(Issue(quarto_yml, 1, f"--paths 落在书根之外：{raw}"))
+            elif not candidate.is_file():
+                issues.append(Issue(candidate, 1, f"--paths 指定的文件不存在：{raw}"))
+            else:
+                requested.append(candidate)
+        files = requested
     if not files:
         print(f"失败  {root} 下没有 .qmd 章节（确认 --root 指向书根目录）")
         return 1
 
-    has_project, project = load_project(root)
+    try:
+        has_project, project = load_project(root)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        print(f"失败  读取项目规则失败: {exc}")
+        return 1
 
     missing = [rel for rel in chapters if not (root / rel).is_file()]
-    issues: list[Issue] = [
+    issues.extend([
         Issue(quarto_yml, 1, f"目录中的章节不存在：{rel}") for rel in missing
-    ]
+    ])
+
+    if args.strict:
+        extras = [item for item in collect_all_qmd(root) if item not in files]
+        for item in extras:
+            issues.append(Issue(item, 1, "未列入 _quarto.yml（strict 模式）"))
+        files.extend(extras)
 
     for path in files:
-        issues.extend(check_file(path, root, project, chapters))
+        try:
+            issues.extend(check_file(path, root, project, chapters))
+        except (OSError, UnicodeDecodeError) as exc:
+            issues.append(Issue(path, 1, f"无法按 UTF-8 读取：{exc}"))
 
-    if args.strict:
-        for issue in list(issues):
-            if "未列入 _quarto.yml" in issue.message:
-                issue.message = issue.message.replace("（目录会漏章）", "")
-    else:
+    if not args.strict:
         issues = [issue for issue in issues if "未列入 _quarto.yml" not in issue.message]
 
     if not args.quiet:

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

@@ -100,11 +100,12 @@ int main() {
 
 ### 代码与图的桥接
 
-代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，两条硬边界：
+代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，边界如下：
 
 - 代码块与图之间必须有桥接句，说明图要核对代码已讲清的哪条关系；中间只有空行视为堆叠（`verifying-content.py` 的 DOC-E11 只要求相邻围栏留空行，空行不等于桥接正文）。
 - 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见 `quarto/coords.md` 与本文件。
-- 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（三条边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
+- 图注与图前句分工：图注写图面内容与读法，落在图下；图前只写引出关系的一句，不写“下图标出……”这类图面说明。三类图（Mermaid、坐标图、原生 HTML/SVG）的写法见 `quarto/figures.md`。
+- 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（上述边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
 - 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式（「画面上方是列号」式会让读者翻回前章）；调用方行为等第二主题移出图前段（示例章定义坐标范围节两段并一段的改稿对照）。
 
 图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见 `examples/03-qmd-elements.md`「代码与图桥接对照」。
@@ -225,7 +226,7 @@ int main() {
 
 ### 情况：图是 Mermaid 或坐标轴图
 
-要画流程图、类图或时序图才打开 `quarto/mermaid.md`（类图先按内容预算删节点和成员），坐标轴网格图打开 `quarto/coords.md`。不排图不打开。
+要画流程图、类图或时序图才打开 `quarto/mermaid.md`（类图先按内容预算删节点和成员），坐标轴网格图打开 `quarto/coords.md`，图注与原生 HTML/SVG 图打开 `quarto/figures.md`。不排图不打开。
 
 ### 情况：Callout
 

package/skills/writing-quarto/steps/06-wording.md

@@ -31,6 +31,22 @@
 
 「只读」「只写」是读写性质的固定术语，保留；`const` 成员函数首次称「只读」时，写明它不改动对象。安全、协议或验收条件确实需要排他时，写成可核对的条件（「`PlaceCell` 在目标格子非空时返回 `false`」），不靠「只」承担论证。
 
+### 表示、保存、记录，不用「承载」
+
+读者正文不把类型或字段写成「承载」某个值。「承载」是抽象能力或文档职责的说法，套到 `struct`、`enum`、字段上会让读者分不清它表示什么、运行时保存什么。
+
+按对象选动词：
+
+- 类型表达概念：`CellPosition` **表示**一对行列，`CellType` **表示**格子里的取值。
+- 对象保存数据：`Board` 的 `cells_` **保存**九个 `CellType`。
+- 文件或协议留下记录：快照 **记录**落子次数、当前玩家和结果。
+- 名称与值对应：`kX` **对应** X 标记。
+
+- 不佳：坐标由 `CellPosition` 承载，取值由 `CellType` 承载。
+- 改写：`CellPosition` 表示一对行列，`CellType` 表示格子里的取值。
+- 不佳：这份配置承载三个字段。
+- 改写：这份配置保存三个字段。
+
 ### 读者正文禁无信息提问与自造关系词
 
 读者正文不向读者发问。没有任务指向的提问（「总览图为什么不列成员？」「这条边表示什么？」）只是把作者自检提纲搬进正文，删掉后读者仍能拿到同样信息；需要读者判断的内容改写为陈述句，或放进自测。
@@ -100,6 +116,7 @@
 - 动词选用与主动语态见「目标语气」；「由 X 完成」在这一步改成主动句，改完露出第二个核就退回定段落。
 - 「同一概念只使用一个称呼」的判定见「七个质量维度」；英文标识保持大小写。
 - 「游戏」指作品或玩法整体，「对局」指具体一场：定义「井字棋是…游戏」用「游戏」，规则、落子与结果语境用「对局」；同一页不把两者当同义词换用（对照见 `examples/06-wording-cases.md`「游戏与对局」）。
+- 项目名在同一页首次写全（如「井字棋棋盘」），后文改用对象名（「棋盘」「动态库」「对局」）；不逐段重复项目名，也不在同一页反复解释已经说过的事。
 - 无信息修饰的删除判定见「七个质量维度」；禁用词以 `scripts/verifying-content.py` 词表为准。
 - 压缩动词写全：`重建`、`重编`、`重跑` 这类两字词，读者可能读成「重新创建」；写「重新生成」「重新编译」「重新运行」，同一页后续也不回退到压缩词。
 - 连续出现三个「的」时的改写判定见「七个质量维度」第 5 条。