Markdown 结构检查d-ouyang/dsh-plugin-md-outline

dsh-plugin-md-outline

🇨🇳 中文  |  🇺🇸 English

一个最小但实用的 DeepSeek Harness 插件，给 harness 增加 md_outline 工具。
它用来梳理和检查 Markdown 文档结构：输出嵌套标题树，并给出手工很难查、长文档里极易出错的结构警告
（书稿、skill 集、规格文档都适用）。

话题标签：dsh-plugin —— 给 GitHub 仓库加上这个 topic，生态就能发现它
（见下方发布 dsh-plugin 话题一节）。

它能做什么

| 检查项 | 为什么有用 |
|---|---|
| 标题树（H1–H6，带行号） | 一眼看清长文档结构、方便导航与审计。 |
| 标题层级跳级（如 H1 → H3） | 抓出文档层级断裂。 |
| 重复标题文本 | 标记会破坏锚点/目录的意外重复。 |
| 缺少 H1 / 多个 H1 | 强制要求单一文档标题。 |
| 未闭合的代码围栏 | 长文档最经典的坑——一段围栏没闭合会让后面整篇都变成"代码"。代码块内的标题会被正确忽略。 |

效果预览

终端运行 node examples/run.mjs 的真实输出（覆盖全部 5 个示例文档：
clean、跳级、重复标题、多 H1、未闭合围栏）：

效果预览

错误长什么样 — examples/level-skip.md

左边是你写出来的原始文档，右边是 md_outline 的检测报告。
第 3 行 H1 → H3 的跳级被精确定位，并给出原因。

Level-skip 对比

重新生成：python3 docs/gen_screenshot.py（会写出 docs/screenshot.png）。

安装

一键安装（任何机器、任何 profile 都可用）：

dsh plugin add https://github.com/d-ouyang/dsh-plugin-md-outline.git
dsh --profile demo --dump-config | grep -i md-outline   # 确认插件层已加入

需要 dsh CLI（DeepSeek Harness）。本插件是纯 ESM JavaScript，无需构建步骤、也不会触发 allowBuilds 提示，可直接从 git 仓库安装。

也支持本地目录安装：

dsh plugin --profile demo add /path/to/dsh-plugin-md-outline

卸载：

dsh plugin remove dsh-plugin-md-outline

使用

在 Web UI（或任何支持工具的表面）里直接让模型：

梳理 ~/book/draft.md 并告诉我有哪些结构问题。

或在代码模式里直接调用：

await tools.md_outline({ path: '~/book/draft.md', mode: 'both' })
await tools.md_outline({ path: '~/skills', mode: 'lint', recursive: true })
await tools.md_outline({ path: '~/notes/spec.md', mode: 'outline', maxDepth: 2 })

参数

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 是 | 一个 .md/.markdown/.mdx 文件，或一个目录。 |
| mode | 'outline' \| 'lint' \| 'both' | 否 | 默认 both。 |
| maxDepth | number (1–6) | 否 | 限制大纲嵌套深度。 |
| recursive | boolean | 否 | path 为目录时是否扫描子目录（默认 true）。 |

规范返回值是有结构的（{ files, summary }），方便代码模式里程序化处理；
面向模型的卡片展示的是人读版的 summary。

它是怎么搭出来的（cookbook 回顾）

本插件严格走官方写作路径：

1. 工具契约 —— docs/user/develop/basic/tool.md 与 docs/cookbook/adding-a-tool.md：
用 defineTool({ name, description, parameters, output, execute }) 通过 ctx.tools.register(...) 注册。
2. 打包成 bundle —— docs/user/develop/basic/publish.md：
bundle 是一个 npm 包，带 dsh.bundle 清单 + 一个 cordis.patch.yml 层，按包名插入插件行。
3. 零构建 —— 用纯 ESM JavaScript 编写，所以 github: 安装时无需跑任何 prepare 脚本。

dsh-plugin-md-outline/
├── package.json        # dsh.bundle 清单 + 对 @deepseek-ai/dsh-tools 的 peer 依赖
├── cordis.patch.yml    # profile 加入本 bundle 时应用的那一层
├── index.js            # 插件入口：name / inject / apply -> 注册 md_outline
├── md-outline-core.js  # 纯函数、零依赖的分析逻辑（有单元测试）
├── test.mjs            # node test.mjs 校验核心逻辑
├── examples/           # 样例文档 + run.mjs（真实输出见 docs/USAGE.md）
├── docs/USAGE.md       # 🇨🇳 完整使用说明（含真实测试结果）
├── README.md
└── README.zh-CN.md

本地开发

node test.mjs                 # 跑核心逻辑的单元测试
node examples/run.mjs         # 跑全部样例，输出真实大纲 + 检查报告
node --check index.js        # 语法检查插件入口

完整使用说明与真实测试结果见 docs/USAGE.md。

运行期契约依赖 @deepseek-ai/dsh-tools 存在于 dsh 安装中（harness 本身就用它）。
声明为 peerDependency，因此永远不会从 registry 去拉取。

发布 dsh-plugin 话题

dsh-plugin 这个 GitHub topic 是社区插件被发现的关键。在仓库 Settings → Topics 里添加，
或仓库建好后通过 API 设置：

git push 之后，通过 GitHub API 设置 topic（需要 token）
curl -X PUT -H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/d-ouyang/dsh-plugin-md-outline/topics \
-d '{"names":["dsh-plugin","markdown","deepseek-harness"]}'

许可证

MIT