sap-extension-creator

name sap-extension-creator description Create Super Agent Party (SAP) extensions. This skill should be used when users want to create, build, or scaffold a new extension for Super Agent Party - including static HTML extensions (pure frontend) and Node.js backend extensions. Triggers on requests like "create a new SAP extension", "build an extension for Super Agent Party", "scaffold a plugin", "make a chat UI extension", or when working with sap extension projects. SAP Extension Creator Overview Create Super Agent Party extensions—self-contained packages that extend the platform with custom chat UI and tools. Two modes are supported: Static extension : Pure HTML/CSS/JS frontend, served directly by SAP from the extension folder Node.js extension : Full-stack with Express backend, auto-managed by SAP ( npm install + node index.js <port> ) Both modes support MCP tool registration (the register_node_extension_mcp protocol message works for ANY extension via WebSocket, despite the "node" in its name). Quick Decision Tree User wants to create an extension? ├─ Only needs UI (chat, display, simple interactions)? → Static Extension └─ Needs backend logic (API calls, DB, file processing)? → Node.js Extension Core Files Every Extension Needs File Required Purpose package.json ✅ Metadata, dependencies, window config index.html ✅ Main UI (full HTML page, single-file app) index.js Node only Node.js entry point node_modules/ Node only Auto-installed by SAP via npm install Workflow Step 1: Gather Requirements Ask the user: Extension name? (hyphen-case, e.g., my-weather-widget ) Description? (one sentence) Static or Node.js? (Node.js only if backend logic/server-side code is needed) For Node.js: what npm dependencies? Should it register custom tools for the AI? (works in both static and Node.js modes via WebSocket MCP) GitHub repository URL? (optional, for updates) Transparent window? (frameless, always-on-top — for mini widgets like music controllers) Default window size? (width/height in pixels) Step 2: Scaffold the Extension Use the templates in assets/ as starting points: Static : Copy assets/static-template/ Node.js : Copy assets/node-template/ Create the extension directory under the workspace (user will later install it into SAP's extensions/ folder). Step 3: Write package.json See references/package-json-spec.md for the complete field reference. Minimum: { "name" : "my-extension" , "version" : "1.0.0" , "description" : "What it does" , "author" : "your-name" , "repository" : "https://github.com/user/repo" , "backupRepository" : "https://gitee.com/user/repo" , "category" : "Tools" } For Node.js extensions, also include: { "main" : "index.js" , "nodePort" : 0 , "dependencies" : { "express" : "^5.1.0" } } For transparent/frameless widgets (e.g., mini music controllers, floating panels): { "transparent" : true , "width" : 280 , "height" : 80 } When transparent: true , SAP creates a frameless, transparent, always-on-top window (see main.js open-extension-window handler). Use this for compact overlay widgets. Step 4: Write index.html The HTML page is rendered inside an Electron BrowserWindow (either directly or via an iframe). Key patterns: Self-contained : The extension is a single HTML file with all CSS/JS inlined or loaded from CDN. For Node.js extensions, static assets are served from the extension directory. Font Awesome : Use CDN to ensure reliable loading in both static and Node.js modes: < link rel = "stylesheet" href = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css" > Avoid relative paths like ../../fontawesome/ — these may work for static extensions but break for Node.js extensions (different serving paths). Dark/Light mode : Always support both (see "Theme & i18n" section below). i18n (Chinese/English) : Always support bilingual UI (see "Theme & i18n" section below). WebSocket connection : Connect to ws://host/ws for messaging and MCP. Extension ID : Parse window.location.pathname for /extensions/{ext_id}/ . Message rendering : Listen for messages_update and broadcast_messages events. Send user input : Send set_user_input then trigger_send_message . Step 5: Write index.js (Node.js only) See references/node-entry-spec.md for the full protocol. The entry point: Receives a port number via process.argv[2] Starts an Express server on that port at 127.0.0.1 Serves static files from its own directory Exposes a /health endpoint for readiness checks SAP reverse-proxies requests to the extension Step 6: Implement Tool Registration (optional, works in both modes) Extensions can register tools that the AI agent can call — via WebSocket in the frontend (both static and Node.js). The MCP lifecycle has three mandatory stages: STARTUP → ws.onopen → registerMcpTools() RUNTIME → ws.onmessage → handleMcpCall() when AI calls a tool SHUTDOWN → window.beforeunload → unregisterMcpTools() ① Register on startup — always in ws.onopen , using a dedicated function: function registerMcpTools ( ) { getExtId (); ws. send ( JSON . stringify ({ type : 'register_node_extension_mcp' , data : { ext_id : MY_EXT_ID , tools : [{ name : ` ${MY_EXT_ID} _my_tool` , description : 'What this tool does (use the user\'s language)' , parameters : { type : 'object' , properties : { param1 : { type : 'string' , description : '...' } }, required : [ 'param1' ] } }] } })); } ② Handle tool calls — the AI agent calls your tool: async function handleMcpCall ( data ) { const { ext_id, tool_name, tool_params, call_id } = data; if (ext_id !== MY_EXT_ID && !tool_name. includes ( MY_EXT_ID )) return ; // ... execute logic, then: ws. send ( JSON . stringify ({ type : 'mcp_tool_result' , data : { call_id, result : 'output' } })); } ③ Unregister on shutdown — MUST send unregister_node_extension_mcp before the window closes: function unregisterMcpTools ( ) { if (ws && ws. readyState === WebSocket . OPEN ) { ws. send ( JSON . stringify ({ type : 'unregister_node_extension_mcp' , data : { ext_id : MY_EXT_ID } })); } } window . addEventListener ( 'beforeunload' , () => { unregisterMcpTools (); }); Key rule : Registration and unregistration MUST be in separate named functions ( registerMcpTools / unregisterMcpTools ), NOT inline code. This makes the lifecycle explicit and easy for AI to understand. If an extension has no MCP tools, all three functions can be deleted. See sap-lx-music/index.html for a complete real-world MCP implementation example (static extension with 12+ registered tools). Theme & i18n (Dark/Light Mode + Bilingual) Every extension should support dark/light mode and Chinese/English bilingual UI. Do NOT hardcode a single theme color scheme — use CSS variables so each extension can have its own identity. CSS Variable Pattern Define light theme in :root and override in body.dark : :root { --bg : #ffffff ; --bg-secondary : #f5f5f5 ; --text : #333333 ; --text-sub : #888888 ; --accent : #ec4141 ; /* extension's own brand color */ --accent-hover : #d73a3a ; --border : rgba ( 0 , 0 , 0 , 0.08 ); --transition : 0.3s cubic-bezier ( 0.25 , 0.1 , 0.25 , 1 ); --font : -apple-system, BlinkMacSystemFont, "SF Pro Display" , "Helvetica Neue" , sans-serif; } body .dark { --bg : #2b2b2b ; --bg-secondary : #222222 ; --text : #e0e0e0 ; --text-sub : #888888 ; --border : rgba ( 255 , 255 , 255 , 0.06 ); } * { box-sizing : border-box; margin : 0 ; padding : 0 ; } html , body { height : 100% ; font-family : var (--font); background : var (--bg); color : var (--text); transition : background var (--transition); } Dark Mode Toggle function initTheme ( ) { const saved = localStorage . getItem ( 'myext_dark' ); if (saved === 'dark' || (!saved && matchMedia ( '(prefers-color-scheme:dark)' ). matches )) { document . body . classList . add ( 'dark' ); } } function toggleDarkMode ( ) { const isDark = document . body . classList . toggle ( 'dark' ); localStorage . setItem ( 'myext_dark' , isDark ? 'dark' : 'light' ); } i18n Pattern const i18n = { zh : { welcome : '欢迎使用我的扩展' , send : '发送' , // ... all UI strings }, en : { welcome : 'Welcome to My Extension' , send : 'Send' , // ... } }; let lang = localStorage . getItem ( 'myext_lang' ) || 'zh' ; function t ( k ) { return i18n[lang]?.[k] || i18n. zh [k] || k; } function toggleLanguage ( ) { lang = lang === 'zh' ? 'en' : 'zh' ; localStorage . setItem ( 'myext_lang' , lang); updateAllTexts (); // re-render all i18n-dependent UI } When registering MCP tools, set description and parameters in the current user's language for better AI interaction. Responsive Design Every extension should work well across different window sizes. Critical patterns: Viewport Meta (REQUIRED) < meta name = "viewport" content = "width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" /> CSS Media Queries Use breakpoints to adapt layout at small sizes: @media ( max-width : 900px ) { /* stack layouts vertically, reduce padding */ } @media ( max-width : 600px ) { /* hide secondary elements, compact controls */ } Key responsive practices: Use vw units for widths as fallback (e.g., width: 65vw; max-width: 360px ) Use flex layouts with flex-wrap that naturally adapt Hide non-essential elements on small screens ( display: none ) Reduce font sizes and padding at breakpoints iframe Compatibility Extensions may be rendered inside an iframe (depending on SAP's configuration). Ensure: Extension ID detection : Use window.location.pathname (works in both direct and iframe contexts): function getExtId ( ) { try { const match = window . location . pathname . match ( /\/extensions\/([^\/]+)/ ); return match ? match[ 1 ] : 'unknown' ; } catch (e) { return 'unknown' ; } } WebSocket connection : Use location.host (not hardcoded): const proto = location. protocol === 'https:' ? 'wss:' : 'ws:' ; ws = new WebSocket ( ` ${proto} // ${location.host} /ws` ); Window close : window.close() works in both direct and iframe contexts Avoid window.top / window.parent assumptions — your extension may be the top-level window Font Awesome via CDN ensures icons load regardless of serving path Transparent Window / Compact Mode When transparent: true is set in package.json, SAP creates a frameless transparent window. The extension must implement compact mode to work correctly. How SAP Creates Transparent Windows From main.js , when extension.transparent is true: { frame : false , transparent : true , alwaysOnTop : true , skipTaskbar : false , hasShadow : false , backgroundColor : 'rgba(0, 0, 0, 0)' , } Compact Mode CSS (REQUIRED for transparent extensions) /* Transparent backgrounds */ body .compact { background : transparent !important ; } html .compact { background : transparent !important ; } /* Drag regions — make structural elements draggable for frameless windows */ body .compact header ,