前言¶
在 DSH 裏做對話類產品，加表情包是常見需求，但現成的做法通常有兩難：要麼插件自帶圖庫卻結構混亂、許可不清，要麼結構清晰卻要自己先構建素材、跑不起來。更麻煩的是，不少方案沿用 markdown 圖片鏈接，宿主的 Markdown 渲染器會把相對地址當成工作區文件處理，圖片顯示「無法預覽」。dsh-stickerbook 就是針對這些問題的本地表情包庫插件：自帶圖庫、開箱即用，同時把索引、搜索、路由、發送的分層和素材許可邊界都寫清楚。
一句話定位：這是一個跑在 DeepSeek Harness 上的本地表情包插件，用 157 張中文表情做可搜索圖庫，用戶和助手都能發圖，可選原生走 QQ。插件由 Asgoresmilelong 維護，代碼在 GitHub 上開源。
它解決什麼¶
插件綜合了兩個同類插件的取捨：像 dsh-meme 一樣開箱即用，自帶圖庫、小圖、無需構建，並且帶測試；像 dsh-nekowhale-stickers 一樣結構清晰，索引、搜索、路由、發送分層，元數據可讀可改，許可邊界寫清楚。
主要解決三點：
- 素材問題：不需要自己找圖、不必構建，裝完就有 157 張「藍色大肥魚」表情，且來源和許可都明示。
- 發送問題：發圖不依賴 markdown 圖片，改用
[貼紙: 描述]純文本 token，由客戶端渲染成圖片，這是桌面端唯一穩定的路。 - 擴展問題：想加自己的圖，丟文件、讓 agent 收錄、手工編輯都可以，新增圖片無需改代碼。
核心能力¶
搜索：按情緒 tag（happy / angry / sad / food 等）或關鍵詞查找，支持中文子串與多詞 AND 匹配。
用戶發圖：輸入框左側的「🙂 表情」按鈕打開可搜索的圖庫面板，點一張就把 [貼紙: 描述] 放進輸入框併發送。
助手發圖：消息裏只存 [貼紙: 描述] 純文本 token，客戶端渲染成圖片；工具返回候選，並附可直接複製的 token。
QQ / IM 原生髮送：宿主有 companionQq 服務時，action="send" 可直接原生髮原圖。
加圖零配置：把圖片放進 packs/<pack>/images/，文件名先當描述，再用 sticker_learn / sticker_update 補描述。
零運行時依賴：宿主側只用 Node 內置模塊（node:fs / node:http），沒有數據庫、沒有原生擴展。
測試：node --test，覆蓋搜索、pack 解析、HTTP 圍欄、元數據寫入、token 格式與列表 API，倉庫共 33 個測試。
安裝與啓用¶
按官方使用方式，安裝命令直接走 CLI，注意不要憑插件名拼接，以下三條均來自倉庫文檔：
# 本地開發（link 安裝，改代碼重啓即生效）
dsh plugin --profile desktop add link:F:\DSH-\oss\dsh-stickerbook
# 或從 npm 安裝
dsh plugin --profile desktop add dsh-stickerbook
# 或從 GitHub 安裝
dsh plugin --profile desktop add github:<you>/dsh-stickerbook
官方桌面端請完全退出 DSH 後再執行 CLI，裝完重啓 DSH。
裝好後 agent 會拿到四個工具：
| 工具 | 幹什麼 |
|---|---|
send_sticker |
找圖（tag / query）並返回候選；action=send + path 走 QQ 原生髮圖 |
sticker_list |
只讀瀏覽，帶 pack/file 方便維護 |
sticker_learn |
把一張圖收進用戶圖庫（默認 mine） |
sticker_update |
改描述 / 情緒 / 關鍵詞 |
典型用法¶
助手發圖（Web 端）。三步：工具返回候選，模型把選中的 token 原樣寫進回覆，客戶端把 token 換成 /dsh-stickers/... 的 <img>。
send_sticker({ query: "摸魚" })→ 工具返回候選，每張帶一行[貼紙: 描述]- 模型把選中那張的 token 原樣寫進回覆
- 客戶端把 token 替換成
/dsh-stickers/...的<img>
這裏不推薦用 markdown 圖片：宿主渲染器會把相對地址當作工作區文件（/api/file），/dsh-stickers/... 或 http URL 都會顯示「圖片無法預覽」。token + DOM 裝飾纔是穩定方案。
QQ / IM 會話：
send_sticker({ tag: "happy" })拿候選（含絕對路徑）send_sticker({ action: "send", path: "<絕對路徑>" })由插件調用companionQq.sendImage
用戶發圖：點輸入框左側的「🙂 表情」，搜索或直接點一張，插件會把 [貼紙: 描述] 放進輸入框併發送。
加圖¶
三種方式，按方便程度排列。
方式一，直接丟文件，最快：
packs/blue-whale/images/新表情.gif
重啓 DSH 或等下一次工具調用重新掃描後就能搜到；描述先用文件名，之後用 sticker_update 改。
方式二，讓 agent 收錄：
sticker_learn({ path: "D:\\pics\\生氣貓.gif", caption: "生氣貓：再問就咬你", emotion: "angry", tags: "貓 生氣 咬人" })
文件會被複制到 ~/.dsh/sticker-packs/mine/images/，原圖留在原地。
方式三，手工編輯 stickers.json：
{
"version": 1,
"items": [
{
"file": "images/生氣貓.gif",
"caption": "生氣貓：再問就咬你",
"emotion": "angry",
"tags": ["貓", "生氣", "咬人"],
"use": "被問煩了的時候"
}
]
}
stickers.json 是可選文件，沒有它也能用，文件名就是描述。圖庫格式如下：
packs/
blue-whale/
pack.json # { id, name, description, author, source, license, version }
stickers.json # { version: 1, items: [{ file, caption, emotion, tags, use }] }
images/ # 圖片（gif/png/jpg/webp），可以有子目錄
用戶圖庫放在 ~/.dsh/sticker-packs/<pack>/，與插件包分開，升級插件不會丟。
配置¶
在 profile 的 cordis.patch.yml 裏給這一行加 config:：
- id: stickerbook
name: dsh-stickerbook
config:
route: /dsh-stickers # 圖片路由前綴
packs: # 覆蓋默認掃描根（相對包目錄或絕對路徑）
- packs
- D:\my-stickers
allowLan: false # 默認只允許迴環地址取圖
allowedHosts: [] # 反代域名白名單
maxBytes: 20971520 # 單圖上限 20MB
環境變量 DSH_STICKERBOOK_ALLOW_LAN=1 等價於 allowLan: true。
HTTP 圍欄只認 Host 頭（不是 Origin），默認僅迴環地址；反代或 LAN 必須顯式放行。
設計取捨¶
元數據在磁盤上：packs/** 是唯一真相，內存索引是派生的；改一條描述不需要遷移或重建數據庫。
發圖用 token + 客戶端裝飾：消息裏只存 [貼紙: 描述] 純文本，客戶端換成 <img>；宿主的 Markdown 渲染器不認本地或 HTTP 圖片地址，這是桌面端唯一穩定的路。
工具少而清晰：發送、瀏覽、添加、編輯四件事，避免一個巨型設置面板。
適用場景與注意¶
適合想在 DSH 對話里加表情包、又不想自己構建素材的開發者：需要本地可搜索圖庫、用戶可選圖發送、必要時走 QQ 原生髮圖的，可以拿它當起點；想長期維護大量自有圖庫的，也可以借鑑它的分層和許可拆分。
有幾點要提前知道：
- 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證，不要看到目錄站收錄就直接裝。
- 代碼是 MIT 許可，作者 Asgoresmilelong；但
packs/blue-whale/images/下的 157 張表情不是插件作者的原創，全部來自 B站 @赤風RED，素材許可是 CC BY-NC 4.0（署名 + 非商業性使用）。轉載或分發必須保留「赤風RED」署名與來源鏈接，商用需另行獲得赤風RED許可；MIT 只覆蓋代碼，不覆蓋這批素材。 - 倉庫自帶的 157 張「藍色大肥魚」是 460MB 原始 GIF 壓縮到 45MB（240px、12fps、128 色）後的版本，壓縮腳本在
tools/prepare-pack.mjs，重新打包時可複用。
結尾¶
dsh-stickerbook 的價值在於把「自帶圖庫 + 穩定發圖 + 清楚許可」三件事一次做對：裝完即用，token 渲染繞開了 markdown 圖片的限制，素材的來源和商用邊界也明示清楚。如果要做同類功能，它的四工具劃分、磁盤即元數據的約定和許可拆分都值得參考。
- 目錄頁：https://www.skillhub.cn/plugins/Asgoresmilelong/dsh-stickerbook
- GitHub：https://github.com/Asgoresmilelong/dsh-stickerbook
