@codify-ai/mcp-client 1.0.32 → 1.0.34

package/README.md

@@ -58,7 +58,7 @@
 
 #### 方式 1：将设计稿给其他人（研发）拉取代码到本地
 
-在 Codify 插件中选中一个元素，复制的指令然后给到其他人来获取代码。
+在 MasterGo 中选中一个元素，复制的指令然后给到其他人来获取代码。
 
 无需启动 MasterGo，直接在 IDE 中输入该指令即可获取代码。
 
@@ -77,13 +77,13 @@ codify://getCode/{contentId}
 - "将我选中的图层，同步到本地代码" (**agent_sync_design**)
 - "对比本地代码与设计稿的差异" (**get_design_diff**)
 
-#### 方式 3：引用核心规范资源
+#### 方式 3：加载核心规范工具
 
-在对话中通过或直接输入 URI 引用：
+在对话中直接要求调用：
 
-- `codify://rule`
-  - 核心规范与设计哲学：
-    你需要让 LLM 严格遵守转译代码规范才能完美的将它转译为 MasterGo 设计稿。当你需要将你已有的前端项目转换为设计稿的时候，必须让 LLM 读取此文档。同时，Codify为你总结了一套非常实用的UI设计哲学，它能够让LLM在生成页面的时候，保持优秀的设计审美。
+- `get_guidelines`
+  - 推荐用法：
+    当你需要让 LLM 严格遵守 Codify 的转译规范、组件导入规则和最终硬闸门时，应优先调用该工具加载规则，而不是引用旧的资源 URI。
 
 ## 可用工具
 
@@ -126,28 +126,46 @@ codify://getCode/{contentId}
 
 #### **get_component_info**
 
-拉取指定团队库组件数据并落盘到本地 `.codify/library/<teamLibraryId>/<teamLibraryName>.json`，用于组件库页面生成。
+拉取指定团队库组件数据并落盘到本地 `.codify/library/<teamLibraryId>/<teamLibraryName>/`，用于组件库页面生成。每次指定团队库调用都会重新远端拉取并覆盖本地快照。
 
 - **参数**: `projectDir` (必填), `teamLibraryId` (可选), `teamLibraryName` (可选), `includePropertyDetails` (可选, 默认 true)
 - **示例**: "使用 Ant Design UIKit 团队库，拉取组件信息"
 
 组件库页面生成标准流程：
 1. 调用 `get_library_list` 确认团队库；
-2. 调用 `get_component_info` 拉取并落盘 JSON；
-3. 读取 JSON 结构：`components` 用于 `<ui-component>`，`icons` 用于 `<ui-icon>`；其中 `<ui-component>` 的 `props` 仅允许由 `components[].props` 推导（禁止臆造）。
+2. 调用 `get_component_info` 重新远端拉取并覆盖落盘 `index.md`、`components/*.json`、`icons.json`、`variable.json`；
+3. 先读 `index.md` 了解文件位置，再直接读取 `components/*.json` 作为 `<ui-component>` 来源，读取 `icons.json` 作为 `<ui-icon>` 来源；其中 `<ui-component>` 的 `props` 仅允许由组件详情文件里的 `props` 推导（禁止臆造）。
+
+#### **get_variables**
+
+获取当前 MasterGo 文件中的全部本地变量。只读取当前文件，不读取远程团队库。
+
+- **参数**: `projectDir` (必填)
+- **示例**: "获取当前文件的全部变量"
+- **返回**: `documentName`、`documentId`、`variables`
+- **落盘**: 将 `variables` 字段内容写入 `.codify/variable/{documentId}.json`
+
+#### **update_variables**
+
+创建、修改或删除当前 MasterGo 文件变量。
+
+- **固定流程**: 先调用 `get_variables` 落盘；创建一套变量时先 `update_variables` 提交基础变量，再 `get_variables` 刷新 ID，然后 `update_variables` 提交语义/引用变量，最后再次 `get_variables`
+- **参数**: `projectDir` (必填), `filePath` / `variables` / `operations` 三选一；也可传 `documentId` 让工具读取 `.codify/variable/{documentId}.json`
+- **规则**: 首次调用会自动加载 `variable-generate` 规则；已有变量修改必须保留 `id`
+- **示例**: "把当前变量文件提交到 MasterGo"
 
 ### 🎨 生成与设计
 
