neoctl-web 0.1.0

package/plugins/xhs-artifact/xhs-artifact-contract.mjs

@@ -0,0 +1,125 @@
+export const XHS_PAYLOAD_FIELDS = ['title', 'body', 'interaction', 'hashtags', 'images', 'review'];
+export const XHS_IMAGE_FIELDS = ['url', 'caption', 'overlay', 'note'];
+
+export const XHS_ARTIFACT_EDITOR_HINT = `
+【小红书编辑器输出契约】
+当你已经产出一篇完整、可发布的小红书笔记时，必须调用 open_xhs_artifact_editor，不能用普通 Markdown、JSON 代码块或自然语言代替工具调用。
+
+工具参数只能是以下结构，字段名、层级和类型必须完全一致：
+{"payload":{"title":"发布标题","body":"仅发布正文","interaction":"可选互动/活动规则，无则为空字符串","hashtags":["#话题1","#话题2"],"images":[{"url":"真实图片 URL、/api/ 路径或绝对本地路径；尚未生成则为空字符串","caption":"画面内容说明","overlay":"图片上实际显示的文字，无则为空字符串","note":"拍摄/生成/排版备注，无则为空字符串"}],"review":"内部审核备注，无则为空字符串"}}
+
+严格边界：
+1. payload 必须且只能包含 title、body、interaction、hashtags、images、review 六个字段，六个字段都必须提供。
+2. title 只放最终发布标题；body 只放最终发布正文，不能重复 title，不能包含“标题/正文/配图/标签/审核”等章节标题，不能包含话题标签、图片方案、审核意见、JSON 或 Markdown 围栏。
+3. hashtags 必须是字符串数组，每项是一个以 # 开头的话题；话题不能再次写入 body。
+4. images 必须是数组且至少一项。每项必须且只能包含 url、caption、overlay、note 四个字符串字段，不能传字符串、Markdown 图片、旧字段名或嵌套对象。
+5. 已生成/已上传图片：把图片工具返回的真实 URL 或绝对路径原样放入 images[].url。未生成图片：url 必须为 ""，将配图方案写入 caption/note。严禁把提示词、图片描述、文件 id 或 Markdown 图片语法放入 url。
+6. interaction 和 review 没有内容时传 ""，不得省略。不要把工具参数再输出成正文。
+7. 修改已有编辑器前，先调用 read_xhs_artifact 读取最新内容，保留用户编辑，再用相同 artifact_id 和完整 payload 调用 open_xhs_artifact_editor。
+`.trim();
+
+export const XHS_ARTIFACT_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    artifact_id: {
+      type: 'string',
+      description: '已有编辑器 id。仅修改时提供；修改前必须先调用 read_xhs_artifact。',
+    },
+    payload: {
+      type: 'object',
+      description: '完整的小红书编辑器数据。只能使用声明的六个字段，不接受 Markdown、内容块或旧字段名。',
+      properties: {
+        title: {
+          type: 'string',
+          description: '最终发布标题。只放标题，不含正文、封面文案备选、话题或其他章节。',
+        },
+        body: {
+          type: 'string',
+          description: '最终发布正文。不得重复标题，不得含话题、配图方案、审核意见、JSON、Markdown 围栏或“正文”等章节标题。',
+        },
+        interaction: {
+          type: 'string',
+          description: '单独展示的互动文案或活动规则；没有时必须传空字符串。',
+        },
+        hashtags: {
+          type: 'array',
+          description: '话题数组。每项是一个以 # 开头的字符串；不得把话题写入正文。',
+          items: { type: 'string' },
+        },
+        images: {
+          type: 'array',
+          description: '有序配图数组，至少一项。每项只能是 url、caption、overlay、note 四个字符串字段。',
+          items: {
+            type: 'object',
+            properties: {
+              url: {
+                type: 'string',
+                description: '真实 http(s) URL、/api/ URL 或绝对本地图片路径；图片尚未创建时传空字符串。不得放描述或提示词。',
+              },
+              caption: {
+                type: 'string',
+                description: '画面内容说明。不是正文，也不是图片 URL。',
+              },
+              overlay: {
+                type: 'string',
+                description: '图片上实际显示的文字；没有时传空字符串。',
+              },
+              note: {
+                type: 'string',
+                description: '内部拍摄、生成、布局或设计备注；没有时传空字符串。',
+              },
+            },
+            required: XHS_IMAGE_FIELDS,
+            additionalProperties: false,
+          },
+        },
+        review: {
+          type: 'string',
+          description: '内部合规/风格审核备注；没有时必须传空字符串，绝不能写入正文。',
+        },
+      },
+      required: XHS_PAYLOAD_FIELDS,
+      additionalProperties: false,
+    },
+  },
+  required: ['payload'],
+  additionalProperties: false,
+};
+
+export function parseXhsArtifactToolOutput(value) {
+  const parsed = typeof value === 'string' ? parseFirstJsonObject(value) : value;
+  const artifact = parsed?.artifact || parsed?.output?.artifact || parsed?.result?.artifact;
+  return isCompleteXhsArtifact(artifact) ? artifact : null;
+}
+
+export function selectNewestXhsArtifact(current, candidate) {
+  if (!isCompleteXhsArtifact(candidate)) return isCompleteXhsArtifact(current) ? current : null;
+  if (!isCompleteXhsArtifact(current)) return candidate;
+  if (String(current.id) !== String(candidate.id)) return candidate;
+  const currentUpdatedAt = Number(current.updatedAt || current.createdAt || 0);
+  const candidateUpdatedAt = Number(candidate.updatedAt || candidate.createdAt || 0);
+  return candidateUpdatedAt > currentUpdatedAt ? candidate : current;
+}
+
+function isCompleteXhsArtifact(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || !String(value.id || '').trim()) return false;
+  const payload = value.payload;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return false;
+  if (!XHS_PAYLOAD_FIELDS.every((field) => Object.prototype.hasOwnProperty.call(payload, field))) return false;
+  if (typeof payload.title !== 'string' || typeof payload.body !== 'string' || typeof payload.interaction !== 'string' || typeof payload.review !== 'string') return false;
+  if (!payload.title.trim() || !payload.body.trim() || !Array.isArray(payload.hashtags) || !payload.hashtags.every((tag) => typeof tag === 'string')) return false;
+  if (!Array.isArray(payload.images) || !payload.images.length) return false;
+  return payload.images.every((image) => image && typeof image === 'object' && !Array.isArray(image)
+    && XHS_IMAGE_FIELDS.every((field) => typeof image[field] === 'string'));
+}
+
+function parseFirstJsonObject(text) {
+  const raw = String(text || '');
+  const start = raw.indexOf('{');
+  if (start < 0) return null;
+  for (let end = raw.length; end > start; end = raw.lastIndexOf('}', end - 1)) {
+    if (end <= start) break;
+    try { return JSON.parse(raw.slice(start, end + 1)); } catch {}
+  }
+  return null;
+}

