dsh-markdown-kit：Markdown 批量处理工具箱

前言¶

技术文档交付、周报合并、链接盘点这些活，常见于智能体开发与知识库维护场景。手工复制粘贴、套样式、拼目录、查重复链接，既耗时又容易出错。DSH（DeepSeek Harness）采用「一切皆插件」的思路，把这类任务交给脚本完成：输入一个文件或目录，输出 Word / TOC.md / links.txt / merged.md，每件产物都能打开核对。

下面介绍 dsh-markdown-kit。

是什么¶

dsh-markdown-kit 是一个 DSH 插件，由 feely0208 维护。它提供四个子命令：to-docx（Markdown 转 Word）、toc（生成目录）、links（提取链接）、merge（合并 Markdown）。它不依赖第三方 Markdown 库，只处理 .md / .markdown 文件（UTF-8），全部在本机运行，不联网、不上传文档。

核心功能¶

1. Markdown 转 Word（to-docx）¶

输入一个 Markdown 文件或目录，输出对应的 Word 文档。支持的元素包括：
- 标题（# / ## 等）
- 段落
- 无序/有序列表
- 代码块（等宽字体 + 浅灰底纹）
- 引用
- 表格
- 链接文字

代码块会使用 Consolas 字体，标题使用微软雅黑。生成的 Word 文档每篇对应一个 .docx 文件。JSON 输出会给出每个文件的标题、表格、代码块条数。

示例：

dsh-markdown-kit to-docx --input ./文档 --out ./word

2. 生成目录（toc）¶

按标题层级生成目录，支持两种模式：
- 目录模式：带文件相对路径，如 01-指南.md#第一章-总览
- 单文件模式：纯锚点，可直接贴进正文

锚点命名遵循 GitHub 规则（#第一章-总览），重名时自动添加 -1 后缀。

示例：

# 整本手册生成目录（带文件路径锚点）
dsh-markdown-kit toc --input ./文档

# 单篇文档生成目录（纯锚点）
dsh-markdown-kit toc --input ./文档/README.md --out ./目录

3. 提取链接（links）¶

提取文档中的链接信息，输出为制表符分隔的 links.txt，每行包含文件名、行号、类型、文字、URL。支持：
- [文字](链接) 格式的内联链接
- 图片（![文字](图片路径)）
- 裸 URL（http(s)://...）
- 自动链接（<https://…>）

使用 --json 可输出结构化结果，包含按文件统计的链接数量、重复项等。

示例：

dsh-markdown-kit links --input ./文档 --json

4. 合并 Markdown（merge）¶

按文件名自然顺序合并多个 Markdown 文件。排序规则是字典序：1、2、10 而不是 1、10、2。每个文件前会加上 # 文件名.md 作为分隔标题。

示例：

dsh-markdown-kit merge --input ./周报 --out ./合并

共同约定¶

不修改输入文件：只读 .md，所有产物写进输出目录。
默认输出 <输入目录>/_输出，可用 --out 指定。
同名文件不覆盖：已存在时自动变成 报告_1.docx、报告_2.docx。
目录递归处理，跳过 .git、node_modules、_输出 和所有点开头的目录。
只有 to-docx / --demo 需要 python-docx；toc / links / merge 只要 python3。
--json 输出结构化结果（含每个文件的产物路径与条数），方便脚本和 CI 断言。
出错退出码：2 参数/输入问题、3 缺依赖、1 运行失败。

安装与启用¶

安装命令如下：

dsh plugin --profile web add @deepwhale-cn/dsh-markdown-kit

运行依赖本机的 python3（插件不会替你装）。to-docx 还需要 python-docx。缺依赖时 CLI 会直接打印安装命令：

python3 -m pip install python-docx
# macOS 没有 python3 时
brew install python3

典型用法¶

# 查看帮助
dsh-markdown-kit --help

# 运行演示（自造样例，不碰你的文件）
dsh-markdown-kit --demo

# 批量转 Word
dsh-markdown-kit to-docx --input ./文档 --out ./word

# 生成目录
dsh-markdown-kit toc --input ./文档

# 盘点链接与重复项
dsh-markdown-kit links --input ./文档 --json

# 按文件名顺序合并周报
dsh-markdown-kit merge --input ./周报 --out ./合并

适用场景与注意¶

适合以下场景：
- 技术文档批量转 Word 交付
- 手册/指南目录自动生成
- 文档链接盘点与重复项检查
- 周报/报告批量合并

注意：
- 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
- 它不是完整的 CommonMark 渲染器，只支持七种块类型（标题 / 段落 / 列表 / 代码块 / 引用 / 表格 / 内联链接），其他元素会退化成普通段落。
- 图片不会嵌进 Word，只保留文字。
- 不保证排版等同于设计稿：标题字号/页边距固定，不做页眉页脚、页码、分页、封面页、多栏。
- 有序列表在 Word 里可能跨列表连续编号，需要精确编号请自己写 1. 文字。
- to-docx 和 toc 会跳过文档开头的 YAML front matter；merge 原样保留每篇内容（含 front matter）。
- links 不扫描围栏代码块，只提取文档链接。

结尾¶

dsh-markdown-kit 把机械但量大的文档处理任务交给脚本完成，适合需要批量交付 Word、自动生成目录、盘点链接、合并报告的场景。它的定位是工具箱，而不是完整的 Markdown 渲染器，使用前应确认它支持你需要的元素。

目录页：https://www.skillhub.cn/plugins/feely0208/dsh-markdown-kit
GitHub：https://github.com/feely0208/dsh-markdown-kit