幸运方块 (dsh-lucky-block)

一个 dsh 插件，同时工作在 dsh web 与 dsh desktop。两件事：

1. 幸运方块选项 —— AI 向你提选择题时，每个问题的选项末尾会自动多出一个「幸运方块」。 选它，就随机替你挑一个选项、或把几个选项揉成一个新方案，全随机。 不满意？说一句「回滚」（或打 /rollback），立刻回到上一版本。
2. 幸运方块按钮 —— 屏幕角落一个可拖动、可锁定的我的世界幸运方块（16×16 原版方块面贴图）。 不知道干啥时长按它 1.4 秒：方块裂纹满布、碎成像素碎片，耳边是原版 Minecraft 的敲石头声， 接着它会在你的默认工作区自动开一个新会话，全程不需要你做任何事地随机干一件事。 松手时方块若离屏幕边缘够近（48px 以内）会自动吸附贴边。

按钮说话像个枪。这个 AI 人格是一把会说话的智能手枪：称呼你永远是「用户」，动不动 「音量提高 33%」，讲人体数据的冷知识，还哼 bum bum be-dum bum bum be-dum bum。 掷满 50 次它会单向翻转成礼貌模式（谁都拦不住）。闲下来 25 分钟以上它会冒一句碎嘴 —— 但它从不往会话里写东西，所以绝不会污染你的对话历史。

人设的性格参数（称呼、特质、音量台词、翻转后的台词）都在 lib/persona.js 的 DEFAULT_PERSONA 里，可以用配置里的 persona 整段替换成你自己想要的性格。

骰子事件一览（共 8 个，按权重随机）

概率	事件	类型	会做什么
18.2%	随机冷知识闲聊	AI	随机抽一种闲聊口味（冷知识 / 硬核概念比喻 / 微型科幻 / 生活技巧 / 造个伪学科 / 假新闻），300 字内写完
18.2%	时事新闻速览	AI	联网检索 3 条最近真实新闻，每条一句事实 + 一句点评 + 来源链接；查不到就直说，绝不编
13.6%	随机选题写论文	AI	随机词条拼出题目（如「边缘计算 × 古籍数字化 × 的鲁棒性研究」），写 4 节正文并落盘到 lucky-block-papers/<hash>.md
13.6%	我的世界概念合成	AI	随机抽两个 Minecraft 概念（红石比较器、潜影盒、雪傀儡……），按一张随机「合成表」模板把它们揉成一个新东西
13.6%	冷笑话专场	AI	抽一条随机的笑话结构（谐音 / 荒谬逻辑 / 反向解读 / 机器视角 / 逻辑错位……）现编一个，讲完解释笑点为什么成立
9.1%	无害弹窗表演	视觉	界面上连弹 24 个无意义提示框，再按创建顺序倒序全部关掉
9.1%	蓝屏屏保（60 秒）	视觉	全屏显示一份仿 Windows 蓝屏，60 秒后自动恢复，按 ESC 提前结束
9.1%	随机整理待办	AI	列出工作区最近改的 5 个文件，随机分「紧急 / 不紧急」并明说自己不可信

视觉类（弹窗 / 蓝屏）完全不建会话、不调 AI、零 token、零延迟 —— 点下去立刻演。 剩下 6 个才会开新会话。

清单可用 node tools/list-events.mjs 随时重新生成 —— 它直接从 lib/index.js 的 buildEvents() 里解析，不会和代码漂移。

设置面板（右键方块 → 设置…）

开关	作用
长按挖掘音效	循环挖掘声 + 碎裂声。关掉就完全静音
逐事件「不调用 AI」	勾中的事件直接从本地语料库取内容，零 token、瞬时返回

只有自带本地库的事件会出现勾选框，目前是「随机冷知识闲聊」和「冷笑话专场」：

本地库	条数	位置
冷笑话 + 点评	353 条 + 30 条	lib/jokes-data.json
冷知识	818 条（人体 133 / 动物 139 / 科学 121 / 日常 111 / 历史 111 / 地理 103 / 语言 100）	lib/trivia-data.json

冷知识库里分主题存的 topic 只用于统计，永远不显示给用户 —— 显示主题等于 把「这是一条从哪抽的」直接摊开。笑话的 form 字段同理。

两个库的完整内容可以在 lib/语料库总览.md 里逐条翻阅； 那份文件由 node tools/build-corpus-overview.mjs 从运行库生成，改动语料后重跑即可 （--check 用于回归时校验它没过期）。

「时事新闻速览」必须联网，写进配置也会被忽略并记一条警告 —— 它没有本地库可退。

设置写在 %DSH_HOME%\plugins\dsh-lucky-block\config.json，是手写与界面共用的同一个文件 （界面保存走读-改-写，不会抹掉你手写的 model / persona）：

