@szc-ft/mcp-szcd-client 0.20.0 → 0.22.0

package/scripts/lib/claude-code.js

@@ -9,7 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { execSync } from "node:child_process";
-import { getClientConfigHeader as getClientConfigHeaderDirect, getApiKey as getApiKeyDirect } from "./common.js";
+import { getClientConfigHeader as getClientConfigHeaderDirect, getApiKey as getApiKeyDirect, getSketchMcpServerUrl, ADDITIONAL_MCP_SERVERS } from "./common.js";
 
 // ==================== 路径工具 ====================
 
@@ -363,9 +363,53 @@ export function setupClaudeCode(deps) {
         }
     }
 
+    // 最后注册额外的 MCP Server，避免被 CLI 操作覆盖
+    registerAdditionalMcpServers();
+
     return {
         claudeProjectInstalled,
         skillsDirectory: getClaudeCodeSkillsDirectory(),
         agentsDirectory: getClaudeCodeAgentsDirectory(),
     };
 }
+
+/**
+ * 注册额外的 MCP Server 到 Claude Code
+ * HTTP 类型: { type: "http", url: "<httpUrl>" }
+ * stdio 类型: { type: "stdio", command, args }
+ * 注意：仅通过文件操作写入 ~/.claude.json，不使用 CLI，
+ * 因为 `claude mcp add` 会重写整个文件并丢失其他 server 条目
+ */
+function registerAdditionalMcpServers() {
+    const configPath = getClaudeCodeConfigPath();
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        } catch { /* 忽略 */ }
+    }
+    if (!config.mcpServers) config.mcpServers = {};
+
+    let changed = false;
+    for (const server of ADDITIONAL_MCP_SERVERS) {
+        let expected;
+        if (server.type === "http") {
+            const sketchUrl = `${getSketchMcpServerUrl()}/mcp`;
+            expected = { type: "http", url: sketchUrl };
+        } else {
+            expected = { type: server.type, command: server.command, args: server.args };
+        }
+        const current = config.mcpServers[server.name];
+        if (current && JSON.stringify(current) === JSON.stringify(expected)) {
+            console.log(`✓ Claude Code ~/.claude.json already has: ${server.name}`);
+            continue;
+        }
+        config.mcpServers[server.name] = expected;
+        console.log(`✓ Added ${server.name} to Claude Code ~/.claude.json (${server.type})`);
+        changed = true;
+    }
+
+    if (changed) {
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    }
+}

package/scripts/lib/common.js

@@ -17,6 +17,18 @@ const __dirname = path.dirname(__filename);
 // 默认值（需在 SKILL_SOURCE 之前定义）
 export const DEFAULT_MCP_SERVER_URL = "http://localhost:3456";
 export const DEFAULT_MCP_SERVER_NAME = "szcd-component-helper";
+export const DEFAULT_SKETCH_MCP_SERVER_URL = "http://localhost:3457";
+
+// 额外的 MCP Server（HTTP 模式，由独立进程或代理提供 HTTP 接口）
+export const ADDITIONAL_MCP_SERVERS = [
+    {
+        name: "sketch-mcp-server",
+        type: "stdio",
+        command: "sketch-mcp-server",
+        args: [],
+        description: "Sketch 设计文件解析（szcd 维护版），解析 .sketch 文件提取页面结构、图层信息和导出图片。postinstall 会尝试全局安装以加速启动",
+    },
+];
 
 export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 export const SKILLS_DIR = path.join(PACKAGE_ROOT, "standard-skill");
@@ -184,6 +196,11 @@ export function getMcpServerName() {
     return config.MCP_SERVER_NAME || DEFAULT_MCP_SERVER_NAME;
 }
 
