# 1. 启动 MCP 服务器（HTTP 模式，端口 59322）
python winctl_mcp_server.py --port 59322

# 2. 注册到 Hermes Agent
hermes mcp add winctl --url http://127.0.0.1:59322

# 3. 验证连通性
curl http://127.0.0.1:59322/health
# → {"status":"ok","version":"0.1.0","has_windeep":true,"has_pil":true}

# 4. 单次 CLI 调用
python winctl_mcp_server.py list_windows
python winctl_mcp_server.py screenshot

windeep/                          ← 项目根目录
│
├── winctl_mcp_server.py          ← MCP 服务器 (22 工具, HTTP :59322)
│                                       ThreadedHTTPServer, GDI try/finally
│
├── computer_control_enhanced.py  ← CLI 入口 + P0 特性集成
│                                       UiTreeCache / 元素指纹 / 自适应 settle
│
├── compress_image.py             ← 渐进式截图压缩
│                                       quality 二分搜索 + PNG→JPEG→WebP 降级
│                                       compress_pipeline (47x 加速)
│
└── scripts/                      ← 模块化组件
    ├── ui_tree_cache.py          ← UI 树缓存 (TTL + threading.Lock)
    ├── element_fingerprint.py    ← SHA256 元素指纹
    ├── ocr_finder.py             ← Windows 原生 OCR (WinRT, PowerShell)
    ├── smart_matcher.py          ← 五级智能元素匹配
    ├── assertion_verifier.py     ← 四种断言验证
    ├── shared_ui_state.py        ← 跨 Agent 共享状态
    └── action_queue.py           ← 延迟适配队列

┌──────────────────────────────────────────────────────┐
│  战略层 (Hermes, ~10s 决策粒度)                        │
│  "打开 Chrome → 登录 Gemini → 提交 prompt"            │
│  输出: 操作序列 + 断言预期                              │
├──────────────────────────────────────────────────────┤
│  战术层 (winctl, ~500ms 调度粒度)                      │
│  指纹匹配 / settle 参数 / OCR fallback / 断言验证      │
│  输出: (action, fingerprint) 元组                      │
├──────────────────────────────────────────────────────┤
│  反射层 (Win32 API, ~50ms 执行粒度)                    │
│  PostMessage / WM_CHAR / PrintWindow / UIA Invoke    │
│  输出: {success, snapshot, confidence}                 │
└──────────────────────────────────────────────────────┘
         ↕ 共享状态: shared_ui_state.json (指纹+settle+断言)

click "提交"
  │
  ├─ 1. UIA 精确匹配    (element_index, 置信度 98%)
  │    角色+标签精确匹配，UIA Tree 原生支持
  │
  ├─ 2. UIA 模糊匹配    (Levenshtein, 置信度 70-95%)
  │    大小写不敏感、近似文本匹配
  │
  ├─ 3. OCR 文字匹配    (Windows WinRT OCR, 置信度 80-95%)  ← 覆盖 UIA 盲区
  │    Electron / WebView / 自定义 Canvas 中的文字
  │    零外部依赖，Windows 10+ 原生
  │
  ├─ 4. 位置邻近匹配    (置信度 30-70%)
  │    距上次点击位置最近的可交互元素
  │
  └─ 5. 坐标直发        (裸 x,y，置信度 ~10%)
        最终 fallback

from scripts.assertion_verifier import capture_state, verify

before = capture_state(pid=1234)
click(pid=1234, element=7)
after = capture_state(pid=1234)

report = verify(before, after, [
    ("hash_change", {}),                       # UI 树必须变化
    ("element_appeared", {"text": "保存成功"}),  # 预期元素出现
])

{
  "fingerprints": {
    "a3f8c2": {"name": "Send", "index": 5, "role": "Button"}
  },
  "settle_history": {
    "Chrome:click": [780, 810, 750],
    "_adaptive_Chrome:click": 790
  },
  "last_action": {
    "action": "click", "success": true
  }
}

# Hermes (规划层)：入队操作
queue.enqueue("click", {"pid": 1234, "element_index": 7})

