@szc-ft/mcp-szcd-client 0.28.2 → 0.30.0

package/qwen-extension/skills/local-browser-test/lib/browser-engine.js

@@ -24,6 +24,7 @@ export class BrowserEngine {
         this._activeFrame = null;  // 当前活跃 iframe 上下文（微前端场景）
         this._adapter = null;      // 懒加载 AntAdapter
         this._lastActWasDropdown = false; // 用于 act 入口自动 closeAllDropdowns
+        this._wujieContext = null;  // wujie 微前端模式 { type, frameCount, wujieApp? }
     }
 
     /**
@@ -72,6 +73,138 @@ export class BrowserEngine {
         }
     }
 
+    /**
+     * 检测 wujie 微前端模式（WebComponent / iframe）
+     * @returns {{ type: 'webcomponent'|'iframe'|'none', frameCount: number, wujieApp?: object }}
+     */
+    async _detectWujieMode() {
+        const frames = this.page.frames();
+        const frameCount = frames.length;
+        const mainFrame = this.page.mainFrame();
+        // JSON 输出返回完整文本不截断；stderr 日志仅截取前 200 字符预览
+        const LOG_PREVIEW_LEN = 200;
+
+        // 检查主文档中是否有 <wujie-app> 自定义元素（WebComponent 模式标志）
+        const wujieInfo = await mainFrame.evaluate(() => {
+            const app = document.querySelector('wujie-app');
+            if (!app) return null;
+            const sr = app.shadowRoot;
+            const body = sr?.querySelector('body');
+            const fullText = body?.innerText || '';
+            return {
+                tagName: app.tagName,
+                className: app.className,
+                hasShadowRoot: !!sr,
+                shadowChildren: sr?.children?.length || 0,
+                shadowBodyText: fullText,
+                shadowBodyTextLength: fullText.length,
+            };
+        }).catch(() => null);
+
+        if (wujieInfo) {
+            const ctx = { type: 'webcomponent', frameCount, wujieApp: wujieInfo };
+            process.stderr.write(`[wujie] WebComponent 模式: <${wujieInfo.tagName} class="${wujieInfo.className}"> shadowRoot=${wujieInfo.hasShadowRoot} children=${wujieInfo.shadowChildren} frames=${frameCount}\n`);
+            // stderr 只输出预览（不刷屏），JSON 中返回全文
+            const preview = wujieInfo.shadowBodyText?.substring(0, LOG_PREVIEW_LEN) || '';
+            process.stderr.write(`[wujie]   shadow body (${wujieInfo.shadowBodyTextLength} chars): "${preview}${wujieInfo.shadowBodyTextLength > LOG_PREVIEW_LEN ? '...' : ''}"\n`);
+            // 列出所有 frame 供排障
+            for (let i = 0; i < frames.length; i++) {
+                process.stderr.write(`[wujie]   frame[${i}]: ${frames[i].url().substring(0, 100)}\n`);
+            }
+            return ctx;
+        }
+
+        if (frameCount > 1) {
+            process.stderr.write(`[wujie] iframe 模式: ${frameCount} frames\n`);
+            for (let i = 0; i < frames.length; i++) {
+                process.stderr.write(`[wujie]   frame[${i}]: ${frames[i].url().substring(0, 100)}\n`);
+            }
+            return { type: 'iframe', frameCount };
+        }
+
+        process.stderr.write(`[wujie] 未检测到微前端 (frames=${frameCount})\n`);
+        return { type: 'none', frameCount };
+    }
+
+    /**
+     * 安全获取页面列表（优先同步 targets() 避免 pages() 挂死 + 泄露 WebSocket）
+     */
+    async _safeGetPages() {
+        // 1. 优先使用同步 targets()，不会挂死也不会泄露未完成的 promise
+        try {
+            const targets = this.browser.targets();
+            const pageTargets = targets.filter((t) => t.type() === "page");
+            if (pageTargets.length > 0) {
+                const pages = [];
+                for (const t of pageTargets) {
+                    try {
+                        const p = await Promise.race([
+                            t.page(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("page() timeout")), 3000)),
+                        ]);
+                        if (p) pages.push(p);
+                    } catch {
+                        // 跳过无法获取的 target
+                    }
+                }
+                if (pages.length > 0) return pages;
+            }
+        } catch {
+            // targets() 失败
+        }
+
+        // 2. 回退：CDP Target.getTargets
+        try {
+            const client = await this.browser.target().createCDPSession();
+            const { targetInfos } = await client.send("Target.getTargets");
+            const pageInfos = targetInfos.filter((t) => t.type === "page");
+            const pages = [];
+            for (const info of pageInfos) {
+                try {
+                    const target = await Promise.race([
+                        this.browser.waitForTarget((t) => t.url() === info.url, { timeout: 2000 }),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error("waitForTarget timeout")), 3000)),
+                    ]);
+                    if (target) {
+                        const p = await Promise.race([
+                            target.page(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("page() timeout")), 3000)),
+                        ]);
+                        if (p) pages.push(p);
+                    }
+                } catch {
+                    // skip
+                }
+            }
+            if (pages.length > 0) return pages;
+        } catch {
+            // CDP 回退也失败
+        }
+
+        // 3. 最后手段：只能尝试 pages()（带严格超时，用完立即 disconnect/reconnect 清理）
+        try {
+            const pages = await Promise.race([
+                this.browser.pages(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("pages() timeout")), 5000)),
+            ]);
+            if (pages && pages.length > 0) return pages;
+        } catch {
+            // pages() 超时；注意此时 browser.pages() 的 WebSocket 可能泄露
+            // 清理：断开后重新连接
+            try {
+                const wsUrl = this.browser.wsEndpoint();
+                const puppeteer = await loadPuppeteer();
+                await this.browser.disconnect();
+                this.browser = await puppeteer.connect({ browserWSEndpoint: wsUrl, defaultViewport: null });
+            } catch {
+                // reconnect 失败，继续用当前 browser
+            }
+        }
+
+        // 4. 最后手段：newPage()
+        return [await this.browser.newPage()];
+    }
+
     /**
      * 模式 A：连接到用户已有的 Chrome
      */
