@zhin.js/plugin-roulette 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @zhin.js/plugin-roulette
 
-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.
+俄罗斯轮盘：群里多人轮流扣动扳机，弹巢里只有一发子弹，中弹的人输。接入游戏大厅，战绩和排行由 `@zhin.js/plugin-game-hub` 统一展示。每个群可以单独开启「输家禁言」惩罚，默认关闭。
+
+## 安装
+
+```yaml
+plugins:
+  game-hub: "@zhin.js/plugin-game-hub"
+  roulette: "@zhin.js/plugin-roulette"
+database:
+  dialect: sqlite
+  storage: ./data/zhin.db
+```
+
+没有数据库时对局保存在内存里，重启后丢失。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `轮盘` / `轮盘 帮助` | 玩法说明 |
+| `轮盘 开局` | 创建一局，自己先上桌 |
+| `轮盘 加入` | 加入等待中的对局 |
+| `轮盘 开始` | 房主开局，至少 2 人 |
+| `开枪`（或 `轮盘 开枪`） | 轮到你时扣动扳机；没轮到你时「开枪」只是普通聊天 |
+| `轮盘 退出` | 等待时离开；对局中离开算认输 |
+| `轮盘 取消` | 房主或机器人管理员取消本局，不计分 |
+| `轮盘 状态` | 查看当前对局 |
+| `轮盘 禁言` | 查看本群禁言惩罚和平台是否支持禁言 |
+| `轮盘 开启禁言` / `轮盘 关闭禁言` | 机器人主人（`master`）或受信任用户（`trusted`）切换本群禁言惩罚 |
+
+`/轮盘赌`、`roulette` 是同一组命令的别名；也可以从 `/游戏` 大厅进入。
+
+## 规则
+
+- 一个群同一时间只有一局。玩家按加入顺序轮流开枪，弹巢数量和人数上限见配置。
+- 开局时随机把子弹装进其中一个弹巢，之后按顺序逐个击发，所以最多一轮弹巢就会分出胜负。
+- 轮到的人超过 `turnTimeoutSeconds` 不开枪，判负；每开一枪重新计时。
+- 开局后超过 `lobbyTimeoutSeconds` 还没开始，自动解散，不计分。
+- 对局中离开等同认输。
+- 结束后幸存者各记 1 胜（得 1 分），输家记 1 负。对局和群设置都存在数据库表里（`roulette_sessions`、`roulette_group_settings`），不使用插件 state store。取消或解散的对局不记录。用 `战绩`、`排行 轮盘` 查看。
+
+## 禁言惩罚
+
+- 按群开关，默认关闭。只有机器人主人或受信任用户可以切换，判断的是框架角色，不读取平台的群管理员身份。
+- 插件不判断平台名称。每次需要时，用消息自带的 `conversation.endpoint`（适配器插件和 Endpoint 能力 id）走 `project(adapterFeatureId).connection(adapter, endpointId)`，再看 `resolveEndpointManagement(endpoint)?.muteGroupMember` 是否存在。存在就能禁言，不存在（或运行时没有 Adapter Feature）就只计分。
+- 超时判负由 `schedules/deadlines` 每 5 秒检查一次，它拿到的也是同样的能力上下文，所以超时的输家同样会按上面的规则处理。
+- 平台不支持禁言时无法开启；开启后平台失去这项能力，或禁言被拒绝（例如机器人不是群管理员），这一局照常结算，只是不禁言。
+- 只在群聊里生效，输家禁言 `muteSeconds` 秒。
+
+## 配置
+
+```yaml
+roulette:
+  chambers: 6              # 弹巢数，2-12
+  maxPlayers: 6            # 每局人数上限，2-10
+  turnTimeoutSeconds: 60   # 轮到的人多久不开枪判负，10-600
+  lobbyTimeoutSeconds: 300 # 开局后多久不开始自动解散，30-3600
+  muteSeconds: 60          # 开启禁言惩罚的群里输家禁言秒数，10-3600
+```
+
+## 开发
+
+```bash
+pnpm --filter @zhin.js/plugin-roulette build
+pnpm vitest run plugins/games/roulette/tests
+```

package/commands/roulette/[[action]]/index.js

