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

package/standard-skill/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/standard-skill/szcd-component-helper/SKILL.md

@@ -211,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
 
 ### 样式注入指南工具