# 路线图

| 项目 | 内容 |
|---|---|
| 版本 | v0.1 |
| 原则 | 先跑通最小闭环，再上 AI；每个里程碑可独立验收 |

---

## 阶段总览

| 里程碑 | 主题 | 交付物 | 目标状态 |
|---|---|---|---|
| **M0** | 规划与仓库初始化 | 全部文档、仓库骨架、美术目录 | ✅ 已完成 |
| **M1** | 本地最小闭环（无后端也能玩） | 插件壳 + 规则引擎 + 单机对局 + 本地状态 | ✅ 可本地「人 vs 机器人 vs 机器人」完整打一局 |
| **M2** | PVP 上线（第一阶段） | Cloudflare 后端 + 匹配 + WS 实时 + Token 经济 + 段位 + 资料同步 + 埋点 | 3 人真实 PVP 可玩、经济闭环、埋点可查 |
| **M3** | DSH Agent（第二阶段） | Agent 桥接 + 人机混桌 + 双 AI 观战 | 自己的/别人的 DSH 可入桌打牌 |
| **M4** | 打磨与增长 | 好友房、音效、成就/皮肤、调优 | 可对外宣传 |

---

## M0 · 规划与仓库初始化（已完成 ✅）

- [x] 需求文档、策划文档、架构设计、路线图、数据埋点文档
- [x] GitHub 仓库初始化（public）+ 目录骨架
- [x] 美术资源文件夹与规范（assets/）
- [x] scratch/ 作为草稿目录 gitignore
- [x] 默认头像与牌背素材：用户提供 DeepSeek 品牌蓝/黑 SVG（assets/deepseek-blue.svg、deepseek-black.svg）
- [x] Cloudflare 连接：wrangler login 完成，D1/KV 已建，健康检查 Worker 已部署（https://dsh-doudizhu.1546567314.workers.dev）
- [ ] （暂缓）R2 启用 + 建 avatars 存储桶 —— 需绑定支付方式，用户决定暂缓，自定义头像后置
- [ ] 用户确认 Cloudflare 账号并配置 wrangler（进入 M2 前）→ 已由上方完成

---

## M1 · 本地最小闭环（已完成）

**目标**：不依赖云后端，在 DSH 里能打开牌桌，打完一局完整斗地主（人 vs 简单机器人×2）。

**当前状态**：已具备本地大厅、Token/签到、默认头像选择、昵称编辑、三人发牌与出牌、25 秒倒计时、牌型特效、结算和引擎单测；尚未接入云端 PVP。

| 任务 | 说明 | 验收 |
|---|---|---|
| 插件骨架 | 根 package.json / cordis.patch.yml / 客户端入口，注册一个「斗地主」入口面板 | 在 DSH GUI 中可见入口并可打开空大厅 |
| 规则引擎 | deck/valid/compare/scoring + 完整单测 | 单测覆盖全部牌型与结算，账目守恒 |
| 牌桌渲染 | 发牌、选牌、出牌/过/提示 UI | 可本地完成一次完整对局 |
| 简单机器人 | 规则引擎兜底出牌（先过，后接最小合法牌） | 机器人能打完一局 |
| 本地状态 | 余额/签到在 localStorage 模拟（M1 仅演示） | 签到与余额展示可用 |
| 客户端挂载 | M1 使用 `document.body` + `createRoot` portal，不依赖 shell slots | 浮动入口与全局面板可挂载、卸载 |

**M1 验收**：`dsh plugin --profile web add <本地路径>` 后可打开大厅 → 开局 → 打完整局 → 结算展示；引擎单测全绿。

---

## M2 · PVP 上线（第一阶段，预估 2–3 周）

**目标**：真实 3 人 PVP + 完整经济/段位 + 埋点。

**当前状态**：后端与客户端在线模式已开发完成并通过本地/线上 e2e 验证；剩「重启 dsh web 后的 GUI 实机 PVP 体验」。

| 任务 | 说明 | 状态 |
|---|---|---|
| Cloudflare 后端 | Workers API + Room DO + D1 schema + 迁移 | ✅ 已部署 |
| 匿名身份 | UID 生成、token 签发、资料 API | ✅ |
| 匹配 | KV 桌别队列 → 满 3 人开局 | ✅ |
| WS 实时对局 | state/patch/turn/settle；断线重连与托管（DO hibernation API） | ✅ |
| 经济 | 签到 200k、底注、结算、抽水、流水（救济金待补） | ✅ |
| 段位 | 阈值判定、peak 保底、升级反馈 | ✅ |
| 资料同步 | 默认头像/昵称经 `/api/me/profile` | ✅ |
| 埋点 | ingest + 事件字典 + Admin 报表 | ✅ |
| 客户端在线模式 | 签到/资料/匹配/WS 真人 PVP（保留本地机器人模式） | ✅ |
| 验证 | 本地 e2e + 线上 e2e（3 客户端完整对局、账目守恒） | ✅ |

**M2 验收**：两台设备（两个 DSH）可匹配同一局完整打完并正确结算；余额/段位服务端生效；日活/对局数/经济指标可从 Admin 查询。→ 待 GUI 实机复测确认。

---

## M3 · DSH Agent（第二阶段，预估 2–3 周）

**目标**：DSH 成为牌手。

| 任务 | 说明 |
|---|---|
| Agent 桥接 | 本机 headless 决策调用 + 提示词模板 + 超时兜底 |
| 人机混桌 | 空位由 Agent 接管（自己的/别人的 DSH） |
| 双 AI 对局 | 全 AI 房间 + 观战渲染 |
| Agent 决策日志 | 每手思考摘要展示 |
| 恢复码 | UID 找回，防清浏览器丢号 |

**M3 验收**：玩家可与「自己的 DSH」打完一局；可开「自己的 DSH vs 朋友的 DSH」观战局；Agent 超时不卡局。

---

## M4 · 打磨与增长（持续）

| 任务 | 说明 |
|---|---|
| 好友房 | 邀请码建房/加入 |
| 音效/动效 | 全套 + 设置项 |
| 自定义头像（可选） | 需启用 R2/绑卡，用户暂缓；如启用按架构设计 §3.5 做 |
| 皮肤/梗彩蛋 | 工程师梗牌面（K=KPI 等） |
| 数值调优 | 按埋点数据调底注/rake/签到/段位阈值 |
| 上架 | 插件市场发布、README 完善 |

---

## 风险与依赖

| 依赖/风险 | 影响里程碑 | 说明 |
|---|---|---|
| DSH 插件 API 细节 | M2 | 当前 M1 使用 body portal；后续如接入 slots 再验证 API |
| Cloudflare 账号/wrangler 配置 | M2 | 需要用户提供/确认账号 |
| 3 人同时在线凑齐 | M2 | 新手桌机器人垫桌（M2 末评估） |
| 默认头像素材 | M1–M2 | 已提供 DeepSeek 品牌蓝/黑（assets/）；如需更多变体后续再派生 |
| Agent 决策质量 | M3 | 提示词调优 + 兜底 |

---

## 里程碑节奏建议

- M1、M2 各自独立可交付；M1 结束即可让用户本地体验，M2 结束可小范围内测。
- 每个里程碑结束做一次「数值/体验走查 + 埋点数据核对」，再进入下一阶段。