@@ -0,0 +1,13 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { ROULETTE_HELP } from "../../../lib/roulette-actions.js";
+import { runRouletteCommand } from "../../../lib/roulette-command.js";
+export default defineCommand({
+    description: '俄罗斯轮盘：多人轮流开枪，中弹者输',
+    params: { action: { type: 'string', default: '' } },
+    async execute(context) {
+        const action = String(context.params.action ?? '');
+        const reply = await runRouletteCommand(context, context.input, action);
+        return reply ?? `未知操作：${action}\n\n${ROULETTE_HELP}`;
+    },
+});

package/lib/config.d.ts

@@ -0,0 +1,14 @@
+/** Plugin instance configuration (`schema.json`), with defaults and safe bounds. */
+export interface RouletteConfig {
+    /** Chambers in the cylinder; one holds the bullet. */
+    readonly chambers: number;
+    readonly maxPlayers: number;
+    /** The player on turn loses when they do not fire within this time. */
+    readonly turnTimeoutSeconds: number;
+    /** A lobby that never starts is dissolved after this time. */
+    readonly lobbyTimeoutSeconds: number;
+    /** Mute length for the loser, used only in groups that enabled the mute penalty. */
+    readonly muteSeconds: number;
+}
+export declare const DEFAULT_ROULETTE_CONFIG: RouletteConfig;
+export declare function resolveRouletteConfig(raw: unknown): RouletteConfig;

package/lib/config.js

@@ -0,0 +1,27 @@
+const CONFIG_BOUNDS = {
+    chambers: { fallback: 6, min: 2, max: 12 },
+    maxPlayers: { fallback: 6, min: 2, max: 10 },
+    turnTimeoutSeconds: { fallback: 60, min: 10, max: 600 },
+    lobbyTimeoutSeconds: { fallback: 300, min: 30, max: 3600 },
+    muteSeconds: { fallback: 60, min: 10, max: 3600 },
+};
+export const DEFAULT_ROULETTE_CONFIG = resolveRouletteConfig(undefined);
+export function resolveRouletteConfig(raw) {
+    const source = raw && typeof raw === 'object' ? raw : {};
+    return Object.freeze({
+        chambers: readInteger(source.chambers, CONFIG_BOUNDS.chambers),
+        maxPlayers: readInteger(source.maxPlayers, CONFIG_BOUNDS.maxPlayers),
+        turnTimeoutSeconds: readInteger(source.turnTimeoutSeconds, CONFIG_BOUNDS.turnTimeoutSeconds),
+        lobbyTimeoutSeconds: readInteger(source.lobbyTimeoutSeconds, CONFIG_BOUNDS.lobbyTimeoutSeconds),
+        muteSeconds: readInteger(source.muteSeconds, CONFIG_BOUNDS.muteSeconds),
+    });
+}
+function readInteger(value, bounds) {
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return bounds.fallback;
+    if (value < bounds.min)
+        return bounds.min;
+    if (value > bounds.max)
+        return bounds.max;
+    return value;
+}

package/lib/deadline-job.d.ts

@@ -0,0 +1,9 @@
+import { type RouletteCapabilityContext } from './runtime.js';
+/** Turn and lobby deadlines are checked every five seconds. */
+export declare const DEADLINE_CRON = "*/5 * * * * *";
+/**
+ * One deadline sweep. It runs with the schedule's capability context, so a
+ * timed-out loser gets the same mute check (adapter projection) as one who
+ * was shot in a command.
+ */
+export declare function runDeadlineSweep(context: RouletteCapabilityContext, now: number): Promise<void>;

package/lib/deadline-job.js

