前言¶
DeepSeek Harness（DSH）将智能体开发工具链与文件系统打通，但在本地存放大量知识库、笔记或草稿时，没有一个统一的阅读与编辑入口。传统做法要么在终端里用 cat、less，要么在系统文件管理器中打开目录，来回切换窗口，容易打断工作流。本插件通过 DSH 的 Slot 机制接入 Web 界面，在主面板提供一个类似浏览器标签页的阅读器，支持 Markdown 左编右渲、txt 单栏编辑、文件夹树与置顶管理，把「备忘录 + 目录阅读器」整合进工作区。
插件定位¶
本插件名称为 dsh-client-ui-notes，是 DSH 的纯外部图形界面插件：不修改 DSH 源码，只通过官方 Slot 注册主面板与左侧栏入口。维护者为 Zxy0902。它解决的问题是：在 DSH 环境中统一管理本地笔记，提供类浏览器标签页的阅读体验，支持文件夹树、搜索、置顶、跨文件夹保留状态等操作。
安装与启用¶
本插件仅在有图形界面的场景下可用，包括桌面应用与通过 dsh web 启动的 Web 界面。纯终端场景（dsh headless、SDK、ACP）安装不会报错，但没有任何功能可用。
桌面应用（macOS / Windows）¶
在左侧栏打开「插件」面板 → 点击「添加插件」 → 输入包名 dsh-client-ui-notes → 安装。
终端 / 自建 profile（任意平台，含 Linux）¶
先创建一个带 Web 界面的 profile，再安装插件：
# 1. 以 web 模板创建 profile（只建不启动，配置输出丢弃）
dsh --profile notes --from-default-profile web --dump-config > /dev/null
# 2. 把插件装进该 profile
dsh plugin --profile notes add dsh-client-ui-notes
# 3. 启动，然后在浏览器里打开它打印的地址
dsh --profile notes web
左侧栏出现「笔记」按钮即为安装成功。
⚠️ 不要跳过第 1 步。直接
dsh plugin add会创建一个以@deepseek-ai/dsh-base为基础的 profile，该 profile 没有 Web 界面层，启动web时界面无法显示，插件自然也无法显示。也不能用
dsh plugin --profile desktop安装桌面应用的 profile：该 profile 归应用独占管理，命令行写入会被拒绝。
想确认插件层已登记，可以看合并后的配置：
dsh --profile notes --dump-config | grep -A2 dsh-client-ui-notes
卸载：
dsh plugin --profile notes remove dsh-client-ui-notes
核心功能¶
本插件在主面板提供浏览器式 tab 栏与左侧文件夹树，支持 Markdown 编辑与预览、txt 编辑、文件搜索、置顶、拖拽移动、跨文件夹保留状态等功能。
左侧栏入口与面板布局¶
「笔记」按钮排在会话栏上方的全局面板按钮区，默认顺序为 30。点击后中间主面板切换成阅读器：左侧文件夹树 + 置顶区，右侧浏览器式 tab 栏。面板变窄时自动收起文件夹栏，改为上下堆叠，避免内容被挤成一列字。
浏览器式 tab 栏¶
tab 栏支持切换、关闭（×、中键、右键菜单）、新建。未保存时显示小圆点。按住标签拖动可调整顺序，顺序会保存。标签多到放不下时，栏右端出现向下尖头，点开下拉列出全部标签（含被裁掉的），当前项高亮。
文件夹树与搜索¶
文件夹树支持任意文件夹作为根，目录懒加载展开，当前文件高亮。根目录按「文件夹 / 根目录文件」分组。可隐藏以 . 开头的文件/目录（.git、.obsidian 等）与 node_modules，但不禁止访问。
置顶区最多 6 个，有独立分隔线，与文件树分区。置顶项可拖动调整顺序，拖动时其他项实时让位并显示落点指示线。双栏 / 单栏切换开关在「置顶」标题右侧，双栏省纵向空间，单栏文件名更完整。
文件名搜索框位于置顶区下方：输入即列出当前目录下文件名匹配的文件，上下键移动、回车或点击选中，自动展开树中所在目录并滚过去高亮，同时在右侧打开。
文件树操作¶
文件行右键可删除（二次确认）与定位文件：
- 删除：移入系统回收站（macOS ~/.Trash、Linux XDG 回收站）或笔记根目录下的 dsh-notes-trash/（Windows 不提供，见兼容性）。
- 定位文件：右键「在访达中打开」（macOS）/「打开文件所在位置」（Windows）/「在文件管理器中显示」（Linux）。
- 树内定位：文件树标题栏的准星按钮可一键展开当前打开文件所在的所有文件夹并滚过去高亮。
- 树批量折叠：标题栏的「打开所有文件夹 / 收起所有文件夹」两个按钮，一次展开或收拢整棵树。
拖拽移动：拖文件到文件夹上即移动进去，也可拖回文件树空白处移回根目录。悬停 600ms 自动展开目标文件夹，可拖进多层。
Markdown 编辑与预览¶
Markdown 左侧编辑、右侧实时预览，使用官方 MarkdownText，支持 GFM 与代码高亮。编辑 / 分栏 / 仅预览 三段切换，仅预览时编辑框完全不渲染。切换会被记住为默认：选一次「仅预览」，之后打开任何 md 都是阅读模式（只影响本插件，非 md 文件不受影响，默认仍是分栏）。
同步滚动：两侧按比例联动，工具栏可一键关闭。自适应宽度：面板变窄时自动收起文件夹栏、改为上下堆叠。
文件管理¶
txt 单栏直接编辑，不显示预览栏。新建时先选类型（Markdown / 纯文本），再填文件名，自动补扩展名。手动保存通过 ⌘S / Ctrl+S 或保存按钮。未保存时 tab 有圆点、文档头显示「未保存」。
状态记忆与跨文件夹¶
tab、当前 tab、置顶、展开的目录、滚动位置、未保存草稿、文件夹历史都会保留。切换文件夹时，已打开的标签页与置顶都会保留，并且仍能打开与保存。每个标签页记住自己打开时所在的文件夹，不跟着当前文件夹变。卸载本插件时自动清掉这些本地记录。
标签页管理¶
tab 上右键可「关闭 / 关闭其他 / 关闭右侧标签页 / 关闭全部」。
文件可见范围¶
文件树标题行有「可编辑 / 全部」开关，偏好持久化。「可编辑」只列能在阅读器里打开的文件（如 .md、.txt）；「全部」连 .doc/.pdf 一起列出。
不可预览文件的打开方式¶
点这类文件不会直接弹出系统程序，而是在阅读区开一个标签页：显示「此格式无法在阅读器中打开」+ 一个「打开方式」控件。左边按钮用默认应用打开，右边下拉列出系统里所有能打开它的应用，底部另有「显示文件位置」。
技能浏览（可关）¶
文件夹下拉里的「浏览技能…」（未选文件夹时引导页也有入口）列出当前可用的全部 skill。列表本身是一个单例标签页，点进某个技能后左边的「技能」tab 仍在，点一下就能返回列表。列表按 DSH 约定扫描磁盘（项目 / 用户 / 自定义根）+ 官方注册表补充，支持按名称/说明筛选。插件内置的技能标「内置」，正文由 DSH 提供，显示为只读视图。整体只读，不启用/禁用、不改文件。列表分「系统内置」与「我的技能」两块。
更新与兼容性¶
更新方式¶
- 插件详情页的「更新」：侧栏「插件」→ 点本插件卡片 → 顶部按钮。
- 插件市场：市场里搜到本插件后点「更新」。
- 命令行：
dsh plugin --profile <名字> add dsh-client-ui-notes@latest。
每个版本改了什么见 CHANGELOG.md。从 0.1.6 及更早升上来时，详情页的「更新」按钮必然失败，需要手动升级一次（市场或插件页装到 0.1.7+）。
兼容性¶
操作系统¶
| macOS | Windows | Linux | |
|---|---|---|---|
| 桌面应用 | ✅ | ✅ | ❌ 官方未发布 |
自建 dsh web |
✅ | ✅ | ✅ |
| 插件运行环境 | 两者皆可 | 两者皆可 | 只能自建 |
插件功能各平台的差异：
- 阅读器功能（树、标签页、编辑、预览、置顶、拖拽）：macOS / Windows / Linux 均支持。
- 「打开方式」控件：所有平台均支持。
- 删除文件：macOS / Linux 进系统回收站或 dsh-notes-trash/；Windows 不提供删除入口。
- 顶部避让窗口控件：macOS 折叠会话栏后，只有左栏额外下移让开交通灯，右侧阅读区保持不动；Windows 不触发。
DSH 版本与依赖¶
- 目标 DSH：
>=0.2.0-rc.1。 - 零三方运行时依赖：客户端 bundle 实际只
require三个平台基线模块（react、react/jsx-runtime、@deepseek-ai/dsh-client-ui-primitives），宿主侧只用 Node 内置模块。 - 所有槽位注册都包在
ctx.slots.inject()里：即使 DSH 未来删掉某个席位，插件也只是不显示，不会让启动失败。 - 客户端
inject里必须显式声明remote.session。
适用场景¶
本插件适合在 DSH 环境中需要统一管理知识库、会议记录、代码片段或草稿的用户。适合需要频繁在编辑与阅读之间切换、需要文件树与搜索、需要置顶常用条目的开发者与研究员。注意：插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。
总结¶
dsh-client-ui-notes 将笔记阅读与编辑整合进 DSH 的 Web 界面，提供文件夹树、浏览器式 tab 栏、Markdown 左编右渲、txt 编辑、搜索、置顶、拖拽移动等功能，支持跨文件夹保留状态与状态记忆。它不修改 DSH 源码，纯外部插件，适合需要在 DSH 中统一管理本地笔记的用户。更多细节与源码见目录页与 GitHub 仓库。
