PositionCore 指南针

看得见，点得中

基于 Windows + .NET 10 的远程 GUI 操作组件，分体式架构：本体负责调度，节点负责执行。

此项目完全由 AI 生成和维护

职责边界：只负责截屏 + 键鼠操作，不负责图片理解。调用方拿到截图后自行处理图像理解。

---

📋 项目概述

特性	说明
类型	GUI 操作引擎模块
定位	GUI 操作引擎（截屏 + 键鼠控制）
架构	本体（Controller） + 节点（Node）
通信	WebSocket（节点主动注册）
平台	Windows 10/11 + .NET 10
依赖	Win32 API (user32.dll, gdi32.dll)
不负责	图片理解（交给调用方 Agent）

---

🏗️ 架构设计

PositionCore 采用分体式架构：本体（Controller）负责调度，节点（Node）负责执行。

核心组件：

• 本体：CLI + HTTP API + WebSocket Server，管理节点和调度操作
• 节点：Win32 API 引擎，执行截屏、键鼠操作

详细架构设计、项目结构、模型定义请参见：ARCHITECTURE.md

---

📡 通信协议

节点通过 WebSocket 连接本体，支持注册、心跳、操作指令和响应。

交互方式：

• 终端模式（CLI）：适合 LLM 调用
• API 模式（HTTP）：适合 Agent 产品集成

详细协议规范、消息格式、HTTP API 请参见：ARCHITECTURE-PROTOCOL.md

---

🖥️ 两种交互方式

1. 终端模式（CLI）

# 节点管理
position nodes                                    # 列出节点
position health                                   # 健康检查

# 窗口操作
position windows --node remote-node              # 窗口列表
position activate --hwnd 12345 --node remote-node # 激活窗口

# 鼠标操作
position click 100 200 --node remote-node         # 单击
position doubleclick 100 200 --node remote-node   # 双击
position rightclick 100 200 --node remote-node    # 右键
position drag 100 200 300 400 --node remote-node  # 拖拽
position scroll 100 200 -3 --node remote-node     # 滚轮（负=向下）

# 键盘操作
position type "hello world" --node local           # 输入文本
position key Enter --node remote-node             # 按键
position key Ctrl+C --node remote-node            # 快捷键

# 截屏
position screenshot --node remote-node                         # 全屏
position screenshot --node remote-node --region 0,0,800,600   # 区域
position screenshot --node remote-node --hwnd 12345           # 窗口

2. API 模式（HTTP）

# 节点管理
GET  /v1/position/nodes
GET  /v1/position/health

# 窗口操作
GET  /v1/position/windows        ?node=remote-node
POST /v1/position/activate       { hwnd, node }

# 鼠标操作
POST /v1/position/click          { x, y, node }
POST /v1/position/doubleclick    { x, y, node }
POST /v1/position/rightclick     { x, y, node }
POST /v1/position/drag           { x1, y1, x2, y2, node }
POST /v1/position/scroll         { x, y, delta, node }

# 键盘操作
POST /v1/position/type           { text, node }
POST /v1/position/key            { key, node }

# 截屏
POST /v1/position/screenshot     { node, region?, hwnd? }

---

📁 项目结构

PositionCore/
├── README.md                      # 本文档
├── LICENSE                        # MIT 许可证
├── CONTRIBUTING.md                # 贡献指南
├── ARCHITECTURE.md                # 架构设计
├── ARCHITECTURE-PROTOCOL.md       # 协议规范
├── warning.md                     # 风险与约束
├── plan.md                        # 开发计划
├── PositionCore.slnx              # 解决方案
├── doc/
│   ├── 开发规范.md
│   └── error-codes.md             # 错误码规范
├── src/
│   ├── PositionCore.Models/       # 共享模型（本体 + 节点都引用）
│   ├── PositionCore.Controller/   # 本体
│   └── PositionCore.Node/         # 节点
└── tests/
    └── PositionCore.Tests/

---

🚀 快速开始

启动节点

# 本机节点
dotnet run --project src/PositionCore.Node -- ws://localhost:50051/ws local

# 远程节点（指定本体地址）
dotnet run --project src/PositionCore.Node -- ws://<controller-ip>:50051/ws <node-id>

启动本体

# 默认端口 5000
dotnet run --project src/PositionCore.Controller

---

🔗 独立使用

PositionCore 可作为独立组件使用，也可作为更大系统的可扩展模块。

---

🧪 测试计划

测试项	说明
节点注册	启动节点 → 本体接收注册 → 状态为 online
心跳保活	节点每 15 秒发送心跳 → 本体更新时间戳
断线重连	节点断线 → 指数退避重连 → 恢复状态
窗口管理	EnumWindows 获取窗口列表、激活指定窗口
鼠标操作	单击、双击、右键、拖拽、滚轮精确性验证
键盘操作	文本输入、单键、快捷键组合验证
截屏传输	全屏/区域/窗口三种模式，WebP + Binary WebSocket 传输
Base64 输出	截图返回 Base64 格式，供 Agent 消费

---

📄 相关文档

• 架构设计
• 协议规范
• 贡献指南
• 错误码规范

📜 许可证

本项目采用 MIT 许可证 开源。