dsh-xgame

dsh-xgame

DeepSeek Harness 文字冒险/推理游戏插件:用 DSH 玩海龟汤、侦探推理、密室逃脱、剧本杀、时间循环、王国议会与单人跑团,由大模型担任主持人(GM)与 NPC。

特性

• 确定性内核,真相封存:游戏状态落盘 $DSH_HOME/storages/dsh-xgame/,海龟汤汤底、侦探案卷、密室谜底与剧本真相只存于插件,永不进入模型上下文——GM 想泄露也做不到。
• GM 由主会话 agent 扮演:/game new 开局后,主持人接管对话;玩家自由提问、勘查、审讯、操作机关、公聊对质。
• NPC 审讯:侦探推理与剧本杀中的每个 NPC 有独立人设、知识边界与说谎策略——台词由隔离子代理生成(spawn provider、不继承主会话上下文、无任何工具,真相永不进入 NPC 会话;主机无 subagent 服务时自动回退插件侧 LLM)。
• 泄密审计:每句 NPC 台词都过双层审计——确定性引擎(敏感事实滑窗/公共子串匹配,越界或说漏嘴的发言当场作废,换成"警觉地停住"的净化台词)+ 每 4 轮一次的 LLM 语义抽查;全部留证审计日志,卷宗标注、结算作废说明,保证泄密内容到不了玩家。
• 推理报告评审:终局由独立评审逐条对照真相评分,三栏结算。
• 程序化案件 + 可解性求解器:侦探推理的案件由模板 + 种子随机数程序化生成,每个案件都过求解器硬门禁(线索可达、关键线索唯一解、每名嫌疑人可被排除、红鲱鱼可洗清);手工招牌案件与剧本杀剧本同样过门禁。
• 密室逃脱·确定性谜题引擎:房间状态机 + 道具图 + 谜题规则函数,裁决全部为纯函数(点火、转镜、撬窗、猜密码都走引擎),LLM 只负责叙事包装;暴力猜谜会被审计并在结算中扣分;程序化题库:同一套机制三套叙事皮肤(老宅/潜艇/飞船),每个变体都过"引擎金路径重放"可解性求解器。
• 剧本杀·群像对质:暴风雪山庄《风雪夜归人》,5 名 AI 角色与玩家同困山庄;搜证、私聊对质、公聊(引擎并发 fan-out——每个角色一个隔离子代理,每人一句,泄密即净化)、出示铁证触发凶手崩溃认罪,终局双栏结算(推理正确性 + 扮演质量)。
• 剧本杀·反转模式(难度 3):玩家饰演凶手,侦探团围猎——你的秘密角色卡只有你自己能看(/role,GM 上下文里没有);每轮陈述由引擎对照证据裁决嫌疑度(坚守说辞洗清、自曝或与证据矛盾大涨),5 轮质询后终局裁决:全身而退或被识破。
• 时间循环·昨日重现:8 时间片/循环,19:00 悲剧必然降临;世界回滚但元知识清单、好感度、道具认知与循环 diff 跨循环保留——用一次次轮回收集信息、切断因果,终局提交"完美一日"方案由引擎逐条验证;已知动作可快进重放;NPC 对话走隔离子代理,回滚时对话历史清空 → NPC 天然"循环内失忆"。手工剧本库 3 本(北桥镇秋祭日·钟楼倒塌 / 客栈大火 / 宴会中毒)+ 程序化皮肤变体(经典/武侠/西幻,骨架 × 皮肤换名)+ 程序化时间表生成(2 场景(望海灯塔/黑石矿镇)× 3 因果链形状(事故/崩塌/命案,含链式前置拓扑),求解器还会返回可排程计划供回放验证),全部过 ScheduleSolver 硬门禁,按会话确定性选本。
• 王国议会·朝堂博弈:20 季王国经营;确定性账本(粮/金/军/民心)+ 四个隐藏祸患(瘟疫/贪腐/外敌/饥荒);四名顾问各怀议程、每局开局扰动(财政贪腐度、密探买家),顾问立场由引擎按标签偏好确定性计算,台词由顾问隔离子代理生成(议程/欺瞒边界注入,泄密即净化);信任评级按"主张 vs 实际结果"升降;调查可揭露顾问议程,终局三栏结算(王国结局/决策质量/识人准确度)。
• 单人跑团·织梦者:沙盒冒险——角色卡 + 种子骰子(d20 优势/劣势,历史留档不可篡改)+ 奇招检定(GM 提议 DC、引擎掷骰)+ 回合制战斗状态机(先攻/攻击/敌人 AI/逃跑,失败不死档晕倒回旅店)+ 主支线任务链 + 升级成长;战斗模拟器回归保证胜负分布落在目标区间;程序化世界生成(招牌《霜松林地》+ 荒漠驿站/海港疑云两主题,每个世界都必须通过"引擎黄金路径重放"可解性求解器);NPC 对话走隔离子代理 + 好感度影响态度 + 泄密审计。

