# 需求文档（PRD）

| 项目 | 内容 |
|---|---|
| 产品名 | 斗地主（dsh-doudizhu） |
| 阶段 | 规划期 · v0.1 草案 |
| 平台 | DeepSeek Harness Web GUI 插件 |
| 后端 | Cloudflare（Workers / Durable Objects / D1） |
| 状态 | 待评审（用户确认后冻结 v0.1） |

---

## 1. 背景与目标

### 1.1 背景
DeepSeek Harness（DSH）是一个带 Web GUI 的 AI 编程/对话工作台。用户在向 DSH 发起耗时任务（长对话、代码生成、后台 job）时，存在一段「等待时间」。我们希望把这段等待转化为轻量娱乐，同时不打断主对话流程。

### 1.2 产品目标
1. **即开即玩**：在 DSH 界面内一键进入牌局，无需注册、无需下载，匿名即玩。
2. **社交 PVP**：第一阶段支持真人玩家之间对战（3 人标准斗地主）。
3. **AI 融入（第二阶段）**：让「DSH 本身」成为牌友/对手——用自己的 DSH 或别人的 DSH 打牌，成为 DSH 生态内独有的玩法。
4. **玩具经济**：以 Token（非真实货币/非真实 LLM Token）为货币，每日登录领 200k，段位体系（小难梁→梁祖）驱动长期目标。
5. **贴合 DSH 风格**：视觉、文案、交互都像是 DSH 原生的一部分（白色内容面、浅灰边界、蓝色操作色、技术梗与克制动效）。

### 1.3 成功指标（北极星）
- 周活跃对局数（WAU 局数）
- 「等待期间开牌率」= 长任务期间打开牌局的人数 / 长任务会话数
- 次日回访率（次日再领一次登录 Token）

---

## 2. 用户画像与典型场景

| 画像 | 描述 | 典型场景 |
|---|---|---|
| 打工人 | 用 DSH 写代码/跑任务，等结果的碎片时间 | 跑测试/部署的空档，点开斗地主来一把 |
| 牌友组 | 几个都用 DSH 的同事/朋友 | 建好友房，三人开黑打牌 |
| AI 好奇者（Phase 2） | 想看「DSH 自己打牌」 | 观战自己的 DSH vs 别人的 DSH |

### 2.1 典型场景（User Story）
- **U1 等待开局**：用户向 DSH 发起长任务，界面提示「等待中，来一把斗地主？」，点击进入大厅。
- **U2 快速匹配**：用户选择桌别 → 匹配 → 凑齐 3 人 → 开局。全程 < 30 秒。
- **U3 领取签到**：每日首次进入大厅，自动/一键领取 200k Token。
- **U4 段位炫耀**：用户赢了，段位从「牢梁」升到「梁子」，收到升级提示与分享卡片。
- **U5 好友房**：用户创建房间并分享邀请码，好友加入后开局（Phase 2 支持）。
- **U6 人机混桌（Phase 2）**：用户开房，空位由「DSH Agent」接管（可指定自己的 DSH 或朋友的 DSH）。
- **U7 全 AI 观战（Phase 2）**：用户让自己的 DSH 与另一个 DSH 对局，自己观战并可下注（娱乐）。

---

## 3. 名词表

| 名词 | 定义 |
|---|---|
| Token | 游戏货币，虚构单位，不代表真实 LLM Token，无任何现金价值 |
| 段位 | 按 Token 总数划分的 6 级体系（小难梁→梁祖） |
| 底注 | 一局对局的默认押注，按桌别设定 |
| 桌别 | 按底注大小分档的房间类型（新手桌/进阶桌/高倍桌） |
| DSH Agent | 第二阶段引入的 AI 牌手，由某个 DSH 实例托管决策 |
| 匿名 UID | 本地生成的玩家唯一标识，未注册账户的等价物 |

---

## 4. 产品范围

### 4.1 第一阶段（PVP 上线，对应路线图 M1–M2）
| 模块 | 内容 |
|---|---|
| 身份与资料 | 匿名 UID（localStorage 持久化）、主页资料区编辑昵称、默认头像选择（DeepSeek 蓝/黑） |
| Token 经济 | 每日登录领 200k、余额展示、对局下注/结算、流水记录 |
| 段位 | 6 级段位判定、升级提示 |
| 对局（PVP） | 3 人标准斗地主：匹配/房间、叫地主、出牌、结算、断线重连 |
| 数据埋点 | 访问量、对局、经济、错误等事件上报与统计 |

### 4.2 第二阶段（DSH Agent，对应路线图 M3）
| 模块 | 内容 |
|---|---|
| 人机混桌 | 玩家 + DSH Agent 同桌 |
| 双 AI 对局 | 自己的 DSH vs 别人的 DSH，玩家观战 |
| 好友房 | 邀请码建房 |
| 自定义头像（可选） | 需启用 Cloudflare R2（用户决定暂缓，避免绑定支付方式） |
| 回收/找回 | UID 恢复码，防止清浏览器丢号 |