@@ -0,0 +1,45 @@
+import { outboundHostToken } from 'zhin.js';
+import { expireOverdueSessions } from './game-flow.js';
+import { resolveRouletteFlow } from './runtime.js';
+/** Turn and lobby deadlines are checked every five seconds. */
+export const DEADLINE_CRON = '*/5 * * * * *';
+/**
+ * One deadline sweep. It runs with the schedule's capability context, so a
+ * timed-out loser gets the same mute check (adapter projection) as one who
+ * was shot in a command.
+ */
+export async function runDeadlineSweep(context, now) {
+    const flow = resolveRouletteFlow(context);
+    const notices = await expireOverdueSessions(flow, now);
+    const outbound = readOutbound(context);
+    if (!outbound)
+        return;
+    for (const notice of notices) {
+        await announce(outbound, notice);
+    }
+}
+function readOutbound(context) {
+    try {
+        return context.use(outboundHostToken);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function announce(outbound, notice) {
+    const session = notice.session;
+    try {
+        await outbound.send({
+            adapter: session.adapter,
+            endpointKey: session.endpoint,
+            conversation: {
+                kind: session.channel_type,
+                id: session.channel_id,
+            },
+            content: notice.text,
+        });
+    }
+    catch {
+        // The result is already stored; a failed notice must not stop the other sessions.
+    }
+}

package/lib/engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure Russian roulette rules. No I/O, no clock and no randomness: callers pass
+ * the bullet position in, so every transition is deterministic and testable.
+ */
+export declare const ROULETTE_STATE_VERSION = 1;
+export type RoulettePhase = 'lobby' | 'playing' | 'finished' | 'aborted';
+export type RouletteEndReason = 'shot' | 'turn-timeout' | 'forfeit' | 'cancelled' | 'lobby-expired' | 'lobby-empty';
+export interface RoulettePlayer {
+    readonly id: string;
+    readonly name: string;
+}
+export interface RouletteState {
+    readonly schemaVersion: typeof ROULETTE_STATE_VERSION;
+    readonly phase: RoulettePhase;
+    readonly hostId: string;
+    readonly players: readonly RoulettePlayer[];
+    readonly chamberCount: number;
+    /** Zero-based chamber holding the bullet; -1 until the round starts. */
+    readonly bulletChamber: number;
+    /** Trigger pulls so far; the next pull fires chamber `pullsMade`. */
+    readonly pullsMade: number;
+    /** Index into `players` of whoever must pull next. */
+    readonly turnIndex: number;
+    readonly loserId?: string;
+    readonly endReason?: RouletteEndReason;
+}
+export interface RouletteTableRules {
+    readonly chamberCount: number;
+    readonly maxPlayers: number;
+}
+export declare const MIN_ROULETTE_PLAYERS = 2;
+export type TriggerOutcome = 'click' | 'bang';
+export interface TriggerResult {
+    readonly state: RouletteState;
+    readonly outcome: TriggerOutcome;
+    readonly shooter: RoulettePlayer;
+}
+/** A rule violation the player should read, e.g. firing out of turn. */
+export declare class RouletteRuleError extends Error {
+    constructor(message: string);
+}
+export declare function createLobby(host: RoulettePlayer, rules: RouletteTableRules): RouletteState;
+export declare function joinLobby(state: RouletteState, player: RoulettePlayer, rules: RouletteTableRules): RouletteState;
+export declare function startRound(state: RouletteState, actorId: string, bulletChamber: number): RouletteState;
+export declare function pullTrigger(state: RouletteState, actorId: string): TriggerResult;
+/**
+ * Leaving the lobby just removes the player. Leaving a running round is a
+ * forfeit: the leaver loses, so nobody can dodge the bullet by walking away.
+ */
+export declare function leaveGame(state: RouletteState, playerId: string): RouletteState;
+/** The player on turn ran out of time: treated like a shot, they lose. */
+export declare function expireTurn(state: RouletteState): RouletteState;
+export declare function expireLobby(state: RouletteState): RouletteState;
+export declare function cancelGame(state: RouletteState): RouletteState;
+export declare function isOpen(state: RouletteState): boolean;
+export declare function currentPlayer(state: RouletteState): RoulettePlayer | undefined;
+export declare function findPlayer(state: RouletteState, playerId: string): RoulettePlayer | undefined;
+export declare function loserOf(state: RouletteState): RoulettePlayer | undefined;
+export declare function survivorsOf(state: RouletteState): readonly RoulettePlayer[];
+export declare function remainingChambers(state: RouletteState): number;
+export declare function decodeRouletteState(json: string): RouletteState;

package/lib/engine.js

@@ -0,0 +1,157 @@
+/**
+ * Pure Russian roulette rules. No I/O, no clock and no randomness: callers pass
+ * the bullet position in, so every transition is deterministic and testable.
+ */
+export const ROULETTE_STATE_VERSION = 1;
+export const MIN_ROULETTE_PLAYERS = 2;
+/** A rule violation the player should read, e.g. firing out of turn. */
+export class RouletteRuleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RouletteRuleError';
+    }
+}
+export function createLobby(host, rules) {
+    return {
+        schemaVersion: ROULETTE_STATE_VERSION,
+        phase: 'lobby',
+        hostId: host.id,
+        players: [host],
+        chamberCount: rules.chamberCount,
+        bulletChamber: -1,
+        pullsMade: 0,
+        turnIndex: 0,
+    };
+}
+export function joinLobby(state, player, rules) {
+    requirePhase(state, 'lobby', '对局已经开始，不能再加入了。');
+    if (findPlayer(state, player.id)) {
+        throw new RouletteRuleError('你已经在这局轮盘里了。');
+    }
+    if (state.players.length >= rules.maxPlayers) {
+        throw new RouletteRuleError(`人数已满（最多 ${rules.maxPlayers} 人）。`);
+    }
+    return { ...state, players: [...state.players, player] };
+}
+export function startRound(state, actorId, bulletChamber) {
+    requirePhase(state, 'lobby', '对局已经开始了。');
+    if (actorId !== state.hostId) {
+        throw new RouletteRuleError('只有开局的人可以开始。');
+    }
+    if (state.players.length < MIN_ROULETTE_PLAYERS) {
+        throw new RouletteRuleError(`至少需要 ${MIN_ROULETTE_PLAYERS} 名玩家才能开始。`);
+    }
+    if (!Number.isInteger(bulletChamber) || bulletChamber < 0 || bulletChamber >= state.chamberCount) {
+        throw new RangeError(`bulletChamber must be within 0..${state.chamberCount - 1}`);
+    }
+    return {
+        ...state,
+        phase: 'playing',
+        bulletChamber,
+        pullsMade: 0,
+        turnIndex: 0,
+    };
+}
+export function pullTrigger(state, actorId) {
+    requirePhase(state, 'playing', '对局还没开始。');
+    const shooter = currentPlayer(state);
+    if (!shooter)
+        throw new RouletteRuleError('对局没有可以开枪的玩家。');
+    if (shooter.id !== actorId) {
+        throw new RouletteRuleError(`还没轮到你，现在轮到 ${shooter.name}。`);
+    }
+    const firedChamber = state.pullsMade;
+    const pullsMade = state.pullsMade + 1;
+    if (firedChamber === state.bulletChamber) {
+        const finished = finishWithLoser({ ...state, pullsMade }, shooter.id, 'shot');
+        return { state: finished, outcome: 'bang', shooter };
+    }
+    const turnIndex = (state.turnIndex + 1) % state.players.length;
+    return { state: { ...state, pullsMade, turnIndex }, outcome: 'click', shooter };
+}
+/**
+ * Leaving the lobby just removes the player. Leaving a running round is a
+ * forfeit: the leaver loses, so nobody can dodge the bullet by walking away.
+ */
+export function leaveGame(state, playerId) {
+    const leaver = findPlayer(state, playerId);
+    if (!leaver)
+        throw new RouletteRuleError('你不在这局轮盘里。');
+    if (state.phase === 'playing') {
+        return finishWithLoser(state, playerId, 'forfeit');
+    }
+    requirePhase(state, 'lobby', '对局已经结束。');
+    const players = state.players.filter((player) => player.id !== playerId);
+    const nextHost = players[0];
+    if (!nextHost) {
+        return { ...state, players, phase: 'aborted', endReason: 'lobby-empty' };
+    }
+    const hostId = state.hostId === playerId ? nextHost.id : state.hostId;
+    return { ...state, players, hostId };
+}
+/** The player on turn ran out of time: treated like a shot, they lose. */
+export function expireTurn(state) {
+    requirePhase(state, 'playing', '对局还没开始。');
+    const late = currentPlayer(state);
+    if (!late)
+        throw new RouletteRuleError('对局没有可以开枪的玩家。');
+    return finishWithLoser(state, late.id, 'turn-timeout');
+}
+export function expireLobby(state) {
+    requirePhase(state, 'lobby', '对局已经开始了。');
+    return { ...state, phase: 'aborted', endReason: 'lobby-expired' };
+}
+export function cancelGame(state) {
+    if (!isOpen(state))
+        throw new RouletteRuleError('对局已经结束。');
+    return { ...state, phase: 'aborted', endReason: 'cancelled' };
+}
+export function isOpen(state) {
+    return state.phase === 'lobby' || state.phase === 'playing';
+}
+export function currentPlayer(state) {
+    if (state.phase !== 'playing')
+        return undefined;
+    return state.players[state.turnIndex];
+}
+export function findPlayer(state, playerId) {
+    return state.players.find((player) => player.id === playerId);
+}
+export function loserOf(state) {
+    if (!state.loserId)
+        return undefined;
+    return findPlayer(state, state.loserId);
+}
+export function survivorsOf(state) {
+    return state.players.filter((player) => player.id !== state.loserId);
+}
+export function remainingChambers(state) {
+    return state.chamberCount - state.pullsMade;
+}
+export function decodeRouletteState(json) {
+    const parsed = JSON.parse(json);
+    if (!isRouletteState(parsed)) {
+        throw new TypeError('Stored roulette state is malformed');
+    }
+    return parsed;
+}
+function finishWithLoser(state, loserId, endReason) {
+    return { ...state, phase: 'finished', loserId, endReason };
+}
+function requirePhase(state, phase, message) {
+    if (state.phase !== phase)
+        throw new RouletteRuleError(message);
+}
+function isRouletteState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const state = value;
+    return state.schemaVersion === ROULETTE_STATE_VERSION
+        && typeof state.phase === 'string'
+        && typeof state.hostId === 'string'
+        && Array.isArray(state.players)
+        && typeof state.chamberCount === 'number'
+        && typeof state.bulletChamber === 'number'
+        && typeof state.pullsMade === 'number'
+        && typeof state.turnIndex === 'number';
+}

