dsh-doc-outline
v0.1.0
Published
doc outline toolkit for DeepSeek Harness: md_outline (build markdown heading tree), check_toc (verify TOC vs heading consistency), insert_toc (generate and insert a TOC). Zero runtime dependencies, read-only by default.
Maintainers
geekleiReadme
dsh-doc-outline
DeepSeek Harness 的 Markdown 文档大纲工具箱：md_outline 解析文档生成标题树、check_toc 校验目录（TOC）与正文标题是否一致、insert_toc 为文档生成 / 插入目录。只读优先、零运行时依赖，帮长文档把结构理清楚、目录维护少踩坑。
- 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-doc-outline
- npm：https://www.npmjs.com/package/dsh-doc-outline
功能说明
Markdown 文档长了以后，标题结构容易失控，手写目录（TOC）更是反复和标题不同步——改了标题忘了改目录、锚点对不上、章节漏收录。本插件用三档工具把文档大纲管起来：
- 标题树（
md_outline）：解析文档里所有 ATX 标题（#~######），按层级缩进生成标题树，每个标题带行号与 GitHub 风格锚点，快速概览文档结构、定位章节。 - 一致性检查（
check_toc）：收集文档中所有[标题](#锚点)目录链接，与正文标题逐条比对，报告三类问题——失效项（TOC 有但正文无对应标题）、未收录标题（正文有标题但 TOC 漏了）、锚点不一致（标题在但锚点对不上）。 - 目录生成（
insert_toc）：按正文标题自动生成目录列表，在<!-- TOC -->与<!-- /TOC -->标记之间写入（或替换），无标记则在文档开头插入；可只返回文本预览，也可write=true写回文件。
锚点按 GitHub 风格生成：转小写、去标点、空白转连字符、中文保留；重复标题自动追加 -1、-2 后缀去重。默认只读不写文件，只有你显式 write=true 才回写。
安装
npm install dsh-doc-outline安装后在 cordis.patch.yml 中加入：
- insert:
- id: doc-outline
name: "dsh-doc-outline"使用说明
md_outline
解析文档生成标题树。path 传 markdown 文件路径，content 直接传文本（二选一）；max_depth 控制显示到第几级；with_anchor 控制是否带锚点（默认 true）。
来源：E:\docs\guide.md；标题 7 个：
H1 项目概览（行 1, #项目概览）
H2 安装（行 2, #安装）
H2 使用（行 3, #使用）
H3 示例代码（行 4, #示例代码）
H2 配置（行 5, #配置）
H3 环境变量（行 6, #环境变量）
H4 数据库（行 7, #数据库）只识别 ATX（# 前缀）标题，不识别 setext（===/--- 下划线式）；代码块围栏（```）内的 # 会被忽略，不会误当标题。
check_toc
校验 TOC 与正文一致性。同样的 path / content 二选一，输出检查报告。
来源：content 文本
正文标题 7 个；TOC 链接 3 个
失效项（TOC 有但正文无对应标题，共 1）：
1. [旧名称](#旧标题)
未收录标题（正文有标题但 TOC 未收录，共 2）：
1. 安装（行 2, #安装）
2. 配置（行 5, #配置）三类问题含义：
- 失效项：TOC 里写了，但正文根本没有这个标题（多半是标题被删/改名后目录没跟），点击会跳到空。
- 未收录标题：正文有新标题，但目录没加进去。
- 锚点不一致：标题还在，但 TOC 里的锚点和按当前标题生成的锚点对不上（改了标题文字但目录锚点还是旧的）。
完全一致时直接输出「目录与正文完全一致 ✅」。只做检查，不修改文件。
insert_toc
生成目录并插入。优先在 <!-- TOC --> 与 <!-- /TOC --> 标记之间写入（替换旧目录，不重复堆叠）；没有标记则在文档开头插入。
<!-- TOC -->
- [项目概览](#项目概览)
- [安装](#安装)
- [使用](#使用)
- [示例代码](#示例代码)
- [配置](#配置)
<!-- /TOC -->默认只返回更新后的文本便于预览；传 write: true 且用 path 时才写回原文件。
典型场景
- 文档结构概览：几千行的 README / 设计文档，
md_outline秒出标题树，看清章节层级与篇幅分布。 - 目录同步维护：改完标题后
check_toc校验一遍，揪出失效项、漏收录的章节、对不上的锚点。 - 自动生成目录：长文档要加目录时
insert_toc一键生成，标记块内更新，不污染正文。 - CI 文档门禁：对仓库里的 md 文档跑
check_toc，防止合并请求带坏的目录进来。 - 多文档大纲汇总：对一批文档逐个
md_outline，汇总成知识库索引。 - 迁移/重构辅助：改章节名时用
check_toc批量确认哪些文档的目录要跟着改。
安全边界
- 只读优先：
md_outline、check_toc纯读取、零写入；insert_toc默认只返回文本，只有显式write=true且传path才回写原文件。 - 不访问网络：全部在本地解析，无任何外部请求，也不外发内容。
- 只解析 ATX 标题：setext 标题与特殊块（如部分 TOC 工具）可能不在识别范围；代码块内的
#已屏蔽。 - 锚点为启发式：锚点按 GitHub 风格生成，但不同渲染器（如部分 CMS）锚点规则可能有差异，
check_toc以本插件生成规则为准。 - 限制规模：
max_size跳过超大文件；max_chars截断过长输出。
其他插件集成说明
| 协作插件 | 集成方式 |
|---|---|
| dsh-markdown-lint | doc-outline 管标题结构与目录，markdown-lint 管格式规则，互为补充 |
| dsh-code-metrics | 文档也算代码资产：用 code-metrics 量篇幅，doc-outline 看结构 |
| dsh-test-report | 生成 README 后 insert_toc 自动补目录，README 更易读 |
| dsh-template-render | 把 check_toc 的差异清单渲染成报告发给文档负责人 |
| dsh-doc-outline（自用） | 用本插件的工具维护本仓库各插件 README 的一致性 |
版本说明
- 0.1.0（2026-10-11）：初始版本。
md_outline：解析 ATX 标题生成标题树，带行号与 GitHub 风格锚点；代码块内#屏蔽check_toc：对比 TOC 链接与正文标题，检出失效项 / 未收录标题 / 锚点不一致insert_toc：在<!-- TOC -->标记块内生成 / 替换目录，无标记则插入开头；默认只返回文本- 锚点：小写 / 去标点 / 空白转连字符 / 中文保留，重复标题
-1去重 - 只读优先、二进制与超大文件拒绝、输出截断
RoadMap
v0.2（计划）
- 支持 setext 标题（
===/---下划线式）识别 - 增加
md_outline的levels过滤与「折叠到指定层级」预览 insert_toc支持自定义目录标题与「插入到## 目录标题后」的定位
v0.3（展望）
- 增加
check_headings：校验标题层级跳跃（H2 后直接 H4）与空标题 - 输出可选
format=json结构化结果，便于脚本消费 - 支持锚点自定义规则（对齐特定渲染器）
FAQ
Q：为什么只识别 ATX 标题，不识别 setext（=== 下划线式）？
ATX（# 前缀）是 Markdown 最通用、可移植性最强的标题写法，绝大多数字档都用它。setext 需要额外规则且不同实现行为不一，v0.1 暂不支持，已列入 RoadMap v0.2。
Q：代码块里的 # 会被当成标题吗？ 不会。解析器维护代码块围栏（```）状态，围栏内的行全部跳过，不会误判。
Q：check_toc 的「失效项 / 未收录 / 锚点不一致」怎么区分？
以「正文标题」为唯一真源：TOC 里的条目在正文找不到任何对应标题 = 失效项；正文有标题但 TOC 里找不到任何对应条目 = 未收录；标题文字能对上但 TOC 锚点和按当前标题生成的锚点不符 = 锚点不一致。
Q：insert_toc 会破坏我原来的目录吗？
不会。它只操作 <!-- TOC --> 与 <!-- /TOC --> 之间的内容，原样替换为重新生成的目录；没有该标记块则在文档开头整体插入一段，不影响已有正文。并且默认只返回文本，不写文件。
Q：锚点对中文标题有效吗？
有效。锚点生成对中文字符保留，如「安装」→ #安装。重复的中文标题会追加 -1 后缀。个别渲染器对中文锚点有额外编码规则，可能与本插件不一致。
Q：为什么不直接写文件？
「只读优先」是本插件设计基调：检查与生成默认只出结果，由你确认后再决定是否回写，避免工具擅自改动你的文档。回写需显式 write=true。
Q：一个文档里多个相同标题怎么办？
锚点自动去重：第一个用原名，后续追加 -1、-2……这样 insert_toc 生成的每个链接都能精确跳转，check_toc 也能一一对上。
源码与发布地址
- 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-doc-outline
- npm：https://www.npmjs.com/package/dsh-doc-outline
许可证
MIT