-#### **design**
+#### **design_page**
 
 根据自然语言需求生成符合 Codify 规范的 HTML+CSS 代码。
 
 - **参数**: `requirement` (必填)
 - **示例**: "帮我设计一个深色模式的登录页面"
 
-#### **agent_create_page**
+#### **submit_page_to_canvas**
 
-将生成的 HTML 代码发送到 MasterGo 插件并创建新页面。
+将生成的 HTML 代码发送到 MasterGo 并创建新页面。
 
 - **参数**: `code` (可选), `filePath` (可选), `projectDir` (必填), `saveCodeToLocal` (可选)
 - **示例**: "在 MasterGo 中创建一个新页面，代码在 ./temp.html"

package/dist/component-generate.md

@@ -6,7 +6,7 @@
 - 本文件不定义工作流编排与工具调用顺序；仅约束输出代码本身。
 
 ## 目标
-根据需求输出可被插件识别的组件代码，生成以下两类资产：
+根据需求输出可被 MasterGo 识别的组件代码，生成以下两类资产：
 1. `Component`（单个母版组件）
 2. `Component Set`（带变体的组件集）
 
@@ -86,6 +86,35 @@
 3. 根节点缺失 `data-type` 或 `data-name`。
 4. 输出页面容器（如 `<main w-[1440px]>`）来包裹组件集。
 
+## 与工具参数对齐
+- 提交组件时，传入字段是 `code`（不是 `htmlCode`）。
+- `code` 内容必须包含 `data-type="component"` 或 `data-type="component-set"`。
+
+## 变量样式优先（视觉语言一致性）
+
+如果当前文件已存在设计系统变量（`get_variables` 已落盘到 `{{docDir}}/variable/{documentId}.json`），母版组件样式**必须**优先通过 `var(...)` 引用变量，而不是写死字面值。
+
+适用属性：颜色、字号、字重、行高、圆角、边框宽度、阴影、间距（gap / padding / 单边）等关键视觉属性。
+
+约束、写法、回退策略一律遵循 `variable-import.md`，本文不重复展开。要点：
+
+- 变量引用统一写为 `var(变量 name)`，放入 Tailwind 任意值语法（如 `bg-[var(色彩/brand/primary)]` / `gap-[var(间距/index_8/sm)]`）
+- 引用时只能写变量 `name` 原文，禁止改写大小写 / 中英文 / 分隔符，禁止把 `value` 直接抄进 class
+- 找不到精确匹配时按语义最近邻；都不匹配才允许该属性局部回退字面值，并在自检里标注"属性 + 缺失变量原因"
+- 字面值回退时仍需满足 `page-generate.md` 的 8pt 网格 / Hex 颜色 / 整数 px 约束
+
+模板对照（同样的 button 组件，有变量时怎么写）：
+
+```html
+<div data-type="component" data-name="primary-button"
+     class="flex flex-row justify-center items-center bg-[var(色彩/brand/primary)] rounded-[var(圆角/index_8/sm)] px-[var(间距/index_16/md)] py-[var(间距/index_10/sm)]">
+  <span data-name="label"
+        class="text-[var(文字/正文/14)] leading-[var(行高/正文/1.2)] font-[var(字重/semibold)] text-[var(色彩/文本/反白)]">确认</span>
+</div>
+```
+
+只有当前文件**完全没有变量**（变量清单 JSON 为空或不存在）时，才允许回到本文件示例里的字面值写法。
+
 ## 输出前自检清单
 1. 根节点是否为 `component` 或 `component-set`。
 2. 每个节点是否都有 `data-name`。
@@ -93,7 +122,4 @@
 4. 变体维度键和值是否完整一致。
 5. 是否存在 margin / grid / 原生表单标签。
 6. Flex 是否显式写全。
-
-## 与工具参数对齐
-- 提交组件时，传入字段是 `code`（不是 `htmlCode`）。
-- `code` 内容必须包含 `data-type="component"` 或 `data-type="component-set"`。
+7. 当前文件存在变量时，关键视觉属性（颜色 / 文字 / 间距 / 圆角 / 边框 / 阴影）是否已经走 `var(...)` 引用；每个回退字面值是否在自检里标注了缺失原因。

package/dist/component-import.md