package/lib/game-flow.d.ts

@@ -0,0 +1,26 @@
+import { type GameMessageLike } from '@zhin.js/game-kit';
+import type { RouletteConfig } from './config.js';
+import type { RouletteSessionRow } from './models.js';
+import type { MutePenaltyPort, PenaltyConversation } from './mute-penalty.js';
+import { type RouletteCommandAction } from './roulette-actions.js';
+import { type EndpointIdentity, type RouletteServices } from './session-service.js';
+/** Everything one action needs, resolved from the current runtime generation. */
+export interface RouletteFlow {
+    readonly services: RouletteServices;
+    readonly config: RouletteConfig;
+    readonly penalty: MutePenaltyPort;
+}
+/** Who sent the action, from the runtime message. */
+export interface RouletteActor {
+    readonly message: GameMessageLike;
+    readonly endpoint: EndpointIdentity;
+    readonly roles: readonly string[];
+}
+export interface ExpiredSessionNotice {
+    readonly session: RouletteSessionRow;
+    readonly text: string;
+}
+export declare function runRouletteAction(flow: RouletteFlow, actor: RouletteActor, action: RouletteCommandAction): Promise<string>;
+/** Called by the deadline schedule; each returned notice still has to be delivered. */
+export declare function expireOverdueSessions(flow: RouletteFlow, now: number): Promise<readonly ExpiredSessionNotice[]>;
+export declare function conversationOfSession(session: RouletteSessionRow): PenaltyConversation;

