前言¶
在 DeepSeek Harness（DSH）里做智能体或复杂项目时，文档往往散落在 docs、wiki、各子目录的 README 与 records 里。用文件树逐个点开能读，但缺少按「地图 / 契约 / 记录层 / 运维」这类口径分层浏览的能力；记录类 Markdown 的生命周期（proposed、implemented 等）也不容易在侧栏一眼区分。社区里也有右侧栏文档类插件，而 dsh-doc-tree 走另一条路：只依赖 DSH 官方扩展点，不捆绑 dsh-docs-panel 或 dsh-better-sidebar，在同一右侧栏里提供策展分层、全文搜索、同栏阅读，并通过 /docs-organize 让模型完成扫描、体检、dry-run 与人工审批后再写入 .dsh-doc-tree.json。
下面介绍该插件的定位、能力与安装用法。维护者为 Meowrium；分类为工作流；源码与说明见 GitHub，社区目录页为 SkillHub。
这是什么¶
dsh-doc-tree 是面向 DSH Web 右侧栏的文档树插件：在栏内按配置或内置默认分层浏览 Markdown，展开 records/{lifecycle}/{class} 语义结构，支持全文搜索与同栏预览；另提供 Files.md 风格的暖色阅读主题、双文档对照、Ctrl/Cmd+K 快速切换，以及行内/块级 LaTeX（复用宿主 KaTeX）。
一句话：受治理的文档树 + AI 辅助分层命令，把「怎么看」和「怎么定分层规则」拆开——日常浏览靠配置与 UI，大规模整理靠 /docs-organize 与 host 侧 doc_tree_* 工具。
核心功能¶
策展分层与记录层¶
- 默认分组包括：文档地图、口径契约、记录层、子系统参考、运维手册、术语、其他等；组头显示篇数，可折叠。
- 记录层按
records/{proposed|implemented|rejected|archived}/{class}成树；生命周期色点与 class 标签；阅读时把首部Status:提到标题下；可按 lifecycle / class 筛选。
扫描、搜索与阅读¶
- 顶栏雷达按钮扫描工作区候选根（
docs/documentation/wiki及项目下docs），候选带篇数，点选后保存。 - 搜索覆盖路径、文件名与正文（后台内存索引，命中带上下文与高亮）。
- 阅读复用宿主
MarkdownText；相对.md链接在 tab 内跳转；大纲按 h1–h4 导航。 - 右栏宽度 ≥700px 时自动双栏（列表 + 阅读区）；更窄时单栏下钻。
配置驱动¶
工作区根目录放置 .dsh-doc-tree.json（不在文档目录内），定义 root、groups、records.statuses 等；无配置时使用内置默认分层。groups 通过 glob match 机械归类；语义分层由 /docs-organize 中的模型判断，README 明确要求「不要按目录名硬套」。
Files.md 风格与对照阅读¶
- 顶栏调色板切换暖色主题（大标题、暖灰背景、蓝链接、左侧蓝条引用）。
- 阅读器「对照」可选第二篇文档；宽屏为「列表 + 两篇」，窄屏隐藏列表、两篇平分。
Ctrl/Cmd+K打开命令面板，按路径过滤文档并 Enter 打开。
AI 分层：/docs-organize¶
命令与默认流程（写配置前必须经 ask_user_question 批量审批）：
/docs-organize # 默认：scan + lint + dry-run + 人工审批
/docs-organize docs # 指定工作区相对根
/docs-organize --report docs # 只出报告：不提问、不写配置
Host 侧工具包括 doc_tree_scan、doc_tree_lint、doc_tree_read_plan、doc_tree_apply_plan（dryRun:true 只返回 diff，不写盘）。合并/删除/移动文档不在该命令范围内；lint 默认可机械项也只报告，除非用户明确同意处理。
独立性¶
插件仅使用：ctx.sidebarRightTabs.register、sidebar.right.pane.tab slot、workspaceFiles Remote（只读）、baseline 的 MarkdownText / MarkdownDelegateProvider，以及 ctx.tools / ctx.commands / ctx.fs。
安装与启用¶
要求 DSH 0.2.1-rc.1+（README 写明开发验证于 0.2.1-rc.2）。Node >=20。许可证 MIT，当前包版本 0.1.0。
从 GitHub 安装（dsh plugin 会把参数转发给 pnpm）：
dsh plugin --profile web add github:Meowrium/dsh-doc-tree
安装后重启 dsh web，浏览器硬刷新（Ctrl/Cmd+Shift+R）。右侧栏「＋」→「文档树」。
开发期可用 dsh-super-injector 热装配，免重启：
dev_install_package /path/to/dsh-doc-tree
插件在 当前 dsh 进程权限 下运行；安装前请自行查看 仓库源码 与许可证，确认符合你的安全与合规要求。
典型用法¶
- 打开右侧栏「＋」→「文档树」。
- 首次打开会自动扫描候选根目录；也可点顶部雷达重扫，选路径后「保存」。
- 点右上角
<>在「策展分层」与「原始目录结构」间切换；⟳重新扫描（外部改文档后索引需重建）。 - 点击文档在右侧阅读；
大纲导航标题，×关闭当前文档。 - 体验公式与对照：将文档根设为工作区内的
dsh-doc-tree/examples/docs（或 clone 后等价路径）。
配置示例（工作区根 .dsh-doc-tree.json）：
{
"version": 1,
"root": "docs",
"generatedAt": "2026-10-19T00:00:00.000Z",
"generatedBy": "docs-organize",
"groups": [
{ "id": "map", "title": "文档地图", "hint": "L2", "match": ["README.md", "AGENTS.md"] },
{ "id": "contracts", "title": "口径契约", "hint": "L4", "prefix": "contracts/", "match": ["contracts/**"] },
{ "id": "records", "title": "记录层", "hint": "L5", "prefix": "records/", "match": ["records/**"], "records": true },
{ "id": "development", "title": "子系统参考", "hint": "L2", "prefix": "development/", "match": ["development/**"] },
{ "id": "other", "title": "其他", "match": ["**"] }
],
"records": {
"dir": "records",
"lifecycles": ["proposed", "implemented", "rejected", "archived"],
"statuses": { "records/implemented/feature/x.md": "implemented" }
}
}
公式由宿主渲染，插件不额外打包 KaTeX：
行内：$E = mc^2$
$$
\frac{\partial \mathcal{L}}{\partial \theta}
= \frac{1}{N}\sum_{i=1}^{N}(\hat{y}_i - y_i)^2
$$
块级公式建议 $$ 独占一行，前后留空行。
适用场景与注意¶
适合：已在 DSH Web 中开发、希望右侧栏统一浏览项目文档；有 records/ 生命周期目录结构；需要全文搜索与同栏阅读、偶尔用模型整理分层并落盘配置的团队或个人。
注意（来自 README「已知限制」）：
- 自动扫描为有界启发式（约 64 个一级目录 × 16 个子目录），超大仓库建议
/docs-organize <root>或手填root。 - 无配置且内置分组均不匹配时，文件落入「其他」；可用「原始结构」或生成配置。
- 正文索引在打开 tab 后后台建立，非增量；外部改动后点
⟳。 - 单文件读取上限 5000 行；未做虚拟滚动，上千篇文档性能需自行评估。
- 公式依赖宿主 KaTeX；未加载时退化为文本。Files.md 风格仅视觉/交互移植，不含其编辑器、chat、sync 或写文件能力。
结尾¶
dsh-doc-tree 把 DSH 右侧栏变成可配置的文档阅读面，并用 /docs-organize 把「分层设计」做成可审批、可 dry-run 的工作流，与「只读浏览」解耦。社区插件目录 SkillHub 与仓库 github.com/Meowrium/dsh-doc-tree 可查阅安装说明与 issue；目录站为社区维护，与 DeepSeek / 幻方无官方从属关系。
