ucu-mcp 0.4.3 → 0.5.0

package/dist/src/platform/macos/element.js

@@ -22,6 +22,9 @@ export async function clickElement(elementId, app) {
     ${jxaElementActionHelpers()}
     var elemPath = ${elementIdLiteral};
     var appName = ${appLiteral};
+    // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
+    var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
+    var appNorm = _norm(appName);
     var cached = ${cachedJson};
 
     var elem = resolveElementInApp(elemPath, appName) || resolveElementByFullPath(elemPath);
@@ -88,6 +91,9 @@ export async function typeInElement(elementId, text, app, clearFirst) {
     ${jxaElementActionHelpers()}
     var elemPath = ${elementIdLiteral};
     var appName = ${appLiteral};
+    // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
+    var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
+    var appNorm = _norm(appName);
     var textToType = ${textLiteral};
     var shouldClear = ${clearFirst ? "true" : "false"};
     var cached = ${cachedJson};
@@ -167,6 +173,9 @@ export async function setElementValue(elementId, value, app) {
     ${jxaElementActionHelpers()}
     var elemPath = ${elementIdLiteral};
     var appName = ${appLiteral};
+    // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
+    var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
+    var appNorm = _norm(appName);
     var valueToSet = ${valueLiteral};
     var cached = ${cachedJson};
 
@@ -210,3 +219,249 @@ export async function setElementValue(elementId, value, app) {
         rethrowElementActionError(error, "set_value", elementId);
     }
 }
+export async function findMenuBarExtra(app) {
+    const appLiteral = JSON.stringify(app);
+    // 两阶段 JXA：先遍历 app 自身 menuBarItems（host:"self"），若为空或只有 Apple 菜单，
+    // 再遍历 SystemUIServer.menuBarItems 找第三方托盘 status item（host:"systemuiserver"）。
+    // 纯 LSUIElement 托盘应用的 status item 由 SystemUIServer 进程托管，不在 app 自身进程里。
+    const jxaScript = `
+    var se = Application('System Events');
+    var _result = null;
+    var appName = ${appLiteral};
+    // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
+    var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
+    var appNorm = _norm(appName);
+
+    // 双向 includes 容忍 "CC Switch" vs "cc-switch" 之类长度差异
+    var _matchApp = function(itemNorm) {
+      if (!itemNorm) return false;
+      return itemNorm === appNorm || itemNorm.indexOf(appNorm) !== -1 || appNorm.indexOf(itemNorm) !== -1;
+    };
+
+    var _readItem = function(item, mb, i, host) {
+      var desc = '', nm = '';
+      try { desc = item.description(); } catch(e) {}
+      try { nm = item.name(); } catch(e) {}
+      var pos = [0,0], sz = [0,0];
+      try { pos = item.position(); } catch(e) {}
+      try { sz = item.size(); } catch(e) {}
+      if (sz[0] === 0 && sz[1] === 0) return null;
+      return {menuBar: mb, index: i, name: nm, description: desc, x: pos[0], y: pos[1], width: sz[0], height: sz[1], host: host};
+    };
+
+    try {
+      var procs = se.processes;
+      var p = null;
+      for (var k = 0; k < procs.length; k++) {
+        var pn = '';
+        try { pn = procs[k].name(); } catch(e) {}
+        if (_norm(pn) === appNorm) { p = procs[k]; break; }
+      }
+
+      var items = [];
+
+      // 阶段 1：app 自身 menuBarItems（host:"self"）
+      if (p) {
+        try {
+          var menuBars = p.menuBars();
+          for (var mb = 0; mb < menuBars.length; mb++) {
+            var mbItems;
+            try { mbItems = menuBars[mb].menuBarItems(); } catch(e) { continue; }
+            for (var i = 0; i < mbItems.length; i++) {
+              var rec = _readItem(mbItems[i], mb, i, "self");
+              if (rec) items.push(rec);
+            }
+          }
+        } catch(e) {}
+      }
+
+      // 是否需要阶段 2：app 自身无 item，或仅含 Apple 菜单（index 0 的 app-name 项）
+      var hasNonApple = false;
+      for (var j = 0; j < items.length; j++) {
+        if (_norm(items[j].name) !== "apple") { hasNonApple = true; break; }
+      }
+
+      // 阶段 2：SystemUIServer 托管的第三方托盘 status item（host:"systemuiserver"）
+      // 仅当 app 自身没有可点击的非 Apple 项时才查 SystemUIServer，避免对有窗口的应用产生噪音。
+      if (!hasNonApple) {
+        try {
+          var suiProcs = se.processes.byName("SystemUIServer");
+          if (suiProcs) {
+            var suiBars = suiProcs.menuBars();
+            for (var smb = 0; smb < suiBars.length; smb++) {
+              var suiItems;
+              try { suiItems = suiBars[smb].menuBarItems(); } catch(e) { continue; }
+              for (var si = 0; si < suiItems.length; si++) {
+                var sItem = suiItems[si];
+                var sDesc = '', sNm = '';
+                try { sDesc = sItem.description(); } catch(e) {}
+                try { sNm = sItem.name(); } catch(e) {}
+                // 按 description/name 匹配目标 app（status item 的 description 通常是 app 名）
+                if (_matchApp(_norm(sDesc)) || _matchApp(_norm(sNm))) {
+                  var sRec = _readItem(sItem, smb, si, "systemuiserver");
+                  if (sRec) {
+                    // 保留匹配信号，供 click 二次定位
+                    sRec.name = sNm; sRec.description = sDesc;
+                    items.push(sRec);
+                  }
+                }
+              }
+            }
+          }
+        } catch(e) {
+          // SystemUIServer 不可达（罕见），忽略，继续返回阶段 1 结果
+        }
+      }
+
+      if (!p && items.length === 0) {
+        _result = {error: "process not found: " + appName, items: []};
+      } else {
+        _result = {items: items};
+      }
+    } catch(e) {
+      _result = {error: "menu bar AX read failed: " + String(e.message || e), items: []};
+    }
+    JSON.stringify(_result);
+  `;
+    let out;
+    try {
+        out = execFileSync("osascript", ["-l", "JavaScript", "-e", jxaScript], { encoding: "utf-8", timeout: 15000 }).trim();
+    }
+    catch (error) {
+        rethrowElementActionError(error, "find_menu_bar_extra", app);
+        return []; // unreachable — rethrow throws
+    }
+    const parsed = JSON.parse(out);
+    if (parsed.error) {
+        throw new Error(parsed.error);
+    }
+    return parsed.items;
+}
+export function matchMenuBarExtra(items, selector) {
+    if (items.length === 0)
+        return undefined;
+    let filtered = items;
+    if (selector.description) {
+        const d = selector.description.toLowerCase();
+        filtered = filtered.filter((it) => (it.description || "").toLowerCase().includes(d) || (it.name || "").toLowerCase().includes(d));
+    }
+    else if (selector.name) {
+        const n = selector.name.toLowerCase();
+        filtered = filtered.filter((it) => (it.name || "").toLowerCase().includes(n) || (it.description || "").toLowerCase().includes(n));
+    }
+    else if (selector.index === undefined) {
+        // 无 selector 时排除 Apple 菜单（macOS 每个 app 的 index 0 app-name 项），
+        // 否则 click_menu_bar_extra(app) 不带 selector 会误点 Apple 菜单。
+        // 注意：SystemUIServer 托管的第三方托盘 item 不应被此过滤误删——它们的 name 通常非 "apple"。
+        filtered = filtered.filter((it) => (it.name || "").toLowerCase() !== "apple");
+    }
+    if (selector.index !== undefined) {
+        return filtered[selector.index];
+    }
+    return filtered[0];
+}
+export async function clickMenuBarExtra(app, selector = {}) {
+    const items = await this.findMenuBarExtra(app);
+    const target = matchMenuBarExtra(items, selector);
+    if (!target) {
+        throw new ElementNotFoundError(`menu bar extra not found in ${app} (selector: ${JSON.stringify(selector)}; ${items.length} items scanned)`);
+    }
+    const appLiteral = JSON.stringify(app);
+    const mb = target.menuBar;
+    const idx = target.index;
+    const host = target.host;
+    const tgtNameLiteral = JSON.stringify(target.name || "");
+    const tgtDescLiteral = JSON.stringify(target.description || "");
+    // AXPress，失败则坐标点击中心（与 clickElement 同模式，应对 Tauri 等静默吞）
+    // host==="systemuiserver" 时在 SystemUIServer 进程上重定位（托盘 status item 由它托管），
+    // SystemUIServer.menuBarItems 顺序不稳定，用保存的 name/description 二次匹配定位具体 item。
+    // host==="self" 时按 app 进程的 menuBars()[mb].menuBarItems()[idx] 重定位（稳定）。
+    const resolveItemBlock = host === "systemuiserver"
+        ? `// SystemUIServer 托管的第三方托盘：按 name/description 二次匹配（顺序不稳定）
+      var suiProc = null;
+      try { suiProc = se.processes.byName("SystemUIServer"); } catch(e) {}
+      var item = null;
+      if (suiProc) {
+        var suiBars = suiProc.menuBars();
+        outer: for (var b = 0; b < suiBars.length; b++) {
+          var suiItems;
+          try { suiItems = suiBars[b].menuBarItems(); } catch(e) { continue; }
+          for (var ii = 0; ii < suiItems.length; ii++) {
+            var it = suiItems[ii];
+            var iDesc = '', iNm = '';
+            try { iDesc = it.description(); } catch(e) {}
+            try { iNm = it.name(); } catch(e) {}
+            if (_matchApp(_norm(iDesc)) || _matchApp(_norm(iNm))
+                || _norm(iDesc) === tgtDescNorm || _norm(iNm) === tgtNameNorm) {
+              item = it; break outer;
+            }
+          }
+        }
+      }
+      if (!item) { _result = {success: false, error: "SystemUIServer status item not found for " + appName}; }`
+        : `// app 自身 menu bar：按 menuBar/index 重定位（稳定）
+      if (!p) {
+        _result = {success: false, error: "process not found: " + appName};
+      } else {
+        var item = p.menuBars()[${mb}].menuBarItems()[${idx}];
+      }`;
+    const jxaScript = `
+    var se = Application('System Events');
+    var _result = null;
+    var appName = ${appLiteral};
+    var tgtName = ${tgtNameLiteral};
+    var tgtDesc = ${tgtDescLiteral};
+    // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
+    var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
+    var appNorm = _norm(appName);
+    var tgtNameNorm = _norm(tgtName);
+    var tgtDescNorm = _norm(tgtDesc);
+    var _matchApp = function(itemNorm) {
+      if (!itemNorm) return false;
+      return itemNorm === appNorm || itemNorm.indexOf(appNorm) !== -1 || appNorm.indexOf(itemNorm) !== -1;
+    };
+    try {
+      var procs = se.processes;
+      var p = null;
+      for (var k = 0; k < procs.length; k++) {
+        var pn = '';
+        try { pn = procs[k].name(); } catch(e) {}
+        if (_norm(pn) === appNorm) { p = procs[k]; break; }
+      }
+      ${resolveItemBlock}
+      if (!_result && item) {
+        try {
+          item.actions.AXPress.perform();
+          _result = {success: true, method: "axpress"};
+        } catch(e) {
+          var pos = item.position();
+          var sz = item.size();
+          var cx = pos[0] + sz[0] / 2;
+          var cy = pos[1] + sz[1] / 2;
+          ObjC.import('CoreGraphics');
+          var pt = $.CGPointMake(cx, cy);
+          var down = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
+          $.CGEventPost($.kCGHIDEventTap, down);
+          var up = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
+          $.CGEventPost($.kCGHIDEventTap, up);
+          _result = {success: true, method: "coordinate", x: cx, y: cy};
+        }
+      }
+    } catch(e) {
+      _result = {success: false, error: String(e.message || e)};
+    }
+    JSON.stringify(_result);
+  `;
+    let out;
+    try {
+        out = execFileSync("osascript", ["-l", "JavaScript", "-e", jxaScript], { encoding: "utf-8", timeout: 15000 }).trim();
+    }
+    catch (error) {
+        rethrowElementActionError(error, "click_menu_bar_extra", app);
+        return; // unreachable
+    }
+    const result = JSON.parse(out);
+    if (!result.success) {
+        throw new Error(`click_menu_bar_extra failed in ${app}: ${result.error}`);
+    }
+}

package/dist/src/platform/macos/screen.js

@@ -74,7 +74,7 @@ export async function ocr(display, region) {
         const nativeResult = await ocrNative(tmpPath, scaleFactor, region);
         if (nativeResult)
             return nativeResult;
-        return await ocrJxa(tmpPath, screenSize, scaleFactor, region, buf);
+        return await ocrJxa(tmpPath, screenSize, scaleFactor, region);
     }
     finally {
         await unlink(tmpPath).catch(() => { });
@@ -83,6 +83,9 @@ export async function ocr(display, region) {
 async function ocrNative(tmpPath, scaleFactor, region) {
     const screenDirname = dirname(fileURLToPath(import.meta.url));
     const candidates = [
+        // npm prod: screen.js 编译落在 dist/src/platform/macos/（4 级深），到包根需 4 级 ../
+        join(screenDirname, "..", "..", "..", "..", "native", "ocr", "ocr-helper"),
+        // dev: screen.ts 在 src/platform/macos/（3 级深），3 级到包根
         join(screenDirname, "..", "..", "..", "native", "ocr", "ocr-helper"),
         join(screenDirname, "..", "..", "native", "ocr", "ocr-helper"),
         join(process.cwd(), "native", "ocr", "ocr-helper"),
@@ -120,45 +123,47 @@ async function ocrNative(tmpPath, scaleFactor, region) {
         return null;
     }
 }
-async function ocrJxa(tmpPath, screenSize, scaleFactor, region, buf) {
+async function ocrJxa(tmpPath, screenSize, scaleFactor, region) {
     const pathLiteral = JSON.stringify(tmpPath);
     const jxaScript = `
     function run() {
       ObjC.import('Vision');
       ObjC.import('AppKit');
       ObjC.import('Foundation');
-      var app = Application.currentApplication();
-      app.includeStandardAdditions = true;
       var path = ${pathLiteral};
-      var url = $.NSURL.fileURLWithPath(path);
-      var image = $.NSImage.alloc.initWithContentsOfURL(url);
-      if (!image || !image.isValid) {
+      var fm = $.NSFileManager.defaultManager;
+      if (!fm.fileExistsAtPath(path)) {
         return JSON.stringify({error: "Failed to load screenshot image", elements: [], fullText: ""});
       }
-      var cgImage = image.CGImageForProposedRectContextHints(null, null, null);
-      if (!cgImage) {
+      var url = $.NSURL.fileURLWithPath(path);
+      var handler = $.VNImageRequestHandler.alloc.initWithURLOptions(url, $());
+      if (!handler) {
         return JSON.stringify({error: "Failed to get CGImage from screenshot", elements: [], fullText: ""});
       }
       var request = $.VNRecognizeTextRequest.alloc.init;
       request.recognitionLevel = $.VNRequestTextRecognitionLevelAccurate;
       request.usesLanguageCorrection = true;
-      var handler = $.VNImageRequestHandler.alloc.initWithCGImageOptions(cgImage, null);
-      var performError = $();
-      var success = handler.performRequestsError([request], performError);
+      var performError = Ref();
+      var success = handler.performRequestsError($([request]), performError);
       if (!success) {
         return JSON.stringify({error: "OCR request failed", elements: [], fullText: ""});
       }
       var results = request.results;
+      var image = $.NSImage.alloc.initWithContentsOfURL(url);
+      if (!image || $(image.representations()).count === 0) {
+        return JSON.stringify({error: "Failed to load screenshot image", elements: [], fullText: ""});
+      }
+      var rep = image.representations().objectAtIndex(0);
+      var imgWidth = rep.pixelsWide;
+      var imgHeight = rep.pixelsHigh;
       var elements = [];
       var fullTextParts = [];
-      var imgWidth = cgImage.width;
-      var imgHeight = cgImage.height;
       for (var i = 0; i < results.count; i++) {
         var obs = $(results).objectAtIndex(i);
         var candidates = obs.topCandidates(1);
-        if (candidates && candidates.count > 0) {
+        if (candidates && $(candidates).count > 0) {
           var candidate = $(candidates).objectAtIndex(0);
-          var text = candidate.string.toString();
+          var text = ObjC.unwrap(candidate.string);
           var confidence = candidate.confidence;
           var bbox = obs.boundingBox;
           var bx = bbox.origin.x * imgWidth;
@@ -183,8 +188,6 @@ async function ocrJxa(tmpPath, screenSize, scaleFactor, region, buf) {
                 : "";
         throw new CaptureError(`ocr failed: ${parsed.error}${hint}`);
     }
-    const imgWidth = buf.readUInt32BE(16);
-    const scaleFactorX = screenSize.width / (region ? region.width : (imgWidth / scaleFactor));
     const elements = parsed.elements.map((el) => ({
         text: el.text,
         x: Math.round(el.x / scaleFactor) + (region ? region.x : 0),

package/dist/src/platform/macos/window.js

@@ -53,6 +53,25 @@ export async function focusApp(app) {
         await new Promise((resolve) => setTimeout(resolve, 150));
     } while (Date.now() < deadline);
     if (!target) {
+        // 托盘应用（LSUIElement，如 cc-switch）没有常规窗口——回退找菜单栏 status item，
+        // 建立 tray activeTarget（windowId='tray'，validateActiveTarget 对它特判不查窗口）。
+        try {
+            const extras = await this.findMenuBarExtra(app);
+            if (extras.length > 0) {
+                this.activeTarget = {
+                    targetId: randomUUID(),
+                    appName: app,
+                    pid: 0,
+                    windowId: "tray",
+                    title: "",
+                    capturedAt: new Date().toISOString(),
+                };
+                return this.activeTarget;
+            }
+        }
+        catch {
+            // findMenuBarExtra 失败（AX 权限/进程不可达等），落到下面的 WindowNotFoundError
+        }
         this.activeTarget = undefined;
         const err = new WindowNotFoundError(app, { hint: "list_windows returned no match for this app. If the app is running, " +
                 "the most likely cause is that it is an Electron app whose AX tree is " +
@@ -194,6 +213,9 @@ function resolveNativeHelper(folder, binary) {
         return override === null ? null : override;
     }
     const candidates = [
+        // npm prod: window.js 在 dist/src/platform/macos/（4 级深），到包根需 4 级 ../
+        join(__windowDirname, "..", "..", "..", "..", "native", folder, binary),
+        // dev: window.ts 在 src/platform/macos/（3 级深），3 级到包根
         join(__windowDirname, "..", "..", "..", "native", folder, binary),
         join(__windowDirname, "..", "..", "native", folder, binary),
     ];

package/dist/src/safety/guard.js

@@ -12,6 +12,8 @@
 const DEFAULT_BLOCKED_KEYS = [
     // macOS – app-level
     "cmd+q",
+    "cmd+shift+q", // log out（方向2 后字母 q 可解析，须显式拦截）
+    "cmd+option+q", // log out variant
     "cmd+w",
     "cmd+l", // lock screen
     // macOS – system-level
@@ -74,12 +76,22 @@ const DEFAULT_TEXT_INJECTION_PATTERNS = [
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Normalize a shortcut string to lowercase, trimmed, sorted modifiers. */
+/** Modifier alias → canonical name. MAC_MODIFIER_FLAGS accepts both forms
+ *  (cmd/command, option/alt, control/ctrl); normalize them so a blocklist
+ *  entry like "cmd+option+esc" also catches "cmd+alt+esc". */
+const MODIFIER_CANONICAL = {
+    alt: "option", ctrl: "control", cmd: "command",
+};
+/** Normalize a shortcut string to lowercase, trimmed, sorted modifiers with
+ *  modifier aliases canonicalized (alt→option, ctrl→control, cmd→command). */
 function normalizeShortcut(raw) {
     return raw
         .toLowerCase()
         .split("+")
-        .map((s) => s.trim())
+        .map((s) => {
+        const t = s.trim();
+        return MODIFIER_CANONICAL[t] ?? t;
+    })
         .sort()
         .join("+");
 }
@@ -104,6 +116,8 @@ export const OBSERVE_ACTIONS = new Set([
     // and an AX window lookup — it does not synthesize mouse or keyboard input,
     // so the user-activity pause must not block it. (OpenCode 0.3.7 follow-up)
     "focus_app",
+    // describe_screen reads screen state (OCR + AX), no input synthesis.
+    "describe_screen",
 ]);
 /** Actions that synthesize user input — need full user-activity protection. */
 export const INPUT_ACTIONS = new Set([
@@ -117,6 +131,7 @@ export const INPUT_ACTIONS = new Set([
     "click_element",
     "type_in_element",
     "set_value",
+    "click_menu_bar_extra",
     "clipboard_write",
 ]);
 export function classifyAction(action) {

package/dist/src/utils/input.js

@@ -80,6 +80,20 @@ const MAC_MODIFIER_FLAGS = {
     option: 0x00080000, alt: 0x00080000,
     control: 0x00040000, ctrl: 0x00040000,
 };
+// 字母/数字 keyCode —— typeText 与 pressKey 共享的唯一数据源。
+// pressKey 在 MAC_KEY_CODES（特殊键）未命中时回退查这两个 map，让 Cmd+M / Cmd+W 等
+// 含字母的快捷键可用。注意 'a' 的 keyCode 是 0，查找时必须用 `in` 判定存在性，
+// 不能用 truthy（否则 0 会被当成未命中而穿透到 digit map）。
+const MAC_LETTER_KEY_CODES = {
+    a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9,
+    b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
+    o: 31, u: 32, i: 33, p: 34, l: 37, j: 38, k: 40,
+    n: 45, m: 46,
+};
+const MAC_DIGIT_KEY_CODES = {
+    "1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
+    "6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
+};
 // ── AppleScript string escaping ───────────────────────────────────────────
 function escapeAppleScriptString(str) {
     return str
@@ -288,23 +302,11 @@ export async function typeText(text, delay = 20, _platform = process.platform) {
     if (_platform === "darwin") {
         // Character -> { keyCode, shift? } map for CGEvent injection
         const CHAR_TO_KEY = {};
-        // Lowercase letters
-        const letterMap = {
-            a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9,
-            b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
-            o: 31, u: 32, i: 33, p: 34, l: 37, j: 38, k: 40,
-            n: 45, m: 46,
-        };
-        for (const [ch, code] of Object.entries(letterMap)) {
+        for (const [ch, code] of Object.entries(MAC_LETTER_KEY_CODES)) {
             CHAR_TO_KEY[ch] = { code };
             CHAR_TO_KEY[ch.toUpperCase()] = { code, shift: true };
         }
-        // Digits
-        const digitMap = {
-            "1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
-            "6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
-        };
-        for (const [ch, code] of Object.entries(digitMap)) {
+        for (const [ch, code] of Object.entries(MAC_DIGIT_KEY_CODES)) {
             CHAR_TO_KEY[ch] = { code };
         }
         // Unshifted symbols
@@ -422,9 +424,15 @@ export async function pressKey(key, modifiers = [], _platform = process.platform
         return;
     }
     if (_platform === "darwin") {
-        const keyCode = MAC_KEY_CODES[key.toLowerCase()];
+        const lookup = key.toLowerCase();
+        // 先查特殊键，未命中再回退查字母/数字（让 Cmd+M / Cmd+W 等含字母的快捷键可用）。
+        // 用 `in` 判定存在性——'a' 的 keyCode 是 0，truthy 判断会误穿透到 digit map。
+        const keyCode = lookup in MAC_KEY_CODES ? MAC_KEY_CODES[lookup] :
+            (key.length === 1 && lookup in MAC_LETTER_KEY_CODES) ? MAC_LETTER_KEY_CODES[lookup] :
+                (key.length === 1 && key in MAC_DIGIT_KEY_CODES) ? MAC_DIGIT_KEY_CODES[key] :
+                    undefined;
         if (keyCode === undefined) {
-            throw new Error(`Unknown key: ${key}. Supported keys: ${Object.keys(MAC_KEY_CODES).join(", ")}`);
+            throw new Error(`Unknown key: ${key}. Supported keys: special keys (${Object.keys(MAC_KEY_CODES).join(", ")}), single letters a-z, single digits 0-9`);
         }
         // Build modifier flags
         let flags = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "dist/src/",
     "dist/index.js",
     "dist/index.d.ts",
+    "skills/",
     "README.md",
     "CHANGELOG.md"
   ],

package/skills/ucu-mcp/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ucu-mcp
+description: >-
+  Guidance for using UCU-MCP, the macOS computer-use MCP server (screenshot,
+  click, type, OCR, AX element tools, menu-bar tray support). Use when an
+  agent needs to automate macOS desktop apps over MCP — establishing target
+  context, reading screen state, interacting with UI elements, operating
+  menu-bar/tray apps, or recovering from AX/permission errors. Covers Claude
+  Code CLI/Desktop, Codex, OpenCode, and other MCP clients.
+---
+
+# UCU-MCP
+
+UCU-MCP is a cross-client computer-use MCP server for macOS (Windows/Linux are
+explicit stubs). It exposes 26 tools that let an agent see the screen and drive
+native apps through a combination of Accessibility (AX) APIs, CGEvent input
+synthesis, Vision OCR, and ScreenCaptureKit screenshots.
+
+- npm package: `ucu-mcp`
+- Run: `npx -y ucu-mcp` (stdio MCP server) or install globally via `npm i -g ucu-mcp`
+
+## Core Workflow
+
+1. **Check readiness** → `doctor` verifies Accessibility + Screen Recording
+   permissions and native helpers. If anything is missing, follow its guidance
+   (see [troubleshooting](references/troubleshooting.md)).
+2. **Establish target context** → `list_apps` then `focus_app(name)` sets the
+   active window target. Subsequent AX tools operate against that target.
+3. **Prefer AX over coordinates** → `find_element(text/role/value)` →
+   `click_element` / `type_in_element` / `set_value`. AX is precise and survives
+   layout shifts; coordinates are a last resort.
+4. **When AX is opaque (Electron/Tauri/WebView)** → `screenshot` + `ocr` to
+   locate text by bounding box, then `click(x, y)` at the returned coordinates.
+5. **When image content is not visible to you** (relayed/downgraded to a URL) →
+   `screenshot(describe: true)` or the standalone `describe_screen` tool to get a
+   structured text view (OCR blocks + AX tree + foreground window).
+6. **Menu-bar/tray apps** (e.g. cc-switch) → `click_menu_bar_extra(app,
+   description/name/index)` opens the tray menu, then `find_element` inside it.
+7. **Verify actions** → pass `captureAfter: true` on action tools, or call
+   `screenshot` / `get_window_state` afterwards.
+8. **Recover from errors** → every error response carries a `hint` with the
+   next step. See the [error code table](references/troubleshooting.md).
+
+Full tool inventory with parameters: [tool-reference](references/tool-reference.md).
+Common task playbooks: [workflows](references/workflows.md).
+
+## Operating Rules
+
+- **AX-first.** Use `find_element` → `click_element` / `type_in_element` /
+  `set_value` whenever the AX tree exposes the target. Fall back to coordinates
+  only when AX returns nothing (Electron/WebView) or the control silently
+  swallows AX actions.
+- **Observe before acting.** Call `screenshot` / `get_window_state` /
+  `describe_screen` before destructive or hard-to-reverse actions so you act on
+  current state, not assumptions.
+- **TARGET_STALE is recoverable.** Re-run `focus_app` for the target app, then
+  retry — the element cache refetches equivalent AX nodes.
+- **Tray apps need `click_menu_bar_extra`.** `focus_app` alone cannot reach
+  pure menu-bar (LSUIElement) apps; their status item is hosted by
+  `SystemUIServer` and is not in any app window's AX tree.
+- **Dangerous actions are blocked.** Quit/logout/lock shortcuts (`cmd+q`,
+  `cmd+shift+q`, `cmd+l`, …), sensitive-window URLs, and suspicious injected
+  text are rejected by the safety guard. Choose a safer action or ask the user.
+- **Sensitive fields are masked in `describe_screen`.** Password fields
+  (`AXSecureTextField`, or names matching `/password|secret|token/i`) appear as
+  `[REDACTED]` — never try to read or exfiltrate them.
+- **macOS is locked → actions blocked.** The server refuses to synthesize input
+  while the screen is locked; wait for unlock or ask the user.
+
+## MCP Config
+
+Add UCU-MCP to your MCP client. Stdio transport, no arguments needed.
+
+**Codex / generic TOML:**
+
+```toml
+[mcp_servers.ucu-mcp]
+command = "npx"
+args = ["-y", "ucu-mcp"]
+```
+
+**Claude Code CLI / Desktop** — add via `claude mcp add`:
+
+```bash
+claude mcp add ucu-mcp -- npx -y ucu-mcp
+```
+
+Run `ucu-mcp doctor` once after first connect to verify macOS permissions
+(System Settings → Privacy & Security → Accessibility **and** Screen Recording
+must be granted to the launching terminal/client).
+
+## References
+
+- [tool-reference.md](references/tool-reference.md) — all 26 tools, parameters,
+  return shapes, and when to use each.
+- [workflows.md](references/workflows.md) — playbooks for common tasks: form
+  filling, tray apps, opaque Electron UIs, vision-degraded environments, stale
+  targets.
+- [troubleshooting.md](references/troubleshooting.md) — error code table with
+  recovery steps, permission issues, AX-opacity workarounds, OCR failures.

package/skills/ucu-mcp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UCU-MCP"
+  short_description: "Guide agents using UCU-MCP macOS computer-use"
+  default_prompt: "Use $ucu-mcp to automate macOS desktop apps through UCU-MCP."