package/lib/game-flow.js

@@ -0,0 +1,208 @@
+import { GameSessionConflictError, SessionRevisionConflictError, channelKey, } from '@zhin.js/game-kit';
+import { RouletteRuleError, loserOf } from './engine.js';
+import { ROULETTE_HELP } from './roulette-actions.js';
+import { playerFromMessage, stateOf, } from './session-service.js';
+import { describeAbort, describeClick, describeEnding, describeLobby, describeRoundStart, describeStatus, } from './view.js';
+const DEADLINE_ACTOR = 'deadline';
+const MANAGER_ROLES = ['master', 'trusted'];
+const NO_GAME_TEXT = '本群没有进行中的轮盘，发送「轮盘 开局」创建一局。';
+export async function runRouletteAction(flow, actor, action) {
+    const message = actor.message;
+    if (action === 'help')
+        return ROULETTE_HELP;
+    if (message.$channel.type === 'private')
+        return '轮盘需要多人参与，请在群聊里玩。';
+    if (action === 'penalty-on' || action === 'penalty-off' || action === 'penalty-status') {
+        return handlePenaltySetting(flow, actor, action);
+    }
+    const notices = [];
+    let session = await flow.services.sessions.getActiveByChannel(channelKey(message));
+    if (session && isOverdue(session, Date.now())) {
+        const expired = await expireSession(flow, session);
+        if (expired)
+            notices.push(expired);
+        session = null;
+    }
+    const reply = await handleGameAction(flow, actor, action, session);
+    return [...notices, reply].join('\n\n');
+}
+/** Called by the deadline schedule; each returned notice still has to be delivered. */
+export async function expireOverdueSessions(flow, now) {
+    const overdue = await flow.services.sessions.listOverdue(now);
+    const notices = [];
+    for (const session of overdue) {
+        const text = await expireSession(flow, session);
+        if (text)
+            notices.push({ session, text });
+    }
+    return notices;
+}
+async function handleGameAction(flow, actor, action, session) {
+    const message = actor.message;
+    if (action === 'open')
+        return openLobby(flow, actor, session);
+    if (!session)
+        return NO_GAME_TEXT;
+    if (action === 'status')
+        return describeStatus(stateOf(session), flow.config);
+    if (action === 'cancel' && !mayCancel(session, message, actor.roles)) {
+        return '只有开局的人或机器人管理员可以取消本局。';
+    }
+    const gameAction = toGameAction(action, message);
+    if (!gameAction)
+        return NO_GAME_TEXT;
+    try {
+        const result = await flow.services.sessions.applyAction(session, message.$sender.id, gameAction, flow.config);
+        return describeResult(flow, gameAction, result, message);
+    }
+    catch (error) {
+        if (error instanceof RouletteRuleError)
+            return error.message;
+        if (error instanceof GameSessionConflictError)
+            return error.message;
+        if (error instanceof SessionRevisionConflictError)
+            return '对局状态刚刚变了，请再发一次。';
+        throw error;
+    }
+}
+async function openLobby(flow, actor, session) {
+    if (session) {
+        return `本群已经有一局轮盘了。\n${describeStatus(stateOf(session), flow.config)}`;
+    }
+    try {
+        const created = await flow.services.sessions.createLobby(actor.message, actor.endpoint, flow.config);
+        return describeLobby(stateOf(created), flow.config);
+    }
+    catch (error) {
+        if (error instanceof GameSessionConflictError)
+            return error.message;
+        throw error;
+    }
+}
+async function describeResult(flow, action, result, message) {
+    const state = result.state;
+    if (!result.applied)
+        return describeStatus(state, flow.config);
+    if (state.phase === 'finished')
+        return finishText(flow, result.session, state);
+    if (state.phase === 'aborted')
+        return describeAbort(state);
+    if (action.type === 'start')
+        return describeRoundStart(state, flow.config);
+    if (action.type === 'fire') {
+        return describeClick(playerFromMessage(message), state, flow.config);
+    }
+    if (action.type === 'leave') {
+        return `${playerFromMessage(message).name} 离开了。\n${describeLobby(state, flow.config)}`;
+    }
+    return describeLobby(state, flow.config);
+}
+async function expireSession(flow, session) {
+    try {
+        const result = await flow.services.sessions.applyAction(session, DEADLINE_ACTOR, { type: 'expire' }, flow.config);
+        if (!result.applied)
+            return '';
+        if (result.state.phase === 'finished')
+            return finishText(flow, result.session, result.state);
+        return describeAbort(result.state);
+    }
+    catch (error) {
+        // A player acted on the session in the meantime; the next sweep re-reads it.
+        if (error instanceof SessionRevisionConflictError)
+            return '';
+        throw error;
+    }
+}
+async function finishText(flow, session, state) {
+    const penalty = await applyLoserPenalty(flow, session, state);
+    return [describeEnding(state), penalty].filter(Boolean).join('\n');
+}
+/** Mute the loser only when this group opted in and the Endpoint declares muting. */
+async function applyLoserPenalty(flow, session, state) {
+    const loser = loserOf(state);
+    if (!loser)
+        return '';
+    const enabled = await flow.services.settings.isMutePenaltyEnabled(session.channel_key);
+    if (!enabled)
+        return '';
+    const conversation = conversationOfSession(session);
+    if (flow.penalty.support(conversation) !== 'supported') {
+        return '（本群开启了禁言惩罚，但当前平台无法禁言，本局只计分。）';
+    }
+    try {
+        await flow.penalty.mute(conversation, loser.id, flow.config.muteSeconds);
+        return `🔇 ${loser.name} 被禁言 ${flow.config.muteSeconds} 秒。`;
+    }
+    catch {
+        return '（禁言没有成功，可能是机器人没有群管理权限；本局只计分。）';
+    }
+}
+async function handlePenaltySetting(flow, actor, action) {
+    const message = actor.message;
+    if (message.$channel.type !== 'group')
+        return '禁言惩罚只能在群聊里设置。';
+    const key = channelKey(message);
+    const settings = flow.services.settings;
+    const support = flow.penalty.support(conversationOfActor(actor));
+    if (action === 'penalty-status') {
+        const enabled = await settings.isMutePenaltyEnabled(key);
+        return describePenaltyStatus(enabled, support === 'supported', flow.config);
+    }
+    if (!isManager(actor.roles))
+        return '只有机器人主人或受信任用户可以修改禁言惩罚。';
+    if (action === 'penalty-off') {
+        await settings.setMutePenalty(key, false, message.$sender.id);
+        return '已关闭禁言惩罚，本群轮盘只计分。';
+    }
+    if (support !== 'supported') {
+        return '当前平台不支持禁言，禁言惩罚没有开启；本群轮盘只计分。';
+    }
+    await settings.setMutePenalty(key, true, message.$sender.id);
+    return `已开启禁言惩罚：每局输家会被禁言 ${flow.config.muteSeconds} 秒（需要机器人有群管理权限）。`;
+}
+function describePenaltyStatus(enabled, supported, config) {
+    const platform = supported ? '当前平台支持禁言。' : '当前平台不支持禁言，只能计分。';
+    if (!enabled)
+        return `本群禁言惩罚：关闭。${platform}`;
+    return `本群禁言惩罚：开启，输家禁言 ${config.muteSeconds} 秒。${platform}`;
+}
+function toGameAction(action, message) {
+    if (action === 'join')
+        return { type: 'join', player: playerFromMessage(message) };
+    if (action === 'start')
+        return { type: 'start' };
+    if (action === 'fire')
+        return { type: 'fire' };
+    if (action === 'leave')
+        return { type: 'leave' };
+    if (action === 'cancel')
+        return { type: 'cancel' };
+    return null;
+}
+function mayCancel(session, message, senderRoles) {
+    if (stateOf(session).hostId === message.$sender.id)
+        return true;
+    return isManager(senderRoles);
+}
+function isManager(senderRoles) {
+    return senderRoles.some((role) => MANAGER_ROLES.includes(role));
+}
+function isOverdue(session, now) {
+    return session.deadline_at > 0 && session.deadline_at <= now;
+}
+export function conversationOfSession(session) {
+    return {
+        endpointAdapter: session.endpoint_adapter,
+        endpointId: session.endpoint_id,
+        kind: session.channel_type,
+        id: session.channel_id,
+    };
+}
+function conversationOfActor(actor) {
+    return {
+        endpointAdapter: actor.endpoint.adapter,
+        endpointId: actor.endpoint.id,
+        kind: actor.message.$channel.type,
+        id: actor.message.$channel.id,
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_ROULETTE_CONFIG, resolveRouletteConfig, type RouletteConfig } from './config.js';
+export * from './engine.js';
+export { expireOverdueSessions, runRouletteAction, type RouletteActor, type RouletteFlow } from './game-flow.js';
+export { DEADLINE_CRON, runDeadlineSweep } from './deadline-job.js';
+export { resolveMutePenalty, type AdapterProjectionContext, type MutePenaltyPort, type MuteSupport, type PenaltyConversation, } from './mute-penalty.js';
+export { ROULETTE_HELP, normalizeRouletteAction, type RouletteCommandAction } from './roulette-actions.js';
+export { endpointOf, rouletteServicesToken, resolveRouletteFlow } from './runtime.js';
+export { RouletteGroupSettings, RouletteSessionService, createServices, type EndpointIdentity, type RouletteServices, } from './session-service.js';

package/lib/index.js

@@ -0,0 +1,8 @@
+export { DEFAULT_ROULETTE_CONFIG, resolveRouletteConfig } from './config.js';
+export * from './engine.js';
+export { expireOverdueSessions, runRouletteAction } from './game-flow.js';
+export { DEADLINE_CRON, runDeadlineSweep } from './deadline-job.js';
+export { resolveMutePenalty, } from './mute-penalty.js';
+export { ROULETTE_HELP, normalizeRouletteAction } from './roulette-actions.js';
+export { endpointOf, rouletteServicesToken, resolveRouletteFlow } from './runtime.js';
+export { RouletteGroupSettings, RouletteSessionService, createServices, } from './session-service.js';