素材授权检索 refkitjs/dsh-plugin

@refkit/dsh-plugin

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

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

十一个来源无需任何密钥即可使用（Openverse、Met、Art Institute of Chicago、Wikimedia Commons、Rijksmuseum、Internet Archive、Project Gutenberg、PoetryDB、Poly Haven、ambientCG、nailbook）。其余来源在「设置 → 插件 → 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.5-rc.2(next 频道)上测试通过;dsh 目前处于开发者预览阶段,其插件 API 在各个 release candidate 之间会发生变化。

配置

Settings → Plugins → refkit(命名空间为 refkit;修改在下一次调用时生效)。所有 key 字段都是 secret 类型:在卡片中会被遮罩显示,不会被记录日志,也不会返回给模型。每个 key 都有对应的环境变量兜底——与 @refkit/mcp 读取的变量名相同,因此同一份 .env 可以同时服务这两者。

| 字段 | 环境变量(先匹配者优先) | 启用的来源 |
| 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 的逐条详情拉取数量 |
| poolFactor | 2 | 排序融合(rank-fusion)的候选池倍数(1–4) |
| deadlineMs | 15000 | 整次搜索的截止时间 |
| timeoutMs | 10000 | 单个来源的超时时间 |
| rerank | true | 对 title、description、tags 和 excerpt 做词法重排序(支持 CJK) |
| sourceConfidence | true | 对结果批次中完全没有提及查询词的来源降权 |
| userAgent | refkit-dsh-plugin/ | 随请求发送给各来源的 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 |
| limit | 1–30 | 默认取自配置 |
| cursor | string | 沿用上一次结果里的 nextCursor 继续翻页 |
| controls | object | orientation、color、language、sort、safety、license、media、creator、text、page |
| minRelevance | 0–1 | 丢弃重排序分数低于该值的结果 |
| explain | boolean | 在 meta 下附带每个来源的诊断信息 |

示例提示词:“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”。

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