HS Knowledge Vault

windows_bridge

6分钟阅读

Windows Bridge（Spark MCP 桥）知识文档

2026-08-17 搭建；2026-08-24 大改：固定域名 + 开机自启 + venv 3.11 根因。 用途：Google Gemini Spark（云端 Ultra 订阅——8/24 起主力大脑）通过 MCP 控制本地 Windows 电脑。 相关：env/spark_handover.md（交接文档 v3——Spark 主上下文）

架构

Gemini Spark (Google 云端)
   │ MCP (streamable-http, POST /mcp)
   ▼
cloudflared 命名隧道 sparkbridge（公网 HTTPS）
   ▼  DNS: spark.hsdesign.biz CNAME → 隧道（proxied）+ 精确 route（覆盖通配劫持）
spark_bridge.py (本地 127.0.0.1:8000, FastMCP 1.x)
   ▼
PowerShell / 文件系统 / psutil (Windows 本地)
  • MCP 端点（永久不变）：https://spark.hsdesign.biz/mcp（8/24 命名隧道定案——不再用 trycloudflare 随机 URL）

关键文件（2026-08-24 更新）

文件用途
D:\hermes\hsdesign_work\spark_bridge.py主服务（9 工具增强版）
D:\hermes\hsdesign_work\start_spark_bridge.py启动器（venv Python 3.11 拉桥 + 命名隧道 + URL 写 Drive）
D:\hermes\hsdesign_work\cloudflared_spark.ymlcloudflared 隧道 config（ingress → 127.0.0.1:8000）
D:\hermes\secrets\spark_tunnel_token.txt命名隧道 sparkbridge token（CF API tokens）
H:\My Drive\hermes-to-spark\bridge_url.txt桥状态自动通道（固定域名记录——Spark 读这里拿端点）
H:\My Drive\hermes-to-spark\bridge_status.json在线心跳（备用）
D:\hermes\hsdesign_work\verify_spark_bridge.py本地验证脚本
.jobs/（同目录）后台任务元数据/日志

启动 / 重启（2026-08-24 定版）

  • 自启：计划任务 SparkBridge（AtLogOn——重启后自动拉桥+隧道，3 分钟内就绪，无需人工）
  • 手动：python D:\hermes\hsdesign_work\start_spark_bridge.py
  • ⚠️ 必须用 venv Python 3.11（不是系统 Python 3.13——见坑 13）

验证（连接是否活）

# 端点可达性（406 = 桥已响应只差 Accept 头——真客户端带上即通）
curl -s -m 15 -X POST "https://spark.hsdesign.biz/mcp" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}'
# 200 + serverInfo:LocalWindowsBridge = 通；本地: curl -s http://127.0.0.1:8000/mcp（同理）

工具清单（9 个）

  1. execute_command(command, timeout_seconds=30, working_dir) — 同步 PowerShell 执行（UTF-8 前置）
  2. start_background_job(command, job_name, working_dir) — 异步后台任务（detached，日志落 .jobs/）
  3. get_job_status(job_id, tail_lines=50) — 后台任务状态 + 日志尾
  4. list_jobs(limit=10) — 历史任务清单
  5. stop_job(job_id) — 终止任务进程树（psutil 递归杀）
  6. list_directory(path=".", max_depth=2) — 安全目录列出（防超大目录）
  7. read_file(path, offset_line, limit_lines) — 分页读文件（防撑爆上下文）
  8. write_file(path, content, append) — 原子写（临时文件 + replace）
  9. get_system_info() — CPU/内存/磁盘/主机名/时间戳

踩坑记录（8/17 实测 + 8/24 新增）

  1. PYTHONPATH 污染：Hermes 运行时设 PYTHONPATH 指向 hermes venv——任何 Python 都被污染 → 启动前清空 PYTHONPATH=（start_spark_bridge.py 已处理）
  2. hermes venv 损坏：pydantic_core._pydantic_core / rpds.rpds 缺二进制 → 不用 hermes venv 装 MCP 包
  3. mcp 2.0 移除 FastMCP（mcp.server.fastmcp 不存在）→ 降级 pip install "mcp<2"（1.x 有 FastMCP）
  4. FastMCP.run() 不收 host/port 参数（1.x 签名只有 transport/mount_path）→ 默认 127.0.0.1:8000
  5. SSE 经隧道不稳定（长连接握手超时×2）→ 用 streamable-http（POST 短请求——实测稳定）
  6. FastMCP 内置 DNS rebinding 保护（host=127.0.0.1 自动启用——公网 Host → 421 Misdirected）→ TransportSecuritySettings(enable_dns_rebinding_protection=False, allowed_hosts=["*"], allowed_origins=["*"])
  7. streamable-http 406：缺 Accept: application/json, text/event-stream 头
  8. 裸 POST 工具调用 400 Missing session ID：streamable 需先 initialize 拿 session——真客户端自动处理
  9. 原增强代码 bug：pathlib.Path(file) 和 if name == "main"（缺下划线）→ 已修为 __file__ / __main__
  10. UnicodeDecodeError：PowerShell 输出非 UTF-8 字节（GBK）→ subprocess 加 encoding="utf-8", errors="replace"
  11. venv 创建失败（系统 Python313/311 -m venv 静默无目录）→ 依赖装进既有 venv（3.11）
  12. wsl python 找不到包：WSL 侧无 mcp 包——服务必须在 Windows 侧跑
  13. 🆕 8/24 电脑重启后桥挂根因：旧进程用系统 Python 3.13 启动 → venv 包是 cp311 .pyd（pydantic_core）加载失败 → 启动即退。必须用 venv Python 3.11 启动（.pyd 在 venv 内）——计划任务 SparkBridge 已固定正确解释器；手动恢复也先确认解释器
  14. 🆕 8/24 固定域名三大坑：① *.hsdesign.biz/* 通配 Workers Route 劫持 DNS（同 8/23 webwatch）→ 添加精确 route（script=""）覆盖；② 503 = 隧道缺 ingress 配置 → 写 cloudflared_spark.yml（ingress service: http://127.0.0.1:8000）用 --config + token 启动（勿用 tunnel run <name> 裸起——或确保 credentials 文件就位）；③ MSYS 路径坑：Windows 程序不认 /d/ 路径——cloudflared/配置一律用 Windows 原生路径（D:\...）

安全提醒

  • execute_command / start_background_job 公网可用 = 任何拿到 URL 的人可执行命令 → 固定域名公开但凭据已收进 secrets/spark_tunnel_token.txt；隧道凭据泄露即吊销重建（CF 控制台）
  • PowerShell 纪律：非交互式 + 超时 + 破坏性命令先确认（已写入 spark_handover.md §六/十二）

Gemini Spark 侧

  • 端点：https://spark.hsdesign.biz/mcp（streamable-http——不是 /sse）——永不变，绑定一次即终身
  • 绑定：Gemini → 设置与帮助 → 已关联的应用 → Add custom app → 粘贴端点
  • 每次重启后：bridge_url.txt 自动更新（同内容）——Spark 拿端点优先读文件（hermes-to-spark/bridge_url.txt + /mcp）
  • 发任务前先读 hermes-to-spark/watcher_heartbeat.json（>/5 分钟更新 = 本地在线；>10min 死 = 本地离线别死等）
  • 已实测：Google IP 连接成功 + 工具调用 200（2026-08-17 + 8/24 命名隧道 406 握手验证）

关系图谱

反向链接