![](\"https://avatars.githubusercontent.com/u/59811714\")
\n \n\n \n
让中文 Markdown 写作更规范、更一致。
\n\nLint your Chinese Markdown for cleaner, more consistent writing.
\n\nlint-md/core 是 lint-md 体系中的规则引擎核心，专注解决中文 Markdown 在团队协作中的一致性问题。它基于 AST 执行规则检查与自动修复，适用于文档、博客、知识库等长期维护场景。\n\n[](https://github.com/lint-md/lint-md)\n[](https://www.npmjs.com/package/@lint-md/core)\n[](https://www.npmjs.com/package/@lint-md/core)\n[](https://github.com/lint-md/lint-md/blob/master/LICENSE)\n[](https://github.com/lint-md/lint-md/actions/workflows/build.yml)\n\n## ✨ 特性\n\n- **专注中文 Markdown 规范**：围绕中文写作场景设计规则与自动修复能力。\n- **规则可配置、可扩展**：支持按规则粒度配置等级与参数，也支持扩展规则。\n- **高性能处理能力**：4 vCPU 环境下，处理 1000 篇文档耗时 4s 内。\n- **生态封装完善**：可接入 CLI、Prettier、ESLint、VSCode，也欢迎按业务场景继续封装。\n\n## 🏗️ 架构原则\n\ncore 遵循「纯引擎 + 薄适配器」设计：\n\n- **core 零 I/O**：只接受字符串入参，返回结构化数据，不读写文件、不直接输出到终端\n- **集成做 I/O**：CLI、编辑器插件等适配器只负责输入输出和格式转换，不包含规则逻辑\n- **标准诊断**：`LintDiagnostic` 统一诊断格式，core 提供格式转换器（`toALEOutput`），适配器无需自行实现映射\n\n### SourceCode 范围\n\n每次 lint 执行创建一个 `SourceCode` 实例。\n规则通过 `context.sourceCode` 读取原文和 AST。\n规则也通过该实例转换文本范围。\n\n```ts\nconst range = context.sourceCode.getTextRange(node, start, end);\n\ncontext.report({\n range,\n message: '发现不规范文本'\n});\n```\n\n所有范围使用 JavaScript UTF-16 索引。\n范围采用 `[start, end)` 语义。\n`TextRange` 是只读的二元组。\n\n无效范围会抛出 `InvalidRuleRangeError`。\n映射缺失会抛出 `SourceMapUnavailableError`。\n节点被修改后，映射会抛出 `SourceMapConsistencyError`。\n映射错误不会进入 `executionErrors`。\n\n## 🚀 快速使用\n\nCore 提供明确的修复 API：`fixMarkdown`。\n\n```ts\nfixMarkdown(\n markdown: string,\n options?: {\n rules?: LintMdRulesConfig,\n ruleErrorPolicy?: 'collect' | 'strict'\n }\n)\n```\n\n`rules` 配置本次修复使用的规则。\n`ruleErrorPolicy` 配置规则执行失败策略。\n\n`fixMarkdown()` 返回 `LintMdFixResult`。\n其中 `lintResult` 描述原始输入。\n`fixedResult.result` 包含最终修复文本。\n\n现有 `lintMarkdown` API 保持兼容：\n\n```ts\nlintMarkdown(\n markdown: string,\n rules?: LintMdRulesConfig,\n isFixMode?: boolean,\n options?: LintExecutionOptions\n)\n```\n\n参数说明：\n\n| 参数 | 说明 |\n| --- | --- |\n| `markdown` | 要检查的 Markdown 字符串 |\n| `rules` | 规则配置，默认 `{}` |\n| `isFixMode` | 是否开启自动修复，默认 `true` |\n| `options.ruleErrorPolicy` | 规则执行失败策略：默认 `'collect'` 返回部分结果及错误；`'strict'` 首次失败即抛出 `RuleExecutionFailure` |\n\n返回结果：\n\n- `lintResult`：命中规则后的诊断结果列表（含规则名、位置信息、消息、级别）\n- `diagnostics`：标准诊断格式列表（`LintDiagnostic[]`），供编辑器集成直接消费\n- `fixedResult`：开启修复模式时返回 `{ result, notAppliedFixes }`（`result` 为修复后的文本，`notAppliedFixes` 为因冲突等原因未能应用的修复项），否则为 `null`\n- `executionErrors`：规则执行失败的结构化列表。非空时，`diagnostics` 与 `lintResult` 可能只是部分结果；CLI 和编辑器 Adapter 应据此标记本次检查不完整。\n\nIn fix mode, `lintResult`, `diagnostics`, and both fixable counts describe the original Markdown.\n`fixedResult.result` contains the final Markdown.\n`fixedResult.notAppliedFixes` uses coordinates from the final relevant fix round.\n`executionErrors` aggregates failures from all fix rounds.\n`fixedResult.convergence`, `rounds`, and `metrics` describe the complete fix process.\nDo not apply original diagnostic positions to `fixedResult.result`.\n\n### Unapplied fix contract\n\nEach `notAppliedFixes` item contains these fields:\n\n- `range`: The range is relative to the input of the final fix round.\n- `text`: The replacement text.\n- `targetRule`: The source `rule.meta.name`.\n- `reason`: A stable conflict code.\n\nThe range is not necessarily relative to the returned `result`.\nThe `reason` value is `overlap` or `same-offset`.\n`overlap` means that the fix starts inside an applied range.\n`same-offset` means that an earlier insertion owns the same offset.\nThe result contains only conflicts from the final fix round.\nThe new `targetRule` and `reason` fields use JSON-compatible strings.\nThe optional `data` field remains rule-defined.\nThe API does not guarantee that `data` supports JSON serialization.\n\n下面是一个最小示例，可直接作为接入起点：\n\n```ts\nimport { fixMarkdown } from '@lint-md/core';\n\nconst markdown = '中文English 123';\n\nconst result = fixMarkdown(markdown, {\n rules: {\n 'space-around-alphabet': 2,\n 'space-around-number': 2,\n 'no-long-code': [1, { length: 100, exclude: [] }],\n 'require-trailing-spaces': 2,\n 'space-around-link': 2,\n 'no-multiple-blank-lines': 2\n }\n});\n\nconsole.log(result.lintResult);\nconsole.log(result.fixedResult.result);\n```\n\n```ts\n// 使用标准诊断格式接入编辑器（如 Vim/Neovim ALE）\nimport { lintMarkdown, toALEOutput } from '@lint-md/core';\n\nconst result = lintMarkdown('中文English 123', {}, false);\nconsole.log(toALEOutput(result.diagnostics, 'test.md'));\n// test.md:1:3: E space-around-alphabet: 中英文之间需要添加空格\n// test.md:1:12: W space-around-number: 中文与数字之间需要添加空格\n```\n\n集成层应在消费 diagnostics 前检查执行错误；默认 `'collect'` 保留可用的部分结果，适合\n交互式编辑器。需要快速失败的 CI 可显式启用 strict 模式：\n\n```ts\nconst result = lintMarkdown(markdown, rules, false);\n\nif (result.executionErrors.length > 0) {\n // 标记本次 lint 结果不完整，并按 Adapter 的策略记录或设置退出码。\n}\n\nlintMarkdown(markdown, rules, false, {\n ruleErrorPolicy: 'strict'\n}); // 首次规则执行失败即抛出 RuleExecutionFailure\n```\n\n`no-long-code` 的 `exclude` 用于排除指定代码语言（如 `['dot', 'mermaid']`）的长度检查。\n\n## 📏 书写规则列表\n\n目前内置 20 个规则，覆盖大部分的中文规则。\n\n| 规则名 | 说明 | 可配置 | 可修复 |\n| --- | --- | --- | --- |\n| `space-around-alphabet` | 中文与英文之间需要空格 | 否 | 是 |\n| `space-around-number` | 中文与数字之间需要空格 | 否 | 是 |\n| `no-empty-code-lang` | 代码块语言不能为空 | 否 | 是 |\n| `no-empty-url` | 链接/图片地址不能为空 | 否 | 是 |\n| `no-empty-list` | 列表项内容不能为空 | 否 | 是 |\n| `no-empty-code` | 代码块内容不能为空 | 否 | 是 |\n| `no-empty-inline-code` | 行内代码内容不能为空 | 否 | 是 |\n| `no-empty-blockquote` | 引用块内容不能为空 | 否 | 是 |\n| `no-special-characters` | 文本中不能有特殊字符 | 否 | 是 |\n| `use-standard-ellipsis` | 使用标准省略号 | 否 | 是 |\n| `no-full-width-number` | 不能使用全角数字 | 否 | 是 |\n| `no-space-in-link` | 链接内容前后不能有空格 | 否 | 是 |\n| `no-multiple-space-blockquote` | 引用头部和内容间只能有一个空格 | 否 | 是 |\n| `correct-title-trailing-punctuation` | 标题末尾标点需合法 | 否 | 是 |\n| `no-space-in-inline-code` | 行内代码内容前后不能有空格 | 否 | 是 |\n| `no-long-code` | 代码块行长度不能超过限制 | 是 | 否 |\n| `no-half-width-punctuation` | 中文语境下应使用全角标点符号 | 否 | 是 |\n| `require-trailing-spaces` | 软换行前需要两个空格 | 否 | 是 |\n| `space-around-link` | 链接与正文之间需要空格 | 否 | 是 |\n| `no-multiple-blank-lines` | 连续空白行最多保留一行 | 否 | 是 |\n\n`require-trailing-spaces`、`space-around-link` 和 `no-multiple-blank-lines` 默认关闭。\nCLI 用户可以在项目根目录的 `.lintmdrc` 中启用这些规则：\n\n| 规则级别 | 含义 |\n| --- | --- |\n| `0` | 关闭规则 |\n| `1` | 生成警告 |\n| `2` | 生成错误 |\n\n下面的示例将三条规则设置为错误级别：\n\n```json\n{\n \"rules\": {\n \"require-trailing-spaces\": 2,\n \"space-around-link\": 2,\n \"no-multiple-blank-lines\": 2\n }\n}\n```\n\nCLI 默认读取 `./.lintmdrc`。也可以使用 `lint-md --config <文件路径>` 指定配置文件。\n\n直接使用 Core API 时，在 `fixMarkdown()` 的 `rules` 中配置规则：\n\n```ts\nimport { fixMarkdown, RULE_SEVERITY } from '@lint-md/core';\n\nconst markdown = '第一行\\n第二行';\nconst result = fixMarkdown(markdown, {\n rules: {\n 'require-trailing-spaces': RULE_SEVERITY.ERROR,\n 'space-around-link': RULE_SEVERITY.ERROR,\n 'no-multiple-blank-lines': RULE_SEVERITY.ERROR\n }\n});\n\nconsole.log(result.fixedResult.result);\n```\n\n`RULE_SEVERITY.ERROR` 等同于规则级别 `2`。\n`fixMarkdown()` 始终执行自动修复。\n只检查时，继续使用 `lintMarkdown(markdown, rules, false)`。\n\n`space-around-link` 处理普通链接、自动链接和引用链接。它不处理独立图片。\n全角标点、其他 Unicode 标点、已有空白和块边界不需要空格。连续链接之间只添加一个空格。\n\n`no-multiple-blank-lines` 将连续空白行修复为一个空白行。\n它删除文档开头的空白行。它保留文档末尾的一个换行。\n空格和 Tab 组成的行也算空白行。代码块内部内容不受影响。\n\n欢迎大家提交需求，或者提交 PR 新增规则。\n\n## 🔌 生态封装\n\nlint-md 提供了多个常用场景的官方封装，可按你的工程工具链直接接入：\n\n- [@lint-md/cli](https://github.com/lint-md/cli)：命令行批量检查与修复，适合本地和 CI。\n- [@lint-md/prettier-plugin](https://github.com/lint-md/prettier-plugin)：在 Prettier 流程中统一执行中文 Markdown 规范。\n- [@lint-md/eslint-plugin](https://github.com/lint-md/eslint-plugin)：将 Markdown 规则纳入 ESLint 规则体系。\n- [@lint-md/vscode-plugin](https://github.com/lint-md/vscode-plugin)：在 VSCode 中实时提示并辅助修复。\n\n也欢迎大家提交新的生态封装（Issue / PR），我们会持续收录。\n\n### 开发新集成\n\n按照架构原则，新集成的开发步骤（以 ALE 为例）：\n\n1. 依赖 `@lint-md/core`\n2. 调用 `lintMarkdown()` 获取 `diagnostics`，并检查 `executionErrors` 是否为空\n3. 使用 `toALEOutput()` 或自行转换格式\n4. 处理 stdin/file 输入 → 输出 → 退出码；CI 需要快速失败时启用 strict 模式\n\n约 30 行代码即可完成一个新编辑器集成。\n\n## 🛠️ 开发\n\n```bash\n# 安装依赖\nnpm install\n\n# 运行测试\nnpm test\n\n# 代码检查\nnpm run lint\n\n# 类型检查\nnpm run typecheck\n\n# 构建\nnpm run build\n```\n\n`npm run lint` checks TypeScript and MJS files in `src/`, `__tests__/`, and `scripts/`.\n\n### 维护公共 API\n\n项目使用 [API Extractor](https://api-extractor.com/) 跟踪 `@lint-md/core` 的公开类型接口。API 基线保存在 `etc/core.api.md`，该文件由工具生成，请勿手动编辑。\n\n修改导出函数、类型、枚举或规则对象后，运行：\n\n```bash\nnpm run api:report\n```\n\n该命令会重新构建项目，并根据当前声明文件更新 API report。提交代码前请检查 `etc/core.api.md` 的 diff，确认其中只包含预期的 API 变化，并将更新后的 report 与源码一起提交。\n\nCI 会在构建后运行：\n\n```bash\nnpm run api:check\n```\n\n如果源码生成的公共 API 与已提交的 report 不一致，检查将失败。\n\n发布前会自动执行完整校验（lint → typecheck → build → test）。\n\n## 📄 License\n\n[MIT](./LICENSE) © [hustcc](https://github.com/hustcc)\n","readmeFilename":"README.md"}