package/plugins.mjs

@@ -0,0 +1,111 @@
+function normalizePlugin(plugin) {
+  if (!plugin || typeof plugin !== 'object') throw new Error('web plugin resource must be an object');
+  const id = String(plugin.id || '').trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) throw new Error(`invalid web plugin id: ${id || '(empty)'}`);
+  if (!String(plugin.name || '').trim()) throw new Error(`web plugin ${id} is missing name`);
+  if (!String(plugin.version || '').trim()) throw new Error(`web plugin ${id} is missing version`);
+  if (plugin.route !== undefined && typeof plugin.route !== 'function') throw new Error(`web plugin ${id} route must be a function`);
+  if (plugin.presentToolResult !== undefined && typeof plugin.presentToolResult !== 'function') throw new Error(`web plugin ${id} presentToolResult must be a function`);
+  return {
+    ...plugin,
+    id,
+    name: String(plugin.name).trim(),
+    version: String(plugin.version).trim(),
+    defaultEnabled: plugin.defaultEnabled !== false,
+    tools: Array.isArray(plugin.tools) ? plugin.tools : [],
+    promptSections: Array.isArray(plugin.promptSections) ? plugin.promptSections : [],
+  };
+}
+
+export function createWebPluginHost(options = {}) {
+  const catalog = (options.plugins || []).map(normalizePlugin).sort((left, right) => left.id.localeCompare(right.id));
+  const ids = catalog.map((plugin) => plugin.id);
+  if (new Set(ids).size !== ids.length) throw new Error('duplicate web plugin id');
+  const enabledIds = resolveEnabledPluginIds(catalog, options.enabled);
+  const enabled = catalog.filter((plugin) => enabledIds.has(plugin.id));
+  const tools = enabled.flatMap((plugin) => plugin.tools);
+  const toolNames = tools.map((tool) => String(tool?.name || '').trim()).filter(Boolean);
+  if (new Set(toolNames).size !== toolNames.length) throw new Error('duplicate tool name across enabled web plugins');
+
+  return {
+    ids: enabled.map((plugin) => plugin.id),
+    tools,
+    promptSections: enabled.flatMap((plugin) => plugin.promptSections),
+    runtimePlugins(sessionId) {
+      const overrides = options.settings?.sessionOverrides(sessionId) || {};
+      return {
+        externalPlugins: catalog.map((plugin) => ({
+          id: plugin.id,
+          name: plugin.name,
+          version: plugin.version,
+          globallyEnabled: enabledIds.has(plugin.id),
+          tools: plugin.tools,
+          promptSections: plugin.promptSections,
+          presentToolResult: plugin.presentToolResult,
+        })),
+        sessionPluginOverrides: overrides,
+        persistSessionPluginOverrides: (resolvedSessionId, next) => options.settings?.setSessionOverrides(resolvedSessionId, next),
+        resolveSessionPluginOverrides: (resolvedSessionId) => options.settings?.sessionOverrides(resolvedSessionId) || {},
+      };
+    },
+    snapshot() {
+      const configuredIds = new Set(options.settings?.globalEnabledIds() ?? [...enabledIds]);
+      return {
+        items: catalog.map((plugin) => ({
+          id: plugin.id,
+          name: plugin.name,
+          version: plugin.version,
+          enabled: enabledIds.has(plugin.id),
+          configuredEnabled: configuredIds.has(plugin.id),
+          tools: plugin.tools.map((tool) => tool.name),
+        })),
+        restartRequired: true,
+        locked: options.locked === true,
+      };
+    },
+    async route(req, res, url, helpers = {}) {
+      if (req.method === 'GET' && url.pathname === '/api/plugins') {
+        helpers.sendJson?.(res, this.snapshot());
+        return true;
+      }
+      if (req.method === 'POST' && url.pathname === '/api/plugins/global') {
+        if (options.locked) {
+          helpers.sendJson?.(res, { errorCode: 'PLUGINS_LOCKED', error: 'plugins are locked by NEO_WEB_PLUGINS' }, 409);
+          return true;
+        }
+        const body = await helpers.readJsonBody?.(req);
+        const requested = Array.isArray(body?.enabledIds) ? body.enabledIds.map(String) : [];
+        const unknown = requested.filter((id) => !ids.includes(id));
+        if (unknown.length) {
+          helpers.sendJson?.(res, { errorCode: 'PLUGIN_INVALID', error: `unknown web plugin: ${unknown.join(', ')}` }, 400);
+          return true;
+        }
+        await options.settings?.setGlobalEnabled(requested);
+        helpers.sendJson?.(res, { ok: true, enabledIds: [...new Set(requested)].sort(), restartRequired: true });
+        return true;
+      }
+      for (const plugin of enabled) {
+        if (typeof plugin.route === 'function' && await plugin.route(req, res, url, helpers)) return true;
+      }
+      return false;
+    },
+  };
+}
+
+export function resolveEnabledPluginIds(catalog, configured) {
+  const available = new Set(catalog.map((plugin) => plugin.id));
+  if (Array.isArray(configured)) {
+    const requested = configured.map(String);
+    const unknown = requested.filter((id) => !available.has(id));
+    if (unknown.length) throw new Error(`unknown web plugin: ${unknown.join(', ')}`);
+    return new Set(requested);
+  }
+  const raw = configured === undefined || configured === null ? '' : String(configured).trim();
+  if (!raw) return new Set(catalog.filter((plugin) => plugin.defaultEnabled !== false).map((plugin) => plugin.id));
+  if (raw.toLowerCase() === 'none') return new Set();
+  if (raw.toLowerCase() === 'all') return available;
+  const requested = raw.split(',').map((id) => id.trim()).filter(Boolean);
+  const unknown = requested.filter((id) => !available.has(id));
+  if (unknown.length) throw new Error(`unknown web plugin: ${unknown.join(', ')}`);
+  return new Set(requested);
+}