@@ -82,7 +215,7 @@ export class BrowserEngine {
         this.ownedBrowser = false;
 
         // 获取页面：优先使用指定 URL 匹配的标签页
-        const pages = await this.browser.pages();
+        const pages = await this._safeGetPages();
         if (options.pageUrl) {
             this.page = pages.find((p) => p.url().includes(options.pageUrl))
                      || await this.browser.newPage();
@@ -96,6 +229,9 @@ export class BrowserEngine {
             await this.page.setViewport(options.viewport);
         }
 
+        // 微前端模式检测
+        this._wujieContext = await this._detectWujieMode();
+
         return {
             mode: "connect",
             cdpUrl,
@@ -223,6 +359,7 @@ export class BrowserEngine {
                 frameUrl: targetFrame.frame.url(),
                 matchedBy: targetFrame.matchedBy,
             },
+            wujieContext: this._wujieContext,
             frames,
             tree,
             interactiveElements,
@@ -247,7 +384,10 @@ export class BrowserEngine {
 
         const targetFrame = await this._resolveObserveFrame(options);
         if (options.menuPath) {
-            return this._actMenuPath(targetFrame, options);
+            // 菜单在 main frame 外壳中渲染，不随子应用切换
+            const menuFrame = this.page.mainFrame();
+            const menuTarget = { frame: menuFrame, frameId: "main", matchedBy: "main (menu shell)" };
+            return this._actMenuPath(menuTarget, options);
         }
 
         const index = options.index !== undefined ? Number.parseInt(options.index, 10) : undefined;
@@ -308,17 +448,36 @@ export class BrowserEngine {
 
             function findBySelector(selector) {
                 if (!selector) return null;
+                // text== 精确匹配（Playwright 兼容）：只匹配 innerText 完全相等的元素
+                if (selector.startsWith("text==")) {
+                    const expected = selector.slice(6).trim();
+                    const filter = (el) => isVisibleEnabled(el);
+                    const interactive = interactiveElements().filter(filter);
+                    let hit = interactive.find((el) => getText(el) === expected || getName(el, getText(el)) === expected);
+                    if (hit) return hit;
+                    const all = Array.from(document.querySelectorAll("*")).filter(filter);
+                    return all.find((el) => getText(el) === expected) || null;
+                }
+                // text= 模糊匹配：优先选 innerText 最短的元素（离目标文字最近的叶子节点）
+                // 避免命中包含目标文字的大容器（如 drawer 整体 div）
                 if (selector.startsWith("text=")) {
                     const expected = selector.slice(5).trim();
-                    // 默认仅匹配 visible+enabled 元素，避免命中 ant-select 的隐藏 input、收起菜单里的 li
-                    // 需要包含隐藏元素时显式 includeHidden=true
                     const includeHidden = actOptions.includeHidden === true;
                     const filter = (el) => includeHidden || isVisibleEnabled(el);
                     const interactive = interactiveElements().filter(filter);
-                    let hit = interactive.find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected));
-                    if (hit) return hit;
+                    let hits = interactive.filter((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected));
+                    if (hits.length > 0) {
+                        // 按 innerText 长度升序：最短的最可能是目标元素本身而非父容器
+                        hits.sort((a, b) => getText(a).length - getText(b).length);
+                        return hits[0];
+                    }
                     const all = Array.from(document.querySelectorAll("*")).filter(filter);
-                    return all.find((el) => getText(el).includes(expected)) || null;
+                    hits = all.filter((el) => getText(el).includes(expected));
+                    if (hits.length > 0) {
+                        hits.sort((a, b) => getText(a).length - getText(b).length);
+                        return hits[0];
+                    }
+                    return null;
                 }
                 if (selector.startsWith("role=")) {
                     const match = selector.match(/^role=([^\[]+)(?:\[name="([^"]+)"\])?/);
@@ -944,6 +1103,15 @@ export class BrowserEngine {
     }
 
     async _resolveObserveFrame(options = {}) {
+        // testCase setup 已预定位 iframe，且调用方未显式传 frame 参数 → 直接复用
+        if (this._activeFrame && options.frameIndex === undefined && !options.frameUrlContains && !options.frameContentContains) {
+            const frames = this.page.frames();
+            const idx = frames.indexOf(this._activeFrame);
+            if (idx >= 0) {
+                return { frame: this._activeFrame, frameId: idx === 0 ? "main" : `frame-${idx}`, matchedBy: "activeFrame (from testCase setup)" };
+            }
+        }
+
         const frames = this.page.frames();
         const mainFrame = this.page.mainFrame();
 
@@ -973,6 +1141,14 @@ export class BrowserEngine {
             }
         }
 
+        // 无显式 frame 参数时：WebComponent 模式默认用 sandbox iframe（含子应用实际 DOM）
+        if (this._wujieContext?.type === 'webcomponent' && frames.length > 1) {
+            const sandboxIdx = frames.findIndex((f) => f !== mainFrame && !f.url().startsWith('about:'));
+            if (sandboxIdx >= 0) {
+                return { frame: frames[sandboxIdx], frameId: `frame-${sandboxIdx}`, matchedBy: 'webcomponent sandbox iframe' };
+            }
+        }
+
         const mainIndex = frames.indexOf(mainFrame);
         return { frame: mainFrame, frameId: mainIndex <= 0 ? "main" : `frame-${mainIndex}`, matchedBy: "main" };
     }
@@ -1097,8 +1273,23 @@ export class BrowserEngine {
 
             const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
             const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
-            return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
-                .filter(isCandidate)
+
+            // 1. 先收集 portal 弹窗/抽屉中的元素（排在前面，避免 text= 匹配到外层容器）
+            const portalSelectors = '.ant-drawer:not(.ant-drawer-closed), .ant-drawer-open .ant-drawer-content-wrapper, .ant-modal-wrap:not([style*="display: none"]), .ant-dropdown:not(.ant-dropdown-hidden)';
+            const portalEls = [];
+            document.querySelectorAll(portalSelectors).forEach(portal => {
+                portal.querySelectorAll('a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*="btn"],[class*="button"],[class*="ant-btn"]').forEach(el => {
+                    if (isCandidate(el)) portalEls.push(el);
+                });
+            });
+
+            // 2. 再收集 body 中的元素，但要排除已在 portal 中的（避免重复）
+            const portalSet = new Set(portalEls);
+            const bodyEls = Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                .filter(el => isCandidate(el) && !portalSet.has(el));
+
+            // portal 元素排前面（优先级更高），body 元素排后面
+            return portalEls.concat(bodyEls)
                 .slice(0, limit)
                 .map((el, idx) => {
                     const rect = el.getBoundingClientRect();
@@ -1693,7 +1884,7 @@ export class BrowserEngine {
      * 查找已打开的标签页（connect 模式，端口可变场景）
      */
     async _findPage(step) {
-        const pages = await this.browser.pages();
+        const pages = await this._safeGetPages();
         let matched = null;
         let matchReason = "";
 
@@ -2114,7 +2305,15 @@ export class BrowserEngine {
         const results = [];
         const dataset = testCase.dataset || [{ __row: 0 }];
 
-        // setup 阶段：frame 预定位
+        // setup 阶段：page 切换 + frame 预定位
+        if (testCase.setup?.findPage) {
+            const pageResult = await this._findPage(testCase.setup.findPage);
+            if (!pageResult.found) {
+                throw new Error(`findPage failed: ${pageResult.error} - available pages: ${JSON.stringify(pageResult.pages?.map(p => p.url))}`);
+            }
+            // page 切换后需要重新检测 wujie 模式
+            this._wujieContext = await this._detectWujieMode();
+        }
         if (testCase.setup?.findFrame && !this._activeFrame) {
             const resolved = await this._resolveObserveFrame(testCase.setup.findFrame);
             this._activeFrame = resolved.frame;

package/qwen-extension/skills/local-browser-test/local-browser-executor.js

@@ -8,11 +8,12 @@
  *   node local-browser-executor.js --action act --menu-path "目录管理/数据集目录" --observe-after
  *   node local-browser-executor.js --action api-capture --wait 15000 --include-response-body
  *   node local-browser-executor.js --action assert-api --capture-file /tmp/browser-api-capture.json --max-failed 0
+ *   node local-browser-executor.js --action evaluate --expression "(() => ({a:1}))()" --frame-index 1
  *   node local-browser-executor.js --plan '<JSON>' --output /tmp/result.json
  *   node local-browser-executor.js --plan-file /path/to/plan.json --output /tmp/result.json
  *
  * 参数：
- *   --action     直接执行动作，当前支持 observe/act/assert/api-capture
+ *   --action     直接执行动作，当前支持 observe/act/assert/evaluate/api-capture/assert-api/run-task/test-case/plan
  *   --plan       测试计划 JSON 字符串
  *   --plan-file  测试计划 JSON 文件路径（与 --plan 二选一）
  *   --output     结果输出文件路径（默认 stdout）
@@ -228,6 +229,15 @@ function parseArgs() {
             case "--test-report":
                 parsed.testReport = args[++i];
                 break;
+            case "--expression":
+                parsed.expression = args[++i];
+                break;
+            case "--expect-result-contains":
+                parsed.expectResultContains = args[++i];
+                break;
+            case "--fail-on-falsy":
+                parsed.failOnFalsy = true;
+                break;
             case "--help":
             case "-h":
                 printHelp();
@@ -249,11 +259,12 @@ function printHelp() {
   node local-browser-executor.js --action api-capture --wait 15000 --include-response-body [options]
   node local-browser-executor.js --action assert-api --capture-file /tmp/browser-api-capture.json --max-failed 0 [options]
   node local-browser-executor.js --action run-task --task menu-api-scan --capture-input-file /tmp/menu-tree.json [options]
+  node local-browser-executor.js --action evaluate --expression "(() => ({a:1}))()" [options]
   node local-browser-executor.js --plan '<JSON>' [options]
   node local-browser-executor.js --plan-file <path> [options]
 
 选项:
-  --action <name>                    直接执行动作，当前支持 observe/act/assert/api-capture/assert-api/run-task
+  --action <name>                    直接执行动作，当前支持 observe/act/assert/evaluate/api-capture/assert-api/run-task/test-case/plan
   --plan <json>                      测试计划 JSON 字符串
   --plan-file <path>                 测试计划 JSON 文件路径
   --output <path>                    结果输出文件路径（默认 stdout）
@@ -274,6 +285,9 @@ function printHelp() {
   --menu-path <a/b>                  act 时按菜单路径展开并点击，如 "目录管理/数据集目录"
   --wait-after-each <ms>             menu-path 每步点击后的等待时间（默认 300）
   --observe-after                    act 后再次 observe，返回 before/act/after 闭环结果
+  --expression <js>                  evaluate 时执行的 JS 表达式（需用 IIFE 包裹）
+  --expect-result-contains <text>    evaluate 时期望结果包含的文本
+  --fail-on-falsy                    evaluate 时结果为 falsy 则标记失败
   --url-contains-assert <text>       assert 当前 URL 包含文本
   --text-contains <text>             assert 页面文本包含内容
   --expect-visible                   assert selector 可见
@@ -493,6 +507,34 @@ async function executeAction(args) {
                 });
                 return { type: "actObserve", act: actResult, after, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
             }
+            case "evaluate": {
+                // 先通过 _resolveObserveFrame 设置 _activeFrame，使 safeEval 在正确的 frame 中执行
+                const resolved = await engine._resolveObserveFrame({
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                });
+                engine._activeFrame = resolved.frame;
+                const evalResult = await engine.safeEval(args.expression);
+                const evalPassed = args.failOnFalsy ? !!evalResult : true;
+                const containsMatch = args.expectResultContains
+                    ? JSON.stringify(evalResult).includes(args.expectResultContains)
+                    : true;
+                return {
+                    type: "evaluate",
+                    expression: args.expression,
+                    result: evalResult,
+                    passed: evalPassed && containsMatch,
+                    frameTarget: resolved.frameId,
+                    checks: {
+                        failOnFalsy: args.failOnFalsy ? { expected: "truthy", actual: !!evalResult, passed: !!evalResult } : null,
+                        expectResultContains: args.expectResultContains ? { expected: args.expectResultContains, passed: containsMatch } : null,
+                    },
+                    browserInfo: initResult,
+                    startTime: startedAt,
+                    endTime: new Date().toISOString(),
+                };
+            }
             case "assert": {
                 const expect = {};
                 if (args.expectVisible) expect.visible = true;
@@ -509,6 +551,11 @@ async function executeAction(args) {
                 });
                 return { type: "assert", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
             }
+            case "plan": {
+                const plan = loadPlan(args);
+                const result = await executePlan(plan, { cdpUrl: args.cdpUrl, pageUrl: args.pageUrl || args.urlContains });
+                return { type: "plan", ...result, startTime: startedAt, endTime: new Date().toISOString() };
+            }
             case "api-capture":
             case "apiCapture": {
                 const result = await engine.captureApi({
@@ -628,7 +675,7 @@ async function executeAction(args) {
                 return {
                     error: `未知 action: ${args.action}`,
                     errorCode: "UNKNOWN_ACTION",
-                    supportedActions: ["observe", "act", "assert", "api-capture", "assert-api", "run-task", "test-case"],
+                    supportedActions: ["observe", "act", "assert", "evaluate", "api-capture", "assert-api", "run-task", "test-case", "plan"],
                     startTime: startedAt,
                     endTime: new Date().toISOString(),
                 };

package/qwen-extension/skills/local-browser-test/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/qwen-extension/skills/szcd-upload-zip/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: szcd-upload-zip
+description: |
+    本地 ZIP 文件上传与解压工具。将用户本地的 zip 压缩包通过 `upload-zip` REST 端点上传到 szcd-mcp-server，
+    自动解压到服务器的 `uploads/<zip包名>/` 目录，并返回解压后的文件列表。
+    上传后解压的文件可通过文件下载接口按路径获取或供其他流程使用。
+compatibility:
+  tools:
+    - run_command
+  runtime:
+    - node >= 18（读取配置用，仅 `cat ~/.szcd-mcp-config.json` 场景）
+    - curl（文件上传所需）
+---
+
+# ZIP 上传与解压工具（szcd-upload-zip）
+
+## 概述
+
+当 AI 需要将用户本地的 ZIP 压缩包上传到 szcd-mcp-server 时，使用此技能。
+上传后服务器自动解压，开发者或 AI 可通过下载 API 访问解压后的文件。
+
+## 适用场景
+
+- 用户有一个本地 zip 包需要上传到服务器存储
+- zipped 源码/资源包需要上传到服务器供后续流程使用
+- 需要在服务器端解压 zip 并取用其中的文件
+
+## 工作流
+
+### 第 0 步：探测运行时
+
+```bash
+node --version 2>/dev/null && echo "NODE_OK"; \
+curl --version 2>/dev/null | head -1 && echo "CURL_OK"
+```
+
+### 第 1 步：读取配置获取服务器地址和 API Key
+
+```bash
+cat ~/.szcd-mcp-config.json
+```
+
+配置示例：
+```json
+{
+  "MCP_SERVER_URL": "http://localhost:3456",
+  "MCP_TIMEOUT": 30000,
+  "MCP_API_KEY": "your-api-key"
+}
+```
+
+- 若 `MCP_API_KEY` 为空字符串，则上传时不带 `X-API-Key` header
+- 若 `MCP_SERVER_URL` 未配置，默认使用 `http://localhost:3456`
+
+### 第 2 步：上传 ZIP 文件
+
+```bash
+# 从 ~/.szcd-mcp-config.json 取 URL 和 API Key
+MCP_URL=$(node -e "const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_SERVER_URL||'http://localhost:3456')")
+MCP_KEY=$(node -e "const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_API_KEY||'')")
+
+# 上传 zip 文件
+if [ -n "$MCP_KEY" ]; then
+  curl -s -X POST "$MCP_URL/upload-zip" -H "X-API-Key: $MCP_KEY" -F "file=@<zip文件路径>"
+else
+  curl -s -X POST "$MCP_URL/upload-zip" -F "file=@<zip文件路径>"
+fi
+```
+
+其中 `<zip文件路径>` 替换为实际 zip 文件的绝对路径。
+
+**响应示例：**
+```json
+{
+  "ok": true,
+  "dir_name": "my-package",
+  "extract_dir": "/scity/zengzhijie/mcp/uploads/my-package",
+  "file_count": 5,
+  "files": [
+    { "path": "index.html", "size": 2048 },
+    { "path": "js/app.js", "size": 15360 },
+    { "path": "css/style.css", "size": 4096 },
+    { "path": "images/logo.png", "size": 819200 },
+    { "path": "data/config.json", "size": 512 }
+  ]
+}
+```
+
+### 第 3 步：查看解压后的文件
+
+上传成功后，可通过下载 API 查看解压后的文件或取单个文件内容：
+
+```bash
+# 列出解压目录
+curl -s "$MCP_URL/api/download/list?dir=/scity/zengzhijie/mcp/uploads/my-package" \
+  ${MCP_KEY:+-H "X-API-Key: $MCP_KEY"}
+
+# 下载单个文件
+curl -s "$MCP_URL/api/download?path=/scity/zengzhijie/mcp/uploads/my-package/data/config.json" \
+  ${MCP_KEY:+-H "X-API-Key: $MCP_KEY"}
+```
+
+## 限制说明
+
+- 仅支持真正的 ZIP 格式（magic number `PK\x03\x04` 校验），改扩展名无用
+- 单文件大小上限 100MB
+- 同名 zip 包名会覆盖服务器上已有的目录
+- 解压后文件持久存储，无自动过期
+- 上传路径始终为 `/upload-zip`（不含 `/api/` 前缀）
+
+## 完整命令示例（一步完成）
+
+```bash
+# 读取配置
+MCP_URL=$(node -e "try{const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_SERVER_URL||'http://localhost:3456')}catch{console.log('http://localhost:3456')}")
+MCP_KEY=$(node -e "try{const c=require('fs').readFileSync(require('os').homedir()+'/.szcd-mcp-config.json','utf8');const j=JSON.parse(c);console.log(j.MCP_API_KEY||'')}catch{console.log('')}")
+
+# 上传
+curl -s -X POST "$MCP_URL/upload-zip" \
+  ${MCP_KEY:+-H "X-API-Key: $MCP_KEY"} \
+  -F "file=@/path/to/archive.zip" | python3 -m json.tool
+```