前言¶
DeepSeek Harness (DSH) 依賴模塊化設計。開發者有時需要將 SillyTavern 的角色扮演素材（JSON/PNG 卡片）整合進 DSH 的 agent 生態。dsh-bard 插件實現了這一點：它讀取 SillyTavern 的角色卡和世界書，將它們與 Harness 技能組合，並保存爲原生 agent preset。它不建立獨立的對話循環；它將內容翻譯成 Harness 的內部格式（agent preset、system prompt 上下文、技能列表），因此歷史記錄、工具、權限、上下文壓縮全部沿用 Harness 既有行爲。
核心功能¶
角色卡導入
支持 SillyTavern V1/V2/V3 格式。可讀取 JSON 文件，或讀取 PNG 卡片中的 tEXt 塊（優先級 ccv3 優於 chara）。導入後可預覽立繪、簡介及開場白。
世界書導入
支持導入獨立 JSON 世界書，或提取角色卡內嵌的 character_book。
內容選擇與預算裁剪
世界書條目通過關鍵詞匹配（常駐/次級門控），停用條目會自動跳過。系統按條數和字符雙預算裁剪，且排名最高的條目即使超預算也會強制注入。
技能與工具綁定
一個預設可綁定若干 Harness 技能。創建/編輯預設時可關閉工具調用（適配純文本模型），或使用工具白名單限制允許進入請求的工具。Section 白名單可從完整 system prompt 中挑選指定 section（與 complete: true 互斥）。
用戶與性別
每個預設可指定 {{user}} 的替換值，角色卡內的 SillyTavern 宏在渲染時自動替換。可指定玩家性別（未指定/男/女/自定義文本），避免模型因中性名字猜錯代詞。
數據落庫與立繪
保存後的預設前綴爲 bard-，出現在 Harness 的預設選擇器裏。導入 PNG 卡時，立繪原圖會保留。
數據存儲
所有數據存放於 $DSH_HOME/bard/（默認 ~/.dsh/bard/），純文件、可讀、可手改。寫入採用原子操作（臨時文件 + rename），崩潰不會留下半截記錄。
安裝與啓用¶
插件目錄需要能作爲 bundle 被解析到。推薦在 profile 的 package.json 中配置：
{
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-bard"] } }
}
包本身聲明瞭 dsh.bundle.patch: ./cordis.patch.yml，該 patch 會插入一行 { id: bard, name: dsh-bard }。解析順序是「安裝錨點優先，然後 profile 目錄」，因此只要 dsh-bard 出現在 profile 的 node_modules 下即可被找到。
啓用後，插件會在 $DSH_HOME/bard/ 下創建 cards / worldbooks / portraits / presets 四個目錄，並在「設置 → 吟遊」中提供四個標籤頁。
使用¶
界面操作¶
- 設置 → 吟遊：分爲角色卡、世界書、技能、預設四個標籤頁。
- 導入：在角色卡或世界書標籤頁導入素材。
- 綁定：在技能標籤頁勾選 Harness 技能。
- 保存：在預設標籤頁組合上述素材，命名並保存。
命令¶
/bard 列出所有吟遊預設
/bard card 查看當前會話正在使用的角色
/bard greet [序號] 輸出開場白（第 n 條備選，缺省用當前會話的角色）
開演流程¶
- 在設置 → 吟遊裏完成素材導入、技能綁定並保存預設。
- 在會話的預設選擇器裏選擇「吟遊 · <預設名>」。
- 角色卡的 persona、命中的世界書條目、綁定的技能會自動進入該會話的 system prompt。
技術細節¶
Scope 限制
Host 側的所有服務必須從 agent.ctx 獲取，不能從插件的全局 ctx 獲取。這是因爲 DSH 的服務按 scope 分層，插件 ctx 沒有 scope 標籤，寫進去會落到全局層導致靜默失敗。
工具注入
工具清單通過變量注入到 persona 前綴，而不是獨立的 section。這樣可以確保清單出現在 persona 下方，且免疫 complete: true 的裁剪（該標誌會丟棄除 persona 外的所有 section）。
白名單實現
工具白名單隻過濾繼承的工具（全局層與祖先層），不過濾子 agent 自身註冊的工具（如 Agent Teams 的工具）。Section 白名單通過 system-prompt/assemble 的 waterfall 實現，監聽器原地修改 assembly.sections。
數據來源
世界書注入文本取自該會話最近 24 條消息，截尾 8000 字符。HTTP 端點僅允許 loopback host + 同源 origin 訪問。
總結¶
dsh-bard 是一個將 SillyTavern 角色扮演素材轉化爲 DeepSeek Harness 原生能力的工具。它不構建獨立的對話循環，而是通過翻譯素材和利用 Harness 的原生機制來實現角色扮演功能。
