dsh-bard · 吟游角色扮演

给 DeepSeek Harness 加上「吟游」式的角色扮演能力：导入 SillyTavern 角色卡和世界书，挑选 Harness 技能，把组合存成一个原生 DSH agent preset，然后在会话里用 Harness 自己的预设选择器选它即可开演。

插件不会另造一套对话循环——它把吟游的素材翻译成 Harness 原生的东西（agent preset、system prompt 上下文、技能列表），所以历史记录、工具、权限、上下文压缩全部沿用 Harness 既有行为。

它做什么

数据存放

一切都放在 $DSH_HOME/bard/（默认 ~/.dsh/bard/）下，纯文件、可读、可手改、不依赖数据库，升级插件不会丢：

~/.dsh/bard/
  cards/<id>.json        归一化后的角色卡
  worldbooks/<id>.json   归一化后的世界书
  portraits/<id>.png     从 PNG 卡里保留下来的原图
  presets/<id>.json      角色卡 + 世界书 + 技能的组合
  rendered/<presetId>.json  替换掉 {{char}}/{{user}} 后的卡快照（删预设时一并删除）

写入是原子的（临时文件 + rename），崩溃不会留下半截记录。

安装与启用

插件目录需要能作为 bundle 被解析到。两种方式任选其一：

A. 作为 bundle 启用（推荐） — 在 profile 的 package.json 里把包名加进 dsh.profile.bundles：

{
  "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 下（symlink/junction 或真实安装均可）就能被找到，不需要导出 ./package.json。

B. 直接改 profile 的 cordis.patch.yml — 加入与插件自带 patch 相同的内容：

- insert:
    - id: bard
      name: dsh-bard

profile 的 package.json 与 cordis.patch.yml 都受 HMR 监视：实时 profile 下改动即时生效，启动型 profile 需要重启。

启用后：

1. 插件会在 $DSH_HOME/bard/ 下创建 cards / worldbooks / portraits / presets 四个目录；
2. 设置 → 吟游 出现四个标签页：角色卡、世界书、技能、预设；
3. 会话的预设选择器里出现「吟游 · …」条目。

使用

界面

设置 → 吟游，四个标签页：

• 角色卡 — 导入 JSON / PNG 卡，预览立绘、简介、开场白，删除卡片（会提示哪些预设正在引用它）
• 世界书 — 导入世界书；角色卡内嵌的世界书可一键提取；查看条目与关键词
• 技能 — 从 Harness 技能列表里勾选，绑定进预设
• 预设 — 选角色卡 + 世界书 + 技能，命名并保存；保存后立即注册为原生 agent preset

命令

/bard                    列出所有吟游预设（等同 /bard list、/bard presets）
/bard card               查看当前会话正在使用的角色
/bard greet [序号]       输出开场白（第 n 条备选，缺省用当前会话的角色）

card 与 greet 依赖当前会话已经选中某个「吟游 · …」预设；没有选中时会给出提示而不是静默失败。

开演

1. 在 设置 → 吟游 里导入角色卡，按需挑世界书和技能，保存预设；
2. 在会话的预设选择器里选择「吟游 · <你的预设名>」；
3. 角色卡的 persona、命中的世界书条目、绑定的技能会自动进入该会话的 system prompt。

工作原理

插件分 Host 侧与 Web 客户端两部分。

Host（lib/index.js）

• inject: ['webServer']，插件名 bard。
• 把每个吟游预设注册成原生 agent preset，名称前缀 bard-，排序基址 PRESET_ORDER_BASE = 50（排在 Harness 自带预设之后）。
• 预设的插件列表从 profile 当前默认 agent preset 的 inherited.plugins 深拷贝而来，取不到时回退到一份内置工具清单——这样吟游预设与用户当前的默认配置保持一致。
• 通过 agentPresets.composedPreset(agent.ctx) 判断某个 agent 是否正在跑吟游预设；是则用 agent.ctx.get('systemPrompt').context({ name: 'bard:world-book', order: 130, text }) 注入世界书。
• 所有服务都必须从 agent.ctx 获取，不能从插件的全局 ctx 获取。 systemPrompt.section() / context() 会把注册落到「访问服务时所用 ctx 的 scope 层」——插件 ctx 没有 scope 标签，写进去会落到全局层：第一个 agent 侥幸成功，之后每个 agent 都撞上 already registered 异常并被静默吞掉；而且注册的生命周期跟插件走，不跟 agent 走。tools 服务同样是按 scope 分的，从插件 ctx 拿只能看到内核常驻工具（compress、decompress 等），看不到 read / write / pwsh——所以 agent.ctx.get('tools') 是必须的。
• 工具清单通过 agent.ctx.get('systemPrompt').variable('bard_tools', provider) 注入，而不再是一个独立 section。原因是 section 在 DSH 里是原子单位：它只在顶层按 order 互相排序、再拼成 prompt 正文，没有任何接口能把文本插进某个 section 内部——清单只能在 persona 旁边，永远到不了【关于你自己】段的最后一句正下方。prompt 变量不占位置、只做替换：persona 前缀里直接写 {{bard_tools}}，assemble 时 DSH 对该 section 文本逐个变量求值，引用点就被就地换成清单。变量还免疫 complete: true 的裁剪——该标志会丢弃除 persona 外的所有 section，但 persona 正文本身仍会插值，变量引用随正文一起留下。provider 每次请求前由 DSH 求值；agent/created 时 Bard 预设尚未应用到 agent 的 ctx，任何基于 composedPreset() 的外层判断都会早退，因此全部逻辑都在 provider 内部。渲染结果按 preset id 缓存：provider 每轮都跑，但只有 composed preset 真正变化时才重算。世界书注入（bard:world-book，order 130）同样是 thunk，且每轮重新选择条目、不缓存。
• 注入文本取自该会话最近 RECENT_LIMIT = 24 条消息，截尾 8000 字符，再按世界书选择器裁剪（默认 maxEntries = 12、maxChars = 6000）。
• 注册 /bard 命令。
• HTTP 端点挂在 /dsh-bard/api/ 下，并对 loopback host + 同源 origin 做校验（不通过返回 403），上传上限 MAX_UPLOAD_BYTES = 12 MiB。

Web 客户端（client.js）

• 以 settings.section 槽位注册「吟游」设置节（id: 'bard', order: 25）。
• 只通过 /dsh-bard/api 与 Host 通信。

模块划分

开发

离线自测，不需要启动 Harness：

node tools/bard-selftest.mjs

覆盖 13 项检查：PNG 与 JSON 判别、V2 JSON 卡、PNG 内嵌卡、ccv3 优先级、V1 扁平卡、无卡数据的 PNG 报错、世界书对象键归一化、character_book 反向 flag、关键词/常驻/次级门控/停用条目选择、预算裁剪、渲染去重、persona 前缀、空节省略。

语法检查：

node --check lib/index.js && node --check client.js

许可

MIT