KatanA Markdown Linter

katana-markdown-linter

兼容 markdownlint 的 Rust 引擎、kml CLI、格式化工具、安全修复工具、编辑器服务，以及面向 Agent 的 MCP 服务。

安装 | CLI 用法 | 库 API | 编辑器集成 | MCP 服务

---

什么是 kml

katana-markdown-linter 是一款快速的 Markdown 检查引擎，适用于技术写作、规范文档和 AI Agent 辅助的文档工作流。

该项目沿用 KatanA 的视觉形象，同时保持独立边界：crate、CLI、封装程序、编辑器服务和 MCP 服务均不依赖 KatanA Desktop。

功能

• 兼容 markdownlint 的检查，支持当前上游规则目录
• 安全修复低风险规则违规，并支持明确选择启用的不安全修复
• 格式化模式，规范布局而不改变作者意图
• 可嵌入的 Rust API，供需要在进程内执行检查或修复的应用使用
• kml CLI，支持 JSON 输出、标准输入、忽略规则和统计信息
• 编辑器集成，通过 stdio Language Server Protocol 服务实现
• MCP 服务，为需要结构化检查功能的 Agent 和工具提供支持
• 多渠道分发，通过 Cargo、GitHub Releases、npm、PyPI 和 Homebrew 提供

库 API

在其他 Rust 应用中嵌入 lint 功能时，可直接使用此 crate。

• lint(content, options)
• fix(content, options)
• available_rules()
• localized_available_rules(language_code)
• implemented_rules()
• missing_rules()
• rule_catalog()
• localized_rule_catalog(language_code)
• resolve_locale_code(language_code)
• resolve_locale_code_or(language_code, fallback)
• localized_rule_description(rule_id, fallback_description, language_code)
• supported_locales()
• upstream::get_rule_documentation(rule_id, locale)
• MarkdownLintConfig
• MarkdownLintConfig::schema()
• MarkdownLintConfig::to_lint_options()

available_rules() 返回规范的英文元数据。对于面向用户的规则目录，请调用 localized_available_rules(language_code)、 localized_rule_catalog(language_code)、RuleMeta::localized_description(...) 或 localized_rule_description(...)，这样应用就能传入 UI 语言代码，而不必重新实现 kml 的回退策略。

从 v0.6.0 起，Locale 为 #[non_exhaustive]。匹配 Locale 的使用方应包含通配分支， 并优先使用 resolve_locale_code(...) 或 resolve_locale_code_or(...) 处理 UI 语言字符串。 规则说明和规则 Markdown 文档支持以下语言的本地化：en、ja、zh-CN、zh-TW、 ko、pt、fr、de、es 和 it。

可在 examples/ 下找到最小嵌入示例：

• embedding.rs：字符串检查、文件树检查、字符串修复、配置加载和配置到选项的转换

安装

Cargo

cargo install katana-markdown-linter

二进制目标为 kml。如果希望通过同一渠道获取 Rust crate 和 CLI，请使用 Cargo。

npm

npm 包是一个轻量启动器，首次使用时会下载与 kml、kml-mcp 或 kml-mcp-remote 匹配的 GitHub Release 压缩包：

npm install -g katana-markdown-linter
kml version

可使用 npx 运行一次性任务：

npx --yes [email protected] check README.md
npx --yes [email protected] kml-mcp --workspace-root /absolute/path/to/workspace
bunx --package [email protected] kml-mcp --workspace-root /absolute/path/to/workspace

PyPI

PyPI 包是一个轻量 Python 启动器，首次使用时会下载与 kml、kml-mcp 或 kml-mcp-remote 匹配的 GitHub Release 压缩包：

pipx install katana-markdown-linter
kml version

如果不使用 pipx，请通过常用的 Python 环境管理器安装。

可使用 uvx 运行一次性任务，无需将启动器安装到当前活动环境中：

uvx --from katana-markdown-linter==0.19.6 kml check README.md
uvx --from katana-markdown-linter==0.19.6 kml-mcp --workspace-root /absolute/path/to/workspace

