dou-cl 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iguangyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,322 @@
+# 发布到 npm —— 让别人的机器 `npx dou-cl` 直接开玩
+
+> 本文只讲怎么把这个包发上 npm。玩法说明看 [README.md](README.md)。
+
+---
+
+## 0. 先说名字：`dou-cli` 已经被占了
+
+你要的 `npx dou-cli` 用不了，因为 npm 上已经有这个包：
+
+```
+dou-cli@1.0.12
+author: Andoni Arbulu Lozano <andoni.arbulu@digitalonus.com>
+maintainers: andoni-arb, richardhern
+last modified: 2022-04-29
+description: A simple cli for creating and setting up projects ... [Digital On Us]
+```
+
+是家美国公司 2022 年发的脚手架工具，虽然早就没人维护了，但包名还是人家的。
+npm 没有"抢名字"的正规途径（除非走商标争议，不值当）。
+
+**所以用 `dou-cl`**，这名字是空的，而且正好是这个仓库的名字，一样短：
+
+| 方案 | 别人怎么运行 | 说明 |
+| --- | --- | --- |
+| **`dou-cl`（推荐）** | `npx dou-cl` | 名字已确认空闲，和仓库同名 |
+| 带 scope | `npx @iguangyu/dou-cli` | 一定能用，但每次要多敲一截 |
+| `doucli` | `npx doucli` | 也空闲，但少个连字符看着怪 |
+
+`package.json` 里现在就是 `"name": "dou-cl"`，`bin` 里也有 `dou-cl`，所以发上去就是 `npx dou-cl`。
+
+---
+
+## 1. 一次性准备
+
+### 1.1 注册 npm 账号
+
+没有账号就去 <https://www.npmjs.com/signup> 注册。注册完**去邮箱点验证链接**，
+没验证的账号发布时会报 `E403`。
+
+### 1.2 登录（注意要指向官方源）
+
+你这台机器默认 registry 是淘宝镜像，所以**登录必须显式指定官方源**：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+# Username / Password / Email / 一次性验证码(如果开了 2FA)
+npm whoami --registry=https://registry.npmjs.org/     # 能打印出用户名就成功了
+```
+
+> token 会写进 `~/.npmrc`，并且**只对 npmjs 生效** —— 你平时 `npm i` 还是走淘宝镜像，不受影响。
+
+**发布目标已经在 `package.json` 里锁死了**，不用你每次加参数：
+
+```json
+"publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
+```
+
+---
+
+## 2. 发布（两条命令）
+
+```bash
+cd C:\Users\lgy\WorkBuddy\Dou_CL
+
+npm publish --dry-run     # 先干跑一遍：列文件、算体积，不会真发
+npm publish               # 真发
+```
+
+`--dry-run` 应该看到这样的输出（已经验证过）：
+
+```
+npm notice name: dou-cl
+npm notice version: 1.0.0
+npm notice package size: 46.3 kB
+npm notice unpacked size: 150.3 kB
+npm notice total files: 25
+npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access (dry-run)
++ dou-cl@1.0.0
+```
+
+注意 `Publishing to https://registry.npmjs.org/` 这行 —— 说明 `publishConfig` 生效了，
+没跑到淘宝镜像上去。
+
+真发的时候会自动先跑测试（`prepublishOnly` → `npm test`，97 条断言）。
+**测试挂了就不会发出去**，这是故意的。
+
+### 2.1 账号开了 2FA 的话（大概率会撞上）
+
+现在 npm 强制 2FA，很多人都开了。症状是发布直接 403：
+
+```
+npm error code E403
+npm error 403 403 Forbidden - PUT https://registry.npmjs.org/dou-cl - Two-factor
+authentication or granular access token with bypass 2fa enabled is required to publish packages.
+```
+
+意思是：**你手上这个 token 没有「Bypass 2FA」权限**。
+
+> 顺带一个坑：2025 年 11 月起 npm 只支持 **Granular access token**，老的 Legacy token 已经下线。
+> Granular token 长这样：`npm_` + 36 位（共 40 字符）。
+> 如果你早先建的 token 没勾 Bypass 2FA（**该选项默认不勾**），就会正好撞上这个 403。
+
+两条路，任选：
+
+#### 路 A：发布时补一次性验证码（最快）
+
+```bash
+npm publish --otp=123456
+```
+
+验证码来自你绑定 2FA 的验证器 App，**30 秒失效**，过期就重新跑一次。
+缺点：每次发布都要掏手机。
+
+> 如果你的 2FA 是 **passkey / 安全密钥**（不是 6 位数字），那没码可输，只能走路 B。
+
+#### 路 B：重建一个勾了 Bypass 2FA 的 token（一劳永逸）
+
+1. 打开 <https://www.npmjs.com/settings/~/tokens> → **Generate New Token → Granular Access Token**
+2. 逐项这么选（**这四项选错任何一个都会继续 403**）：
+
+   | 项目 | 选什么 | 为什么 |
+   | --- | --- | --- |
+   | Expiration | 自定，比如 90 天 | 到期要重建，记得加提醒 |
+   | Packages and scopes | **All packages** | 第一次发新包时 `dou-cl` 还不存在，列表里根本勾不到它 |
+   | Permission | **Read and write** → 再选 **Publish and stage** | 选成 *Stage only* 会报 `E_STAGE_REQUIRED`，那是另一套审核流程 |
+   | **Bypass 2FA** | **☑ 必须勾上** | 就是这次 403 的根因 |
+
+   > 「Bypass 2FA」这个勾选框**只在 token 有写权限时才出现**，默认是**不勾**的。
+   > 它一旦勾上，优先级高于账号级/包级的 2FA 设置 —— 也就是说这个 token 能做发布这类"自动化动作"而不用再掏验证码。
+   > 但注意：**账号安全类操作（改密码、改 2FA、管 token、加维护者）永远要交互式 2FA**，token 绕不过去。
+
+3. 复制 token（**只显示这一次**），替换掉本地那个：
+
+   直接编辑 `C:\Users\lgy\.npmrc`，把这一行
+   ```
+   //registry.npmjs.org/:_authToken=npm_旧token
+   ```
+   换成新的。或者：
+   ```bash
+   npm config set //registry.npmjs.org/:_authToken npm_新的token
+   ```
+
+4. 验证一下换成功了、然后发：
+   ```bash
+   npm whoami --registry=https://registry.npmjs.org/
+   npm publish
+   ```
+
+> ⚠️ token 是密码级别的凭证：只放在 `~/.npmrc`，**别写进项目里的任何文件**，别提交，别贴聊天里。
+> 泄露了就回上面的页面 Revoke 掉重建。
+
+#### 路 C：将来换 trusted publishing（推荐，但要 CI）
+
+npm 已经公告：**Bypass 2FA token 的"直接发布"能力会在 2027 年 1 月移除**。
+长期方案是 trusted publishing（OIDC），**完全不需要 token**，也就没有 2FA 这档事 —— 见 §7。
+
+---
+
+## 3. 别人怎么玩
+
+发完之后，**任何装了 Node 16+ 的机器**，一行就够：
+
+```bash
+npx dou-cl
+```
+
+第一次会下载（46 kB，加上 `ws` 依赖也就 100 KB 出头），之后走 npx 缓存。
+
+常用几种：
+
+```bash
+npx dou-cl -g doudizhu                        # 跳过菜单，直接开一局（最隐蔽）
+npx dou-cl -g fivek                           # 510K
+npx dou-cl --skin hex                         # 换个伪装皮肤
+npx dou-cl --serve --port 8080                # 当服务器，别人连你
+npx dou-cl --join 192.168.1.10:8080 --code ABCD
+npx dou-cl --match doudizhu --server 1.2.3.4:8080
+```
+
+### ⚠️ 刚发完可能拉不到
+
+如果对方的 npm 也配了淘宝镜像（npmmirror），**镜像同步有几分钟到几十分钟延迟**，
+刚发布立刻 `npx dou-cl` 可能 404。两个办法：
+
+```bash
+# 立刻能用的写法，绕开镜像
+npx --registry=https://registry.npmjs.org/ dou-cl
+
+# 或者直接等几分钟再试
+npx dou-cl
+```
+
+---
+
+## 4. 以后更新版本
+
+改完代码，**必须升版本号**再发，否则 npm 会报 `EPUBLISHCONFLICT` / `E403`：
+
+```bash
+npm version patch    # 1.0.0 → 1.0.1   修 bug
+npm version minor    # 1.0.0 → 1.1.0   加功能
+npm version major    # 1.0.0 → 2.0.0   不兼容改动
+
+npm publish
+```
+
+`npm version` 会自动改 `package.json`、打一个 git tag（`v1.0.1`）、并提交。
+顺手把 tag 推上去，GitHub 上就能看到版本：
+
+```bash
+git push --follow-tags
+```
+
+---
+
+## 5. 常见错误对照
+
+| 报错 | 原因 / 怎么办 |
+| --- | --- |
+| `E403 ... you must be logged in` | 没登录。`npm login --registry=https://registry.npmjs.org/` |
+| `E403 ... verify your email` | 账号邮箱没验证，去邮箱点链接 |
+| `E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required` | **token 没勾 Bypass 2FA** —— 最常撞的一个。`npm publish --otp=123456`，或按 §2.1 重建 token |
+| `E403 You do not have permission to publish "dou-cli"` | 名字被占用（就是本文第 0 节那事）。换名或改 `package.json` 的 `name` |
+| `E403 You do not have permission to publish "dou-cl"` | token 的 Packages and scopes 没勾「All packages」，勾不到还不存在的包 |
+| `E_STAGE_REQUIRED` | token 建成了 *Stage only*，重建时改选 **Read and write → Publish and stage** |
+| `EPUBLISHCONFLICT` / `cannot publish over the previously published versions` | 版本号没升。`npm version patch` |
+| `EOTP` | 开了 2FA，命令会提示你输一次性验证码 |
+| `npm notice Publishing to https://registry.npmmirror.com` | 说明 `publishConfig` 被改掉了，**千万别发到镜像**，改回来 |
+| 发布成功但 `npx dou-cl` 找不到 | 镜像同步延迟，见第 3 节 |
+| `402 Payment Required` | 想发到别人的 scope 下，或 scope 未授权 |
+
+### 发错了想撤
+
+```bash
+npm unpublish dou-cl@1.0.0 --force
+```
+
+**限制很严**：只有发布后 **72 小时内**、且没有别的包依赖它、且不是被大量下载过的版本才能撤。
+所以发布前务必先用 `--dry-run` 看一眼文件列表。
+
+---
+
+## 6. 发布前检查清单
+
+- [ ] `npm whoami --registry=https://registry.npmjs.org/` 能打印用户名
+- [ ] `npm test` 全绿（97 条断言）
+- [ ] `npm publish --dry-run` 输出的 `Publishing to` 是 **registry.npmjs.org**
+- [ ] `--dry-run` 的文件列表里**没有** `test/`、`预览.html`、`.workbuddy/`、`node_modules/`
+      （`package.json` 的 `files` 白名单控制，现在只有 `bin` / `src` / `README.md` / `PUBLISH.md` / `LICENSE`）
+- [ ] **token 勾了 Bypass 2FA，或者你准备好输 `--otp=`**（见 §2.1，这是最容易卡住的一步）
+- [ ] 升过版本号了（重复发同一个版本会被拒）
+- [ ] `git status` 干净、改动的代码都提交了
+
+---
+
+## 7. 可选：推 tag 自动发布（GitHub Actions + trusted publishing）
+
+npm 已经公告 **2027 年 1 月会移除 bypass-2FA token 的"直接发布"能力**，
+所以 CI 这条路现在推荐走 **trusted publishing（OIDC）**：**完全不用 token**，
+也就没有 2FA 那档子事，而且顺带拿到 provenance 签名。
+
+在仓库里建 `.github/workflows/publish.yml`：
+
+```yaml
+name: publish
+on:
+  push:
+    tags: ['v*']              # 只有推 v1.2.3 这种 tag 才触发，平时 push 不会跑
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write          # trusted publishing / provenance 都要这个
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish --provenance --access public
+        # 注意：这里没有 NODE_AUTH_TOKEN，靠 OIDC 换临时凭证
+```
+
+用之前要到 npm 上把仓库挂上去：
+
+1. 打开 <https://www.npmjs.com/package/dou-cl/access>（包发出来之后才有这一页）
+   → **Trusted Publisher** → 选 **GitHub Actions**
+2. 填：Organization/user = `iguangyu`，Repository = `dou-cl`，
+   Workflow filename = `publish.yml`（**只写文件名，不带路径**），Environment 留空
+3. 保存。之后 `npm version patch && git push --follow-tags`，tag 一推就自动发。
+
+> 这套的前提是包**已经存在**（第一次还是得用 `npm publish` 手动发一次）。
+> 所以顺序是：先按 §2 手动发布成功 → 再去配 trusted publisher。
+
+> 注意：`publish.yml` 我**没有**替你建。因为没配 trusted publisher 之前，
+> 一旦有 tag 推上去 CI 就会红。你要用的话自己建，或者让我建。
+
+---
+
+## 8. 附：这个包现在的发布配置
+
+```jsonc
+{
+  "name": "dou-cl",                    // 发布后的包名 → npx dou-cl
+  "version": "1.0.0",
+  "bin": {
+    "dou-cl": "bin/dou-cl.js",         // npx 找的就是这个
+    "doucl":  "bin/dou-cl.js"          // 顺手给的短别名（本地安装可用）
+  },
+  "files": ["bin", "src", "README.md", "PUBLISH.md", "LICENSE"],   // 只发这些
+  "engines": { "node": ">=16" },
+  "dependencies": { "ws": "^8.18.0" }, // 联网用的，就这一个
+  "scripts": { "prepublishOnly": "npm test" },        // 发布前自动跑测试
+  "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
+}
+```
+
+`ws` 这个依赖已经在 tarball 里装好验证过了：本地 `npm i dou-cl-1.0.0.tgz`
+之后 `npx ../dou-cl-1.0.0.tgz` 能正常起菜单、开对局、出牌，所以发出去别人也一样能跑。

