chore: init qmt_bridge repo (HTTP+WS bridge, MCP endpoint, docs, references)

2026-08-26 16:53:15 +08:00
commit 22a5b8ca04
210 changed files with 68176 additions and 0 deletions
@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""Apifox 接口规范导入辅助工具。
+
+背景: 之前尝试通过 Apifox 开放 API (POST /v1/projects/{id}/import-openapi)
+自动推送, 但沙箱网络代理会伪造 201 空响应 (Python urllib), PowerShell 直连
+又返回 422 (body 格式未确认)。经实测, **手动导入本地 YAML 到 Apifox 可以
+正确显示中文接口**。因此本工具改为: 生成一个可直接粘贴/导入的规范文件,
+并打印手动导入步骤。
+
+用法:
+    python tools/push_apifox.py
+    输出: docs/api_spec/openapi.json (生成最新 JSON 版规范)
+
+Apifox 手动导入步骤:
+    1. 打开 Apifox -> 进入项目 QMT_HTTP_BRIDGE
+    2. 点「导入数据」(或 项目设置 -> 导入)
+    3. 数据格式选 OpenAPI/Swagger
+    4. 方式选「文件导入」, 选择 docs/api_spec/openapi.yaml
+       (或「粘贴内容」, 粘贴 openapi.yaml 全文)
+    5. 点确定, 接口即以中文定义导入
+"""
+import json
+import os
+import sys
+
+BASE = os.path.dirname(os.path.abspath(__file__))
+YAML_PATH = os.path.join(BASE, "..", "docs", "api_spec", "openapi.yaml")
+JSON_PATH = os.path.join(BASE, "..", "docs", "api_spec", "openapi.json")
+
+def main():
+    if not os.path.exists(YAML_PATH):
+        print("ERROR: spec not found: %s" % YAML_PATH)
+        sys.exit(1)
+
+    # Parse YAML -> JSON (PyYAML optional; if missing, keep previous JSON)
+    try:
+        import yaml
+        with open(YAML_PATH, encoding="utf-8") as f:
+            doc = yaml.safe_load(f)
+        with open(JSON_PATH, "w", encoding="utf-8") as f:
+            json.dump(doc, f, ensure_ascii=False, indent=2)
+        print("JSON generated: %s" % JSON_PATH)
+        print("  title: %s" % doc.get("info", {}).get("title"))
+        print("  paths: %d" % len(doc.get("paths", {})))
+    except ImportError:
+        print("PyYAML not installed; cannot regenerate JSON. "
+              "Use openapi.yaml directly for import.")
+    except Exception as e:
+        print("YAML parse failed: %s" % e)
+        sys.exit(1)
+
+    print()
+    print("=" * 60)
+    print("Apifox 手动导入步骤 (已验证可用):")
+    print("  1. Apifox 打开项目 QMT_HTTP_BRIDGE (ID 8742354)")
+    print("  2. 导入数据 -> 格式 OpenAPI/Swagger")
+    print("  3. 文件导入: %s" % YAML_PATH)
+    print("     (或粘贴 openapi.yaml 全文)")
+    print("  4. 确定后, 接口以中文定义显示")
+    print("=" * 60)
+    print()
+    print("注: 开放 API 自动推送 (import-openapi) 尚未打通, 详见 docs/项目规范.md")
+
+if __name__ == "__main__":
+    main()