素材库 yingqi-studio/dsh-material-library

dsh-material-library

给 DeepSeek Harness（dsh）用的素材库：把对话里产出的东西收起来——文件夹、文件、笔记——按真实文件夹存放，打上标签，一键跳回它来自的那段聊天。

三栏视图中的素材库

中文说明

功能

- 从对话采集。 会话标题栏里的按钮，加上素材库里的 从对话采集 / Collect from chat 按钮，会打开选择器：选一段对话，浏览它的工作目录，挑一个文件夹或文件，给条目起名，选素材库文件夹和标签。条目指向原始路径，不复制任何内容。
- 真实文件夹，真实文件。 笔记就是磁盘上的 .md 文件；文件夹树就是素材库根目录下的目录树（默认 ~/.dsh/materials）。标签存在旁边的 .index.json 里。两者都能在应用外编辑。
- 像 Finder 一样浏览。 来源列表（全部素材 / 文件夹 / 标签）· 列表视图，显示名称、更新时间、文件夹和标签 · 详情面板，带文件卡片、默认应用按钮和「打开方式…」菜单。
- 打开方式… 调用 macOS 的 open 命令：默认应用，或从菜单里挑另一个已安装的应用，或在 Finder 中显示。图片内联预览；文本和 Markdown 在详情面板里渲染。
- 像聊天一样阅读。 Markdown 按对话消息的排版渲染——标题、嵌套列表、引用、代码块、表格、分隔线——条目指向素材库外的文件时也一样。
- 回到来源。 对采集来的条目，Open in original session 会切到那段对话，并在右侧边栏打开对应文件夹。
- 一切皆可编辑。 在侧边栏重命名或删除文件夹、标签（重命名标签会改写所有出现处；重命名文件夹会移动其中的文件），编辑任意条目的名称 / 文件夹 / 标签，搜索名称、正文和标签。
- 版本历史。 每次保存都把上一版正文留在 .history/ 下（每个文件最多 30 版）。在详情标题栏打开 Versions，在面板里读任意版本，然后恢复——恢复前会先给当前正文拍快照，所以恢复可以撤销。注意：引用和文件夹没有版本。
- 把引用复制进素材库。 采集来的条目可以变成素材库里的真实文件（收进库 / Copy into library）；原始文件不动。
- 导入目录树。 /import 把你主目录下任意位置的文件或目录复制进素材库（每次最多 2000 个文件），沿用同一套防冲突命名。

采集对话框

安装

dsh plugin --profile <your-profile> add dsh-material-library

已发布到 npm：dsh-material-library；直接从 GitHub 安装也可以：dsh plugin --profile <your-profile> add github:yingqi-studio/dsh-material-library。
在 DSH Desktop 里打开 Plugins，搜索名称，然后在那里安装。重启 dsh web（或刷新页面），资料库就会以图标形式出现在侧边栏。

需要宿主支持 sidebar-entry 和 right-sidebar 插槽（dsh.web 0.2.x）。engines.dsh 声明为 >=0.2.0。

内容存放位置

~/.dsh/materials/ # library root (override with the plugin config root)
├── .index.json # tags for notes, plus the references you collected
├── .rules.json # auto-filing rules (see below)
├── 使用说明.md # a note = a real markdown file └── 客户项目/ # a folder = a real folder └── 需求.md

在插件配置里设置 root，就能把资料库挪到别处。写入串行执行，并且是原子操作（.tmp + rename）；路径限制在资料库根目录内，收集的目标必须留在你的主目录里。

HTTP API

UI 通过 /api/dsh-materials 下的同源 JSON 路由与宿主通信（不生成 remotes，所以保持零依赖）：

