@forgeax/interface 0.4.1

package/dist/package/node/lib/builtin-actions.js

@@ -0,0 +1,558 @@
+/** builtin-actions —— 首批高频 action 登记(产品 AI 化 P0,方案 §6)。
+ *
+ *  内容层:这里是**产品专属内容**(interface 知道自己有哪些功能),机制归 action-registry。
+ *  每条 action 就是包一层 zustand store action / forgeax-bridge REST——按钮与 AI 走同一条
+ *  路(Derive 不 Duplicate)。capability 如实声明:它是编排层 trust-gate 的权限输入,
+ *  delete 类(session.close)会弹用户确认卡,这是有意的。
+ *
+ *  surface 口径(方案 §5):纯视图操作 'ui';背后是 server REST 的标 'both'(headless
+ *  等价路径 P1 接线,声明先行,UI run() 已经就是调同一 HTTP API,server 是行为 SSOT)。
+ */
+import { registerAction, registerStateSlice } from './action-registry.js';
+import { getSessionClient } from '../store-parts/session-client.js';
+import { useShellStore, tabLabel } from '../store.js';
+import { openExtensionPage, resolveRegisteredOverlayId } from '../core/page-navigation.js';
+import { useHealthStore } from '../components/StatusBar/healthStore.js';
+import { getBrowserConsole, clearBrowserConsole } from '../components/StatusBar/healthBridge.js';
+import { listExtensions, pickLang } from './extension-api.js';
+import { getStudioProjectClient } from '../store-parts/domain-clients.js';
+let registered = false;
+async function readRoleRoster() {
+    const response = await fetch('/api/tools/call', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ toolId: 'team:list_roles', caller: { kind: 'user' }, args: {} }),
+    });
+    const data = (await response.json().catch(() => ({})));
+    if (!response.ok || data.ok === false) {
+        return { ok: false, reason: data.error ?? `list roles failed (HTTP ${response.status})` };
+    }
+    const roles = Array.isArray(data.result?.roles)
+        ? data.result.roles.filter((role) => !!role && typeof role === 'object')
+        : [];
+    return {
+        ok: true,
+        count: typeof data.result?.count === 'number' ? data.result.count : roles.length,
+        roles,
+    };
+}
+/** bootUiBridge 调用一次(幂等)。 */
+export function registerBuiltinActions() {
+    if (registered)
+        return;
+    registered = true;
+    const st = () => useShellStore.getState();
+    // ── 视图 / 布局(纯 UI)──────────────────────────────────────────────────
+    registerAction({
+        id: 'panel.toggle_sidebar',
+        title: '折叠/展开侧栏',
+        description: 'Toggle the left sidebar collapsed state.',
+        capability: 'write',
+        surface: 'ui',
+        run: () => {
+            st().toggleSidebar();
+            return { status: 'completed', stateDigest: { sidebarCollapsed: st().sidebarCollapsed } };
+        },
+    });
+    registerAction({
+        id: 'panel.toggle_chatpanel',
+        title: '折叠/展开聊天面板',
+        description: 'Toggle the chat panel collapsed state.',
+        capability: 'write',
+        surface: 'ui',
+        run: () => {
+            st().toggleChatpanel();
+            return { status: 'completed', stateDigest: { chatpanelCollapsed: st().chatpanelCollapsed } };
+        },
+    });
+    registerAction({
+        id: 'app.set_fullscreen',
+        title: '沉浸模式',
+        description: 'Enter or exit fullscreen (immersive) mode which hides all chrome around the main area.',
+        schema: { type: 'object', properties: { value: { type: 'boolean' } }, required: ['value'] },
+        capability: 'write',
+        surface: 'ui',
+        run: (args) => {
+            st().setFullscreen(args.value);
+            return { status: 'completed', stateDigest: { fullscreen: st().fullscreen } };
+        },
+    });
+    // 扩展页面发现与打开：AI 和人共用 Page navigation。
+    registerAction({
+        id: 'extension.list',
+        title: '列出扩展页面',
+        description: 'List installed extensions that contribute pages. Returns { count, plugins:[{id,name,description}] }.',
+        capability: 'read',
+        firstClass: true,
+        surface: 'ui',
+        run: async () => {
+            const { items } = await listExtensions();
+            // 2026-08-06 外审 B5:此前这里带 railPinned/railNote —— 判据是一张手维护的
+            // 14-slug 表,而 rail 的真实可达性 = manifest 的 contributes.activities ∩ 每浏览
+            // 器 localStorage 的 pin 集,与那张表毫无关系。默认(无 localStorage)全部
+            // pinned,note 却断言"都看不到"并禁止 agent 说出正确答案 —— 用单一账源下
+            // 否定结论 + 手维护副本必然腐烂,两条都是本打样自己立的反面不变式。删除;
+            // 可达性交给真投影(将来 rail 接入 surface 总线后由它现算),不再猜。
+            const plugins = items
+                .filter((p) => (p.contributes?.pages?.length ?? 0) > 0)
+                .map((p) => ({
+                id: p.id,
+                name: pickLang(p.displayName, 'zh', p.id),
+                description: p.description ? pickLang(p.description, 'zh', '') : '',
+            }));
+            return { status: 'completed', stateDigest: { count: plugins.length, plugins } };
+        },
+    });
+    registerAction({
+        id: 'extension.open',
+        title: '打开扩展页面',
+        description: 'Open the Page contributed by a specific extension id. Discover valid ids via extension.list.',
+        schema: { type: 'object', properties: { extensionId: { type: 'string' } }, required: ['extensionId'] },
+        capability: 'write',
+        firstClass: true,
+        surface: 'ui',
+        // 命令面板把 extensionId 变成「现有插件」下拉,免瞎填。
+        choices: {
+            extensionId: async () => (await listExtensions()).items.filter((p) => (p.contributes?.pages?.length ?? 0) > 0).map((p) => p.id),
+        },
+        run: async (args) => {
+            const extensionId = args.extensionId;
+            await openExtensionPage(extensionId);
+            return { status: 'completed', stateDigest: { extensionId } };
+        },
+    });
+    // 角色桥(插件桥的「角色版」:人和 AI 同一条路造/用/看角色)。role.create 是**唯一**创建
+    // 路径 —— AI 经 ui_act_role_create / ui_invoke 调,人经 ⌘K / 按钮 pill 调;背后是 server
+    // 执行器 team:create_role(对 AI 隐藏),经 /api/tools/call(caller:user)落 agent-pack 到
+    // 用户安装/项目专属 extension source、reloadPlugins,新角色 ~5s 内自动进名单(roster 轮询 +1)。治理靠 trust-gate
+    // 的 delegate 闸(capability 如实声明)。role.list 让 AI 能告诉用户「有哪些角色」并防重名;
+    // role.open 打开角色页 / 把某角色绑到当前会话展示其详情。
+    registerAction({
+        id: 'role.create',
+        title: '创建新角色',
+        description: 'Mint a NEW teammate/agent role when no existing role in the roster fits. Args: id (single segment [a-zA-Z0-9_-]) + persona (markdown: who they are / what they are good at / when to delegate to them / what they produce) + optional displayName / role / avatar / color / scope("global"|"project") / tools(host-tool allow globs). The new role persists and joins the roster (delegate_to_subagent can then dispatch it). Duplicate ids are rejected, never overwritten.',
+        schema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: '单段 [a-zA-Z0-9_-];如 "level-designer"' },
+                persona: { type: 'string', description: '角色 markdown:是谁 / 擅长什么 / 何时被派 / 产出什么' },
+                displayName: {
+                    type: 'object',
+                    properties: { zh: { type: 'string' }, en: { type: 'string' } },
+                },
+                role: { type: 'string', description: "定位,如 'pillar' / 'artist' / 'peer'" },
+                avatar: { type: 'string', description: 'emoji / 单字符' },
+                color: { type: 'string', description: '#hex' },
+                scope: { type: 'string', enum: ['global', 'project'] },
+                tools: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['id', 'persona'],
+        },
+        capability: 'delegate',
+        firstClass: true,
+        surface: 'both',
+        timeoutMs: 15000,
+        run: async (args) => {
+            const r = await fetch('/api/tools/call', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ toolId: 'team:create_role', caller: { kind: 'user' }, args }),
+            });
+            const data = (await r.json().catch(() => ({})));
+            if (!r.ok || data.ok === false) {
+                return { status: 'rejected', reason: data.error ?? `create role failed (HTTP ${r.status})` };
+            }
+            const res = data.result ?? {};
+            return { status: 'completed', stateDigest: { id: res.id ?? args.id, scope: res.scope } };
+        },
+    });
+    registerAction({
+        id: 'role.list',
+        title: '列出角色',
+        description: 'List all currently dispatchable roles (plugin agents + built-ins). Use this to tell the user which roles exist / check for duplicates before role.create. Returns { count, roles:[{id,role,displayName,source}] }.',
+        capability: 'read',
+        firstClass: true,
+        surface: 'both',
+        run: async () => {
+            const roster = await readRoleRoster();
+            if (!roster.ok)
+                return { status: 'rejected', reason: roster.reason };
+            return { status: 'completed', stateDigest: { count: roster.count, roles: roster.roles } };
+        },
+    });
+    registerAction({
+        id: 'role.open',
+        title: '打开角色页',
+        description: "Open the roles/team surface. With no args it switches to the AI workspace (where the roster lives). With { id } it also binds that role to the current chat session so its persona detail is shown. Use this to show the user the team or a specific teammate.",
+        schema: { type: 'object', properties: { id: { type: 'string' } } },
+        capability: 'read',
+        firstClass: true,
+        surface: 'ui',
+        run: async (args) => {
+            const id = typeof args.id === 'string' && args.id.trim() ? args.id.trim() : '';
+            const state = st();
+            const activeTab = id
+                ? state.tabs.find((tab) => tab.sid === state.activeSid)
+                : undefined;
+            const targetSid = activeTab?.sid;
+            if (id && !activeTab) {
+                return { status: 'rejected', reason: 'role.open with id requires an active chat session' };
+            }
+            if (id) {
+                const roster = await readRoleRoster();
+                if (!roster.ok) {
+                    return { status: 'rejected', reason: `role.open could not read the current roster: ${roster.reason}` };
+                }
+                const roleExists = roster.roles.some((role) => role.id === id);
+                if (!roleExists) {
+                    return { status: 'rejected', reason: `role.open could not find role "${id}" in the current roster` };
+                }
+            }
+            await openExtensionPage('@forgeax/studio-agents');
+            if (id) {
+                const currentState = st();
+                const targetTab = currentState.tabs.find((tab) => tab.sid === targetSid);
+                if (!targetTab) {
+                    return { status: 'rejected', reason: 'role.open target session no longer exists' };
+                }
+                st().setTabAgent(targetTab.sid, id); // 固定调用开始时的会话,避免 await 期间切 tab 后绑错对象。
+                if (st().tabs.find((tab) => tab.sid === targetTab.sid)?.agentId !== id) {
+                    return { status: 'rejected', reason: 'role.open could not bind the role to the target chat session' };
+                }
+                return { status: 'completed', stateDigest: { opened: id, boundSid: targetTab.sid, activeWorkspace: 'ai' } };
+            }
+            return { status: 'completed', stateDigest: { activeWorkspace: 'ai' } };
+        },
+    });
+    registerAction({
+        id: 'overlay.open',
+        title: '打开浮层',
+        description: "Open an overlay by id (e.g. 'settings'). Optional param selects a section inside it.",
+        schema: {
+            type: 'object',
+            properties: { id: { type: 'string' }, param: { type: 'string' } },
+            required: ['id'],
+        },
+        capability: 'write',
+        surface: 'ui',
+        run: (args) => {
+            const requestedId = args.id;
+            const overlayId = resolveRegisteredOverlayId(requestedId);
+            if (!overlayId) {
+                return { status: 'rejected', reason: `overlay.open could not find registered overlay "${requestedId}"` };
+            }
+            st().openOverlay(overlayId, typeof args.param === 'string' ? args.param : undefined);
+            if (st().activeOverlay !== overlayId) {
+                return { status: 'rejected', reason: `overlay.open could not activate overlay "${overlayId}"` };
+            }
+            return { status: 'completed', stateDigest: { activeOverlay: overlayId } };
+        },
+    });
+    registerAction({
+        id: 'overlay.close',
+        title: '关闭浮层',
+        description: 'Close the currently open overlay, if any.',
+        capability: 'write',
+        surface: 'ui',
+        run: () => {
+            st().closeOverlay();
+            return { status: 'completed' };
+        },
+    });
+    // ── 日志类(瞬态,清空不算删除用户数据)────────────────────────────────────
+    registerAction({
+        id: 'console.clear',
+        title: '清空控制台',
+        description: "Clear a collected console buffer. source:'browser' (default) clears the studio-shell browser console buffer PLUS the cross-tier health entries (fatal region banners are preserved). source:'game' clears the in-app game/editor console (store.consoleLog). Neither touches the raw browser DevTools buffer.",
+        schema: { type: 'object', properties: { source: { type: 'string', enum: ['browser', 'game'] } } },
+        capability: 'write',
+        surface: 'ui',
+        run: (args) => {
+            const source = args.source === 'game' ? 'game' : 'browser';
+            if (source === 'game') {
+                const cleared = st().consoleLog.length;
+                st().clearConsole();
+                return { status: 'completed', stateDigest: { source, cleared } };
+            }
+            const cleared = getBrowserConsole().length + useHealthStore.getState().entries.length;
+            clearBrowserConsole();
+            useHealthStore.getState().clear(); // 只清 entries;fatal 横幅由 clearFatal 单独管,不受影响
+            return { status: 'completed', stateDigest: { source, cleared } }; // 回报清了几条,避免「点了没反应」
+        },
+    });
+    // AI 可读控制台(方案「让 AI 感知」的补全)。区分两个**不同**的东西:
+    //  - source:'browser'(默认)→ 读 useHealthStore:studio 外壳已采集的**浏览器控制台/健康流**
+    //    (shell 的 console.error/console.warn + window.onerror + unhandledrejection + iframe 转发的
+    //     forgeax:health / VAG_CONSOLE 报错),跨端汇聚,也落盘 .forgeax/logs/info.jsonl。
+    //    ⚠ 现采集只含 error/warn/health 级别,不含 shell 的 console.log/info(要全量需扩采集)。
+    //  - source:'game' → 读 store.consoleLog:引擎/编辑器 iframe 的**游戏控制台**全量流。
+    //  两者都不是浏览器 DevTools 的原始缓冲(网页读不到),'browser' 是产品自采集的最接近者。
+    registerAction({
+        id: 'console.read',
+        title: '读取控制台',
+        description: "Read the studio's collected console feed. source:'browser' (default) = the full studio-shell browser console (ALL levels: log/info/warn/error/debug, captured into a 500-entry ring buffer) merged with cross-tier iframe/health signals (window.onerror, unhandled rejections, forwarded play/edit/plugin/engine health). source:'game' = the in-app game/editor console stream. Params: source ('browser'|'game'), level (filter), limit (default 50, max 200). Returns { source, total, count, lines } in the result. This is the studio's own captured console (a web page cannot read the raw browser DevTools buffer directly).",
+        schema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string', enum: ['browser', 'game'] },
+                level: { type: 'string' },
+                limit: { type: 'number' },
+            },
+        },
+        capability: 'read',
+        firstClass: true, // 让模型直接看到这条读工具,免一次 snapshot 发现
+        surface: 'ui',
+        run: (args) => {
+            const source = args.source === 'game' ? 'game' : 'browser';
+            const level = typeof args.level === 'string' ? args.level : undefined;
+            const limit = Math.min(typeof args.limit === 'number' && args.limit > 0 ? Math.floor(args.limit) : 50, 200);
+            if (source === 'game') {
+                const all = st().consoleLog;
+                const f = level ? all.filter((l) => l.level === level) : all;
+                const lines = f.slice(-limit).map((l) => ({ level: l.level, text: l.text, ts: l.ts }));
+                return { status: 'completed', stateDigest: { source, total: all.length, count: lines.length, lines } };
+            }
+            // browser: 外壳全量 console(browserConsole,所有 level)+ 跨端 iframe/health
+            // (healthStore,去掉与外壳 console-error/warn 重复的),按 ts 合并取尾部。
+            const shell = getBrowserConsole().map((e) => ({
+                level: e.level,
+                source: 'shell',
+                code: undefined,
+                text: e.text,
+                ts: e.ts,
+                ...(e.repeat ? { repeat: e.repeat } : {}),
+            }));
+            const health = useHealthStore
+                .getState()
+                .entries.filter((e) => !(e.source === 'shell' && (e.code === 'console-error' || e.code === 'console-warn')))
+                .map((e) => ({ level: e.level, source: e.source, code: e.code, text: e.message, ts: e.ts }));
+            let merged = [...shell, ...health].sort((a, b) => a.ts - b.ts);
+            if (level)
+                merged = merged.filter((e) => e.level === level);
+            const lines = merged.slice(-limit);
+            return { status: 'completed', stateDigest: { source, total: merged.length, count: lines.length, lines } };
+        },
+    });
+    registerAction({
+        id: 'network.clear',
+        title: '清空网络日志',
+        description: 'Clear the in-app network log panel (store.networkLog). NOT the browser DevTools network tab.',
+        capability: 'write',
+        surface: 'ui',
+        run: () => {
+            const cleared = st().networkLog.length;
+            st().clearNetwork();
+            return { status: 'completed', stateDigest: { cleared } };
+        },
+    });
+    // ── 会话(背后是 server REST → surface 'both',server 是行为 SSOT)──────────
+    registerAction({
+        id: 'session.switch',
+        title: '切换会话',
+        description: 'Switch the active chat session to the given sid (see the session.tabs state slice for candidates).',
+        schema: { type: 'object', properties: { sid: { type: 'string' } }, required: ['sid'] },
+        capability: 'write',
+        firstClass: true, // P1-9:高频 action 派生一等 ToolSpec(ui_act_*)
+        surface: 'ui',
+        timeoutMs: 15_000,
+        run: async (args) => {
+            await st().switchToSession(args.sid);
+            return { status: 'completed', stateDigest: { activeSid: st().activeSid } };
+        },
+    });
+    registerAction({
+        id: 'session.create',
+        title: '新建会话',
+        description: 'Create a new chat session (optionally named) and switch to it.',
+        schema: { type: 'object', properties: { displayName: { type: 'string' } } },
+        capability: 'write',
+        firstClass: true, // P1-9:高频 action 派生一等 ToolSpec(ui_act_*)
+        surface: 'both',
+        timeoutMs: 20_000,
+        run: async (args) => {
+            const { sid } = await getSessionClient().createSession(typeof args.displayName === 'string' ? { displayName: args.displayName } : undefined);
+            await st().refreshSessions();
+            await st().switchToSession(sid);
+            return { status: 'completed', stateDigest: { activeSid: sid } };
+        },
+    });
+    registerAction({
+        id: 'session.close',
+        title: '关闭会话',
+        description: 'Close (delete) a chat session by sid. Destructive: the session and its history are removed from disk.',
+        schema: { type: 'object', properties: { sid: { type: 'string' } }, required: ['sid'] },
+        capability: 'delete', // 如实声明:编排层会弹确认卡
+        firstClass: true, // P1-9:高频 action 派生一等 ToolSpec(ui_act_*)
+        surface: 'both',
+        timeoutMs: 15_000,
+        run: async (args) => {
+            const sid = args.sid;
+            const result = await st().closeSession(sid);
+            if (result.status === 'not-deleted') {
+                return {
+                    status: 'rejected',
+                    reason: `session.close could not delete session "${sid}": ${result.error.message}`,
+                    stateDigest: { code: result.error.code, activeSid: result.activeSid },
+                };
+            }
+            if (st().tabs.some((tab) => tab.sid === sid)) {
+                return {
+                    status: 'completed',
+                    stateDigest: {
+                        deleted: true,
+                        activeSid: result.activeSid,
+                        localStateConsistent: false,
+                        warning: {
+                            code: 'SESSION_DELETE_READBACK_FAILED',
+                            message: `Session "${sid}" was deleted on the server but local state still contains it`,
+                        },
+                        recovery: 'Refresh sessions before continuing. Do not retry the deletion.',
+                    },
+                };
+            }
+            if (result.status === 'deleted-without-active-session') {
+                return {
+                    status: 'completed',
+                    stateDigest: {
+                        deleted: true,
+                        activeSid: null,
+                        replacementReady: false,
+                        warning: result.error,
+                        recovery: 'Create or refresh a session before continuing chat work. Do not retry the deletion.',
+                    },
+                };
+            }
+            return { status: 'completed', stateDigest: { deleted: true, activeSid: result.activeSid } };
+        },
+    });
+    registerAction({
+        id: 'session.rename',
+        title: '重命名会话',
+        description: 'Persistent session rename is not available in this Studio version; this action rejects instead of changing only the temporary tab label.',
+        schema: {
+            type: 'object',
+            properties: { sid: { type: 'string' }, displayName: { type: 'string' } },
+            required: ['sid', 'displayName'],
+        },
+        capability: 'write',
+        surface: 'both',
+        available: () => 'Persistent session rename is not available in this Studio version',
+        run: () => ({
+            status: 'rejected',
+            reason: 'Persistent session rename is not available in this Studio version',
+        }),
+    });
+    registerAction({
+        id: 'sessions.refresh',
+        title: '刷新会话列表',
+        description: 'Re-fetch the session list from the server.',
+        capability: 'read',
+        surface: 'both',
+        run: async () => {
+            const result = await st().refreshSessions();
+            if (result.status === 'failed') {
+                return {
+                    status: 'rejected',
+                    reason: `sessions.refresh could not read the server session list: ${result.error.message}`,
+                    stateDigest: { code: result.error.code },
+                };
+            }
+            if (result.status === 'superseded') {
+                return {
+                    status: 'rejected',
+                    reason: 'sessions.refresh was superseded by a newer game selection',
+                };
+            }
+            return { status: 'completed', stateDigest: { tabs: st().tabs.length, serverCount: result.count } };
+        },
+    });
+    registerAction({
+        id: 'sessions.list',
+        title: '列出会话',
+        description: 'List chat sessions of the current game scope. Returns sid/displayName rows in stateDigest.',
+        capability: 'read',
+        surface: 'both',
+        run: async () => {
+            const rows = await getSessionClient().fetchSessionList(st().activeGameSlug ?? undefined);
+            return {
+                status: 'completed',
+                stateDigest: rows.map((s) => ({ sid: s.sid, displayName: s.displayName ?? null })),
+            };
+        },
+    });
+    registerAction({
+        id: 'game.switch',
+        title: '切换游戏',
+        description: 'Select the active game (project) by slug. Every open Studio page follows the server authority.',
+        schema: { type: 'object', properties: { slug: { type: 'string' } }, required: ['slug'] },
+        capability: 'write',
+        firstClass: true, // P1-9:高频 action 派生一等 ToolSpec(ui_act_*)
+        surface: 'both',
+        timeoutMs: 20_000,
+        // 命令面板把 slug 变成「现有游戏」下拉,避免瞎填触发 server 404。
+        choices: {
+            slug: async () => {
+                const result = await getStudioProjectClient().listProjects();
+                return result.games.map((project) => project.slug);
+            },
+        },
+        run: async (args) => {
+            const switched = await st().setActiveGame(args.slug);
+            const runtime = st().activeGameRuntime;
+            return {
+                status: 'completed',
+                stateDigest: {
+                    activeGameSlug: st().activeGameSlug,
+                    runtimeStatus: runtime.status,
+                    ...(switched.warning ? { warning: switched.warning } : {}),
+                },
+            };
+        },
+    });
+    registerAction({
+        id: 'game.create',
+        title: '新建游戏',
+        description: 'Create a NEW game (project) from the template and give it its own dedicated chat session. Args: slug (required, 1-41 chars lowercase ASCII/digits/hyphens, must start with a letter/digit — e.g. "neon-runner") + optional name (display name) + optional brief (one line describing what game to make, recorded in FORGE.md for later). Fails with 409 if the slug already exists — use game.switch for existing games; list existing slugs to avoid collisions. NOTE: this does NOT switch the UI to the new game (switching mid-turn would break the active chat channel). Tell the user the game is ready and to open it from the top-bar game switcher; game.switch will land on its dedicated session.',
+        schema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: '1-41 位小写字母/数字/连字符,首位字母或数字;如 "neon-runner"' },
+                name: { type: 'string', description: '显示名(可选,缺省用 slug)' },
+                brief: { type: 'string', description: '一句话说明要做什么游戏(可选,写进 FORGE.md)' },
+            },
+            required: ['slug'],
+        },
+        capability: 'write',
+        firstClass: true,
+        surface: 'both',
+        timeoutMs: 20_000,
+        run: async (args) => {
+            const slug = String(args.slug ?? '').trim();
+            const data = await getStudioProjectClient().createProject({
+                slug,
+                name: typeof args.name === 'string' ? args.name : slug,
+                brief: typeof args.brief === 'string' ? args.brief : '',
+            });
+            if (!data.ok) {
+                return { status: 'rejected', reason: data.error ?? 'create game failed' };
+            }
+            return {
+                status: 'completed',
+                stateDigest: {
+                    slug,
+                    session: data.session?.sid ?? null,
+                    hint: '新游戏已建好并配了独立会话;从顶栏游戏切换器切过去即可开始做',
+                },
+            };
+        },
+    });
+    // ── 状态摘要片(评审 2.5:注册式 derive,禁手写台账)────────────────────────
+    registerStateSlice('app.layout', () => ({
+        fullscreen: st().fullscreen,
+        sidebarCollapsed: st().sidebarCollapsed,
+        chatpanelCollapsed: st().chatpanelCollapsed,
+    }));
+    registerStateSlice('game.active', () => st().activeGameSlug);
+    registerStateSlice('session.active', () => st().activeSid);
+    registerStateSlice('session.tabs', () => st().tabs.slice(0, 20).map((t) => ({ sid: t.sid, label: tabLabel(t) })));
+}

