前言¶
在 DSH 工作流里，交付物经常是成批的 Markdown 或纯文本说明。人工通读时容易漏掉标题从 ## 直接跳到 ####、同级标题重复、空标题行，以及整篇没有任何标题的「无结构」文档。这些问题不会立刻导致构建失败，却会让后续检索、目录生成和 Agent 按章节引用变得不可靠。
下面介绍社区插件 深鲸文档结构（npm 包名 @deepwhale-cn/dsh-doc-outline，仓库 feely0208/dsh-doc-outline）。它在 DSH Web 侧栏提供检查结果，并对指定目录做批量扫描；只提示问题，不自动改文件。
这是什么¶
深鲸文档结构 归类为 DSH 社区目录中的 工作流 插件，由维护者 feely0208 发布，源码托管于 GitHub。插件定位是：对 Markdown 文档的 标题结构 做静态检查，覆盖层级跳跃、重复标题、空标题，以及完全没有标题结构的文档。
与「写完后凭肉眼扫一遍」相比，它把上述规则固定成可重复执行的检查，适合在交付前或 CI 旁路里统一跑一遍。
核心功能¶
依据项目 README 与 package.json 描述，当前版本（0.1.0）核实到的能力如下：
- 层级跳跃：标题级别不应出现不合理跳级（例如中间缺层）。
- 重复标题：识别文档内重复的标题文本。
- 空标题：发现无有效内容的标题行。
- 无结构文档：对没有任何标题结构的
.md/.txt给出提示。
扫描范围与行为边界（README 明确说明）：
- 仅处理
.md与.txt文件。 - 只提示，不修改 源文件。
- Web 面板入口：侧栏 「深鲸文档结构」。
插件依赖 @deepwhale-cn/dsh-guard-core，面向 DSH Web 客户端注入（platform: "web"），运行环境要求 Node >= 18，DSH >= 0.1.0-rc.6 且 < 0.3.0。许可证为 MIT。
安装与启用¶
安装命令须使用资料原文，不要自行拼接 GitHub 地址：
dsh plugin --profile web add @deepwhale-cn/dsh-doc-outline
--profile web 与包内 dsh.client.platform: "web" 一致，用于在 Web 侧加载面板与客户端逻辑。安装前建议打开仓库 README 与源码，确认许可证与将要执行的检查逻辑；插件以 当前 dsh 进程的权限 读取你指定的输入路径。
典型用法¶
命令行入口为 dsh-doc-outline（见 package.json 的 bin 字段）。README 给出的示例如下：
dsh-doc-outline --input ./交付材料
将 ./交付材料 换成实际目录即可对其中符合条件的 Markdown / 文本做结构检查。Web 端可在侧栏打开 「深鲸文档结构」 查看与 CLI 一致的检查能力（具体交互以你安装的 DSH 版本为准）。
适用场景与注意¶
适合谁
- 需要批量验收技术文档、投标材料、插件说明等 Markdown 交付物的团队。
- 希望在 DSH Web 工作流里随手看结构问题、又不想工具擅自改文件的开发者。
使用时注意
- 插件 不会写回文件；修复标题仍需人工或你们自己的格式化流程。
- 非
.md/.txt不会被扫描；其它格式需先转换或换用别的工具。 - 社区目录页（skillhub 条目）与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」，安装与审计责任在使用方。
- 安装与运行前请自行审查 GitHub 仓库 源码与 MIT 许可证；任何读取本地路径的操作都受 dsh 进程权限约束。
结尾¶
深鲸文档结构 把 Markdown 标题的常见问题收成可重复的检查：层级、重复、空标题与无结构文档，CLI 与 Web 侧栏并用，且保持只读提示。若你在 DSH 里整理文档交付物，可先安装 @deepwhale-cn/dsh-doc-outline，对目标目录执行 dsh-doc-outline --input，再在侧栏 「深鲸文档结构」 对照结果。
