refkitjs/dsh-plugin

English | 中文

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