dsh-plugin-feihualing —— 飞花令游戏插件

DeepSeek Harness 飞花令游戏插件：简易 / 古法严格双模式，游戏状态（令字、得分、已使用诗句、剩余提示次数）由插件按会话独立维护；插件自身不向主聊天输出流写入任何内容，所有播报由模型根据工具返回值完成。

玩法

关键词指令（直接对插件说）

指令	作用
开始飞花令 / 开始游戏	开启一局（关键词默认简易模式）
结束飞花令 / 结束游戏 / 停止飞花令	结束对局并结算
换字	更换令字（得分与已用诗句保留）
提示	消耗 1 次提示次数，给出参考诗句
认输	认输并结算
暂停	手动暂停并保存现场
继续飞花令 / 继续游戏	从暂停处继续

非指令的普通消息若包含令字，会被当作诗句尝试自动判定；不含令字的消息视为聊天，直接忽略。

判定规则

• simple 简易：诗句（4–48 字）任意位置包含令字即可，得分 +1；重复诗句无效。
• ancient 古法严格：令字必须位于本轮指定位置（第 1 字 → 第 7 字循环）；位置不符或诗句过短无效。

模型工具

工具	说明
feihualing_start	开始/重新开始对局，可选参数 mode: simple | ancient
feihualing_status	查询状态：模式、令字、得分、已用诗句、剩余提示次数、最近判定等
feihualing_stop	结束对局并结算

自动暂停（保存现场）

检测到 shell / 文件写入类工具调用（bash、pwsh、shell、write、edit 等，可配置 autoPause 关闭）时，游戏自动暂停，现场写入快照文件；宿主重启后同一会话可通过「继续飞花令」恢复。手动暂停同样保存现场。

配置

在 profile 的 cordis.yml 对应条目下配置（缺省值如下）：

- id: feihualing
  name: dsh-plugin-feihualing
  config:
    enable: true        # 总开关
    maxHintCount: 3     # 每局最大提示次数（0-10 整数）
    autoPause: true     # shell/文件写入工具调用时自动暂停

安装

本插件是 DSH bundle，安装到 profile 即自动挂载（id feihualing），运行时零第三方依赖。需已装 dsh CLI（或桌面版）、Node.js ≥ 20、pnpm ≥ 10；下文 profile 以 desktop 为例，替换为你实际的 profile（见 $DSH_HOME/profiles/）。

从 GitHub 直接安装（推荐）

dsh plugin --profile desktop add github:zhaoxuejie/dsh-plugin-feihualing

• git 安装拿到的是源码，包的 prepare 脚本会在安装时自动执行 pnpm run build 生成 lib/，无需手动构建；
• pnpm ≥ 10 默认拒绝执行 git 依赖的 prepare，首次会失败：请在该 profile 目录的 pnpm-workspace.yaml 加入白名单后重跑上面的命令：

allowBuilds:
  dsh-plugin-feihualing: true

⚠️ 允许构建 = 允许安装时在您机器上执行该包代码，仅对信任的源码开启；更稳妥的是固定 commit：github:zhaoxuejie/dsh-plugin-feihualing#<sha>。

克隆源码本地安装

git clone https://github.com/zhaoxuejie/dsh-plugin-feihualing.git
cd dsh-plugin-feihualing
pnpm install && pnpm run build
dsh plugin --profile desktop add .   # 在仓库根目录执行

或经 npm / tarball 安装（预构建，免白名单）

dsh plugin --profile desktop add dsh-plugin-feihualing               # 已发布 npm 时
dsh plugin --profile desktop add ./dsh-plugin-feihualing-1.0.0.tgz   # 或 pnpm pack 产物

验证与卸载

dsh --profile desktop --dump-config   # 应能看到 "# == dsh-plugin-feihualing" 层
dsh --profile desktop                 # 启动后对模型说「开始飞花令」即可开局

dsh plugin --profile desktop remove dsh-plugin-feihualing   # 卸载并清理快照

可选配置（提示次数、自动暂停等）见上方「配置」章节。

文件读写安全（白名单）

• 快照目录固定为 $DSH_HOME/storages/dsh-plugin-feihualing（DSH_HOME 环境变量优先，否则 ~/.dsh）。
• 所有读写经 assertSnapshotPath() 校验：会话 id 仅允许 [A-Za-z0-9._-]{1,64}、防目录穿越、文件大小上限 64 KB、内容逐字段校验；白名单目录以外的任何路径一律拒绝。
• 插件卸载时清空全部会话内存状态并删除白名单目录内全部快照（无残留）。

其它说明

• 不使用定时器、无后台任务；会话之间状态完全隔离。
• 事件映射（需求名 → 本 Harness 实际事件）：user:message → user/message、turn:before → turn/start、turn:after → turn/end、tool:before → tool/call、plugin:unload → Cordis fiber dispose（ctx.effect 清理 + 字面量事件兜底）。
• 不做侧边 UI 面板（按需求仅工具与事件逻辑）；游戏状态经 feihualing_status 返回给模型播报。