openlearn-next 0.3.10 → 0.3.13

package/dist/server.cjs

@@ -805,6 +805,207 @@ var init_config_service = __esm({
   }
 });
 
+// packages/core/plugin-host/http-router.ts
+function compileRoutePattern(pattern) {
+  const normalized = pattern.startsWith("/") ? pattern : "/" + pattern;
+  const paramNames = [];
+  const regexStr = normalized.replace(/:([a-zA-Z0-9_]+)/g, (_match, paramName) => {
+    paramNames.push(paramName);
+    return "([^/]+)";
+  }).replace(/\*/g, () => {
+    paramNames.push("wildcard");
+    return "(.*)";
+  });
+  return {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames
+  };
+}
+var PluginHttpRouter;
+var init_http_router = __esm({
+  "packages/core/plugin-host/http-router.ts"() {
+    PluginHttpRouter = class {
+      constructor() {
+        this.routes = [];
+      }
+      /**
+       * 注册指定动词与路径的 Handler
+       */
+      route(method, path20, handler) {
+        const upperMethod = method.toUpperCase();
+        const normalized = path20.startsWith("/") ? path20 : "/" + path20;
+        const { regex, paramNames } = compileRoutePattern(normalized);
+        this.routes.push({
+          method: upperMethod,
+          pattern: normalized,
+          regex,
+          paramNames,
+          handler,
+          isStream: false
+        });
+      }
+      get(path20, handler) {
+        this.route("GET", path20, handler);
+      }
+      post(path20, handler) {
+        this.route("POST", path20, handler);
+      }
+      put(path20, handler) {
+        this.route("PUT", path20, handler);
+      }
+      patch(path20, handler) {
+        this.route("PATCH", path20, handler);
+      }
+      delete(path20, handler) {
+        this.route("DELETE", path20, handler);
+      }
+      stream(methodOrPath, pathOrHandler, maybeHandler) {
+        if (typeof pathOrHandler === "function") {
+          const path20 = methodOrPath;
+          const handler = pathOrHandler;
+          this.registerStream("GET", path20, handler);
+          this.registerStream("POST", path20, handler);
+        } else {
+          const method = methodOrPath.toUpperCase();
+          const path20 = pathOrHandler;
+          const handler = maybeHandler;
+          this.registerStream(method, path20, handler);
+        }
+      }
+      registerStream(method, path20, handler) {
+        const normalized = path20.startsWith("/") ? path20 : "/" + path20;
+        const { regex, paramNames } = compileRoutePattern(normalized);
+        this.routes.push({
+          method: method.toUpperCase(),
+          pattern: normalized,
+          regex,
+          paramNames,
+          streamHandler: handler,
+          isStream: true
+        });
+      }
+      /**
+       * 检查指定动词与路径是否为流式路由
+       */
+      isStream(method, path20) {
+        const upperMethod = method.toUpperCase();
+        const normalized = path20.startsWith("/") ? path20 : "/" + path20;
+        for (const entry of this.routes) {
+          if (entry.method !== upperMethod) continue;
+          if (entry.regex.test(normalized)) {
+            return entry.isStream === true;
+          }
+        }
+        return false;
+      }
+      /**
+       * 匹配路由并提取路由参数
+       */
+      match(method, path20) {
+        const upperMethod = method.toUpperCase();
+        const normalized = path20.startsWith("/") ? path20 : "/" + path20;
+        for (const entry of this.routes) {
+          if (entry.method !== upperMethod) continue;
+          const match = normalized.match(entry.regex);
+          if (match) {
+            const params = {};
+            for (let i = 0; i < entry.paramNames.length; i++) {
+              params[entry.paramNames[i]] = decodeURIComponent(match[i + 1] || "");
+            }
+            return {
+              handler: entry.handler,
+              streamHandler: entry.streamHandler,
+              isStream: entry.isStream,
+              params
+            };
+          }
+        }
+        return null;
+      }
+      /**
+       * 执行请求
+       */
+      async handle(req) {
+        const matched = this.match(req.method, req.path);
+        if (!matched) {
+          return {
+            status: 404,
+            body: { error: `Cannot ${req.method} ${req.path}` }
+          };
+        }
+        if (matched.isStream) {
+          return {
+            status: 400,
+            body: { error: `${req.path} is a streaming route, please use SSE or ctx.http.stream` }
+          };
+        }
+        if (!matched.handler) {
+          return {
+            status: 404,
+            body: { error: `Cannot ${req.method} ${req.path}` }
+          };
+        }
+        const requestWithParams = {
+          ...req,
+          params: { ...req.params, ...matched.params }
+        };
+        const rawResult = await matched.handler(requestWithParams);
+        if (rawResult !== null && typeof rawResult === "object" && "body" in rawResult && (typeof rawResult.status === "number" || rawResult.status === void 0)) {
+          const resp = rawResult;
+          return {
+            status: resp.status ?? 200,
+            headers: resp.headers,
+            body: resp.body
+          };
+        }
+        return {
+          status: 200,
+          body: rawResult
+        };
+      }
+      /**
+       * 执行流式请求
+       */
+      async handleStream(req, stream) {
+        const matched = this.match(req.method, req.path);
+        if (!matched || !matched.streamHandler) {
+          stream.error(new Error(`Cannot ${req.method} ${req.path} (Stream route not found)`));
+          stream.end();
+          return;
+        }
+        const requestWithParams = {
+          ...req,
+          params: { ...req.params, ...matched.params }
+        };
+        try {
+          await matched.streamHandler(requestWithParams, stream);
+        } catch (err) {
+          if (!stream.isClosed) {
+            stream.error(err instanceof Error ? err : new Error(String(err)));
+            stream.end();
+          }
+        }
+      }
+      /**
+       * 获取所有已注册的路由元数据（用于调试或内省）
+       */
+      getRegisteredRoutes() {
+        return this.routes.map((r) => ({
+          method: r.method,
+          pattern: r.pattern,
+          isStream: r.isStream
+        }));
+      }
+      /**
+       * 清空所有路由
+       */
+      clear() {
+        this.routes = [];
+      }
+    };
+  }
+});
+
 // server/utils/logger.ts
 function createLogger(component) {
   return logger.child({ component });
@@ -1268,10 +1469,17 @@ async function buildContext(serviceRegistry, tracker, pluginId, manifest, db2, s
       }));
     }
   };