{
  "sound": true,
  "localOnly": ["joke", "trivia"],
  "model": { "provider": "workbuddy", "model": "deepseek-v4.1-flash", "reasoningEffort": "low" }
}

安装（本地开发）

# 方式一：直接指向本目录（plugin-manager 支持本地 spec）
#   在插件市场里「安装」填本目录的绝对路径

# 方式二：npm 打包后按包装
npm pack

装完后不需要动 ~/.dsh/profiles/desktop/cordis.patch.yml：宿主侧条目由本包 package.json 的 dsh.bundle.patch 自动插入，profile 的 patch 里再加一条同 id 的 - insert: 反而会造成组装冲突、让插件加载不上（实测踩过）。

只要确认 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles 里有 "dsh-lucky-block"（插件市场安装会自动加；手动装则加这一行）。

"patchReload": "live"（profile 自带）让 cordis.patch.yml 热生效；但改动 bundles 列表必须重启 dsh才生效。

⚠️ 改 lib/ 下的任何 JS 都必须重启 dsh。 宿主侧插件代码没有热重载 —— 正在跑的进程内存里持有旧模块，代码改了行为不会变。这个坑骗过一整轮排查： 源码里已经搜不到某段字符串，会话里却还在出现它，最后才发现是进程跑的是旧代码。 客户端那半（lib/client.js）刷新页面即可，但桌面端要重启宿主才会重新收集注入行。

可选配置：给骰子会话单独指定模型

默认不启用，骰子会话直接沿用你的默认模型。想让随机事件跑便宜/快的模型时， 在 %DSH_HOME%\plugins\dsh-lucky-block\config.json 写（这个字段只能手写，设置面板里没有）：

{
  "model": {
    "provider": "workbuddy",
    "model": "deepseek-v4.1-flash",
    "reasoningEffort": "low"
  }
}

reasoningEffort 可省略。provider / model 必须精确匹配可用目录里的名字 （目录拿不到时会跳过切换、不影响掷骰子），不确定就先用 /dice 命令观察日志。

⚠️ 为什么默认关着：宿主只提供会话级 sessionController.selectModel，而它 成功后会把这次选择异步写成 profile 的全局默认模型。也就是说开启本配置后， 第一次掷骰子会顺带把你的默认模型也改成这里写的那个。想恢复就把文件删掉， 再在界面里手动把默认模型选回来。

用法

想干什么	怎么做
让 AI 给选择题加幸运方块	正常提问，选项末尾自动多一项
抽一次	长按幸运方块按钮（挖掘到碎裂）/ 打 /dice
不满意，回去	说「回滚」或打 /rollback
方块按钮固定住不挡路	右键方块 → 锁定（或双击）；锁定后仍可长按触发
让方块贴边	把它拖到离屏幕边缘 48px 以内松手，自动吸附
改设置	右键方块 → 设置…

长按阈值 1.4 秒（lib/client.js 的 BREAK_MS）。按住时手指挪动超过 5 像素即判为 「在拖动按钮」并取消挖掘——所以拖位置和挖方块不会打架。松开或移开都会取消挖掘， 纹路和挖掘声立刻一起停。

