VS Code MAHJONG 插件

这是一个基于 VS Code 插件的局域网四人广东麻将项目。当前版本使用字符表示牌面，牌面通过独立渲染层抽象，后续可以替换为图片或 SVG。

当前状态

项目已完成阶段 0-9：规则引擎、单局状态机、局域网房间、机器人补位、紧凑可移动 Webview、联机校验、可配置计分和 VSIX 打包验证均已实现。

已确认：136 张牌、不含花牌。
已确认：不允许吃牌，支持碰、明杠、暗杠、加杠。
已确认：基础和牌支持标准牌型，A/B/C 三组特殊牌型全部支持。
已确认：普通和牌支持自摸；特殊流程支持杠上开花、海底、妙手回春、天胡和地胡，不支持抢杠胡。
已确认：同一局只允许一名赢家。
已确认：第一版完成单局流程，不做连续多局和四圈牌局。
默认计分：最低 1 番、封顶 8 番、自摸加 1 番；明杠 1 分、暗杠 2 分、加杠 1 分；买马默认 2 匹。具体配置见 docs/01-rules.md。
已确认：房主插件启动局域网服务器，其他插件作为客户端连接。
已实现：房主默认监听所有 IPv4 网卡并公布局域网地址，创建和加入房间支持可选密码。
已实现：插件脚手架、34 种牌模型、136 张牌墙、可复现洗牌、初始发牌、摸牌、标准和牌及 A/B/C 特殊牌型检测。
当前限制：普通点炮、一炮多响、抢杠胡关闭；房间协议默认单局；图片牌面、动画、音效和主题皮肤延期。

文档索引

规则基线：当前确定的牌局规则、延期规则和规则引擎边界。
技术架构：插件、Webview、局域网通信和扩展点设计。
开发阶段总表：9 个开发阶段、任务、前置条件、验收标准和状态。
进度记录：已完成、进行中、未开始和待确认事项。
安装与运行：编译、测试、打包、安装、创建房间、加入房间和常见错误。
开发前检查：进入编码前需要锁定的规则歧义。

安装与启动

牌桌默认显示在 VS Code 底部 Panel 中，安装后通过 VS Code 命令面板启动。它是一个可移动的独立视图，没有单独的 Activity Bar 图标。

安装 VSIX

在 VS Code 中按 Ctrl+Shift+X 打开扩展面板，点击右上角 ...，选择 Install from VSIX...，然后选择项目根目录下的：

guangdong-mahjong-vscode-0.1.0.vsix

也可以在 PowerShell 中安装：

& 'D:\software\Microsoft VS Code\bin\code.cmd' `
  --install-extension 'D:\test_project\mahjong\guangdong-mahjong-vscode-0.1.0.vsix' `
  --force

安装后执行 Developer: Reload Window，或重启 VS Code。可以在扩展面板搜索 MAHJONG，扩展 ID 为 local-development.guangdong-mahjong-vscode。

启动牌桌

打开 MAHJONG 视图后，未创建或加入房间时只显示房间入口。创建区域可直接填写可选密码；加入区域可直接填写房主 IP、端口、玩家名和密码。提交表单即可完成操作，不会再弹出命令行输入框。完成创建或加入后才会显示牌桌；命令行和命令面板仍然可以继续使用。

按 Ctrl+Shift+P 打开命令面板，执行以下命令：

Mahjong: Create LAN Room：创建局域网房间并作为房主。创建成功后会自动打开牌桌，并显示局域网 IP 和端口。
Mahjong: Join LAN Room：作为客户端加入房间，需要填写房主 IP、端口、玩家名和密码。
Mahjong: Open Table：打开紧凑牌桌；创建或加入房间后通常会自动打开。

所有玩家进入房间后点击“准备”，房主点击“开始”。房间固定四个座位，真人不足时由机器人补位。

牌桌会和“终端”“端口”“问题”等视图并列显示。拖动牌桌视图标题，或在视图标题菜单中选择“移动视图”，即可将它移动到左侧或右侧侧栏。VS Code 不支持把扩展 Webview 嵌入这些内置视图的内容区域。如果牌桌没有自动出现，可在底部 Panel 或侧栏的视图标题菜单中选择“打开视图”，搜索并打开“MAHJONG”；安装新版本后如仍看不到，执行 Developer: Reload Window。

按 Alt+M 可切换到固定内容的资源管理器老板模式，再按一次恢复牌桌。切换不会退出房间或清除当前牌局。

局域网连接要求

其他电脑必须使用房主显示的局域网 IPv4 地址，不能使用 127.0.0.1。
房主创建房间时默认监听本机所有 IPv4 网卡。
Windows 防火墙需要允许插件使用对应 TCP 端口的入站连接。
如果命令搜索不到，先确认 VSIX 安装在当前 VS Code，然后执行 Developer: Reload Window。
如果牌桌空白，执行 Mahjong: Open Table，并在 VS Code 的“输出”面板查看 MAHJONG 通道。

阶段完成提交

阶段完成后，先把 docs/03-roadmap.md 和 docs/04-progress.md 中对应阶段都更新为“已完成”，再执行：

npm run phase:complete -- 9

命令会检查两份文档的状态和阶段名称，运行测试，通过后自动提交阶段变更。提交信息格式为 phase(<阶段编号>): complete <阶段名称>。可以使用 --dry-run 只验证状态和测试，不创建提交。

已确认的房间行为

房间固定四个座位；真人不足时由简单机器人补位。
支持短时间断线重连；房主退出时结束房间。
使用 UDP 自动发现房间，同时支持手动输入 IP 和端口。

MAHJONG

Azusa