侧栏文档面板ShineFree7/dsh-doc-rail

dsh-doc-rail

一个可调整大小的右侧文档栏，用于 DeepSeek Harness Web GUI（dsh web）。它会在你的对话旁边显示一个 Markdown 或纯文本文件——这是会话交接说明的天然归宿——并具备：

- 浅色（暖纸色）和深海军蓝深色主题，可在面板中切换；
- 拖动调整宽度（双击左边缘重置为 400 px）；
- 打开任意本地 .md / .txt 路径（粘贴路径，或从最近记录中选择）；
- 自动同步：文件每 4 秒重新读取一次，因此保存后会自动显示；
- 外观、宽度、最后打开的文件和最近历史记录保存在进程内存中（页面刷新后仍保留；重启后重置，与插件本身一样）。

该面板挂载在横跨整个框架的 shell.overlay 位置——仅做增量添加，绝不替换已发布的 UI。

截图

示例内容预览（非真实文档），浅色和深色主题：

| 浅色主题 | 深色主题 |
| --- | --- |
| dsh-doc-rail 浅色主题 | dsh-doc-rail 深色主题 |

要求

- DeepSeek Harness 从源代码检出或发行版运行，且组合了 Web GUI 配置文件（dsh web），Node.js >= 24（node 部分为直接运行的纯 TypeScript；浏览器部分以预构建形式提供为 lib/client.js）。
- 该插件需要 webServer 服务，因此仅在 web 配置文件下激活。安装到仅 CLI 的配置文件中时，它会按设计保持惰性。

兼容性说明：dsh-doc-rail 针对本包开发快照时的 web 客户端 slot/layout API。如果你使用已发布的 dsh 发行版，请优先选择匹配的 dsh-doc-rail 版本（见 releases），并在安装后确认面板出现一次。

安装

从注册表安装（发布后）：

dsh plugin --profile web add dsh-doc-rail

从本地检出或 tarball 安装：

dsh plugin --profile web add /path/to/dsh-doc-rail
or
dsh plugin --profile web add ./dsh-doc-rail-0.1.0.tgz

重启 Web GUI（dsh web）——页面随后会在右侧启动时带有该栏。点击 ✕ 将其折叠；小的 📄 文档面板 胶囊按钮可重新打开它。

设置默认文档（可选）

面板启动时带有路径输入框且没有默认文件，因此可以安全地分发给任何人。要固定你的交接说明（或任意文件），请在配置文件自己的 cordis.patch.yml 中覆盖该行配置：

- replace:
- id: dsh-doc-rail
name: dsh-doc-rail
config:
defaultPath: 'C:/Users/you/Documents/handover.md'

路径可以使用 / 或 \\ 分隔符；文件以 UTF-8 文本读取。

用法

1. 粘贴完整路径（.md、.txt 或任意 UTF-8 文本文件）并按 Enter，或点击 打开。
2. 使用 最近 跳回较早的文件，使用 清空输入 重置输入框。你打开的文件会自动添加到最近列表中。
3. 浅色 / 深色 会立即切换调色板；该选择会被记住。
4. 拖动面板左边缘的细条可调整大小；双击它可重置。

隐私
一切都在本地：节点部分读取你自己 dsh web 进程内的文件，浏览器部分通过同源 JSON 路由 /dsh-doc-rail/api/doc 和 /dsh-doc-rail/api/pref 与其通信。没有网络服务，没有遥测，没有任何路径离开你的机器。

开发

npm install
npm run typecheck   # tsc --noEmit
npm run bundle      # tsdown → lib/client.js（惰性 CJS 模块表工厂）
npm run smoke       # 结构检查

浏览器打包契约记录在 harness 检出目录的 packages/client/tsdown.client.ts 中（在预设发布到 npm 之前，外部包必须复刻该契约）。

布局

package.json          # dsh.bundle + dsh.client 清单，导出
cordis.patch.yml      # 按包名插入插件行
src/index.ts          # 节点部分：基于 ctx.webServer 的 doc + pref JSON 路由
src/client/index.ts   # 浏览器部分：注册 shell.overlay
src/client/Rail.tsx   # 面板 UI（主题、调整大小、路径输入、markdown 渲染）
src/client/styles.ts  # 注入样式表（CSS 变量，无 CSS 管线）
scripts/smoke.mjs     # 结构冒烟检查

许可证

MIT — 参见 LICENSE。