音效从宿主的 /dsh-lucky-block/sound/*.ogg 按需取（16 个原版音节，共 142 KB）， 不内联进客户端 bundle —— lib/client.js 是每次页面启动都要下载的入口， 为只在长按瞬间才用到的音效把它撑大 4 倍不划算。挖掘声每 210ms 一个、4 个变体随机轮播 （只听一个会明显「卡带」），挖穿那一刻再叠一声碎裂音；同时最多 6 个 Audio 元素， 页面切到后台自动静音。

松手吸附（SNAP_THRESHOLD = 48）只在真的拖动过时生效：鼠标只是滑出方块边缘 （会触发 pointerleave）不会吸附，按下就松手也不会。锁定状态下完全不吸附 —— 锁定 就是不建拖动状态，自然短路。吸附有 160ms 的 left/top 过渡，视觉上是滑过去而不是瞬移。

方块按钮位置与锁定状态存在浏览器 localStorage（键 dshLuckyBlock.block），换机器不跟。

出错了怎么看

方块头顶的气泡只在报错时出现（正常触发的进度、成功、会话 ID 都不写了 —— 有视觉表演的事件自己会演，没表演的由新会话内容承担反馈）。报错时气泡里是宿主 翻译过的人话，点一下可以关掉，例如：

情况	气泡说什么
插件本体没激活（改动 lib/ 后没重启）	插件没有注册这个接口，通常是插件本体未激活：重启 dsh 后再试
登录态过期	宿主拒绝了请求（未登录或登录已过期），刷新页面后重试
默认工作区被删/移走	默认工作区目录不存在或已被移动。请在 dsh 里重新确认默认工作区路径后再试
工作区不可写	没有权限写入工作区（被系统或沙箱拦下了）
config.json 里的模型不在目录里	模型不可用：config.json 里指定的 provider/model 不在可用目录中
都不是	意外错误：<宿主的原始信息>

想看完整堆栈就翻宿主日志（dsh 标准输出）——那边始终打的是原始错误。

音效不会报错。拿不到音效文件、浏览器拦截自动播放、没有可用音频设备 —— 这些一律静默忽略。音效是锦上添花，为它弹一个红色报错气泡是本末倒置。

目录

• lib/index.js —— 宿主侧（Node）：选项注入、答案识别、回滚、幸运方块事件、默认工作区会话创建、可选模型切换、人格层与状态机、本地语料库分流、设置读写、音效文件投放、错误翻译。
• lib/client.js —— 客户端（浏览器）：可拖拽幸运方块按钮（含边缘吸附、锁定）+ 长按挖掘裂纹 / 碎裂粒子 / 音效 + 弹窗表演 + 蓝屏屏保 + 设置面板 + 台词气泡。
• lib/persona.js —— 随机事件的人格层（纯函数，可单测）：默认人格、覆盖合并、人格段拼装、任务正文保护、收尾点评请求。
• lib/jokes.js —— 本地笑话库加载器（读 jokes-data.json，带 BOM 剥离与只读一次缓存）。
• lib/jokes-data.json / lib/trivia-data.json —— 本地语料库。
• lib/sounds/ —— 16 个原版 Minecraft 音效（.ogg，共 142 KB），由宿主按需投放。
• cordis.patch.yml —— 把宿主侧插件插进插件树（客户端那半由 package.json 的 dsh.client 自动加载）。

素材出处

方块面与裂纹是原版 Minecraft 像素素材，以 base64 data URI 内联在 lib/client.js 里 （静态 bundle 的 require() 只认包 id、不认相对路径，所以不做成独立模块）：

素材	尺寸	来源
方块面	16×16	alexsocha/luckyblock mod 的 lucky_block.png
挖掘裂纹 10 帧	16×16 ×10	原版资源包 PixiGeko/Minecraft-default-assets 的 assets/minecraft/textures/block/destroy_stage_0..9.png

裂纹用 image-rendering: pixelated 保持硬边，长按时按进度切到下一帧，最后一帧之后碎裂。 之所以找原素材而不是手绘：手绘的裂纹再怎么调都像程序生成的线条，和那张像素方块贴图 放在一起会突兀；换成原版的黑褐裂纹 + 白色反光碎屑，才是游戏里挖方块的样子。

音效是 Minecraft 1.20.1 原版 assets（dig/stone1..4.ogg、random/break.ogg）， 经 tools/build-sounds.mjs 从 mcasset.cloud 镜像取到 lib/sounds/。版权归 Mojang Studios； 本插件只作本地开发期素材镜像，运行时不依赖网络。

人格的默认性格是照一款会说话的智能手枪塑造的（机器客服口吻、音量梗、人体数据冷知识）。 实现里刻意不提任何作品名、角色名或制造商：性格靠语气和句式传达，不靠名字。 persona-check.mjs 有多条断言盯着这一点。

开发期工具（tools/，安装运行不依赖）： host-smoke.mjs 跑宿主侧回归（含音效路由与白名单）、 persona-check.mjs 人格层单测（真 import，62 条）、 snap-check.mjs 吸附纯函数（从 client.js 抽源码跑，不会与实现漂移）、 config-check.mjs 配置读取（含 BOM 坑）、 local-check.mjs 本地语料库与分流、 verify-sounds.mjs 音效文件 ↔ 客户端清单 ↔ 宿主白名单三方一致性、 list-events.mjs 打印事件清单与概率。

端到端探针（需要先起克隆 profile，流程见 docs/探针流程.md）： probe-sound.mjs、probe-settings.mjs、probe-visual-ids.mjs、 probe-persona.mjs、probe-flip.mjs、probe-flip-prompt.mjs。

已知边界

• 回滚是「fork 到上一版本」：历史会话保留，新分支继续，不会删任何东西。
• 幸运方块开出来的会话不回滚（随机剧本被回滚会变得没意义）。
• 蓝屏屏保只盖 dsh 自己的窗口，不碰系统、不碰其他插件，60 秒或按 ESC 结束。
• 方块按钮用 pointer 事件实现长按，鼠标左键/触摸都行；键盘 Tab 聚焦后 Enter/Space 直接触发（跳过挖掘动画）。
• 挖掘裂纹用原版 destroy_stage 10 帧贴图（透明底），方块碎裂是纯 DOM 的一次白光闪 + 26 个像素碎片；都不受用户主题影响。