@zhin.js/plugin-game-hub 1.1.21 → 1.1.23

package/README.md

@@ -1,3 +1,15 @@
 # @zhin.js/plugin-game-hub
 
-Plugin Runtime 游戏大厅：通过 `/games` 列出当前 generation 的 `GameIndex` 投影。
+Plugin Runtime 游戏大厅：聚合展示当前 generation 已注册的小游戏插件（`GameIndex` 投影）、个人战绩与排行榜。
+
+## 能力
+
+- **聊天命令**：
+  - `games [action]`：列出已加载的小游戏插件及快捷开局提示。
+  - `战绩`：查询当前用户在各小游戏中的胜负与积分统计。
+  - `排行 [游戏名]`：查看指定小游戏的积分排行榜。
+- **AI Skill 与 Tool**：
+  - `skills/game-hub/SKILL.md`：按需激活的游戏大厅技能。
+  - `skills/game-hub/tools/game_catalog/index.ts`（`game_catalog`，`readOnly: true`）：查询已注册小游戏目录（ID、名称、别名、人数范围、简介与开局指令），支持按名称或别名过滤。
+- **Console 页面**：
+  - `pages/index/index.ts`（权限 `game-hub:read`）：通过 `pluginConsoleRpcToken`（`createGameHubConsoleRpc`）展示已注册游戏数量与游戏目录表。

package/lib/catalog.d.ts

@@ -0,0 +1,29 @@
+import { type GameIndex, type RuntimeRegisteredGame } from '@zhin.js/game-kit';
+export declare const gameIndexStore: import("zhin.js").PluginStore<GameIndex, unknown>;
+export declare const gameIndexToken: import("zhin.js").PluginStore<GameIndex, unknown>;
+export interface GameCatalogEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly icon: string;
+    readonly aliases: readonly string[];
+    readonly minPlayers: number;
+    readonly maxPlayers: number;
+    readonly playerCountRange: string;
+    readonly description: string;
+    readonly startCommand: string;
+}
+type RuntimeGameWithPlayers = RuntimeRegisteredGame & {
+    readonly minPlayers?: number;
+    readonly maxPlayers?: number;
+};
+type ContextWithIndexLookup = {
+    readonly project?: (feature: never) => unknown;
+    readonly use?: (token: never) => unknown;
+};
+export declare function resolveGameIndex(context?: ContextWithIndexLookup): GameIndex | undefined;
+export declare function inferPlayerBounds(game: RuntimeGameWithPlayers): {
+    readonly minPlayers: number;
+    readonly maxPlayers: number;
+};
+export declare function toGameCatalogEntry(game: RuntimeRegisteredGame): GameCatalogEntry;
+export {};

package/lib/catalog.js