| 方法 | 路由 | 用途 |
| GET | /health | 资料库根目录、就绪状态 |
| GET | /home | 主目录（选择器的回退起点） |
| GET | /state | 文件夹、笔记、引用、标签计数 |
| GET | /list?path= | 列出资料库之外的目录（供选择器使用） |
| GET | /file?path= | 读取笔记 |
| GET | /ref/preview?id= | 读取引用的文本文件，供详情面板使用 |
| GET | /ref/raw?id= | 引用文件的原始字节（图片） |
| GET | /openers?path= | 能打开目标的已安装应用，带图标 |
| GET | /search?q=&tag= | 搜索名称、正文和标签 |
| GET | /session-times | 每个会话的最后修改时间（选择器排序） |
| POST | /create /update /delete | 笔记 |
| POST | /folder /folder/rename /folder/delete | 文件夹 |
| POST | /tag/rename /tag/delete | 标签 |
| POST | /ref/add /ref/update /ref/delete | 收集的引用 |
| POST | /open | 用操作系统打开 / 定位目标 |
| GET | /versions?path= | 笔记的已保存版本（id、时间、大小） |
| GET | /version?path=&id= | 读取某个已保存版本 |
| POST | /restore | 恢复某个版本（先给当前正文做快照） |
| POST | /ref/copy | 把收集的引用复制进资料库，成为真实文件 |
| POST | /import | 把主目录内的文件或目录复制进资料库 |
| POST | /archive | 把文件或文件夹归档进资料库作为引用（幂等；对已归档的路径合并标签） |
| GET | /rules | 自动归档规则（根目录、文件夹、标签、上次运行） |
| POST | /rules/run | 立即运行某个会话的规则 |
| POST | /rules/delete | 忘记某条规则 |

所有写操作都经过同一个串行存储；冲突（重名、文件夹非空、未知应用）会以可读的 4xx 错误返回。

智能体工具：materials_archive

定时任务可以把自己的产出归档。宿主注册了一个工具 materials_archive，每个会话都能用：

materials_archive(path="out/", folder="日报/2026-11", tags=["日报"], include=".html,.md")

- path —— 文件或文件夹（支持 ~；相对路径按会话的工作目录解析）。省略时用工作目录。
- folder —— 材料库里的文件夹；留空或省略则归到根目录。按需创建。
- tags —— 与条目已有的标签合并。
- depth —— 1（默认）归档文件夹里直接包含的文件，0 把文件夹本身作为一个条目归档，最大 12。
- include —— 逗号分隔的后缀/glob 过滤，例如 .html,.jpg 或 .png。
- limit —— 归档 N 个条目后停止（默认 50，最大 200）。

按路径幂等：再次归档同一路径只会刷新它的标签和文件夹，不会新增第二个条目，所以每天跑的任务直接再调一次就行。文件不会被移动或复制 —— 条目只是一份引用。

对定时任务，在任务提示词末尾加一行，类似：

跑完把 out/ 收进材料库，folder 用「日报/当月」，tags 用 ["日报"]。

自动归档：归档一次，之后持续归档

归档一次产出，也是一个决定：「这东西会一直产出」。材料库会记住它，之后每次在该文件夹里工作的定时运行结束时，都会自动归档新文档 —— 不用提示词指示，也不用额外调用工具。

第一次归档通常由你来做：你把任务产出的第一份日报归档。没真正归档过就不会留下任何记忆，所以从没人归档过的任务在材料库里不留痕迹。

materials_archive(path="out/", folder="日报", tags=["日报"]) # first run, by hand
... the task writes out/2026-11-03.html on its next run ...
... end of that run: out/2026-11-03.html is already in 日报 ...

- 只对定时运行生效。 规则由任何一次真实归档创建（通常是你，在聊天里），但只在定时任务发起的那一轮结束时触发* —— 它的用户消息里带着定时提醒。普通聊天轮次结束时不会归档任何东西。
- 规则跟着文件夹走，不跟着聊天走。 它对归档它的那个会话生效，也对任何工作目录包含该文件夹的定时运行生效，所以第一次归档是在任务自己的会话里做的，还是在别的对话里做的，都无所谓。
- 归档产出，不归档临时文件。 指向一个文件夹，只归档文档 —— pdf、word、excel、ppt、html、markdown、csv 之类（.json、.log、.tmp、截图和点文件留在磁盘上）。文件夹里一个文档都没有时，回退为归档全部，所以产出真的是 .json 的任务不会被悄悄清空。传 include 可以覆盖。
- 规则会记住归档过哪些文件类型：归档 out/2026-11-02.html，规则就只盯 out/ 里的 .html。归档单个文件时，记住它的文件夹和类型。
- 归档一个混合了四种文件类型的文件夹，不会留下任何规则（那个文件夹不算一件成品）；归档工作目录本身也永远不会变成规则。
- 按会话 + 文件夹 + 类型作为键，所以再次归档同一个文件夹只会扩展它的标签。深度上限为 3，一次运行最多归档 50 个条目。
- 左栏的 自动归档 下会列出这些规则；悬停某一行并点击 × 即可停止一条规则。
- 规则存放在库根目录的 .rules.json 里；目标消失时跳过，不会导致失败。
- 在对话里归档也能用，并且只归档你指定的内容；它同时会创建规则，之后这条规则会等待该文件夹的下一次定时运行。