GitHub Releases

GitHub Releases 附带独立的 kml 压缩包。请选择与 Rust 目标三元组匹配的压缩包：

curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.19.6/kml-v0.19.6-aarch64-apple-darwin.tar.gz
curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.19.6/kml-v0.19.6-aarch64-apple-darwin.tar.gz.sha256
shasum -a 256 -c kml-v0.19.6-aarch64-apple-darwin.tar.gz.sha256
tar -xzf kml-v0.19.6-aarch64-apple-darwin.tar.gz

Homebrew

Homebrew formula 会在发布流程中发布。使用以下命令安装：

brew install HiroyukiFuruno/katana/kml

VS Code

从 VS Code Marketplace 安装 KatanA Markdown Linter 扩展，或侧载本地包。该扩展是 kml lsp 服务的轻量封装，并会在启动时验证版本兼容性。

# Sideload for MVP testing
cd editors/vscode
npm install
npm run compile
code --extensionDevelopmentPath=$PWD

Zed

从 Zed 扩展注册表安装 KatanA Markdown Linter 扩展，或从仓库侧载。该扩展会将 kml lsp 注册为 Markdown 语言服务，并支持自定义二进制文件路径。

# Sideload for MVP testing
# Use the "zed: install dev extension" action in Zed
# and select the 'editors/zed' directory.

GitHub Actions

使用仓库 Action 在 CI 中运行 kml，无需编写安装步骤：

- uses: actions/checkout@v5
- uses: HiroyukiFuruno/[email protected]
  with: { version: "0.18.0", command: check, paths: "README.md\ndocs", config: .markdownlint.json }

为确保运行可复现，请将 Action 标签和 version 一起固定。默认情况下，Action 会从 crates.io 安装 kml。仓库本地的冒烟测试可以设置 install-source: path 和 path: .。

extra-args 每行接受一个参数，因此需要值的标志必须分行填写。

CLI 用法

kml check
kml check --locale en
kml check -l ja
kml --locale ja help
kml fix
kml fmt
kml check --fix
kml fix --unsafe --yes README.md
kml check --fix --unsafe --yes README.md
kml check README.md
kml check --file README.md
kml check --output json "docs/**/*.md"
kml check --format json "docs/**/*.md"
kml check --ignore-config-errors README.md
kml check --stdin
kml fix --stdin
kml check --include "**/*.md" --exclude "target/**"
kml check --include-reserved node_modules
kml check --no-ignore --force-exclude --exclude "vendor/**" vendor/README.md
kml check --statistics --quiet
kml fix --diff README.md
kml rule
kml rule --locale ja
kml rule --locale fr
kml rule MD013
kml rule MD013 --locale ja --output json
kml config file
kml config get --output json
kml config schema
kml --help
kml -h
kml help
kml check --help
kml check -h
kml version
kml --version
kml -v
kml fix --config .markdownlint.json README.md
kml init-config

未提供文件时，kml check、kml fix 和 kml fmt 会递归处理当前目录下的 Markdown 文件。使用 --file 可明确指定仅处理单个文件。

check 会报告诊断信息，并在发现 lint 违规时以 1 退出。 fix 和 check --fix 会应用安全的 lint 修复，并在重写后仍存在 违规时以 1 退出。fmt 是用于规范缩进和换行的布局格式化工具；即使 check 仍会报告无关的 lint 诊断，格式化成功后它也会以 0 退出。文件系统 或配置错误以 2 退出。

fmt 当前会将 CRLF/CR 行尾规范为 LF，并规范末尾换行、连续空行、 标题/围栏/列表/表格周围的空行，以及安全的列表缩进和列表标记间距。它不会 重新排版段落、改变标题或强调样式、改变 URL/表格样式、删除尾随空格，也不会默认应用 不安全的修复。

