@szc-ft/mcp-szcd-client 0.32.1 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.32.1",
+    "version": "0.34.0",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",
@@ -22,6 +22,7 @@
     "bin": {
         "szcd-mcp-proxy": "mcp-proxy.js",
         "szcd-mcp-setup": "scripts/postinstall.js",
+        "szcd-mcp-install-shortcuts": "scripts/install-dev-shortcuts.js",
         "szcd-mcp-update-url": "scripts/update-mcp-url.js",
         "szcd-mcp-coding-config": "scripts/update-coding-config.js",
         "szcd-mcp-api-config": "scripts/update-api-config.js",
@@ -32,6 +33,7 @@
         "local-browser-executor.js",
         "lib/",
         "scripts/postinstall.js",
+        "scripts/install-dev-shortcuts.js",
         "scripts/update-mcp-url.js",
         "scripts/update-coding-config.js",
         "scripts/update-api-config.js",

package/qwen-extension/qwen-extension.json

@@ -1,6 +1,6 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.32.1",
+    "version": "0.34.0",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {

package/scripts/install-dev-shortcuts.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * install-dev-shortcuts.js — 手动重跑 dev-browser 快捷方式安装的 CLI
+ *
+ * 用途：postinstall 静默失败时（特别是 Windows 中文系统、AV 拦截、ExecutionPolicy 等）
+ * 用户跑 `npx szcd-mcp-install-shortcuts` 单独重试并看到完整错误信息。
+ *
+ * 与 postinstall 调用同一个 setupDevBrowserShortcut；本 CLI 区别在于：
+ *   1. 进程退出码：失败时 exit 1（postinstall 是 exit 0 不阻塞 npm install）
+ *   2. 输出更详细：直接传入 process 的 stdout / stderr，不被 npm install 折叠
+ *   3. 文末汇总：成功/失败计数 + 每条失败的完整错误，便于贴回 issue
+ */
+
+import { setupDevBrowserShortcut } from "./lib/dev-browser-shortcut.js";
+
+console.log("============================================================");
+console.log("  szcd-mcp dev-browser DevSession shortcut installer");
+console.log("============================================================");
+console.log(`Platform: ${process.platform}`);
+console.log(`Node:     ${process.version}`);
+console.log("");
+
+const result = setupDevBrowserShortcut({});
+
+console.log("");
+console.log("============================================================");
+console.log("  Summary");
+console.log("============================================================");
+if (result.skipped) {
+    console.log("⚠️  No Chrome/Edge detected on this machine.");
+    console.log("    Install Google Chrome or Microsoft Edge, then re-run this command.");
+    process.exit(1);
+}
+
+const okCount = result.results.filter(r => r.ok).length;
+const total = result.results.length;
+console.log(`Installed: ${okCount}/${total}`);
+for (const r of result.results) {
+    if (r.ok) {
+        console.log(`  ✓ ${r.name}: ${r.path}`);
+    } else {
+        console.log(`  ✗ ${r.name}:`);
+        for (const line of String(r.error || "(unknown error)").split("\n")) {
+            console.log(`      ${line}`);
+        }
+    }
+}
+console.log("");
+
+process.exit(result.ok ? 0 : 1);

package/scripts/lib/codex.js

@@ -0,0 +1,260 @@
+/**
+ * codex.js — OpenAI Codex CLI 兼容逻辑
+ *
+ * 导出 setupCodex(deps) 供 postinstall.js 调用。
+ *
+ * Codex CLI 关键事实（来源：github.com/openai/codex codex-rs/cli/src/mcp_cmd.rs +
+ * developers.openai.ac.cn/codex/skills + 本机 codex-cli 0.142.0 实测）：
+ *   - 安装：npm i -g @openai/codex（提供 `codex` 命令）
+ *   - 配置文件：$CODEX_HOME/config.toml（默认 ~/.codex/config.toml），TOML 格式
+ *   - MCP server 节段：[mcp_servers.<NAME>]，扁平字段，无 transport 子表、无 type/enabled：
+ *     · stdio：command = "..."，可选 args/env
+ *     · streamable_http：url = "..."，可选 bearer_token_env_var
+ *     CLI 通过是否存在 url/command 自动识别 transport 类型
+ *   - 管理子命令：codex mcp { list | get | add | remove }
+ *   - Skill 目录（用户级）：$HOME/.agents/skills/<skill-name>/SKILL.md（不是 ~/.codex/skills/，
+ *     与 Codex CLI 自己的 home 分离；同一 .agents/skills/ 也被其它走 "open agent skills 规范"
+ *     的客户端共享）。Codex 还会读仓库级 .agents/skills，但 postinstall 不应碰用户仓库。
+ *   - Skill 格式：目录形式，必含 SKILL.md（YAML frontmatter: name/description + Markdown 正文），
+ *     可选 scripts/、references/、assets/、agents/openai.yaml 等子目录。无需 CLI 注册，
+ *     放文件即生效；变更后重启 Codex。
+ *
+ * 本实现策略：
+ *   1. MCP：优先 spawn `codex mcp remove` 再 `codex mcp add`（CLI 自己做 TOML 合并 + 幂等）
+ *   2. MCP fallback：找不到 `codex` 时直接写 config.toml（扁平 TOML，与 CLI 序列化一致）
+ *   3. Skill：调用 deps.copySkill(...) 把 standard-skill/* 整目录拷到 ~/.agents/skills/
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execSync } from "node:child_process";
+import { getSketchMcpServerUrl, ADDITIONAL_MCP_SERVERS } from "./common.js";
+
+// ==================== 路径工具 ====================
+
+function getHomeDir() {
+    if (os.platform() === "win32") {
+        return process.env.USERPROFILE || process.env.HOME || os.homedir();
+    }
+    return process.env.HOME || os.homedir();
+}
+
+function getCodexHome() {
+    return process.env.CODEX_HOME || path.join(getHomeDir(), ".codex");
+}
+
+function getCodexConfigPath() {
+    return path.join(getCodexHome(), "config.toml");
+}
+
+function isCodexCliAvailable() {
+    try {
+        execSync("codex --version", { stdio: "pipe", timeout: 5000 });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// ==================== TOML 序列化（最小子集，够本场景用） ====================
+
+/**
+ * 把单个 mcp server 渲染成 TOML（与 codex CLI 实际序列化格式一致：扁平、无 transport 子表）。
+ *
+ * stdio:
+ *   [mcp_servers.NAME]
+ *   command = "..."
+ *   args = ["...", "..."]
+ *
+ * streamable_http:
+ *   [mcp_servers.NAME]
+ *   url = "https://..."
+ *
+ * 注：codex CLI 0.142 实测产物不写 `type`、`enabled`、`transport`，
+ * 由它根据是否有 url/command 字段自动识别。手写 TOML 必须与 CLI 一致，
+ * 否则 CLI 下次 `mcp add/remove` 重写时会丢失字段。
+ */
+function renderStdioServerToml(name, command, args = []) {
+    const lines = [
+        `[mcp_servers.${name}]`,
+        `command = ${tomlString(command)}`,
+    ];
+    if (args.length) {
+        lines.push(`args = [${args.map(tomlString).join(", ")}]`);
+    }
+    return lines.join("\n");
+}
+
+function renderHttpServerToml(name, url, bearerTokenEnvVar) {
+    const lines = [
+        `[mcp_servers.${name}]`,
+        `url = ${tomlString(url)}`,
+    ];
+    if (bearerTokenEnvVar) {
+        lines.push(`bearer_token_env_var = ${tomlString(bearerTokenEnvVar)}`);
+    }
+    return lines.join("\n");
+}
+
+function tomlString(s) {
+    // basic TOML string: 双引号 + 转义反斜杠/双引号/换行
+    return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n") + '"';
+}
+
+// ==================== 文件级合并（CLI 不可用时回退） ====================
+
+/**
+ * 读取已有 config.toml，移除本包负责的 [mcp_servers.<name>] / [mcp_servers.<name>.transport]
+ * 整段（直到下一个 [...]），然后追加新的渲染结果。
+ *
+ * 不引入完整 TOML 解析器（用户其它 server / 顶层 settings 用纯文本保留，最稳）。
+ */
+function upsertCodexConfig(configPath, ourServers) {
+    let existing = "";
+    if (fs.existsSync(configPath)) {
+        existing = fs.readFileSync(configPath, "utf8");
+    }
+
+    // 移除我们要写的每个 server 的旧 [mcp_servers.NAME] 整段（直到下一个 [...] 或文件末）
+    for (const s of ourServers) {
+        const sectionRegex = new RegExp(
+            `(^|\\n)\\[mcp_servers\\.${escapeRegex(s.name)}\\][^\\n]*\\n` +
+            `(?:(?!\\n\\[)[\\s\\S])*?(?=\\n\\[|$)`,
+            "g"
+        );
+        existing = existing.replace(sectionRegex, "");
+    }
+    // 收尾：折叠多余空行 / 保证末尾有换行
+    existing = existing.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "").trimEnd();
+
+    const newBlocks = ourServers.map(s => {
+        if (s.kind === "stdio") return renderStdioServerToml(s.name, s.command, s.args);
+        return renderHttpServerToml(s.name, s.url, s.bearerTokenEnvVar);
+    }).join("\n\n");
+
+    const sep = existing.length ? "\n\n" : "";
+    return existing + sep + newBlocks + "\n";
+}
+
+function escapeRegex(s) {
+    return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ==================== CLI 优先路径 ====================
+
+function addServerViaCli(server) {
+    // codex mcp add NAME --url URL                       (HTTP)
+    // codex mcp add NAME [--env K=V]... -- COMMAND ARGS  (stdio)
+    let cmd;
+    if (server.kind === "http") {
+        cmd = `codex mcp add ${shellEscape(server.name)} --url ${shellEscape(server.url)}`;
+    } else {
+        const args = (server.args || []).map(shellEscape).join(" ");
+        cmd = `codex mcp add ${shellEscape(server.name)} -- ${shellEscape(server.command)}${args ? " " + args : ""}`;
+    }
+    try {
+        // 先 remove 再 add，保证幂等（add 在已存在时会报错）
+        execSync(`codex mcp remove ${shellEscape(server.name)}`, { stdio: "pipe", timeout: 8000 });
+    } catch { /* 没有就忽略 */ }
+    try {
+        execSync(cmd, { stdio: "pipe", timeout: 10000 });
+        return { ok: true, via: "cli" };
+    } catch (e) {
+        return { ok: false, via: "cli", error: String(e.stderr || e.message).slice(0, 300) };
+    }
+}
+
+function shellEscape(s) {
+    // 简单版：含空格/特殊字符的串用单引号包，单引号本身转义为 '"'"'
+    if (/^[A-Za-z0-9_\-./:@=]+$/.test(s)) return s;
+    return `'${String(s).replace(/'/g, `'"'"'`)}'`;
+}
+
+// ==================== Skill 复制 ====================
+
+function getCodexSkillsDirectory() {
+    return path.join(getHomeDir(), ".agents", "skills");
+}
+
+function copySkillsToCodex(deps) {
+    if (typeof deps.discoverSkills !== "function" || typeof deps.copySkill !== "function") {
+        console.log("ℹ️  deps.discoverSkills / deps.copySkill not provided — skipping Codex skill copy");
+        return { ok: false, skipped: true };
+    }
+    const skillsRoot = getCodexSkillsDirectory();
+    const skills = deps.discoverSkills();
+    const results = [];
+    for (const skill of skills) {
+        const skillDir = path.join(skillsRoot, skill.name);
+        try {
+            deps.ensureDirectory?.(skillDir) ?? fs.mkdirSync(skillDir, { recursive: true });
+            const dest = path.join(skillDir, "SKILL.md");
+            deps.copySkill(skill.sourcePath, dest);
+            console.log(`✓ Copied skill "${skill.name}" to Codex (${skillDir})`);
+            results.push({ name: skill.name, ok: true, path: skillDir });
+        } catch (e) {
+            console.warn(`⚠️  Failed to copy skill "${skill.name}" to Codex: ${e.message}`);
+            results.push({ name: skill.name, ok: false, error: e.message });
+        }
+    }
+    return { ok: results.every(r => r.ok), results, skillsRoot };
+}
+
+// ==================== 主入口 ====================
+
+export function setupCodex(deps) {
+    // 1) 构造我们要注册的两个 server
+    const httpUrl = (deps.getMcpServerUrl?.() || "http://localhost:3456") + "/mcp";
+    const serverName = deps.getMcpServerName?.() || "szcd-component-helper";
+
+    const ourServers = [
+        // szcd 主 server：HTTP（与其它 IDE 一致；本地 server 无鉴权，故不带 bearer）
+        { kind: "http", name: serverName, url: httpUrl },
+        // sketch-mcp-server：stdio
+        ...ADDITIONAL_MCP_SERVERS.filter(s => s.type === "stdio").map(s => ({
+            kind: "stdio", name: s.name, command: s.command, args: s.args || [],
+        })),
+    ];
+
+    // 2) MCP 注册
+    const mcpResult = registerMcpServers(ourServers);
+
+    // 3) Skill 复制（独立于 MCP 注册成败，文件操作本身基本不会失败）
+    const skillResult = copySkillsToCodex(deps);
+
+    return { mcp: mcpResult, skill: skillResult };
+}
+
+function registerMcpServers(ourServers) {
+    const cliAvailable = isCodexCliAvailable();
+    if (cliAvailable) {
+        console.log("✓ codex CLI detected — registering MCP servers via `codex mcp add`");
+        const cliResults = [];
+        for (const s of ourServers) {
+            const r = addServerViaCli(s);
+            cliResults.push({ name: s.name, ...r });
+            if (r.ok) console.log(`  ✓ codex mcp add ${s.name} (${s.kind})`);
+            else console.warn(`  ⚠️  codex mcp add ${s.name} failed: ${r.error}`);
+        }
+        const allOk = cliResults.every(r => r.ok);
+        if (allOk) return { ok: true, via: "cli", servers: cliResults };
+        console.log("→ CLI partial failure, falling back to direct config.toml edit");
+    } else {
+        console.log("ℹ️  codex CLI not installed (you can install via `npm i -g @openai/codex`)");
+        console.log("   Writing config.toml directly so it works once Codex is installed.");
+    }
+
+    // 回退：直接写 config.toml
+    const configPath = getCodexConfigPath();
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        const merged = upsertCodexConfig(configPath, ourServers);
+        fs.writeFileSync(configPath, merged);
+        console.log(`✓ Wrote Codex MCP config: ${configPath}`);
+        return { ok: true, via: "config-toml", configPath, servers: ourServers.map(s => s.name) };
+    } catch (e) {
+        console.warn(`⚠️  Failed to write ${configPath}: ${e.message}`);
+        return { ok: false, error: e.message };
+    }
+}

package/scripts/lib/dev-browser-shortcut.js

@@ -19,7 +19,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { execSync } from "node:child_process";
+import { execSync, spawnSync } from "node:child_process";
 
 // 与 SKILL.md 第 186-191 行保持一致
 const CDP_PORT = 9222;
@@ -117,12 +117,40 @@ function installWindows(browser) {
     ].join("; ");
     // -EncodedCommand 要求脚本块本身是 UTF-16LE base64
     const encoded = Buffer.from(psScript, "utf16le").toString("base64");
-    try {
-        execSync(`powershell -NoProfile -ExecutionPolicy Bypass -EncodedCommand ${encoded}`, { stdio: "ignore" });
-        return { ok: true, path: lnkPath };
-    } catch (e) {
-        return { ok: false, error: e.message };
+
+    // 反馈 #18（2026-06-24, accuracy=1）：原先用
+    //   execSync('powershell ... -EncodedCommand ...', { stdio: 'ignore' })
+    // 在中文 Windows + 全局 npm install 场景下静默失败：execSync 经 cmd.exe /d /s /c
+    // 调用 PowerShell，中文 Windows 下 PowerShell 启动期向 stderr 写 CLIXML
+    // (progress/information record)，stdio:'ignore' 导致 stderr 写入失败，
+    // PowerShell 以 exit code 1 终止，CreateShortcut COM 调用未执行；
+    // 外层 try/catch 仅 console.warn，postinstall 整体仍成功，用户无法察觉。
+    //
+    // 修复：用 spawnSync 直接调 powershell.exe，绕开 cmd.exe；stderr/stdout 用 pipe
+    // 而不是 ignore，捕获真实失败信息以便排查。
+    const result = spawnSync(
+        "powershell.exe",
+        ["-NoProfile", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded],
+        { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }
+    );
+    if (result.error) {
+        return { ok: false, error: `spawn failed: ${result.error.message}` };
     }
+    if (result.status !== 0) {
+        const stderr = (result.stderr?.toString() || "").trim();
+        const stdout = (result.stdout?.toString() || "").trim();
+        return {
+            ok: false,
+            error: `powershell exit code ${result.status}` +
+                   (stderr ? `\n  stderr: ${stderr.slice(0, 400)}` : "") +
+                   (stdout ? `\n  stdout: ${stdout.slice(0, 200)}` : ""),
+        };
+    }
+    // 二次校验：文件实际存在再算成功
+    if (!fs.existsSync(lnkPath)) {
+        return { ok: false, error: `powershell exit 0 but ${lnkPath} not created` };
+    }
+    return { ok: true, path: lnkPath };
 }
 
 // 字符串 → UTF-8 bytes → base64，给 PowerShell 内联反序列化用
@@ -216,14 +244,15 @@ export function setupDevBrowserShortcut(deps = {}) {
             installLinux;
         for (const b of browsers) {
             const r = install(b);
-            results.push({ browser: b.id, ...r });
+            results.push({ browser: b.id, name: b.name, ...r });
             if (r.ok) {
                 console.log(`✓ Created ${b.name} DevSession shortcut: ${r.path}`);
             } else {
-                console.warn(`⚠️  Failed to create ${b.name} DevSession shortcut: ${r.error}`);
+                console.warn(`⚠️  Failed to create ${b.name} DevSession shortcut:\n  ${r.error}`);
             }
         }
         const okCount = results.filter(r => r.ok).length;
+        const failCount = results.length - okCount;
         if (okCount > 0) {
             const dirHint = platform === "win32" ? "桌面 (Desktop)"
                 : platform === "darwin" ? "~/Applications/ (Launchpad / Spotlight)"
@@ -231,7 +260,16 @@ export function setupDevBrowserShortcut(deps = {}) {
             console.log(`\n💡 Double-click the "DevSession" shortcut in ${dirHint} to start a CDP-enabled browser`);
             console.log(`   on port ${CDP_PORT} with an isolated profile, then re-run your local-browser-test plan.`);
         }
-        return { ok: okCount > 0, results };
+        if (failCount > 0) {
+            // 醒目告警 + 手动重跑命令（反馈 #18 要求）
+            console.warn("");
+            console.warn("⚠️  ============================================================");
+            console.warn(`⚠️   ${failCount}/${results.length} dev-browser shortcut(s) failed to install.`);
+            console.warn("⚠️   Re-run the dedicated CLI to retry with full diagnostics:");
+            console.warn("⚠️     npx szcd-mcp-install-shortcuts");
+            console.warn("⚠️  ============================================================");
+        }
+        return { ok: okCount > 0 && failCount === 0, results, platform };
     } catch (e) {
         console.warn(`⚠️  setupDevBrowserShortcut error: ${e.message}`);
         return { ok: false, results, error: e.message };

package/scripts/postinstall.js

@@ -24,6 +24,7 @@ import { setupClaudeCode } from "./lib/claude-code.js";
 import { setupOpenCode } from "./lib/opencode.js";
 import { setupQwenCode } from "./lib/qwen-code.js";
 import { setupQoder } from "./lib/qoder.js";
+import { setupCodex } from "./lib/codex.js";
 import { setupDevBrowserShortcut } from "./lib/dev-browser-shortcut.js";
 
 // 递归守卫在 common.js 加载时已执行
@@ -228,6 +229,10 @@ function main() {
         console.log("\n🔧 Setting up Qoder CLI compatibility...\n");
         const qoderResult = setupQoder(deps);
 
+        // ---- OpenAI Codex CLI ----
+        console.log("\n🔧 Setting up Codex CLI compatibility...\n");
+        setupCodex(deps);
+
         // ---- Dev Browser Shortcut（local-browser-test 一键启动） ----
         console.log("\n🔧 Setting up dev-browser shortcut for local-browser-test...\n");
         setupDevBrowserShortcut(deps);