package/runtime-router-cleanup.mjs

@@ -0,0 +1,152 @@
+import { WebRuntimeRouter } from './core-runtime.mjs';
+
+const INSTALL_KEY = Symbol.for('neoctl-web.runtime-router-session-hubs');
+const routerTimers = new WeakMap();
+const routerAccessTimes = new WeakMap();
+
+export function installRuntimeRouterIdleCleanup(options = {}) {
+  const prototype = WebRuntimeRouter.prototype;
+  if (prototype[INSTALL_KEY]) return;
+  prototype[INSTALL_KEY] = true;
+
+  const idleMs = Math.max(60_000, positiveNumber(options.idleMs || process.env.NEO_RUNTIME_IDLE_MS, 15 * 60_000));
+  const maxSessions = Math.max(1, positiveNumber(options.maxSessions || process.env.NEO_RUNTIME_MAX_SESSIONS, 64));
+  const originalGet = prototype.get;
+
+  prototype.get = function getSharedSessionRuntime(scope = {}) {
+    const tabId = normalizeScopeValue(scope.tabId);
+    const sessionId = normalizeScopeValue(scope.sessionId);
+    const key = sessionId ? `session:${sessionId}` : tabId ? `tab:${tabId}` : '__default__';
+    let result = this.repls?.get(key);
+
+    if (!result && sessionId && tabId) {
+      const tabKey = `tab:${tabId}`;
+      const bootstrap = this.repls?.get(tabKey);
+      if (bootstrap) {
+        result = promoteBootstrapRuntime(this, originalGet, bootstrap, tabKey, key, sessionId);
+        this.repls.set(key, result);
+      }
+    }
+
+    if (!result) {
+      result = originalGet.call(this, sessionId ? { sessionId } : tabId ? { tabId } : {});
+    }
+
+    touchRuntime(this, key);
+    scheduleCleanup(this, key, result, idleMs);
+    void enforceSessionLimit(this, maxSessions);
+    return result;
+  };
+}
+
+function promoteBootstrapRuntime(router, originalGet, bootstrap, tabKey, sessionKey, sessionId) {
+  let promoted;
+  promoted = bootstrap.then(async (repl) => {
+    if (runtimeSessionId(repl) === sessionId) {
+      if (router.repls?.get(tabKey) === bootstrap) router.repls.delete(tabKey);
+      clearRuntimeTimer(router, tabKey);
+      clearRuntimeAccessTime(router, tabKey);
+      return repl;
+    }
+
+    if (router.repls?.get(sessionKey) === promoted) router.repls.delete(sessionKey);
+    return originalGet.call(router, { sessionId });
+  });
+  return promoted;
+}
+
+function scheduleCleanup(router, key, replPromise, idleMs) {
+  let timers = routerTimers.get(router);
+  if (!timers) {
+    timers = new Map();
+    routerTimers.set(router, timers);
+  }
+  clearTimeout(timers.get(key));
+  const timer = setTimeout(async () => {
+    timers.delete(key);
+    if (router.repls?.get(key) !== replPromise) return;
+    let repl;
+    try { repl = await replPromise; } catch { return; }
+    if (isRuntimeActive(repl)) {
+      scheduleCleanup(router, key, replPromise, idleMs);
+      return;
+    }
+    router.repls.delete(key);
+    clearRuntimeAccessTime(router, key);
+  }, idleMs);
+  timer.unref?.();
+  timers.set(key, timer);
+}
+
+async function enforceSessionLimit(router, maxSessions) {
+  const entries = [...(router.repls?.entries() || [])]
+    .filter(([key]) => key.startsWith('session:'));
+  if (entries.length <= maxSessions) return;
+
+  const accessTimes = routerAccessTimes.get(router) || new Map();
+  entries.sort(([left], [right]) => (accessTimes.get(left) || 0) - (accessTimes.get(right) || 0));
+  let overflow = entries.length - maxSessions;
+  for (const [key, promise] of entries) {
+    if (overflow <= 0) break;
+    if (router.repls?.get(key) !== promise) continue;
+    let repl;
+    try { repl = await promise; } catch { repl = undefined; }
+    if (repl && isRuntimeActive(repl)) continue;
+    if (router.repls?.get(key) !== promise) continue;
+    router.repls.delete(key);
+    clearRuntimeTimer(router, key);
+    clearRuntimeAccessTime(router, key);
+    overflow -= 1;
+  }
+}
+
+function isRuntimeActive(repl) {
+  return Boolean(
+    repl?.busy
+      || repl?.subscribers?.size > 0
+      || repl?.backgroundSessionRuns?.size > 0
+      || Number(repl?.backgroundTaskCount || 0) > 0
+  );
+}
+
+function runtimeSessionId(repl) {
+  return String(repl?.runtime?.engine?.snapshot?.().session?.sessionId || '').trim();
+}
+
+function touchRuntime(router, key) {
+  let accessTimes = routerAccessTimes.get(router);
+  if (!accessTimes) {
+    accessTimes = new Map();
+    routerAccessTimes.set(router, accessTimes);
+  }
+  accessTimes.set(key, Date.now());
+}
+
+function clearRuntimeTimer(router, key) {
+  const timers = routerTimers.get(router);
+  if (!timers) return;
+  clearTimeout(timers.get(key));
+  timers.delete(key);
+}
+
+function clearRuntimeAccessTime(router, key) {
+  routerAccessTimes.get(router)?.delete(key);
+}
+
+function normalizeScopeValue(value) {
+  const normalized = String(value || '').trim();
+  return normalized || undefined;
+}
+
+function positiveNumber(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function runtimeScopeKey(scope = {}) {
+  const sessionId = normalizeScopeValue(scope.sessionId);
+  if (sessionId) return `session:${sessionId}`;
+  const tabId = normalizeScopeValue(scope.tabId);
+  if (tabId) return `tab:${tabId}`;
+  return '__default__';
+}