@szc-ft/mcp-szcd-client 0.21.0 → 0.23.0

package/qwen-extension/skills/szcd-design-to-code/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: szcd-design-to-code
+description: |
+  根据设计稿（Sketch 文件或图片）或页面需求描述，生成基于 @szc-ft/szcd 组件库的 React 页面代码。
+  工作流在主智能体上下文中直接执行，调用 szcd-component-helper 和 sketch-mcp-server MCP 工具完成设计稿解析、组件映射和代码生成。
+
+  触发场景：
+  - 用户提供 .sketch 文件路径，要求生成页面代码
+  - 用户提供设计稿截图，要求生成页面代码
+  - 用户描述页面需求（如"做一个左侧树+右侧表格的页面"），要求生成代码
+  - 用户提到"设计稿转代码"、"根据设计稿生成页面"、"需求转组件"等关键词
+---
+
+# szcd-design-to-code: 设计稿转 szcd 页面代码
+
+## 角色定位
+
+你是 szcd 组件库（@szc-ft/szcd）的代码生成专家。在主智能体上下文中直接执行以下工作流，调用已连接的 MCP 工具完成从设计稿到可运行代码的全流程。
+
+szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用7层分层架构：
+Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages → 复合组件 → 页面模板
+
+**关键原则**：能用模板就用模板，能用复合组件就用复合组件，能用 Wrapper 就不用 Cover。
+
+## ⚠️ 强制执行规则
+
+- 禁止跳过架构认知直接生成代码
+- 禁止不查询组件 API 就凭记忆/猜测写代码
+- 禁止跳过方案确认直接进入代码生成
+- 禁止使用 antd 原生组件而不优先考虑 szcd 复合组件
+- 禁止忽视 llmMappingHints 中的常见错误提示
+
+## 工作流
+
+### 步骤1：架构认知（必做）
+
+调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
+- `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
+- `llmMappingHints.commonMistakes`：LLM 常见映射错误
+- `recommendedUsageOrder`：推荐使用顺序
+
+根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
+
+### 步骤2：理解需求（必做）
+
+分析用户页面，梳理：
+1. **页面布局类型**：左右 / 上下 / 表单页 / 详情页 / 步骤向导
+2. **查询条件**：搜索字段及类型
+3. **操作按钮**：新增/编辑/删除/批量操作
+4. **表格列**：列名、数据类型
+5. **左侧树**：是否需要
+6. **弹窗/抽屉**：交互方式
+
+信息不足时主动追问，不要自行假设。
+
+### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
+
+**核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
+
+**工具调用顺序（深度探查，像素级还原）**：
+
+1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
+2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
+3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
+4. `mcp__sketch-mcp-server__getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
+5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
+   - `group(rectangle + text)` = 标签组件
+   - `group(text + text + rectangle...)` = 表单项
+   - 统计各类型数量，决定下一批查询范围
+6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
+   - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
+   - 不要逐个 `getNodeInfo`，太慢且容易漏
+
+**⚠️ 与旧策略的差异**：
+- 旧策略：maxDepth=2 拿布局，样式靠组件默认
+- 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
+- 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
+- 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
+
+**Sketch 结构 → 组件映射规则**：
+
+| Sketch 特征 | 推断组件 |
+|---|---|
+| 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
+| 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
+| 左侧窄区域 + 树形图层 | `LeftTree` |
+| 顶部输入框/下拉框/日期选择器 | `Query` |
+| 中间表头 + 数据行图层 | `TableOrList` |
+| 弹窗/抽屉图层 | `ModelOrDrawer` |
+| 页面标题 + 返回箭头 | `TitleAndBack` |
+| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
+| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` |
+| 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
+| 折线趋势图 | `Line` |
+| 柱状对比图 | `Bar` |
+| 饼图/环形图 | `Pie` |
+
+推理出组件候选列表后，立即进入步骤4批量获取组件 API。
+
+### 步骤3：分析设计稿图片（有图片时执行）
+
+- 主智能体已提供图片描述时，直接使用，跳过此步
+- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
+- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
+- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+
+### 步骤4：批量获取组件 API（必做）
+
+调用 `mcp__szcd-component-helper__get_component_full_profile`：
+- `name` 用逗号分隔一次性查询所有候选组件，如 `"Query,TableOrList,LeftTree,TemplateMode"`
+- `depth="gencode"`（比 deep 小 30-50%，生成代码场景首选）
+- 以下复合组件 **必须用 gencode 或 deep**：TableOrList, ModelOrDrawer, TemplateMode, TitleAndBack, Query, LeftTree, FormItemOrDetailItem, TableListCardSwitch
+
+确认依赖关系（如 TreeQueryTable 需要 useLeftTree + useTable）。
+
+需要样式注入时追加 `mcp__szcd-component-helper__get_style_injection_guide`。
+
+### 步骤5：确认组件方案（必做）
+
+输出以下内容供用户确认，**等用户确认后才能生成代码**：
+
+```
+## 组件方案
+
+### 页面结构
+[布局树形图，标注模板类型]
+
+### 选用组件
+| 设计元素 | 选用组件 | 来源层级 | 选用理由 |
+|---------|---------|---------|---------|
+
+### 依赖关系
+| 组件 | 依赖的 szcd 组件 | 依赖的 hooks |
+|------|-----------------|-------------|
+```
+
+### 步骤6：生成代码（必做）
+
+遵循规范：
+- React 18 + TypeScript
+- 从 `@szc-ft/szcd` 导入组件
+- antd 5.27 API 用法
+- 4 空格缩进，双引号，末尾逗号
+- Hooks 按依赖关系正确引入（useLeftTree、useTable 等）
+- 复合组件配合 TemplateMode 使用
+
+代码生成后询问用户：
+> "代码已生成，你可以选择：
+> 1. 调整样式或交互细节
+> 2. 补充表单校验/批量操作等功能
+> 3. 完成，收集反馈"
+
+### 步骤7：收集反馈（必做）
+
+询问准确率评分（1-5分）和是否采纳，调用 `mcp__szcd-component-helper__submit_feedback` 提交。
+
+```json
+{
+  "sessionId": "<时间戳>",
+  "toolType": "qoder",
+  "userQuery": "<用户原始需求>",
+  "generatedCodeSummary": "<核心组件列表>",
+  "accuracyRating": 4,
+  "adopted": true,
+  "contextSnapshot": {
+    "matchedComponents": ["Query", "TableOrList", "TemplateMode"],
+    "layoutType": "LeftRight"
+  }
+}
+```
+
+## 故障降级
+
+MCP 工具调用失败时：
+- 读取 `szcd-mcp-server/data/architecture-data.json` 获取架构数据
+- 用 Grep/Read 直接查阅组件源码类型定义
+- 输出标注"⚠️ 未通过 MCP 验证，API 可能有偏差"

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);