@codify-ai/mcp-client 1.0.24 → 1.0.27

package/dist/index.js

@@ -17,15 +17,16 @@ const designPhilosophy = readFileSync(
   resolve(__dirname$1, "design-philosophy.md"),
   "utf-8"
 );
-const SERVER_URL = process.env.CODIFY_SERVER_URL || "http://localhost:8080";
+const urlArg = process.argv.find((arg) => arg.startsWith("--url="));
+const SERVER_URL = urlArg ? urlArg.slice("--url=".length) : process.env.CODIFY_SERVER_URL || "https://mcp.codify-api.com";
 const ACCESS_KEY = process.env.CODIFY_ACCESS_KEY;
 const CODIFY_DOC_DIR = ".codify";
 const CODIFY_OUTPUT_DIR = ".codify-output";
 const isEmpty = (value) => value === null || value === void 0 || value === "" || typeof value === "string" && value.trim() === "";
 function buildSuccessText(result, actionName = "操作") {
   let responseText = `✅ ${actionName}已成功完成`;
-  if (result.rootNodeId) responseText += `
-- 根节点 ID: ${result.rootNodeId}`;
+  if (result.targetNodeId) responseText += `
+- 节点 ID: ${result.targetNodeId}`;
   if (result.documentId) responseText += `
 - 文档: ${result.documentName || ""} (${result.documentId})`;
   if (result.documentPageId) responseText += `
@@ -111,7 +112,7 @@ async function saveCodeAndResources({
   documentId,
   documentPageId,
   contentId,
-  nodeId,
+  targetNodeId,
   nodeName,
   code,
   resourcePath,
@@ -120,11 +121,11 @@ async function saveCodeAndResources({
   image,
   isSelection = false
 }) {
-  let targetDir = outDir ? path.resolve(baseDir, outDir) : documentId && documentPageId ? path.join(baseDir, CODIFY_DOC_DIR, String(documentId).replace(/:/g, "-"), String(documentPageId).replace(/:/g, "-"), contentId && !isSelection && !nodeId ? "code" : "") : isSelection ? path.join(baseDir, CODIFY_OUTPUT_DIR, "selection") : path.join(baseDir, `${CODIFY_OUTPUT_DIR}${contentId ? "/" + contentId : ""}`);
+  let targetDir = outDir ? path.resolve(baseDir, outDir) : documentId && documentPageId ? path.join(baseDir, CODIFY_DOC_DIR, String(documentId).replace(/:/g, "-"), String(documentPageId).replace(/:/g, "-"), contentId && !isSelection && !targetNodeId ? "code" : "") : isSelection ? path.join(baseDir, CODIFY_OUTPUT_DIR, "selection") : path.join(baseDir, `${CODIFY_OUTPUT_DIR}${contentId ? "/" + contentId : ""}`);
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
-  const safeId = String(nodeId || Date.now()).replace(/:/g, "-");
+  const safeId = String(targetNodeId || Date.now()).replace(/:/g, "-");
   const safeName = String(nodeName || (isSelection ? "selection" : "node")).replace(/[^a-zA-Z0-9\u4e00-\u9fa5_-]/g, "-");
-  const htmlFileName = isSelection || nodeId || nodeName ? `${safeName}-${safeId}.html` : `${contentId || "index"}.html`;
+  const htmlFileName = isSelection || targetNodeId || nodeName ? `${safeName}-${safeId}.html` : `${contentId || "index"}.html`;
   const htmlPath = path.join(targetDir, htmlFileName);
   if (code) {
     await fs.writeFile(htmlPath, code, "utf8");
@@ -137,11 +138,82 @@ async function saveCodeAndResources({
   ]);
   return { targetDir, htmlFileName, htmlPath, shapeCount: stats[0], svgCount: stats[1], imageCount: stats[2], resourcePathMap: resPathMap };
 }
+const zh = {
+  createPage: {
+    description: "将代码发送到 Codify 插件转换为设计稿。\n\n【极致性能要求】若纯 HTML 已保存为本地文件，你必须且只能通过 filePath 传入该文件的绝对路径。严禁使用 Read 工具读取文件内容，严禁将大段代码写入 code 参数。工具底层会自动读取并传输，以节省 Token。只有当代码是你在当前对话中临时生成且尚未写入文件时，才允许使用 code 参数。\n\n⚠️ 逆向转译警告：严禁直接发送 Vue/React 等包含动态绑定 ({{}}) 或框架指令的业务代码！若要将业务代码转为设计稿，必须先执行【逆向转译】（参考 codify://generation-rules），将其转换为带静态假数据的纯 HTML 后再发送。",
+    code: "【可选】要发送的 HTML 代码内容。仅当代码是临时生成且未保存为文件时使用。大段代码严禁使用此参数。",
+    filePath: "【可选】本地 HTML 文件的绝对路径。若文件已存在本地，必须传此参数，工具会自动读取并执行落盘。",
+    projectDir: "【必填】用户当前工作区的根目录绝对路径",
+    saveCodeToLocal: "是否将插件返回的渲染结果保存到本地 .codify 目录（落盘机制）"
+  },
+  updateNode: {
+    description: "将修改后的 HTML 代码发回 MasterGo 画布进行【局部修改】（如改颜色、加文字、改间距等）。完成代码修改后，你必须同步调用此工具。注意：此工具一次只能同步一个节点及其关联子节点，必须传入 code。",
+    documentId: "当前 MasterGo 文档 ID。",
+    documentPageId: "当前 MasterGo 页面 ID。",
+    targetNodeId: "【选填】目标图层 ID (例如 123:456)。如果不传，则默认更新 MasterGo 中当前选中的图层。",
+    code: "【必填】修改后的 HTML 代码片段。必须包含 data-node-id。"
+  },
+  syncToDesign: {
+    description: "将本地完整的静态 HTML 文件内容同步覆盖到 MasterGo 画布进行【全量同步】（如保存整个页面、复杂的模块同步）。必须传入根节点 ID (rootId) 以确保层级正确。",
+    documentId: "当前 MasterGo 文档 ID。",
+    documentPageId: "当前 MasterGo 页面 ID。",
+    targetNodeId: "【必填】页面的根节点 ID (rootId)。",
+    filePath: "【必填】本地静态 HTML 文件的绝对路径（通常位于 .codify/... 目录下）。工具会自动读取内容。严禁传入 .vue/.tsx 业务代码路径！"
+  },
+  getSelectionCode: {
+    description: "获取 MasterGo 中当前选中图层（或指定图层）的代码。如果你获取的是子节点，工具只会将代码作为纯文本返回给你进行局部修改上下文，绝对不会在本地生成烦人的 HTML 碎片文件！若是根节点则会自动将完整页面代码同步保存到 .codify 目录。",
+    projectDir: "【必填】用户当前工作区的根目录绝对路径",
+    targetNodeId: "【选填】MasterGo图层ID (例如 123:456)。如果提供，将直接拉取该ID的代码；如果不提供，将拉取当前选中图层的代码。",
+    syncToBase: "【选填】是否将获取到的子图层代码同步回本地 .codify 目录下的基准 HTML 文件（合并更新）。默认为 true。"
+  },
+  createComponent: {
+    description: '创建一个 MasterGo 母版组件或组件集（变体）。应当使用 HTML 格式并包含 data-type="component" 属性。',
+    code: '组件的 HTML 结构。必须包含 data-type="component" 或 "component-set"。'
+  },
+  getDesignDiff: {
+    description: `获取设计稿与本地代码的差异。
+【标准双向同步规程】：
+1. 准备：将当前项目业务代码（Vue/React）按 rules.md 规范物理逆推为纯静态 HTML。
+2. 刷新：将转译产物覆盖写入 .codify 目录对应的基准 HTML 文件。
+3. 比对：调用此工具比对“基准文件”与“画布现状”获得差异列表。
+4. 决策：展示差异，由用户决定执行“全量同步到设计稿”或“按差异局部同步到项目”。`,
+    projectDir: "【必填】用户当前工作区的根目录绝对路径",
+    targetNodeId: "【选填】MasterGo图层ID (例如 123:456)。如果不传，则默认获取当前选中图层的代码进行对比。",
+    filePath: "【选填】本地基准 HTML 文件的绝对路径。如果已通过 write_to_file 更新了基准文件，请直接传此路径。"
+  },
+  getCodeList: {
+    description: "获取所有可用的代码列表",
+    inputSchema: "无需参数获取代码列表"
+  },
+  design: {
+    description: "根据需求生成符合 Codify 规范的 HTML+CSS 代码。生成完成后，应调用 agent_create_page 将代码发送到画布。",
+    requirement: '界面需求描述，例如："一个美观的登录页面"、"现代化的仪表盘界面"等。'
+  },
+  getUserInfo: {
+    description: "获取当前登录用户的信息，包括配额、团队等",
+    inputSchema: "获取当前用户信息"
+  },
+  getCode: {
+    description: '【特定场景】通过 contentId 从 Codify 插件获取代码。常规的"获取选中代码"请优先使用 get_selection_code 工具。',
+    contentId: "从Codify插件复制图层的指令 (contentId)",
+    documentId: "当前 MasterGo 文档 ID。",
+    documentPageId: "当前 MasterGo 页面 ID。",
+    projectDir: "【必填】用户当前工作区的根目录绝对路径",
+    outDir: "【必填】保存代码和资源的绝对路径"
+  },
+  removeNode: {
+    description: "在 MasterGo 画布中执行删除节点操作。支持通过 targetNodeId 指定 ID，或在不传 ID 时默认删除当前选中图层。",
+    documentId: "当前 MasterGo 文档 ID。",
+    documentPageId: "当前 MasterGo 页面 ID。",
+    targetNodeId: "【选填】要删除的目标图层 ID (例如 123:456)。如果不传，则默认删除 MasterGo 中当前选中的图层。"
+  }
+};
+const i18n = zh;
 const createComponentTool = {
   name: "agent_create_component",
-  description: '创建一个 MasterGo 母版组件或组件集（变体）。应当使用 HTML 格式并包含 data-type="component" 属性。',
+  description: i18n.createComponent.description,
   inputSchema: {
-    code: z.string().describe('组件的 HTML 结构。必须包含 data-type="component" 或 "component-set"。')
+    code: z.string().describe(i18n.createComponent.code)
   },
   handler: async (args) => {
     const { code } = args;
@@ -152,12 +224,12 @@ const createComponentTool = {
 };
 const createPageTool = {
   name: "agent_create_page",
-  description: "将代码发送到 Codify 插件转换为设计稿。若 HTML 已保存为本地文件，请通过 filePath 传入，避免大段 code 占用 Token。",
+  description: i18n.createPage.description,
   inputSchema: {
-    code: z.string().optional().describe("【可选】要发送的 HTML 代码内容。小片段可直接传此参数。"),
-    filePath: z.string().optional().describe("【可选】本地 HTML 文件的绝对路径。创建设计稿且文件已存在时，优先传此参数，工具会读取后发送并执行落盘。"),
-    projectDir: z.string().describe("【必填】用户当前工作区的根目录绝对路径"),
-    saveCodeToLocal: z.boolean().default(true).describe("是否将插件返回的渲染结果保存到本地 .codify 目录（落盘机制）")
+    code: z.string().optional().describe(i18n.createPage.code),
+    filePath: z.string().optional().describe(i18n.createPage.filePath),
+    projectDir: z.string().describe(i18n.createPage.projectDir),
+    saveCodeToLocal: z.boolean().default(true).describe(i18n.createPage.saveCodeToLocal)
   },
   handler: async (args) => {
     const { projectDir, saveCodeToLocal = true } = args;
@@ -183,7 +255,7 @@ const createPageTool = {
           code: data.htmlCode || code,
           documentId: data.documentId,
           documentPageId: data.documentPageId,
-          nodeId: data.rootNodeId,
+          targetNodeId: data.targetNodeId,
           nodeName: data.nodeName,
           resourcePath: data.resourcePath,
           shape: data.shape,
@@ -202,9 +274,9 @@ const createPageTool = {
 };
 const designTool = {
   name: "design",
-  description: "根据需求生成符合 Codify 规范的 HTML+CSS 代码",
+  description: i18n.design.description,
   inputSchema: {
-    requirement: z.string().describe('界面需求描述，例如："一个美观的登录页面"、"现代化的仪表盘界面"等。')
+    requirement: z.string().describe(i18n.design.requirement)
   },
   handler: async (args) => {
     const { requirement } = args;
@@ -234,13 +306,13 @@ ${generationRules}
 };
 const getCodeTool = {
   name: "get_code",
-  description: "从 Codify For MasterGo 插件获取指定的代码",
+  description: i18n.getCode.description,
   inputSchema: {
-    contentId: z.string().describe("从Codify插件复制图层的指令"),
-    documentId: z.string().optional().describe("当前 MasterGo 文档 ID。"),
-    documentPageId: z.string().optional().describe("当前 MasterGo 页面 ID。"),
-    projectDir: z.string().describe("【必填】用户当前工作区的根目录绝对路径"),
-    outDir: z.string().describe("【必填】保存代码和资源的绝对路径")
+    contentId: z.string().describe(i18n.getCode.contentId),
+    documentId: z.string().optional().describe(i18n.getCode.documentId),
+    documentPageId: z.string().optional().describe(i18n.getCode.documentPageId),
+    projectDir: z.string().describe(i18n.getCode.projectDir),
+    outDir: z.string().describe(i18n.getCode.outDir)
   },
   handler: async (args) => {
     const { contentId, outDir, projectDir, documentId, documentPageId } = args;
@@ -276,8 +348,8 @@ const getCodeTool = {
 };
 const getCodeListTool = {
   name: "get_code_list",
-  description: "获取所有可用的代码列表",
-  inputSchema: z.object({}).describe("无需参数获取代码列表"),
+  description: i18n.getCodeList.description,
+  inputSchema: z.object({}).describe(i18n.getCodeList.inputSchema),
   handler: async () => {
     const { data, error } = await callApi("GET", "/api/getCodeList");
     if (error) return { content: [{ type: "text", text: `❌ 获取失败: ${error.message}` }], isError: true };
@@ -299,31 +371,63 @@ const getCodeListTool = {
 };
 const getSelectionCodeTool = {
   name: "get_selection_code",
-  description: "获取 MasterGo 中当前选中图层（或指定图层）的代码，并智能落盘到本地 .codify 目录。\n\n【强制触发场景】凡用户说「将选中的 xxx 改成 yyy」「将选中的按钮改成红色」「修改当前选中的图层」等含「选中」的修改指令，你必须首先调用此工具拉取当前画布选中节点的最新代码，再根据返回的 HTML 进行修改，禁止凭空生成或直接修改本地文件。",
+  description: i18n.getSelectionCode.description,
   inputSchema: {
-    projectDir: z.string().describe("【必填】用户当前工作区的根目录绝对路径"),
-    id: z.string().optional().describe("【选填】MasterGo图层ID (例如 123:456)。如果提供，将直接拉取该ID的代码；如果不提供，将拉取当前选中图层的代码。")
+    projectDir: z.string().describe(i18n.getSelectionCode.projectDir),
+    targetNodeId: z.string().optional().describe(i18n.getSelectionCode.targetNodeId),
+    syncToBase: z.boolean().default(true).describe(i18n.getSelectionCode.syncToBase)
   },
+  /**
+   * 工具处理器
+   * @param args.syncToBase 是否尝试将子节点代码合并到基准 HTML 文件
+   * @param args._depth 内部参数，用于防止递归获取根节点时出现无限循环
+   */
   handler: async (args) => {
-    const { projectDir, id } = args;
+    const { projectDir, targetNodeId: id, syncToBase = true, _depth = 0 } = args;
+    if (_depth > 2) {
+      return {
+        content: [
+          { type: "text", text: "❌ 递归获取根节点深度过深，已停止。" }
+        ],
+        isError: true
+      };
+    }
     const endpoint = id ? `/api/getSelectionCode?id=${encodeURIComponent(id)}` : "/api/getSelectionCode";
     const { data, error } = await callApi("GET", endpoint);
     if (error) {
       if (error.status === 400 && error.data?.error === "NoSelection") {
-        return { content: [{ type: "text", text: "❌ 获取失败: 没有选中任何图层。请先在 MasterGo 中选中一个图层。" }], isError: true };
+        return {
+          content: [
+            {
+              type: "text",
+              text: "❌ 获取失败: 没有选中任何图层。请先在 MasterGo 中选中一个图层。"
+            }
+          ],
+          isError: true
+        };
       }
-      return { content: [{ type: "text", text: `❌ 获取失败: ${error.message}` }], isError: true };
+      return {
+        content: [{ type: "text", text: `❌ 获取失败: ${error.message}` }],
+        isError: true
+      };
     }
     const baseDir = projectDir ? path.resolve(projectDir) : process.cwd();
     const nodeInfo = data.nodeInfo || {};
-    const { rootId, documentId, documentPageId, nodeId, nodeName, parentId } = nodeInfo;
-    if (!parentId || parentId === "null") {
+    const {
+      rootId,
+      documentId,
+      documentPageId,
+      targetNodeId,
+      nodeName,
+      parentId
+    } = nodeInfo;
+    if (targetNodeId === rootId) {
+      console.log(`[getSelectionCode] 当前节点ID: ${targetNodeId}, 根节点ID: ${rootId}`);
       const saveResult = await saveCodeAndResources({
         baseDir,
         documentId,
         documentPageId,
-        nodeId: rootId || nodeId,
-        // 使用 rootId 作为文件名后缀
+        targetNodeId: rootId,
         nodeName,
         code: data.code,
         resourcePath: data.resourcePath,
@@ -331,70 +435,108 @@ const getSelectionCodeTool = {
         svg: data.svg,
         image: data.image
       });
-      console.log("saveResult", saveResult);
       return {
         content: [
           {
             type: "text",
             text: `✅ 成功获取并保存根节点代码
-- 节点: ${nodeName} (${nodeId})
-- 文件: ${saveResult.htmlPath}
-
-请查看该文件了解当前结构。`
+- 节点: ${nodeName} (${targetNodeId})
+- 根节点: ${rootId}
+- 文件: ${saveResult.htmlPath}。`
           }
         ]
       };
     } else {
-      if (!documentId || !documentPageId) {
-        return { content: [{ type: "text", text: `❌ 更新失败: 缺少 documentId 或 documentPageId 信息。` }], isError: true };
-      }
-      const targetDir = path.join(baseDir, CODIFY_DOC_DIR, String(documentId).replace(/:/g, "-"), String(documentPageId).replace(/:/g, "-"));
-      if (!existsSync(targetDir)) {
-        return { content: [{ type: "text", text: `❌ 更新失败: 找不到根节点所在目录 ${targetDir}。请先选中并获取根节点的代码。` }], isError: true };
-      }
-      const files = await fs.readdir(targetDir);
-      const safeRootId = String(rootId).replace(/:/g, "-");
-      const rootFile = files.find((f) => f.endsWith(`-${safeRootId}.html`));
-      if (!rootFile) {
-        return { content: [{ type: "text", text: `❌ 更新失败: 在目录中找不到包含根节点 ID (${rootId}) 的文件。请先选中并获取根节点的代码。` }], isError: true };
-      }
-      const rootFilePath = path.join(targetDir, rootFile);
-      const htmlContent = await fs.readFile(rootFilePath, "utf8");
-      const rootNode = parse(htmlContent);
-      const targetElement = rootNode.querySelector(`[data-node-id="${nodeId}"]`);
-      if (targetElement) {
-        targetElement.replaceWith(data.code);
-      } else if (nodeInfo.parentId) {
-        const parentElement = rootNode.querySelector(`[data-node-id="${nodeInfo.parentId}"]`);
-        if (parentElement) {
-          parentElement.insertAdjacentHTML("beforeend", data.code);
-        } else {
-          return { content: [{ type: "text", text: `❌ 更新失败: 在文件 ${rootFile} 中找不到当前节点(${nodeId})，也找不到父节点(${nodeInfo.parentId})。` }], isError: true };
+      console.log(`[getSelectionCode] 当前节点ID: ${targetNodeId}, 根节点ID: ${rootId}`);
+      let mergedToFilePath = "";
+      if (syncToBase && documentId && documentPageId) {
+        const targetPageDir = path.join(
+          baseDir,
+          CODIFY_DOC_DIR,
+          String(documentId).replace(/:/g, "-"),
+          String(documentPageId).replace(/:/g, "-")
+        );
+        const safeRootId = String(rootId).replace(/:/g, "-");
+        let rootFile = "";
+        const findRootFile = async () => {
+          if (existsSync(targetPageDir)) {
+            const files = await fs.readdir(targetPageDir);
+            return files.find((f) => f.endsWith(`-${safeRootId}.html`)) || "";
+          }
+          return "";
+        };
+        rootFile = await findRootFile();
+        if (!rootFile && _depth === 0) {
+          console.log(
+            `[getSelectionCode] 基准文件不存在，自动拉取根节点: ${rootId}`
+          );
+          await getSelectionCodeTool.handler({
+            projectDir,
+            targetNodeId: rootId,
+            syncToBase: true,
+            _depth: _depth + 1
+          });
+          rootFile = await findRootFile();
+        }
+        if (rootFile) {
+          const rootFilePath = path.join(targetPageDir, rootFile);
+          try {
+            const htmlContent = await fs.readFile(rootFilePath, "utf8");
+            const rootNode = parse(htmlContent);
+            const targetElement = rootNode.querySelector(
+              `[data-node-id="${targetNodeId}"]`
+            );
+            if (targetElement) {
+              targetElement.replaceWith(data.code);
+            } else if (parentId) {
+              const parentElement = rootNode.querySelector(
+                `[data-node-id="${parentId}"]`
+              );
+              if (parentElement) {
+                parentElement.insertAdjacentHTML("beforeend", data.code);
+              }
+            }
+            if (targetElement || parentId && rootNode.querySelector(`[data-node-id="${parentId}"]`)) {
+              await fs.writeFile(rootFilePath, rootNode.toString(), "utf8");
+              mergedToFilePath = rootFilePath;
+            }
+          } catch (err) {
+            console.error("合并到基准文件操作出错:", err);
+          }
         }
-      } else {
-        return { content: [{ type: "text", text: `❌ 更新失败: 在文件 ${rootFile} 中找不到 data-node-id="${nodeId}" 的元素，且未提供 parentId 作为后备。` }], isError: true };
       }
-      await fs.writeFile(rootFilePath, rootNode.toString(), "utf8");
       await saveCodeAndResources({
         baseDir,
         documentId,
         documentPageId,
-        nodeId,
+        targetNodeId,
         nodeName,
         code: "",
-        // 我们已经手动更新了 HTML，这里传空字符串，主要是为了利用它去保存资源
+        // 核心改动：强制将此参数留空，彻底阻断 .html 碎片文件的生成
         resourcePath: data.resourcePath,
         shape: data.shape,
         svg: data.svg,
         image: data.image
-      }).catch((e) => console.error("保存子节点资源失败:", e));
+      });
+      let successText = `✅ 成功获取子节点代码
+- 节点: ${nodeName} (${targetNodeId})
+- 根节点: ${rootId}`;
+      if (mergedToFilePath) {
+        successText += `
+- ⚠️ (自动机制) 子节点最新代码已合并备份至本地基准 HTML: ${mergedToFilePath}`;
+      } else {
+        successText += `
+- 💡 提示: 子节点代码已提取到对话上下文中，未生成本地 HTML 碎片文件。可以直接针对返回代码进行修改。`;
+      }
       return {
         content: [
           {
             type: "text",
-            text: `✅ 成功更新子节点代码
-- 节点: ${nodeName} (${nodeId})
-- 已更新文件: ${rootFilePath}`
+            text: `${successText}
+
+代码内容：
+
+${data.code}`
           }
         ]
       };
@@ -403,8 +545,8 @@ const getSelectionCodeTool = {
 };
 const getUserInfoTool = {
   name: "get_user_info",
-  description: "获取当前登录用户的信息，包括配额、团队等",
-  inputSchema: z.object({}).describe("获取当前用户信息"),
+  description: i18n.getUserInfo.description,
+  inputSchema: z.object({}).describe(i18n.getUserInfo.inputSchema),
   handler: async () => {
     const { data, error } = await callApi("GET", "/api/getUserInfo");
     if (error) return { content: [{ type: "text", text: `❌ 获取失败: ${error.message}` }], isError: true };
@@ -433,67 +575,95 @@ const getUserInfoTool = {
 };
 const updateNodeTool = {
   name: "agent_update_node",
-  description: '将修改后的 HTML 代码发回 MasterGo 画布进行更新。\n\n【调用前置条件】若用户说的是「将选中的 xxx 改成 yyy」等含「选中」的修改指令，你必须先调用 get_selection_code 拉取当前选中节点代码，修改完成后再调用本工具，不得跳过前置步骤。\n\n【局部修改（改文字/颜色/某处）】只传你改动的那一个节点（含 data-node-id 及子节点）的 HTML 片段到 code 参数，严禁传整个文件。\n\n【全量同步（用户明确说"同步到设计稿"）】才用 filePath 传本地文件绝对路径，禁止用 Read 工具读大文件再塞进 code。\n\n若是从 Vue/React 业务代码同步，请剔除框架指令（v-for、@click 等），只传纯 HTML。',
+  description: i18n.updateNode.description,
   inputSchema: {
-    documentId: z.string().optional().describe("当前 MasterGo 文档 ID。"),
-    documentPageId: z.string().optional().describe("当前 MasterGo 页面 ID。"),
-    targetNodeId: z.string().optional().describe("【选填】目标图层 ID (例如 123:456)。如果不传，则默认更新 MasterGo 中当前选中的图层。"),
-    code: z.string().optional().describe("【可选】修改后的 HTML 代码片段。如果只是局部小修改，可以直接传代码。"),
-    filePath: z.string().optional().describe("【可选】如果需要发送整个文件或大量代码，请提供该文件的绝对路径，工具会自动读取并发送，绝对不要把整个文件的代码塞进 code 参数里！")
+    documentId: z.string().optional().describe(i18n.updateNode.documentId),
+    documentPageId: z.string().optional().describe(i18n.updateNode.documentPageId),
+    targetNodeId: z.string().optional().describe(i18n.updateNode.targetNodeId),
+    code: z.string().describe(i18n.updateNode.code)
   },
   handler: async (args) => {
-    const { targetNodeId, documentId, documentPageId, filePath } = args;
-    let finalCode = args.code || "";
-    if (filePath) {
-      try {
-        const absolutePath = path.resolve(filePath);
-        finalCode = await fs.readFile(absolutePath, "utf8");
-      } catch (e) {
-        return { content: [{ type: "text", text: `❌ 读取文件失败: ${e.message}` }], isError: true };
-      }
+    const { targetNodeId, documentId, documentPageId, code } = args;
+    if (!code) {
+      return { content: [{ type: "text", text: `❌ 必须提供 code` }], isError: true };
     }
-    if (!finalCode) {
-      return { content: [{ type: "text", text: `❌ 必须提供 code 或 filePath` }], isError: true };
-    }
-    const { data, error } = await callApi("POST", "/api/updateNode", { code: finalCode, targetNodeId, documentId, documentPageId });
-    if (error) return { content: [{ type: "text", text: `❌ 更新失败: ${error.message}` }], isError: true };
+    const { data, error } = await callApi("POST", "/api/updateNode", { code, targetNodeId, documentId, documentPageId });
+    if (error) return { content: [{ type: "text", text: `❌ 局部更新失败: ${error.message}` }], isError: true };
     return {
-      content: [{ type: "text", text: `✅ 已成功发送更新指令${data.nodeId ? `
-- 结果节点 ID: ${data.nodeId}` : ""}
-
-⚠️ 强烈建议：为了保证本地 .codify 目录中的基准 HTML 与设计稿保持一致，请立即调用 get_selection_code 工具（传入对应的根节点 ID），拉取最新的纯净 HTML 并覆盖本地基准文件。` }]
+      content: [{ type: "text", text: `✅ [局部修改] 指令已发送${data.targetNodeId ? `
+- 节点 ID: ${data.targetNodeId}` : ""}` }]
     };
   }
 };
 const getDesignDiffTool = {
   name: "get_design_diff",
-  description: "获取最新设计稿代码与本地 .codify 目录中旧代码的差异 (Diff)。当用户要求“同步设计稿到业务代码”或“对比最新设计稿”时使用。注意：拿到差异后，请根据 data-node-id 精准修改用户的业务代码，绝对不要破坏原有的框架逻辑（如 Vue/React 指令）。",
+  description: i18n.getDesignDiff.description,
   inputSchema: {
-    projectDir: z.string().describe("【必填】用户当前工作区的根目录绝对路径"),
-    id: z.string().optional().describe("【选填】MasterGo图层ID (例如 123:456)。如果不传，则默认获取当前选中图层的代码进行对比。")
+    projectDir: z.string().describe(i18n.getDesignDiff.projectDir),
+    targetNodeId: z.string().optional().describe(i18n.getDesignDiff.targetNodeId),
+    filePath: z.string().optional().describe(i18n.getDesignDiff.filePath)
   },
   handler: async (args) => {
-    const { projectDir, id } = args;
+    const { projectDir, targetNodeId, filePath } = args;
     const baseDir = projectDir ? path.resolve(projectDir) : process.cwd();
+    let currentTargetNodeId = targetNodeId;
     let oldHtml = "";
-    let localFilePath = "";
-    if (id) {
-      const safeId = String(id).replace(/:/g, "-");
-      const findFile = async (dir) => {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            const found = await findFile(fullPath);
-            if (found) return found;
-          } else if (entry.name.endsWith(`-${safeId}.html`)) {
-            return fullPath;
+    let localFilePath = filePath || "";
+    if (localFilePath) {
+      try {
+        const absolutePath = path.isAbsolute(localFilePath) ? localFilePath : path.resolve(baseDir, localFilePath);
+        oldHtml = await fs.readFile(absolutePath, "utf8");
+      } catch (e) {
+        return {
+          content: [
+            { type: "text", text: `❌ 无法读取指定的 filePath: ${e.message}` }
+          ],
+          isError: true
+        };
+      }
+    }
+    let finalRootId = "";
+    if (!oldHtml || !currentTargetNodeId) {
+      const selectionEndpoint = currentTargetNodeId ? `/api/getSelectionCode?id=${encodeURIComponent(currentTargetNodeId)}` : "/api/getSelectionCode";
+      const { data: selectionData, error: selectionError } = await callApi(
+        "GET",
+        selectionEndpoint
+      );
+      if (selectionError || !selectionData?.nodeInfo?.targetNodeId) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `❌ 无法获取图层信息，请确保已在 MasterGo 中选中图层。`
+            }
+          ],
+          isError: true
+        };
+      }
+      const {
+        rootId,
+        targetNodeId: finalTargetId,
+        nodeName: finalNodeName
+      } = selectionData.nodeInfo;
+      finalRootId = rootId;
+      if (!currentTargetNodeId) currentTargetNodeId = finalTargetId;
+      if (!oldHtml && rootId) {
+        const safeRootId = String(rootId).replace(/:/g, "-");
+        const findFile = async (dir) => {
+          if (!existsSync(dir)) return null;
+          const entries = await fs.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              const found = await findFile(fullPath);
+              if (found) return found;
+            } else if (entry.name.endsWith(`-${safeRootId}.html`)) {
+              return fullPath;
+            }
           }
-        }
-        return null;
-      };
-      const codifyDir = path.join(baseDir, CODIFY_DOC_DIR);
-      if (existsSync(codifyDir)) {
+          return null;
+        };
+        const codifyDir = path.join(baseDir, CODIFY_DOC_DIR);
         localFilePath = await findFile(codifyDir) || "";
         if (localFilePath) {
           oldHtml = await fs.readFile(localFilePath, "utf8");
@@ -502,21 +672,32 @@ const getDesignDiffTool = {
     }
     if (!oldHtml) {
       return {
-        content: [{
-          type: "text",
-          text: id ? `❌ 在本地 .codify 目录中找不到 ID 为 ${id} 的代码文件。请确保已执行过拉取操作。` : `❌ 请提供图层 ID 以便从本地 .codify 目录加载基准代码进行 Diff。`
-        }],
+        content: [
+          {
+            type: "text",
+            text: `❌ 在本地 .codify 目录中找不到 ID 为 ${finalRootId || currentTargetNodeId} 的基准代码文件。请确保您之前已使用 get_selection_code 拉取过该图层或其根节点的代码。`
+          }
+        ],
         isError: true
       };
     }
     const { data, error } = await callApi("POST", "/api/getDesignDiff", {
       code: oldHtml,
-      id
+      targetNodeId: currentTargetNodeId
     });
     if (error) {
-      return { content: [{ type: "text", text: `❌ 获取设计稿差异失败: ${error.message}` }], isError: true };
+      return {
+        content: [
+          { type: "text", text: `❌ 获取设计稿差异失败: ${error.message}` }
+        ],
+        isError: true
+      };
+    }
+    let diffs = data.diffs || [];
+    if (diffs && !Array.isArray(diffs) && Array.isArray(diffs.diffs)) {
+      diffs.nodeInfo;
+      diffs = diffs.diffs;
     }
-    const diffs = data.diffs || [];
     if (diffs.length === 0) {
       return {
         content: [
@@ -543,6 +724,65 @@ ${JSON.stringify(diffs, null, 2)}
     };
   }
 };
+const removeNodeTool = {
+  name: "agent_remove_node",
+  description: i18n.removeNode.description,
+  inputSchema: {
+    documentId: z.string().optional().describe(i18n.removeNode.documentId),
+    documentPageId: z.string().optional().describe(i18n.removeNode.documentPageId),
+    targetNodeId: z.string().optional().describe(i18n.removeNode.targetNodeId)
+  },
+  handler: async (args) => {
+    const { targetNodeId, documentId, documentPageId } = args;
+    const { data, error } = await callApi("POST", "/api/removeNode", { targetNodeId, documentId, documentPageId });
+    if (error) {
+      return {
+        content: [{ type: "text", text: `❌ 删除失败: ${error.message}` }],
+        isError: true
+      };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: `✅ 已成功发送删除指令
+- 目标节点 ID: ${data.targetNodeId || targetNodeId || "当前选中图层"}`
+      }]
+    };
+  }
+};
+const syncToDesignTool = {
+  name: "agent_sync_design",
+  description: i18n.syncToDesign.description,
+  inputSchema: {
+    documentId: z.string().optional().describe(i18n.syncToDesign.documentId),
+    documentPageId: z.string().optional().describe(i18n.syncToDesign.documentPageId),
+    targetNodeId: z.string().optional().describe(i18n.syncToDesign.targetNodeId),
+    filePath: z.string().describe(i18n.syncToDesign.filePath)
+  },
+  handler: async (args) => {
+    const { targetNodeId, documentId, documentPageId, filePath } = args;
+    let finalCode = "";
+    if (filePath) {
+      try {
+        const absolutePath = path.resolve(filePath);
+        finalCode = await fs.readFile(absolutePath, "utf8");
+      } catch (e) {
+        return { content: [{ type: "text", text: `❌ 读取本地文件失败: ${e.message}` }], isError: true };
+      }
+    }
+    if (!finalCode) {
+      return { content: [{ type: "text", text: `❌ 同步失败: 未能从指定路径读取到有效代码` }], isError: true };
+    }
+    const { data, error } = await callApi("POST", "/api/syncToDesign", { code: finalCode, targetNodeId, documentId, documentPageId });
+    if (error) return { content: [{ type: "text", text: `❌ [全量同步] 失败: ${error.message}` }], isError: true };
+    return {
+      content: [{ type: "text", text: `✅ [全量同步] 已成功推送至画布${data.targetNodeId ? `
+- 根节点 ID: ${data.targetNodeId}` : ""}
+
+💡 建议：同步完成后，请立即通过 get_selection_code (传入 rootId) 重新拉取一次纯净 HTML，以刷新本地 .codify 基准。` }]
+    };
+  }
+};
 const allTools = [
   designTool,
   getCodeTool,
@@ -552,7 +792,9 @@ const allTools = [
   createComponentTool,
   getSelectionCodeTool,
   updateNodeTool,
-  getDesignDiffTool
+  syncToDesignTool,
+  getDesignDiffTool,
+  removeNodeTool
 ];
 function registerAllTools(mcpServer2) {
   allTools.forEach((tool) => {

package/dist/rules.md

@@ -10,6 +10,29 @@
 **核心二：严苛的 Figma 协议编译器（负责“格式化”）**
 一旦视觉方案定型，你必须将这个绝美的界面，**100% 严格地“降维、压缩、翻译”**成符合底层规范的代码。你不再是设计师，而是一个没有感情的机器，确保每一行代码都能被程序完美逆向解析为 Figma 图层。任何非标代码都会导致转换失败系统崩溃。
 
+## 🔄 标准双向同步协议 (Standard Bi-directional Sync Protocol)
+
+当需要将本地工程与 MasterGo 设计稿进行比对或同步时，必须严格遵守以下“三步走”规程，严禁跳步：
+
+### Step 1: 准备与逆向转译 (Prepare & Reverse Transpile)
+你必须读取当前项目对应的业务代码（如 `.vue`, `.tsx`），并将其物理“解构”为符合本协议规范的纯静态 HTML。
+- **清除所有框架指令**：删除 `v-for`, `@click`, `v-if`, `props` 等所有动态逻辑。
+- **展开静态数据**：将变量替换为高逼真的静态假数据，将循环展开为重复的 HTML 结构。
+- **验证样式**：确保所有类名已转换为本协议要求的 Tailwind 任意值语法。
+
+### Step 2: 刷新本地基准 (Refresh Local Base)
+将 Step 1 产出的纯静态 HTML 代码，通过 `write_to_file` 覆盖写入到 `.codify` 目录下对应的基准 `.html` 文件中。
+- **理由**：通过此步骤，我们确保 `.codify` 目录实时映射了当前代码的真实视觉状态，使得后续的 Diff 能够准确反映“代码”与“设计”的差异，而非过期的快照。
+
+### Step 3: 比对与决策 (Diff & Decision)
+调用 `get_design_diff` 工具，获取基准文件与画布现状的差异 JSON。
+- **展示差异**：向用户展示变更列表（修改、插入、删除）。
+- **用户决策**：
+  - **A. 同步到设计稿**：用户确认代码是正确的，调用 `agent_update_node` (带 `filePath`) 将文件强行覆盖到画布根节点。
+  - **B. 同步到代码**：用户确认设计是正确的，你根据 Diff JSON 精准修补业务代码中的样式和结构。
+
+---
+
 ## 📜 最终产出总纲 (Final Output Standards)
 
 你所有的工作产出，必须无条件满足以下 7 大黄金标准：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codify-ai/mcp-client",
-  "version": "1.0.24",
+  "version": "1.0.27",
   "description": "Codify MCP 客户端 - 连接到远程 Codify MCP 服务器，供 CLI 或 Cursor 等 IDE 使用",
   "type": "module",
   "bin": {