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

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

@@ -4,6 +4,7 @@
 The checks encode the writing-quarto conventions: one chapter table in
 `_quarto.yml`, YAML titles instead of a body H1, ##/### heading depth, short
 paragraphs and sentences, declared code-fence languages, `{mermaid}` fences,
+class-diagram content budgets, directory-tree annotation columns and markers,
 and no placeholder text left in the prose.
 
 Project-specific rules are optional. If the book has
@@ -31,6 +32,7 @@ import argparse
 import json
 import re
 import sys
+import unicodedata
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -46,6 +48,30 @@ CHAPTER_NUMBER_RE = re.compile(r"第\s*\d+\s*章")
 PLACEHOLDER_RE = re.compile(r"^\s*TODO|待补|待定|TBD", re.IGNORECASE)
 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({
+    "头文件", "源文件", "源码", "实现", "测试", "配置文件",
+    "构建脚本", "构建规则", "动态库", "可执行文件",
+})
+MAX_TREE_LINES = 20
+MAX_TREE_COMMENT_WIDTH = 28
+MAX_TREE_DIR_COMMENT_WIDTH = 16
+MIN_TREE_GAP = 4
+
+# 类图的内容预算。数字是版面判断，不是浏览器实测：正文栏约 840 px、字号
+# 15 px 时，6 个类型、14 行成员、单行 40 列仍能在栏内排下；超过就删内容或拆图。
+MAX_CLASS_DIAGRAM_TYPES = 6
+MAX_CLASS_DIAGRAM_MEMBERS = 14
+MAX_CLASS_MEMBERS = 5
+MAX_CLASS_MEMBER_COLUMNS = 40
+CLASS_RE = re.compile(r"^class\s+([A-Za-z_]\w*)\s*(\{)?")
+
 HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*$")
 HEADING_PERSONAL_RE = re.compile(r"自己|咱们|我们|你|您|跟我|试试|来看")
 FENCE_RE = re.compile(r"^\s*(```+|~~~+)\s*(\{[^}]*\}|[^\s`]*)?")