package/dist/package/node/lib/bus.js

@@ -0,0 +1,71 @@
+// interface 跨-app 事件总线 primitive —— 纯机制，零 app 语义。
+//
+// 设计意图（R5 store 收敛）：interface 是可复用 AppKit foundation，不认识任何上层 app 的 topic。
+// 各 app 通过 TS declaration merging 往 `BusTopics` 里登记自己的 topic → payload
+// 类型；interface 只提供 publish / subscribe 机制本身。这样「新增 app 不改 foundation」——app 自带
+// 自己的 topic 声明即可。
+//
+// 两种用法：
+//   1. 意图 (fire-and-forget)：`publish('overlay:open', { id })` → 当前订阅者收到，
+//      不留存。用于跨 app 导航/深链意图（原 store 里的 ~14 个 pending* 槽）。
+//   2. 只读真值快照：`publish('sessions:changed', snap, { retain: true })` → 留存最近
+//      一次值；之后 subscribe 的新订阅者**立即**收到该值。用于 owner app 广播共享真值、
+//      其他 app 存只读副本（原 store 里 tabs / liveAgents 等跨 app 读的状态）。
+//
+// HMR 安全：handler 表 + retained 表挂在 globalThis 上，模块被重新求值时不丢订阅、
+// 不丢最近快照。
+const _BUS_FLAG = '__FORGEAX_BUS__';
+const _gt = globalThis;
+const _bus = _gt[_BUS_FLAG] ?? (_gt[_BUS_FLAG] = { handlers: new Map(), retained: new Map() });
+/** 发布一条 topic。
+ *  @param opts.retain 留存本次 payload；之后新订阅者会立即收到（快照语义）。默认 false（纯意图）。 */
+export function publish(topic, payload, opts) {
+    if (opts?.retain)
+        _bus.retained.set(topic, payload);
+    const set = _bus.handlers.get(topic);
+    if (!set)
+        return;
+    for (const h of [...set]) {
+        try {
+            h(payload);
+        }
+        catch (err) {
+            console.warn(`[bus] handler for "${topic}" threw`, err);
+        }
+    }
+}
+/** 订阅一条 topic，返回 unsubscribe。
+ *  若该 topic 有 retained 快照，handler 会被**同步立即**调用一次（补齐当前值）。 */
+export function subscribe(topic, handler) {
+    const h = handler;
+    let set = _bus.handlers.get(topic);
+    if (!set) {
+        set = new Set();
+        _bus.handlers.set(topic, set);
+    }
+    set.add(h);
+    if (_bus.retained.has(topic)) {
+        try {
+            h(_bus.retained.get(topic));
+        }
+        catch (err) {
+            console.warn(`[bus] replay for "${topic}" threw`, err);
+        }
+    }
+    return () => {
+        const s = _bus.handlers.get(topic);
+        if (s) {
+            s.delete(h);
+            if (s.size === 0)
+                _bus.handlers.delete(topic);
+        }
+    };
+}
+/** 读取某 topic 最近一次 retained 快照（无则 undefined）。给「订阅前先取一次当前值」用。 */
+export function peek(topic) {
+    return _bus.retained.get(topic);
+}
+/** 清掉某 topic 的 retained 快照（owner app 卸载共享真值时用）。 */
+export function clearRetained(topic) {
+    _bus.retained.delete(topic);
+}