+export function getSketchMcpServerUrl() {
+    const config = loadExistingConfig();
+    return config.SKETCH_MCP_SERVER_URL || DEFAULT_SKETCH_MCP_SERVER_URL;
+}
+
 // ==================== 客户端 CODING 配置透传 ====================
 
 /**

package/scripts/lib/opencode.js

@@ -39,7 +39,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { execSync } from "node:child_process";
-import { getClientConfigHeader as _getClientConfigHeader, getApiKey as _getApiKey } from "./common.js";
+import { getClientConfigHeader as _getClientConfigHeader, getApiKey as _getApiKey, getSketchMcpServerUrl, ADDITIONAL_MCP_SERVERS } from "./common.js";
 
 // ==================== 路径工具 ====================
 
@@ -97,10 +97,40 @@ function readJsonFile(filePath) {
     if (!fs.existsSync(filePath)) return {};
     try {
         const content = fs.readFileSync(filePath, "utf8");
-        // jsonc 支持：简单去除注释（// 和 /* */）
-        const cleaned = content
+        // jsonc 支持：去除注释，但需跳过字符串内的 //
+        // 策略：逐字符扫描，追踪是否在字符串内
+        const lines = content.split("\n");
+        const result = [];
+        for (const line of lines) {
+            let inString = false;
+            let escape = false;
+            let cleanLine = "";
+            for (let i = 0; i < line.length; i++) {
+                const ch = line[i];
+                if (escape) {
+                    cleanLine += ch;
+                    escape = false;
+                    continue;
+                }
+                if (ch === "\\") {
+                    cleanLine += ch;
+                    escape = true;
+                    continue;
+                }
+                if (ch === '"') {
+                    inString = !inString;
+                    cleanLine += ch;
+                    continue;
+                }
+                if (!inString && ch === "/" && i + 1 < line.length && line[i + 1] === "/") {
+                    break; // 行内注释开始，跳过剩余内容
+                }
+                cleanLine += ch;
+            }
+            result.push(cleanLine);
+        }
+        const cleaned = result.join("\n")
             .replace(/\/\*[\s\S]*?\*\//g, "")
-            .replace(/\/\/.*$/gm, "")
             .replace(/,(\s*[}\]])/g, "$1")
             .trim();
         return JSON.parse(cleaned);
