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

package/qwen-extension/skills/local-browser-test/SKILL.md

@@ -68,6 +68,10 @@ AI 直接构造测试计划 JSON：
 | waitFor | 等待条件 | `selector` 或 `url`, `timeout` | `{ matched, waited }` |
 | evaluate | 执行 JS | `expression` | `{ result }` |
 | checkElement | 元素断言 | `selector`, `expect: {visible, minCount, maxCount, hasText}` | `{ passed, checks, elementCount }` |
+| findPage | 查找已打开的标签页 | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` | `{ found, url, title, totalPages }` |
+| findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
+| loginWait | 等待 SSO 登录完成 | `loginSelector`, `timeout`, `interval` | `{ loggedIn, elapsed, currentUrl }` |
+| aiAssert | 语义断言（截图+审查） | `assertion`, `filename` | `{ screenshotPath, assertion, needsVisualReview }` |
 
 ### 场景选择策略
 
@@ -85,6 +89,11 @@ AI 直接构造测试计划 JSON：
 **场景 D：仅页面检查**
 `navigate → waitFor → screenshot → evaluate(JS错误检查)`
 
+**场景 E：微前端 + SSO 登录（最常见生产场景）**
+`findPage(按路径发现标签页) → findFrame(按内容发现iframe) → 在 iframe 内执行功能步骤`
+
+> 微前端场景端口可变，优先用 `findPage` + `findFrame` 发现页面，而非硬编码 URL 导航。
+
 ### 构造步骤的指导原则
 
 1. **selector 必须从用户代码中读取，不要猜测**
@@ -96,19 +105,80 @@ AI 直接构造测试计划 JSON：
    - dataSource 有数据 → `expect: { minCount: 1 }`（检查行数）
 4. **compare 的 regions 从设计稿分析结果或组件布局推断**
 
+## 微前端测试指南（实战经验）
+
+项目多使用 wujie/qiankun 微前端，测试时需注意：
+
+### 端口可变问题（重点）
+微前端主应用和子应用的端口会变化，**不要在计划中硬编码 URL**。两种方案：
+
+**方案 A：`findPage` 发现已打开的标签页（推荐，connect 模式）**
+用户已在浏览器中打开了目标页面，按路径或标题发现：
+```json
+{ "type": "findPage", "urlIncludes": "knowledge-main" }
+{ "type": "findPage", "titleIncludes": "知识库" }
+```
+
+**方案 B：URL 模板变量 + `--base-url` 运行时传入**
+计划中使用占位符，运行时替换：
+```json
+{ "type": "navigate", "url": "{{baseUrl}}/knowledge-main/", "allowRedirects": true }
+```
+执行时传入：`--base-url http://localhost:9090`
+
+### SSO 登录重定向链
+主应用访问时会重定向到登录服务，登录后再跳回。
+
+```json
+{ "type": "navigate", "url": "{{baseUrl}}/app/", "allowRedirects": true, "redirectWait": 5000 }
+{ "type": "loginWait", "timeout": 120000, "loginSelector": "input[type='password']" }
+```
+
+- `allowRedirects: true` 使用 `domcontentloaded` 避免重定向链导致 page 对象销毁
+- `loginWait` 轮询检测登录页是否消失（用户手动登录）
+
+### iframe 内操作
+wujie 微前端子应用渲染在 blob URL iframe 中，**坐标点击无法到达 iframe 内容**。
+
+```json
+{ "type": "findFrame", "contentIncludes": "知识采编" }
+{ "type": "click", "selector": "a.edit-btn" }
+{ "type": "checkElement", "selector": "~.editKnowledge", "expect": { "minCount": 1 } }
+```
+
+- `findFrame` 支持 `urlIncludes`、`titleIncludes`、`contentIncludes` 多种发现方式
+- 优先用 `contentIncludes`（按页面文字内容查找），不依赖 URL/端口
+- `findFrame` 后，后续所有步骤自动在 iframe 内执行
+- iframe 内的 click 使用 `evaluate()` 触发 DOM click，不依赖坐标
+
+### CSS Modules 哈希类名
+项目使用 CSS Modules，类名会被哈希化（如 `editKnowledge___ynQgI`）。
+
+选择器语法：
+- `~.editKnowledge` → 自动转为 `[class*="editKnowledge"]`（模糊匹配）
+- `~#myId` → 自动转为 `[id*="myId"]`
+- 普通选择器（如 `.my-class`）保持精确匹配
+
+### puppeteer-core v22 注意事项
+- `page.$x()` 已移除，用 `evaluate` + `querySelectorAll` 替代
+- SVG 元素的 `className` 是 `SVGAnimatedString` 对象而非字符串，需先检查 `typeof`
+- 所有 `evaluate` 调用内部使用 `safeEval` 包装，自动处理 context destroyed 错误
+
 ## 执行命令
 
 ```bash
 node {client_install_path}/local-browser-executor.js \
   --plan '<测试计划JSON>' \
-  --output /tmp/browser-test-result.json
+  --output /tmp/browser-test-result.json \
+  --base-url http://localhost:8088
 ```
 
 也支持从文件读取计划：
 ```bash
 node {client_install_path}/local-browser-executor.js \
   --plan-file /tmp/test-plan.json \
-  --output /tmp/browser-test-result.json
+  --output /tmp/browser-test-result.json \
+  --base-url http://localhost:8088
 ```
 
 ### 可选参数