新用户安装指南

前提

• Node.js ≥ 22,且已全局安装 DSH 命令行:npm install -g @deepseek-ai/dsh(装完 dsh 可用);
• 一个可用的 LLM API key(DeepSeek 官方 key 或自建网关 key)。

1. 获取并安装插件(二选一)

方式 A:npm 安装(推荐)

dsh plugin --profile game add dsh-xgame

pnpm 会从 registry 安装 dsh-xgame 及其依赖(@deepseek-ai/dsh-llm、@deepseek-ai/dsh-tools,均为 0.1.0-rc.6 系列),并自动把它加入 profile 的 bundles。

方式 B:本地构建安装(开发 / npm 暂不可用时)

克隆或拷贝本仓库目录后:

cd dsh-xgame
npm install            # devDependencies(typescript 等)
npm run link-deps      # 链接本机 dsh 安装的类型包(自动定位安装目录)
npm run build          # 编译到 lib/
dsh plugin --profile game add link:$(pwd)

2. 配置 LLM(最容易漏的一步)

编辑 ~/.dsh/settings.yaml,指定默认 provider/model;把 key 写入 ~/.dsh/.credentials.yaml(私密文件,勿提交):

# ~/.dsh/settings.yaml
agent-default-model:
  provider: <你的 provider 名>
  model: deepseek-v4-pro    # 或网关支持的模型名

# ~/.dsh/.credentials.yaml
OPENCODE_GO_API_KEY: sk-你的key

provider 写法按你的网关文档(README 作者环境实测 llm-pi-ai + opencode-go);也可以先运行 dsh web 走 UI 引导配置模型。

3. 创建 game profile 并挂载插件

方式 A 已在第 1 步完成 profile 创建;方式 B 执行 dsh plugin --profile game add link:$(pwd) 后,确认 ~/.dsh/profiles/game/package.json 内容含(路径换成你的绝对路径):

{
  "name": "dsh-profile-game",
  "private": true,
  "dependencies": { "dsh-xgame": "link:/你的绝对路径/dsh-xgame" },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-xgame"]
    }
  }
}

注意:若 profile 由 dsh plugin 自动初始化,bundles 初始只有 @deepseek-ai/dsh-base;必须手动补上 @deepseek-ai/dsh-web-app 才有网页界面(npm 安装时 dsh-xgame 会自动加入,方式 B 同理自动加入)。

4. 启动与开局

dsh --profile game --port 3180

浏览器打开 http://127.0.0.1:3180,新建会话后输入:

/game new soup         # 海龟汤
/game new detective    # 侦探推理
/game new escape       # 密室逃脱
/game new party        # 剧本杀(party 3 = 反转模式)
/game new loop         # 时间循环
/game new council      # 王国议会
/game new trpg         # 单人跑团
/game score / quit / resume / hint   # 查分 / 退局 / 续局 / 提示

可选:无头验证(不开浏览器)