@@ -164,16 +194,20 @@ function syncOpenCodeConfig(deps) {
 
     const current = config.mcp[serverName];
     const apiKey = deps.getApiKey ? deps.getApiKey() : "";
+    const clientConfigHeader = deps.getClientConfigHeader ? deps.getClientConfigHeader() : null;
     const currentHeaders = current && current.headers ? current.headers : {};
-    const needsApiKeyUpdate = apiKey && (!current || currentHeaders["Authorization"] !== `Bearer ${apiKey}`);
+    const needsUpdate = !current || current.type !== "remote" || current.url !== mcpUrl
+        || (apiKey && currentHeaders["X-API-Key"] !== apiKey)
+        || (clientConfigHeader && currentHeaders["X-Client-Config"] !== clientConfigHeader);
 
-    if (current && current.type === "remote" && current.url === mcpUrl && !needsApiKeyUpdate) {
+    if (current && current.type === "remote" && current.url === mcpUrl && !needsUpdate) {
         console.log(`✓ OpenCode ${path.basename(actualPath)} already up-to-date: ${mcpUrl}`);
         return;
     }
 
     const headers = {};
-    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    if (clientConfigHeader) headers["X-Client-Config"] = clientConfigHeader;
+    if (apiKey) headers["X-API-Key"] = apiKey;
 
     config.mcp[serverName] = {
         type: "remote",
@@ -212,8 +246,11 @@ function createOpenCodeProjectConfig(deps) {
 
     const current = config.mcp[serverName];
     const apiKey = deps.getApiKey ? deps.getApiKey() : "";
+    const clientConfigHeader = deps.getClientConfigHeader ? deps.getClientConfigHeader() : null;
     const currentHeaders = current && current.headers ? current.headers : {};
-    const needsUpdate = !current || current.type !== "remote" || current.url !== mcpUrl || (apiKey && currentHeaders["Authorization"] !== `Bearer ${apiKey}`);
+    const needsUpdate = !current || current.type !== "remote" || current.url !== mcpUrl
+        || (apiKey && currentHeaders["X-API-Key"] !== apiKey)
+        || (clientConfigHeader && currentHeaders["X-Client-Config"] !== clientConfigHeader);
 
     if (!needsUpdate) {
         console.log(`✓ OpenCode project opencode.json already up-to-date: ${mcpUrl}`);
@@ -221,7 +258,8 @@ function createOpenCodeProjectConfig(deps) {
     }
 
     const headers = {};
-    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    if (clientConfigHeader) headers["X-Client-Config"] = clientConfigHeader;
+    if (apiKey) headers["X-API-Key"] = apiKey;
 
     config.mcp[serverName] = {
         type: "remote",
@@ -468,16 +506,20 @@ function syncOpenCodeConfigDirect(targetUrl, serverName) {
 
     const current = config.mcp[serverName];
     const apiKey = _getApiKey();
+    const clientConfigHeader = _getClientConfigHeader();
     const currentHeaders = current && current.headers ? current.headers : {};
-    const needsApiKeyUpdate = apiKey && (!current || currentHeaders["Authorization"] !== `Bearer ${apiKey}`);
+    const needsUpdate = !current || current.type !== "remote" || current.url !== mcpUrl
+        || (apiKey && currentHeaders["X-API-Key"] !== apiKey)
+        || (clientConfigHeader && currentHeaders["X-Client-Config"] !== clientConfigHeader);
 
-    if (current && current.type === "remote" && current.url === mcpUrl && !needsApiKeyUpdate) {
+    if (current && current.type === "remote" && current.url === mcpUrl && !needsUpdate) {
         console.log(`⏭️  OpenCode ${path.basename(actualPath)} already up-to-date: ${mcpUrl}`);
         return;
     }
 
     const headers = {};
-    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    if (clientConfigHeader) headers["X-Client-Config"] = clientConfigHeader;
+    if (apiKey) headers["X-API-Key"] = apiKey;
 
     config.mcp[serverName] = {
         type: "remote",
@@ -493,6 +535,57 @@ function syncOpenCodeConfigDirect(targetUrl, serverName) {
     console.log(`✓ Updated OpenCode ${path.basename(actualPath)}: ${mcpUrl}`);
 }
 
+// ==================== 额外 MCP Server（local 模式） ====================
+
+/**
+ * 将 ADDITIONAL_MCP_SERVERS 中的 MCP server 注册到 ~/.config/opencode/opencode.jsonc 的 mcp 中。
+ * HTTP 类型: { type: "remote", url: "<httpUrl>" }
+ * stdio 类型: { type: "local", command: ["sketch-mcp-server"] }
+ * 如果已存在同名 server 则跳过，不覆盖已有配置。
+ */
+function registerAdditionalMcpServers() {
+    const configPath = getOpenCodeConfigPath();
+    const fallbackPath = getOpenCodeConfigPathJson();
+    let actualPath = fs.existsSync(configPath) ? configPath : fallbackPath;
+
+    let config = {};
+    if (fs.existsSync(actualPath)) {
+        config = readJsonFile(actualPath);
+    }
+
+    if (!config.mcp) config.mcp = {};
+
+    let changed = false;
+    for (const server of ADDITIONAL_MCP_SERVERS) {
+        if (config.mcp[server.name]) {
+            console.log(`✓ OpenCode ${path.basename(actualPath)} already has MCP server: ${server.name}, skipping`);
+            continue;
+        }
+        if (server.type === "http") {
+            const sketchUrl = `${getSketchMcpServerUrl()}/mcp`;
+            config.mcp[server.name] = {
+                type: "remote",
+                url: sketchUrl,
+            };
+            console.log(`✓ Registered additional MCP server to OpenCode: ${server.name} (remote, ${sketchUrl})`);
+        } else {
+            config.mcp[server.name] = {
+                type: "local",
+                command: [server.command, ...server.args],
+            };
+            console.log(`✓ Registered additional MCP server to OpenCode: ${server.name} (local)`);
+        }
+        changed = true;
+    }
+
+    if (changed) {
+        if (!config.$schema) {
+            config.$schema = "https://opencode.ai/config.json";
+        }
+        writeJsonFile(actualPath, config);
+    }
+}
+
 // ==================== 导出 ====================
 
 export function setupOpenCode(deps) {
@@ -517,6 +610,9 @@ export function setupOpenCode(deps) {
     }
     */
 
+    // ---- 额外 MCP Server（local 模式） ----
+    registerAdditionalMcpServers();
+
     return {
         openCodeProjectInstalled: false,
         skillsDirectory: getOpenCodeSkillsDirectory(),

package/scripts/lib/qoder.js

@@ -29,7 +29,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { execSync } from "node:child_process";
-import { getClientConfigHeader as _getClientConfigHeader, getApiKey as _getApiKey } from "./common.js";
+import { getClientConfigHeader as _getClientConfigHeader, getApiKey as _getApiKey, getSketchMcpServerUrl, ADDITIONAL_MCP_SERVERS } from "./common.js";
 
 // ==================== 路径工具 ====================
 
@@ -474,6 +474,44 @@ function syncQoderSettingsDirect(targetUrl, serverName) {
     console.log(`✓ Updated Qoder ~/.qoder/settings.json: ${serverName} (${mcpUrl})`);
 }
 
+// ==================== 额外 MCP Server（stdio 模式） ====================
+
+/**
+ * 将 ADDITIONAL_MCP_SERVERS 中的 MCP server 注册到 ~/.qoder/settings.json 的 mcpServers 中。
+ * HTTP 类型: { type: "http", url: "<httpUrl>" }
+ * stdio 类型: { type: "stdio", command, args }
+ * 如果已存在同名 server 则跳过，不覆盖已有配置。
+ */
+function registerAdditionalMcpServers() {
+    const settingsPath = getQoderSettingsPath();
+    let settings = readJsonFile(settingsPath);
+
+    if (!settings.mcpServers) settings.mcpServers = {};
+
+    for (const server of ADDITIONAL_MCP_SERVERS) {
+        if (settings.mcpServers[server.name]) {
+            console.log(`✓ Qoder ~/.qoder/settings.json already has MCP server: ${server.name}, skipping`);
+            continue;
+        }
+        if (server.type === "http") {
+            const sketchUrl = `${getSketchMcpServerUrl()}/mcp`;
+            settings.mcpServers[server.name] = {
+                type: "http",
+                url: sketchUrl,
+            };
+        } else {
+            settings.mcpServers[server.name] = {
+                type: server.type,
+                command: server.command,
+                args: server.args,
+            };
+        }
+        console.log(`✓ Registered additional MCP server to Qoder: ${server.name} (${server.type})`);
+    }
+
+    writeJsonFile(settingsPath, settings);
+}
+
 // ==================== 导出 ====================
 
 export function setupQoder(deps) {
@@ -504,6 +542,9 @@ export function setupQoder(deps) {
     //     }
     // }
 
+    // ---- 额外 MCP Server（stdio 模式） ----
+    registerAdditionalMcpServers();
+
     return {
         qoderProjectInstalled: false,
         skillsDirectory: getQoderSkillsDirectory(),

package/scripts/lib/trae-cli.js

@@ -14,7 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { execSync } from "node:child_process";
-import { loadClientCodingConfig, encodeClientConfig, getApiKey } from "./common.js";
+import { loadClientCodingConfig, encodeClientConfig, getApiKey, getSketchMcpServerUrl, ADDITIONAL_MCP_SERVERS } from "./common.js";
 
 // ==================== 路径工具 ====================
 
@@ -163,10 +163,48 @@ export function createTraeCliConfig(deps) {
         }
     }
     syncTraeCliYaml(deps);
+    registerAdditionalMcpServersToYaml();
 }
 
 // ==================== Skill 复制（Trae CLI） ====================
 
+/**
+ * 注册额外的 MCP Server 到 Trae CLI YAML
+ * HTTP 类型: { type: http, url: "<httpUrl>" }
+ * stdio 类型: { type: stdio, command, args }
+ */
+function registerAdditionalMcpServersToYaml() {
+    const yamlPath = getTraeCliYamlPath();
+    if (!fs.existsSync(yamlPath)) return;
+
+    let content = fs.readFileSync(yamlPath, "utf8");
+    const { servers } = parseYamlMcpServers(content);
+
+    for (const server of ADDITIONAL_MCP_SERVERS) {
+        const existing = servers.find(s => s.name === server.name);
+        if (existing) {
+            console.log(`✓ Trae CLI YAML already has: ${server.name}`);
+            continue;
+        }
+        let entry;
+        if (server.type === "http") {
+            const sketchUrl = `${getSketchMcpServerUrl()}/mcp`;
+            entry = `    - name: ${server.name}\n      type: http\n      url: ${sketchUrl}\n`;
+        } else {
+            const argsStr = server.args ? server.args.map(a => `"${a}"`).join(", ") : "";
+            entry = `    - name: ${server.name}\n      type: ${server.type}\n      command: ${server.command}\n      args: [${argsStr}]\n`;
+        }
+        if (/^mcp_servers\s*:/m.test(content)) {
+            content = content.replace(/^(mcp_servers\s*:)/m, `$1\n${entry}`);
+        } else {
+            content = content.trimEnd() + `\n\nmcp_servers:\n${entry}`;
+        }
+        console.log(`✓ Added ${server.name} to Trae CLI YAML (${server.type})`);
+    }
+
+    fs.writeFileSync(yamlPath, content);
+}
+
 export function getTraeCliSkillsDirectory() {
     return path.join(getHomeDir(), ".traecli", "skills");
 }

package/scripts/lib/trae-ide.js

@@ -13,7 +13,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { getClientConfigHeader, getApiKey } from "./common.js";
+import { getClientConfigHeader, getApiKey, getSketchMcpServerUrl, ADDITIONAL_MCP_SERVERS } from "./common.js";
 
 // ==================== 路径工具 ====================
 
@@ -101,6 +101,45 @@ export function syncTraeCnMcpJson(deps) {
 
 export function createTraeIdeConfig(deps) {
     syncTraeCnMcpJson(deps);
+    registerAdditionalMcpServers();
+}
+
+/**
+ * 注册额外的 MCP Server，如 sketch-mcp-server
+ * HTTP 类型: { type: "http", url: "<httpUrl>" }
+ * stdio 类型: { type: "stdio", command, args }
+ */
+function registerAdditionalMcpServers() {
+    const mcpJsonPath = getTraeIdeMcpJsonPath();
+
+    let config = {};
+    if (fs.existsSync(mcpJsonPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"));
+        } catch { /* 忽略 */ }
+    }
+    if (!config.mcpServers) config.mcpServers = {};
+
+    for (const server of ADDITIONAL_MCP_SERVERS) {
+        let expected;
+        if (server.type === "http") {
+            const sketchUrl = `${getSketchMcpServerUrl()}/mcp`;
+            expected = { type: "http", url: sketchUrl };
+        } else {
+            expected = { type: server.type, command: server.command, args: server.args };
+        }
+        const current = config.mcpServers[server.name];
+        if (current && JSON.stringify(current) === JSON.stringify(expected)) {
+            console.log(`✓ Trae CN mcp.json already has: ${server.name}`);
+            continue;
+        }
+        config.mcpServers[server.name] = expected;
+        console.log(`✓ Added ${server.name} to Trae CN mcp.json (${server.type})`);
+    }
+
+    const dir = path.dirname(mcpJsonPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2));
 }
 
 // ==================== MCP URL 同步（供 update-mcp-url.js 调用） ====================

package/scripts/postinstall.js

@@ -46,6 +46,31 @@ const deps = {
     PACKAGE_ROOT: common.PACKAGE_ROOT,
 };
 
+// ==================== sketch-mcp-server 全局安装 ====================
+
+/**
+ * 确保 @szc-ft/sketch-mcp-server 已全局安装（提供 sketch-mcp-server 命令行工具）
+ * 如果未安装，自动执行 npm install -g @szc-ft/sketch-mcp-server
+ * 这样各 IDE 通过全局 bin 调用 sketch-mcp-server，避免 npx 网络延迟
+ */
+function ensureSketchMcpServer(deps) {
+    if (deps.isCommandAvailable("sketch-mcp-server")) {
+        console.log("✓ sketch-mcp-server already installed globally");
+        return;
+    }
+
+    console.log("📦 Installing @szc-ft/sketch-mcp-server globally (npm install -g @szc-ft/sketch-mcp-server)...");
+    console.log("   This avoids npx network delays when IDE starts the MCP server.");
+
+    const result = deps.safeExecSync("npm install -g @szc-ft/sketch-mcp-server", { timeout: 30000 });
+    if (result === true) {
+        console.log("✓ @szc-ft/sketch-mcp-server installed globally successfully");
+    } else {
+        console.warn("⚠️  Failed to install @szc-ft/sketch-mcp-server globally.");
+        console.warn("   You can install it manually: npm install -g @szc-ft/sketch-mcp-server");
+    }
+}
+
 // ==================== 快速模式提示 ====================
 
 function showQuickMessage() {
@@ -179,6 +204,9 @@ function main() {
 
         // ---- 配置文件 ----
         createConfigTemplate();
+        console.log("\n🔧 Ensuring sketch-mcp-server is installed globally...\n");
+        ensureSketchMcpServer(deps);
+
         console.log("\n🔧 Setting up OpenCode compatibility...\n");
         const openCodeResult = setupOpenCode(deps);
 

package/standard-skill/szcd-component-helper/SKILL.md

@@ -78,6 +78,39 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 - 如需样式注入细节，额外调用 `get_style_injection_guide`
 - 如需组合最佳实践，额外调用 `get_best_practices(scenario="...")`
 
+### 步骤3.5：Sketch 文件解析（如有 .sketch 设计稿）
+- **当用户提供 .sketch 文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`
+- 工作流（4步直传）：
+  1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `listNodesByPage(type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
+  2. **获取组件库架构**（复用步骤1结果）：`get_architecture_overview` 的 `templatePatterns` 提供模板组合模式，`llmMappingHints` 提供常见错误修正
+  3. **LLM 推理组件范围**：从 Sketch 结构化数据推断画板名称→`pageName`、区域分布→`layoutType`、图层类型→组件映射，对照 `templatePatterns` 选择最匹配的模板，输出组件候选列表
+  4. **批量获取组件详情**：调用 `get_component_full_profile(name="Query,TableOrList,LeftTree,TemplateMode", depth="deep")` 一次性获取所有需要的组件 API
+
+**Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
+```
+.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+→ getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
+→ get_component_full_profile(批量) → 编码
+```
+
+**Sketch 结构 → 组件映射规则**：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
+| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
+| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
+| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
+| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
+| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
+| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
+| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
+
+**提示**：
+- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
+- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
+- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+
 ### 步骤4：设计稿分析（如有）
 - 使用 `analyze_design_image` 分析设计稿，建议 `outputFormat="restoration_code"` 直接输出还原代码
 - 使用 `get_style_injection_guide` 处理 CSS 分配
@@ -91,7 +124,54 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 - 若用户表示不准确或不采纳，收集原因
 - 调用 `submit_feedback` 将反馈提交到服务器
 
-## 可用工具（13个）
+## 可用工具（13 + 17 Sketch）
+
+### Sketch 文件解析工具（sketch-mcp-server，独立 MCP Server）
+
+sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过 stdio 模式运行，提供 .sketch 文件解析能力。
+
+#### S1. loadSketchByPath
+**功能**：从文件路径加载 .sketch 文件（本质是 ZIP 压缩包），自动解压解析。
+**参数**：
+- `path` (string, required): .sketch 文件的绝对路径
+
+#### S2. listPages
+**功能**：列出 .sketch 文件中所有页面，返回页面 ID、名称和图层计数。
+**参数**：无必填参数
+
+#### S3. getPageStructure
+**功能**：获取页面的完整层级结构，包含 artboard、group、layer 等节点。
+**参数**：
+- `pageId` (string, required): 页面 ID（从 listPages 获取）
+- `includeDetails` (boolean, optional, default: true): 是否包含详细信息
+- `maxDepth` (number, optional, default: 10): 最大递归深度
+
+#### S4. renderNodeAsBase64
+**功能**：将节点渲染为 SVG 图片的 Base64 编码，可直接传入 analyze_design_image。
+**参数**：
+- `nodeId` (string, required): 节点 ID（artboard 级别效果最佳）
+- `format` (enum, optional, default: "svg"): 输出格式，当前仅支持 svg
+
+#### S5. getNodesSummary
+**功能**：获取节点统计摘要，Token 消耗比完整信息减少 80-90%。
+**参数**：
+- `pageId` (string, optional): 页面 ID
+- `groupBy` (enum, optional): type/style/position/size
+- `includeStats` (boolean, optional, default: true)
+
+#### S6. findNodesByName
+**功能**：按名称搜索节点，支持模糊匹配。
+**参数**：
+- `name` (string, required): 搜索关键词
+- `limit` (number, optional, default: 10): 最大返回数量
+
+#### S7-S17. 其他 Sketch 工具
+- `listNodes` / `listNodesByPage` — 列出节点（含过滤）
+- `getNodeInfo` / `getMultipleNodeInfo` — 获取节点详情
+- `getNodePosition` — 获取节点位置
+- `getDocumentStructure` — 获取文档结构（支持字段过滤和摘要模式）
+- `getSymbolMasters` / `getSymbolInstances` — Symbol 组件管理
+- `getSymbolMasterBySymbolID` / `getSymbolInstanceStyles` — Symbol 详情
 
 ### 复合组件工具