前言¶
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 的原生机制来实现角色扮演功能。