@@ -19,66 +19,52 @@
 
 ## 流程（仅组件库模式）
 1. `get_library_list`（确认目标团队库）
-2. `get_component_info`（落盘本地快照）
-3. 严格基于落盘 JSON 生成代码
-4. 如果你无法推测这个组件的形态，你可以查看 `index.json` 里 `cover` 字段的图片
-5. 使用 `variable.json` 里的样式变量
+2. `get_component_info`（重新远端拉取并覆盖落盘本地快照）
+3. 严格基于落盘文件生成代码
+4. 选择组件时必须参考 `components/*.json` 里的 `description`；它可能描述组件用途或限制，不能只按组件名猜测。
+5. 如果你无法推测这个组件的形态，你可以查看对应 `components/*.json` 里的 `cover` 字段图片
+6. 使用 `variable.json` 里的样式变量
 
 示例：
 ```text
-get_library_list -> get_component_info -> 读取 index/components/icons/variable -> 生成页面 -> agent_create_page
+get_library_list -> get_component_info -> 读取 index.md/components/icons/variable -> 生成页面 -> submit_page_to_canvas
 ```
 
 ## 数据来源（唯一事实）
 按顺序读取：
-1. `index.json`（候选组件）
-2. `components/{key}.json`（组件详情）
+1. `index.md`（文件导航和读取说明）
+2. `components/*.json`（组件详情；每个文件直接包含 `name`、`description`、`cover`、`size`、`props`、`slots`、`instance_swap`）
 3. `icons.json`
 4. `variable.json`（样式变量，必须读取）
 
-禁止臆造组件名、props、slot 名称、图标名或 instance_swap 值。
+所有 `name` 只能来自落盘文件，禁止改写：`components/*.json`、`icons.json`、`instance_swap`、`variable.json`。
 
 示例（读取顺序）：
 ```text
-先从 index.json 选“卡片”
-再读 components/001-卡片.json 获取 props/slots/instance_swap
+先读 index.md 了解组件、图标、变量文件在哪里
+再扫描/读取 components/*.json，找到“卡片”并获取 description/cover/props/slots/instance_swap
 再读 icons.json 选择图标名
 最后读 variable.json 使用设计变量
 ```
 
-## 变量样式协议（关键）
-- 在 `full-components` 与 `hybrid` 两种策略下，必须优先使用 `variable.json` 中可用变量表达样式。
-- 适用范围：颜色、字号、字重、行高、圆角、边框宽度、阴影、间距（gap/padding）等关键视觉属性。
-- 变量引用格式统一为 `var(...)`，并放入 Tailwind 任意值语法；引用时必须使用变量名（`name`，缺失时可用 `ukey`），禁止直接抄 `value`。
-- 若变量项为 `{ name: "色彩/brand/primary", value: "#1677FF" }`，必须写 `bg-[var(色彩/brand/primary)]`，禁止写 `bg-[#1677FF]`。
-- 若变量项为 `{ name: "间距/index_10/sm", value: "8px" }`，必须写 `gap-[var(间距/index_10/sm)]`，禁止写 `gap-[8px]`。
-- 变量引用示例：
-  - `bg-[var(色彩/brand/primary)]`
-  - `text-[var(文字/正文/14)]`
-  - `gap-[var(间距/index_10/sm)]`
-  - `rounded-[var(圆角/index_6/md)]`
-- 仅当 `variable.json` 中确实不存在可匹配变量时，才允许回退字面值（Hex/px）；并需在输出前自检中标注“属性 + 缺失变量原因”。
-
-示例：
-```html
-<div data-name="filter-wrap" class="flex flex-row justify-start items-center gap-[var(间距/index_10/sm)] p-[var(间距/index_12/md)] bg-[var(色彩/填充/容器)] rounded-[var(圆角/index_6/md)]">
-  <span data-name="filter-label" class="text-[var(文字/正文/14)] leading-[var(行高/正文/1.5)] font-[var(字重/medium)] text-[var(色彩/文本/主)]">筛选条件</span>
-</div>
-```
+## 变量样式
+- 组件库模式下变量来源为 `variable.json`，引用写法、强约束、回退策略一律遵循 `variable-import.md`。
+- 本文档不重复展开；所有 `full-components` / `hybrid` 输出必须同时满足 `variable-import.md` 的硬约束。
 
 ## 合法引用
 - `<ui-component name="...">`
