biaodian: review Chinese punctuation with cited explanations

# 中文标点校对 ## 标准依据与边界 本工具的依据是 **GB/T 15834-2011《标点符号用法》**（2011-12-30 发布，2012-06-01 实施，现行；全部代替 GB/T 15834-1995，主管部门教育部）。它规定了现代汉语 17 种标点符号的定义、形式、基本用法、位置和书写形式，并用规范性附录 A（补充规则，主要说明“不能这样用”）和资料性附录 B（易混标点辨析）解决争议。标准原文与状态见[国家标准全文公开系统](https://openstd.samr.gov.cn/bzgk/std/newGbInfo?hcno=22EA6D162E4110E752259661E1A0D0A8)与[全国标准信息公共服务平台](https://std.samr.gov.cn/gb/search/gbDetailedCNF?id=71F772D7FE25D3A7E05397BE0A0AB82A)。 > 说明：常被写错的 `GB/T 15843-2011` 并不存在；标点符号的现行国标号是 **GB/T 15834-2011**。本工具一律以后者为准。 本工具只处理标点符号这一层，**不改文意、不改词语、不改数字、不改行文风格**。标点之外的错别字、语法、事实问题不在职责范围内；确有必要时只在报告末尾“附近提示”中一句话点出，不展开。标准是推荐性国标，个别用法（如并列引号之间用不用顿号）存在允许的弹性空间，遇到这类情况只作“建议”、不判“错误”。 ## 工具定位 中文标点，日常写、日常读，绝大多数人不成问题。本工具服务两类人：一类是想把标点学明白的人（不限学生）；另一类是工作上对文字较真、不能出错的人（体制内材料、媒体、出版、小说写作等）。对他们，本工具做三件事： 1. **先机械扫描**：全半角混用、中英文标点混排、省略号与破折号写法、重复/叠用标点、引号括号书名号配对、顿号误用于概数、序次语后标点、标点前后空格等，用脚本一次性列全，避免遗漏。 2. **再语义复核**：脚本查不出的“用错了但形式合法”的问题——句号/问号/叹号的语气判断、顿号/逗号/分号/冒号的层次与节奏、引号内外的句末点号位置、“说/道”后的点号、破折号与括号的分工、书名号的适用范围，由模型按判定矩阵逐条过。 3. **给依据、给案例**：每一处修改都落到国标条款号；凡是官媒已经公开讲过的类型，附上人民日报、新华社、央视等的原文案例与出处链接，让用户明白“为什么错、为什么这样改”。 ## 工作流 ### 第 1 步：跑机械扫描 ```bash node scripts/lint_punctuation.mjs --input 待检文本.md --format text # 需要结构化结果时： node scripts/lint_punctuation.mjs --input 待检文本.md --format json # 直接给一段文字： node scripts/lint_punctuation.mjs --text "待检的一句话，" ``` 脚本把问题分成三档：`error`（明确违规，应当修改）、`warn`（大概率该改）、`review`（需结合语境判断，交模型复核）。脚本只报位置和候选依据，不改文本。若环境无法运行 Node，按 @references/detection-flow.md 第 1 节的机械规则逐项手查。 ### 第 2 步：读知识库 - @references/gbt15834-2011-summary.md：国标执行摘要（17 种标点的形式与用法、位置与书写形式、附录 A 补充规则、附录 B 辨析要点）。 - @references/gbt15834-audit-matrix.md：逐条判定矩阵——条款 → 判定条件 → 常见误用 → 自动/人工。 - @references/confusable-pairs.md：易混标点对照（逗/顿/分/冒、引号内外、括号内外、破折号 vs 括号、省略号 vs “等”）。 - @references/official-cases.md：官方案例库，每条含“误→正 + 出处 + 链接”。 ### 第 3 步：语义复核 按 @references/detection-flow.md 的顺序通读全文，逐条应用判定矩阵。顺序为：**句末点号（语气）→ 句内点号（层次与节奏）→ 标号（配对、位置、范围）→ 连用规则 → 书写形式**。凡是脚本已报的项，只做确认或降级，不重复计数。 ### 第 4 步：产出报告 严格按 @references/report-template.md 的三段式输出，缺一不可： 1. **问题清单**：哪里错了、正确的应该是什么； 2. **逐处说明与官方案例科普**：为什么错、为什么这样改，附国标条款与官方案例； 3. **修正全文**：可直接替换的干净版本。 ### 第 5 步：交付前自检 - 每一处“错误”都能指到国标条款或官方案例；指不到的，降级为“建议”。 - 官方案例只从 @references/official-cases.md 取，**不得编造案例、出处或链接**。 - 不把“可选/弹性”的用法写成“错误”（如并列引号之间的顿号、文末句号的取舍）。 - 不因改标点而改动原文字词、语序、数字写法。 ## 报告原则（重要） - **先给结论，再给证据**：开头一句讲清“共几处、严重程度如何、最要紧的是哪处”。 - **一一对应**：清单里的第 N 条，必须在第 2 部分有同编号的解释与案例。 - **说人话**：解释用大白话讲清语气和停顿的差别，不堆术语；术语首次出现时给中文名。 - **有官方依据才“科普”**：讲“为什么”时优先引用国标示例与官媒案例原话，注明媒体、篇名与日期。 - **不越界**：只谈标点；文意、用词、事实问题不在报告主体中出现。 ## 验证 ```bash # 快速自检（任意环境都能跑，不依赖测试件） node scripts/lint_punctuation.mjs --text "待检的一句话，" # 完整测试套件（源码仓库自带；分发/上架包中不含 tests/，不影响使用） node scripts/lint_punctuation.mjs --input tests/fixtures/bad-sample.md --format text bash tests/run_tests.sh ``` `tests/run_tests.sh` 用内置样例验证脚本能找到预期问题类型、且不误报干净文本。语义类判定（语气、层次、引号内外点号）无法由脚本自动证明，须由模型对照 @references/official-cases.md 复核。 ## 输出说明 - 报告须写明依据标准：`GB/T 15834-2011《标点符号用法》`。 - 存在弹性空间或需作者定夺的，单列“可商榷”小节，不与“错误”混排。