[](README.md) [](README_EN.md)
# dsh-theme-minecraft
**把 DeepSeek Harness 变成一个像 Minecraft Java Edition 一样使用的 AI Coding Agent —— 打开 `dsh web`，第一眼不是「AI 编程工具」，而是「我打开了 Minecraft，这个世界里住着一个 AI」。**
[](#license)
[](https://github.com/your-username/dsh-theme-minecraft)
[](package.json)
> **工作原理**：本主题是一个标准 DSH 插件（bundle），**不修改 DeepSeek Harness 任何核心源码**。
> 会话、消息流、工具调用、审批、预设、工作区、凭据等真实能力全部通过 DSH 现有
> JSON-RPC / WebSocket API 完成，界面上的每一帧状态都有真实数据来源，没有任何伪造。
## ✨ 功能特性
- [x] **原版主菜单** —— WebGL 旋转全景 + 像素 Logo + 黄色闪字 + 石板按钮，`dsh web` 打印的 URL 打开即是
- [x] **会话即世界存档** —— 「继续对话」渲染成存档选择页，重命名 / 归档 / 刷新都走真实 `session/*` 调用
- [x] **模式选择 = Agent 预设** —— 生存 / 创造 / 冒险 / 专家四张像素皮肤，对应 DSH 的 standard / ptc / minimal / cordis 预设
- [x] **世界内聊天台** —— Steve 与「AI him」对话：流式输出、思考过程可折叠、模型 / Token / 工作区实时面板
- [x] **工具调用卡片** —— 📖 打开书、⚙️ 红石机关、⛏️ 挖掉方块……每个真实 `tool/call` / `tool/result` 都有像素皮肤
- [x] **危险操作审批** —— 审批面板弹出时跑酷小游戏自动暂停，允许 / 拒绝后恢复（`approval/request` waterfall）
- [x] **村民提问** —— AI 的澄清问题以村民对话气泡呈现，回答直接回流 DSH（`user-questions/request`）
- [x] **AI 思考跑酷** —— Chrome 离线小恐龙跑酷（T-Rex Runner，Chromium BSD 许可）只由真实 THINKING / STREAMING / TOOL_CALLING 状态驱动，空闲时绝不假装在思考
- [x] **五页设置中心** —— 游戏 / AI / 世界 / 音频 / 视觉：设置存 localStorage，音乐存 IndexedDB，API Key 存 DSH 凭据库
- [x] **音效与音乐** —— WebAudio 合成 8-bit 音效，支持导入自己的背景音乐（MP3 / WAV / OGG / FLAC / M4A / AAC / OPUS）
- [x] **桌宠与粒子** —— 互动桌宠（美西螈/猫/狼/苦力怕/恶魂，支持喂食、好感度、图鉴换宠）+ 经验球 / 红石粒子（限量 80 粒），独立开关
- [x] **零侵入** —— 经典 DSH Web 界面原样保留，`/index.html` 一键切回
## 📦 安装与使用
### 1. 环境要求
| 依赖 | 要求 |
| ---------------- | ------------------------------------------------- |
| Node.js | `^22.19` 或 `>=24`（DeepSeek Harness 运行要求） |
| DeepSeek Harness | 已安装，且 `dsh` 命令可用 |
| 浏览器 | 支持 WebGL 与 WebSocket 的现代浏览器 |
| DEEPSEEK_API_KEY | 真实对话必需，见下方「配置」步骤 |
### 2. 安装主题
**方式一：安装到 web profile（标准用法）**
```bash
dsh plugin --profile web add dsh-theme-minecraft # npm 发布后
dsh plugin --profile web add ./dsh-theme-minecraft # 或本地目录安装
```
安装后插件进入 `~/.dsh/profiles/web`，随 `dsh web` 自动挂载，无需其他步骤。
**方式二：仓库内源码运行（开发调试）**
在 DeepSeek Harness 仓库根目录执行：
```bash
pnpm dsh web --patch ./dsh-theme-minecraft/cordis.source.patch.yml --no-open
# 浏览器打开 http://127.0.0.1:3080/
```
### 3. 配置
1. **登录**：使用 `dsh web` 打印的带 `?token=` 的 URL 完成登录（与原版一致的签名
Cookie 流程，主题复用了 `connection.authorizeIndex`，没有绕过任何认证）。
2. **API Key**（二选一）：
- 主题内：主菜单 → 设置… → AI 设置 → 保存（走 `credentials/set` 写入 DSH 凭据库，值只进不出）；
- 环境变量：在 `.env` 里提供 `DEEPSEEK_API_KEY`。
### 4. 启动
```bash
dsh web
```
打开终端打印的 URL，即看到 Minecraft 主菜单。想回到经典界面，直接访问
`http://:/index.html`。主菜单的「模型选择」可切换新对话使用的模型
（`session/modelCatalog` 列出部署内全部可路由提供方，含非 DeepSeek 厂家；选择经
`session/selectModel` 安装到新会话）。
## 🛠 技术栈
| 技术 | 用途 | 版本 / 兼容范围 |
| ------------------------ | ---------------------------------------- | ------------------------- |
| JavaScript（ESM） | 插件与前端全部逻辑，零运行时依赖 | ES2022+ |
| Node.js | 宿主运行环境 | `^22.19` 或 `>=24` |
| Cordis 插件框架 | 插件生命周期与依赖注入 | `>=0.x`（peer 依赖） |
| WebSocket + JSON-RPC | 与 DSH 的全部真实通信（RPC / 流 / 事件） | DSH 内置 API |
| WebGL | 主菜单全景立方体贴图 | 浏览器原生（无 three.js） |
| Canvas 2D | AI 思考跑酷小游戏渲染（iframe 内 T-Rex） | 浏览器原生 |
| Web Audio API | 8-bit 音效合成与背景音乐播放 | 浏览器原生 |
| IndexedDB / localStorage | 设置与音乐文件持久化 | 浏览器原生 |
## 📁 项目结构
```
dsh-theme-minecraft/
├── .github/
│ └── workflows/
│ └── static.yml # GitHub Pages 自动部署（demo/ 素材演示站）
├── demo/ # Minecraft-Panorama 素材演示站（GitHub Pages）
│ ├── index.html # 主菜单演示（three.js 高清全景背景）
│ ├── 404.html # Pages 404 页面
│ ├── asset/ # 全景立方体贴图 6 张 + 界面素材
│ ├── css/ # 演示站样式与像素字体
│ ├── figure/ # 角色头像（Steve / 村民 / 苦力怕）
│ ├── loading/ # 加载地形页演示
│ └── worlds/ # 选择世界页演示
├── docs/
│ └── 开发文档.md # 主题设计开发文档
├── screenshots/ # README 演示截图
├── web/ # 主题本体（单页应用）
│ ├── index.html # SPA 外壳
│ ├── manifest.webmanifest # PWA 清单
│ ├── css/
│ │ ├── minecraft.css # 主菜单 / 存档页 / 设置页视觉
│ │ └── hud.css # 游戏 HUD
│ ├── fonts/ # Minecraft 风格像素字体（ttf / woff）
│ ├── assets/ # 官方素材：全景图、GUI、头像
│ ├── js/
│ │ ├── rpc.js # 浏览器协议客户端（unary RPC + 流 + $events）
│ │ ├── panorama.js # 原生 WebGL 立方体贴图全景
│ │ ├── menu.js # 主菜单 / 存档 / 模式 / 设置
│ │ ├── world.js # 游戏 HUD、AI 状态机、审批与提问面板
│ │ ├── store.js # localStorage 设置 + IndexedDB 音乐
│ │ ├── audio.js # WebAudio 合成音效 + 背景音乐
│ │ ├── particles.js # 经验球 / 红石粒子（限量 80 粒）
│ │ ├── pet.js # 桌宠（iframe 挂载 web/pet/pet.html）
│ │ ├── ui.js # 对话框 / toast / 闪字库 / 模式风味命名
│ │ └── main.js # 路由与启动
│ ├── pet/ # 桌宠应用本体（pet.html + picture/ 素材）
│ └── mini-games/
│ ├── dino-runner.js # 跑酷封装（T-Rex iframe 适配，createDinoGame 工厂）
│ └── t-rex/ # Chrome 离线小恐龙跑酷本体（Chromium BSD 许可）
├── index.js # Host 插件：注册 / 与 /minecraft 两条路由
├── cordis.patch.yml # bundle 层挂载声明（DSH 插件标记）
├── cordis.source.patch.yml # 仓库内源码调试层
├── package.json # dsh.bundle.patch 声明（bundle 形态）
├── LICENSE # MIT
├── .gitignore
├── README.md
└── README_EN.md
```
## 📸 效果截图
**主菜单** —— 下界全景旋转背景，黄色闪字是每个玩家的 reminder：
**世界存档** —— 历史会话渲染为存档卡片，可直接进入、重命名或刷新：
**模式选择** —— 四种游戏模式即四种 Agent 预设，右侧是 DSH 真实描述：
**世界内对话** —— Steve 与「AI him」聊天，AI 思考时弹窗出现小恐龙跑酷小游戏：
**工具与思考过程** —— 工具调用卡片、可折叠思考过程、完成时的经验球粒子：
**设置中心** —— 游戏 / AI / 世界 / 音频 / 视觉五个标签页：
> 仓库另带一个独立的 three.js 全景演示站（`demo/` 目录，即 Minecraft-Panorama 素材站），
> push 到 main 后由 GitHub Pages 自动部署；主题本体不依赖 three.js，全景由原生 WebGL 实现。
## 📄 License 信息
本项目以 **[MIT](LICENSE)** 协议开源。
[](#license)
> ⚠️ **素材版权说明**：`Minecraft` 名称与官方素材（全景图、GUI 贴图、角色头像、像素字体）
> 版权归 Mojang AB / Microsoft 所有，本项目仅作非商用粉丝主题使用。请勿将本仓库用于
> 商业产品；如需移除，Mojang 可随时提出要求。
## 🤝 贡献指南
欢迎 Issue 与 PR！为提高协作效率，请遵循以下约定。
**提交 Issue**
- **Bug 报告**请包含：
- 环境信息：操作系统、浏览器及版本、Node.js 版本、DeepSeek Harness 版本；
- 复现步骤（从哪条命令开始）、期望行为、实际行为；
- 浏览器控制台与 `dsh web` 终端日志截图。
- **功能请求**请说明：想解决的场景、期望的 Minecraft 表现形式、对应的 DSH 能力（若已知）。
**提交 Pull Request**
```text
1. Fork 本仓库
2. 新建分支 git checkout -b feat/your-feature # 或 fix/your-fix
3. 提交变更 git commit -m "feat: 支持 xxx" # 遵循 Conventional Commits
4. 推送并建 PR Push 到你的 Fork，向 main 分支发起 Pull Request
5. 等待 Review 按评审意见修改，通过后由维护者合并
```
> 注意事项：UI 变更请附改动前后的截图；请勿在 PR 中引入对 DeepSeek Harness 核心源码
> 的修改——主题能力只应通过 DSH 现有插件机制与 API 实现。