dsh-doc-outline
Advanced tools
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.
DeepSeek Harness 的 Markdown 文档大纲工具箱：md_outline 解析文档生成标题树、check_toc 校验目录（TOC）与正文标题是否一致、insert_toc 为文档生成 / 插入目录。只读优先、零运行时依赖，帮长文档把结构理清楚、目录维护少踩坑。
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"
解析文档生成标题树。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（===/--- 下划线式）；代码块围栏（```）内的 # 会被忽略，不会误当标题。
校验 TOC 与正文一致性。同样的 path / content 二选一，输出检查报告。
来源：content 文本
正文标题 7 个；TOC 链接 3 个
失效项（TOC 有但正文无对应标题，共 1）：
1. [旧名称](#旧标题)
未收录标题（正文有标题但 TOC 未收录，共 2）：
1. 安装（行 2, #安装）
2. 配置（行 5, #配置）
三类问题含义：
完全一致时直接输出「目录与正文完全一致 ✅」。只做检查，不修改文件。
生成目录并插入。优先在 <!-- TOC --> 与 <!-- /TOC --> 标记之间写入（替换旧目录，不重复堆叠）；没有标记则在文档开头插入。
<!-- TOC -->
- [项目概览](#项目概览)
- [安装](#安装)
- [使用](#使用)
- [示例代码](#示例代码)
- [配置](#配置)
<!-- /TOC -->
默认只返回更新后的文本便于预览；传 write: true 且用 path 时才写回原文件。
md_outline 秒出标题树，看清章节层级与篇幅分布。check_toc 校验一遍，揪出失效项、漏收录的章节、对不上的锚点。insert_toc 一键生成，标记块内更新，不污染正文。check_toc，防止合并请求带坏的目录进来。md_outline，汇总成知识库索引。check_toc 批量确认哪些文档的目录要跟着改。md_outline、check_toc 纯读取、零写入；insert_toc 默认只返回文本，只有显式 write=true 且传 path 才回写原文件。# 已屏蔽。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 的一致性 |
md_outline：解析 ATX 标题生成标题树，带行号与 GitHub 风格锚点；代码块内 # 屏蔽check_toc：对比 TOC 链接与正文标题，检出失效项 / 未收录标题 / 锚点不一致insert_toc：在 <!-- TOC --> 标记块内生成 / 替换目录，无标记则插入开头；默认只返回文本-1 去重v0.2（计划）
=== / --- 下划线式）识别md_outline 的 levels 过滤与「折叠到指定层级」预览insert_toc 支持自定义目录标题与「插入到 ## 目录 标题后」的定位v0.3（展望）
check_headings：校验标题层级跳跃（H2 后直接 H4）与空标题format=json 结构化结果，便于脚本消费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 也能一一对上。
MIT
FAQs
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.
The npm package dsh-doc-outline receives a total of 6 weekly downloads. As such, dsh-doc-outline popularity was classified as not popular.
We found that dsh-doc-outline demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.