fix 和 check --fix 需要明确选择加入才能应用不安全的修复。 交互式使用时会提示 [Y/n]；非交互式使用时必须传入 --unsafe --yes。

--output json 是首选的 JSON 输出标志。--format json 仍作为兼容别名保留。 修复模式的 JSON 会按文件包含 fix_details，以便将已应用的规则与修复前的诊断 和重写后的文件差异进行比较。

--stdin 会从标准输入读取 Markdown。check --stdin 会针对 <stdin> 报告诊断；fix --stdin 会将修复后的 Markdown 写入标准输出；fmt --stdin 只会将格式化后的 Markdown 写入标准输出。

目录扫描默认遵循 gitignore 文件。使用 --no-ignore 可在所有位置包含被忽略的路径，或使用 --include-ignored 仅包含显式目录输入（如 .agents）下被忽略的路径。即使没有 gitignore 条目，.git、node_modules、target、dist 和 coverage 等保留目录默认也会跳过；只有在确实要扫描这些目录时才使用 --include-reserved。项目专用的生成目录或 Agent 目录应通过 gitignore 或 --exclude 排除。--exclude 会过滤发现的文件；除非同时设置 --force-exclude，否则显式指定的文件仍会保留。

不带命令调用 kml 会打印全局帮助信息。kml help、kml --help、 kml -h 和 kml <command> --help 会打印帮助信息，不会扫描文件。

--locale <locale> 和 -l <locale> 用于选择面向用户的 CLI 消息和帮助 文本语言。 支持的值会解析为 en、ja、zh-CN、zh-TW、ko、pt、fr、 de、es 和 it，也支持 fr-FR、 pt-BR 或 ko-KR 等常见区域格式。省略时，kml 会读取操作系统的语言环境变量， 如果语言环境不可用或不受支持，则回退到英语。显式指定不受支持的语言环境 会导致 CLI 错误。--local 是为 v0.4.0 用户保留的向后兼容别名。

kml rule 和 kml rule <id> 也支持 --locale。 文本输出使用本地化的规则说明，JSON 输出同时包含 description（本地化）和 english_description（规范英语）。

规则映射

kml 为当前启用的 markdownlint 规则目录提供 lint 检查。以下规则 ID 与 available_rules() 和 kml rule --output json 返回的公开目录一致；状态列描述由测试样例支持的实现 状态。运行 kml rule MD013 可查看某条规则及其上游文档 URL。

简要说明：

能力	状态
检查覆盖范围	所有 53 条启用规则均为 Implemented
安全修复覆盖范围	38 条规则提供安全修复；15 条规则仅提供诊断
不安全修复覆盖范围	1 条规则提供需明确选择加入的不安全修复子集；其余规则不适用或需要手动判断意图
上游已删除的 ID	7 个历史 ID 显示为 Deleted，修复状态为 -
安全修复刻意保持保守。已实现的子集表示 kml 会重写该规则下由固定测试样例覆盖的低风险违规形式。仅诊断表示已实现检查，但不提供安全修复。需要人工判断意图表示自动重写会替作者决定意图。不适用表示除安全修复策略外，目前未发现单独的不安全候选项。已删除行是历史上的 markdownlint ID，不属于当前上游规则目录。

完整的测试样例支持规则矩阵