package/dist/package/node/lib/checkpoint-api.js

@@ -0,0 +1,41 @@
+/** checkpoint-api —— checkpoint 回退点的 REST 包装(server api/sessions.ts 路由)。
+ *  与 forgeax-bridge 同款风格:不持状态,调用方显式传 sid。 */
+async function post(url, body) {
+    const r = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+        let detail;
+        try {
+            detail = (await r.json()).error ?? `HTTP ${r.status}`;
+        }
+        catch {
+            detail = `HTTP ${r.status}`;
+        }
+        throw new Error(detail);
+    }
+    return (await r.json());
+}
+export async function fetchCheckpoints(sid, signal) {
+    const r = await fetch(`/api/sessions/${encodeURIComponent(sid)}/checkpoints`, { signal });
+    if (!r.ok)
+        throw new Error(`GET checkpoints ${r.status}`);
+    return (await r.json());
+}
+export function rewindPreview(sid, msgId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/preview`, { msgId });
+}
+export function rewindTo(sid, msgId, mode) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind`, { msgId, mode });
+}
+export function rewindCancel(sid, boundaryId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/cancel`, { boundaryId });
+}
+export function rewindOverwriteDirty(sid, boundaryId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/overwrite-dirty`, { boundaryId });
+}
+export function rewindUndoOverwrite(sid, boundaryId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/undo-overwrite`, { boundaryId });
+}