无头跑一局验证 LLM 与插件链路(profile 创建方式同上,bundles 换成 @deepseek-ai/dsh-headless):

dsh --profile gamehead "开始一局海龟汤,然后问第一个问题"

常见问题

• 开局后 GM 报"llm 服务不可用":DSH 里没有可用 LLM(缺 dsh-llm 服务或 provider/model/key 没配好),回到第 2 步;
• 升级插件:重新 npm run build 并重启 dsh 进程即可;
• 无 subagent 服务的主机:插件自动回退插件侧 LLM 扮演,照常可玩。

玩法

/game new soup                 # 海龟汤(难度 1-3 可选:/game new soup 2)
/game new detective            # 侦探推理(程序化案件 + 招牌案件《雾都公馆》)
/game new escape               # 密室逃脱·第七扇门(难度 1/2/3 = 2/3/4 房间)
/game new party                # 剧本杀(招牌+程序化剧本;/game new party 3 = 反转模式)
/game new loop                 # 时间循环(3 本手工剧本 + 皮肤变体,按会话确定性选本;难度=循环上限 8/6/4)
/game new council              # 王国议会·云澜国(20 季经营,难度 1/2/3 = 摄政/君王/暴君)
/game new trpg                 # 单人跑团(霜松林地/荒漠驿站/海港疑云,按会话选世界)
/game score  /game quit  /game resume  /hint
/casefile                      # 侦探推理:线索卷宗
/look  /bag  /map              # 密室逃脱:房间 / 背包 / 地图
/roles  /timeline  /role      # 剧本杀:角色名册 / 已确证时间线 / 我的角色(反转模式=秘密凶手卡)
/facts /relations /schedule /loops   # 时间循环:元知识 / 好感度 / 已观测时间表 / 循环记录
/ledger /trust /history        # 王国议会:账本 / 信任评级 / 历史决策
/sheet /quests /world          # 单人跑团:角色卡 / 任务 / 地图(/bag /map 亦可用)

海龟汤:主持人不知道汤底,每个问题都经引擎裁决(是/否/无关)。 侦探推理:勘查地点、审讯嫌疑人、出示证据、提交推理报告或直接指控。 密室逃脱:自然语言操作机关("撬开窗户""用火柴点壁炉""把钟拨到四点半"),全部经确定性引擎裁决;卡住时三层苏格拉底式提示不直接给答案。 剧本杀:搜证、私聊对质、公聊("我找到了带血的火钳"→ 引擎并发收集 5 名角色的反应)、出示铁证、终局指控双栏结算;反转模式(难度 3)里你饰演凶手,用陈述与侦探团周旋,嫌疑度决定你是全身而退还是被识破。 时间循环:每循环 8 个时间片,移动消耗 1 片;19:00 悲剧结算后世界回滚、元知识保留;集齐因果知识后提交"完美一日"方案终局。 王国议会:每季议会 = 事件揭示 → 四顾问发言(立场引擎确定、台词由隔离子代理撰写)→ 追问/调查 → 拍板结算(账本 + 信任评级)→ 20 季终局。 单人跑团:自由冒险——移动/检查/奇招检定/对话/战斗/休整全走引擎裁决,GM 只叙事不口胡数值;骰子由种子 RNG 产生并留档。

开发

npm run build       # tsc 编译到 lib/(含类型声明,供冒烟测试)
npm run bundle      # esbuild 打包到 dist/index.js(发布产物,自包含)
npm test            # 冒烟测试(装配 + 引擎 + 生成器/求解器 + 存档结算)

• 构建所需类型包以 devDependencies 从 npm registry 安装(npm install 即可,不需要本机 dsh 安装);npm run link-deps 仅作离线/源码树开发的备用手段。
• 发布/安装产物是 dist/index.js(package.json 的 main 指向它):运行时依赖已全部打包进产物,不会向 profile 的 node_modules 引入任何 @deepseek-ai 包——否则会遮蔽 harness 自身的同名模块解析(双实例导致工具调用崩溃,已实测复现),这是必须打包的原因。
• 以 link: 安装进 profile 后,重新 npm run build && npm run bundle 并重启 dsh 进程即生效。