| 规则 | 检查 | 修复（安全） | 修复（不安全） | | --- | --- | --- | --- | | `MD001` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD002` | 已删除 | - | - | | `MD003` | 已实现 | 已实现子集 | 不适用 | | `MD004` | 已实现 | 已实现子集 | 不适用 | | `MD005` | 已实现 | 已实现子集 | 不适用 | | `MD006` | 已删除 | - | - | | `MD007` | 已实现 | 已实现子集 | 不适用 | | `MD008` | 已删除 | - | - | | `MD009` | 已实现 | 已实现子集 | 不适用 | | `MD010` | 已实现 | 已实现子集 | 不适用 | | `MD011` | 已实现 | 已实现子集 | 不适用 | | `MD012` | 已实现 | 已实现子集 | 不适用 | | `MD013` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD014` | 已实现 | 已实现子集 | 不适用 | | `MD015` | 已删除 | - | - | | `MD016` | 已删除 | - | - | | `MD017` | 已删除 | - | - | | `MD018` | 已实现 | 已实现子集 | 不适用 | | `MD019` | 已实现 | 已实现子集 | 不适用 | | `MD020` | 已实现 | 已实现子集 | 不适用 | | `MD021` | 已实现 | 已实现子集 | 不适用 | | `MD022` | 已实现 | 已实现子集 | 不适用 | | `MD023` | 已实现 | 已实现子集 | 不适用 | | `MD024` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD025` | 已实现 | 已实现子集 | 不适用 | | `MD026` | 已实现 | 已实现子集 | 不适用 | | `MD027` | 已实现 | 已实现子集 | 不适用 | | `MD028` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD029` | 已实现 | 已实现子集 | 不适用 | | `MD030` | 已实现 | 已实现子集 | 不适用 | | `MD031` | 已实现 | 已实现子集 | 不适用 | | `MD032` | 已实现 | 已实现子集 | 不适用 | | `MD033` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD034` | 已实现 | 已实现子集 | 不适用 | | `MD035` | 已实现 | 已实现子集 | 不适用 | | `MD036` | 已实现 | 仅诊断 | 已实现子集 | | `MD037` | 已实现 | 已实现子集 | 不适用 | | `MD038` | 已实现 | 已实现子集 | 不适用 | | `MD039` | 已实现 | 已实现子集 | 不适用 | | `MD040` | 已实现 | 已实现子集 | 不适用 | | `MD041` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD042` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD043` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD044` | 已实现 | 已实现子集 | 不适用 | | `MD045` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD046` | 已实现 | 已实现子集 | 不适用 | | `MD047` | 已实现 | 已实现子集 | 不适用 | | `MD048` | 已实现 | 已实现子集 | 不适用 | | `MD049` | 已实现 | 已实现子集 | 不适用 | | `MD050` | 已实现 | 已实现子集 | 不适用 | | `MD051` | 已实现 | 已实现子集 | 不适用 | | `MD052` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD053` | 已实现 | 已实现子集 | 不适用 | | `MD054` | 已实现 | 已实现子集 | 不适用 | | `MD055` | 已实现 | 已实现子集 | 不适用 | | `MD056` | 已实现 | 已实现（填充较短的行；溢出行仍仅提供诊断） | 不适用 | | `MD057` | 已删除 | - | - | | `MD058` | 已实现 | 已实现子集 | 不适用 | | `MD059` | 已实现 | 仅诊断 | 需要手动判断意图 | | `MD060` | 已实现 | 已实现子集 | 不适用 |

## 配置

该 crate 会读取和写入兼容 markdownlint 的 JSON 和 JSONC 配置文件：

• .markdownlint.json
• .markdownlint.jsonc

使用 kml init-config 创建默认的 .markdownlint.json。

使用 kml config schema 打印供编辑器集成和配置验证使用的 JSON Schema。稳定的 Schema ID 为 https://schemas.katana.tools/kml/markdownlint.schema.json。

配置错误会导致 check、fix 和 fmt 在报告文件诊断之前停止。请先修复配置；如果明确希望本次运行忽略无效配置项，也可以传入 --ignore-config-errors。支持官方 markdownlint 别名，例如 first-line-h1、first-line-heading、no-duplicate-heading 和 no-inline-html。

编辑器集成

kml lsp 会启动一个基于标准输入输出的语言服务器协议服务，用于提供 Markdown 诊断、格式化、范围格式化和安全的快速修复。VS Code、Zed 和 Neovim 的配置示例见 docs/editor-integration.md。

质量门禁

使用 just check 运行默认的本地门禁。它会运行格式检查、Clippy、AST lint 和测试。

