# 策划文档（GDD） | 项目 | 内容 | |---|---| | 版本 | v0.1 草案 | | 主题 | 斗地主 · DSH 插件 | | 定位 | 等待 DSH 回复时的轻量对局，白色轻量技术风，匿名即玩 | --- ## 1. 世界观与主题 ### 1.1 「梁」的梗 段位体系以「梁」为家族命名（小难梁 → 梁祖），这是产品的记忆点： - 谐音/梗来源：DeepSeek 创始人梁文锋的姓氏「梁」（梁子/梁圣/梁神/梁祖 均为由此衍生的玩家尊称梗）。 - 氛围：跟 DSH 的产品气质一致（清晰、克制、技术感，但允许有趣）。 ### 1.2 叙事（一句话） 「DSH 忙它的，咱们打我们的。赢了算你的，输了……再领 2k 继续。」 ### 1.3 视觉基调 - **主题适配（增强兼容性）**：所有语义色不再写死浅色值，而是映射到 DSH 宿主主题令牌（`--dsw-alias-*`）。宿主切浅色/深色或安装第三方主题时自动跟随（官方浅色、官方深色、第三方主题全覆盖），每个映射带浅色兜底、宿主无主题时视觉零回归；扑克牌作为「物理牌面」保持白底红黑不变。详见 [DESIGN.md](../DESIGN.md)。 - 默认基调（浅色）：白色内容面与浅灰牌桌，蓝色主操作色 + 红/金语义强调色，贴近 DSH 的轻量工作台界面。 - 布局：无独立顶部信息栏，直接进入中央低对比度牌桌画布；顶部揭示底牌，左右两侧放对手，每位玩家前方有独立出牌区，底部是自己的手牌，操作按钮位于出牌区与手牌之间。 - 手牌和玩家出牌区采用欢乐斗地主式横向叠牌：第一张完整显示，第二张及之后只露出部分牌面，保证多张牌紧凑可读。 - 牌面左上角显示点数与花色，右下角显示花色；红色花色和黑色花色沿用统一语义色。 - 底牌在叫地主阶段保持隐藏，确认地主并进入出牌阶段后再揭示；地主身份标记与底牌保持同一时机出现。 - 叫地主阶段以三张黑色 DeepSeek 牌背占位；确认身份后显示地主/农民标志，并为每轮出牌提供 25 秒时限，当前行动玩家持续显示倒计时。 - 对局为在线唯一模式（已移除本地机器人板块）：真人不足时由机器人补位，机器人昵称取自真人风格昵称池，按 0.9–2.5 秒人性化节奏叫地主/出牌；有人叫过后，玩家操作切换为“抢地主/不抢”。 - 大厅将玩家信息与 Token 余额纵向排列在同一信息组内；入口位于 DSH 侧栏“新会话”与“工作区”之间，复用侧边栏的白底、细边界与紧凑字号。 - 主页头像可点击打开默认头像选择器；昵称旁提供编辑图标，支持在原位编辑、保存与取消，昵称继续受 12 个 Unicode 字符限制。 - 组件：所有玩家复用统一信息胶囊；头像上方显示段位，卡片内显示头像、昵称和较小字号的 Token 数量（按 k/M/B 格式化），下方显示信息标签，对手显示剩余手牌数量，自己显示本局实时倍率，并统一地主/农民身份标记与行动边界提示。自己的个人信息与手牌同排展示，不用厚重面板或成排牌背填充空间。 - 玩家昵称最多 12 个 Unicode 字符，超出部分截断，避免破坏玩家信息胶囊布局。 - 字体：等宽字体用于数字/Token 金额，贴合「余额/日志」的技术感。 - 动效：克制，独立工作区打开、小窗出现、底牌翻牌揭示、各自出牌、轮到行动和按钮反馈使用短时缓动；不做花哨粒子，并支持减少动效设置。 - 交互：按钮和桌别卡片提供清晰的 hover、focus、selected、disabled 状态；支持减少动效设置。 - **品牌素材**：默认头像与牌背都基于 DeepSeek 品牌图（蓝 `deepseek-blue.svg` / 黑 `deepseek-black.svg`），同一元素贯穿「玩家形象 + 牌桌」，形成辨识度。 - 细节设计规范见 [assets/README.md](../assets/README.md)。 --- ## 2. 核心玩法：3 人标准斗地主 ### 2.1 对局流程 ``` 开始 → 洗牌 → 发牌(分3轮, 每轮6/6/5张, 期间可"明牌"×4/×3/×2) → 叫地主 → 抢地主(其余两家先抢, 最后回到叫地主的人再选择, 每次抢×2) → 加倍(每人5s内选 不加倍/加倍×2/超级加倍×4) → 确认地主+底牌 → 出牌循环(地主可明牌×2) → 一方先出完 → 结算弹窗 → 返回大厅 ``` ### 2.2 叫地主与抢地主 - 随机起始叫牌者（上局赢家可优先，首局随机）。 - 叫牌顺序按**逆时针**推进：从随机起始座位开始，依次下家 → 再下家，与出牌阶段方向一致。 - 轮流「叫地主/不叫」；首个叫的人成为「叫地主的人」并直接进入**抢地主环节**：其余两家按原顺序依次「抢地主/不抢」（每次抢倍数 ×2），**最后回到叫地主的人再选择「抢地主」（抢回）或「不抢」**。 - 若三家都不叫 → 重新发牌（不重复扣费，但算一次「洗牌重开」埋点）。 ### 2.3 明牌与加倍 - **发牌期间明牌**：发牌分 3 轮进行，第 1/2/3 轮明牌的倍数分别为 ×4/×3/×2（越早明牌倍数越高）；明牌后该玩家手牌对所有人公开，并在其个人名片上方以小牌展示。 - **加倍环节**：抢地主结束后、出牌前，每人有 5 秒选择「不加倍 / 加倍 ×2 / 超级加倍 ×4」，选择叠加。 - **决策限时**：叫地主、抢地主、加倍等决策动作每人均限时 5 秒（操作区显示倒计时），超时由服务端托管。 - **地主明牌**：出牌阶段**仅第一轮出牌时**（地主还没出过牌）可明牌一次，明牌后手牌公开且本局倍数 ×2；出过牌后不可再明牌。 ### 2.3 牌型（标准规则） | 牌型 | 示例 | 说明 | |---|---|---| | 单张 | 3 | 单牌 | | 对子 | 33 | 两张同点数 | | 三张 | 333 | 三张同点数 | | 三带一 | 3334 | 三张 + 任意单 | | 三带二 | 33344 | 三张 + 一对 | | 顺子 | 34567 | ≥5 张连续单牌（不含 2 和王） | | 连对 | 334455 | ≥3 组连续对子 | | 飞机 | 333444 | ≥2 组连续三张 | | 飞机带单/带对 | 33344456 / 3334445566 | 飞机带翅膀 | | 四带二 | 333345 / 33334455 | 四张带两单或两对（不是炸弹） | | 炸弹 | 3333 | 四张同点数，可炸任何非炸弹 | | 王炸 | 大小王 | 最大，可炸一切 | - **大小**：3<4<... 一切普通牌型；同牌型比最大点；王炸最大。 - **禁止**：顺子含 2 或王；飞机翅膀规则按通用线上规则实现（允许带对）。 - **过**：本轮不出；**跟牌**必须大过上家同类型（炸弹/王炸例外可改变类型）。 ### 2.4 结算与倍数 - 基础分 = 桌别底分（见 §6）。 - **开局倍数 ×15**（每局起始）；倍数叠加：发牌明牌 ×4/×3/×2；抢地主每次 ×2；加倍 ×2 / 超级加倍 ×4；炸弹/王炸 ×2；地主明牌 ×2。 - **春天**：地主首出且农民一张未出 → 结算 ×2；**反春**：农民先出完且地主未出牌 → ×2。 - **每场封顶**：赢家所得不超过它自己的本金（开局余额），同时保证任何一方都不会输超本金——即实际生效的 `stake = min(底分×倍数, 地主本金/2, 各农民本金)`。 - 结算公式（每局）： - 地主胜：每农民付 `底注 × 倍数` 给地主。 - 农民胜：地主付 `底注 × 倍数` 给两个农民（各半）。 - 平台抽水：从**赢家所得**中抽取 `rake%`（默认 5%），输家支付额不变。 - 示例：底注 100，倍数 8（2 炸 + 春天），地主赢 → 每农民付 800，地主得 1600×0.95 = 1520，抽水 80。 --- ## 3. 局外系统 ### 3.1 信息架构 ``` 启动插件 └─ 大厅（Lobby） ├─ 我的信息：昵称/头像/段位/余额 ├─ 每日签到（2,000，今日未领时高亮） ├─ 桌别选择（新手桌/进阶桌/高倍桌）→ 匹配队列 ├─ 好友房（Phase 2） ├─ 我的对局（战绩） ├─ 流水 └─ 设置（昵称/默认头像/音效/退出） 对局中：牌桌 → 结算页 → 返回大厅 ``` ### 3.2 匹配（Phase 1） - 用户选桌别（底注档位）→ 进队列，显示「匹配中… 已等待秒数 · x/3（点击取消）」（如 `匹配中… 12s · 2/3`），退出不扣费。 - 满 3 名真人自动开局；等待超过 15s 仍未凑满，则由机器人补位垫满 3 人开局（机器人伪装成真人：真实感昵称 + 人性化出牌节奏）。 - 机器人补位玩家的 Token 余额以本桌真人平均余额为基准（±20%），避免与玩家余额相差太远穿帮。 - 桌别门槛：余额需 ≥ 该桌「余额门槛」才能进，防止秒破产。 - 匹配不按段位分（阶段一用户量少），只按桌别。 ### 3.3 大厅状态 - 余额与段位实时刷新（服务端返回）；在线 Token 以服务端为权威，与本地/机器人模式完全独立。 - 签到：`/api/daily` 领取，幂等（同日重复请求返回已领取）；「今日已领」状态同样来自服务端，跨会话/跨设备一致。 - 反馈气泡（签到/救济金/提示/错误）约 2.6 秒自动淡出，无需手动点击关闭。 --- ## 4. 段位体系 ### 4.1 段位定义（按 Token 总余额） | 段位 | 名称 | 余额区间（Token） | 大约到账时间（仅签到，每日 2000） | 文案梗 | |---|---|---|---|---| | 1 | 小难梁 | 0 – 4,999 | 初始 | 「新手，牌都还认不全」 | | 2 | 牢梁 | 5,000 – 19,999 | ~3 天 | 「坐牢般打工攒 token」 | | 3 | 梁子 | 20,000 – 99,999 | ~2 周 | 「量子纠缠般算牌」 | | 4 | 梁圣 | 100,000 – 499,999 | ~2 个月 | 「靠赢牌登圣」 | | 5 | 梁神 | 500,000 – 1,999,999 | ~1 年 | 「凡人已不可及」 | | 6 | 梁祖 | ≥ 2,000,000 | 多年 / 靠赢牌 | 「开山立派」 | > 阈值写在 `shared/config.ts`（可配置），上线后按数据调优。 ### 4.2 段位规则 - 段位 = f(当前余额)。余额达标即升段、输钱掉余额即降段，实时生效。 - 升级：全屏横幅 + 动效 + 可复制分享文案。 - 段位仅展示与荣耀用途，不参与匹配/不设排位分（保持轻量）。 - 大厅的段位标签可点击，弹出「段位体系」说明：6 档段位的余额区间，当前段位高亮。 --- ## 5. UI/UX 与流程 ### 5.1 入口（贴合 DSH） - 插件在 DSH 侧栏“新会话”与“工作区”之间注册一个常驻「斗地主」入口；点击入口后在其对应的独立工作区打开游戏，入口显示灰色高光，不切换或覆盖任何 AI 会话、工作区或会话列表。 - 主页面不使用遮罩弹窗；独立工作区从主内容区域开始显示。点击「小窗」后，在右下角打开保持最高层的画中画窗口；拖动标题栏可调整位置，拖动四边或四角的边框手柄可调整尺寸。小窗最小尺寸为 360 × 280px。 - 斗地主主工作区打开时，侧栏中的 AI 会话不显示选中高光；进入画中画小窗后恢复当前 AI 会话的选中高光，关闭斗地主或点击其他宿主导航后保持宿主选中态。 - 打开斗地主后点击 AI 会话、工作区或「新会话」时，只自动释放斗地主主工作区，画中画小窗保持打开，再执行 DSH 原生导航，保证目标页面正常打开。 - 项目文件夹上的「＋ 新建会话」图标按钮同样自动释放独立工作区并跳转到新会话页面（点击目标落在 SVG 图标上，释放判定按 `Element` 覆盖）。 - 宿主打开系统级模态（如设置/附件查看）时，斗地主入口、独立工作区与画中画小窗让位于宿主遮罩之下：入口与侧栏其它按钮一致变暗且不可点击，工作区/小窗不遮挡系统弹层。 - **长任务提示**：DSH 在跑长任务时（如 LLM 流式输出/后台 job 运行中），可弹出轻提示「等待中，来一把？」——不打断，用户点开即进入大厅。此联动在 M1 spike 验证可接入点。 ### 5.2 牌桌布局（桌面） ``` ┌────────────────────────────┐ │ [顶部揭示的地主底牌] │ │ [对手A] [出牌区] [出牌区] [对手B] │ │ [自己的出牌区] │ │ [叫地主/出牌操作] │ │ [自己信息] [我的手牌] │ ← 底部 └────────────────────────────┘ ``` - 手牌支持**点击**与**按住左键拖拽划过连续选择**两种方式拉起候选牌，拖动过程中划过即加入/移出候选。 - 出牌按**逆时针**方向轮转：下家（下一手行动者）恒显示在右侧、上家（上一手行动者）恒显示在左侧，与欢乐斗地主等惯例一致。 - 叫地主/抢地主/不抢/过 以**直接文本**形式显示在各自玩家前方的出牌区内（与出牌同性质，非气泡）；行动文本**持久显示、不自动消失**——轮到某座位时清空该座位出牌框（“过”轮到自己才消失），出牌阶段首次落牌时清空叫牌遗留文本。叫/抢 用主色高权重、放弃/过 用次级灰，与出牌区其它文本形成层级关系。 - 每位玩家前方的出牌区显示该玩家本轮最近一次出的牌，避免所有牌堆叠在桌面中央；**轮到自己出牌时清空自己的出牌框**，让位给当前手牌。 - **发牌动画**：开局不一次性发完，而是分 3 轮（每轮 6/6/5 张）依次落入各人手牌（带落牌动效），发完后整手做一次「整理」动效；发牌期间操作区显示「明牌 ×K」按钮。 - **阶段操作**：叫地主阶段显示「叫地主/不叫」；抢地主阶段显示「抢地主/不抢」（此阶段不显示地主/农民标，抢地主结束后才显示）；加倍阶段显示「不加倍/加倍×2/超级加倍×4」（金色按钮）——叫地主/抢地主/加倍均为 **5 秒限时并显示倒计时**；出牌阶段地主仅第一轮可显示「明牌」按钮。 - **明牌展示**：明牌玩家的完整手牌以其个人名片上方的迷你小牌展示，对局内所有人可见。 - **结算弹窗**：打完最后一手后停留约 1 秒展示最终牌面，再以弹窗形式盖在牌桌上（胜负、总倍数、抽水、余额、返回大厅），不再整页切换结算页。 - 对手回合时也能点选手牌（用于规划出牌），但「出牌」按钮仅在轮到自己时可用。 - 牌组按横向叠放展示，牌间露出宽度由响应式规则控制，移动端继续保持可横向浏览。 - 倒计时提示（每手 25s，当前玩家的倒计时显示在操作按钮右侧，对手倒计时显示在各自前方的出牌区内，最后 3s 进入红色紧迫态）。 - 操作提示使用气泡形式定位在“提示”按钮上方，不再固定显示在牌桌顶部；提示仅在当前出牌回合内有效，轮转后清除。 - Token 与倍数实时显示；自己的信息标签显示本局倍率，对手信息标签显示剩余手牌数；炸弹/春天触发时牌桌抖动+计数。 - 非基础牌型出牌时显示牌型标签与短时高亮，炸弹与王炸使用更强的爆发特效；保留 `prefers-reduced-motion` 下的静态降级。 ### 5.3 结算页 - 三方结果、倍数明细、Token 变化（+/- 与抽水）、段位变化。 - 「再来一局 / 返回大厅 / 分享战报」。 ### 5.4 文案风格（示例） | 场景 | 文案 | |---|---| | 签到 | 「今日 2,000 已到账，别再说 DSH 不给你发工资了」 | | 输光破产 | 「余额见底，救济金已打款——打工人的相互救赎」 | | 升段 | 「恭喜晋升【梁子】，量子开始纠缠了」 | | 等待匹配 | 「3 缺 2……3 缺 1……到齐开打」 | | Agent 出牌（Phase 2） | 「DSH：我分析了 12 种出法，这手稳赢」 | ### 5.5 自定义头像（**暂缓**） - 用户决定暂缓：启用 R2 需绑定支付方式，第一阶段只用默认头像（DeepSeek 蓝/黑）。 - 设计保留（未来做时参考）： - 设置页「上传自定义头像」，与默认头像并列可选。 - 处理流程：客户端选图 → canvas 裁方 → 转 **WebP**（q0.8，256×256、≤128KB）→ 上传 → 服务端校验后存 R2 → 返回地址。 - 失败提示：非图片/超限/脚本注入 → 明确报错且不产生脏数据。 - 上传成功埋点 `avatar_upload`（见 docs/数据埋点.md §5）。 --- ## 6. 经济系统（Token） > **免责声明**：Token 为**虚拟货币**，仅作娱乐用途，不可兑换任何真实货币或服务，性质类似「欢乐豆」，不具有任何真实经济价值。无购买、无充值、无提现（见 6.2）。 ### 6.1 发行 - **每日签到**：2,000/天（唯一稳定发行源，Phase 1）。 - **救济金**：破产后每日一次 2,000（保体验下限）。 ### 6.2 流通与消耗 - **底注**（核心消耗）：对局入场与结算。 - 新手场：底分 15（余额门槛 1千–15万） - 普通场：底分 80（余额门槛 5千以上） - 高级场：底分 480（余额门槛 4万以上） - **平台抽水 rake**：赢家所得 5% 回收 → 抵消每日增发的通胀（见 6.4）。 - 无购买、无充值、无提现。 ### 6.3 单局期望 - 每局三人合计净变化：0（输家支付 = 赢家所得 + 抽水）。系统每局回收 `赢家所得 × 5%`。 - 为维持通胀平衡，需要「日回收 ≥ 日发行」： - 日发行 = 2,000 × DAU + 救济金。 - 日回收 = Σ(赢家所得 × 5%)。粗略估算：每人每天平均玩 ~10 局、平均下注流水 ~3 倍底注，需靠数值/抽水率调优。 ### 6.4 通胀控制 - 抽水率默认 5%，可配置；若通胀超阈值（如均价对局回收不足），可： - 上调 rake 至 8–10%； - 高倍桌提高底注门槛； - 引入「段位入场券」（高段位进入高倍桌需小额手续费，Phase 2 评估）。 - 上线后按埋点数据（日发行 vs 日回收、流通总量、均价对局流水）持续调优，见 docs/数据埋点.md §6 指标。 ### 6.5 防作弊 / 防刷 - 余额、领取、结算全部服务端权威（见架构设计 §6）。 - 每日领取幂等 + 限流 + 设备指纹关联；异常模式（如瞬时高额流水）标记告警。 --- ## 7. DSH Agent 玩法（第二阶段） ### 7.1 三种模式 | 模式 | 构成 | 说明 | |---|---|---| | 人机混桌 | 玩家 + 2 Agent | 空位由 DSH Agent 接管，最快凑桌 | | 观战对局 | 自己的 DSH vs 别人的 DSH | 全 AI 自动推进，玩家观战（可娱乐下注） | | 好友混桌 | 2 玩家 + 1 Agent | 拉一个朋友，缺的位子让 Agent 顶上 | ### 7.2 Agent 行为规范 - 决策：轮到时，房主/托管方调用 DSH headless 会话：「你是斗地主玩家，手牌…上家…请出牌，只输出牌面」。 - 超时兜底：15s 未回 → 规则引擎出「最小合法牌」。 - 决策日志：把 Agent 的一句思考摘要随出牌展示（DSH 风格）。 - Agent 不追求必胜，只追求「看起来会打」+ 偶尔戏精（输出梗），保持娱乐性。 ### 7.3 谁的 DSH 在打？ - 「自己的 DSH」：指用户本机的 DSH harness（localhost:3080），通过本机 bridge 调用 headless 会话。 - 「别人的 DSH」：对方的 DSH 以受控客户端身份连进同一房间，由对方插件代为决策。 - 房间协议不区分人类/Agent 座位——只区分「决策来源」，架构天然支持（详见架构设计 §8）。 --- ## 8. 音效与动效清单（引用 assets 规范） | 类型 | 项 | |---|---| | 音效 | 发牌、出牌、过、抢地主、炸弹、王炸、春天、结算、签到、升级、破产 | | 动效 | 发牌依次落位、手牌选中、底牌揭示、出牌飞入、倒计时与紧迫态、炸弹抖动、结算计数、段位横幅 | > 音效用轻量 Web Audio 合成优先（体积小），美术文件见 assets/sound。 --- ## 9. 数值调优计划 - 上线后（M2）接入埋点，收集：对局数、平均倍数、人均局数、抽水回收 vs 发行、段位分布、停留时长。 - 定期（每 2 周）按数据调整：底注、rake、签到额、段位阈值。 - 目标：让 80% 玩家在「打 5–10 局后」余额仍能维持（不会一把输光劝退），同时段位成长节奏约 2–4 周升一级（中位用户）。 --- ## 10. 开放问题 1. 3 人凑齐难 → 是否 Phase 1 末期就引入「简单机器人」（非 DSH Agent）垫桌？ 2. 「等待提示」的触发时机（长任务判定标准）与不打扰的交互形态。 3. 段位是否参与匹配（用户量上来后）？ 4. 明牌（发牌明牌 ×4/×3/×2、地主明牌 ×2）与加倍环节（加倍 ×2 / 超级加倍 ×4）已按当前版本实现，数值可后续按对局数据调优。 5. 牌面美术：写实扑克 or 工程师梗风格（如 K=「KPI」、Q=「Queue」）？→ 默认先写实扑克，梗作为彩蛋皮肤（Phase 2）。