+  const httpRouter = new PluginHttpRouter();
+  tracker.track(pluginId, {
+    dispose: () => {
+      httpRouter.clear();
+    }
+  });
   return {
     services,
     pluginId,
     manifest,
+    http: httpRouter,
     resolve: (token) => {
       if (typeof token === "string") {
         return serviceRegistry.resolveByName(token);
@@ -1316,6 +1524,7 @@ var init_context_builder = __esm({
   "packages/core/plugin-host/context-builder.ts"() {
     init_types();
     init_config_service();
+    init_http_router();
     init_logger();
     init_interfaces();
     init_plugin_namespace();
@@ -1577,8 +1786,11 @@ var init_service_host = __esm({
          *                   emit a warning.
          */
         this.pendingCommandExecutes = /* @__PURE__ */ new Map();
+        this.pendingHttpRequests = /* @__PURE__ */ new Map();
         this.registeredCommandTypes = /* @__PURE__ */ new Set();
         this.registeredActionIds = /* @__PURE__ */ new Set();
+        this.activeStreams = /* @__PURE__ */ new Map();
+        this.registeredRoutes = [];
       }
       // ── Public accessors ───────────────────────────────────────────────────
       /** The plugin actor ID bound to this ServiceHost. */
@@ -1640,6 +1852,76 @@ var init_service_host = __esm({
               }
               break;
             }
+            case "httpResponse": {
+              const rMsg = msg;
+              const pending = this.pendingHttpRequests.get(rMsg.invokeId);
+              if (pending) {
+                this.pendingHttpRequests.delete(rMsg.invokeId);
+                clearTimeout(pending.timer);
+                if (rMsg.error) {
+                  const err = new Error(rMsg.error.message);
+                  err.stack = rMsg.error.stack;
+                  pending.reject(err);
+                } else {
+                  pending.resolve(rMsg.response ?? { status: 200, body: null });
+                }
+              }
+              break;
+            }
+            case "httpStreamChunk": {
+              const cMsg = msg;
+              const active = this.activeStreams.get(cMsg.streamId);
+              if (active) {
+                if (active.firstChunkTimer) {
+                  clearTimeout(active.firstChunkTimer);
+                  active.firstChunkTimer = void 0;
+                }
+                if (active.idleTimer) {
+                  clearTimeout(active.idleTimer);
+                  active.idleTimer = setTimeout(() => {
+                    this.abortStream(cMsg.streamId, "Stream idle timeout (60s)");
+                    active.stream.error(new Error("Stream idle timeout (60s)"));
+                    active.stream.end();
+                  }, 6e4);
+                }
+                const rawData = cMsg.data;
+                const payloadLength = typeof rawData === "string" ? Buffer.byteLength(rawData) : Buffer.byteLength(JSON.stringify(rawData));
+                if (payloadLength > 65536) {
+                  this.abortStream(cMsg.streamId, "Chunk size exceeded 64KB limit");
+                  active.stream.error(new Error("Chunk size exceeded 64KB limit"));
+                  active.stream.end();
+                  break;
+                }
+                active.stream.write(cMsg.data, cMsg.event, cMsg.id);
+              }
+              break;
+            }
+            case "httpStreamEnd": {
+              const eMsg = msg;
+              const active = this.activeStreams.get(eMsg.streamId);
+              if (active) {
+                active.cleanup();
+                this.activeStreams.delete(eMsg.streamId);
+                active.stream.end();
+              }
+              break;
+            }
+            case "httpStreamError": {
+              const errMsg = msg;
+              const active = this.activeStreams.get(errMsg.streamId);
+              if (active) {
+                active.cleanup();
+                this.activeStreams.delete(errMsg.streamId);
+                active.stream.error(new Error(errMsg.error.message));
+                active.stream.end();
+              }
+              break;
+            }
+            case "routesRegistered": {
+              const rMsg = msg;
+              this.registeredRoutes = rMsg.routes || [];
+              break;
+            }
             case "activated":
             case "deactivated":
               break;
@@ -1761,6 +2043,162 @@ var init_service_host = __esm({
           }
           this.registeredActionIds.clear();
         }
+        if (this.pendingHttpRequests.size > 0) {
+          for (const [, pending] of this.pendingHttpRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(`Worker for plugin "${this.pluginActorId}" was terminated`));
+          }
+          this.pendingHttpRequests.clear();
+        }
+        if (this.activeStreams.size > 0) {
+          for (const [streamId, active] of this.activeStreams) {
+            active.cleanup();
+            try {
+              active.transport.postMessage({
+                type: "httpStreamAbort",
+                streamId,
+                reason: `Worker for plugin "${this.pluginActorId}" was terminated`
+              });
+            } catch {
+            }
+            active.stream.end();
+          }
+          this.activeStreams.clear();
+        }
+      }
+      /**
+       * 中止指定的 Worker HTTP 流
+       */
+      abortStream(streamId, reason) {
+        const active = this.activeStreams.get(streamId);
+        if (!active) return;
+        active.cleanup();
+        this.activeStreams.delete(streamId);
+        try {
+          active.transport.postMessage({
+            type: "httpStreamAbort",
+            streamId,
+            reason
+          });
+        } catch {
+        }
+      }
+      /**
+       * 向 Worker 隔离线程派发 HTTP 请求 DTO，并等待响应（带超时守卫）
+       *
+       * @param transport - Worker 通信运输层
+       * @param request - 纯 DTO 请求对象
+       * @param timeoutMs - 超时时间（毫秒，默认 5000ms）
+       */
+      async dispatchHttpRequest(transport, request, timeoutMs = 5e3) {
+        const invokeId = globalThis.crypto.randomUUID();
+        return new Promise((resolve2, reject) => {
+          const timer = setTimeout(() => {
+            if (this.pendingHttpRequests.has(invokeId)) {
+              this.pendingHttpRequests.delete(invokeId);
+              const err = new Error(`Plugin API request timed out after ${timeoutMs}ms`);
+              err.name = "GatewayTimeoutError";
+              reject(err);
+            }
+          }, timeoutMs);
+          this.pendingHttpRequests.set(invokeId, {
+            resolve: (val) => {
+              clearTimeout(timer);
+              resolve2(val);
+            },
+            reject: (err) => {
+              clearTimeout(timer);
+              reject(err);
+            },
+            timer
+          });
+          try {
+            transport.postMessage({
+              type: "httpRequest",
+              invokeId,
+              request
+            });
+          } catch (err) {
+            clearTimeout(timer);
+            this.pendingHttpRequests.delete(invokeId);
+            reject(err);
+          }
+        });
+      }
+      /**
+       * 向 Worker 隔离线程派发 HTTP SSE 流式请求，并桥接流式数据块（带超时看门狗与中断感知）
+       *
+       * @param transport - Worker 通信运输层
+       * @param request - 纯 DTO 请求对象
+       * @param stream - 主线程流式响应写入器
+       * @param maxLifetimeMs - 最大生命周期超时（默认 300,000ms = 5分钟）
+       */
+      async dispatchHttpStream(transport, request, stream, maxLifetimeMs = 3e5) {
+        const streamId = globalThis.crypto.randomUUID();
+        let firstChunkTimer = setTimeout(() => {
+          const active = this.activeStreams.get(streamId);
+          if (active) {
+            this.abortStream(streamId, "First chunk timeout (10s)");
+            stream.error(new Error("First chunk timeout (10s)"));
+            stream.end();
+          }
+        }, 1e4);
+        let idleTimer = setTimeout(() => {
+          const active = this.activeStreams.get(streamId);
+          if (active) {
+            this.abortStream(streamId, "Stream idle timeout (60s)");
+            stream.error(new Error("Stream idle timeout (60s)"));
+            stream.end();
+          }
+        }, 6e4);
+        const lifetimeTimer = setTimeout(() => {
+          const active = this.activeStreams.get(streamId);
+          if (active) {
+            this.abortStream(streamId, `Stream max lifetime exceeded (${Math.round(maxLifetimeMs / 1e3)}s)`);
+            stream.error(new Error(`Stream max lifetime exceeded (${Math.round(maxLifetimeMs / 1e3)}s)`));
+            stream.end();
+          }
+        }, maxLifetimeMs);
+        const cleanup = () => {
+          if (firstChunkTimer) {
+            clearTimeout(firstChunkTimer);
+            firstChunkTimer = void 0;
+          }
+          if (idleTimer) {
+            clearTimeout(idleTimer);
+            idleTimer = void 0;
+          }
+          clearTimeout(lifetimeTimer);
+        };
+        stream.onClose(() => {
+          this.abortStream(streamId, "Client closed connection");
+        });
+        this.activeStreams.set(streamId, {
+          stream,
+          transport,
+          firstChunkTimer,
+          idleTimer,
+          lifetimeTimer,
+          cleanup
+        });
+        try {
+          transport.postMessage({
+            type: "httpStreamStart",
+            streamId,
+            request
+          });
+        } catch (err) {
+          cleanup();
+          this.activeStreams.delete(streamId);
+          stream.error(err);
+          stream.end();
+        }
+      }
+      /**
+       * 获取由 Worker 注册的所有路由（含是否为流式路由）
+       */
+      getRegisteredRoutes() {
+        return this.registeredRoutes;
       }
       // ── Invoke handling (core RPC logic) ───────────────────────────────────
       /**
@@ -2503,10 +2941,153 @@ function createServiceProxies(serviceTokens) {
   return services;
 }
 
+// \u2500\u2500 V5.2: Worker \u7AEF RESTful Router \u2500\u2500
+function compileRoutePattern(pattern) {
+  var normalized = pattern.indexOf('/') === 0 ? pattern : '/' + pattern;
+  var paramNames = [];
+  var regexStr = normalized
+    .replace(/:([a-zA-Z0-9_]+)/g, function(_m, p) {
+      paramNames.push(p);
+      return '([^/]+)';
+    })
+    .replace(/\\*/g, function() {
+      paramNames.push('wildcard');
+      return '(.*)';
+    });
+  return { regex: new RegExp('^' + regexStr + '$'), paramNames: paramNames };
+}
+
+function createPluginHttpRouter() {
+  var routes = [];
+  var routeFn = function(method, path, handler) {
+    var upperMethod = method.toUpperCase();
+    var normalized = path.indexOf('/') === 0 ? path : '/' + path;
+    var compiled = compileRoutePattern(normalized);
+    routes.push({
+      method: upperMethod,
+      pattern: normalized,
+      regex: compiled.regex,
+      paramNames: compiled.paramNames,
+      handler: handler,
+      isStream: false
+    });
+  };
+  var routeStreamFn = function(method, path, handler) {
+    var upperMethod = method.toUpperCase();
+    var normalized = path.indexOf('/') === 0 ? path : '/' + path;
+    var compiled = compileRoutePattern(normalized);
+    routes.push({
+      method: upperMethod,
+      pattern: normalized,
+      regex: compiled.regex,
+      paramNames: compiled.paramNames,
+      streamHandler: handler,
+      isStream: true
+    });
+  };
+
+  return {
+    get: function(path, handler) { routeFn('GET', path, handler); },
+    post: function(path, handler) { routeFn('POST', path, handler); },
+    put: function(path, handler) { routeFn('PUT', path, handler); },
+    patch: function(path, handler) { routeFn('PATCH', path, handler); },
+    delete: function(path, handler) { routeFn('DELETE', path, handler); },
+    route: routeFn,
+    stream: function(methodOrPath, pathOrHandler, maybeHandler) {
+      if (typeof pathOrHandler === 'function') {
+        var path = methodOrPath;
+        var handler = pathOrHandler;
+        routeStreamFn('GET', path, handler);
+        routeStreamFn('POST', path, handler);
+      } else {
+        var method = methodOrPath.toUpperCase();
+        var path = pathOrHandler;
+        var handler = maybeHandler;
+        routeStreamFn(method, path, handler);
+      }
+    },
+    match: function(method, path) {
+      var upperMethod = method.toUpperCase();
+      var normalized = path.indexOf('/') === 0 ? path : '/' + path;
+      for (var i = 0; i < routes.length; i++) {
+        var entry = routes[i];
+        if (entry.method !== upperMethod) continue;
+        var m = normalized.match(entry.regex);
+        if (m) {
+          var params = {};
+          for (var j = 0; j < entry.paramNames.length; j++) {
+            params[entry.paramNames[j]] = decodeURIComponent(m[j + 1] || '');
+          }
+          return {
+            handler: entry.handler,
+            streamHandler: entry.streamHandler,
+            isStream: entry.isStream,
+            params: params
+          };
+        }
+      }
+      return null;
+    },
+    handle: async function(req) {
+      var matched = this.match(req.method, req.path);
+      if (!matched) {
+        return { status: 404, body: { error: 'Cannot ' + req.method + ' ' + req.path } };
+      }
+      if (matched.isStream) {
+        return { status: 400, body: { error: req.path + ' is a streaming route, please use SSE or ctx.http.stream' } };
+      }
+      if (!matched.handler) {
+        return { status: 404, body: { error: 'Cannot ' + req.method + ' ' + req.path } };
+      }
+      var requestWithParams = Object.assign({}, req, {
+        params: Object.assign({}, req.params, matched.params)
+      });
+      var rawResult = await matched.handler(requestWithParams);
+      if (rawResult !== null && typeof rawResult === 'object' && 'body' in rawResult && (typeof rawResult.status === 'number' || rawResult.status === undefined)) {
+        return {
+          status: rawResult.status !== undefined ? rawResult.status : 200,
+          headers: rawResult.headers,
+          body: rawResult.body
+        };
+      }
+      return { status: 200, body: rawResult };
+    },
+    handleStream: async function(req, stream) {
+      var matched = this.match(req.method, req.path);
+      if (!matched || !matched.streamHandler) {
+        stream.error(new Error('Cannot ' + req.method + ' ' + req.path + ' (Stream route not found)'));
+        stream.end();
+        return;
+      }
+      var requestWithParams = Object.assign({}, req, {
+        params: Object.assign({}, req.params, matched.params)
+      });
+      try {
+        await matched.streamHandler(requestWithParams, stream);
+      } catch (err) {
+        if (!stream.isClosed) {
+          stream.error(err instanceof Error ? err : new Error(String(err)));
+          stream.end();
+        }
+      }
+    },
+    getRegisteredRoutes: function() {
+      return routes.map(function(r) {
+        return { method: r.method, pattern: r.pattern, isStream: r.isStream };
+      });
+    },
+    clear: function() {
+      routes = [];
+    }
+  };
+}
+
 // \u2500\u2500 \u5355\u6D88\u606F\u5904\u7406\u5668 \u2500\u2500
 
 var eventBusProxy = null;
 var registeredCommandHandlers = new Map();
+var pluginHttpRouter = createPluginHttpRouter();
+var activeWorkerStreams = new Map();
 
 parentPort.on('message', async function(msg) {
   // 1. \u8F6C\u53D1\u7684\u5E73\u53F0\u4E8B\u4EF6\u5206\u53D1
@@ -2544,6 +3125,117 @@ parentPort.on('message', async function(msg) {
     return;
   }
 
+  // 1c. Intercept HTTP request from host (V5.2)
+  if (msg && msg.type === 'httpRequest') {
+    try {
+      var res = await pluginHttpRouter.handle(msg.request);
+      parentPort.postMessage({
+        type: 'httpResponse',
+        invokeId: msg.invokeId,
+        response: res
+      });
+    } catch (err) {
+      parentPort.postMessage({
+        type: 'httpResponse',
+        invokeId: msg.invokeId,
+        error: {
+          message: (err && err.message) ? err.message : String(err),
+          stack: (err && err.stack) || ''
+        }
+      });
+    }
+    return;
+  }
+
+  // 1d. Intercept HTTP stream start from host (V5.3)
+  if (msg && msg.type === 'httpStreamStart') {
+    var streamId = msg.streamId;
+    var isStreamClosed = false;
+    var closeCallbacks = [];
+
+    var streamWriter = {
+      get isClosed() {
+        return isStreamClosed;
+      },
+      write: function(data, event, id) {
+        if (isStreamClosed) return false;
+        var rawStr = typeof data === 'string' ? data : JSON.stringify(data);
+        if (rawStr.length > 65536) {
+          throw new Error('Chunk size exceeds 64KB limit');
+        }
+        parentPort.postMessage({
+          type: 'httpStreamChunk',
+          streamId: streamId,
+          data: data,
+          event: event,
+          id: id
+        });
+        return true;
+      },
+      end: function() {
+        if (isStreamClosed) return;
+        isStreamClosed = true;
+        activeWorkerStreams.delete(streamId);
+        parentPort.postMessage({
+          type: 'httpStreamEnd',
+          streamId: streamId
+        });
+      },
+      error: function(err) {
+        if (isStreamClosed) return;
+        isStreamClosed = true;
+        activeWorkerStreams.delete(streamId);
+        parentPort.postMessage({
+          type: 'httpStreamError',
+          streamId: streamId,
+          error: {
+            message: (err && err.message) ? err.message : String(err),
+            stack: (err && err.stack) || ''
+          }
+        });
+      },
+      onClose: function(callback) {
+        if (typeof callback === 'function') {
+          if (isStreamClosed) {
+            try { callback(); } catch(e) {}
+          } else {
+            closeCallbacks.push(callback);
+          }
+        }
+      }
+    };
+
+    activeWorkerStreams.set(streamId, {
+      stream: streamWriter,
+      abort: function() {
+        if (isStreamClosed) return;
+        isStreamClosed = true;
+        activeWorkerStreams.delete(streamId);
+        for (var i = 0; i < closeCallbacks.length; i++) {
+          try {
+            closeCallbacks[i]();
+          } catch(e) {
+            console.error('[WorkerStream] Error in onClose callback:', e);
+          }
+        }
+      }
+    });
+
+    pluginHttpRouter.handleStream(msg.request, streamWriter).catch(function(err) {
+      streamWriter.error(err);
+    });
+    return;
+  }
+
+  // 1e. Intercept HTTP stream abort from host (V5.3)
+  if (msg && msg.type === 'httpStreamAbort') {
+    var activeToAbort = activeWorkerStreams.get(msg.streamId);
+    if (activeToAbort) {
+      activeToAbort.abort();
+    }
+    return;
+  }
+
   // 2. RPC \u7ED3\u679C/\u9519\u8BEF\u5206\u53D1\uFF08\u6709 invokeId \u4E14\u5728 pendingCalls \u4E2D\uFF09
   if (msg && msg.invokeId && pendingCalls.has(msg.invokeId)) {
     var pending = pendingCalls.get(msg.invokeId);
@@ -2786,12 +3478,21 @@ parentPort.on('message', async function(msg) {
             }
           }
           throw new Error('Plugin cannot require non-shared module: ' + moduleName);
-        }
+        },
+        http: pluginHttpRouter
       };
 
       // \u8C03\u7528 activate
       await plugin.activate(ctx, msg.prevState);
 
+      // \u4E0A\u62A5\u5DF2\u6CE8\u518C\u8DEF\u7531\u5143\u6570\u636E\u7ED9\u5BBF\u4E3B
+      if (pluginHttpRouter) {
+        parentPort.postMessage({
+          type: 'routesRegistered',
+          routes: pluginHttpRouter.getRegisteredRoutes()
+        });
+      }
+
       parentPort.postMessage({ type: 'activated' });
 
       // 4. \u505C\u7528\u8BF7\u6C42\uFF08\u6FC0\u6D3B\u540E\u6CE8\u518C\uFF0C\u907F\u514D\u7ADE\u4E89\uFF09
@@ -2804,12 +3505,21 @@ parentPort.on('message', async function(msg) {
               state = await plugin.deactivate();
             }
           } finally {
-            // \u6E05\u7406 pending calls \u548C\u4E8B\u4EF6\u4EE3\u7406
+            // \u6E05\u7406 pending calls\u3001\u6D3B\u8DC3\u6D41\u3001\u4E8B\u4EF6\u4EE3\u7406\u4E0E HTTP \u8DEF\u7531
             pendingCalls.clear();
+            if (activeWorkerStreams) {
+              for (var s of activeWorkerStreams.values()) {
+                try { s.abort(); } catch(e) {}
+              }
+              activeWorkerStreams.clear();
+            }
             if (eventBusProxy) {
               eventBusProxy.disposeAll();
               eventBusProxy = null;
             }
+            if (pluginHttpRouter) {
+              pluginHttpRouter.clear();
+            }
             parentPort.postMessage({ type: 'deactivated', state: state });
           }
         }
@@ -3822,6 +4532,20 @@ var deploySchema = import_zod.z.object({
   staticRoute: import_zod.z.string().optional(),
   staticDir: import_zod.z.string().optional()
 }).optional();
+var apiRouteSchema = import_zod.z.object({
+  method: import_zod.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: import_zod.z.string().min(1, { error: "api route path \u4E0D\u80FD\u4E3A\u7A7A" }),
+  auth: import_zod.z.boolean().optional(),
+  roles: import_zod.z.array(import_zod.z.string()).optional(),
+  rateLimit: import_zod.z.object({
+    windowMs: import_zod.z.number().optional(),
+    max: import_zod.z.number().optional()
+  }).optional()
+});
+var apiSchema = import_zod.z.object({
+  baseRoute: import_zod.z.string().optional(),
+  routes: import_zod.z.array(apiRouteSchema).optional()
+}).optional();
 var requiresItemSchema = import_zod.z.string().regex(
   /^@[\w-]+\/[\w-]+:I\w+(?:@[\^~]?\d+\.\d+\.\d+(?:-[\w.]+)?)?$/,
   { message: "requires/optional \u6761\u76EE\u683C\u5F0F\u65E0\u6548\u3002\u9700\u8981 @scope/domain:IServiceName \u6216 @scope/domain:IServiceName@^x.y.z" }
@@ -3851,7 +4575,8 @@ var manifestSchema = import_zod.z.object({
   }).optional(),
   contributes: contributesSchema,
   classroomTools: import_zod.z.array(import_zod.z.unknown()).optional(),
-  deploy: deploySchema
+  deploy: deploySchema,
+  api: apiSchema
 }).passthrough();
 var requiresItemV3Schema = import_zod.z.string().regex(
   /^@[\w-]+\/[\w-]+:I\w+$/,
@@ -8192,6 +8917,7 @@ function compose(middlewares) {
 
 // packages/core/plugin-host/index.ts
 init_types();
+init_http_router();
 
 // packages/core/plugin-host/errors.ts
 var PluginHostError = class extends Error {
@@ -8262,7 +8988,7 @@ var HotReloadActivationError = class extends HotReloadError {
 init_interfaces();
 
 // packages/core/version.ts
-var PLATFORM_VERSION = "0.3.10";
+var PLATFORM_VERSION = "0.3.13";
 var OPENLEARN_VERSION = PLATFORM_VERSION;
 
 // packages/core/plugin-host/plugin-runtime-composition.ts
@@ -8604,6 +9330,7 @@ var PluginDistributionManager = class {
 };
 
 // packages/core/plugin-host/index.ts
+init_http_router();
 var VALID_TRANSITIONS = {
   ["installed" /* INSTALLED */]: ["activating" /* ACTIVATING */, "uninstalled" /* UNINSTALLED */],
   ["activating" /* ACTIVATING */]: ["active" /* ACTIVE */, "error" /* ERROR */],
@@ -8717,6 +9444,125 @@ var PluginHost = class {
   getPluginManifestPath(pluginId) {
     return import_path4.default.join(this.getPluginDir(pluginId), "manifest.json");
   }
+  // ── V5.2: RESTful API Gateway Dispatcher ───────────────────────────────
+  /**
+   * 向插件派发 HTTP 请求（自动路由到 Worker 隔离线程或 Inline 实例）
+   */
+  async dispatchHttpRequest(pluginIdOrManifestId, req, timeoutMs = 5e3) {
+    const resolvedId = this.resolvePluginUuid(pluginIdOrManifestId);
+    const instance = this.pluginInstances.get(resolvedId) ?? this.pluginInstances.get(pluginIdOrManifestId);
+    if (!instance) {
+      const state = this.pluginStates.get(resolvedId) ?? this.pluginStates.get(pluginIdOrManifestId);
+      if (state && state !== "active" /* ACTIVE */) {
+        return {
+          status: 503,
+          body: { error: `Plugin "${pluginIdOrManifestId}" is currently ${state}` }
+        };
+      }
+      return {
+        status: 404,
+        body: { error: `Plugin "${pluginIdOrManifestId}" not found or not active` }
+      };
+    }
+    if (instance.workerRef) {
+      return instance.workerRef.serviceHost.dispatchHttpRequest(
+        instance.workerRef.transport,
+        req,
+        timeoutMs
+      );
+    }
+    if (instance.context?.http) {
+      return instance.context.http.handle(req);
+    }
+    return {
+      status: 404,
+      body: { error: `Plugin "${pluginIdOrManifestId}" has no HTTP router registered` }
+    };
+  }
+  /**
+   * 判断指定插件的某个请求路径是否为流式路由 (SSE)
+   */
+  isStreamRoute(pluginIdOrManifestId, method, path20) {
+    const upperMethod = method.toUpperCase();
+    const resolvedId = this.resolvePluginUuid(pluginIdOrManifestId);
+    const instance = this.pluginInstances.get(resolvedId) ?? this.pluginInstances.get(pluginIdOrManifestId);
+    const manifest = this.getPluginManifest(pluginIdOrManifestId);
+    if (manifest?.api?.routes) {
+      for (const r of manifest.api.routes) {
+        if (r.method.toUpperCase() === upperMethod && r.streaming === true) {
+          const compiled = compileRoutePattern(r.path);
+          if (compiled.regex.test(path20)) {
+            return true;
+          }
+        }
+      }
+    }
+    if (!instance) return false;
+    if (instance.context?.http) {
+      return instance.context.http.isStream(upperMethod, path20);
+    }
+    if (instance.workerRef) {
+      const routes = instance.workerRef.serviceHost.getRegisteredRoutes();
+      for (const r of routes) {
+        if (r.method === upperMethod && r.isStream) {
+          const compiled = compileRoutePattern(r.pattern);
+          if (compiled.regex.test(path20)) {
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+  /**
+   * 向插件派发 HTTP SSE 流式传输请求（自动路由到 Worker 隔离线程或 Inline 实例）
+   */
+  async dispatchHttpStream(pluginIdOrManifestId, req, stream, maxLifetimeMs = 3e5) {
+    const resolvedId = this.resolvePluginUuid(pluginIdOrManifestId);
+    const instance = this.pluginInstances.get(resolvedId) ?? this.pluginInstances.get(pluginIdOrManifestId);
+    if (!instance) {
+      const state = this.pluginStates.get(resolvedId) ?? this.pluginStates.get(pluginIdOrManifestId);
+      if (state && state !== "active" /* ACTIVE */) {
+        stream.error(new Error(`Plugin "${pluginIdOrManifestId}" is currently ${state}`));
+        stream.end();
+        return;
+      }
+      stream.error(new Error(`Plugin "${pluginIdOrManifestId}" not found or not active`));
+      stream.end();
+      return;
+    }
+    if (instance.workerRef) {
+      return instance.workerRef.serviceHost.dispatchHttpStream(
+        instance.workerRef.transport,
+        req,
+        stream,
+        maxLifetimeMs
+      );
+    }
+    if (instance.context?.http) {
+      return instance.context.http.handleStream(req, stream);
+    }
+    stream.error(new Error(`Plugin "${pluginIdOrManifestId}" has no HTTP router registered`));
+    stream.end();
+  }
+  /**
+   * 获取指定插件的 Manifest（支持已激活或 DB 中的插件）
+   */
+  getPluginManifest(pluginIdOrManifestId) {
+    const resolvedId = this.resolvePluginUuid(pluginIdOrManifestId);
+    const instance = this.pluginInstances.get(resolvedId) ?? this.pluginInstances.get(pluginIdOrManifestId);
+    if (instance?.manifest) return instance.manifest;
+    const preloaded = this.preloadedPlugins.get(resolvedId) ?? this.preloadedPlugins.get(pluginIdOrManifestId);
+    if (preloaded?.manifest) return preloaded.manifest;
+    try {
+      const row = this.db.prepare("SELECT manifest FROM plugins WHERE id = ?").get(resolvedId);
+      if (row?.manifest) {
+        return JSON.parse(row.manifest);
+      }
+    } catch {
+    }
+    return null;
+  }
   /**
    * Set the WorkerManager instance (Phase 5).
    * Called by Kernel after both PluginHost and WorkerManager are constructed,
@@ -9296,7 +10142,7 @@ var PluginHost = class {
             )
           ]);
         });
-        this.pluginInstances.set(pluginId, { manifest, activate, deactivate });
+        this.pluginInstances.set(pluginId, { manifest, activate, deactivate, context: ctx });
         this.pluginStates.set(pluginId, "active" /* ACTIVE */);
         this.db.prepare("UPDATE plugins SET status = ? WHERE id = ?").run("active", pluginId);
       } catch (err) {
@@ -9422,7 +10268,8 @@ var PluginHost = class {
         this.pluginInstances.set(pluginId, {
           manifest: mergedManifest,
           activate,
-          deactivate: typeof deactivate === "function" ? deactivate : void 0
+          deactivate: typeof deactivate === "function" ? deactivate : void 0,
+          context: ctx
         });
         this.db.prepare("UPDATE plugins SET status = ? WHERE id = ?").run("active", pluginId);
         if (this._hotReloadController) {
@@ -23889,6 +24736,361 @@ async function checkVersion(source, installedVersion) {
   }
 }
 
+// server/routes/plugin-api-gateway.ts
+var import_node_path3 = __toESM(require("node:path"), 1);
+init_http_router();
+var RESERVED_ACTIONS = /* @__PURE__ */ new Set([
+  "config",
+  "toggle",
+  "contributions",
+  "check-update",
+  "one-click-update"
+]);
+var FORBIDDEN_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
+  "set-cookie",
+  "access-control-allow-origin",
+  "access-control-allow-credentials",
+  "access-control-allow-methods",
+  "access-control-allow-headers",
+  "content-security-policy",
+  "x-frame-options",
+  "transfer-encoding",
+  "connection",
+  "host"
+]);
+var MAX_PAYLOAD_BYTES = 1024 * 1024;
+var PluginRateLimiter = class {
+  constructor() {
+    this.buckets = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 检查并递增计数。返回 true 表示放行，false 表示限流。
+   */
+  consume(key, limit, windowMs) {
+    const now = Date.now();
+    const entry = this.buckets.get(key);
+    if (!entry || now > entry.resetAt) {
+      this.buckets.set(key, { count: 1, resetAt: now + windowMs });
+      return true;
+    }
+    if (entry.count >= limit) {
+      return false;
+    }
+    entry.count += 1;
+    return true;
+  }
+  /**
+   * 清理过期桶
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [k, v] of this.buckets) {
+      if (now > v.resetAt) {
+        this.buckets.delete(k);
+      }
+    }
+  }
+};
+var rateLimiter = new PluginRateLimiter();
+setInterval(() => rateLimiter.cleanup(), 5 * 60 * 1e3).unref();
+var StreamConnectionTracker = class {
+  constructor() {
+    this.ipCounts = /* @__PURE__ */ new Map();
+    this.pluginCounts = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 尝试获取流连接名额
+   */
+  tryAcquire(ip, pluginId, maxIp = 5, maxPlugin = 50) {
+    const curIp = this.ipCounts.get(ip) || 0;
+    if (curIp >= maxIp) {
+      return { success: false, reason: `Too many concurrent stream connections for this IP (max ${maxIp})` };
+    }
+    const curPlugin = this.pluginCounts.get(pluginId) || 0;
+    if (curPlugin >= maxPlugin) {
+      return { success: false, reason: `Too many concurrent stream connections for plugin (max ${maxPlugin})` };
+    }
+    this.ipCounts.set(ip, curIp + 1);
+    this.pluginCounts.set(pluginId, curPlugin + 1);
+    return { success: true };
+  }
+  /**
+   * 释放流连接名额
+   */
+  release(ip, pluginId) {
+    const curIp = this.ipCounts.get(ip) || 0;
+    if (curIp <= 1) {
+      this.ipCounts.delete(ip);
+    } else {
+      this.ipCounts.set(ip, curIp - 1);
+    }
+    const curPlugin = this.pluginCounts.get(pluginId) || 0;
+    if (curPlugin <= 1) {
+      this.pluginCounts.delete(pluginId);
+    } else {
+      this.pluginCounts.set(pluginId, curPlugin - 1);
+    }
+  }
+};
+var streamConnectionTracker = new StreamConnectionTracker();
+function resolveAuthContext(req) {
+  const actorId = getActorId(req);
+  let token = getCookieToken(req);
+  if (!token && req.headers.authorization?.startsWith("Bearer ")) {
+    token = req.headers.authorization.slice(7).trim();
+  }
+  if (!token) {
+    return {
+      actorId,
+      role: "anonymous",
+      isAuthenticated: false
+    };
+  }
+  const session = getValidSession(token);
+  if (!session) {
+    return {
+      actorId: "anonymous",
+      role: "anonymous",
+      isAuthenticated: false
+    };
+  }
+  let userRole = session.subRole || session.role || "anonymous";
+  if (session.username === "admin" || session.userId === "usr_admin" || userRole === "admin") {
+    userRole = "administrator";
+  }
+  return {
+    actorId,
+    userId: session.userId,
+    username: session.username,
+    role: userRole,
+    permissions: session.permissions,
+    isAuthenticated: true
+  };
+}
+async function pluginApiGatewayMiddleware(req, res, next) {
+  const pluginId = req.params.pluginId;
+  const rawSubPath = req.params[0] || "";
+  if (RESERVED_ACTIONS.has(rawSubPath)) {
+    return next();
+  }
+  if (rawSubPath.includes("..") || rawSubPath.toLowerCase().includes("%2e%2e")) {
+    res.status(400).json({ success: false, error: "Path traversal attempt detected" });
+    return;
+  }
+  const normalizedSubPath = import_node_path3.default.posix.normalize("/" + rawSubPath);
+  if (normalizedSubPath.includes("..")) {
+    res.status(400).json({ success: false, error: "Path traversal attempt detected" });
+    return;
+  }
+  const pluginHost = kernelContainer.pluginHost;
+  if (!pluginHost) {
+    res.status(503).json({ success: false, error: "Plugin system is not initialized" });
+    return;
+  }
+  const resolvedUuid = pluginHost.resolvePluginUuid(pluginId);
+  const manifest = pluginHost.getPluginManifest(pluginId);
+  const contentLength = parseInt(req.headers["content-length"] || "0", 10);
+  if (contentLength > MAX_PAYLOAD_BYTES) {
+    res.status(413).json({
+      success: false,
+      error: `Payload too large. Maximum allowed size is ${MAX_PAYLOAD_BYTES / 1024}KB`
+    });
+    return;
+  }
+  const auth = resolveAuthContext(req);
+  const method = req.method.toUpperCase();
+  const manifestRoutes = manifest?.api?.routes || [];
+  let matchedRule;
+  for (const r of manifestRoutes) {
+    if (r.method.toUpperCase() === method) {
+      const compiled = compileRoutePattern(r.path);
+      if (compiled.regex.test(normalizedSubPath)) {
+        matchedRule = r;
+        break;
+      }
+    }
+  }
+  const requiresAuth = matchedRule?.auth !== false;
+  if (requiresAuth && !auth.isAuthenticated) {
+    res.status(401).json({ success: false, error: "Authentication required" });
+    return;
+  }
+  if (matchedRule?.roles && matchedRule.roles.length > 0) {
+    const isSuperAdmin = auth.role === "administrator";
+    const hasRole = matchedRule.roles.includes(auth.role);
+    if (!isSuperAdmin && !hasRole) {
+      res.status(403).json({
+        success: false,
+        error: `Forbidden. Required roles: ${matchedRule.roles.join(", ")}`
+      });
+      return;
+    }
+  }
+  const clientIp = req.ip || req.socket?.remoteAddress || "unknown-ip";
+  const rateLimitKey = `${clientIp}:${resolvedUuid || pluginId}:${method}:${normalizedSubPath}`;
+  const windowMs = matchedRule?.rateLimit?.windowMs ?? 60 * 1e3;
+  const maxRequests = matchedRule?.rateLimit?.max ?? 120;
+  if (!rateLimiter.consume(rateLimitKey, maxRequests, windowMs)) {
+    res.setHeader("Retry-After", Math.ceil(windowMs / 1e3).toString());
+    res.status(429).json({
+      success: false,
+      error: "Too many requests, please slow down"
+    });
+    return;
+  }
+  const safeHeaders = {};
+  const ALLOWED_REQUEST_HEADERS = [
+    "content-type",
+    "accept",
+    "user-agent",
+    "x-request-id",
+    "accept-language"
+  ];
+  for (const h of ALLOWED_REQUEST_HEADERS) {
+    const val = req.headers[h];
+    if (typeof val === "string") {
+      safeHeaders[h] = val;
+    }
+  }
+  const reqDto = {
+    method,
+    path: normalizedSubPath,
+    params: {},
+    // 由 PluginHttpRouter 在内部根据路由模板动态补全
+    query: req.query,
+    headers: safeHeaders,
+    body: req.body,
+    ip: clientIp,
+    actor: {
+      actorId: auth.actorId,
+      userId: auth.userId,
+      username: auth.username,
+      role: auth.role,
+      permissions: auth.permissions
+    }
+  };
+  const isStream = matchedRule?.streaming === true || pluginHost.isStreamRoute(pluginId, method, normalizedSubPath) || req.headers.accept?.includes("text/event-stream") && pluginHost.isStreamRoute(pluginId, method, normalizedSubPath);
+  if (isStream) {
+    const maxIp = matchedRule?.rateLimit?.maxConcurrentStreams ?? 5;
+    const acquireRes = streamConnectionTracker.tryAcquire(clientIp, resolvedUuid || pluginId, maxIp, 50);
+    if (!acquireRes.success) {
+      res.status(429).json({
+        success: false,
+        error: acquireRes.reason
+      });
+      return;
+    }
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no"
+    });
+    res.flushHeaders?.();
+    let streamEnded = false;
+    const closeListeners = /* @__PURE__ */ new Set();
+    const releaseResource = () => {
+      if (!streamEnded) {
+        streamEnded = true;
+        streamConnectionTracker.release(clientIp, resolvedUuid || pluginId);
+      }
+    };
+    res.on("close", () => {
+      releaseResource();
+      for (const cb of closeListeners) {
+        try {
+          cb();
+        } catch (e) {
+          console.error("[PluginApiGateway] Error in stream onClose listener:", e);
+        }
+      }
+    });
+    const streamResponse = {
+      get isClosed() {
+        if (streamEnded || res.writableEnded || res.destroyed) return true;
+        if (res.socket && !res.socket.writable) return true;
+        return false;
+      },
+      write(data, event, id) {
+        if (this.isClosed) return false;
+        let sse = "";
+        if (id) sse += `id: ${id}
+`;
+        if (event) sse += `event: ${event}
+`;
+        const text = typeof data === "object" ? JSON.stringify(data) : String(data);
+        const lines = text.split("\n");
+        for (const line of lines) {
+          sse += `data: ${line}
+`;
+        }
+        sse += "\n";
+        return res.write(sse);
+      },
+      end() {
+        if (streamEnded) return;
+        releaseResource();
+        res.end();
+      },
+      error(err) {
+        if (this.isClosed) return;
+        const msg = err instanceof Error ? err.message : String(err);
+        res.write(`event: error
+data: ${JSON.stringify({ error: msg })}
+
+`);
+        this.end();
+      },
+      onClose(callback) {
+        if (this.isClosed) {
+          try {
+            callback();
+          } catch {
+          }
+        } else {
+          closeListeners.add(callback);
+        }
+      }
+    };
+    try {
+      await pluginHost.dispatchHttpStream(pluginId, reqDto, streamResponse);
+    } catch (err) {
+      console.error(`[PluginApiGateway] Stream dispatch error for ${method} ${req.originalUrl}:`, err);
+      if (!streamResponse.isClosed) {
+        streamResponse.error(err);
+      }
+    }
+    return;
+  }
+  try {
+    const response = await pluginHost.dispatchHttpRequest(
+      pluginId,
+      reqDto,
+      5e3
+    );
+    const status = typeof response.status === "number" && response.status >= 100 && response.status <= 599 ? response.status : 200;
+    if (response.headers && typeof response.headers === "object") {
+      for (const [k, v] of Object.entries(response.headers)) {
+        const lowerKey = k.toLowerCase();
+        if (!FORBIDDEN_RESPONSE_HEADERS.has(lowerKey)) {
+          res.setHeader(k, v);
+        }
+      }
+    }
+    if (res.getHeader("content-type") === void 0) {
+      res.setHeader("content-type", "application/json; charset=utf-8");
+    }
+    res.status(status).send(response.body);
+  } catch (err) {
+    if (err.name === "GatewayTimeoutError" || err.message?.includes("timed out")) {
+      res.status(504).json({ success: false, error: "Gateway Timeout: Plugin did not respond in time" });
+      return;
+    }
+    console.error(`[PluginApiGateway] Error handling ${method} ${req.originalUrl}:`, err);
+    sendSafeError(res, err);
+  }
+}
+
 // server/routes/plugins.ts
 function findLocalPluginSource(manifestId) {
   const root = import_path14.default.resolve(process.cwd(), "v2_plugins");
@@ -24382,6 +25584,7 @@ function registerPluginsRoutes(ctx) {
       sendSafeError(res, err);
     }
   });
+  app.all("/api/plugins/:pluginId/*", pluginApiGatewayMiddleware);
   app.get("/api/ai-providers", requireAuth("teacher", "administrator"), (req, res) => {
     try {
       const providers = kernelContainer.db.prepare("SELECT * FROM ai_providers ORDER BY created_at DESC").all();