dsh-plugin-md-outline
> 🇨🇳 中文 | 🇺🇸 English
一个最小但实用的 DeepSeek Harness 插件，给 harness 增加 md_outline 工具。 它用来梳理和检查 Markdown 文档结构：输出嵌套标题树，并给出手工很难查、长文档里极易出错的结构警告 （书稿、skill 集、规格文档都适用）。
> 话题标签：dsh-plugin —— 给 GitHub 仓库加上这个 topic，生态就能发现它 > （见下方[发布 dsh-plugin 话题](#发布-dsh-plugin-话题)一节）。
它能做什么
| 检查项 | 为什么有用 |
|---|---|
| 标题树（H1–H6，带行号） | 一眼看清长文档结构、方便导航与审计。 |
| 标题层级跳级（如 H1 → H3） | 抓出文档层级断裂。 |
| 重复标题文本 | 标记会破坏锚点/目录的意外重复。 |
| 缺少 H1 / 多个 H1 | 强制要求单一文档标题。 |
| 未闭合的代码围栏 | 长文档最经典的坑——一段围栏没闭合会让后面整篇都变成"代码"。代码块内的标题会被正确忽略。 |
效果预览
终端运行 node examples/run.mjs 的真实输出（覆盖全部 5 个示例文档： clean、跳级、重复标题、多 H1、未闭合围栏）：
错误长什么样 — examples/level-skip.md
左边是你写出来的原始文档，右边是 md_outline 的检测报告。 第 3 行 H1 → H3 的跳级被精确定位，并给出原因。
重新生成：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](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