资料库 · dsh-library

DeepSeek Harness 的本地产出资料库插件。

把每次对话、每个项目产出的东西收进一处：文档、表格、图片、音视频、链接、附件 —— 以自带页面的样子出现在 DSH 里，可浏览、可检索、可预览、可整理，也能让助手读取并按路径引用。

目录

功能一览 · 界面 · 快速开始 · 配置 · 架构 · HTTP API · 文档直接预览 · 安全设计 · 测试 · 路线图 · 与资产库的边界 · 排障 FAQ

功能一览

界面

三栏布局 —— 左树 / 中列表 / 右内容，点开任意一条是页内「放大卡片」：

网格视图，媒体卡片带类型角标与标签：

右栏直接预览 Markdown / Word / Excel / 代码（真实渲染，非截图拼接）：

Markdown	Word 文档

快速开始

前置：Node.js ≥ 22、已安装 DeepSeek Harness、本仓库已在本地。

# 1) 装进 profile（官方 CLI 负责 bundle 层）
& 'F:\DSH\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'D:\dsh-library'

然后编辑 C:\Users\<你>\.dsh\profiles\desktop\package.json：

1. 把依赖规格从 link: 改成 file:（file: 让 pnpm 复制成实体目录，解析链才完整）；
2. 把 dsh-library 加进 dsh.profile.bundles 数组 —— 不加这一行，插件不会进组合配置树。

{
  "dependencies": { "dsh-library": "file:D:/dsh-library" },
  "dsh": { "profile": { "bundles": ["…", "dsh-library"] } }
}

# 2) 同步一次，然后完全重启 DSH（托盘也退出）
& 'F:\DSH\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop install

重启后侧边栏出现「资料库」入口即成功。改完源码不生效、或想核对安装状态，见排障 FAQ。

配置

cordis.patch.yml 里按行 id 覆盖（全部字段都有默认值，不配也能跑）：

- id: library
  name: dsh-library
  config:
    root: 'D:/dsh-library-data'   # '' = 退回 <DSH_HOME>/library
    includeHidden: false
    maxDepth: 8
    maxFiles: 20000
    pageSize: 60
    cacheMs: 1500            # 扫描缓存毫秒数；写操作会立刻作废缓存，要绝对实时就设 0
    maxUploadBytes: 67108864  # 单次入库上限（64 MB）
    allowAgentSave: true     # 助手可把新产出存进库
    allowAgentModify: false  # 助手不可改动 / 移动 / 删除已有资料

库根解析顺序：显式配置 → 出厂默认（lib/config.js 的 LIBRARY_DEFAULTS.root）→ 显式 '' 退回 <DSH_HOME>/library。 出厂默认刻意写死一个非系统盘路径：库根放错会静默留在 C 盘上，等用户发现时已经积了几 GB —— 把默认值与补丁层设成同一处，堵掉这个失败模式。换机器时两处一起改。

架构

插件分两半，同包不同进程侧：

dsh-library/
├── index.js              # 宿主半入口：激活、配置、路由挂载
├── lib/
│   ├── config.js         # 配置默认值与解析
│   ├── scan.js           # 递归扫描 + 目录汇总（唯一事实来源）
│   ├── store.js          # .library-index.json（只存人的输入：标签/备注/来源）
│   ├── service.js        # 内核：快照缓存、列表/搜索、文档解析、写操作
│   ├── routes.js         # HTTP 面：15 个端点，先过信任栅栏再干活
│   ├── paths.js          # 路径归一化与包含检查（安全核心）
│   ├── kinds.js          # 类型目录（未收录扩展名归 file，不是忽略）
│   ├── names.js          # 名称校验与去重（名字 (2).ext，Windows 保留名）
│   └── office.js         # 零依赖 xlsx/docx 解析（自写最小 zip 读取器）
└── client.js             # 浏览器半：三栏面板，经 window.__ModuleLoader__ 注入

