dsh-bard-0.03

dsh-bard · 吟游角色扮演

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

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

---

它做什么

能力	说明
角色卡导入	SillyTavern V1 / V2 / V3 卡片；JSON 文件，或 PNG 卡片（读 tEXt 块，ccv3 优先于 chara）
世界书导入	独立世界书 JSON，或角色卡内嵌的 character_book（可一键抽出来存成独立世界书）
关键词选择	世界书条目按关键词、常驻（constant）、次级门控（secondary keys）命中，停用条目跳过
预算裁剪	按条数和字符双预算裁剪，且排名最高的条目即使超预算也强制注入
技能绑定	一个预设可绑定若干 Harness 技能，随 system prompt 一起生效
工具开关	创建/编辑预设时可关闭工具调用；关闭后生成的预设不携带任何工具定义，适配纯文本模型。与 complete 独立控制
工具白名单	每个预设可勾选允许进入请求的工具；留空 = 不限制。工具定义按 agent.ctx 采集，写入 tool-catalog.json 供界面读取。与「工具开关」解耦：关闭工具开关会连带清空白名单
Section 白名单	每个预设可从完整 system prompt 中挑选要保留的 section（按名精确匹配）；留空 = 保留全部。与 complete 互斥：勾选任一 section 会自动关闭 complete
你的名字	每个预设可指定 {{user}} 的替换值；角色卡里的 {{char}}、{{user}} 等 SillyTavern 宏会在渲染时自动替换，未知宏降级为 [[...]] 而不报错
玩家性别	每个预设可指定玩家性别（未指定 / 男 / 女 / 自定义文本）；写进 persona 前缀的「关于玩家」段，避免模型因玩家的中性名字猜错代词
开场白	读取角色卡的 first_mes 与 alternate_greetings，可在界面里预览，也能用命令输出
预设落库	保存为原生 agent preset，名称前缀 bard-，出现在 Harness 的预设选择器里
立绘	导入 PNG 卡时保留原图，界面里直接显示

数据存放

一切都放在 $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}} 后的卡快照（删预设时一并删除）
  workspaces/<shortId>.json    每个 Bard 会话的工作区记录（懒清扫凭据）
  tool-catalog.json            工具清单缓存（每 agent 首轮采集一次）
  section-catalog.json         system prompt section 清单缓存（每 agent 首轮采集一次）

写入是原子的（临时文件 + 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，且每轮重新选择条目、不缓存。
• 工具白名单通过 agent.ctx.effect(() => tools.restrict({ allow }), 'bard.tool-filter') 注册。restrict 只过滤 scope 继承来的工具（全局层与祖先层），不过滤 scope 自身注册的——这是设计豁免：delegation runtime 需要把子 agent 的 structured-output 工具写进子 agent 自己的层。因此 Agent Teams 的 11 个工具（spawn_teammate / send_message / team_task_* 等）注册在 agent 自身层，白名单盖不住。白名单用于控制全局层工具（compress / acp_status / load_workspace_dependencies 等）是否出现。
• Section 白名单通过 system-prompt/assemble 的 waterfall 实现。assemble 会构造 assembly 对象（含全部 section），把 next 作为末尾参数传给每个 listener；listener 原地修改 assembly.sections 后 return next()。waterfall 的 next() 不接收参数——返回值被静默丢弃——所以传播只能靠原地修改。监听器从 agent.ctx 注册，effect 随 agent 生命周期销毁。与 complete: true 互斥：complete 会在 waterfall 之后强制把 sections 覆盖为 [completeSection]，抹掉白名单的任何改动，因此预设里 complete === true 时白名单被忽略。section-catalog.json 在 agent 首轮请求时采集，此后不再写——后续请求的 section 列表可能已被白名单裁剪，重复采集会把清单越缩越小。
• 注入文本取自该会话最近 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 通信。

模块划分

文件	职责
lib/index.js	Host 主体：预设注册、世界书注入、HTTP 路由、/bard 命令
lib/cards.js	角色卡读取与归一化（JSON / PNG tEXt，V1/V2/V3，ccv3 优先于 chara）
lib/lorebook.js	世界书归一化、关键词选择、渲染
lib/persona.js	角色 prompt 前缀拼装（身份 + 技能）
lib/store.js	原子文件存储与目录管理
client.js	Web 设置页（四个标签页）
cordis.patch.yml	bundle patch：插入 bard 行
locale/zh.json、locale/en.json	设置节的标题与描述

开发

tools/asar-extract.mjs 是开发辅助脚本，用来读 DSH 自身的 app.asar，跟插件运行无关。

语法检查：

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

许可

MIT