说明与限制

- 收录的条目是引用，不是副本：原文件移动后，条目会显示为缺失。
- 自动归档只对定时任务运行，而且只针对你归档过一次的文件类型——普通对话永远不会自己往库里填东西。
- 只有 home 目录内的目标才能被收录。
- 你手动拖进库的文件会被列出，但在 UI 里给它们打标签之前没有标签。
- Markdown 渲染器是内置的（约 150 行，无依赖）：覆盖常见语法，但不支持行内 HTML、脚注或任务列表复选框。
- 版本只对笔记存在，对引用和文件夹不存在。
- materials_archive 归档的是引用，所以重跑一个会覆盖输出的任务，仍然指向同一个（新的）文件；而每次运行都写一个带时间戳新文件的任务，每跑一次就多一个条目。

中文说明

把对话里产出的目录、文件和笔记收进一个材料库：真实文件夹 + 标签，Finder 的观感，点开像对话消息一样阅读，一键跳回原始会话。

- 从对话采集：会话标题栏按钮 / 库内「从对话采集」按钮 → 选对话、浏览目录、选文件或目录、起名、选库内文件夹与标签。收进来的是引用，原文件不动。
- 真实目录：笔记就是磁盘上的 .md，文件夹就是目录树（默认 ~/.dsh/materials），标签存在 .index.json。
- 三栏浏览：左栏 全部材料 / 文件夹 / 标签；中栏列表（名称、更新、文件夹、标签）；右栏文件卡 + 默认应用 + 「打开方式」菜单。
- 打开方式：默认应用 / 其它已安装应用 / 在 Finder 中显示；图片行内预览，文本与 Markdown 在右栏渲染。
- 像对话一样阅读：标题、嵌套列表、引用、代码块、表格、分隔线，引用外部文件时同样渲染。
- 在原始会话右侧打开：切回那个对话并打开右侧文件面板。
- 都能改：文件夹、标签可就地改名或删除（标签改名全库生效、文件夹改名带走文件），条目的名称/文件夹/标签可编辑。
- 历史版本：每次保存都把上一版留在 .history/（每个文件最多 30 份）；右栏头部「历史版本」→ 选中看正文 → 「恢复这个版本」。恢复前会先给当前内容拍一份快照，所以恢复本身也能撤回。
- 收进库：引用型条目可以复制成库里的真实文件，原件不动。
- 导入：/import 把 home 目录里的一个文件或一整个目录复制进库（单次上限 2000 个文件）。
- 只收文档类成品：指向一个目录时，默认只收 pdf / word / excel / ppt / html / markdown / csv 这类成品，过程文件（.json/.log/.tmp/截图/. 开头）留在原处；目录里一个文档都没有时退回全收（产物本来就是 .json 的任务不会被清空）。显式给 include 可覆盖。
- 自动归档规则：你手动收过一次，材料库就把这次收录记成规则——只记「哪个目录 + 哪几种文件类型」（收的是 日报.html，就只盯 .html）。没有人手动收过，就什么都不记。规则只在该目录所属的定时任务跑完时触发，把新出的同类成品自动收进来；普通对话轮次结束不会自动收录。规则跟着目录走，所以第一次在哪个对话里收的都无所谓。左栏「自动归档」可看到规则，悬停点 × 即停。
- 给 agent 的工具 materials_archive：定时任务可以把最终成品收进库。任务 prompt 末尾加一句「跑完把 out/ 里最终成品收进材料库，folder 用日报/当月，tags 用 ["日报"]」即可；收过一次后同类文件以后自动进来，不必每次写。同一条路径重复归档只更新标签与文件夹，不会重复入库，原件不动。

安装：dsh plugin --profile <profile> add dsh-material-library（未发布 npm 时用 github:yingqi-studio/dsh-material-library）。

License

MIT