@wyq183dsh-artifact-library
DSH 产物库 + 本地文件管理器：跨会话产物采集 / AI 精化 / 全文检索，以及基于 Everything 清单索引的文件搜索与目录浏览
- Stars
- 1
- Language
- JavaScript
- Created
- Aug 14, 2026
- Updated
- Sep 30, 2026
Introduction
🐋 dsh-artifact-library · DSH 产物库
DeepSeek Harness 的「作品柜 + 资料柜 + 工作台」：自动采集 AI 产出、AI 自动分类整理、一句话语义检索、AI 替你连线，外加一个内置 Everything 引擎的本地文件管理器。本地优先，数据绝不出本机。
The "deliverable vault + reference shelf + shared workspace" for DeepSeek Harness: auto-collect AI outputs, AI-organize them, semantic search in plain language, AI-suggested linking — plus a local file manager powered by a bundled Everything engine. Local-first — your data never leaves the machine.
📸 截图 Screenshots
⚠️ 截图待补（0/3） —— 目录站会自动抓取
docs/screenshots/*.png。 真图必须在运行中的 DSH GUI 里人工截取（本插件是宿主 UI 插件，无法用静态页复现）。 截什么、怎么截、命名与尺寸规范见 docs/screenshots/README.md。
| 目录视图 | 文件搜索 | 卡片视图 |
|---|---|---|
待补 01-directory.png | 待补 02-search.png | 待补 03-cards.png |
📑 目录 Table of contents
✨ 功能一览 Features
| 能力 | 说明 |
|---|---|
| 本地文件管理器（v0.7.0 新增） | 内置 Everything 引擎（MIT，见 THIRD-PARTY-NOTICES.md），毫秒级本地文件搜索：Everything 语法（ext:psd · dm:today · size:>10mb · path:项目），命中项可一键登记为产物。索引范围严格限定在「DSH 工作区 + 已登记产出所在目录」，不索引全盘，全部本地完成 |
| 自动采集 | 订阅会话事件，AI 每轮产出的文件自动进库，并记录来源会话（可回看诞生过程） |
| AI 整理分类 | 自动采集后标记「待精化」，会话内模型主动补全摘要/标签/项目；或点「立即精炼」开专属精化会话批量处理 |
| 一句话语义搜索 | artifact_find / 管理页 🔍 语义搜索：用自然语言描述（「上次那个视频素材」）就能找回，自动拆词加权打分 |
| AI 替你连线 | artifact_suggest_links / 编辑页「相关建议」：自动扫描同项目/同标签/同目录/标题相似的产出与资料，一键填入引用 |
| 整理建议单 | artifact_suggest_cleanup / 管理页 🧹：扫描重复记录、文件缺失、待精化、僵尸项目，出可执行建议单 |
| 资料库 | 文件夹一键批量导入（目录名当项目、本地正文索引），产出可关联引用的资料 |
| 项目总览 | project_overview 一句话了解某项目的产出与资料 |
| 维护 | 定时整理（去重/文件状态刷新，默认每周）、自动备份（默认保留 10 份）、导出 JSON |
| 人性化 | 撤销式操作、快捷键、批量操作、图片缩放/音视频倍速预览、缺失文件提醒 |
平台：原生面板与文件管理器依赖 Everything，仅 Windows；产物库本体（登记/检索/精化/连线）跨平台，非 Windows 上文件视图会显示不可用原因并优雅降级。
📦 安装 Install
dsh plugin add github:wyq183/dsh-artifact-library
# 数据落在 web profile 时用：
# dsh plugin --profile web add github:wyq183/dsh-artifact-library
# 或本地源码：
# dsh plugin --profile web add <本仓库路径>
# 重启 dsh web 生效
装完重启 dsh web。启动日志里应出现一行自证：
artifact-library: store at ~/.dsh/artifact-library/artifacts.json (N records)
数据存于 ~/.dsh/artifact-library/（可用环境变量 DSH_ARTIFACT_LIBRARY_DIR 覆盖）。
🧩 DSH 版本对照 Compatibility
本插件声明的 peerDependencies 下限为 >=0.2.0-rc.2。DSH 在启动/安装时会拿插件
package.json 的 peerDependencies 去比对运行时版本：不满足的插件会被判为不兼容，
需要 dsh plugin allow-version 显式放行才能加载。
| 插件版本 | 需要 DSH 运行时 | 状态 |
|---|---|---|
| v0.7.0 | >= 0.2.0-rc.2 | ✅ 当前版本 |
| v0.6.0 | >= 0.2.0-rc.2 | 原生面板第一期 |
- 对照依据：运行时
@deepseek-ai/dsh-app-boot的evaluatePluginCompatibility()， 只检查peerDependencies里@deepseek-ai/dsh/@deepseek-ai/dsh-*这两类名字， 用semver.satisfies(runtime, range, { includePrerelease: true })判定。 - 写法上用下限（
>=）而不是 caret：caret 在跨 minor 时会静默把插件挡在门外， 而带下限的范围不会反过来排掉当前运行时。
🚀 特性巡礼 Feature tour
🖥️ 原生面板（v0.6.0 起，推荐）
左侧栏 🐋「产物库」图标 → 主区整块打开产物库面板。走的是官方公开席位
（sidebar.panellist + main），不依赖任何第三方侧栏插件。
- 原生 React 渲染，样式全部读 DSH 设计 token（
--dsw-alias-*/--dsw-font-*/--dsw-radius-*/--dsw-shadow-*），自动跟随深浅主题 - 统计条、搜索、kind/状态/项目/排序筛选
- 卡片 · 列表 · 项目三视图
- 详情抽屉：图片 / 文本 / 音视频内联预览、星级打分、编辑、回收站/恢复、文件管理器定位、复制路径
🗂️ 本地文件管理器（v0.7.0）
面板顶部视图切换点「文件」→ 首次点「启动文件索引」→ 之后输入关键词即时出结果。 索引范围会在界面上如实显示，命中项可一键「登记」进产物库。
- 独立实例
DSHArtifacts：与你自己的 Everything 完全隔离，不改不卸不干扰 - 懒启动：不搜索就不启动任何进程；关闭走官方
-exit - 「目录」视图：逐层浏览工作区与产出目录，目录在前文件在后，可「打开」/「定位」/「登记」
- 主动纳管：订阅会话事件，会话的工作目录自动纳入索引范围，防抖攒批 30 秒
（
config.indexScopeDebounceMs可调），把多次会话创建合并成一次实例重启 - 模型侧也能用
search_files搜本地文件（工具描述里如实写明范围边界）
📥 自动采集与 AI 精化
- 每轮产出自动登记，默认每轮上限 20 条（设置面板可调）
- 新条目标记「待精化」，会话内模型会主动补全摘要 / 标签 / 项目
- 也可在管理页勾选条目 → ⚡ 立即精炼（或 ⚡ 精化项目 / ⚡ 精化文件夹）→ 开专属精化会话批量处理
- 精化会话选用哪个模型只作弹窗预选，绝不自动应用
🔍 检索与连线
- 语义搜索：管理页 🔍 按钮，或让任意会话的 AI 用
artifact_find（自然语言描述） - 关键词检索：
artifact_search（全文） - AI 连线：编辑产物时点「扫描相关条目」，或让 AI 用
artifact_suggest_links - 整理建议：管理页 🧹 按钮，或让 AI 用
artifact_suggest_cleanup
🧰 维护与备份
- 定时整理：默认每 7 天（
cleanupIntervalDays，可设 1–365），整理前自动备份 - 自动备份：默认保留 10 份（
backupKeep，可设 1–100） - 导出 JSON：整库一键导出
🤖 模型工具 Model tools（13 个）
12 个产物工具：register_artifact · artifact_list · artifact_get · artifact_update ·
artifact_trash · artifact_restore · artifact_stats · artifact_search · artifact_find ·
artifact_suggest_links · artifact_suggest_cleanup · project_overview
外加 1 个文件搜索工具：search_files（本地文件名/路径检索，索引范围与面板一致）
🕹️ 使用 Usage
- 完整管理页（兜底入口）：侧栏脚部「产物库 · 网页版」，或访问
<dsh web 地址>/ext/artifact-library/（端口由运行时决定，插件会向宿主索取绝对地址）。 登记 / 导入文件夹 / 精炼 / 语义搜索 / 整理建议目前仍以此页为主（第二期搬进原生面板） - 文件搜索：面板 →「文件」→ 启动索引 → 输入关键词
- 快捷键：
/搜索 ·n登记 ·g回收站 ·1/2/3视图
🗃️ 数据模型 Data model
id / kind(deliverable|reference) / source / path / mime_type / title / summary / project / artifact_type / tags / status / stars / notes / references[] / contentIndex / session_id / agent_id / needsRefine / refineRequested / created_at / updated_at / trashed_at
⚙️ 配置项 Config
| 位置 | 键 | 默认 | 说明 |
|---|---|---|---|
| 环境变量 | DSH_ARTIFACT_LIBRARY_DIR | ~/.dsh/artifact-library | 数据目录 |
| Cordis config | dataDir | 同上 | 同上（环境变量优先） |
| Cordis config | indexScopeDebounceMs | 30000（最小 1000） | 会话工作区变化后攒批刷新索引范围的防抖时长 |
| Cordis config | maxAutoPerTurn | 20 | 每轮自动采集上限 |
| 设置面板 | autoCollect | true | 自动采集开关 |
| 设置面板 | cleanupEnabled / cleanupIntervalDays | true / 7 | 定时整理 |
| 设置面板 | backupKeep / backupOnCleanup | 10 / true | 备份份数与整理前备份 |
| 设置面板 | importMaxSizeMB | 50 | 文件夹导入的单文件上限（MB） |
| 设置面板 | searchLimit | 20 | 语义搜索默认返回条数 |
🔒 隐私 Privacy
- 全文索引、导入、导出、语义搜索全部本地完成，零外传
- 无遥测、无上报
- 文件索引不索引全盘：范围 = DSH 工作区 + 已登记产出所在目录
DSHArtifacts是独立 Everything 实例，与你自装的 Everything 互不干扰
🛡️ 安全边界 Security（v0.3.1 起）
- 敏感路径防护：凭据/密钥类文件名（
credentials/creds/secret/token/api key/.env/.pem/.key/id_rsa等）与凭据目录（.ssh/.gnupg/.aws/.azure/.kube/.docker/.npmrc）下的文件，登记与导入一律拒绝，防止密钥泄露进全文索引与文件接口 - 来源限制：
/ext/artifacts的文件内容读取（/:id/file、单条记录、/export）与全部写操作仅限本机回环（127.0.0.1）；局域网来源（host: 0.0.0.0绑定）只读浏览不含文件正文的元数据（列表/搜索/统计/建议）。局域网内预览/编辑/登记/回收等操作用不了，属预期行为——安全优先 - 文件操作闸门：文件操作（打开/定位）只放行索引范围内的路径，范围外一律 403
- 文件索引路由：
/ext/artifacts/files*（搜索 / status / start / stop）仅限本机回环，局域网来源 403 - 数据文件
~/.dsh/artifact-library/为本地 JSON，含全文索引，注意本机文件权限
⚠️ 已知限制 Known limitations
这一节是如实记录，不是免责模板。以下每一条都在真机上实测复现过 （完整事故记录见 docs/RISK-ANALYSIS.md）。
1. 文件索引是「三层降级」，首选层是快照
索引按 filelists → ntfs → folder 依次尝试，第一层成功就不往下走：
| 层 | 机制 | 代价 / 已知缺陷 |
|---|---|---|
| ① filelists（首选） | 只让 Everything 加载一份 .efu 文件清单，不遍历目录、不索引卷 | ✅ 不需要管理员权限 · 不挑磁盘格式 · 实测 2.3 秒就绪 · 多目录全部生效 ⚠️ 清单是快照 —— 文件增删后不会自动更新 |
| ② ntfs | 读卷 MFT + ntfs_volume_include_onlys 限制范围 | ✅ 快（实测 30 秒内就绪） ⚠️ 需要管理员权限（普通用户直接失败） ⚠️ 只认第一个路径 —— 多目录场景直接残废 ⚠️ 要读整卷 MFT，隐私上不如清单干净 |
| ③ folder（保底） | 让 Everything 自己逐层遍历目录树 | ⚠️ 范围里含 junction / 符号链接（如 pnpm 的 node_modules）会僵死（CPU 0%、IPC 无响应）⚠️ 特定目录组合会活锁（CPU 100%、库始终 0 KB）—— 实测 11 万项烧到 215 秒仍不就绪 ⚠️ 这是第三方组件的固有缺陷，靠排查无法穷尽规避 |
快照重建规则：满足任一条件才重建 —— 清单文件不存在 · 索引范围变了 · 距上次生成超过 6 小时。
实际影响：新建的文件最多 6 小时后才可能出现在文件搜索结果里。 想立刻看到，重启 dsh 或改动索引范围（都会立即触发重建）。 对「搜项目产出」这个场景够用（产出不是每分钟都在变），但它不是实时索引。
三层全失败时：会明确报错 + 清理实例 + 不影响产物库其它功能，只是「文件」视图显示不可用原因。 引擎懒启动，你不动文件视图就一个进程都不会起。
2. NTFS 模式只认单目录（多目录场景请假定走 folder）
官方文档说 ntfs_volume_include_onlys 是「分号分隔的文件夹列表」，
实测只认第一个路径。因此只要索引范围不止一个目录 —— 而这是常态
（工作区 + 产出目录，两个就够）—— 就不能指望 NTFS 模式，
普通用户会落到已知不可靠的 folder 回退路径上。
3. 仅 Windows
文件索引硬依赖 Everything（vendor/everything/，MIT，版本已锁 1.5.0.1423b）。
非 Windows 平台上文件视图优雅降级为「不可用」，产物库本体功能不受影响。
4. 其它已实测的边界
- 范围规模守卫：单次范围估算超过 60,000 项时会提前返回，避免把 Everything 拖死
（实测 41 万项的目录会让它启动即僵死；排掉
node_modules后立刻恢复） - 不存在的目录会被跳过：索引范围里混入已删除的目录曾导致实例完全不响应 IPC，现已过滤并告警
- 「额外索引目录」尚未接线：
lib/index.js会读settings.indexExtraDirs， 但ArtifactStore.getSettings()/updateSettings()的白名单里都没有这个键， 设置面板也没有入口 —— 也就是说它恒为[]。 当前生效的范围实际只有「DSH 工作区 + 已登记产出所在目录」。 想索引别处，暂时只能把该目录登记为产物、或把它设为会话工作区 - 杀毒软件可能拦截
Everything.exe：目前只能表现为启动失败，尚无专门的人话提示 - Everything 1.5 仍是 beta：版本已锁定，升级前必须重跑
RISK-ANALYSIS.md里的全部对照实验 - 命名注意：
cordis.patch.yml里的id: artifact-library是 Cordis 补丁行 id （对应lib/index.js的export const name = 'artifact-library'）， 与@dsh-external/dsh-artifact-library这个包名不是一回事，改动时别搞混
📜 更新日志 Changelog
v0.7.0（2026-09-30）· 本地文件管理器
- 内置 Everything 引擎（
vendor/everything/：Everything 1.5.0.1423b 便携版 + ES 1.1.0.38，均 MIT） - 索引范围严格限定：DSH 工作区 + 已登记产出所在目录。
实现方式
auto_include_fixed_volumes=0+ 清空卷列表 +folders=白名单。 实测：限定前入库 3,217,522 条 / 库 118 MB → 限定后 6 条 / 库 422 bytes （「额外目录」的读取路径已预留，但写入路径尚未接线，见 已知限制） - 索引模式三层降级：filelists（首选）→ ntfs → folder（保底）， 普通用户无需管理员权限也能用（见 已知限制）
- 独立实例
DSHArtifacts：与用户自己装的 Everything 完全隔离，不改不卸不干扰 - 懒启动：不搜索就不启动任何进程；关闭走官方
-exit（强杀会丢范围配置） - 新增 HTTP 路由
/ext/artifacts/files*（搜索 / status / start / stop），仅限本机回环访问 - 面板新增「文件」视图：Everything 语法搜索、命中统计、一键登记为产物、复制目录
- 「目录」视图（文件管理器形态）：逐层浏览工作区与产出目录
- 主动纳管：订阅会话事件，会话的工作目录自动纳入索引范围，防抖攒批 30 秒
- 文件搜索工具：模型侧也能用
search_files搜本地文件（描述里如实写明范围边界） - 安全闸门：文件操作只放行索引范围内的路径；文件索引路由仅限本机回环
- 离线自验 24 项 + 路由 harness 10 项，全绿；含三条硬断言： 范围外路径零泄漏 · 中文文件名不乱码 · 全盘可见量受控
v0.6.0（2026-09-30）· 搬进 DSH UI 第一期
- 主面板走官方席位：
sidebar.panellist（左侧栏图标）+main（主区 keyed slot 面板） - 原生 React 渲染：统计条、搜索、筛选、三视图、详情抽屉、星级、编辑、回收站、定位、复制路径
- 样式全部读 DSH 设计 token，自动跟随深浅主题
- 完整管理页保留为兜底入口（登记 / 导入 / 精炼 / 语义搜索 / 整理建议 第二期搬入）
- 宿主侧 REST API 与数据零改动；客户端
apply永不抛出 - ⚠️ 客户端 entry 抛异常 = 整个应用起不来（2026-09-28 的教训），所以三条约束不能松：
apply全程 try/catch、用ctx.get('slots')而非ctx.slots、不导出inject
⚖️ License
MIT © 2026 dsh-artifact-library contributors
第三方组件（Everything / ES 等）的许可与来源见 THIRD-PARTY-NOTICES.md。