@jack200714/mafw 4.5.1 → 4.8.0

package/README.md

@@ -146,14 +146,17 @@ npx electron-vite build
 
 ### 3. opencode 接入（可选）
 
+> npm 包仅含 **Gateway + TUI**（`bin: mafw`）。opencode 插件入口（`dist/plugin.js`）不在
+> npm 包内——插件方式接入请从源码构建（`npm run build` 后本地安装 tgz），或仅用下方
+> MCP remote 接线（无需插件）。
+
 ```json
 {
-  "plugin": ["@jack200714/mafw"],
   "mcp": { "mafw": { "type": "remote", "url": "http://127.0.0.1:3000/mcp", "enabled": true } }
 }
 ```
 
-插件激活时自动补写缺失的 MCP 接线并备份原配置（fail-open）。
+源码构建后插件激活时会自动补写缺失的 MCP 接线并备份原配置（fail-open）。
 
 ## 仓库结构
 

package/bin/mafw.js

@@ -125,8 +125,23 @@ function startGateway(background) {
     process.exit(1);
   }
 
+  // Background mode stdio: stdin/stdout 'ignore' (devnull), stderr redirected
+  // straight to a file fd. All three must avoid live pipes: a pipe's write end
+  // breaks once this short-lived CLI exits, and any later console.log in the
+  // gateway (e.g. mdns-advertiser) then crashes it with an unhandled EPIPE; a
+  // piped stderr would also keep THIS CLI's event loop alive and make
+  // `mafw daemon` hang. File fd = crash traces persist with zero plumbing.
+  let stdio = background ? ['ignore', 'ignore', 'ignore'] : 'inherit';
+  if (background) {
+    try {
+      const errLog = path.join(LOG_DIR, 'gateway-stderr.log');
+      try { if (!fs.existsSync(LOG_DIR)) fs.mkdirSync(LOG_DIR, { recursive: true }); } catch {}
+      stdio = ['ignore', 'ignore', fs.openSync(errLog, 'a')];
+    } catch { /* fall back to full ignore */ }
+  }
+
   const child = spawn(process.execPath, [GATEWAY_SCRIPT], {
-    stdio: background ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    stdio,
     detached: background,
     windowsHide: true,
   });