### 4.3 明确不做（当前）
- ❌ 不做真实货币/充值/提现。
- ❌ 不做游戏内商城/皮肤付费。
- ❌ 不做移动端原生 App（仅 Web 插件内）。
- ❌ 不做聊天系统（对局内仅预设表情/快捷短语，Phase 2 再评估）。
- ❌ 不做账号注册/手机号绑定（坚持匿名轻量）。
- ❌ 不做自定义头像上传（用户决定暂缓：启用 R2 需绑定支付方式，第一阶段只用默认头像）。

---

## 5. 功能需求

> 编号规则：`F-<模块>-<序号>`。优先级 P0（必须）/ P1（重要）/ P2（可延后）。

### 5.1 身份与资料
| 编号 | 需求 | 优先级 | 验收标准 |
|---|---|---|---|
| F-IDENT-01 | 首次启动在本地生成匿名 UID 并持久化（localStorage） | P0 | 刷新/重启后 UID 不变；清空浏览器后生成新 UID |
| F-IDENT-02 | 玩家可设置昵称（默认「斗地主玩家+4位随机数」），1–12 字符，需过滤敏感词 | P0 | 非法字符被拦截并提示 |
| F-IDENT-03 | 默认头像：DeepSeek 品牌蓝/黑两枚（assets/deepseek-blue.svg / deepseek-black.svg），玩家可选其一 | P0 | 头像选择器在主页资料区可见、可选、可预览；可扩展更多变体 |
| F-IDENT-04 | 客户端上传 UID+资料到后端建档 | P0 | 首次进入后后端 players 表存在该 UID 记录 |
| F-IDENT-05 | 自定义头像上传（**暂缓**，Phase 2+，需 R2）：客户端转 WebP + 压缩 → 上传 → 服务端校验 → 存 R2 | P2 | 暂缓；仅在设计上保留（见架构设计 §3.5） |
| F-IDENT-06 | 恢复码（Phase 2） | P2 | 输入恢复码可还原原 UID |

### 5.2 Token 经济
| 编号 | 需求 | 优先级 | 验收标准 |
|---|---|---|---|
| F-TOKEN-01 | 每日登录可领 200k Token | P0 | 每日仅可领取一次（UTC+8 自然日）；领取后余额增加 200k |
| F-TOKEN-02 | 余额由服务端记账（D1），客户端仅展示 | P0 | 客户端篡改不生效；以服务端流水为准 |
| F-TOKEN-03 | 对局入场扣除底注、结算按结果增减余额，含平台抽水 | P0 | 结算后三方余额变化 = 底注×倍数×结果，抽水单独入账 |
| F-TOKEN-04 | 展示 Token 流水（时间/类型/±数额） | P1 | 流水页最近 50 条可查 |
| F-TOKEN-05 | 破产保护：余额不足底注时，每日可「救济金」一次（如 100k） | P1 | 余额 < 最低底注时出现入口，每日一次 |

### 5.3 段位
| 编号 | 需求 | 优先级 | 验收标准 |
|---|---|---|---|
| F-RANK-01 | 段位由「Token 总余额」决定，共 6 级（小难梁/牢梁/梁子/梁圣/梁神/梁祖） | P0 | 段位与余额映射正确；阈值可配置 |
| F-RANK-02 | 历史最高段位保底，输钱不掉段 | P1 | 余额下降后段位不回退 |
| F-RANK-03 | 段位变化时给出明显反馈（弹窗/横幅 + 动效） | P1 | 升级触发提示，可分享 |
| F-RANK-04 | 段位分布埋点与展示（可选排行榜） | P2 | Admin 可看分布 |

### 5.4 对局（第一阶段 PVP）
| 编号 | 需求 | 优先级 | 验收标准 |
|---|---|---|---|
| F-GAME-01 | 3 人标准斗地主：54 张牌，发 17×3 + 3 张底牌 | P0 | 牌型、概率正确（引擎单测覆盖） |
| F-GAME-02 | 叫地主/抢地主流程 | P0 | 流程正确，无人抢则重新发牌 |
| F-GAME-03 | 出牌合法性校验（服务端权威） | P0 | 非法出牌被拒绝；客户端也本地预校验 |
| F-GAME-04 | 结算：春天/反春、炸弹倍数、底分计算 | P0 | 结算金额与规则表一致 |
| F-GAME-05 | 匹配系统：选桌别 → 队列 → 凑 3 人开局 | P0 | 单人可进队；满 3 人自动开局；等待超时可退出 |
| F-GAME-06 | 实时同步（WebSocket） | P0 | 三方出牌延迟 < 1s（正常网络）；状态一致 |
| F-GAME-07 | 断线重连：断线可回到原房间，对局暂停/托管 | P0 | 断线 30s 内重连恢复；超时由 AI/托管代打（Phase 1 简化为系统自动托管出最小合法牌） |
| F-GAME-08 | 对局内操作：出牌、过、提示、认输 | P0 | 交互可用、无卡死 |
| F-GAME-09 | 对局记录查询（近期战绩） | P1 | 我的对局页可查最近 N 局结果 |
| F-GAME-10 | 好友房（Phase 2） | P2 | 邀请码建房、加入 |