原生感的来源 —— DSH 的界面本身由槽位组合而成，一个原生页面只有一种做法：

侧边栏条目  slots.inject('sidebar.panellist')  →  register({ id, order, label }, Icon)
页面本体    slots.inject('main')               →  register({ key: <同一个 id> }, Panel)

同一个 id 连接两者，点击侧边栏即切换页面。没有修改 DSH 安装本体（那会被应用更新覆盖）——所谓「内置」是走插件组合层，体验上与自带页面无差别。

扫描是唯一事实来源，索引只保存人的输入：

<库根>/
├── .library-index.json     # 标签 / 备注 / 来源；扫描自动跳过它
├── 分组/
│   ├── 笔记.md
│   └── 2026/
│       └── 截图.png
└── 附件.zip

你在文件管理器里删掉或改名，资料库下一轮扫描就跟着变，不会留下幽灵条目；扫描默认跳过点开头条目、node_modules / .git、Office 临时文件与系统垃圾。

HTTP API

一条前缀路由承载全部端点，全部先过浏览器信任栅栏：

文档直接预览

/document 按扩展名把文件解成结构化内容，右栏直接查看：

失败按 code 分级而不是合成一句「打不开」，因为处置方式完全不同： ENCRYPTED(422) → 去密码另存；NOT_XLSX / CORRUPT 等(422) → 重新导出；UNSUPPORTED(415) → 换格式；TOO_LARGE(413) → 下载。

三条实现约束：CSV 用状态机解析（引号内换行/逗号、"" 转义，split('\n') 三种全错）；文本上限 512 KB 只读前 N 字节，截断是正常结果（truncated: true + 界面一行小字）而非错误态；语义失败统一 4xx 而不是 5xx——5xx 的运维口径会指向「资料库自己坏了」。

安全设计

所有能从库根读到字节的路径都过同一套收口，缺一不可：

1. 路径包含检查（resolveInside）：归一化后必须仍落在库根内，..、盘符、绝对路径一律拒绝。Windows 上大小写不敏感 + 给根补分隔符（否则 C:\lib2 会被 C:\lib 判成在内）；逃逸校验在解码之后（%2E%2E 还原成 .. 也要拦住）。
2. 隐藏段拒绝：任何一段以点开头直接 403 —— 索引文件与库根元数据不在可读范围。
3. HTML / SVG 强制 CSP: sandbox：能携带脚本的格式在流式返回时加沙箱头。少了它，「在资料库里预览一个页面」就等于在 DSH 页面所属的源里执行别人写的脚本。
4. 信任栅栏按请求解析：裸 Web 路由不继承 Connection 服务的 Host/Origin 检查，每个请求先过栅栏再做任何工作（Connection 行可能在路由注册之后才激活，快照式捕获会留永久空洞）。
5. 助手权限收窄：allowAgentSave 只开「往里放新东西」；整理、改名、删除一律由人在页面上做。

入库四端点只新增不覆盖；写入先落 .part 临时文件再改名（.part 本就在扫描跳过规则里，写一半失败不会留下半截文件）；批量导入只认普通文件（lstat，符号链接跳过）。

测试

五套离线测试、500+ 项断言，不启动 DSH 也能跑：

npm test        # logic / scan / client / host / office 五套
npm run check   # 只读诊断真实库根

路线图

与资产库的边界

dsh-asset-library（项目素材索引）与本插件（跨会话资料库）独立并存、互不依赖、不互相替代：

资料库是跨会话的中央库，刻意不注册任何右侧栏停靠面——从「一次会话的侧栏」打开跨会话的库，坐标系不对。契约测试有一条断言守着「不注册右侧栏 tab」别悄悄回来。

排障 FAQ

powershell -NoProfile -ExecutionPolicy Bypass -File "D:\dsh-library\tools\sync-all.ps1"

node tools/install-check.mjs    # 只读，26 项