发布(Trusted Publisher + 全自动)

npmjs 已为 dsh-xgame 配置 GitHub Trusted Publisher(仓库 leo-lab-2026/dsh-xgame,workflow 文件 publish.yml,允许 npm publish)。发布全自动、不需要任何 npm token、无需人工环节:工作流通过 OIDC(id-token: write)自动认证后,直接 npm publish --provenance --access public 上线。

# 提升版本并打标签(版本必须与标签一致,工作流会校验)
npm version patch            # 0.1.0 → 0.1.1,自动 commit + tag v0.1.1
git push && git push --tags

推送 v* 标签即触发发布:.github/workflows/publish.yml 构建 → 打包 → 冒烟测试 → npm publish --provenance --access public(OIDC 自动认证,直接对公众可见),全程无人值守。

也可以手动触发工作流(GitHub Actions → Publish Package → Run workflow):publish = 直接发布(需确认 tag 与版本一致);check = 仅构建测试不发布。

完整流程手册(含异常处理与 OIDC 注意事项)见 docs/10-release-workflow.md。相关文档:npm Trusted Publishers。

实现说明(与策划文档的取舍)

策划文档见 docs/(底座 README、01 侦探推理、04 密室逃脱、06 小游戏等)。落地时的取舍:

• NPC 审讯(subagent 化,v0.16.0 落地):所有 NPC 台词(侦探审讯/出示证据、剧本杀私聊对质与公聊群戏、时间循环 NPC、跑团 NPC、议会顾问)走隔离的一次性子代理——ctx.subagents 的 spawn provider(不继承主会话上下文 → 真相永不进入 NPC 会话)、toolFilter: { allow: [] }(子代理无任何工具,只能回一句台词)、人设/知识边界/说谎边界经提示词注入、历史窗口由调用方传入(时间循环回滚即清空 → NPC 循环内失忆);台词照旧过双层泄密审计。子代理服务缺失/失败时自动回退插件侧无状态 LLM,两者皆缺则抛 LlmUnavailableError 由调用方兜底——无 subagent 服务的主机照常可玩。策划中的"continuable 持久 NPC 会话(存活整局、跨轮私有记忆)"是可选后续演进:DSH 的 followup 不向调用方返回子代理回复,当前以"每次对话一个新子代理 + 历史窗口"实现同等游玩体验。
• 泄密审计:已上线双护栏(src/core/audit.ts):① 确定性审计——全体 NPC 的 mustNotAdmit 并集为敏感事实集,台词经滑窗重叠 + 最长公共子串匹配,越界/说漏嘴即作废并记录;② LLM 抽查——每 4 轮对台词做一次语义级复核,LLM 不可用时优雅降级。审计日志进卷宗(/casefile 的【证词审计】)与结算(【泄密审计】,被作废发言不视为有效证词)。
• 海龟汤裁决:关键词规则快路径 + 插件侧 LLM 兜底(汤底只进插件上下文);判定口径漂移风险仍在,规则库是护栏。新卡负面规则前置,复合问题优先判"否"防误判。
• 侦探内容:1 桩手工招牌案件《雾都公馆》(5 嫌疑人、13 线索、14 事实)+ 程序化案件生成器(5 手法 × 5 动机 × 7 嫌疑人原型 × 6 不在场模板 × 5 红鲱鱼秘密,种子随机数组装,难度 1/2/3 对应 4/5/6 嫌疑人与 1/2/3 条红鲱鱼)。所有案件(含手工案)一律通过 solver.ts 可解性门禁后才会开局;同一种子生成同一案件,可回归测试。
• 密室逃脱:《第七扇门》单场景(阁楼/书房/地窖/密室),难度 1/2/3 = 2/3/4 房间与 3/5/8 个谜题事件;点火-转镜-开暗格联动、冻钥匙烤化、钟面密码、诗页密码(硬核拆分线索 + 黄铜钥匙障眼法 + 地窖支线)。机关状态、配方、谜底全在 escape.ts 纯函数里。程序化题库(M3)已上线:三套叙事皮肤(老宅/潜艇/飞船)经最长优先显示名替换 + 逐字段修正生成,每个变体都必须通过 solveEscapeScenario(用引擎纯函数从初始状态重放金路径逐条断言),每难度 3 个变体按会话确定性选本。
• 剧本杀:v1 落地《风雪夜归人》(5 名 AI 角色,凶手封存于剧本真相)+ 反转模式(难度 3,玩家=凶手:秘密凶手卡仅经 /role 展示、嫌疑度裁决、5 轮质询终局)+ 程序化剧本池(难度 1/2 复用案件生成器与求解器,招牌+程序化剧本混池,按会话确定性选本)。公聊群戏已 subagent 化:引擎并发 fan-out,每个角色一个隔离子代理、每人一句、泄密即净化(docs/03 §9 M2/M3 达标)。
• 时间循环:v1 落地 3 本手工剧本 + 程序化皮肤变体(M3:骨架 × 经典/武侠/西幻换名)+ 程序化时间表生成(M4:望海灯塔/黑石矿镇 2 场景 × 事故/崩塌/命案 3 因果链形状,全部过 ScheduleSolver,求解器排程计划可回放黄金路径;手工剧本《北桥镇秋祭日》《客栈大火》《宴会中毒》,8 时间片/循环,因果链封存):时间片推进、半 reset、元知识清单、循环 diff、快进重放、ScheduleSolver(结构/可解路径/链式前置排程/无环)与完美日 CausalVerifier 全部为纯函数;剧本按会话确定性选本,NPC 对话走隔离子代理 + 泄密审计,回滚即"循环内失忆"(docs/05 §9 达标)。
• 王国议会:v1 落地《云澜王国》(20 季、13 事件模板 + 事件链 + 平静季兜底、4 顾问议程扰动按种子生成)。经济模拟器回归测试(200 种子确定性、全最优通关/全最劣覆灭、随机存活率健康);顾问立场由标签偏好 + 开局扰动确定性计算(每个事件 ≥2 种立场且至少一人主张最优);顾问发言与追问走隔离子代理(议程/欺瞒边界注入、泄密即净化)。
• 跑团世界:手工招牌《霜松林地》+ 程序化生成两主题(荒漠驿站/海港疑云,同构骨架换皮),每个世界都过 solveWorld(结构校验 + 引擎黄金路径重放:勘查/战斗/交还失物/开门/打 Boss,最多 3 次种子尝试),不可解世界一律拒绝;按会话确定性选本。
• 内容与选牌:内置 8 道海龟汤(难度 1/2/3 = 2/4/2 道)。海龟汤/侦探/剧本杀/密室/时间循环/跑团均按会话 id 确定性选择内容,同一会话续局内容一致。
• 自然语言开局:game_start 工具与 /game new 命令等价,直接说"想玩王国议会"即可开局。

路线图进度(docs/08-comparison-roadmap.md §4):阶段 0 骨架 ✅、阶段 1 海龟汤 ✅、阶段 2 密室逃脱 ✅(含程序化题库 M3)、阶段 3 侦探推理 ✅(程序化案件 + 求解器 + 泄密审计 + NPC 子代理)、阶段 4 剧本杀 ✅(v1 闭环 + 反转模式 + 程序化剧本池 + subagent 群戏)、阶段 5 时间循环 ✅(确定性内核 + 快进重放 + 手工 3 本 + 皮肤变体 M3 + 程序化时间表 M4 + NPC 子代理)、阶段 6 ✅(王国议会 v1 + 单人跑团 v1(程序化世界生成 M2 + NPC 子代理))。路线图全部阶段达成;可选后续演进 = continuable 持久 NPC 会话(跨轮私有记忆)、workflow 群戏辩论编排。