Agentic Mahjong

給 AI Agent 與人類玩家使用的 CLI 多人台灣麻將平台。

同一套 agentic-mahjong CLI 同時提供 Server 與 Client 指令。AI Agent 可以把每個 CLI 指令當成 tool use 來打牌；人類玩家也可以直接在 Terminal 操作同一個牌桌。

快速開始

需求環境：Node.js 18 以上。

用 npx 執行

發佈到 npm 之後，可以直接用 npx 執行：

npx agentic-mahjong server

基本操作流程

1. 啟動 Server。

npx agentic-mahjong server --port 3000

2. 註冊玩家。

npx agentic-mahjong register --user-name alice --server http://localhost:3000

3. 建立單機牌桌。

npx agentic-mahjong create-table --token alice --single-player

4. 檢查目前牌局。

npx agentic-mahjong inspect --token alice

5. 依序操作。

npx agentic-mahjong draw --token alice
npx agentic-mahjong discard --token alice --tile 7z

register 成功後會自動把 token 存到本機設定目錄。之後所有指令只要用 --token <user-name> 指定身份即可，不需要重複輸入 server URL。

指令列表

指令	用途	常用範例
server	啟動 HTTP Server	agentic-mahjong server --port 3000 --db-path ./data/mahjong.db
register	註冊新玩家	agentic-mahjong register --user-name alice --server http://localhost:3000
status	查看自己目前狀態	agentic-mahjong status --token alice
find-table	搜尋牌桌	agentic-mahjong find-table --token alice --status waiting
create-table	建立牌桌	agentic-mahjong create-table --token alice --single-player
join-table	加入既有牌桌	agentic-mahjong join-table --table-id <id> --token bob
leave-table	離開牌桌	agentic-mahjong leave-table --token alice
inspect	查看目前牌局	agentic-mahjong inspect --token alice
draw	摸牌	agentic-mahjong draw --token alice
discard	打牌	agentic-mahjong discard --token alice --tile 7z
chi	吃牌	agentic-mahjong chi --token alice --tiles 2m,3m
pon	碰牌	agentic-mahjong pon --token alice
kan	槓牌	agentic-mahjong kan --token alice --tile 5m
hu	胡牌	agentic-mahjong hu --token alice
pass	放棄當前反應機會	agentic-mahjong pass --token alice
poll	取得牌局事件	agentic-mahjong poll --token alice --wait

create-table 補充

agentic-mahjong create-table --token alice --rule taiwan
agentic-mahjong create-table --token alice --single-player
agentic-mahjong create-table --token alice --single-player --bot-strategy random,greedy,balanced

poll 補充

agentic-mahjong poll --token alice
agentic-mahjong poll --token alice --full
agentic-mahjong poll --token alice --last-event-id 12
agentic-mahjong poll --token alice --wait

本地開發

1. 安裝依賴。

pnpm install

2. 建置 CLI bundle。

pnpm build

3. 執行測試。

pnpm test -- --run

4. 執行靜態檢查。

pnpm lint

5. 啟動本地 Server 與 CLI。

pnpm am server
pnpm am register --user-name alice --server http://localhost:3000

專案結構

src/
├── main.ts
├── engine/
├── server/
├── client/
└── utility/
test/
docs/

• src/engine/：純規則邏輯。
• src/server/：Fastify HTTP Server 與 SQLite 持久化。
• src/client/：CLI 命令、格式化與 HTTP client。
• test/：Vitest 測試。
• docs/：PRD、sprint spec、tasks、works。

License

本專案使用 MIT License。詳細內容請見 LICENSE。