@refkit/dsh-plugin

dsh plugin --profile web add @refkit/dsh-plugin

@refkit/dsh-plugin

[English](README.md) | 中文

DeepSeek Harness（dsh）插件，封装了 refkit 参考搜索库：将经过许可证归一化处理的创意素材搜索能力，变成原生 agent 工具，并配有网页卡片，在每条结果上展示许可证与使用判定。

• refkit_search — 一次调用即可扇出到多达 24 个来源(Openverse 图片与音频、Met、Art Institute of Chicago、Wikimedia Commons、Rijksmuseum、Smithsonian、Internet Archive、Project Gutenberg、PoetryDB、Poly Haven 纹理与 HDRI、ambientCG、Europeana、Unsplash、Pexels、Pixabay、Flickr、Freesound、Jamendo、Brave、nailbook),合并并重新排序结果,并为每条结果返回其来源 id、许可证 id、canonical 链接、音频和视频的时长（来源提供时）,以及——当你传入 intent 时——使用判定和一条可直接使用的署名文本。
• refkit_rights — 针对不同的使用意图重新校验同一条许可证,无需重新搜索。
• 网页卡片 — 缩略图网格;每个卡片都带来源和许可证标签;视频显示封面帧并叠加播放标记,音频显示专辑封面,两者都带 m:ss 时长徽章;绿 / 蓝 / 红 / 黄四色徽章分别对应 allowed(允许) / credit required(需署名) / not allowed(不允许) / needs review(需人工复核);一键复制署名文本。

24 个来源中有 13 个无需任何密钥即可使用（Openverse 图片与音频、Met、Art Institute of Chicago、Wikimedia Commons、Rijksmuseum、Internet Archive、Project Gutenberg、PoetryDB、Poly Haven 纹理与 HDRI、ambientCG、nailbook）。其余来源在「插件（侧边栏）→ refkit → 包含的组件 → refkit」里填入免费密钥即可启用。

安装

dsh plugin --profile web add @refkit/dsh-plugin
# 或直接从 GitHub 安装(预构建的产物已提交到仓库):
dsh plugin --profile web add github:refkitjs/dsh-plugin

重启一次 dsh web host,让该 profile 加载该 bundle。已在 @deepseek-ai/dsh 0.1.7-rc.2 和 0.2.1-rc.2 上测试通过;要求 dsh 0.1.x 且不低于 0.1.7-rc.2,或 0.2.x 且不低于 0.2.1-rc.2(^0.1.7-rc.2 || ^0.2.1-rc.2),更低版本以及 0.2.0 预发布版的 dsh 会拒绝加载该插件。dsh 目前处于开发者预览阶段,其插件 API 在各个 release candidate 之间会发生变化。

装着 refkit 0.2.0 或 0.3.0 时把 dsh 升级到了 0.2.1?dsh 0.2.1 会拒绝这两个版本,先移除再重新添加即可:dsh plugin --profile web remove @refkit/dsh-plugin,然后 dsh plugin --profile web add @refkit/dsh-plugin。

配置

密钥和调优参数在「插件（侧边栏）→ refkit → 包含的组件 → refkit」中设置(命名空间为 refkit);修改在下一次调用时生效,无需重启。所有 key 字段都是 secret 类型:设置页不会回显已保存的值(只显示 Set / Not set 标记),不会被记录日志,也不会返回给模型,并以明文形式存储在该 profile 的 cordis.patch.yml 中(文件权限 0600)。某个 key 留空时会依次回退读取下表列出的环境变量(REFKIT_* 优先)——与 @refkit/mcp 读取的变量名相同,因此同一份 .env 可以同时服务这两者。手动编辑后校验失败的 cordis.patch.yml 会使插件启动失败,直到修复为止。

字段 · 环境变量(先匹配者优先) · 启用的来源

unsplashAccessKey · REFKIT_UNSPLASH_KEY, UNSPLASH_KEY · unsplash

pexelsApiKey · REFKIT_PEXELS_KEY, PEXELS_KEY · pexels, pexels-video