@@ -134,19 +149,6 @@ function startGateway(background) {
   writePid(child.pid);
 
   if (background) {
-    // Diagnostics: capture stderr to a file (a detached gateway that crashes
-    // silently otherwise leaves no trace). stdout is discarded; the gateway's
-    // own file logging covers normal logs.
-    // NOTE: use a raw fd + writeSync — a fs.WriteStream here never ends, which
-    // keeps the parent's event loop alive so `mafw daemon` hangs (and any
-    // tree-kill then takes the detached gateway down with it).
-    const errLog = path.join(LOG_DIR, 'gateway-stderr.log');
-    try { if (!fs.existsSync(LOG_DIR)) fs.mkdirSync(LOG_DIR, { recursive: true }); } catch {}
-    const errFd = fs.openSync(errLog, 'a');
-    if (child.stderr) {
-      child.stderr.on('data', (chunk) => { try { fs.writeSync(errFd, chunk); } catch {} });
-    }
-    if (child.stdout) child.stdout.destroy();
     child.unref();
     console.log(`Gateway started in background (PID: ${child.pid})`);
     console.log(`Logs: ${LOG_FILE}`);

package/gateway/dist/index.js

@@ -99,6 +99,7 @@ const self_update_1 = require("./self-update");
 const step_inject_1 = require("./recall/step-inject");
 const inject_format_1 = require("./recall/inject-format");
 const normalize_1 = require("./runtime/normalize");
+const event_broadcast_1 = require("./runtime/event-broadcast");
 const budget_guard_1 = require("./core/budget-guard");
 const goal_budget_1 = require("./core/goal-budget");
 const contract_1 = require("./runtime/contract");
@@ -107,6 +108,7 @@ const pi_runtime_1 = require("./runtime/plugins/pi-runtime");
 const permission_1 = require("./routes/permission");
 const runtime_switch_1 = require("./routes/runtime-switch");
 const plugins_1 = require("./routes/plugins");
+const hub_1 = require("./plugins/hub");
 const restart_agent_1 = require("./routes/restart-agent");
 const session_mutations_1 = require("./routes/session-mutations");
 const serve_supervisor_1 = require("./runtime/serve-supervisor");
@@ -157,6 +159,10 @@ class MafwScheduler {
     serveOwned = false;
     serveExitStreak = 0;
     serveRecovering = false;
+    // External runtimes (pi) do not own serve: the watchdog can only warn and
+    // reconnect the event stream. Flag keeps that warning a one-shot ERROR per
+    // outage instead of an unbounded WARN loop.
+    serveExternalDownNotified = false;
     serveWatchdogTimer = null;
     serveRetryTimer = null;
     serveStableTimer = null;
@@ -206,8 +212,6 @@ class MafwScheduler {
     registeredProjects = new Map();
     registryPath;
     registryWriteQueue = Promise.resolve();
-    configPath;
-    configWriteQueue = Promise.resolve();
     running = true;
     // private dashboard?: DashboardServer;
     mcpEndpoint;
@@ -252,7 +256,6 @@ class MafwScheduler {
         this.serveUrl = config_1.config.server.serveUrl;
         this.apiPort = config_1.config.server.apiPort;
         this.pollInterval = config_1.config.timeouts.backupPollInterval;
-        this.configPath = config_1.config.paths.globalConfig;
         this.registryPath = config_1.config.paths.registryFile;
         this.chatSessions = new chat_sessions_1.ChatSessionManager();
         this.serveSupervisor = (0, serve_supervisor_1.createServeSupervisor)({
@@ -423,8 +426,7 @@ class MafwScheduler {
         // 4. Dashboard is now served via the API server on the same port
         // this.dashboard = new DashboardServer(3001, this.projectDir, this);
         // this.dashboard.start();
-        // 5. 恢复配置和注册表
-        await this.recoverConfig();
+        // 5. 恢复注册表（权威源：gateway DB kv_store + legacy 文件兜底）
         await this.recoverRegistry();
         // 5.0 Data-directory migration: move memory store + pipeline files from
         // the previously-fixed gateway package .mafw (and any project-relative
@@ -773,7 +775,8 @@ class MafwScheduler {
                         registeredAt: new Date().toISOString()
                     });
                     this.persistRegistry();
-                    this.persistConfig();
+                    // 桌面 renderer 依此事件刷新 Rail 项目列表（否则只在 gateway ready 时拉一次）。
+                    this.broadcast((0, event_broadcast_1.projectRegisteredEvent)(projectDir));
                     logger_1.log.info(`[Scheduler] Project registered via filesystem: ${projectDir}`);
                 }
                 catch {
@@ -952,13 +955,15 @@ class MafwScheduler {
             catch (err) {
                 logger_1.log.warn(`[Trajectory] idle aggregation failed (non-fatal): ${err.message}`);
             }
-            this.broadcast({ type: 'opencode_event', data: { type: 'message.complete', sessionID, ...(memoryWorker ? { internal: true } : {}) } });
+            this.broadcast((0, event_broadcast_1.opencodeBroadcast)({ type: 'message.complete', sessionID }, memoryWorker));
         }
         else if (f.broadcast === 'error') {
-            this.broadcast({ type: 'opencode_event', data: { type: 'message.error', sessionID, error: props?.error instanceof Error ? props.error.message : String(props?.error ?? 'Unknown error'), ...(memoryWorker ? { internal: true } : {}) } });
+            this.broadcast((0, event_broadcast_1.opencodeBroadcast)({ type: 'message.error', sessionID, error: props?.error instanceof Error ? props.error.message : String(props?.error ?? 'Unknown error') }, memoryWorker));
         }
         else {
-            this.broadcast({ type: 'opencode_event', data: { type, properties: props, sessionID, ...(memoryWorker ? { internal: true } : {}) } });
+            // directory 透传：session.created/updated/deleted 的消费方（桌面 Rail）
+            // 据此定位所属项目做定向刷新（normalize 已从 GlobalEvent 信封提取）。
+            this.broadcast((0, event_broadcast_1.opencodeBroadcast)({ type, properties: props, sessionID, directory: f.directory }, memoryWorker));
         }
     }
     /** 能力门：runtime 未声明该能力时以 503 显式拒绝（fail-open 的声明式降级）。 */
@@ -2122,6 +2127,10 @@ class MafwScheduler {
             if (!this.running || this.serveRecovering)
                 return;
             if (await this.isServeHealthy()) {
+                if (failures > 0 || this.serveExternalDownNotified) {
+                    logger_1.log.info('[Scheduler] Serve back online');
+                }
+                this.serveExternalDownNotified = false;
                 failures = 0;
                 return;
             }
@@ -2130,7 +2139,10 @@ class MafwScheduler {
             if (failures >= this.serveWatchdogFailures) {
                 failures = 0;
                 if (this.opencodeClient?.external) {
-                    logger_1.log.warn('[Scheduler] External serve unreachable; reconnecting event stream only (not killing external process)');
+                    if (!this.serveExternalDownNotified) {
+                        this.serveExternalDownNotified = true;
+                        logger_1.log.error('[Scheduler] External serve unreachable — the active runtime does not own the serve process, so it will NOT be respawned. Serve-dependent features (provider list, sessions, approvals) are degraded.');
+                    }
                     try {
                         await this.subscribeToEvents();
                     }
@@ -3600,7 +3612,8 @@ class MafwScheduler {
                                 });
                                 // 持久化到磁盘（写队列防并发覆盖）
                                 await this.persistRegistry();
-                                await this.persistConfig();
+                                // 桌面 renderer 依此事件刷新 Rail 项目列表（否则只在 gateway ready 时拉一次）。
+                                this.broadcast((0, event_broadcast_1.projectRegisteredEvent)(projectDir));
                                 if (this.opencodeClient) {
                                     try {
                                         await this.ensureManagerSession(projectDir, mafwDir);
@@ -4089,6 +4102,9 @@ class MafwScheduler {
                                 if (this.automationEngine)
                                     this.automationEngine.setRuntimeClient(rt);
                                 await this.resubscribeEvents(`runtime switched to '${rt.name}'`);
+                                // Desktop hint: a runtime switch swaps the session storage backend
+                                // (opencode SQLite vs pi), so cached session lists are stale.
+                                this.broadcast({ type: 'runtime_switched', runtime: rt.name, previous: prev?.name ?? null });
                                 if (prev && prev.dispose) {
                                     try {
                                         await prev.dispose();
@@ -4144,6 +4160,21 @@ class MafwScheduler {
                                 usage: config_1.config.resolvePath('usage-plugins'),
                                 ui: process.env.MAFW_UI_PLUGINS_DIR || path.join(os.homedir(), '.mafw', 'ui-plugins'),
                             },
+                            builtinEntries: () => {
+                                const entries = [];
+                                const rt = (name) => ({ type: 'runtime', name, file: '(builtin)', status: 'enabled', size: 0, mtime: '' });
+                                entries.push(rt('opencode'));
+                                for (const name of this.runtimeLoader?.getBuiltinNames?.() ?? [])
+                                    entries.push(rt(name));
+                                entries.push({ type: 'media', name: 'pi', file: '(builtin)', status: 'enabled', size: 0, mtime: '' });
+                                const usageState = this.pluginLoader?.getState?.() ?? [];
+                                for (const s of usageState) {
+                                    if (s.builtin && s.status === 'ok' && s.name) {
+                                        entries.push({ type: 'usage', name: s.name, file: s.file, status: 'enabled', size: 0, mtime: '', pluginType: s.pluginType });
+                                    }
+                                }
+                                return entries;
+                            },
                             getErrors: (type) => {
                                 const stateOf = (loader) => (loader && typeof loader.getState === 'function' ? loader.getState() : []);
                                 const source = type === 'runtime' ? this.runtimeLoader : type === 'media' ? this.mediaPluginLoader : type === 'usage' ? this.pluginLoader : null;
@@ -4166,6 +4197,16 @@ class MafwScheduler {
                             },
                         },
                     };
+                    try {
+                        const cleaned = (0, hub_1.cleanupExamples)(pluginHubDeps.hub);
+                        if (cleaned.removed.length)
+                            logger_1.log.info(`[PluginsHub] removed stale examples: ${cleaned.removed.length}`);
+                        if (cleaned.failed.length)
+                            logger_1.log.warn(`[PluginsHub] cleanupExamples failed: ${cleaned.failed.join(', ')}`);
+                    }
+                    catch (err) {
+                        logger_1.log.warn(`[PluginsHub] cleanupExamples error: ${err.message}`);
+                    }
                     if (req.method === 'GET' && req.url?.match(/^\/api\/plugins(?:\?|$)/)) {
                         await (0, plugins_1.handlePluginsList)(req, res, pluginHubDeps);
                         return;
@@ -5433,33 +5474,6 @@ class MafwScheduler {
             logger_1.log.info(`[Scheduler] Recovered ${filtered.length} registered projects`);
         }
     }
-    async persistConfig() {
-        this.configWriteQueue = this.configWriteQueue.then(async () => {
-            const dir = path.dirname(this.configPath);
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
-            let config = {};
-            if (fs.existsSync(this.configPath)) {
-                config = JSON.parse(fs.readFileSync(this.configPath, 'utf-8'));
-            }
-            config.projects = Object.fromEntries(this.registeredProjects);
-            fs.writeFileSync(this.configPath, JSON.stringify(config, null, 2));
-        });
-        await this.configWriteQueue;
-    }
-    async recoverConfig() {
-        if (fs.existsSync(this.configPath)) {
-            try {
-                const config = JSON.parse(fs.readFileSync(this.configPath, 'utf-8'));
-                const entries = Object.entries((config.projects || {}))
-                    .filter(([dir]) => !this.isUserDataDir(dir));
-                this.registeredProjects = new Map(entries);
-            }
-            catch (err) {
-                logger_1.log.error(`[Scheduler] Failed to recover config: ${err.message}`);
-            }
-        }
-    }
     // ── 4. 轮询（降级兜底 + autoresume） ──
     startBackupPolling() {
         const interval = config_1.config.timeouts.backupPollInterval;

package/gateway/dist/media/media-plugin-loader.js

@@ -60,7 +60,6 @@ class MediaPluginLoader {
         if (!fs.existsSync(this.pluginsDir)) {
             fs.mkdirSync(this.pluginsDir, { recursive: true });
             fs.writeFileSync(path.join(this.pluginsDir, 'README.md'), README_CONTENT);
-            fs.writeFileSync(path.join(this.pluginsDir, 'example.js.disabled'), EXAMPLE_CONTENT);
             logger_1.log.info(`[MediaPluginLoader] Created ${this.pluginsDir}`);
         }
     }
@@ -241,14 +240,3 @@ media:
     engine: qwen-vl       # override for video
 \`\`\`
 `;
-const EXAMPLE_CONTENT = `// Rename to example.js to activate
-module.exports = {
-  name: "example",
-  modalities: ["image"],
-  async createPrompt(ctx) {
-    return async (parts, opts) => {
-      return "Example analysis result";
-    };
-  },
-};
-`;

package/gateway/dist/plugins/hub.js

@@ -36,11 +36,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HubError = void 0;
 exports.parseType = parseType;
 exports.listPlugins = listPlugins;
+exports.cleanupExamples = cleanupExamples;
 exports.installPlugin = installPlugin;
 exports.setPluginEnabled = setPluginEnabled;
 exports.deletePlugin = deletePlugin;
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
 class HubError extends Error {
     status;
     constructor(status, message) {
@@ -87,6 +90,19 @@ function statEntry(type, dir, file) {
     };
 }
 function listPlugins(deps) {
+    const userEntries = collectUserEntries(deps);
+    const builtins = (deps.builtinEntries?.() ?? []).map((e) => ({ ...e, builtin: true }));
+    const userKeys = new Set(userEntries.map((e) => `${e.type}/${e.name}`));
+    const configDisabled = deps.configDisabledUsage?.() ?? new Set();
+    for (const b of builtins) {
+        if (userKeys.has(`${b.type}/${b.name}`))
+            b.overridden = true;
+        if (b.type === 'usage' && configDisabled.has(b.name) && b.status === 'enabled')
+            b.status = 'config-disabled';
+    }
+    return [...builtins, ...userEntries];
+}
+function collectUserEntries(deps) {
     const entries = [];
     for (const type of PLUGIN_TYPES) {
         const dir = deps.dirs[type];
@@ -130,24 +146,52 @@ function listPlugins(deps) {
     }
     return entries;
 }
-function decodeContent(contentBase64, maxBytes) {
-    if (typeof contentBase64 !== 'string' || contentBase64.length === 0)
-        throw new HubError(400, 'empty content');
-    const buf = Buffer.from(contentBase64, 'base64');
-    if (buf.length === 0)
-        throw new HubError(400, 'empty content');
-    // round-trip check rejects non-base64 garbage
-    if (buf.toString('base64') !== contentBase64)
-        throw new HubError(400, 'content is not valid base64');
-    if (buf.length > maxBytes)
-        throw new HubError(413, `content exceeds ${maxBytes} bytes`);
-    return buf;
+function cleanupExamples(deps) {
+    const removed = [];
+    const failed = [];
+    for (const dir of Object.values(deps.dirs)) {
+        const target = path.join(dir, 'example.js.disabled');
+        try {
+            if (fs.existsSync(target)) {
+                fs.unlinkSync(target);
+                removed.push(target);
+            }
+        }
+        catch {
+            failed.push(target);
+        }
+    }
+    return { removed, failed };
 }
 async function installPlugin(deps, input) {
-    const type = parseType(input.type);
     const filename = validateFilename(input.filename);
     if (!filename.endsWith('.js'))
         throw new HubError(400, `install filename must end with .js: ${filename}`);
+    const maxBytes = deps.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (!Buffer.isBuffer(input.bytes) || input.bytes.length === 0)
+        throw new HubError(400, 'empty content');
+    if (input.bytes.length > maxBytes)
+        throw new HubError(413, `content exceeds ${maxBytes} bytes`);
+    const explicitType = input.type ? parseType(input.type) : undefined;
+    const { matches, mod } = inspectPlugin(filename, input.bytes);
+    validateName(mod, filename);
+    let type;
+    if (matches.length === 0)
+        throw new HubError(400, 'unrecognized plugin interface: export createRuntime / createPrompt / fetch / tools');
+    if (explicitType) {
+        if (!matches.includes(explicitType)) {
+            const listing = matches.map((m) => `${m} (${MATCH_IFACE[m]})`).join('/');
+            throw new HubError(400, `plugin interface mismatch: selected ${explicitType}, exports ${listing}`);
+        }
+        type = explicitType;
+    }
+    else {
+        if (matches.length > 1)
+            throw new HubError(400, `ambiguous plugin interface: ${matches.join('/')}`);
+        type = matches[0];
+    }
+    if (type === 'media')
+        await validateMediaActivation(mod);
     const dir = deps.dirs[type];
     fs.mkdirSync(dir, { recursive: true });
     const target = resolveInDir(dir, filename);
@@ -156,23 +200,113 @@ async function installPlugin(deps, input) {
     if (!input.overwrite && (fs.existsSync(dup) || fs.existsSync(dupDisabled))) {
         throw new HubError(409, `plugin already exists: ${filename}`);
     }
-    const buf = decodeContent(input.contentBase64, deps.maxBytes ?? DEFAULT_MAX_BYTES);
     const tmp = `${target}.tmp`;
-    fs.writeFileSync(tmp, buf);
+    fs.writeFileSync(tmp, input.bytes);
     fs.renameSync(tmp, target);
     await deps.reload?.(type);
     return statEntry(type, dir, filename);
 }
+const MATCH_IFACE = {
+    runtime: 'createRuntime',
+    media: 'createPrompt',
+    usage: 'fetch',
+    ui: 'tools',
+};
+function computeMatches(mod) {
+    const matches = [];
+    if (typeof mod?.createRuntime === 'function')
+        matches.push('runtime');
+    if (typeof mod?.createPrompt === 'function' || typeof mod?.fixPayload === 'function'
+        || typeof mod?.engine === 'string' || Array.isArray(mod?.modalities))
+        matches.push('media');
+    if (typeof mod?.fetch === 'function'
+        && (mod.type === undefined || mod.type === 'api' || mod.type === 'token-plan' || mod.type === 'local'))
+        matches.push('usage');
+    if (mod?.tools && typeof mod.tools === 'object' && Object.keys(mod.tools).length > 0)
+        matches.push('ui');
+    return matches;
+}
+function inspectPlugin(filename, bytes) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mafw-hub-sniff-'));
+    const tmpFile = path.join(tmpDir, filename);
+    try {
+        fs.writeFileSync(tmpFile, bytes);
+        try {
+            delete require.cache[require.resolve(tmpFile)];
+        }
+        catch { /* first load */ }
+        let mod;
+        try {
+            mod = require(tmpFile);
+        }
+        catch (err) {
+            throw new HubError(400, `plugin failed to load: ${err.message}`);
+        }
+        return { matches: computeMatches(mod), mod };
+    }
+    finally {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+function validateName(mod, filename) {
+    const name = mod?.name;
+    if (typeof name !== 'string' || name.length === 0)
+        throw new HubError(400, 'missing plugin name');
+    const stem = baseName(filename);
+    if (name !== stem) {
+        throw new HubError(400, `plugin name mismatch: exports '${name}', filename '${filename}' (must match)`);
+    }
+}
+const VALID_MODALITIES = new Set(['image', 'video', 'audio']);
+const STUB_MEDIA_CTX = {
+    apiKey: () => null,
+    fetch: (url, opts) => fetch(url, opts),
+    pluginConfig: () => null,
+    log: logger_1.log,
+};
+async function validateMediaActivation(mod) {
+    const modalities = mod?.modalities;
+    if (!Array.isArray(modalities) || modalities.length === 0
+        || !modalities.every((m) => VALID_MODALITIES.has(m))) {
+        throw new HubError(400, 'invalid modalities');
+    }
+    const hasCreatePrompt = typeof mod?.createPrompt === 'function';
+    const hasPiEngine = mod?.engine === 'pi';
+    if (!hasCreatePrompt && !hasPiEngine)
+        throw new HubError(400, 'missing createPrompt() or engine:"pi"');
+    if (hasCreatePrompt && hasPiEngine)
+        throw new HubError(400, 'createPrompt and engine:"pi" are mutually exclusive');
+    if (hasCreatePrompt) {
+        const fn = await mod.createPrompt(STUB_MEDIA_CTX);
+        if (typeof fn !== 'function')
+            throw new HubError(400, 'createPrompt did not return a function');
+    }
+}
 async function setPluginEnabled(deps, input) {
     const type = parseType(input.type);
     const filename = validateFilename(input.filename);
     const dir = deps.dirs[type];
-    const current = resolveInDir(dir, filename);
-    if (!fs.existsSync(current))
+    // Accept either on-disk state: a stale client snapshot (double-toggled
+    // switch, unrefreshed list) sends the opposite-state filename, which must
+    // resolve idempotently instead of 404ing ("激活 not found").
+    const primary = resolveInDir(dir, filename);
+    const variant = /\.js\.disabled$/.test(filename)
+        ? filename.replace(/\.js\.disabled$/, '.js')
+        : filename.replace(/\.js$/, '.js.disabled');
+    const variantPath = resolveInDir(dir, variant);
+    const current = fs.existsSync(primary) ? primary : fs.existsSync(variantPath) ? variantPath : null;
+    if (!current)
         throw new HubError(404, `plugin file not found: ${filename}`);
-    const nextName = input.enabled ? filename.replace(/\.js\.disabled$/, '.js') : filename.replace(/\.js$/, '.js.disabled');
+    const currentName = path.basename(current);
+    const nextName = input.enabled
+        ? currentName.replace(/\.js\.disabled$/, '.js')
+        : currentName.replace(/\.js$/, '.js.disabled');
     const next = resolveInDir(dir, nextName);
-    fs.renameSync(current, next);
+    if (next !== current)
+        fs.renameSync(current, next);
     await deps.reload?.(type);
     return statEntry(type, dir, nextName);
 }

package/gateway/dist/routes/plugins.js

@@ -15,6 +15,14 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
+function readBodyBuffer(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
 async function readJsonBody(req) {
     const raw = await readBody(req);
     try {
@@ -47,11 +55,13 @@ async function handlePluginsList(_req, res, deps) {
 }
 async function handlePluginsInstall(req, res, deps) {
     await guarded(res, async () => {
-        const body = await readJsonBody(req);
-        const entry = await (0, hub_1.installPlugin)(deps.hub, {
-            type: body.type, filename: body.filename, contentBase64: body.contentBase64, overwrite: !!body.overwrite,
-        });
-        logger_1.log.info(`[PluginsHub] installed ${body.type}/${body.filename}`);
+        const url = new URL(req.url || '/', 'http://localhost');
+        const filename = url.searchParams.get('filename') || '';
+        const type = (url.searchParams.get('type') || undefined);
+        const overwrite = url.searchParams.get('overwrite') === '1' || url.searchParams.get('overwrite') === 'true';
+        const bytes = await readBodyBuffer(req);
+        const entry = await (0, hub_1.installPlugin)(deps.hub, { filename, type, bytes, overwrite });
+        logger_1.log.info(`[PluginsHub] installed ${entry.type}/${filename}`);
         return entry;
     });
 }

package/gateway/dist/runtime/event-broadcast.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Mode A 全局广播信封构造器（MafwScheduler.broadcast 的载荷形状）。
+ *
+ * wire 契约（桌面 renderer / TUI 均按此解析）：
+ *   { type: 'opencode_event', data: { type, properties?, sessionID?, directory?, error?, internal? } }
+ *
+ * 规则：可选字段缺失时不得出现在 data 上（key 稳定性，消费方用
+ * `'x' in data` 判定时不受缺省值污染）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.opencodeBroadcast = opencodeBroadcast;
+exports.projectRegisteredEvent = projectRegisteredEvent;
+function opencodeBroadcast(data, internal) {
+    return {
+        type: 'opencode_event',
+        data: {
+            ...data,
+            ...(data.directory === undefined ? {} : { directory: data.directory }),
+            ...(internal ? { internal: true } : {}),
+        },
+    };
+}
+/**
+ * 项目注册广播（桌面 renderer 依此刷新 Rail 项目列表）。
+ *
+ * 顶层广播必须扁平（无 `data` 键）：desktop 剥壳逻辑 `event = raw?.data || raw`
+ * 会把 `data` 当作 opencode_event 的内层载荷，`type` 随之丢失——与
+ * runtime_switched / user_question 同一约定。
+ */
+function projectRegisteredEvent(projectDir) {
+    return { type: 'project_registered', projectDir };
+}

package/gateway/dist/runtime/loader.js

@@ -69,7 +69,6 @@ class RuntimePluginLoader {
         if (!fs.existsSync(this.pluginsDir)) {
             fs.mkdirSync(this.pluginsDir, { recursive: true });
             fs.writeFileSync(path.join(this.pluginsDir, 'README.md'), README_CONTENT);
-            fs.writeFileSync(path.join(this.pluginsDir, 'example.js.disabled'), EXAMPLE_CONTENT);
             logger_1.log.info(`[RuntimePluginLoader] Created ${this.pluginsDir}`);
         }
     }
@@ -90,6 +89,10 @@ class RuntimePluginLoader {
                     this.factories.delete(prev.name);
                     this.meta.delete(prev.name);
                 }
+                if (prev?.alias) {
+                    this.factories.delete(prev.alias);
+                    this.meta.delete(prev.alias);
+                }
                 this.state.delete(file);
             }
         }
@@ -123,9 +126,22 @@ class RuntimePluginLoader {
             const external = mod.external !== false;
             this.factories.set(name, mod.createRuntime);
             this.meta.set(name, { capabilities, external });
-            this.state.set(file, { file, name, status: 'ok', capabilities });
             loadedNames.add(name);
-            logger_1.log.info(`[RuntimePluginLoader] Loaded ${file} (${name})`);
+            // Filename-stem alias: the plugin hub addresses runtime plugins by
+            // filename stem (statEntry baseName) while switch/createRuntime
+            // validate by module.exports.name — register both so hub "激活" works
+            // regardless of the declared name. The real module name always wins
+            // (unconditional set above overwrites an earlier stem alias), and an
+            // alias never shadows a builtin.
+            const stem = file.replace(/\.js$/, '');
+            let alias;
+            if (stem !== name && !this.factories.has(stem) && !this.builtins.has(stem)) {
+                this.factories.set(stem, mod.createRuntime);
+                this.meta.set(stem, { capabilities, external });
+                alias = stem;
+            }
+            this.state.set(file, { file, name, status: 'ok', capabilities, alias });
+            logger_1.log.info(`[RuntimePluginLoader] Loaded ${file} (${name})${alias ? ` [alias: ${alias}]` : ''}`);
         }
         catch (err) {
             const prev = this.state.get(file);
@@ -144,6 +160,10 @@ class RuntimePluginLoader {
             return { createRuntime: builtin.factory, ...builtin };
         return undefined;
     }
+    /** 已注册内置件名（builtin 文件件不在其中，opencode 为恒等默认由 index.ts 注入 hub）。 */
+    getBuiltinNames() {
+        return [...this.builtins.keys()];
+    }
     getState() {
         for (const [name, b] of this.builtins) {
             this.state.set(`builtin:${name}`, { file: `builtin:${name}`, name, status: 'ok', capabilities: b.capabilities });
@@ -228,13 +248,3 @@ Capabilities declared here gate gateway features declaratively: missing
 capabilities disable the corresponding features (503 on gated endpoints,
 skipped event subscription) — they never crash.
 `;
-const EXAMPLE_CONTENT = `// Rename to example.js to activate
-module.exports = {
-  name: "example",
-  capabilities: { eventStream: false },
-  async createRuntime(ctx) {
-    ctx.log.info("[example-runtime] created");
-    throw new Error("example plugin: implement createRuntime before activating");
-  },
-};
-`;