@@ -0,0 +1,107 @@
+import { definePluginStore } from 'zhin.js';
+import { gameFeatureId, isGameIndex, } from '@zhin.js/game-kit';
+export const gameIndexStore = definePluginStore('zhin.game.index', 'Game Hub registered game index');
+export const gameIndexToken = gameIndexStore;
+function isGameIndexLike(value) {
+    return isGameIndex(value)
+        || (typeof value === 'object' && value !== null && typeof value.list === 'function');
+}
+export function resolveGameIndex(context) {
+    if (!context)
+        return undefined;
+    if (typeof context.use === 'function') {
+        try {
+            const fromToken = context.use(gameIndexToken);
+            if (isGameIndexLike(fromToken))
+                return fromToken;
+        }
+        catch {
+            // Fallback to feature projection when token is not bound.
+        }
+    }
+    if (typeof context.project === 'function') {
+        try {
+            const projected = context.project(gameFeatureId);
+            if (isGameIndexLike(projected))
+                return projected;
+        }
+        catch {
+            // Feature projection may not be available in all call contexts.
+        }
+    }
+    return undefined;
+}
+function isAsciiDigitCode(code) {
+    return code >= 48 && code <= 57;
+}
+function isAsciiDigitsOnly(value) {
+    if (value.length === 0 || value.length > 4)
+        return false;
+    for (let i = 0; i < value.length; i += 1) {
+        if (!isAsciiDigitCode(value.charCodeAt(i)))
+            return false;
+    }
+    return true;
+}
+function parsePlayerRangeFromDescription(description) {
+    const text = description.slice(0, 200);
+    let searchFrom = 0;
+    while (searchFrom < text.length) {
+        const personIdx = text.indexOf('人', searchFrom);
+        if (personIdx <= 0)
+            return undefined;
+        searchFrom = personIdx + 1;
+        const prefix = text.slice(0, personIdx).trimEnd();
+        for (const sep of ['-', '~', '至']) {
+            const sepIdx = prefix.lastIndexOf(sep);
+            if (sepIdx <= 0)
+                continue;
+            const rightStr = prefix.slice(sepIdx + sep.length).trim();
+            if (!isAsciiDigitsOnly(rightStr))
+                continue;
+            const leftPrefix = prefix.slice(0, sepIdx).trimEnd();
+            let leftStart = leftPrefix.length;
+            while (leftStart > 0 && isAsciiDigitCode(leftPrefix.charCodeAt(leftStart - 1))) {
+                leftStart -= 1;
+            }
+            const leftStr = leftPrefix.slice(leftStart);
+            if (!isAsciiDigitsOnly(leftStr))
+                continue;
+            return {
+                minPlayers: Number(leftStr),
+                maxPlayers: Number(rightStr),
+            };
+        }
+    }
+    return undefined;
+}
+export function inferPlayerBounds(game) {
+    if (typeof game.minPlayers === 'number' && typeof game.maxPlayers === 'number') {
+        return { minPlayers: game.minPlayers, maxPlayers: game.maxPlayers };
+    }
+    const parsedRange = parsePlayerRangeFromDescription(game.description);
+    if (parsedRange) {
+        return parsedRange;
+    }
+    if (game.id === 'roulette')
+        return { minPlayers: 2, maxPlayers: 6 };
+    if (game.id === 'ttt')
+        return { minPlayers: 1, maxPlayers: 2 };
+    return { minPlayers: 1, maxPlayers: 1 };
+}
+export function toGameCatalogEntry(game) {
+    const { minPlayers, maxPlayers } = inferPlayerBounds(game);
+    const quickStart = game.quickStart ? ` ${game.quickStart}` : '';
+    return {
+        id: game.id,
+        name: game.title,
+        icon: game.icon,
+        aliases: game.aliases ?? [],
+        minPlayers,
+        maxPlayers,
+        playerCountRange: minPlayers === maxPlayers ? `${minPlayers}` : `${minPlayers}-${maxPlayers}`,
+        description: game.description,
+        startCommand: `${game.commandPrefix}${quickStart}`,
+    };
+}
+//# sourceMappingURL=catalog.js.map

package/lib/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/lib/console.d.ts

@@ -0,0 +1,17 @@
+import { type PluginConsoleRpc } from 'zhin.js';
+import type { GameIndex } from '@zhin.js/game-kit';
+export declare const GAME_HUB_CONSOLE_PAGE = "index";
+export declare const GAME_HUB_READ_PERMISSION = "game-hub:read";
+export interface GameHubConsoleGameRow {
+    readonly id: string;
+    readonly name: string;
+    readonly aliases: string;
+    readonly minPlayers: number;
+    readonly maxPlayers: number;
+    readonly description: string;
+}
+export interface GameHubConsoleStatus {
+    readonly gameCount: number;
+    readonly games: readonly GameHubConsoleGameRow[];
+}
+export declare function createGameHubConsoleRpc(fallbackIndex?: GameIndex): PluginConsoleRpc;

package/lib/console.js