pixabayKey · REFKIT_PIXABAY_KEY, PIXABAY_KEY · pixabay, pixabay-video

flickrApiKey · REFKIT_FLICKR_KEY, FLICKR_KEY · flickr

smithsonianApiKey · REFKIT_SMITHSONIAN_KEY, SI_KEY · smithsonian

braveToken · REFKIT_BRAVE_KEY, BRAVE_TOKEN · brave

freesoundToken · REFKIT_FREESOUND_KEY, FREESOUND_TOKEN · freesound

jamendoClientId · REFKIT_JAMENDO_CLIENT_ID, JAMENDO_CLIENT_ID · jamendo

europeanaApiKey · REFKIT_EUROPEANA_KEY, EUROPEANA_KEY · europeana

openverseToken · REFKIT_OPENVERSE_TOKEN · 提升 Openverse 速率限制(可选)

字段 · 默认值 · 含义

sources · [] · 要启用的来源 id;为空 = 启用所有已配置 key 的来源

limit · 12 · 每次调用默认返回的结果数(1–30);也限制 met、rijksmuseum、polyhaven、polyhaven-hdri 的逐条详情拉取数量

poolFactor · 2 · 排序融合(rank-fusion)的候选池倍数(1–4)

deadlineMs · 15000 · 整次搜索的截止时间

timeoutMs · 10000 · 单个来源的超时时间

rerank · true · 对 title、description、tags 和 excerpt 做词法重排序(支持 CJK)

sourceConfidence · true · 对结果批次中完全没有提及查询词的来源降权

userAgent · refkit-dsh-plugin/<version> · 随请求发送给各来源的 User-Agent

工具

refkit_search

参数 · 类型 · 含义

query · string · 要搜索的内容

modalities · image video audio text · 默认 ["image"]

intent · internal-moodboard commercial-product ai-generation-input redistribution · 为每条结果附加使用判定和署名文本

gateFor · 同上 · 仅返回许可证允许该用途的结果

sources · string[] · 限定到特定的来源 id(例如 HDRI 用 polyhaven-hdri,音频用 openverse-audio)

limit · 1–30 · 默认取自配置

cursor · string · 沿用上一次结果里的 nextCursor 继续翻页

controls · object · orientation、color、language、sort、safety、license、media、creator、text、page

minRelevance · 0–1 · 丢弃重排序分数低于该值的结果

explain · boolean · 在 meta 下附带每个来源的诊断信息

每条结果都标明其来源 id(source),并带有许可证、canonical 链接、缩略图(视频的封面帧、音轨的专辑封面),音频和视频在来源提供时还带有 durationSec(时长,秒);width/height 是原件尺寸,来源未提供时取预览文件的尺寸。

示例提示词:“find me reference photos of brutalist libraries I can use in a commercial pitch deck”、“给我找几张可以商用的赛博朋克街景参考图”、“a public-domain poem about the sea for a poster”、“找一张户外 HDRI 用来给产品渲染打光”、“一段用于游戏预告片的短雨声音效”。

refkit_rights

必填:license、intent、canonicalUrl;可选:licenseVersion、author、title、editorialOnly、jurisdiction、userJurisdiction、facts。返回 decision、reasons、confidence、attribution、disclaimer。

开发

pnpm install
pnpm test                 # vitest,进程内运行,无需网络
pnpm build                # lib/index.js(host 半)+ lib/client.js(browser 半)+ lib/types
node scripts/check-client-bundle.mjs
REFKIT_LIVE=1 node scripts/smoke-host.mjs "forest path"   # 一次真实的 Openverse 搜索
dsh plugin --profile web add file:$PWD                    # 安装本地构建产物

lib/ 目录已提交到仓库,因此 github: 方式安装无需额外构建;若该目录与源码不一致,CI 会失败。

非法律意见

判定结果是基于来源声明的许可证事实所做的保守启发式推断。它们说明的是来源允许你做什么,并不构成权利审查(rights clearance)。

License

Apache-2.0