dsh-mini-games

Readme

# dsh-mini-games 🎮

[![npm version](https://img.shields.io/npm/v/dsh-mini-games.svg)](https://www.npmjs.com/package/dsh-mini-games)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

纯前端小游戏集合插件，挂在 **DeepSeek Harness** Web 界面的 **details 面板**（右侧栏，可拖拽调宽、可收起为零宽）。
内置三个可独立游玩的小游戏：**猜数字 / 2048 / 扫雷**。无宿主逻辑、无后端、最高分存 `localStorage`。

```
dsh-mini-games/
├── package.json      # dsh.bundle（cordis.patch.yml）+ dsh.client 声明 + exports["./client"]
├── cordis.patch.yml  # bundle 补丁层：add 时自动插入 mini-games 行
├── index.js          # 宿主半：空 apply（Loader 入口必须是合法插件）
├── client.js         # 浏览器半：lazy-CJS factory bundle（游戏面板本体）
└── test/smoke.mjs    # 本地冒烟测试（node test/smoke.mjs）
```

## 功能

- **details 面板常驻游戏集合页**：标签切换 猜数字 / 2048 / 扫雷，切换时游戏状态保留
- **🎮 右上角悬浮开关**：原生 UI 无法用鼠标重新打开收起的 details 面板（rc 半成品），本插件在 `shell.overlay` 插槽自带了开关按钮；无有效会话时点击会给出提示
- **最高分本地持久化**（`localStorage`，键前缀 `dsh-mini-games:`）
- 2048 支持方向键 + 屏幕按钮；扫雷支持右键插旗、首击安全、计时
- 全部使用 DSH 主题别名 token（`--dsw-alias-*`）配色，跟随明暗主题

![三个游戏面板实拍](docs/panels.png)

## 安装

```powershell
# 一条命令：本包声明了 dsh.bundle，add 时自动把补丁层挂进 profile
dsh plugin --profile web add dsh-mini-games

# 重启 dsh web（配置树在启动时重组）
dsh web
```

也可以直接从 GitHub 安装（首次会要求放行 allowBuilds）：

```powershell
dsh plugin --profile web add github:aga-j/dsh-mini-games
```

> 安装过程中的 `missing peer @deepseek-ai/*` 警告是正常现象（profile 的 `autoInstallPeers: false`，这些 peer 运行时由官方 bundle 提供），**不要**手动安装 `@deepseek-ai/cordis`。

重启后，点击聊天区**右上角的 🎮 圆形按钮**打开/收起小游戏面板。

**验证安装**（可选）：

```powershell
# 配置树里应能看到 mini-games 行
dsh --profile web --dump-config
# 浏览器半应可访问（200）
Invoke-WebRequest http://127.0.0.1:3080/plugins/dsh-mini-games/client.js
```

**要求**：DeepSeek Harness 0.1.0-rc.6+（Web profile）。面板需要处于一个**非空白的会话**中（首页或新建的空白会话点击 🎮 会提示「先进入一个会话」）。

## 卸载

```powershell
dsh plugin --profile web remove dsh-mini-games
# 然后重启 dsh web
```

临时禁用（不卸载）：编辑 `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml` 加两行，重启生效，删掉即恢复：

```yaml
- id: mini-games
  disabled: true
```

## 工作原理（对照 0.1.0-rc.6 源码核实）

| 机制 | 出处 | 说明 |
|---|---|---|
| 插槽 `sidebar / conversation / details / shell.overlay` | `@deepseek-ai/dsh-client-ui-layout` | 三栏 AppFrame 声明；`details` 为 `{ kind: 'single', scope: 'session' }`，关闭时零宽 |
| `ctx.slots.inject(key, cb)` | `@deepseek-ai/dsh-client-runtime` | 等待目标插槽**声明**出现后执行回调，声明坍缩时自动清理——注册进 `details` 必须走它（ui-layout 是兄弟入口，无排序边） |
| `ctx.slots.register({name, ...}, Comp)` | `@deepseek-ai/dsh-client-ui-slots` | single 插槽选项只有 `priority`/`registrant`；list 插槽（如 `shell.overlay`）有 `id/order/label` |
| lazy-CJS factory bundle | `@deepseek-ai/dsh-client-modules` | 执行脚本只 `window.__ModuleLoader__.load({id, factory})`，副作用在物化时运行；`require` 只认平台词（react 等）与其它插件 `./client` 入口 |
| `dsh.client` 包声明 | `@deepseek-ai/dsh-client-modules` | 节点半扫描 Loader 入口里声明 `dsh.client` 的包，合成 `window.__DSH_BOOT__`，在 `/plugins/<id>/client.js` 提供 `exports["./client"]` |
| 补丁文件机制 | `@deepseek-ai/dsh-app-boot` | `cordis.patch.yml` 是 profile/bundle 层的顶层 YAML 数组（id 覆盖、`insert` 列表、`!!js` 表达式） |
| 插件管理 CLI | `@deepseek-ai/dsh` | `dsh plugin --profile <name> <pnpm args>`（pnpm 透传，无独立 `add` 子命令） |

## 开发与自测

```bash
git clone https://github.com/aga-j/dsh-mini-games.git && cd dsh-mini-games
npm install          # 安装 devDependencies（react / react-dom，供冒烟测试用）
npm run check        # node --check client.js && node test/smoke.mjs
```

`client.js` 是手写的 lazy-CJS 产物，改完无需重新构建；重启（或客户端 HMR 就绪后）即生效。
冒烟测试覆盖：load 交接、factory 形状、apply 接线（`shell.overlay` 开关 + `details` 影子注册）、2048 滑动合并、扫雷生成/翻开、整面板 react-dom/server 渲染。

## 已知边界（rc 阶段契约）

- **`exports` 必须显式导出 `"./package.json"`**：client-modules 节点半用 `createRequire(ctx.baseUrl).resolve('<pkg>/package.json')` 解析包元数据，Node 的 exports 门禁会拦掉未导出的子路径（会令启动时的激活扫描直接抛错）。
- `details` 插槽为 single，且 **ui-conversation 已注册 DetailsPanel（priority 0）**：本插件的 `details` 条目用更低 priority（`-100`）影子化它，否则同优先级二次注册会抛错。副作用：面板打开时显示游戏，内置的会话详情视图被顶掉。
- 收起状态的面板无法用鼠标打开，本插件通过 `shell.overlay` 的 🎮 按钮提供开关；开关依赖 `ctx.layout`，开/关判断直接读 AppFrame 帧元素上的 `data-details-collapsed` 实时状态（不用本地镜像布尔值——切换会话或拖拽归零导致的面板关闭不会让它失步）。
- 面板宽度由 ui-layout 决定（300–520px，自动让步收缩后自动关闭）。
- 游戏状态在切换标签时保留（三个面板常驻挂载、CSS 隐藏），切换会话时重置。

## License

[MIT](LICENSE) © 2026 aga-j