-  - `name` 必须来自组件详情
+  - `name` 只能来自 `components/*.json` 的 `name`，禁止改写
   - `props` 字段必须存在于组件详情
   - `props` / `instance_swap` / `variants` 等 JSON 属性必须使用**单引号**包裹，内部 JSON 使用双引号（合法 JSON）
   - 严禁输出 HTML 实体编码到 JSON 属性中（如 `&quot;` / `&#34;` / `&#x22;`）
   - 若模型生成了双引号包裹 JSON 或实体编码，必须在最终输出前改写为单引号 JSON 属性
-  - `instance_swap` 的值优先使用组件名（name）；也可使用 ukey 或组件库 component id
+  - `instance_swap` 的值必须使用组件详情里已归一化的组件名（name）
+  - `instance_swap` 的 value 只能来自组件详情中的 `instance_swap` 或 `icons[].name`，禁止改写
   - 禁止使用画布节点 ID（例如 `data-node-id` / `450:74735/414:32354`）作为 `instance_swap` 值
   - 布局样式按排版需要声明：需要填充主区域时使用 `flex-1` / `self-stretch`；需要固定宽度时可写 `w-[...]`
   - `class` 按需声明：若不需要额外布局/视觉覆盖可省略；若处于复杂布局容器中，建议补充布局 class 以保证排版稳定
 - `<ui-icon name="...">`
-  - `name` 必须来自 `icons[].name`
+  - `name` 只能来自 `icons[].name`，禁止改写
   - 仅用于“独立图标节点”或“组件明确存在可承载图标节点的 slot”
   - 禁止把 `<ui-icon slot="...">` 当作 `instance_swap` 的替代写法
 
@@ -116,9 +102,10 @@ get_library_list -> get_component_info -> 读取 index/components/icons/variable
 ## 子实例接入决策（instance_swap vs 子节点直写）
 - 先看组件详情：
   - `slots` 非空：按 slot 白名单注入内容（`<ui-slot name="...">` 或 `slot="..."`）。
-  - `slots` 为空但存在 `instance_swap`（如 `"图标": "10:38187"` / `"前缀": "10:xxxx"`）：使用 `<ui-component instance_swap='...'>`，不要用子节点伪造替换。
+  - `slots` 为空但存在 `instance_swap`（如 `"图标": "SwitchButton"` / `"前缀": "搜索图标"`）：使用 `<ui-component instance_swap='...'>`，不要用子节点伪造替换。
 - `instance_swap` 是通用“子实例替换”通道，不仅限图标；也可用于前后缀、状态标记、操作区子组件等可替换实例。
-- `instance_swap` 的 value 必须来自组件能力映射（组件名/name、ukey 或组件 id），不是任意字符串。
+- `instance_swap` 的 value 必须来自组件能力映射里的组件名（name），禁止改写。
+- 当 value 来自 `icons.json` 时，只能来自 `icons[].name`，禁止改写。
 - 若某替换目标存在对应 props 开关（如 `显示图标` / `显示右边图标` / `启用前缀`），使用替换时必须同步设为 `true`。
 - `instance_swap` 与子节点直写是两条通道：前者是组件内部实例替换，后者是显式节点渲染，不能混用表达同一替换位。
 
@@ -198,7 +185,7 @@ get_library_list -> get_component_info -> 读取 index/components/icons/variable
 ## 构建策略
 - `full-components`（全组件设计模式）：
   - 页面中的功能区块（如头部、筛选区、表单区、表格区、操作区、状态区）必须优先使用 `<ui-component>`
-  - 只要 `index.json + components/*.json` 中存在可用组件，就禁止改为普通 HTML 自绘
+  - 只要 `components/*.json` 中存在可用组件，就禁止改为普通 HTML 自绘
   - 必须全量使用组件库样式变量与图标系统（变量优先，格式为 `var(...)`）
   - 仅当本地快照中确实不存在可用组件时，才允许局部回退普通 HTML，并在输出前自检中逐项说明“缺失组件原因”
 - `hybrid`（混合设计模式）：
@@ -214,18 +201,17 @@ buildStrategy = "hybrid"
 
 ## full-components 专项硬约束
 - 禁止把常见可组件化区块直接自绘：按钮、输入框、下拉、表单项、标签、卡片、表格、分页、弹窗、菜单、导航、空状态、加载态。
