🐋 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。

📑 目录 Table of contents

• 功能一览
• 安装 · DSH 版本对照
• 特性巡礼
  • 原生面板 · 本地文件管理器 · 自动采集与 AI 精化
  • 检索与连线 · 维护与备份 · 模型工具
  • 使用与快捷键 · 数据模型 · 配置项
• 隐私
• 安全边界
• 已知限制
• 更新日志
• License

✨ 功能一览 Features

平台：原生面板与文件管理器依赖 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 显式放行才能加载。

• 对照依据：运行时 @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

🔒 隐私 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 依次尝试，第一层成功就不往下走：

快照重建规则：满足任一条件才重建 —— 清单文件不存在 · 索引范围变了 · 距上次生成超过 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。

↑ 回到顶部