@@ -116,11 +186,37 @@ node {client_install_path}/local-browser-executor.js \
 - `--cdp-url http://localhost:9223`：指定非默认的 CDP 端口
 - `--page-url http://xxx/page`：connect 模式下指定目标页面
 
-## 依赖检查
+## AI 语义断言（aiAssert）
+
+`aiAssert` 截图后需要视觉审查，三级降级路由：
+
+### Level 1：你能读取图片
+直接读取截图文件，用你的视觉能力判断是否满足断言。
+
+### Level 2：你无法读图，但 MCP 服务器可用
+1. 调用 `get_upload_endpoint` 获取上传地址
+2. 用 curl 上传截图
+3. 调用 `assert_page_screenshot` 工具，传入 `upload_id` + 断言描述
+4. 工具返回 `{ passed, confidence, reasoning, details }`
+
+### Level 3：都没有
+降级为 `checkElement` 步骤，用 DOM 选择器做替代验证。
+
+**构造 aiAssert 步骤示例**：
+```json
+{ "type": "aiAssert", "assertion": "页面显示三栏布局，右侧有滚动条", "filename": "assert-layout.png" }
+{ "type": "aiAssert", "assertion": "表格至少有 5 行数据，包含姓名、手机号列" }
+{ "type": "aiAssert", "assertion": "表单包含必填标记和提交按钮" }
+```
+
+## 依赖管理
 
-如果执行报错依赖缺失，引导用户安装：
+浏览器测试依赖（puppeteer-core, pixelmatch, pngjs, sharp）采用**共享缓存**方案：
+- 首次使用时自动安装到 `~/.szcd-mcp/deps/`
+- 后续所有项目共享复用，无需重复安装
+- 如果自动安装失败，引导用户手动执行：
 ```bash
-npm install puppeteer-core pixelmatch pngjs sharp
+cd ~/.szcd-mcp/deps && npm install puppeteer-core pixelmatch pngjs sharp --registry=https://npmmirror.com
 ```
 
 ## 结果解读

package/scripts/lib/opencode.js