@@ -0,0 +1,32 @@
+import { definePluginConsoleRpc, } from 'zhin.js';
+import { resolveGameIndex, toGameCatalogEntry, } from './catalog.js';
+export const GAME_HUB_CONSOLE_PAGE = 'index';
+export const GAME_HUB_READ_PERMISSION = 'game-hub:read';
+export function createGameHubConsoleRpc(fallbackIndex) {
+    return definePluginConsoleRpc({
+        status: {
+            page: GAME_HUB_CONSOLE_PAGE,
+            requiredPermissions: [GAME_HUB_READ_PERMISSION],
+            handler(_input, call) {
+                const index = resolveGameIndex(call.runtime) ?? fallbackIndex;
+                const registered = index ? index.list() : [];
+                const games = registered.map((game) => {
+                    const entry = toGameCatalogEntry(game);
+                    return {
+                        id: entry.id,
+                        name: entry.name,
+                        aliases: entry.aliases.join(', '),
+                        minPlayers: entry.minPlayers,
+                        maxPlayers: entry.maxPlayers,
+                        description: entry.description,
+                    };
+                });
+                return {
+                    gameCount: games.length,
+                    games,
+                };
+            },
+        },
+    });
+}
+//# sourceMappingURL=console.js.map

package/lib/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../src/console.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAGvB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAC7C,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAgBxD,MAAM,UAAU,uBAAuB,CACrC,aAAyB;IAEzB,OAAO,sBAAsB,CAAC;QAC5B,MAAM,EAAE;YACN,IAAI,EAAE,qBAAqB;YAC3B,mBAAmB,EAAE,CAAC,wBAAwB,CAAC;YAC/C,OAAO,CAAC,MAAM,EAAE,IAA0B;gBACxC,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAgB,CAAC,IAAI,aAAa,CAAC;gBACvE,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;oBACpC,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;oBACvC,OAAO;wBACL,EAAE,EAAE,KAAK,CAAC,EAAE;wBACZ,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;wBACjC,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;qBAC/B,CAAC;gBACJ,CAAC,CAAC,CAAC;gBACH,OAAO;oBACL,SAAS,EAAE,KAAK,CAAC,MAAM;oBACvB,KAAK;iBACN,CAAC;YACJ,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC"}

package/lib/index.d.ts

@@ -1,2 +1,2 @@
-/** Plugin Runtime game hub — re-exports for package entry if needed. */
-export {};
+export { gameIndexToken, inferPlayerBounds, resolveGameIndex, toGameCatalogEntry, type GameCatalogEntry, } from './catalog.js';
+export { createGameHubConsoleRpc, GAME_HUB_CONSOLE_PAGE, GAME_HUB_READ_PERMISSION, type GameHubConsoleGameRow, type GameHubConsoleStatus, } from './console.js';

package/lib/index.js

@@ -1,2 +1,3 @@
-export {};
+export { gameIndexToken, inferPlayerBounds, resolveGameIndex, toGameCatalogEntry, } from './catalog.js';
+export { createGameHubConsoleRpc, GAME_HUB_CONSOLE_PAGE, GAME_HUB_READ_PERMISSION, } from './console.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,GAGzB,MAAM,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-game-hub",
-  "version": "1.1.21",
+  "version": "1.1.23",
   "description": "Zhin.js 游戏大厅 — 列出已加载的游戏插件 (Plugin Runtime)",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,18 +16,25 @@
     "plugin.js",
     "schema.json",
     "commands",