使用 just dogfood 对本仓库的 Markdown 文档运行 kml，且不修改文件。仅在打算应用安全的 Markdown 修复时使用 just dogfood-fix。默认的 dogfood 目标会排除归档的 OpenSpec 文档；运行 just dogfood-archive 可显式检查这些文档。

使用 just examples 编译公开的 Rust 嵌入示例。

质量门禁详情、CI 必需检查、覆盖率模式和发布准备情况见 docs/quality-gates.md。

发布渠道状态和延期说明见 docs/distribution.md。

MCP 服务

kml-mcp 是一个可选的 MCP 服务，适用于希望通过标准输入输出以结构化方式访问库，同时保持核心 crate 不依赖 MCP 的 Agent 和编辑器。

使用 mcp 功能构建或安装：

cargo build --bin kml-mcp --features mcp --locked
cargo install katana-markdown-linter --locked --features mcp --bin kml-mcp

在 v0.19.3 之后，npm 和 PyPI 封装程序无需 Rust 工具链即可启动同一个基于标准输入输出的服务：

npx --yes [email protected] kml-mcp --workspace-root /absolute/path/to/workspace
bunx --package [email protected] kml-mcp --workspace-root /absolute/path/to/workspace
uvx --from katana-markdown-linter==0.19.6 kml-mcp --workspace-root /absolute/path/to/workspace

该服务提供文本、配置、规则元数据和工作区安全的文件工具：

• check_text
• fix_text
• config_validate
• rule_list
• rule_get
• check_file
• check_directory
• fix_file_preview
• fix_file_apply

工作区路径必须位于配置的 --workspace-root 之下。文件写入仅限于 fix_file_apply，且必须设置 apply: true；不提供目录应用工具。

运行 just mcp-stdio-smoke，通过 JSON-RPC 标准输入输出调用测试已安装的 MCP 服务。

kml-mcp-remote 是独立的可自托管 Streamable HTTP 服务，适用于无法启动标准输入输出子进程的 API 托管大模型客户端。默认情况下，它仅提供文本工具，不提供工作区文件工具：

cargo build --bin kml-mcp-remote --features mcp-remote --locked
KML_MCP_REMOTE_TOKEN=change-me target/debug/kml-mcp-remote

也提供用于可自托管远程 MCP 的封装程序入口：

KML_MCP_REMOTE_TOKEN=change-me \
  npx --yes --package [email protected] kml-mcp-remote
KML_MCP_REMOTE_TOKEN=change-me \
  uvx --from katana-markdown-linter==0.19.6 kml-mcp-remote

运行 just mcp-remote-smoke，验证 Bearer 身份验证、纯文本工具功能、文本诊断和请求正文大小限制。

v0.14.0 引入了通过 GitHub Releases 发布的 Linux MCPB bundle，以及本地标准输入输出服务的 MCP Registry 元数据。发布前请构建 bundle 并测试其中打包的 kml-mcp 二进制文件：

just VERSION=v0.19.6 mcpb-smoke

参见 MCP 服务文档、远程 MCP 部署指南、MCP 分发计划以及较早的 MCP 集成评估。

发布策略

• 库 API 是主要契约。
• CLI 是库的轻量封装。
• Cargo.toml 包版本是发布版本的唯一可信来源。
• 发布前运行 just VERSION=vX.Y.Z release-check。
• 运行 just VERSION=vX.Y.Z release-github 仅创建或更新 GitHub Release。
• 仅在计划发布到注册表时运行 just VERSION=vX.Y.Z release。
• 发布后运行 just VERSION=vX.Y.Z release-verify，以比较标签目标、GitHub Release 目标、crates.io、npm、PyPI、封装器启动、Homebrew formula 和二进制发布资源。
• GitHub Releases 要求使用经过签名的注释式 vX.Y.Z 标签，且 GitHub 将其报告为 Verified。
• 如果请求的版本已存在于 crates.io，just release 会在触发发布前停止。
• 发布到 crates.io 需要 GitHub 密钥 CARGO_REGISTRY_TOKEN。