diceframe / dsh-diceframe

dsh-diceframe

English | 中文

DSH AI 跑团 / GM 插件：给 DeepSeek Harness（DSH）加上掷骰、检定判定、世界书与角色卡——让 agent 主持有规则、有判定、有设定的 TRPG 会话，而不是无结构的闲聊。支持直接导入 DiceFrame 世界书 / 角色卡 / 内容包。

功能

模块	提供能力	扩展点
dice	roll_dice 工具：3d6、d20、2d20kh1（优势）、2d20kl1（劣势）、4d6dl1、d100、3d6+2、1d6!（爆炸骰），加密随机，逐骰明细	工具 + 提示段
gm	resolve_check 工具：d100 / d20 / 求和三种模式，含大成功/成功/失败/大失败与 margin；附 GM 主持准则（有起始场景时直接开场）	工具 + 提示段
lore	世界书 / 角色卡 / DiceFrame 内容包导入，注入系统提示词；加载 DiceFrame 内容时附一句多人引导	提示段
commands	斜杠命令 /trpg（开团）、/roll、/check，直接执行不经过模型，骰子永远真实	命令
table	会话状态：世界、玩家角色卡、场景笔记、NPC、先攻顺序（table_state / table_update），按会话隔离	工具
save	存档互通：save_import 读 DiceFrame 存档（state.json / 可移植 zip）载入本局；save_export 把本局写成 DiceFrame 可导入的合法存档	工具 + 提示段

DiceFrame 互通（导入 DiceFrame 内容）

lore 能直接加载 DiceFrame 生态的内容——不用转换、不用复制：

• 单个世界书 JSON（含 world_id）→ world_book_path，自动识别；
• 单个角色卡 JSON（含 character_name）→ character_card_path，自动识别；
• 整个内容包目录（plugin.json + content/worlds|characters|npc|items|spells|classes|rules）→ diceframe_pack_path，一键全量导入。

- id: dsh-diceframe-lore
  config:
    enabled: true
    diceframe_pack_path: "C:/games/diceframe-content-packs/my-pack"
    # diceframe_cta: true   # 加载 DiceFrame 内容时附加一句指向多人联机的引导，可设 false 关闭

导入后，世界书设定条目、角色属性技能、NPC、物品、法术、职业、规则会结构化进入系统提示词。加载到 DiceFrame 内容时，提示段会附加一句引导：

—— 来自 DiceFrame（github.com/diceframe/diceframe）：单人先在这里试，和朋友一起跑，去 DiceFrame 多人联机。

只有加载到 DiceFrame 内容时才出现，不打扰纯通用世界书的用户。

版权提示：本插件不内置任何第三方/IP 同人内容包（如《葬送的芙莉莲》同人包）。请导入你自己的内容包，或使用原创内容。

存档互通（DiceFrame ↔ DSH）

save 模块在 DiceFrame 与 DSH 之间搬运关键状态（世界、玩家角色卡、NPC、场景、先攻、最近进展）：

• 导入：save_import <路径> 读一个 DiceFrame 存档（state.json 或可移植 zip），把世界/角色/场景/NPC 载入本局——在 DSH 里接着 DiceFrame 的团继续。
• 导出：save_export <目录> 把当前桌台状态写成合法的 DiceFrame 存档（state.json + chatlog.jsonl + 可移植 zip）。zip 可被 DiceFrame 的「导入存档」加载为新对局，也可把整个目录放进 DiceFrame 的 data/saves/<game_key>/。

怎么用

save_import / save_export 是 agent 调用的工具——告诉它你想导入/导出什么即可：

导入（DiceFrame → DSH）：对 agent 说

用 save_import 导入这个 DiceFrame 存档：
C:/路径/到/state.json
然后继续这局。

（路径可以是 state.json，也可以是 DiceFrame 导出的 zip。）

导出（DSH → DiceFrame）：对 agent 说

用 save_export 把当前进度导出到：
C:/路径/到/导出目录

会在该目录生成 state.json + chatlog.jsonl + dsh-diceframe-export-<时间戳>.zip。

把导出带去 DiceFrame（二选一）：

• zip：在 DiceFrame 用「导入存档」加载该 zip → 作为新对局恢复；
• 目录：把 state.json + chatlog.jsonl 放进 DiceFrame 的 data/saves/<游戏key>/（key 自定）。

说明：这是"关键状态"互通（世界/角色/场景/历史），不是对 DiceFrame 全部机制（战斗、幸运、谜题等）的逐字段复刻——它在两套引擎间搬运"能继续玩下去"的要素。

导出后想和朋友一起多人跑团 → DiceFrame。

环境要求

• 已安装 DSH（dsh CLI），Node.js ≥ 22。

安装