+    "pages",
+    "skills",
     "src",
     "lib",
     "README.md"
   ],
   "license": "MIT",
   "dependencies": {
-    "@zhin.js/game-kit": "1.1.21"
+    "@zhin.js/console-contract": "1.1.4",
+    "@zhin.js/game-kit": "1.1.23",
+    "@zhin.js/page": "1.1.16",
+    "@zhin.js/skill": "1.1.15",
+    "@zhin.js/tool": "1.1.17"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zhin.js": "1.1.21"
+    "zod": "^4.4.3",
+    "zhin.js": "1.1.23"
   },
   "repository": {
     "type": "git",
@@ -55,17 +62,45 @@
       {
         "package": "@zhin.js/game-kit",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.1.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []
   },
   "peerDependencies": {
-    "@zhin.js/command": "^1.1.14",
-    "zhin.js": "^1.1.21"
+    "zod": "^4.0.0",
+    "@zhin.js/command": "^1.1.16",
+    "@zhin.js/page": "^1.1.16",
+    "@zhin.js/skill": "^1.1.15",
+    "@zhin.js/tool": "^1.1.17",
+    "zhin.js": "^1.1.23"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
       "optional": true
+    },
+    "@zhin.js/page": {
+      "optional": true
+    },
+    "@zhin.js/skill": {
+      "optional": true
+    },
+    "@zhin.js/tool": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "scripts": {

package/pages/index/index.js

@@ -0,0 +1,53 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage, createDeclarativePage } from '@zhin.js/console-contract';
+export const meta = definePage({
+    title: '游戏大厅',
+    titleI18n: { en: 'Game Hub' },
+    icon: 'Gamepad2',
+    order: 57,
+    requiredPermissions: ['game-hub:read'],
+});
+export default createDeclarativePage({
+    title: { zh: '游戏大厅', en: 'Game Hub' },
+    description: {
+        zh: '查看当前已加载的小游戏插件、别名、人数范围与玩法说明',
+        en: 'Browse registered mini-game plugins, aliases, player limits, and descriptions',
+    },
+    stats: [
+        {
+            key: 'gameCount',
+            label: { zh: '已注册游戏数', en: 'Registered Games' },
+            value: 'gameCount',
+        },
+    ],
+    sections: [
+        {
+            id: 'games',
+            title: { zh: '已加载游戏', en: 'Registered Games' },
+            emptyText: { zh: '暂无已注册的游戏插件', en: 'No game plugins registered' },
+            items: 'games',
+            columns: [
+                {
+                    key: 'name',
+                    label: { zh: '游戏名称', en: 'Name' },
+                },
+                {
+                    key: 'aliases',
+                    label: { zh: '别名', en: 'Aliases' },
+                },
+                {
+                    key: 'minPlayers',
+                    label: { zh: '最少人数', en: 'Min Players' },
+                },
+                {
+                    key: 'maxPlayers',
+                    label: { zh: '最多人数', en: 'Max Players' },
+                },
+                {
+                    key: 'description',
+                    label: { zh: '简介', en: 'Description' },
+                },
+            ],
+        },
+    ],
+});

package/pages/index/index.ts

@@ -0,0 +1,58 @@
+import { definePage, createDeclarativePage } from '@zhin.js/console-contract';
+import type { GameHubConsoleGameRow, GameHubConsoleStatus } from '../../src/console.js';
+
+export const meta = definePage({
+  title: '游戏大厅',
+  titleI18n: { en: 'Game Hub' },
+  icon: 'Gamepad2',
+  order: 57,
+  requiredPermissions: ['game-hub:read'],
+});
+
+export default createDeclarativePage<GameHubConsoleStatus>({
+  title: { zh: '游戏大厅', en: 'Game Hub' },
+  description: {
+    zh: '查看当前已加载的小游戏插件、别名、人数范围与玩法说明',
+    en: 'Browse registered mini-game plugins, aliases, player limits, and descriptions',
+  },
+  stats: [
+    {
+      key: 'gameCount',
+      label: { zh: '已注册游戏数', en: 'Registered Games' },
+      value: 'gameCount',
+    },
+  ],
+  sections: [
+    {
+      id: 'games',
+      title: { zh: '已加载游戏', en: 'Registered Games' },
+      emptyText: { zh: '暂无已注册的游戏插件', en: 'No game plugins registered' },
+      items: 'games',
+      columns: [
+        {
+          key: 'name',
+          label: { zh: '游戏名称', en: 'Name' },
+        },
+        {
+          key: 'aliases',
+          label: { zh: '别名', en: 'Aliases' },
+        },
+        {
+          key: 'minPlayers',
+          label: { zh: '最少人数', en: 'Min Players' },
+        },
+        {
+          key: 'maxPlayers',
+          label: { zh: '最多人数', en: 'Max Players' },
+        },
+        {
+          key: 'description',
+          label: { zh: '简介', en: 'Description' },
+        },
+      ] satisfies readonly {
+        readonly key: keyof GameHubConsoleGameRow & string;
+        readonly label: { readonly zh: string; readonly en: string };
+      }[],
+    },
+  ],
+});

package/plugin.js

@@ -1,5 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { definePlugin } from 'zhin.js';
+import { definePlugin, definePluginCapabilityGraph, pluginConsoleRpcToken, } from 'zhin.js';
+import { createGameHubConsoleRpc } from "./lib/console.js";
 /**
  * Plugin Runtime game hub — commands read the generation-owned GameIndex projection.
  * Interactive hub menus are deferred; `/games` command shows help text.
@@ -9,5 +10,18 @@ export default definePlugin({
     metadata: {
         displayName: 'Game Hub',
     },
-    setup() { },
+    capabilityGraph: definePluginCapabilityGraph({
+        provides: [pluginConsoleRpcToken],
+        features: {
+            commands: ['games', '战绩', '排行'],
+            skills: ['game-hub'],
+            tools: ['game_catalog'],
+            pages: ['index'],
+        },
+    }),
+    setup() {
+        return {
+            consoleRpc: createGameHubConsoleRpc(),
+        };
+    },
 });

package/skills/game-hub/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: game-hub
+description: List registered mini-games in the Game Hub and explain rules/commands for starting or quitting a game.
+keywords:
+  - "游戏"
+  - "小游戏"
+  - "大厅"
+  - "games"
+  - "game-hub"
+  - "play"
+tags:
+  - "game"
+  - "entertainment"
+tools:
+  - "game_catalog"
+---
+
+# game-hub
+
+当用户询问有哪些小游戏可玩、如何开始或退出小游戏、或者查看游戏大厅说明时激活。使用 `game_catalog` 工具获取当前已加载的小游戏列表、别名、人数范围、简介与开局指令。

package/skills/game-hub/tools/game_catalog/index.js

@@ -0,0 +1,29 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { resolveGameIndex, toGameCatalogEntry, } from "../../../../lib/catalog.js";
+const inputSchema = z.object({
+    game: z.string().optional().describe('Optional game name or id to filter'),
+});
+export default defineAgentTool({
+    description: '查询游戏大厅中已注册的小游戏目录（名称、别名、人数范围、简介与开局指令）',
+    inputSchema,
+    readOnly: true,
+    requiresApproval: 'never',
+    tags: ['game', 'entertainment'],
+    keywords: ['游戏', '小游戏', '大厅', 'games', 'game-hub'],
+    execute({ game }, context) {
+        const index = resolveGameIndex(context);
+        const allGames = index ? index.list().map(toGameCatalogEntry) : [];
+        const query = game?.trim().toLowerCase();
+        const games = query
+            ? allGames.filter((entry) => entry.id.toLowerCase().includes(query)
+                || entry.name.toLowerCase().includes(query)
+                || entry.aliases.some((alias) => alias.toLowerCase().includes(query)))
+            : allGames;
+        return {
+            count: games.length,
+            games,
+        };
+    },
+});

package/skills/game-hub/tools/game_catalog/index.ts

@@ -0,0 +1,35 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import {
+  resolveGameIndex,
+  toGameCatalogEntry,
+  type GameCatalogEntry,
+} from '../../../../src/catalog.js';
+
+const inputSchema = z.object({
+  game: z.string().optional().describe('Optional game name or id to filter'),
+});
+
+export default defineAgentTool<{ game?: string }, { count: number; games: GameCatalogEntry[] }>({
+  description: '查询游戏大厅中已注册的小游戏目录（名称、别名、人数范围、简介与开局指令）',
+  inputSchema,
+  readOnly: true,
+  requiresApproval: 'never',
+  tags: ['game', 'entertainment'],
+  keywords: ['游戏', '小游戏', '大厅', 'games', 'game-hub'],
+  execute({ game }, context) {
+    const index = resolveGameIndex(context);
+    const allGames = index ? index.list().map(toGameCatalogEntry) : [];
+    const query = game?.trim().toLowerCase();
+    const games = query
+      ? allGames.filter((entry) =>
+        entry.id.toLowerCase().includes(query)
+        || entry.name.toLowerCase().includes(query)
+        || entry.aliases.some((alias) => alias.toLowerCase().includes(query)))
+      : allGames;
+    return {
+      count: games.length,
+      games,
+    };
+  },
+});

package/src/catalog.ts

@@ -0,0 +1,137 @@
+import { definePluginStore } from 'zhin.js';
+import {
+  gameFeatureId,
+  isGameIndex,
+  type GameIndex,
+  type RuntimeRegisteredGame,
+} from '@zhin.js/game-kit';
+
+export const gameIndexStore = definePluginStore<GameIndex>(
+  'zhin.game.index',
+  'Game Hub registered game index',
+);
+export const gameIndexToken = gameIndexStore;
+
+export interface GameCatalogEntry {
+  readonly id: string;
+  readonly name: string;
+  readonly icon: string;
+  readonly aliases: readonly string[];
+  readonly minPlayers: number;
+  readonly maxPlayers: number;
+  readonly playerCountRange: string;
+  readonly description: string;
+  readonly startCommand: string;
+}
+
+type RuntimeGameWithPlayers = RuntimeRegisteredGame & {
+  readonly minPlayers?: number;
+  readonly maxPlayers?: number;
+};
+
+type ContextWithIndexLookup = {
+  readonly project?: (feature: never) => unknown;
+  readonly use?: (token: never) => unknown;
+};
+
+function isGameIndexLike(value: unknown): value is GameIndex {
+  return isGameIndex(value)
+    || (typeof value === 'object' && value !== null && typeof (value as GameIndex).list === 'function');
+}
+
+export function resolveGameIndex(context?: ContextWithIndexLookup): GameIndex | undefined {
+  if (!context) return undefined;
+  if (typeof context.use === 'function') {
+    try {
+      const fromToken = (context.use as (token: unknown) => unknown)(gameIndexToken);
+      if (isGameIndexLike(fromToken)) return fromToken;
+    } catch {
+      // Fallback to feature projection when token is not bound.
+    }
+  }
+  if (typeof context.project === 'function') {
+    try {
+      const projected = (context.project as (feature: unknown) => unknown)(gameFeatureId);
+      if (isGameIndexLike(projected)) return projected;
+    } catch {
+      // Feature projection may not be available in all call contexts.
+    }
+  }
+  return undefined;
+}
+
+function isAsciiDigitCode(code: number): boolean {
+  return code >= 48 && code <= 57;
+}
+
+function isAsciiDigitsOnly(value: string): boolean {
+  if (value.length === 0 || value.length > 4) return false;
+  for (let i = 0; i < value.length; i += 1) {
+    if (!isAsciiDigitCode(value.charCodeAt(i))) return false;
+  }
+  return true;
+}
+
+function parsePlayerRangeFromDescription(description: string): {
+  readonly minPlayers: number;
+  readonly maxPlayers: number;
+} | undefined {
+  const text = description.slice(0, 200);
+  let searchFrom = 0;
+  while (searchFrom < text.length) {
+    const personIdx = text.indexOf('人', searchFrom);
+    if (personIdx <= 0) return undefined;
+    searchFrom = personIdx + 1;
+    const prefix = text.slice(0, personIdx).trimEnd();
+    for (const sep of ['-', '~', '至']) {
+      const sepIdx = prefix.lastIndexOf(sep);
+      if (sepIdx <= 0) continue;
+      const rightStr = prefix.slice(sepIdx + sep.length).trim();
+      if (!isAsciiDigitsOnly(rightStr)) continue;
+      const leftPrefix = prefix.slice(0, sepIdx).trimEnd();
+      let leftStart = leftPrefix.length;
+      while (leftStart > 0 && isAsciiDigitCode(leftPrefix.charCodeAt(leftStart - 1))) {
+        leftStart -= 1;
+      }
+      const leftStr = leftPrefix.slice(leftStart);
+      if (!isAsciiDigitsOnly(leftStr)) continue;
+      return {
+        minPlayers: Number(leftStr),
+        maxPlayers: Number(rightStr),
+      };
+    }
+  }
+  return undefined;
+}
+
+export function inferPlayerBounds(game: RuntimeGameWithPlayers): {
+  readonly minPlayers: number;
+  readonly maxPlayers: number;
+} {
+  if (typeof game.minPlayers === 'number' && typeof game.maxPlayers === 'number') {
+    return { minPlayers: game.minPlayers, maxPlayers: game.maxPlayers };
+  }
+  const parsedRange = parsePlayerRangeFromDescription(game.description);
+  if (parsedRange) {
+    return parsedRange;
+  }
+  if (game.id === 'roulette') return { minPlayers: 2, maxPlayers: 6 };
+  if (game.id === 'ttt') return { minPlayers: 1, maxPlayers: 2 };
+  return { minPlayers: 1, maxPlayers: 1 };
+}
+
+export function toGameCatalogEntry(game: RuntimeRegisteredGame): GameCatalogEntry {
+  const { minPlayers, maxPlayers } = inferPlayerBounds(game);
+  const quickStart = game.quickStart ? ` ${game.quickStart}` : '';
+  return {
+    id: game.id,
+    name: game.title,
+    icon: game.icon,
+    aliases: game.aliases ?? [],
+    minPlayers,
+    maxPlayers,
+    playerCountRange: minPlayers === maxPlayers ? `${minPlayers}` : `${minPlayers}-${maxPlayers}`,
+    description: game.description,
+    startCommand: `${game.commandPrefix}${quickStart}`,
+  };
+}

package/src/console.ts

@@ -0,0 +1,57 @@
+import {
+  definePluginConsoleRpc,
+  type PluginConsoleRpc,
+  type PluginConsoleRpcCall,
+} from 'zhin.js';
+import type { GameIndex } from '@zhin.js/game-kit';
+import {
+  resolveGameIndex,
+  toGameCatalogEntry,
+} from './catalog.js';
+
+export const GAME_HUB_CONSOLE_PAGE = 'index';
+export const GAME_HUB_READ_PERMISSION = 'game-hub:read';
+
+export interface GameHubConsoleGameRow {
+  readonly id: string;
+  readonly name: string;
+  readonly aliases: string;
+  readonly minPlayers: number;
+  readonly maxPlayers: number;
+  readonly description: string;
+}
+
+export interface GameHubConsoleStatus {
+  readonly gameCount: number;
+  readonly games: readonly GameHubConsoleGameRow[];
+}
+
+export function createGameHubConsoleRpc(
+  fallbackIndex?: GameIndex,
+): PluginConsoleRpc {
+  return definePluginConsoleRpc({
+    status: {
+      page: GAME_HUB_CONSOLE_PAGE,
+      requiredPermissions: [GAME_HUB_READ_PERMISSION],
+      handler(_input, call: PluginConsoleRpcCall) {
+        const index = resolveGameIndex(call.runtime as never) ?? fallbackIndex;
+        const registered = index ? index.list() : [];
+        const games = registered.map((game) => {
+          const entry = toGameCatalogEntry(game);
+          return {
+            id: entry.id,
+            name: entry.name,
+            aliases: entry.aliases.join(', '),
+            minPlayers: entry.minPlayers,
+            maxPlayers: entry.maxPlayers,
+            description: entry.description,
+          };
+        });
+        return {
+          gameCount: games.length,
+          games,
+        };
+      },
+    },
+  });
+}

package/src/index.ts

@@ -1,2 +1,14 @@
-/** Plugin Runtime game hub — re-exports for package entry if needed. */
-export {};
+export {
+  gameIndexToken,
+  inferPlayerBounds,
+  resolveGameIndex,
+  toGameCatalogEntry,
+  type GameCatalogEntry,
+} from './catalog.js';
+export {
+  createGameHubConsoleRpc,
+  GAME_HUB_CONSOLE_PAGE,
+  GAME_HUB_READ_PERMISSION,
+  type GameHubConsoleGameRow,
+  type GameHubConsoleStatus,
+} from './console.js';