package/README.md

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+# dou-cl 🃏
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+命令行牌桌 —— **斗地主 / 跑得快 / 510K**，纯终端操作，单机可玩，也能联网对战。
+
+**摸鱼模式**：整个牌桌伪装成看起来正常的开发输出（日志流 / xxd 转储 / JSON 帧 / git diff），
+信息一条不删，只是换了层壳 —— 工位上扫一眼屏幕的人只会觉得你在看构建日志。
+菜单上只有两件事要选：**玩什么** 和 **单机还是联机**。
+详见 [三、牌桌藏在开发输出里](#三牌桌藏在开发输出里默认)。
+
+牌面只用一个字符表示点数，不搞花哨的 ASCII 画图：
+
+```
+点数： 3 4 5 6 7 8 9 0(=10) J Q K A 2   w=小王   W=大王
+花色： ♠ ♥ ♣ ♦          （--ascii 就会变成 S H C D）
+```
+
+---
+
+## 一、跑起来
+
+```bash
+# 进菜单：只选玩法和是否联机
+npx dou-cl
+
+# 跳过菜单直接开一局（最隐蔽，屏幕上不会闪出任何“游戏”字样）
+npx dou-cl -g doudizhu      # 斗地主
+npx dou-cl -g paodekuai     # 跑得快
+npx dou-cl -g fivek         # 510K
+
+# 本地源码方式（没发布 npm 也照样用）
+node bin/dou-cl.js
+npm link        # 之后直接敲 dou-cl
+npx .           # 在项目目录里用 npx 跑
+```
+
+> 从别人那里拿到这个目录时，先 `npm install`（只有 `ws` 一个依赖，联网用；不装也能单机玩）。
+
+---
+
+## 二、操作
+
+| 操作 | 写法 |
+| --- | --- |
+| 出牌 | 直接敲点数：`34567` 或 `3 4 5 6 7` |
+| 指定花色 | 点数后面接花色：`5s 5h 5c`、`10h`、`Wh` |
+| 不要 | `p` 或 `pass` |
+| 提示 | `h` 或 `hint` |
+| 看真身 | `reveal`（临时打印一次原生牌桌） |
+| 换皮肤 | `skin log` / `skin hex` / `skin json` / `skin diff` / `skin term` |
+| 重置画面 | `redraw` |
+| 帮助 | `?` |
+| 退出 | `quit` |
+
+几个小细节：
+
+- 想要同花顺或五十K 时，**不用管花色**，直接敲 `56789` / `50K`，程序会自动挑同一花色那组。
+- 花色字母：`s`=♠ `h`=♥ `c`=♣ `d`=♦。
+- 电脑出牌有约 0.7 秒间隔，用 `--speed 0` 可以飞快跳过。
+
+---
+
+## 三、牌桌藏在开发输出里（默认）
+
+给工位上玩的人准备的：**牌局信息一条都不删，只换一层壳**。
+
+```bash
+npx dou-cl                        # 默认皮肤就是 log（日志流）
+npx dou-cl --skin hex             # 换皮肤： log / hex / json / diff
+npx dou-cl --skin term            # 关掉伪装，显示原生牌桌
+npx dou-cl --skins                # 列皮肤
+```
+
+游戏里敲 `skin <名>` 可以随时换，`reveal` 可以临时看一眼真身。
+
+### 四种壳
+
+| 皮肤 | 长什么样 | 自洽性 |
+| --- | --- | --- |
+| `log`（默认） | 服务端结构化日志（`tail -f` 的感觉），牌就是日志字段 | 时间戳单调递增，混了无关噪声行 |
+| `hex` | `xxd -c 24` 十六进制转储，右边 ASCII 列就是牌 | **左边 hex 与右边字符严格逐字节对应** |
+| `json` | WS 帧 + jq 风格配色 | **去掉颜色就是合法 JSON，能直接 `JSON.parse`** |
+| `diff` | YAML 的统一 diff，绿色 `+` 行是当前牌局 | **是真 diff，能 apply 回去得到当前状态** |
+
+关于「信息没丢」这件事 —— 四种壳里都有：
+
+```
+你的手牌       hand[]  / "hand": [...]  /   hand: [...]
+各家剩几张     peers=[mei:12 fei:8]    /  "peers": [{ "hold": 12 }]
+谁出的什么     history 里的 play/pass 行
+场上最大       table=mei->[5s 5h 5d 6c] trio1
+轮到谁         turn=self
+底牌/分数      bottom= [...] base= / 结果在 result= 行
+```
+
+其它细节：
+
+- **不清屏**，像真的日志流一样往下追加（`--skin term` 才清屏）。
+- 输出**纯 ASCII**，不出现中文，`hex` 的 ASCII 列也不会变成一串 `.`。
+- 玩家名会 ASCII 化（你 → `self`，小美 → `mei`），角色是 `landlord` / `farmer`。
+- 输入提示符也是伪装的（`dev@ws:~/svc$ `、`node > `、`[tail -f] $ `），你敲的 `34567` 看起来就是条命令。
+
+---
+
+## 四、联网
+
+三种玩法都支持联网。房主开服务器，其他人连进来；人数不够的位置由电脑补上。
+
+```bash
+# 1. 一个人当服务器（局域网内直连）
+npx dou-cl --serve --port 8080
+
+# 2. 开房间（连到自己或别人的服务器）
+npx dou-cl --create doudizhu --server 192.168.1.10:8080
+
+# 3. 别人加进来
+npx dou-cl --join 192.168.1.10:8080 --code ABCD
+
+# 或者快速匹配（服务器自动凑桌）
+npx dou-cl --match doudizhu --server 192.168.1.10:8080
+```
+
+参数说明：
+
+| 参数 | 作用 |
+| --- | --- |
+| `--serve [--port N]` | 在本机起服务器，默认端口 8080 |
+| `--create <玩法>` | 连服务器并创建一个房间（会打印 4 位房间号） |
+| `--join <地址> [--code XXXX]` | 加入房间 |
+| `--match <玩法>` | 快速匹配 |
+| `--server <地址>` | 服务器地址，也可用环境变量 `DOUCL_SERVER` |
+| `--name <昵称>` | 显示的名字 |
+| `--skin <名>` | 换伪装皮肤，`term` = 原生牌桌（也可用 `DOUCL_SKIN`） |
+
+**局域网**：直接 `--serve`，把本机 IP（`ipconfig` 里那个 192.168.x.x）告诉朋友即可。
+
+**公网**：把服务器放到有公网 IP 的机器 / 云主机上跑 `npx dou-cl --serve`，大家用 `--server <公网IP>:8080`。服务端是**权威端**，所有牌局逻辑在服务器上跑，客户端只收自己的手牌，改前端看不到别人的牌。
+
+几个实现上的说明：
+
+- 房间 4 位房间号不会重复，房间空了自动回收。
+- 中途断线会被电脑托管，不会卡住别人。
+- 轮到你了不动手，90 秒后自动帮你出一张（可在代码里改 `turnTimeout`）。
+
+---
+
+## 五、玩法
+
+### 斗地主
+- 3 人，每人 17 张，留 3 张底牌。
+- 依次叫分 1/2/3 或不叫，最高分当地主并拿走底牌；三家都不叫则流局重发。
+- 牌型：单张、对子、三张、三带一、三带二、顺子（5 张起）、连对（3 对起）、飞机（带单/带对）、四带二、四带两对、炸弹、王炸。
+- 胜负：地主先出完 → 地主赢；任一农民先出完 → 农民赢。
+- 计分：底分 × 倍数，每个炸弹/王炸 ×2，春天 ×2。
+
+### 跑得快
+- 3 人，一副牌**去掉大小王**共 52 张，每人 17 张，剩 1 张废弃。
+- 首手：持有 ♠3 的玩家先出，且第一手必须带上 ♠3。
+- 牌型：和斗地主一样，但**没有王炸**，连对 2 对即可。
+- 胜负：谁先出完谁赢，其他人按剩余张数扣分。
+
+### 510K
+- 4 人，**两副牌**共 108 张，每人 27 张，没有底牌。
+- 牌型：单张、对子、三张、顺子（5 张起）、连对（2 对起）、飞机、**同花顺**、**五十K**、炸弹（4 张及以上同点）、王炸。
+- **五十K**（同花色的 5·10·K 各一张）是通吃牌型：除炸弹和王炸外，**可以压任何牌型**；同花五十K 之间比花色（♠ > ♥ > ♣ > ♦）。
+- **同花顺**可以压同长度的普通顺子。
+- 计分：5 = 5 分，10 = 10 分，K = 10 分，两副共 200 分。**每一轮结束时，本轮桌面上的分牌全部归本轮最后出牌的人。**
+- 胜负：谁先出完手牌谁赢，分数作为副榜。
+
+---
+
+## 六、目录结构
+
+```
+bin/dou-cl.js           命令行入口（参数解析）
+src/core/cards.js       牌模型 / 发牌 / 排序
+src/core/combo.js       牌型识别、比大小、候选生成
+src/core/rules.js       三种玩法的规则开关
+src/games/base.js       通用回合引擎（校验与执行分离）
+src/games/doudizhu.js   斗地主（叫分 / 春天 / 计分）
+src/games/paodekuai.js  跑得快（♠3 先手）
+src/games/fivek.js      510K（收分 / 五十K）
+src/bot.js              电脑 AI
+src/ui.js               渲染 + 输入解析
+src/color.js            颜色（原生与伪装皮肤共用）
+src/runner.js           单局循环
+src/skins/packet.js     把视野压成与渲染方式无关的状态包
+src/skins/log.js        伪装皮肤：日志流
+src/skins/hex.js        伪装皮肤：xxd 十六进制转储
+src/skins/json.js       伪装皮肤：JSON 帧
+src/skins/diff.js       伪装皮肤：git diff
+src/skins/index.js      皮肤注册表 + 会话状态
+src/net/server.js       房间服务器（权威端）
+src/net/client.js       联网客户端
+test/sim.js             电脑互打自测
+test/smoke.js           渲染 / 输入解析 / 联网全流程
+test/local-test.js      本地视角回归（人类手牌不能被看错）
+test/skins-test.js      伪装皮肤自洽性（hex 对字节 / JSON 可解析 / diff 可 apply / 纯 ASCII）
+test/make-preview.js    生成 预览.html
+test/show.js            单看某个皮肤的效果： node test/show.js fivek hex 8
+```
+
+自测：
+
+```bash
+node test/sim.js 300       # 每种玩法各打 300 局电脑互打，校验规则与牌数守恒
+node test/smoke.js         # 渲染 / 输入解析 / 服务器+客户端联网打完整一局
+node test/local-test.js    # 本地对局：渲染视角必须固定在人类座位上
+node test/skins-test.js    # 伪装皮肤：hex 逐字节、JSON 可解析、diff 可 apply、输出纯 ASCII
+npm test                   # 以上全部
+npm run preview            # 生成 预览.html，先看看跑起来长什么样
+```
+
+---
+
+## 七、加新玩法 / 加新皮肤
+
+**加玩法**：在 `src/core/rules.js` 里加一份规则（座位数、牌堆、最小顺子长度、有没有王炸/五十K……），
+再写一个继承 `src/games/base.js` 的类实现 `setupPhase` / `checkOver` / `onGameEnd`，
+最后在 `src/games/index.js` 注册即可 —— 牌型识别、AI、联网、伪装皮肤全都不用动。
+
+**加伪装皮肤**：在 `src/skins/` 下加一个模块，导出
+`{ key, name, desc, render(p, st), prompt(), help(lines), message(text) }`，
+其中 `p` 是 `packet.build()` 出来的标准状态包（手牌 / 各家张数 / 桌上最大 / 历史 / 结果都已经在里面），
+在 `src/skins/index.js` 的 `LIST` 里注册一行就完事了。
+
+## License
+
+MIT
+
+想把它发到 npm 让别的机器 `npx dou-cl` 直接用？看 [PUBLISH.md](PUBLISH.md)。