# npm 安装（发布后可用）
dsh plugin --profile <名字> add dsh-diceframe

# 或直接从 GitHub 安装（建议固定 commit）
dsh plugin --profile <名字> add github:diceframe/dsh-diceframe

纯 ESM、无构建步骤（没有 prepare 脚本），GitHub 安装无需 allowBuilds 放行。若 pnpm 提示放行，把提示打印的包名写入 profile 的 pnpm-workspace.yaml：

allowBuilds:
  dsh-diceframe: true

运行时零依赖。 插件只 import Node 核心与自身本地模块，加载时不需要任何 @deepseek-ai/* 依赖。本地 link: 安装即装即用，无需 npm install，也不会再出现缺依赖导致启动失败。

配置

六个独立插件行（dsh-diceframe/dice、dsh-diceframe/gm、dsh-diceframe/lore、dsh-diceframe/commands、dsh-diceframe/table、dsh-diceframe/save），在 profile 的 cordis.patch.yml 覆盖。通用格式（Markdown 世界书 / 键: 值 角色卡）也支持内联文本或文件路径：

- id: dsh-diceframe-lore
  config:
    enabled: true
    world_book: |
      ## 迷雾王国
      大陆被永雾笼罩，只有灯塔之城仍有人烟。
    character_card: |
      姓名: 艾琳
      职业: 游侠

enabled: false 关闭对应功能；DiceFrame 配置见上方"互通"一节。

使用

告诉 agent 你想跑团即可——它会用 roll_dice 处理随机性、用 resolve_check 处理检定，然后叙述结果：

开始一个 D&D 5e 风格的一小时短团。我是 1 级游侠艾琳。
营地守夜的侦察检定用 resolve_check，d20，难度 12。

斜杠命令与会话状态

聊天框里的斜杠命令直接执行（不经过模型），骰子永远是真实的。输入 / 会在界面弹出命令菜单，可点选：

• /trpg —— 开团；GM 会用已加载世界书的「起始场景」直接开场。
• /roll 3d6 —— 掷任意记法的骰子，返回真实结构化结果。
• /check 侦察 d20 12 —— 检定（检定名 + 骰子 + 难度）。
• /state —— 查看当前桌台状态（世界 / 角色卡 / 场景 / NPC / 先攻）。
• /save export <目录> —— 导出当前进度为 DiceFrame 存档；/save import <路径> —— 导入 DiceFrame 存档。

agent 通过 table_state / table_update 按会话追踪桌台状态（世界、玩家角色卡、场景笔记、NPC 列表、先攻顺序）——玩的时候让 GM 记录，跨回合保持一致。

想要会话创建界面里有一张独立的**「跑团模式」**入口卡：复制 standard agent 预设并追加五个 dsh-diceframe/* 行即可（部署层配置；删除该预设即移除入口）。

GitHub 曝光（重要）

本包通过 dsh-plugin 这个 GitHub topic 分发——DSH 插件生态的事实注册表（topic 页 + 自动同步的第三方插件市场）。要被人发现：

1. 仓库主页 → About → ⚙️ → Topics。
2. 添加：deepseek、deepseek-harness、dsh、dsh-plugin、trpg、ai-roleplay、tabletop-rpg、diceframe。

发布

npm publish            # 纯 JS 无需构建
# 用户随后执行：dsh plugin --profile <名字> add dsh-diceframe

开发

npm test               # node --test，覆盖骰子/检定/世界书/角色卡/DiceFrame 导入

目录结构：

dsh-diceframe/
├── package.json       # dsh.bundle 清单
├── cordis.patch.yml   # 插件行（patch 层）
├── index.js           # 合并入口（可选）
├── engine.js          # 纯逻辑：骰子、检定、世界书/角色卡/DiceFrame 解析（零依赖）
├── dice.js            # 骰子模块：roll_dice 工具 + 掷骰规则
├── gm.js              # GM 模块：resolve_check 工具 + 主持准则
├── lore.js            # 设定模块：世界书/角色卡/内容包导入 + 引导
├── commands.js        # 斜杠命令：/trpg /roll /check
├── table.js           # 会话状态：世界 / 角色卡 / 场景 / NPC / 先攻
├── save.js            # 存档互通：save_import / save_export（读/写 DiceFrame 存档）
└── tests/             # 纯逻辑单元测试（含原创 fixture 内容包）

路线图

• 骰子系统预设（D&D 5e、克苏鲁、通用）与房规配置。
• 存档互通深化：更完整的角色卡字段映射、DiceFrame 战斗/幸运等机制字段的翻译。
• 暗骰：只向玩家叙述结论，不展示点数。
• 会话状态持久化：跨 DSH 重启恢复桌台状态。

许可证

MIT