@@ -1,37 +1,525 @@
 /**
- * opencode.js — OpenCode 兼容逻辑
+ * opencode.js — OpenCode 全部兼容逻辑
  *
  * 导出 setupOpenCode(deps) 供 postinstall.js 调用。
- * deps 需包含: { getMcpServerUrl, PROJECT_ROOT, fs }
+ * 导出 syncMcpUrl(targetUrl, serverName) 供 update-mcp-url.js 调用。
+ *
+ * deps 需包含: { getMcpServerUrl, getMcpServerName, getApiKey, getClientConfigHeader,
+ *                safeExecSync, isCommandAvailable, ensureDirectory, copyFile, writeFile,
+ *                discoverSkills, PROJECT_ROOT, PACKAGE_ROOT, fs }
+ *
+ * OpenCode 配置方式（HTTP 直连模式）：
+ *   - 优先使用 CLI: opencode mcp add <name> --scope user --url <http-url>
+ *   - 回退方案: 直接修改 ~/.config/opencode/opencode.jsonc
+ *   - Skill 复制: ~/.config/opencode/skills/<serverName>/SKILL.md
+ *   - Agent 复制: ~/.config/opencode/agents/<agentName>.md
+ *   - Command 复制: ~/.config/opencode/commands/<commandName>.md
+ *
+ * OpenCode 目录结构：
+ *   ~/.config/opencode/
+ *   ├── opencode.jsonc       # 用户级配置（MCP servers 等）
+ *   ├── agents/              # 子代理
+ *   │   └── <agentName>.md
+ *   ├── skills/              # Skills
+ *   │   └── <skillName>/
+ *   │       └── SKILL.md
+ *   └── commands/            # 自定义命令
+ *       └── <commandName>.md
+ *
+ * 项目级配置（项目根目录）：
+ *   <project>/
+ *   ├── opencode.json        # 项目级 MCP 配置
+ *   ├── .opencode/
+ *   │   ├── agents/
+ *   │   ├── skills/
+ *   │   └── commands/
  */
 
 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";
 
