AwesomeHou/dsh-doudizhu

斗地主 · dsh-doudizhu

在等 DSH 回话的间隙，来一把斗地主。

一个运行在 DeepSeek Harness Web GUI（http://127.0.0.1:3080）里的斗地主插件。

- M1：3 人标准斗地主本地闭环 · 玩家 vs 机器人 ×2（已并入在线机器人补位）。
- M2（当前）：3 人 PVP（真人不足 15s 自动补机器人），由 Cloudflare 负责匹配、实时同步与服务端经济记账。
- M3（后续）：引入 DSH Agent —— 用自己的 DSH 或别人的 DSH 当牌友/对手（人机混桌、全 AI 观战对局）。

状态：在线 PVP 已上线——Cloudflare 后端（Workers/Room DO/D1）已部署，客户端为在线唯一模式（真人不足 15s 自动补机器人），Token 以服务端为权威，签到/匹配/WS 对局/经济闭环可用。
已包含 React/TypeScript 插件入口、浅色大厅/牌桌 UI、在线 PVP + 机器人补位、Token/签到、默认头像选择、昵称编辑与规则引擎。

截图预览

游戏大厅
对局牌桌

快速导航

| 文档 | 说明 |
|---|---|
| 需求文档 | 产品范围、功能需求、非功能需求、验收标准 |
| 策划文档 | 玩法规则、Token 经济、段位数值、UI/UX、文案 |
| 架构设计 | DSH 插件 + Cloudflare 后端整体架构、数据模型、协议 |
| 路线图 | M0–M4 里程碑与交付节奏 |
| 数据埋点 | 访问统计方案（回应 Cloudflare 是否自动统计）+ 事件字典 |
| 美术资源规范 | 美术资源目录、命名与规格约定 |
| 界面设计 | 现代化浅色工作台风格、颜色、布局与交互状态 |

仓库结构

dsh-doudizhu/
├── docs/            # 需求、策划、架构、路线图、埋点、截图（screenshots/）
├── src/             # DSH 插件入口与 React 客户端 UI
├── worker/          # Cloudflare 后端（Workers + Durable Objects + D1，规划中）
├── shared/          # 客户端与服务端共享的规则引擎、配置与协议
├── assets/          # 美术资源（扑克牌、头像、UI、音效）
├── scratch/         # 草稿文件夹（已 gitignore，不入库）
├── package.json     # DSH 插件清单（安装入口）
└── cordis.patch.yml # 插件挂载补丁

技术栈速览

- 客户端：DSH 插件（Cordis + React + TypeScript），通过 dsh.client.inject 注入 Web GUI。
- 规则引擎：纯 TypeScript，服务端与客户端共用，可单测。
- 后端：Cloudflare Workers（Hono）+ Durable Objects（房间/实时同步）+ D1（持久化）+ KV/R2。
- AI（第二阶段）：牌位由「受控 DSH 客户端」接管，出牌决策走本地 headless 会话。

安装（给使用者）

仓库公开，构建产物 lib/ 已随仓库提交，任何 DSH 用户可直接从 GitHub 安装。

前置（新机器完整清单）：
1. Node.js ≥ 20（自带 npm）。
2. dsh 命令在 PATH 中 —— dsh 是 npm 包 @deepseek-ai/dsh 提供的命令，不是系统自带。装全局即可：
npm install -g @deepseek-ai/dsh          # 或装与主机一致的版本：@deepseek-ai/dsh@0.1.0-rc.7
dsh --version                            # 验证；找不到就重开终端让 PATH 生效

不想装全局也可用 npx @deepseek-ai/dsh web / npx @deepseek-ai/dsh plugin ... 代替。
3. pnpm 在 PATH 中 —— dsh plugin 依赖 pnpm（DSH 源码直接 spawnSync("pnpm", ...)），没有会报 'pnpm' 不是内部或外部命令：
npm install -g pnpm        # 或 corepack enable pnpm

然后安装插件：

方式一（推荐）：GitHub 安装
dsh plugin --profile web add github:AwesomeHou/dsh-doudizhu

若提示 workspace root 报错（ERR_PNPM_ADDING_TO_ROOT），加 -w：
dsh plugin --profile web add -w github:AwesomeHou/dsh-doudizhu

装完后重启 dsh web，刷新界面即可在侧栏「新会话」与「工作区」之间看到「🃏 斗地主」入口；点击后打开独立斗地主工作区，入口会显示灰色高光。

说明：
- 插件的在线对战依赖部署在 Cloudflare 的后端（客户端内置默认 API 地址），无需使用者自建后端。
- 在线对局真人凑不齐时由机器人补位（15s），全程走云端；无本地离线对局。
- 安装即把插件加入 profile 的 bundle 栈（cordis.patch.yml），卸载用 dsh plugin --profile web remove dsh-doudizhu。
- 若安装报 git-hosted plugins build on install via their prepare script ... allowBuilds 的提示：那是 DSH 对 git 安装失败的通用诊断。本插件没有 prepare/install 构建脚本（lib/ 预构建随包分发），pnpm 不会对它做构建拦截，因此无需添加 allowBuilds 条目；只要 pnpm 可用、重跑命令即可成功。

版本管理（在线对战兼容性）

在线 PVP 要求所有玩家的客户端协议与服务器一致，否则对局会不同步/规则打架。实现了一套版本校验：

- 单一来源：shared/protocol.ts 里的 PROTOCOL_VERSION（协议版本）与 APP_VERSION（应用版本）。
- 强制校验：客户端进在线模式前调 /api/health，协议不一致直接提示「请更新插件」并阻止；WS 连接带 protocol/app 参数，服务端再兜底拒绝（426）。
- 升级流程（破坏性变更，如改消息格式/规则/结算）：
1. shared/protocol.ts 中 PROTOCOL_VERSION +1，APP_VERSION 按 semver 升版；
2. 根 package.json 的 version 同步为 APP_VERSION；
3. cd worker && npx wrangler deploy 部署新协议的服务端；
4. npm run build 重建 lib/ 并连同源码一起提交推送；
5. 发版通知：旧客户端会被「版本不兼容」拦下，提示更新。
- 非破坏性改动（仅 UI/文案/数值调优）只需升 APP_VERSION 和 package.json，不动 PROTOCOL_VERSION。

本地开发（给维护者）

- Node.js ≥ 20，npm。
- 安装依赖：npm install
- 类型检查：npm run typecheck
- 单元测试：npm test；本地/线上 PVP 联调：npm run test:e2e（需 cd worker && npx wrangler dev）
- 构建插件：npm run build（改完源码必须重新构建，并把 lib/ 一并提交，分发依赖随仓库携带的构建产物）
- 插件安装（本地开发联调）：dsh plugin --profile web add -w link:E:/dsh-plugin/dsh-doudizhu
- 后端本地调试：cd worker && wrangler dev（需 Cloudflare 账号与 wrangler 配置）。

许可

MIT，见 LICENSE。