-- 先从 `index.json` 选择候选组件，再读取对应 `components/{key}.json` 确认 props/slots；确认可用后必须使用 `<ui-component>`。
+- 先读取 `index.md` 了解文件位置，再从 `components/*.json` 选择候选组件并确认 props/slots；确认可用后必须使用 `<ui-component>`。
 - 组件布局样式按排版需要声明：占满剩余空间使用 `flex-1/self-stretch`；仅在需要固定宽度时写 `w-[...]`。
 - 若最终出现普通 HTML 区块，必须满足两条：
   1. 在组件快照中无法找到可替代组件；
   2. 在输出前自检中逐项标注“区块名 + 缺失原因”。
-- 变量样式强约束：凡能匹配 `variable.json` 的样式属性必须使用 `var(...)`，不得随意写 Hex/px 字面值。
-- 变量名强约束：`var(...)` 中必须写变量名（`name`/`ukey`），禁止把 `value` 直接写进 class（如 `bg-[#1677FF]`、`gap-[8px]`）。
+- 变量样式遵循 `variable-import.md`：能匹配 `variable.json` 的属性必须 `var(...)`；只写 `name`，禁止抄 `value`。
 
 ## 失败回退
 关键字段缺失或不确定时，允许回退普通 HTML；不要使用不确定的组件引用。
 但在 `full-components` 模式下，回退仅限“组件快照不存在可替代项”的区块，且必须在自检中逐项说明。
