cn-linebreak

dsh plugin --profile web add cn-linebreak

cn-linebreak




中文网页文案断行审查与修复工具。把《[中文网页文案断行修复指南](docs/GUIDE.md)》中的规则变成可执行检查：

• 审查：检查显式断行错误及高风险写法——由 <br> 形成的孤字行、"一个字+标点"单独成行、行首/行尾出现禁则标点、缺少 word-break: keep-all、覆盖文本元素的全局 white-space: nowrap、过长 .no-break、长文案零换行点、保护词被换行拆开等。
• 修复：在 ，。；：、 等自然停顿处自动插入 <wbr>（跳过 script/style/pre/code/textarea/title 与 .no-break 保护区域、保护词典命中位置），产出修复版 HTML 供人工复核。
• DSH 插件：同一个包也是 DeepSeek Harness 标准插件包（dsh.bundle），安装后代理可直接调用 cn_linebreak_audit 工具。

能力边界：本工具是静态审查器，只能看到 HTML 中已明确存在的 <br>/<wbr> 和文本/CSS 结构。它不能知道浏览器按真实字号、容器宽度渲染后的实际换行结果——"识别真实渲染后的孤字行"与"识别浏览器自动切开的词组"属于路线图 v0.4.0 的渲染模式能力，详见 [docs/RULES.md](docs/RULES.md)。

核心原则（摘自指南）：中文断行不应由浏览器按单字随机决定；应先划分语义单元，再明确"可断、必断、不可断"三类边界。<wbr> = 可断，<br> = 必断，.no-break = 不可断。

Overview (English)

cn-linebreak is a static HTML auditor for Chinese line-breaking. It checks

explicit-<br> orphan lines, word-break: keep-all CSS coverage, CJK

line-start/line-end punctuation rules (CLReq / GB-T 15834), protected-phrase

splits, and long copy with no break points. In --fix mode it inserts <wbr>

at natural punctuation boundaries for human review. The same package is a

DeepSeek Harness plugin

exposing a cn_linebreak_audit tool.

*Static-only: it cannot see the browser's rendered line boxes. Detecting real

rendered orphan lines is roadmap v0.4.*

零依赖，纯 JavaScript（CommonJS + 一个 ESM 插件入口），Node ≥ 18。

快速开始

# 审查一个文件
npx cn-linebreak page.html

# 审查并输出修复版 HTML（stdout），摘要走 stderr
npx cn-linebreak --fix page.html > page.fixed.html

# 完整 JSON 报告
npx cn-linebreak --json page.html

# 从 stdin 读取
cat page.html | npx cn-linebreak

CLI

cn-linebreak [options] [<file.html> | -]
cat page.html | cn-linebreak [options]

选项 · 作用

--fix · 审查并把修复后 HTML 输出到 stdout；审查摘要与修复后复审结果输出到 stderr（不污染重定向）

--json · 输出完整 JSON 报告（ok / summary / issues / css / stats / fixedHtml）

--output <file> · 把结果写入文件（--fix 写修复后 HTML；否则写报告），stdout 保持干净

--strict · 警告也视为失败（影响退出码）

--config <file> · 读取 JSON 配置（见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)）

--help / --version · 帮助 / 版本

退出码：0=通过，1=发现错误（--strict 时含警告），2=参数错误，3=读取/解析失败。

API

const { auditHtml } = require('cn-linebreak')

const report = auditHtml('<p>读产品手册，提取事实，输出文档。</p>', { mode: 'fix' })

console.log(report.ok)        // false（有错误时）
console.log(report.summary)   // 一句话结论
console.log(report.issues)    // [{ severity, rule, where, message, suggestion }]
console.log(report.fixedHtml) // 修复版 HTML（仅 mode: 'fix' 时）

低层函数：insertWbr(html, { config })、auditCss(html)、collectElements(html)、normalizeConfig(config)、buildProtectedSpans(html, phrases)。

在 DeepSeek Harness (DSH) 中使用

本包声明了 dsh.bundle，是一个标准 DSH 插件包：

dsh plugin --profile <name> add cn-linebreak          # 从 npm
# 或从源码/GitHub：
dsh plugin --profile <name> add github:chiang21fcb/cn-linebreak

安装后插件注册工具 cn_linebreak_audit（参数 html + mode: audit|fix），代理可直接调用。可选的插件配置（通过 profile 的 cordis.patch.yml 覆盖 cn-linebreak 行的 config.engine）：

- id: cn-linebreak
  name: cn-linebreak/plugin
  config:
    engine:
      protectedPhrases: ["产品培训专员", "cordis.yml"]
      minCjkLength: 16

检查规则清单

规则 · 严重度 · 说明

missing-keep-all · 错误 · <style> 中没有任何 word-break: keep-all

keep-all-partial · 警告 · 有 keep-all，但其选择器未覆盖 h1/h2/p 等文本元素

keep-all-without-overflow-wrap · 警告 · keep-all 缺少 overflow-wrap: break-word 兜底，长文本可能溢出容器

broad-nowrap · 错误 · white-space: nowrap 覆盖文本元素（.no-break 作用域不算）

orphan-line · 错误/警告 · <br> 产生的整行只有一两个字 + 句号（孤字行）

line-start-punctuation · 错误 · 行首出现闭式标点（CLReq/GB-T 15834 禁则）

line-end-punctuation · 错误 · 行尾出现开式标点（CLReq/GB-T 15834 禁则）

protected-phrase-split · 错误 · 配置的保护词被 <br> 拆开

missing-css-guard · 警告 · 页面没有 <style> 全局断行保护

missing-line-break-strict · 警告 · 缺少 line-break: strict

no-breakpoint · 警告 · 较长中文文案（默认 ≥16 汉字）没有任何 <wbr>/<br> 换行点

overlong-no-break · 警告 · .no-break 内内容过长（>14 汉字）

leading-punctuation · 警告 · 元素文本以标点开头（可能是上一处断行挤下来的）

text-wrap-only · 提示 · 仅依赖 text-wrap: pretty/balance，浏览器兼容性不稳定

fix-applied · 提示 · 修复模式下插入了多少处 <wbr>

为什么不用纯 CSS 解决

text-wrap: pretty、text-wrap: balance、word-break: auto-phrase 都可以辅助排版，但不同浏览器、版本和字号下结果不稳定。对于演示稿、落地页、数据大屏这类对断句节奏要求高的页面，应由文案作者明确指定换行点——这正是本工具帮你标注的。

局限与人工复核

• 静态检查无法感知真实渲染宽度；"孤字"等布局问题只能通过显式 <br> 可靠识别，其余为启发式提示。
• --fix 只做保守的机械插入：任何语义边界（产品名、专有名词、引号内完整名称）都需要人工复查；可通过 --config 的保护词典减少误插。
• 规则来源与演进路线见 [docs/SOURCES.md](docs/SOURCES.md)、[docs/RULES.md](docs/RULES.md)；配置项说明见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。

开发

npm test          # node --test（54 个用例）
npm pack --dry-run

License

MIT © chiang21fcb