{
  "module": "easytier",
  "version": "1.0",
  "purpose": "EasyTier VPN 网络开关。控制 Windows(192.168.1.16) 和 Linux 246(192.168.1.246) 上的 EasyTier VPN 进程，让两台机器组成 P2P 内网。",
  "ui_location": "I Tab (Infrastructure) → EasyTier VPN section",

  "human_help": {
    "title": "EasyTier VPN",
    "description": [
      "EasyTier 是一个 P2P VPN 组网工具，用于连接 Windows(192.168.1.16) 和 Linux 246(192.168.1.246) 两台机器。",
      "开启后两台机器通过虚拟网卡通信：Windows 获得 10.144.144.3，246 获得 10.144.144.1。",
      "RDP 远程桌面隧道依赖 EasyTier VPN 先连通，请先确保这里显示 Connected 再操作 RDP。"
    ],
    "usage": [
      "1. 点击 Turn On 启动 EasyTier VPN（两台机器都启动）",
      "2. 点击 Turn Off 关闭 EasyTier VPN",
      "3. 状态显示 Connected 表示两台机器都已加入 VPN 网络"
    ],
    "troubleshooting": [
      "如果 Turn On 返回失败：检查 Windows xmpp_bot (python.exe, port 5807) 是否运行",
      "如果状态显示 Off 但实际已启动：等待 1-2 秒再刷新，或检查 246 上 easytier-core 进程"
    ],
    "related": "RDP Remote Desktop 依赖本 VPN 通道，参见 RDP section 的帮助"
  },

  "ai_spec": {
    "apis": [
      {"method": "GET", "path": "/api/easytier", "returns": "status{windows,246} + virtual_ips{windows,246}", "proxied_to": "xmpp_bot /easytier action=status"},
      {"method": "POST", "path": "/api/easytier/toggle", "body": "{action: start|stop}", "returns": "{ok, message}", "proxied_to": "xmpp_bot /easytier action=start|stop"}
    ],
    "dependencies": [
      "xmpp_bot on Windows 192.168.1.16:5807 (HTTP bridge with /easytier endpoint)",
      "XMPP_BRIDGE_URL env var (default: http://192.168.1.16:5807) — set in systemd service",
      "_bridge_post() helper in dashboard.py — proxies POST to xmpp_bot with X-Api-Key header",
      "_BRIDGE_KEY = 'xxm_bridge_8f3a2c' — API key for xmpp_bot HTTP bridge"
    ],
    "architecture": {
      "flow": "Dashboard(246:5803) → _bridge_post() → xmpp_bot(Windows:5807) → starts/stops easytier-core process on respective machine",
      "mechanism": "xmpp_bot receives POST /easytier {action} → starts/stops easytier-core process"
    },
    "constraints": [
      "VPN IP: Windows=10.144.144.3, 246=10.144.144.1 (NOT .2 — .2 was wrong in old code, 已修正)",
      "xmpp_bot must be running on Windows with /easytier HTTP endpoint (API key: xxm_bridge_8f3a2c)",
      "dashboard.py runs on 246 (Linux), xmpp_bot runs on Windows — 通信走 LAN HTTP，不是 local subprocess"
    ],
    "must_not": [
      "不要把 proxy 调用改成 local subprocess（dashboard 在 Linux，EasyTier 在 Windows）",
      "不要把 VPN IP 从 .3 改成 .2 — .3 是正确的 Windows IP",
      "不要删除 _bridge_post() helper 或 _BRIDGE_KEY — 它们是 proxy 的核心",
      "不要在 fI() 里用 fill('infra',h) — 这会清空整个 ct-infra 区域导致 EasyTier/RDP 元素闪烁"
    ],
    "related_modules": [
      {"module": "rdp", "relation": "RDP 远程桌面隧道依赖 EasyTier VPN 连接，启动 RDP 前应确保 EasyTier Connected"}
    ],
    "tests": [
      {"id": "ET01", "name": "EasyTier toggle start returns ok", "endpoint": "POST /api/easytier/toggle {action:start}"},
      {"id": "ET02", "name": "EasyTier toggle stop returns ok", "endpoint": "POST /api/easytier/toggle {action:stop}"},
      {"id": "ET03", "name": "EasyTier status returns virtual_ips with windows=10.144.144.3", "endpoint": "GET /api/easytier"}
    ],
    "known_issues": [
      "如果 xmpp_bot (5807) 停了，EasyTier 操作会失败 — 检查 Windows pythonw.exe 进程",
      "EasyTier status 246 字段可能显示 unknown — 因为 246 的 EasyTier 状态不一定通过 xmpp_bot 返回"
    ],
    "related_files": [
      "gateway/scripts/dashboard.py — /api/easytier*, _bridge_post()",
      "gateway/scripts/templates/dashboard.html — fI() function creates EasyTier section (id=easytier-section)",
      "gateway/scripts/specs/easytier.json — 本 spec 文件",
      "gateway/scripts/specs/rdp.json — 关联模块 RDP 的 spec",
      "xmpp_agent_core.py — /easytier HTTP endpoint (line ~780)"
    ]
  }
}