-export function setupOpenCode(deps) {
-    const projectRoot = deps.PROJECT_ROOT;
-    const opencodeConfigPath = path.join(projectRoot, "opencode.json");
+// ==================== 路径工具 ====================
+
+function getHomeDir() {
+    if (os.platform() === "win32") {
+        return process.env.USERPROFILE || process.env.HOME || os.homedir();
+    }
+    return process.env.HOME || os.homedir();
+}
+
+function getOpenCodeConfigDir() {
+    return path.join(getHomeDir(), ".config", "opencode");
+}
+
+function getOpenCodeConfigPath() {
+    // opencode.jsonc 优先，回退 opencode.json
+    return path.join(getOpenCodeConfigDir(), "opencode.jsonc");
+}
+
+function getOpenCodeConfigPathJson() {
+    return path.join(getOpenCodeConfigDir(), "opencode.json");
+}
+
+function getOpenCodeSkillsDirectory() {
+    return path.join(getOpenCodeConfigDir(), "skills");
+}
+
+function getOpenCodeAgentsDirectory() {
+    return path.join(getOpenCodeConfigDir(), "agents");
+}
+
+function getOpenCodeCommandsDirectory() {
+    return path.join(getOpenCodeConfigDir(), "commands");
+}
+
+function getOpenCodeProjectConfigPath(projectRoot) {
+    return path.join(projectRoot, "opencode.json");
+}
+
+function getOpenCodeProjectSkillsDirectory(projectRoot) {
+    return path.join(projectRoot, ".opencode", "skills");
+}
+
+function getOpenCodeProjectAgentsDirectory(projectRoot) {
+    return path.join(projectRoot, ".opencode", "agents");
+}
+
+function getOpenCodeProjectCommandsDirectory(projectRoot) {
+    return path.join(projectRoot, ".opencode", "commands");
+}
+
+// ==================== JSON 读写 ====================
+
+function readJsonFile(filePath) {
+    if (!fs.existsSync(filePath)) return {};
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        // jsonc 支持：简单去除注释（// 和 /* */）
+        const cleaned = content
+            .replace(/\/\*[\s\S]*?\*\//g, "")
+            .replace(/\/\/.*$/gm, "")
+            .replace(/,(\s*[}\]])/g, "$1")
+            .trim();
+        return JSON.parse(cleaned);
+    } catch {
+        return {};
+    }
+}
+
+function writeJsonFile(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+// ==================== MCP 配置 ====================
+
+/**
+ * 方式1: 通过 CLI 配置 MCP 服务器（推荐）
+ * opencode mcp add <name> --scope user --url <http-url>
+ */
+function createOpenCodeUserConfig(deps) {
+    if (deps.isCommandAvailable("opencode")) {
+        const mcpUrl = `${deps.getMcpServerUrl()}/mcp`;
+        const serverName = deps.getMcpServerName();
+
+        const result = deps.safeExecSync(`opencode mcp add ${serverName} --scope user --url ${mcpUrl}`);
+        if (result === true) {
+            console.log(`✓ OpenCode user MCP server added via CLI: ${serverName} (${mcpUrl})`);
+        } else if (result === "already_exists") {
+            console.log(`✓ OpenCode user MCP server already configured: ${serverName} (${mcpUrl})`);
+        } else {
+            console.warn(`⚠️  Failed to configure OpenCode MCP server via CLI (config file will be updated directly)`);
+        }
+    } else {
+        console.log("⏭️  Skipping OpenCode CLI config: opencode command not found");
+    }
 
-    if (fs.existsSync(opencodeConfigPath)) {
-        console.log(`✓ opencode.json already exists: ${opencodeConfigPath}`);
+    syncOpenCodeConfig(deps);
+}
+
+/**
+ * 方式2: 直接文件操作同步 ~/.config/opencode/opencode.jsonc
+ */
+function syncOpenCodeConfig(deps) {
+    const configPath = getOpenCodeConfigPath();
+    const fallbackPath = getOpenCodeConfigPathJson();
+    const mcpUrl = `${deps.getMcpServerUrl()}/mcp`;
+    const serverName = deps.getMcpServerName();
+
+    // 优先使用 jsonc，不存在则使用 json
+    let actualPath = fs.existsSync(configPath) ? configPath : fallbackPath;
+
+    let config = {};
+    if (fs.existsSync(actualPath)) {
+        config = readJsonFile(actualPath);
+    }
+
+    if (!config.mcp) config.mcp = {};
+
+    const current = config.mcp[serverName];
+    const apiKey = deps.getApiKey ? deps.getApiKey() : "";
+    const currentHeaders = current && current.headers ? current.headers : {};
+    const needsApiKeyUpdate = apiKey && (!current || currentHeaders["Authorization"] !== `Bearer ${apiKey}`);
+
+    if (current && current.type === "remote" && current.url === mcpUrl && !needsApiKeyUpdate) {
+        console.log(`✓ OpenCode ${path.basename(actualPath)} already up-to-date: ${mcpUrl}`);
         return;
     }
 
-    const opencodeConfig = {
-        $schema: "https://opencode.ai/config.json",
-        autoupdate: "notify",
-        instructions: ["请使用中文回复所有问题"],
-        mcp: {
-            "szcd-component-helper": {
-                type: "local",
-                command: ["npx", "szcd-mcp-proxy"],
-                environment: {
-                    MCP_SERVER_URL: deps.getMcpServerUrl(),
-                },
-            },
-        },
+    const headers = {};
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+
+    config.mcp[serverName] = {
+        type: "remote",
+        url: mcpUrl,
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
     };
 
-    deps.writeFile(opencodeConfigPath, JSON.stringify(opencodeConfig, null, 2));
-    console.log(`✓ Created opencode.json: ${opencodeConfigPath}`);
+    // 确保 $schema 存在
+    if (!config.$schema) {
+        config.$schema = "https://opencode.ai/config.json";
+    }
+
+    writeJsonFile(actualPath, config);
+    console.log(`✓ Updated OpenCode ${path.basename(actualPath)}: ${mcpUrl}`);
+}
+
+/**
+ * 项目级 MCP 配置
+ */
+function createOpenCodeProjectConfig(deps) {
+    if (!deps.PROJECT_ROOT || !fs.existsSync(deps.PROJECT_ROOT)) {
+        return false;
+    }
+
+    const projectConfigPath = getOpenCodeProjectConfigPath(deps.PROJECT_ROOT);
+    const mcpUrl = `${deps.getMcpServerUrl()}/mcp`;
+    const serverName = deps.getMcpServerName();
+
+    // 如果项目已有 opencode.json，检查是否需要更新
+    let config = {};
+    if (fs.existsSync(projectConfigPath)) {
+        config = readJsonFile(projectConfigPath);
+    }
+
+    if (!config.mcp) config.mcp = {};
+
+    const current = config.mcp[serverName];
+    const apiKey = deps.getApiKey ? deps.getApiKey() : "";
+    const currentHeaders = current && current.headers ? current.headers : {};
+    const needsUpdate = !current || current.type !== "remote" || current.url !== mcpUrl || (apiKey && currentHeaders["Authorization"] !== `Bearer ${apiKey}`);
+
+    if (!needsUpdate) {
+        console.log(`✓ OpenCode project opencode.json already up-to-date: ${mcpUrl}`);
+        return true;
+    }
+
+    const headers = {};
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+
+    config.mcp[serverName] = {
+        type: "remote",
+        url: mcpUrl,
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
+    };
+
+    if (!config.$schema) {
+        config.$schema = "https://opencode.ai/config.json";
+    }
+
+    writeJsonFile(projectConfigPath, config);
+    console.log(`✓ Created/Updated OpenCode project config: ${projectConfigPath}`);
+    return true;
+}
+
+// ==================== Skill 复制 ====================
+
+function copySkillToOpenCode(deps, isProjectLevel = false) {
+    let openCodeSkillsDir;
+
+    if (isProjectLevel) {
+        openCodeSkillsDir = getOpenCodeProjectSkillsDirectory(deps.PROJECT_ROOT);
+    } else {
+        openCodeSkillsDir = getOpenCodeSkillsDirectory();
+    }
+
+    const skills = deps.discoverSkills();
+    let allOk = true;
+
+    for (const skill of skills) {
+        const skillDir = path.join(openCodeSkillsDir, skill.name);
+        try {
+            deps.ensureDirectory(skillDir);
+            const skillDest = path.join(skillDir, "SKILL.md");
+            deps.copyFile(skill.sourcePath, skillDest);
+            console.log(`✓ Copied skill "${skill.name}" to OpenCode ${isProjectLevel ? 'project' : 'user'} directory: ${skillDir}`);
+        } catch (error) {
+            console.log(`⚠️  Failed to copy skill "${skill.name}" to OpenCode ${isProjectLevel ? 'project' : 'user'} directory: ${error.message}`);
+            allOk = false;
+        }
+    }
+
+    return allOk;
+}
+
+// ==================== Agent 安装 ====================
+
+function copyAgentToOpenCode(deps, isProjectLevel = false) {
+    // 优先使用构建产物，回退到 agents/ 源目录
+    const agentsSourceDir = path.join(deps.PACKAGE_ROOT, "opencode-extension", "agents");
+    const fallbackSourceDir = path.join(deps.PACKAGE_ROOT, "agents");
+
+    let actualSourceDir;
+    if (fs.existsSync(agentsSourceDir)) {
+        actualSourceDir = agentsSourceDir;
+    } else if (fs.existsSync(fallbackSourceDir)) {
+        actualSourceDir = fallbackSourceDir;
+    } else {
+        console.log("⏭️  Skipping agent install: agents source directory not found");
+        return false;
+    }
+
+    let openCodeAgentsDir;
+    if (isProjectLevel) {
+        openCodeAgentsDir = getOpenCodeProjectAgentsDirectory(deps.PROJECT_ROOT);
+    } else {
+        openCodeAgentsDir = getOpenCodeAgentsDirectory();
+    }
+
+    // 只复制 OpenCode 构建产物中的 agent 文件
+    const agentFiles = fs.readdirSync(actualSourceDir).filter(f => f.endsWith(".md"));
+    let copied = 0;
+
+    for (const agentFile of agentFiles) {
+        const sourcePath = path.join(actualSourceDir, agentFile);
+        const destPath = path.join(openCodeAgentsDir, agentFile);
+
+        try {
+            deps.ensureDirectory(openCodeAgentsDir);
+            deps.copyFile(sourcePath, destPath);
+            copied++;
+        } catch (error) {
+            console.log(`⚠️  Failed to copy agent ${agentFile}: ${error.message}`);
+        }
+    }
+
+    if (copied > 0) {
+        console.log(`✓ Copied ${copied} agent(s) to OpenCode ${isProjectLevel ? 'project' : 'user'} directory: ${openCodeAgentsDir}`);
+        return true;
+    }
+    return false;
+}
+
+// ==================== Slash Command 安装 ====================
+
+function installOpenCodeSlashCommand(deps) {
+    const commandsSourceDir = path.join(deps.PACKAGE_ROOT, "commands");
+    if (!fs.existsSync(commandsSourceDir)) {
+        console.log("⚠️  Commands source directory not found, skipping OpenCode");
+        return;
+    }
+
+    const commandFiles = fs.readdirSync(commandsSourceDir).filter(f => f.endsWith(".md"));
+    if (commandFiles.length === 0) {
+        console.log("⚠️  No command files found, skipping OpenCode");
+        return;
+    }
+
+    // 全局命令：~/.config/opencode/commands/
+    const globalCommandsDir = getOpenCodeCommandsDirectory();
+    try {
+        deps.ensureDirectory(globalCommandsDir);
+
+        for (const file of commandFiles) {
+            const commandSource = path.join(commandsSourceDir, file);
+            const commandDest = path.join(globalCommandsDir, file);
+
+            if (fs.existsSync(commandDest)) {
+                const existingContent = fs.readFileSync(commandDest, "utf8").trim();
+                const sourceContent = fs.readFileSync(commandSource, "utf8").trim();
+                if (existingContent !== sourceContent) {
+                    console.log(`⏭️  Skipping OpenCode global command ${file}: already exists (user modified)`);
+                    continue;
+                }
+            }
+
+            deps.copyFile(commandSource, commandDest);
+            console.log(`✓ Installed OpenCode global command: /${file.replace(".md", "")}`);
+        }
+    } catch (error) {
+        console.log(`⚠️  Failed to install OpenCode global commands: ${error.message}`);
+    }
+
+    // 项目级命令暂不启用，全局命令已覆盖所有项目
+    /*
+    if (!deps.PROJECT_ROOT || !fs.existsSync(deps.PROJECT_ROOT)) {
+        return;
+    }
+
+    const openCodeDir = path.join(deps.PROJECT_ROOT, ".opencode");
+    const projectCommandsDir = path.join(openCodeDir, "commands");
+
+    if (fs.existsSync(openCodeDir) && !fs.statSync(openCodeDir).isDirectory()) {
+        console.log(`⚠️  Skipping OpenCode project commands: ${openCodeDir} exists but is not a directory`);
+        return;
+    }
+
+    try {
+        deps.ensureDirectory(projectCommandsDir);
+
+        for (const file of commandFiles) {
+            const commandSource = path.join(commandsSourceDir, file);
+            const commandDest = path.join(projectCommandsDir, file);
+
+            if (fs.existsSync(commandDest)) {
+                const existingContent = fs.readFileSync(commandDest, "utf8").trim();
+                const sourceContent = fs.readFileSync(commandSource, "utf8").trim();
+                if (existingContent !== sourceContent) {
+                    console.log(`⏭️  Skipping OpenCode project command ${file}: already exists (user modified)`);
+                    continue;
+                }
+            }
+
+            deps.copyFile(commandSource, commandDest);
+            console.log(`✓ Installed OpenCode project command: /${file.replace(".md", "")}`);
+        }
+    } catch (error) {
+        console.log(`⚠️  Failed to install OpenCode project commands: ${error.message}`);
+    }
+    */
+}
+
+// ==================== MCP URL 同步（供 update-mcp-url.js 调用） ====================
+
+/**
+ * 不依赖 deps 的 CLI 可用性检测
+ */
+function isCommandAvailable(cmd) {
+    try {
+        execSync(`which ${cmd} 2>/dev/null`, { stdio: "pipe", timeout: 3000 });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * 不依赖 deps 的安全命令执行
+ */
+function safeExecSync(command) {
+    try {
+        execSync(command, { stdio: "pipe", timeout: 10000 });
+        return true;
+    } catch (e) {
+        const stderr = e.stderr?.toString() || "";
+        if (stderr.includes("already exists")) return "already_exists";
+        return false;
+    }
+}
+
+/**
+ * 同步 OpenCode 配置中的 MCP 服务器 URL
+ * @param {string} targetUrl - 新的 MCP 服务器基础 URL（如 http://localhost:3456）
+ * @param {string} serverName - MCP 服务器名称
+ */
+export function syncMcpUrl(targetUrl, serverName) {
+    const mcpUrl = `${targetUrl}/mcp`;
+
+    // 1. CLI 命令同步
+    if (isCommandAvailable("opencode")) {
+        safeExecSync(`opencode mcp remove ${serverName} --scope user 2>/dev/null`);
+        const result = safeExecSync(`opencode mcp add ${serverName} --scope user --url ${mcpUrl}`);
+        if (result === true || result === "already_exists") {
+            console.log(`✓ OpenCode CLI synced: ${mcpUrl}`);
+        } else {
+            console.warn(`⚠️  OpenCode CLI sync failed (config file will be updated directly)`);
+        }
+    } else {
+        console.log("⏭️  Skipping OpenCode CLI sync: opencode not found");
+    }
+
+    // 2. 直接文件操作同步（确保最终状态正确）
+    syncOpenCodeConfigDirect(targetUrl, serverName);
+}
+
+/**
+ * 直接文件操作同步 opencode.jsonc（独立于 deps）
+ */
+function syncOpenCodeConfigDirect(targetUrl, serverName) {
+    const configPath = getOpenCodeConfigPath();
+    const fallbackPath = getOpenCodeConfigPathJson();
+    const mcpUrl = `${targetUrl}/mcp`;
+
+    // 优先使用 jsonc，不存在则使用 json
+    let actualPath = fs.existsSync(configPath) ? configPath : fallbackPath;
+
+    let config = {};
+    if (fs.existsSync(actualPath)) {
+        config = readJsonFile(actualPath);
+    }
+
+    if (!config.mcp) config.mcp = {};
+
+    const current = config.mcp[serverName];
+    const apiKey = _getApiKey();
+    const currentHeaders = current && current.headers ? current.headers : {};
+    const needsApiKeyUpdate = apiKey && (!current || currentHeaders["Authorization"] !== `Bearer ${apiKey}`);
+
+    if (current && current.type === "remote" && current.url === mcpUrl && !needsApiKeyUpdate) {
+        console.log(`⏭️  OpenCode ${path.basename(actualPath)} already up-to-date: ${mcpUrl}`);
+        return;
+    }
+
+    const headers = {};
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+
+    config.mcp[serverName] = {
+        type: "remote",
+        url: mcpUrl,
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
+    };
+
+    if (!config.$schema) {
+        config.$schema = "https://opencode.ai/config.json";
+    }
+
+    writeJsonFile(actualPath, config);
+    console.log(`✓ Updated OpenCode ${path.basename(actualPath)}: ${mcpUrl}`);
+}
+
+// ==================== 导出 ====================
+
+export function setupOpenCode(deps) {
+    createOpenCodeUserConfig(deps);
+    copySkillToOpenCode(deps, false);
+    copyAgentToOpenCode(deps, false);
+    installOpenCodeSlashCommand(deps);
+
+    // 项目级配置暂不启用，用户级已足够
+    /*
+    let openCodeProjectInstalled = false;
+    if (deps.PROJECT_ROOT && fs.existsSync(deps.PROJECT_ROOT)) {
+        try {
+            openCodeProjectInstalled = createOpenCodeProjectConfig(deps);
+            if (openCodeProjectInstalled) {
+                copySkillToOpenCode(deps, true);
+                copyAgentToOpenCode(deps, true);
+            }
+        } catch (e) {
+            console.log(`⚠️  Failed to install OpenCode project config: ${e.message}`);
+        }
+    }
+    */
+
+    return {
+        openCodeProjectInstalled: false,
+        skillsDirectory: getOpenCodeSkillsDirectory(),
+        agentsDirectory: getOpenCodeAgentsDirectory(),
+    };
 }