-变量缺失时，也仅允许该属性局部回退字面值，并在自检中说明“属性 + 缺失变量原因”。
+变量回退细则见 `variable-import.md`。
 
 示例：
 ```text
@@ -236,7 +222,9 @@ buildStrategy = "hybrid"
 - 修改现有节点时，默认使用 `agent_update_node`。
 - 图标、图片、样式、文本及大多数局部结构调整，都应优先通过 `agent_update_node` 完成。
 
-推荐顺序：
+**重要前置条件**：`get_selection_code` 仅用于"读取/同步当前画布上下文"。在用户没有给出具体修改诉求（例如"把按钮改成蓝色"、"替换文案为 XXX"）之前，**禁止**在 `get_selection_code` 之后自动衔接 `agent_update_node` / `agent_replace_node` / `sync_to_design`。仅完成读取后即停下来，等待用户的下一步指令。
+
+推荐顺序（仅当用户已发出明确修改诉求时才进入）：
 1. `get_selection_code` 拉取最新上下文
 2. `agent_update_node` 提交属性修改
 3. 再次 `get_selection_code` 验证结果

package/dist/en.template.json

@@ -0,0 +1,129 @@
+{
+  "getGuidelines": {
+    "description": "[Session entry] When the user wants to use {{displayName}} / MasterGo workflows (e.g. \"use {{displayName}} mcp\", \"design with {{displayName}}\"), call this tool first. scope is a string array, default [\"page-generate\"]. Available values: page-generate / component-import / component-generate / variable-import / variable-generate. component-generate is only for agent_create_component master component/component-set creation; for team/component-library page generation, pass [\"page-generate\",\"component-import\",\"variable-import\"].",
+    "inputSchema": "Optional: scope (string array, items in page-generate / component-import / component-generate / variable-import / variable-generate). Default [\"page-generate\"]. Multiple scopes are concatenated and a Final Hard Gate section is appended."
+  },
+  "createPage": {
+    "description": "[INTERNAL submission tool · Only call after design_page has produced final HTML] Submits a fully-generated page HTML to the {{pluginName}} canvas. ⚠️ When the user says \"design / create / make / build / draw / generate a page\" (or the Chinese equivalents 设计 / 创建 / 做一个 / 帮我画 / 生成 一个页面), DO NOT call this tool directly — you MUST first call design_page to go through requirement decomposition and design-source selection. This tool only ships the final HTML produced by the design_page flow.\n\n[Performance Tip] If pure HTML is already saved as a local file, prefer passing the absolute path via filePath to save tokens. If the code is temporarily generated, use the code parameter directly.\n\nReverse Transpilation Warning: Strictly forbidden to directly send Vue/React business code containing dynamic bindings ({{}}) or framework directives! If you want to convert business code to a design, you MUST first perform \"Reverse Transpilation\" and, when needed, load the official rules through get_guidelines before sending pure HTML with static mock data.",
+    "code": "[Optional] The HTML code content to send. Use ONLY if the code is temporarily generated and not saved as a file.",
+    "filePath": "[Optional] The absolute path of the local HTML file. If the file exists locally, you MUST pass this parameter; the tool will automatically read and persist it.",
+    "projectDir": "[Required] The absolute path of the user's current workspace root directory.",
+    "saveCodeToLocal": "Whether to save the rendering results returned by the plugin to the local {{docDir}} directory (persistence mechanism)."
+  },
+  "updateNode": {
+    "description": "Default tool for edits on existing nodes. Text, styles, icons, images, and most local structural adjustments should all use agent_update_node first. Note: if modifying a parent container's styles or internal content, the returned HTML must include all child elements that should be preserved to prevent data loss.",
+    "documentId": "Current MasterGo document ID.",
+    "documentPageId": "Current MasterGo page ID.",
+    "targetNodeId": "[Optional] Target layer ID (e.g., 123:456). Defaults to the current selection.",
+    "code": "[Required] Modified HTML fragment. MUST include data-node-id."
+  },
+  "replaceNode": {
+    "description": "Use this tool only when the user explicitly asks to replace a specific node, icon, or image. Icons should follow FontAwesome, and image replacement should follow the <img src=\"{{keyword}}\" /> semantic convention.",
+    "documentId": "Current MasterGo document ID.",
+    "documentPageId": "Current MasterGo page ID.",
+    "targetNodeId": "[Optional] Target layer ID (e.g., 123:456). Defaults to the current selection.",
+    "code": "[Required] New HTML code. Will fully replace the target node content."
+  },
+  "removeVariable": {
+    "description": "Remove variable: dedicated tool for dangerous delete operations. Deletes variables in the current MasterGo file and does not use update_variables; tool name is agent_remove_variable. Prefer id; without id, collection/collectionId + name + type are required to avoid accidental deletion. The first call auto-loads the variable-generate rules.",
+    "documentId": "Current MasterGo document ID.",
+    "documentPageId": "Current MasterGo page ID.",
+    "id": "[Recommended] Variable ID to delete.",
+    "collection": "[Required without id] Variable collection name.",
+    "collectionId": "[Optional] Variable collection ID; can replace collection.",
+    "name": "[Required without id] Variable name.",
+    "type": "[Required without id] Variable type, such as COLOR, PAINT, NUMBER.",
+    "variables": "[Optional] Batch delete array. Each item should provide id, or collection/collectionId + name + type."
+  },
+  "syncToDesign": {
+    "description": "Perform a [Full Sync]: overwrite the MasterGo design with your full static HTML file. Only call this when the user explicitly asks to sync to canvas; never auto-sync after local edits.",
+    "documentId": "Current MasterGo document ID.",
+    "documentPageId": "Current MasterGo page ID.",
+    "targetNodeId": "[Recommended] Root Node ID (rootId). Defaults to current selection if omitted.",
+    "filePath": "[Required] Absolute path of local static HTML file (found in {{docDir}}/...). Tool auto-reads the file. NEVER pass .vue/.tsx paths!",
+    "userConfirmed": "[Required] Whether the user explicitly confirmed syncing to canvas. Only pass true after explicit user request."
+  },
+  "getSelectionCode": {
+    "description": "Get HTML/CSS code for the currently selected layer (or a specified layer) in MasterGo and intelligently persist it to the local project directory. This tool ONLY reads/syncs context — do NOT chain agent_update_node / agent_replace_node / sync_to_design after this call unless the user has issued an explicit modification request. The generated code is typically used for partial modifications or syncing local base files. For a rendered preview image (visual reference), call get_selection_image separately.",
+    "projectDir": "[Required] The absolute path of the user's current workspace root directory.",
+    "targetNodeId": "[Optional] MasterGo layer ID (e.g., 123:456). If provided, the code for that ID will be pulled directly; if not, the code for the currently selected layer will be pulled.",
+    "syncToBase": "[Optional] Whether to sync the obtained child layer code back to the base HTML file in the local {{docDir}} directory (merge update). Defaults to true."
+  },
+  "getSelectionImage": {
+    "description": "Get a rendered preview (PNG by default) of the currently selected layer (or a specified layer) in MasterGo. Call this ONLY when you need a visual reference — e.g. \"match the design\", \"reproduce this design\", \"follow the visual\", \"reference the mockup\", \"还原设计稿\", \"对照视觉\". The response includes an image content block for multimodal grounding and persists a copy to {{docDir}}/.preview/ so the user can verify what the model saw. For routine code sync / small edits use get_selection_code, not this tool.",
+    "projectDir": "[Required] Absolute path of the workspace root. Previews are persisted to {{docDir}}/.preview/{documentId}/{pageId}/{nodeId}.png under this root.",
+    "targetNodeId": "[Optional] MasterGo layer ID (e.g., 123:456). If provided, that layer is exported; otherwise the currently selected layer is exported.",
+    "targetNodeIds": "[Optional] Batch list of target layer IDs. When provided, previews are exported in list order."
+  },
+  "createComponent": {
+    "description": "Create a MasterGo master component or component set (variant). Only when creating master components/component sets, load get_guidelines(scope=[\"component-generate\"]) first, then call this tool. Do not use component-generate for team/component-library page generation. This tool only sends code to plugin and does not perform fallback rule validation.",
+    "code": "Pure HTML string of the component. Root node must include data-type=\"component\" or \"component-set\". For component-set, variant nodes must be direct children and variant attributes must be declared with flat data-variant-* fields.",
+    "projectDir": "[Optional] Absolute path of the user workspace root. When provided, the tool checks {{docDir}}/variable/ for the current file's variable snapshot; if found, the variable-import rules are loaded automatically so master components reference var(...) tokens instead of literal values, preserving design-system consistency."
+  },
+  "getDesignDiff": {
+    "description": "Get the difference between the local base file and the current MasterGo canvas design. Returns a JSON Diff result to help determine what layers or styles have changed.",
+    "projectDir": "[Required] The absolute path of the user's current workspace root directory.",
+    "targetNodeId": "[Optional] MasterGo layer ID (e.g., 123:456). If not provided, the code of the currently selected layer will be fetched for comparison by default.",
+    "filePath": "[Optional] The absolute path of the local base HTML file. If you have updated the base file via write_to_file, pass this path directly.",
+    "syncType": "[Optional] Sync direction, must be codeSyncDesign (code syncs to design) or designSyncCode (design syncs to code)."
+  },
+  "getCodeList": {
+    "description": "Get a list of all available code items",
+    "inputSchema": "Get code list without parameters"
+  },
+  "design": {
+    "description": "[PAGE DESIGN MAIN ENTRY · MUST be the first call] When the user expresses any page-level generation intent — \"design / create / make / build / draw / generate a page\" or the Chinese equivalents 设计 / 创建 / 做一个 / 帮我画 / 生成 一个页面 — you MUST call this tool first. NEVER call submit_page_to_canvas directly to skip this flow. This tool owns requirement decomposition, design-source selection, and HTML+CSS generation; the final HTML is then handed off to submit_page_to_canvas. Fixed flow: first let the user choose one of three design sources — free-draw / current-file-variables / component-library. Choosing current-file-variables enforces get_variables to persist the current file variables and then references them via variable-import.md. Choosing component-library asks for a team library and a build strategy. Only after these confirmations will the page be generated.",
+    "requirement": "Interface requirement description, e.g., \"a beautiful login page\", \"a modern dashboard interface\", etc.",
+    "code": "[Optional] If full code is already generated (can include Markdown + <main>), it will auto-extract <main> and submit directly to canvas.",
+    "projectDir": "[Optional] Absolute path of the user workspace root. Required when reading or writing {{docDir}} snapshots (variables / component library).",
+    "designSource": "[Required by workflow] Design source, one of: free-draw / current-file-variables / component-library. The user must explicitly choose each design_page call.",
+    "userConfirmedDesignSource": "[Required by workflow] Whether the user confirmation for the three-way design-source choice has been completed in this page-generation flow.",
+    "teamLibraryName": "[Required in component mode] User-confirmed team library name. Must be reconfirmed each time; assistant must not auto-pick.",
+    "teamLibraryId": "[Recommended in component mode] User-confirmed team library ID. When the ID is already known (e.g. from get_library_list), pass it alongside teamLibraryName; used to dedupe same-library checks accurately and avoid false reuse when two libraries normalize to the same name.",
+    "buildStrategy": "[Required in component mode] Build strategy: full-components / hybrid. full-components prioritizes library components; hybrid uses components only for key functional areas. Both strategies must follow component-import.md + variable-import.md. If omitted, ask the user to choose first."
+  },
+  "getUserInfo": {
+    "description": "Get current logged-in user information, including quotas, teams, etc.",
+    "inputSchema": "Get current user information"
+  },
+  "getCode": {
+    "description": "[Specific Scenario] Get code from the {{pluginName}} via contentId. For regular \"get selected code\" tasks, please prioritize using the get_selection_code tool.",
+    "contentId": "Instruction to copy layers from the {{pluginName}} (contentId)",
+    "documentId": "Current MasterGo document ID.",
+    "documentPageId": "Current MasterGo page ID.",
+    "projectDir": "[Required] The absolute path of the user's current workspace root directory.",
+    "outDir": "[Required] The absolute path to save code and resources"
+  },
+  "getLibraryList": {
+    "description": "Get team library list subscribed/loaded in current file (name, id, componentCount, styleCount). When user says \"generate page with xxx component library\", call this tool first.",
+    "inputSchema": "No parameters"
+  },
+  "getComponentInfo": {
+    "description": "Get component data of a specified team library and persist it as a local snapshot for component-library page generation. Each call with a specified team library re-fetches from remote and overwrites the local snapshot. Only call this when the user explicitly wants to generate with a team/component library; do not call it for regular design flows. If teamLibraryId is missing, return library choices first; after user confirmation, teamLibraryName can auto-match the id. Page generation rules live in component-import.md.",
+    "projectDir": "[Required] Absolute path of the user's workspace root (for persistence).",
+    "teamLibraryId": "[Optional] Team library ID. If provided, fetch directly.",
+    "teamLibraryName": "[Optional] Team library name. Used to auto-match ID when teamLibraryId is not provided.",
+    "includePropertyDetails": "[Optional] Include component property details. Default true."
+  },
+  "getVariables": {
+    "description": "Get all local variables in the current MasterGo file. This reads the current file only, not remote team libraries. Returns documentName, documentId, and variables (same batch array format as updateVariables); also accepts API responses that return a bare array. On success, writes the variables field to {{docDir}}/variable/{documentId}.json.",
+    "inputSchema": "Required: projectDir (absolute workspace root for writing the snapshot).",
+    "projectDir": "[Required] Absolute path of the workspace root; variables are written to {{docDir}}/variable/{documentId}.json."
+  },
+  "updateVariables": {
+    "description": "Update variables: create, modify, or reorder variables in the current MasterGo file. Deleting variables must use agent_remove_variable. Fixed flow: call get_variables first; when creating a token set, submit base variables first, call get_variables again, then submit semantic/reference variables, and finally call get_variables again. The first call auto-loads the variable-generate rules.",
+    "inputSchema": "Required: projectDir. Provide one data source: filePath, variables, or operations. If only documentId is provided, reads {{docDir}}/variable/{documentId}.json.",
+    "projectDir": "[Required] Absolute path of the user's workspace root.",
+    "documentId": "[Optional] Current MasterGo document ID; used to locate {{docDir}}/variable/{documentId}.json when filePath/variables/operations are omitted.",
+    "documentPageId": "[Optional] Current MasterGo page ID.",
+    "filePath": "[Optional] Absolute path of the variable JSON file, typically {{docDir}}/variable/{documentId}.json from get_variables.",
+    "variables": "[Optional] Variable array in the same format written by get_variables; { variables: [...] } is also accepted.",
+    "operations": "[Optional] Operation array for createVariable/updateVariable/moveVariable and other non-snapshot operations. Use agent_remove_variable for deletes."
+  },
+  "removeNode": {
+    "description": "Delete nodes in the MasterGo canvas. Supports specifying an ID via targetNodeId, or defaults to the currently selected layer if no ID is provided.",
+    "documentId": "Current MasterGo document ID.",
+    "documentPageId": "Current MasterGo page ID.",
+    "targetNodeId": "[Optional] The target layer ID to delete (e.g., 123:456). If not provided, the currently selected layer in MasterGo will be deleted by default."
+  }
+}