### 5.5 DSH Agent（第二阶段）
| 编号 | 需求 | 优先级 | 验收标准 |
|---|---|---|---|
| F-AI-01 | 玩家可开「人机混桌」房，空位由 DSH Agent 接管 | P0 | 玩家+2 Agent 可完整打完一局 |
| F-AI-02 | Agent 可指定为「自己的 DSH」或「他人的 DSH」 | P0 | 决策调用对应 DSH 的本地 headless 会话 |
| F-AI-03 | 双 AI 对局观战（自己的 DSH vs 别人的 DSH） | P1 | 全程自动推进，玩家可看、可离场 |
| F-AI-04 | Agent 出牌超时（如 15s）由规则引擎兜底代打 | P0 | 超时不卡局 |
| F-AI-05 | Agent 决策日志可查看（DSH 风格：出牌理由） | P1 | 对局详情页展示每手牌 Agent 的思考摘要 |

### 5.6 数据埋点
| 编号 | 需求 | 优先级 | 验收标准 |
|---|---|---|---|
| F-TRACK-01 | 访问量（PV/UV）统计 | P0 | 日活/周活可查（见数据埋点.md） |
| F-TRACK-02 | 关键业务事件（开局/结算/签到/段位变化）上报 | P0 | 事件可查询、可聚合 |
| F-TRACK-03 | 错误上报（前后端异常） | P1 | 错误率可查 |
| F-TRACK-04 | Admin 只读报表端点 | P1 | 用 token 鉴权，输出 JSON/简单页面 |

---

## 6. 非功能需求

| 类别 | 要求 |
|---|---|
| 性能 | 对局状态同步 p95 < 1s；首屏加载（牌桌）< 2s；不影响 DSH 主对话性能 |
| 可用性 | 后端可用性 ≥ 99.5%（Cloudflare 全球边缘）；断线可恢复 |
| 安全 | 服务端权威校验出牌/结算；防重复领取（幂等）；接口限流；匿名 UID 不可伪造（服务端签名） |
| 风控 | 防脚本/多开刷 Token：设备指纹 + 每日领取限次 + 异常对局检测（Phase 2 加强） |
| 可扩展性 | 规则引擎纯函数可移植；房间逻辑与持久化解耦；支持后续加 2 人斗地主/掼蛋变体 |
| 可观测性 | 埋点 + 结构化日志 + 错误上报（见 docs/数据埋点.md） |
| 隐私 | 不收集真实姓名/手机号；UID 匿名；埋点不含可定位个人身份字段 |

---

## 7. 数据与隐私

- 所有身份为**匿名 UID**，不要求注册，不绑定手机号/邮箱。
- Token 为虚构货币，服务端明确标注「无现金价值」。
- 埋点事件不含消息内容、聊天记录等敏感数据。
- 后端不落盘用户的 DSH 会话内容；DSH Agent 出牌决策只传递「牌局状态 + 手牌」到本地 DSH，且内容为游戏数据。

---

## 8. 风险与开放问题

| 风险/问题 | 影响 | 应对 |
|---|---|---|
| 匿名 UID 丢失（清浏览器） | 丢号、丢 Token | Phase 2 恢复码；UI 明示风险 |
| Token 通胀（每日免费 200k） | 经济失衡 | 平台抽水回收 + 高倍桌门槛 + 抽水/奖励数值调优（见策划文档 §6） |
| 3 人同时在线凑齐难 | 开局等待长、流失 | 新手桌快速填充 + 机器人填充（Phase 1 末期）/ 观战房间 |
| 跨 DSH 实例匹配 | 两个 DSH 都在各自本地 | 靠 Cloudflare 公网后端中转；同一玩家可在两台设备玩 |
| Agent 决策慢/不准（Phase 2） | 对局体验差 | 超时代打 + 决策日志 + 可调 Agent 提示词模板 |
| DSH 插件 API 细节待确认 | 挂载方式可能调整 | M1 先做最小验证（spike），再铺开实现 |

---

## 9. 验收标准（第一阶段上线）

- [ ] 无需注册即可完成「领 200k → 进大厅 → 匹配 → 打完整局 → 结算到账」闭环。
- [ ] 3 人 PVP 对局：规则、叫地主、出牌、结算全部正确（引擎单测通过）。
- [ ] 断线重连可恢复，不丢局。
- [ ] 每日签到防重复（幂等），Token 流水可查。
- [ ] 段位按余额正确判定，升级有反馈。
- [ ] 埋点：PV/UV 与关键事件可从 Admin 端点查询。
- [ ] 主对话不受影响：长任务期间开牌不阻塞 DSH 主流程。