# winctl (执行层)：消费队列
while action := queue.next_pending():
    result = execute(action["tool"], action["params"])
    queue.mark_done(action["id"], result)

# 启动服务（前台运行）
python winctl_mcp_server.py --port 59322

# 注册到 Hermes
hermes mcp add winctl --url http://127.0.0.1:59322

# 调用工具
hermes mcp call winctl list_windows
hermes mcp call winctl screenshot
hermes mcp call winctl smart_click '{"pid": 1234, "target_text": "提交"}'

# 窗口管理
python winctl_mcp_server.py list_windows
python winctl_mcp_server.py find_windows --title-pattern "Chrome"
python winctl_mcp_server.py get_window_info --hwnd 0x1234

# 窗口控制
python winctl_mcp_server.py focus_window --hwnd 0x1234
python winctl_mcp_server.py close_window --hwnd 0x1234
python winctl_mcp_server.py minimize_window --hwnd 0x1234

# 输入操作
python winctl_mcp_server.py click --hwnd 0x1234 --x 500 --y 300
python winctl_mcp_server.py type_text --hwnd 0x1234 "hello world"
python winctl_mcp_server.py send_keys --hwnd 0x1234 "ctrl+c"

# 截图
python winctl_mcp_server.py screenshot  # 全屏
python winctl_mcp_server.py screenshot --hwnd 0x1234  # 指定窗口

# 智能匹配
python winctl_mcp_server.py smart_click --pid 1234 --target-text "登录"

# 验证
python winctl_mcp_server.py desktop_info
python winctl_mcp_server.py ocr_available

# 使用增强控制库
from computer_control_enhanced import (
    capture, click, type_text, paste_text,
    type_keys, scroll, drag, list_apps
)

# 截图（自动压缩至 512KB）
result = capture(pid=1234, compress_kb=512)
print(f"截图: {result['output_kb']:.0f}KB")

# 点击（含 settle delay + 自动验证 + 指纹容错）
result = click(pid=1234, element=7, settle_ms=750)
print(f"点击: {result['result']}")

# 智能输入（自动选择最优方式）
type_text(pid=1234, text="hello")           # 短文本 → 逐字符
type_text(pid=1234, text="这是一段较长的中文文本描述...", element=5)  # 长文本 → set_value
paste_text(pid=1234, text="# 大段代码\nprint('hello')\n")  # 代码 → 剪贴板粘贴

# 快捷键
type_keys(pid=1234, keys=["ctrl", "c"])     # Ctrl+C 复制
type_keys(pid=1234, keys=["ctrl", "v"])     # Ctrl+V 粘贴

# 断言验证
from scripts.assertion_verifier import capture_state, verify
before = capture_state(pid=1234)
click(pid=1234, element=7)
after = capture_state(pid=1234)
report = verify(before, after, [
    ("hash_change", {}),
    ("element_appeared", {"text": "保存成功"}),
])
print(f"验证通过: {report['passed']}, 置信度: {report['confidence']}")

from scripts.smart_matcher import smart_find, smart_click

# 按文字查找元素
match = smart_find("提交", tree=ui_tree, screenshot_b64=screenshot)
print(f"找到: {match['method']}, 坐标: ({match['x']}, {match['y']})")

# 找到即点击（一步完成）
result = smart_click(pid=1234, target_text="登录")
print(f"方法: {result['method']}, 成功: {result['success']}")

from scripts.shared_ui_state import get_state
from scripts.action_queue import ActionQueue

# Hermes 端：写入共享状态
state = get_state()
state.update_fingerprints(elements)
state.set_last_action({"action": "click", "success": True})

# Codex++ 端：读取共享状态
state.reload()
fps = state.get_fingerprints()
settle_ms = state.get_adaptive_settle("Chrome:click")

# Action Queue：延迟适配
queue = ActionQueue()
queue.enqueue("click", {"pid": 1234, "element_index": 7})
# winctl 执行端：
while action := queue.next_pending():
    result = execute(action["tool"], action["params"])
    queue.mark_done(action["id"], result)