@szc-ft/mcp-szcd-client 0.23.1 → 0.25.0

package/opencode-extension/skills/local-api-tool/scripts/extract_swagger.py

@@ -0,0 +1,477 @@
+#!/usr/bin/env python3
+"""
+extract_swagger.py — 本地 Swagger 文档提取与解析（与服务端 parseApiDocs 一比一对齐）
+
+设计目标：
+- 一步完成"下载 → 解析 → 按 tag/path 过滤 → 关联 DTO definitions → 输出"
+- 避免 AI 在客户端用 curl|head 截断 JSON / 写临时 python 脚本踩花括号坑
+- 输出结构与服务端 api_tool(action="parse_swagger_json") 完全一致，可平替
+
+参考实现：szcd-mcp-server/src/lib/swagger.js 的 parseApiDocs + server.js 的 filterApis
+        递归深度 5，两层 definitions（summary + detail），引用树传递闭包裁剪。
+
+用法：
+  # 方式 A：脚本内部 curl 下载
+  extract_swagger.py --url http://10.x.x.x/svc/v2/api-docs [--cookie 'JSESSIONID=xxx']
+
+  # 方式 B：读取本地已下载的 JSON 文件
+  extract_swagger.py --file /tmp/swagger.json
+
+  # 过滤（对 url/summary/operationId/tag/description/dtoRef/responseVoName 模糊匹配，大小写不敏感）
+  extract_swagger.py --file /tmp/swagger.json --filter tag
+  extract_swagger.py --file /tmp/swagger.json --filter tag --filter user
+
+  # 仅查询单个 definition（兜底单 VO 查询，等价于服务端 get_definition）
+  extract_swagger.py --file /tmp/swagger.json --definition KnowledgeOperLogVO
+
+  # 输出到文件而非 stdout
+  extract_swagger.py --file /tmp/swagger.json --filter tag --out /tmp/parsed.json
+
+退出码：0 成功；1 参数错误；2 网络/IO 错误；3 解析错误
+"""
+
+import argparse
+import json
+import sys
+import subprocess
+from pathlib import Path
+
+MAX_DEPTH = 5
+METHOD_KEYS = ["post", "get", "put", "delete", "patch"]
+
+
+# ==================== 工具函数 ====================
+
+def _ref_name(prop):
+    """从 property 定义中提取 $ref/originalRef 名称（不含数组 items 层）。"""
+    if not isinstance(prop, dict):
+        return None
+    if prop.get("originalRef"):
+        return prop["originalRef"]
+    ref = prop.get("$ref")
+    if ref:
+        return ref.rsplit("/", 1)[-1]
+    return None
+
+
+def _ref_name_with_items(prop):
+    """提取 $ref 名称，包含数组 items 层（对齐 JS 端 expandProperties 第 250-251 行）。"""
+    if not isinstance(prop, dict):
+        return None
+    name = _ref_name(prop)
+    if name:
+        return name
+    items = prop.get("items")
+    if isinstance(items, dict):
+        return _ref_name(items)
+    return None
+
+
+def _resolve_property_type(prop):
+    """对齐 JS 端 resolvePropertyType：数组返回 array<XXX>，否则返回 type 或 $ref 名。"""
+    if not isinstance(prop, dict):
+        return "string"
+    if prop.get("type") == "array":
+        items = prop.get("items") or {}
+        item_type = (
+            items.get("type")
+            or items.get("originalRef")
+            or (items.get("$ref", "").rsplit("/", 1)[-1] if items.get("$ref") else None)
+            or "object"
+        )
+        return f"array<{item_type}>"
+    if prop.get("type"):
+        return prop["type"]
+    if prop.get("originalRef"):
+        return prop["originalRef"]
+    if prop.get("$ref"):
+        return prop["$ref"].rsplit("/", 1)[-1]
+    return "object"
+
+
+# ==================== 递归展开（对齐 JS 端 expandProperties，深度 5） ====================
+
+def expand_properties(properties, definitions, depth=0, max_depth=MAX_DEPTH):
+    if not properties:
+        return []
+    result = []
+    for name, prop in properties.items():
+        if not isinstance(prop, dict):
+            prop = {}
+        entry = {
+            "name": name,
+            "type": _resolve_property_type(prop),
+            "description": prop.get("description", ""),
+        }
+        if "format" in prop:
+            entry["format"] = prop["format"]
+        if "example" in prop:
+            entry["example"] = prop["example"]
+        if "enum" in prop:
+            entry["enum"] = prop["enum"]
+
+        ref_name = _ref_name_with_items(prop)
+        if ref_name:
+            entry["refName"] = ref_name
+
+        # 数组类型：展开 items 的嵌套属性
+        if prop.get("type") == "array" and ref_name and depth < max_depth:
+            item_def = (definitions or {}).get(ref_name)
+            if isinstance(item_def, dict) and item_def.get("properties"):
+                entry["itemProperties"] = expand_properties(
+                    item_def["properties"], definitions, depth + 1, max_depth
+                )
+
+        # 对象类型（非数组）：展开嵌套属性
+        if prop.get("type") == "object" and ref_name and depth < max_depth:
+            nested_def = (definitions or {}).get(ref_name)
+            if isinstance(nested_def, dict) and nested_def.get("properties"):
+                entry["nestedProperties"] = expand_properties(
+                    nested_def["properties"], definitions, depth + 1, max_depth
+                )
+
+        # 无 $ref 的 object 且有自身 properties（内联定义）
+        if (
+            prop.get("type") == "object"
+            and not ref_name
+            and prop.get("properties")
+            and depth < max_depth
+        ):
+            entry["nestedProperties"] = expand_properties(
+                prop["properties"], definitions, depth + 1, max_depth
+            )
+
+        result.append(entry)
+    return result
+
+
+# ==================== 主解析（对齐 JS 端 parseApiDocs） ====================
+
+def parse_api_docs(api_docs, referenced_defs=None):
+    paths = api_docs.get("paths") or {}
+    tags = api_docs.get("tags") or []
+    definitions = api_docs.get("definitions") or {}
+    info = api_docs.get("info") or {}
+    api_base_path = api_docs.get("basePath") or ""
+
+    parsed_tags = [
+        {"name": t.get("name"), "description": t.get("description", "")} for t in tags
+    ]
+
+    parsed_apis = []
+    auto_referenced_defs = set()
+
+    for url, path_value in paths.items():
+        if not isinstance(path_value, dict):
+            continue
+        for method in METHOD_KEYS:
+            api_def = path_value.get(method)
+            if not isinstance(api_def, dict):
+                continue
+            tag = (api_def.get("tags") or ["default"])[0]
+            parameters = api_def.get("parameters") or []
+
+            params = []
+            for p in parameters:
+                schema = p.get("schema") or {}
+                param_info = {
+                    "name": p.get("name"),
+                    "in": p.get("in"),
+                    "required": p.get("required", False),
+                    "type": p.get("type") or schema.get("type") or "string",
+                    "description": p.get("description", ""),
+                }
+                # body 参数引用的 DTO
+                ref_name = schema.get("originalRef") or (
+                    schema.get("$ref", "").rsplit("/", 1)[-1] if schema.get("$ref") else None
+                )
+                if ref_name:
+                    param_info["dtoRef"] = ref_name
+                    auto_referenced_defs.add(ref_name)
+                    dto = definitions.get(ref_name)
+                    if isinstance(dto, dict) and dto.get("properties"):
+                        dto_props = expand_properties(dto["properties"], definitions, 0, MAX_DEPTH)
+                        required_fields = dto.get("required") or []
+                        for prop in dto_props:
+                            if prop["name"] in required_fields:
+                                prop["required"] = True
+                        param_info["dtoProperties"] = dto_props
+                params.append(param_info)
+
+            # 响应（递归展开嵌套 VO）
+            response_info = None
+            responses = api_def.get("responses") or {}
+            r200 = responses.get("200") or {}
+            r_schema = r200.get("schema") if isinstance(r200, dict) else None
+            if isinstance(r_schema, dict):
+                ref_name = r_schema.get("originalRef") or (
+                    r_schema.get("$ref", "").rsplit("/", 1)[-1] if r_schema.get("$ref") else None
+                )
+                if ref_name:
+                    auto_referenced_defs.add(ref_name)
+                    vo = definitions.get(ref_name)
+                    if isinstance(vo, dict) and vo.get("properties"):
+                        response_info = {
+                            "voName": ref_name,
+                            "properties": expand_properties(
+                                vo["properties"], definitions, 0, MAX_DEPTH
+                            ),
+                        }
+                    else:
+                        response_info = {"voName": ref_name}
+
+            parsed_apis.append({
+                "url": url,
+                "method": method.upper(),
+                "tag": tag,
+                "summary": api_def.get("summary", ""),
+                "description": api_def.get("description", ""),
+                "deprecated": api_def.get("deprecated", False),
+                "parameters": params,
+                "response": response_info,
+                "operationId": api_def.get("operationId"),
+            })
+
+    # 收集被引用 definitions 的传递闭包
+    collected_refs = set(auto_referenced_defs)
+    queue = list(auto_referenced_defs)
+    while queue:
+        name = queue.pop(0)
+        d = definitions.get(name)
+        if not isinstance(d, dict) or not d.get("properties"):
+            continue
+        for prop in d["properties"].values():
+            ref_name = _ref_name_with_items(prop)
+            if ref_name and ref_name in definitions and ref_name not in collected_refs:
+                collected_refs.add(ref_name)
+                queue.append(ref_name)
+
+    # definitions 摘要层：所有 VO/DTO 的 name + type + description
+    definitions_summary = [
+        {
+            "name": name,
+            "type": d.get("type", "object") if isinstance(d, dict) else "object",
+            "description": (d.get("description") or d.get("title") or "") if isinstance(d, dict) else "",
+        }
+        for name, d in definitions.items()
+    ]
+
+    # definitionsDetail 详情层：仅展开被引用的（含传递闭包），递归深度 5
+    effective_refs = referenced_defs if referenced_defs is not None else collected_refs
+    definitions_detail = []
+    for name in effective_refs:
+        d = definitions.get(name)
+        if isinstance(d, dict):
+            definitions_detail.append({
+                "name": name,
+                "type": d.get("type", "object"),
+                "description": d.get("description") or d.get("title") or "",
+                "properties": expand_properties(
+                    d.get("properties") or {}, definitions, 0, MAX_DEPTH
+                ),
+            })
+
+    return {
+        "info": {
+            "title": info.get("title"),
+            "version": info.get("version"),
+            "description": info.get("description"),
+        } if info else None,
+        "basePath": api_base_path,
+        "tags": parsed_tags,
+        "apis": parsed_apis,
+        "definitions": definitions_summary,
+        "definitionsDetail": definitions_detail,
+    }
+
+
+# ==================== 过滤（对齐 JS 端 filterApis + apiFilter 裁剪 definitionsDetail） ====================
+
+def filter_apis(apis, keywords):
+    """对齐 JS 端 filterApis：对 url/summary/operationId/tag/description/dtoRef/voName 模糊匹配。"""
+    if not keywords or not apis:
+        return apis
+    lower_keywords = [k.lower() for k in keywords]
+    out = []
+    for api in apis:
+        dto_refs = " ".join(p.get("dtoRef", "") for p in (api.get("parameters") or []) if p.get("dtoRef"))
+        response_vo = (api.get("response") or {}).get("voName", "") if api.get("response") else ""
+        searchable = " ".join([
+            api.get("url", ""),
+            api.get("summary", ""),
+            api.get("operationId") or "",
+            api.get("tag", ""),
+            api.get("description", ""),
+            dto_refs,
+            response_vo,
+        ]).lower()
+        if any(kw in searchable for kw in lower_keywords):
+            out.append(api)
+    return out
+
+
+def trim_definitions_detail(result, keywords):
+    """apiFilter 生效时，definitionsDetail 仅保留匹配 API 引用的（含传递闭包）。
+    对齐 JS 端 server.js 第 1581-1604 行的裁剪逻辑。"""
+    apis = result.get("apis") or []
+    matched_refs = set()
+    for api in apis:
+        for p in api.get("parameters") or []:
+            if p.get("dtoRef"):
+                matched_refs.add(p["dtoRef"])
+        if api.get("response") and api["response"].get("voName"):
+            matched_refs.add(api["response"]["voName"])
+
+    detail_index = {d["name"]: d for d in result.get("definitionsDetail") or []}
+    detail_names = set(matched_refs)
+    queue = list(matched_refs)
+    while queue:
+        name = queue.pop(0)
+        detail = detail_index.get(name)
+        if not detail or not detail.get("properties"):
+            continue
+        for prop in detail["properties"]:
+            ref = prop.get("refName")
+            if ref and ref not in detail_names:
+                detail_names.add(ref)
+                queue.append(ref)
+
+    result["definitionsDetail"] = [d for d in result.get("definitionsDetail") or [] if d["name"] in detail_names]
+    result["_filter"] = {
+        "keywords": keywords,
+        "matched": len(apis),
+    }
+    return result
+
+
+# ==================== get_definition（单 VO 查询兜底） ====================
+
+def get_definition(api_docs, definition_name):
+    """对齐 JS 端 get_definition action：按名查询单个 VO，找不到给模糊匹配建议。"""
+    definitions = api_docs.get("definitions") or {}
+    if definition_name in definitions:
+        result = parse_api_docs(api_docs, referenced_defs={definition_name})
+        target = next((d for d in result["definitionsDetail"] if d["name"] == definition_name), None)
+        return {"found": True, "definition": target}
+
+    # 模糊匹配
+    lower = definition_name.lower()
+    suggestions = [n for n in definitions.keys() if lower in n.lower()][:10]
+    return {
+        "found": False,
+        "definitionName": definition_name,
+        "suggestions": suggestions,
+        "message": f"未找到 definition '{definition_name}'。" + (
+            f"相近建议：{', '.join(suggestions)}" if suggestions else "无相近匹配。"
+        ),
+    }
+
+
+# ==================== 输入：curl 下载 / 读文件 ====================
+
+def fetch_via_curl(url, cookie=None, auth=None, timeout=30):
+    """脚本内部走 curl 下载 Swagger JSON。失败抛 RuntimeError。"""
+    cmd = ["curl", "-sS", "--connect-timeout", "10", "--max-time", str(timeout),
+           "-H", "Accept: application/json"]
+    if cookie:
+        cmd += ["-H", f"Cookie: {cookie}"]
+    if auth:
+        cmd += ["-H", f"Authorization: Basic {auth}"]
+    cmd.append(url)
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except FileNotFoundError:
+        raise RuntimeError("找不到 curl 命令，请确认本地已安装 curl") from None
+    if r.returncode != 0:
+        raise RuntimeError(f"curl 失败 (exit {r.returncode}): {r.stderr.strip() or '无错误输出'}")
+    if not r.stdout.strip():
+        raise RuntimeError("curl 返回空响应")
+    return r.stdout
+
+
+def load_json_text(text):
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        # 给出第一行 200 字符 + 错误位置，方便排查
+        preview = text[:200].replace("\n", "\\n")
+        raise RuntimeError(f"JSON 解析失败: {e.msg} (line {e.lineno} col {e.colno})。响应预览: {preview}") from None
+
+
+# ==================== CLI ====================
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="本地 Swagger 文档提取与解析（与服务端 parseApiDocs 一比一对齐）",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument("--url", help="Swagger api-docs URL（脚本内部走 curl 下载）")
+    src.add_argument("--file", help="本地 Swagger JSON 文件路径")
+
+    parser.add_argument("--cookie", help="--url 模式可选，鉴权后的 Cookie 值（如 'JSESSIONID=xxx'）")
+    parser.add_argument("--auth", help="--url 模式可选，Basic 鉴权 base64(user:pass)")
+    parser.add_argument("--timeout", type=int, default=30, help="--url 模式 curl 超时秒数，默认 30")
+
+    parser.add_argument(
+        "--filter", action="append", default=[],
+        help="按关键词过滤 api（可多次指定，对 url/summary/operationId/tag/description/dtoRef/voName 模糊匹配）",
+    )
+    parser.add_argument(
+        "--definition",
+        help="仅查询单个 VO/DTO 的完整字段定义（等价于服务端 get_definition action）",
+    )
+    parser.add_argument("--out", help="输出到文件（默认 stdout）")
+    parser.add_argument(
+        "--indent", type=int, default=2,
+        help="JSON 输出缩进，默认 2；设为 0 输出紧凑 JSON",
+    )
+
+    args = parser.parse_args()
+
+    # 1. 读取原始 Swagger JSON
+    try:
+        if args.url:
+            raw_text = fetch_via_curl(args.url, cookie=args.cookie, auth=args.auth, timeout=args.timeout)
+        else:
+            raw_text = Path(args.file).read_text(encoding="utf-8")
+    except Exception as e:
+        print(f"[ERROR] 读取 Swagger 失败: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    # 2. 解析 JSON
+    try:
+        api_docs = load_json_text(raw_text)
+    except Exception as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        sys.exit(3)
+
+    # 3. 路径分支：--definition 单查 / 默认完整解析
+    try:
+        if args.definition:
+            result = get_definition(api_docs, args.definition)
+        else:
+            result = parse_api_docs(api_docs)
+            if args.filter:
+                total = len(result["apis"])
+                result["apis"] = filter_apis(result["apis"], args.filter)
+                result = trim_definitions_detail(result, args.filter)
+                result["_filter"]["total"] = total
+    except Exception as e:
+        print(f"[ERROR] 解析失败: {e}", file=sys.stderr)
+        sys.exit(3)
+
+    # 4. 输出
+    indent = args.indent if args.indent > 0 else None
+    out_text = json.dumps(result, ensure_ascii=False, indent=indent)
+    if args.out:
+        Path(args.out).write_text(out_text, encoding="utf-8")
+        print(f"[OK] 已输出到 {args.out} ({len(out_text)} bytes)", file=sys.stderr)
+    else:
+        sys.stdout.write(out_text)
+        sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    main()

package/opencode-extension/skills/szcd-component-helper/SKILL.md

@@ -81,14 +81,14 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 ### 步骤3.5：Sketch 文件解析（如有 .sketch 设计稿）
 - **当用户提供 .sketch 文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`
 - 工作流（4步直传）：
-  1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `listNodesByPage(type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
+  1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `queryNodes(pageId, type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
   2. **获取组件库架构**（复用步骤1结果）：`get_architecture_overview` 的 `templatePatterns` 提供模板组合模式，`llmMappingHints` 提供常见错误修正
   3. **LLM 推理组件范围**：从 Sketch 结构化数据推断画板名称→`pageName`、区域分布→`layoutType`、图层类型→组件映射，对照 `templatePatterns` 选择最匹配的模板，输出组件候选列表
   4. **批量获取组件详情**：调用 `get_component_full_profile(name="Query,TableOrList,LeftTree,TemplateMode", depth="deep")` 一次性获取所有需要的组件 API
 
 **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
 ```
-.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+.sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
 → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
 → get_component_full_profile(批量) → 编码
 ```
@@ -107,7 +107,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 
 **提示**：
 - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
-- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
+- `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
 - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
 - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
 
@@ -124,7 +124,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 - 若用户表示不准确或不采纳，收集原因
 - 调用 `submit_feedback` 将反馈提交到服务器
 
-## 可用工具（13 + 17 Sketch）
+## 可用工具（13 + 15 Sketch）
 
 ### Sketch 文件解析工具（sketch-mcp-server，独立 MCP Server）
 
@@ -152,26 +152,28 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
 - `nodeId` (string, required): 节点 ID（artboard 级别效果最佳）
 - `format` (enum, optional, default: "svg"): 输出格式，当前仅支持 svg
 
-#### S5. getNodesSummary
+#### S5. getPageStructure (mode="summary")
 **功能**：获取节点统计摘要，Token 消耗比完整信息减少 80-90%。
 **参数**：
-- `pageId` (string, optional): 页面 ID
+- `pageId` (string, required): 页面 ID
+- `mode` (string, required): "summary"
 - `groupBy` (enum, optional): type/style/position/size
-- `includeStats` (boolean, optional, default: true)
+- `maxSamples` (number, optional, default: 5)
 
-#### S6. findNodesByName
+#### S6. queryNodes (name 参数)
 **功能**：按名称搜索节点，支持模糊匹配。
 **参数**：
 - `name` (string, required): 搜索关键词
-- `limit` (number, optional, default: 10): 最大返回数量
+- `limit` (number, optional, default: 50): 最大返回数量
 
-#### S7-S17. 其他 Sketch 工具
-- `listNodes` / `listNodesByPage` — 列出节点（含过滤）
+#### S7-S15. 其他 Sketch 工具
+- `queryNodes` — 统一节点查询（支持 pageId/type/name/nameContains/limit/offset）
 - `getNodeInfo` / `getMultipleNodeInfo` — 获取节点详情
-- `getNodePosition` — 获取节点位置
 - `getDocumentStructure` — 获取文档结构（支持字段过滤和摘要模式）
-- `getSymbolMasters` / `getSymbolInstances` — Symbol 组件管理
+- `getSymbols` — Symbol 组件查询（type="master" 或 "instance"）
 - `getSymbolMasterBySymbolID` / `getSymbolInstanceStyles` — Symbol 详情
+- `getShapePathData` — 提取 shapePath SVG 路径数据
+- `extractBitmaps` / `matchIconFromName` — 资源提取与图标匹配
 
 ### 复合组件工具
 
@@ -209,16 +211,19 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
 ### 设计稿分析工具
 
 #### 5. analyze_design_image
-**功能**：分析 UI 设计稿图片，提取 Token 配置、CSS 覆盖样式、视觉细节。支持 base64/URL/文件路径，pixel_perfect 模式最高还原度。
+**功能**：分析 UI 设计稿图片，提取 Token 配置、CSS 覆盖样式、视觉细节。支持 upload_id/base64/URL/文件路径，pixel_perfect 模式最高还原度。
 **参数**：
-- `imageSource` (string, required): 图片数据（base64/URL/文件路径）
-- `sourceType` (enum, optional, default: "file_path"): base64/url/file_path
+- `imageSource` (string, required): 图片数据（upload_id/base64/URL/文件路径）
+- `sourceType` (enum, optional, default: "upload_id"): upload_id/base64/url/file_path
 - `analysisType` (enum, optional, default: "full"): layout/components/tokens/full/pixel_perfect
 - `pageContext` (string, optional): 页面业务上下文
 - `targetLibrary` (enum, optional, default: "auto"): szcd/antd/pro-components/auto
 - `outputFormat` (enum, optional, default: "markdown"): markdown/json/structured_text/restoration_code
 
-**重要提示**：远程 SSE/HTTP 连接时优先使用 base64；本地 stdio 可用 file_path。
+**重要提示**：
+- 远程 SSE/HTTP 连接时优先使用 upload_id：先调用 `get_upload_endpoint` 获取上传地址，用 curl 上传图片获取 upload_id，再传给本工具
+- **上传重试限制**：curl 上传最多重试 3 次（含首次），超过后停止重试并向用户说明失败原因，不要无限重试浪费 token
+- 本地 stdio 直连可用 file_path
 
 ### 样式注入指南工具