@@ -66,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]:
@@ -116,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 的文件形式。
@@ -130,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:
@@ -141,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:
@@ -188,6 +219,252 @@ def check_prose_block(path: Path, start_line: int, text: str, issues: list[Issue
                 break
 
 
+def display_width(text: str) -> int:
+    return sum(2 if unicodedata.east_asian_width(char) in {"W", "F"} else 1 for char in text)
+
+
+def check_mermaid_block(path: Path, block: list[tuple[int, str]]) -> list[Issue]:
+    """Check a class diagram's content budget and direction."""
+    diagram_at = next((index for index, (_, raw) in enumerate(block) if "classDiagram" in raw), None)
+    if diagram_at is None:
+        return []
+
+    issues: list[Issue] = []
+    start_line = block[diagram_at][0]
+    text = "\n".join(raw for _, raw in block)
+    if "hideEmptyMembersBox" not in text:
+        issues.append(Issue(
+            path, start_line,
+            "类图块首缺少 hideEmptyMembersBox 配置；空类会画出空成员栏",
+        ))
+    caption_at = next(
+        (index for index, (_, raw) in enumerate(block) if raw.lstrip().startswith("%%| fig-cap:")),
+        None,
+    )
+    init_at = next(
+        (index for index, (_, raw) in enumerate(block) if raw.lstrip().startswith("%%{init")),
+        None,
+    )
+    if caption_at is None:
+        issues.append(Issue(
+            path, start_line,
+            "类图缺少 fig-cap 图注；线型与读图约定应写在图注里",
+        ))
+    elif init_at is not None and caption_at > init_at:
+        issues.append(Issue(
+            path, block[caption_at][0],
+            "fig-cap 必须写在 init 之前；写在 init 之后会原样渲染成 Mermaid 注释",
+        ))
+
+    classes: dict[str, list[tuple[int, str]]] = {}
+    order: list[str] = []
+    direction = ""
+    direction_line = start_line
+    current: str | None = None
+    for number, raw in block[diagram_at:]:
+        line = raw.strip()
+        if not line or line.startswith("%%"):
+            continue
+        if line.startswith("direction "):
+            direction = line.split(None, 1)[1].strip().upper()
+            direction_line = number
+            continue
+        match = CLASS_RE.match(line)
+        if match:
+            name = match.group(1)
+            if name not in classes:
+                classes[name] = []
+                order.append(name)
+            current = name if "{" in line else None
+            continue
+        if current is None:
+            continue
+        if line == "}":
+            current = None
+            continue
+        if line.startswith("<<") and line.endswith(">>"):
+            continue
+        classes[current].append((number, line))
+
+    total_members = sum(len(lines) for lines in classes.values())
+    if len(order) > MAX_CLASS_DIAGRAM_TYPES:
+        issues.append(Issue(
+            path, start_line,
+            f"类图有 {len(order)} 个类型，超过 {MAX_CLASS_DIAGRAM_TYPES} 个；删节点或拆图",
+        ))
+    if total_members > MAX_CLASS_DIAGRAM_MEMBERS:
+        issues.append(Issue(
+            path, start_line,
+            f"类图成员共 {total_members} 行，超过 {MAX_CLASS_DIAGRAM_MEMBERS} 行；只留本章连边要用的成员",
+        ))
+    for name in order:
+        members = classes[name]
+        if len(members) > MAX_CLASS_MEMBERS:
+            issues.append(Issue(
+                path, members[MAX_CLASS_MEMBERS][0],
+                f"类 {name} 有 {len(members)} 行成员，超过 {MAX_CLASS_MEMBERS} 行；删到本章要用的",
+            ))
+        for number, line in members:
+            width = display_width(line)
+            if width > MAX_CLASS_MEMBER_COLUMNS:
+                issues.append(Issue(
+                    path, number,
+                    f"类图成员行 {width} 列，超过 {MAX_CLASS_MEMBER_COLUMNS} 列；参数省略类型名",
+                ))
+    if direction == "LR" and total_members:
+        issues.append(Issue(
+            path, direction_line,
+            "类图有成员却用 LR；改成 TB，让类型上下排",
+        ))
+    return issues
+
+
+def check_mermaid_wrapper(path: Path, lines: list[str], block: list[tuple[int, str]]) -> list[Issue]:
+    """Check a class diagram sits in the .class-diagram scroll container."""
+    if not any("classDiagram" in raw for _, raw in block):
+        return []
+    start = block[0][0]
+    index = start - 2
+    if 0 <= index < len(lines) and lines[index].lstrip().startswith("```"):
+        index -= 1
+    while index >= 0 and not lines[index].strip():
+        index -= 1
+    if index < 0 or ".class-diagram" not in lines[index]:
+        return [Issue(
+            path, start,
+            "类图缺少 .class-diagram 包裹；无法应用类图的宽度与居中规则",
+        )]
+    return []
+
+
+def check_tree_block(path: Path, block: list[tuple[int, str]]) -> list[Issue]:
+    """Check tree glyph lines: size, marker, width, items, and two marker columns."""
+    tree_lines = [(number, raw) for number, raw in block if "├──" in raw or "└──" in raw]
+    if len(tree_lines) < 2:
+        return []
+    issues: list[Issue] = []
+    if len(tree_lines) > MAX_TREE_LINES:
+        issues.append(Issue(
+            path, tree_lines[0][0],
+            f"树有 {len(tree_lines)} 行，超过 {MAX_TREE_LINES} 行；只留本章会点名的文件",
+        ))
+    dirs: list[tuple[int, int]] = []
+    files: list[tuple[int, int]] = []
+    text_columns: list[tuple[int, int]] = []
+    for number, raw in tree_lines:
+        hash_index = raw.find("#")
+        if hash_index < 0:
+            issues.append(Issue(path, number, "树行缺少行尾注释"))
+            continue
+        prefix = raw[:hash_index]
+        entry = prefix.rstrip()
+        if display_width(prefix) - display_width(entry) < MIN_TREE_GAP:
+            issues.append(Issue(path, number, "节点与注释之间至少留四个空格"))
+        rest = raw[hash_index:]
+        marker = "#/" if rest.startswith("#/") else "#"
+        after = rest[len(marker):]
+        if not after.startswith(" ") or (len(after) > 1 and after[1] == " "):
+            issues.append(Issue(path, number, "标记后只留一个空格"))
+        is_directory = entry.endswith("/")
+        if is_directory and marker != "#/":
+            issues.append(Issue(path, number, "目录行的注释以 #/ 开头"))
+        if not is_directory and marker == "#/":
+            issues.append(Issue(path, number, "文件行的注释以 # 开头"))
+        comment = after.strip()
+        if not comment:
+            issues.append(Issue(path, number, "树行注释为空"))
+            continue
+        if is_directory:
+            if "：" in comment or ":" in comment:
+                issues.append(Issue(
+                    path, number,
+                    "目录注释只写这里装什么，不加冒号或子项职责",
+                ))
+            if "、" in comment:
+                issues.append(Issue(
+                    path, number,
+                    "目录注释不列清单，用名词短语",
+                ))
+            if display_width(comment) > MAX_TREE_DIR_COMMENT_WIDTH:
+                issues.append(Issue(
+                    path, number,
+                    f"目录注释 {display_width(comment)} 列，超过 {MAX_TREE_DIR_COMMENT_WIDTH} 列；只留名词短语",
+                ))
+        else:
+            if display_width(comment) > MAX_TREE_COMMENT_WIDTH:
+                issues.append(Issue(
+                    path, number,
+                    f"注释 {display_width(comment)} 列，超过 {MAX_TREE_COMMENT_WIDTH} 列；缩成短名词短语",
+                ))
+            elif comment.rstrip("：:") in TREE_CATEGORY_COMMENTS:
+                issues.append(Issue(path, number, f"注释只写类别词「{comment}」；写对象与用途"))
+            separators = comment.count("、") + len(re.findall(r"(?<!参)与", comment))
+            if separators > 1:
+                issues.append(Issue(
+                    path, number, f"注释列了 {separators + 1} 项；压到 1 到 2 项",
+                ))
+        column = display_width(prefix)
+        if is_directory:
+            dirs.append((number, column))
+        else:
+            files.append((number, column))
+        text_columns.append((number, column + len(marker) + len(after) - len(after.lstrip(" "))))
+    if dirs:
+        dir_column = dirs[0][1]
+        if any(column != dir_column for _, column in dirs[1:]):
+            issues.append(Issue(path, dirs[0][0], "目录 #/ 未对齐"))
+        for number, column in files:
+            if column != dir_column + 1:
+                issues.append(Issue(
+                    path, number,
+                    f"文件 # 应比目录 # 右移一列（目录在 {dir_column}，文件在 {column}）",
+                ))
+                break
+    elif files:
+        file_column = files[0][1]
+        if any(column != file_column for _, column in files[1:]):
+            issues.append(Issue(path, files[0][0], "文件 # 未对齐"))
+    if text_columns:
+        text_column = text_columns[0][1]
+        for number, column in text_columns[1:]:
+            if column != text_column:
+                issues.append(Issue(path, number, "注释文字未对齐"))
+                break
+    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)
@@ -199,12 +476,22 @@ 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 = ""
     fence_start = 0
+    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
@@ -219,23 +506,41 @@ 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:
             if "\t" in raw:
                 issues.append(Issue(path, number, "代码含制表符（改用空格）"))
+            fence_lines.append((number, raw))
             continue
 
         heading = HEADING_RE.match(raw)
@@ -257,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
@@ -268,21 +578,51 @@ 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))
+
+    for block in mermaid_blocks:
+        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:
-            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:
+        if index in fenced_lines:
             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):
@@ -296,6 +636,46 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                 issues.append(Issue(path, index, f"项目禁用词「{term}」"))
                 break
 
+    for index, raw in enumerate(lines, start=1):
+        if raw.lstrip().startswith(("```", "    ")):
+            continue
+        match = QA_PROSE_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"问答式讲解「{match.group(0)}」；改成返回值、判断结果或直接陈述",
+            ))
+        match = CODE_META_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"代码字面复述「{match.group(0)}」；改成围栏没给出的行为或约束",
+            ))
+        match = COINED_RELATION_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                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:
         title = parse_frontmatter_title(front)
@@ -329,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()
@@ -345,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: