nexforge-cli 0.2.12__tar.gz → 0.2.13__tar.gz

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.12
+Version: 0.2.13
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/01-/345/256/211/350/243/205/344/270/216/351/205/215/347/275/256.md

@@ -1,6 +1,6 @@
 # 安装与配置
 
-> NexForgeCLI v0.2.12
+> NexForgeCLI v0.2.13
 
 ## 环境要求
 

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/02-/347/225/214/351/235/242/344/270/216/345/277/253/346/215/267/351/224/256.md

@@ -64,7 +64,7 @@
 |------|------|
 | `/key <key>` | 设置 API Key |
 | `/provider [<name>]` | 无参数列出提供者;带参数切换 |
-| `/model flash|pro|auto` | 切换模型档位(仅 DeepSeek) |
+| `/model flash|pro|auto|vision` | 切换模型档位(仅 DeepSeek, vision=视觉模型) |
 | `/think on|off` | 开关思考模式(仅 DeepSeek) |
 | `/balance` | 查询账户余额(仅 DeepSeek) |
 | `/cost` | 显示累计费用 |

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/03-/346/250/241/345/236/213/351/205/215/347/275/256.md

@@ -20,8 +20,10 @@ DeepSeek 是内置的默认模型，首次运行只需提供 API Key 即可使
 | flash | 快速模型 | 常规编码、文件操作、日常问答 |
 | pro | 推理模型 | 复杂算法、架构设计、调试 |
 | auto | 自动路由 | 默认。小任务 flash，大任务自动升级 pro |
+| vision | 视觉模型 | 图片识别/理解(deepseek-v4-flash-vision-exp, 发图即用) |
 
 **默认 flash**：deepseek 涨价后默认固定 flash 省成本；需要深度推理时用 `/model pro`，或 `/model auto` 恢复自动路由。
+**视觉模型**：`/model vision` 或侧边栏切"视觉"档位后，粘贴图片直接分析（原生多模态，不走识图工具）；vision 档位自动关闭思考模式（exp 模型兼容性）。
 
 auto 模式下的升级触发条件：
 - 关键词(重构/架构/算法/证明/调试/为什么/设计)

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/04-/345/267/245/345/205/267/345/217/202/350/200/203.md

@@ -45,7 +45,7 @@ NexForgeCLI 内置 **35 个工具**供 AI 调用（`git_commit` 需在 config.to
 |------|------|
 | `web_fetch` | HTTP GET 抓取 URL(带 User-Agent, 5MB 限制) |
 | `search_web` | 网络搜索(默认 Bing, 可选 Google/DuckDuckGo/SearXNG) |
-| `image_vision` | 图片识别(阿里云千问 VL) |
+| `image_vision` | 图片识别(deepseek-vision + 千问 VL 双引擎, 支持 cross 交叉验证) |
 | `image_gen` | 图片生成(阿里云通义万相) |
 | `kb_search` | 知识库检索(全局+项目两级) |
 | `kb_write` | 知识沉淀(写入项目/全局知识库) |

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/05-/346/225/260/346/215/256/344/270/216/346/220/234/347/264/242.md

@@ -50,7 +50,9 @@ HTTP GET 抓取指定 URL，返回正文（截断至 20000 字符）。带浏览
 
 ### image_vision（图片识别）
 
-传入图片路径和问题，调用阿里云千问 VL 视觉模型分析图片内容。
+传入图片路径和问题，分析图片内容。**双引擎识别**：
+- `mode=auto`（默认）：优先用当前对话 provider 的视觉模型（如 deepseek-vision，共用对话 key），失败回退阿里云千问 qwen-vl
+- `mode=cross`：**双模型交叉验证**——deepseek-vision 与 qwen-vl 并行识别同一张图，返回双答案供交叉印证，减少单一模型的视觉误差（适合 GUI 验收/关键判断）
 
 ### image_gen（图片生成）
 

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/08-/350/207/252/345/256/232/344/271/211/351/205/215/347/275/256.md

@@ -25,7 +25,7 @@
 
 ```toml
 [models]
-default_tier = "flash"        # flash | pro | auto(默认 flash 省成本; auto 会按需升级 pro)
+default_tier = "flash"        # flash | pro | auto | vision(默认 flash 省成本; auto 会按需升级 pro; vision=视觉模型)
 thinking = true              # 思考模式
 reasoning_effort = "high"    # high | max
 max_output_tokens = 32768      # 输出上限(含思考 tokens), 长思考会吃配额, 不够可调大

{nexforge_cli-0.2.12 → nexforge_cli-0.2.13}/manual/README.md

@@ -1,4 +1,4 @@
-# NexForgeCLI 用户手册 · v0.2.12
+# NexForgeCLI 用户手册 · v0.2.13
 
 ## 这是什么
 

nexforge_cli-0.2.13/plugin_gui_auto/README.md

@@ -0,0 +1,86 @@
+# NF-GUI —— 给 AI 的跨平台 GUI 自动化插件
+
+让 NexForgeCLI 的 AI 获得操作计算机鼠标、键盘、屏幕的能力：能看界面、能精准定位元素、
+能点击/拖拽/输入，用于 GUI 应用的自动化测试、界面验收、交互验证。
+
+## 特性
+
+- **跨平台**：Windows / macOS / Linux（pyautogui 底层，统一逻辑像素坐标）
+- **三层定位**：模板匹配（快准）· 视觉模型（通用）· 像素特征（零依赖）
+- **复杂拖拽**：直线/曲线路径、分段控制点、按住停顿——滑块、调整大小、排序全支持
+- **中文输入**：自动走剪贴板，不受键盘布局影响
+- **操作留痕**：每次操作前自动存档 before 截图到 `.nexforge/gui_logs/`
+- **安全**：鼠标甩到左上角即中断（FAILSAFE）+ 写操作默认需审批
+
+## 安装
+
+```bash
+cd plugin_gui_auto
+python install_plugin.py            # 装依赖 + 安装到用户级 + 自检
+python install_plugin.py --project  # 或装到当前项目
+# 重启 nf 或执行 /plugins reload
+```
+
+可选依赖：`opencv-python`（模板匹配）、`pyperclip`（中文输入，通常已随 pyautogui 带）。
+
+## 工具清单
+
+| 工具 | 功能 | 审批 |
+|------|------|------|
+| `gui_screen` | 截取屏幕/窗口/区域 | 免 |
+| `gui_find` | 定位元素中心坐标（template/prompt/color 三选一） | 免 |
+| `gui_click` | 点击（左/右/中，单/双击，窗口内偏移） | 需 |
+| `gui_drag` | 拖拽（直线/曲线，分段控制，按住停顿） | 需 |
+| `gui_type` | 输入文本（中文走剪贴板） | 需 |
+| `gui_key` | 按键/组合键（enter/ctrl+c/alt+f4） | 需 |
+| `gui_scroll` | 滚动 | 需 |
+| `gui_windows` | 窗口管理（枚举/激活/几何/最小化/最大化/关闭） | 免 |
+
+## 典型工作流
+
+```
+AI 收到 GUI 测试任务后:
+
+1. gui_windows list            # 找目标窗口(或 gui_windows activate handle 激活)
+2. gui_screen                  # 截图看当前界面
+3. gui_find prompt="登录按钮的中心"   # 定位(视觉模型)
+   # 或 gui_find template="btn.png"  # 定位(模板匹配, 更快)
+4. gui_click x=960 y=540       # 点击
+5. gui_type text="admin"       # 输入
+6. gui_drag x1=100 y1=200 x2=300 y2=200 curve=true   # 拖滑块
+7. gui_screen                  # 再截图验证结果
+```
+
+## 坐标体系
+
+- 所有坐标是**屏幕逻辑像素**（与 DPI 无关，Windows 高 DPI 自动处理）
+- `gui_windows geometry` 可拿窗口矩形；`client` 动作转客户区坐标
+- 多显示器：pyautogui 只可靠操作主显示器（官方限制），次屏请先拖到主屏
+
+## 跨平台注意
+
+| 平台 | 说明 |
+|------|------|
+| Windows | 功能最全（窗口控制/DPI 感知/PrintWindow 截图） |
+| Linux | 需 X11；窗口枚举依赖 `xdotool`（`sudo apt install xdotool`）；Wayland 需 XWayland |
+| macOS | pyautogui 需辅助功能权限（系统设置→隐私→辅助功能）；窗口控制走 AppleScript |
+
+## 开发
+
+```
+guiauto/
+  __init__.py   register(api) 插件入口 + 技能提示
+  base.py       核心底座(平台/DPI/坐标/安全/截图)
+  vision.py     视觉定位(模板匹配/视觉模型/像素特征)
+  action.py     鼠标键盘操作(点击/拖拽/输入/按键/滚动)
+  window.py     窗口控制(枚举/激活/几何/最小化/关闭)
+  tools.py      8 个 BaseTool 工具层(暴露给 AI)
+```
+
+## 设计决策
+
+- **视觉模型定位为主力**：Qt/WPF/Web 等自绘控件 UIAutomation 支持有限，视觉定位通用；
+  模板匹配作为"常用元素"的加速通道；像素特征零依赖兜底
+- **操作与定位分离**：`gui_find` 只回答"在哪"，`gui_click/drag` 只负责"执行"，
+  AI 可组合出任意流程
+- **轻量**：核心依赖仅 pyautogui；模板匹配/视觉模型均为可选增强

nexforge_cli-0.2.13/plugin_gui_auto/guiauto/__init__.py

@@ -0,0 +1,80 @@
+"""NF-GUI 自动化插件 —— 让 AI 获得操作计算机鼠标/键盘/屏幕的能力。
+
+安装方式(二选一):
+  1) 用户级(所有项目可用):  把整个 guiauto/ 目录复制到
+       ~/.nexforge/plugins/guiauto/
+  2) 项目级(仅当前项目):    复制到
+       <项目根>/.nexforge/plugins/guiauto/
+
+复制后重启 nf(或 /plugins reload)即生效。验证: 运行 gui_screen 应成功截图。
+
+提供 8 个 AI 工具(均以 gui_ 前缀, 不与内置工具冲突):
+  gui_screen   截取屏幕/窗口/区域(GUI 自动化第一步)
+  gui_find     定位元素中心坐标(模板匹配/视觉模型/像素特征 三选一)
+  gui_click    点击(左/右/中, 单击/双击, 窗口内偏移)
+  gui_drag     拖拽(直线/曲线, 分段控制点, 按住停顿)
+  gui_type     输入文本(中文自动走剪贴板)
+  gui_key      按键/组合键(enter/ctrl+c/alt+f4)
+  gui_scroll   滚动
+  gui_windows  窗口管理(枚举/激活/几何/最小化/最大化/关闭)
+
+典型工作流: gui_screen 看界面 → gui_find 定位 → gui_click/gui_drag 操作
+            → gui_screen 验证结果。
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import base as B
+
+
+def register(api):
+    """插件宿主入口: 注册 GUI 自动化工具 + 技能提示。"""
+    from .tools import (
+        GuiClickTool,
+        GuiDragTool,
+        GuiFindTool,
+        GuiKeyTool,
+        GuiScreenTool,
+        GuiScrollTool,
+        GuiTypeTool,
+        GuiWindowsTool,
+    )
+
+    for tool in (
+        GuiScreenTool(),
+        GuiFindTool(),
+        GuiClickTool(),
+        GuiDragTool(),
+        GuiTypeTool(),
+        GuiKeyTool(),
+        GuiScrollTool(),
+        GuiWindowsTool(),
+    ):
+        try:
+            api.register_tool(tool)
+        except Exception:
+            pass  # 单个工具注册失败不阻塞其他
+
+    api.register_skill("gui-auto", _skill_hint)
+
+
+def _skill_hint(screen=None) -> str | None:
+    """技能提示: 每轮注入 system, 引导 AI 在 GUI 任务时使用工具链。"""
+    try:
+        err = B.ensure_ready()
+        if err:
+            return None  # pyautogui 未装, 不注入
+        return (
+            "你有 GUI 自动化工具(gui_*): 需要操作/测试图形界面时, 按此流程:\n"
+            "1. gui_windows list 找目标窗口(或用 handle 激活)\n"
+            "2. gui_screen 截图看当前界面\n"
+            "3. gui_find 定位元素中心坐标(template=图标模板 / prompt=中文描述 / color=颜色)\n"
+            "4. gui_click / gui_drag / gui_type / gui_key 执行操作\n"
+            "5. 再 gui_screen 截图验证结果\n"
+            "坐标均为屏幕逻辑像素; 拖拽滑块/调整大小用 gui_drag(curve=true 更真实); "
+            "中文输入用 gui_type; 操作前会自动存档 before 截图到 .nexforge/gui_logs/。"
+        )
+    except Exception:
+        return None

nexforge_cli-0.2.13/plugin_gui_auto/guiauto/action.py

@@ -0,0 +1,194 @@
+"""NF-GUI 操作执行 —— 「手」。
+
+基于 pyautogui 的鼠标/键盘操作, 统一坐标(逻辑像素):
+- click: 点击(左/右/双击/三击)
+- move: 移动(瞬时/平滑/指定步数曲线)
+- drag: 拖拽(直线/分段曲线, 支持中间停顿)
+- type: 输入文本(ASCII/Unicode, 中文自动走剪贴板)
+- key: 按/组合键
+- scroll: 滚动
+
+所有操作前可 `pre_action` 回调(如在 .nexforge/temp 存操作前后截图)。
+鼠标动作间有 PAUSE 间隔 + FAILSAFE 保护。
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from . import base as B
+
+# 操作日志(供 AI 回顾)
+_OP_LOG: list[dict] = []
+
+
+def op_log() -> list[dict]:
+    """返回本会话操作日志(最近 N 条)。"""
+    return _OP_LOG[-100:]
+
+
+def _log(kind: str, **info) -> None:
+    info["kind"] = kind
+    info["t"] = time.strftime("%H:%M:%S")
+    _OP_LOG.append(info)
+    if len(_OP_LOG) > 200:
+        _OP_LOG.pop(0)
+
+
+def _clamp(x: int, y: int) -> tuple[int, int]:
+    """坐标钳制到屏幕范围内(防误点出界)。"""
+    s = B.screen_size()
+    x = max(0, min(int(x), max(0, s["width"] - 1)))
+    y = max(0, min(int(y), max(0, s["height"] - 1)))
+    return x, y
+
+
+def _pg():
+    if not B.PY_AUTOGUI_OK:
+        raise RuntimeError(B._dependency_error())
+    return B._pg
+
+
+# ── 鼠标基础 ──────────────────────────────────────────────
+def click(x: int, y: int, button: str = "left", clicks: int = 1,
+          interval: float = 0.2, **kw) -> dict:
+    """点击。button=left/right/middle; clicks=次数(双击=2)。"""
+    x, y = _clamp(x, y)
+    pg = _pg()
+    pg.click(x, y, clicks=max(1, min(int(clicks), 3)),
+             button=button, interval=max(0.0, float(interval)))
+    _log("click", x=x, y=y, button=button, clicks=clicks)
+    return {"ok": True, "x": x, "y": y, "button": button, "clicks": clicks}
+
+
+def move(x: int, y: int, duration: float = 0.3, steps: int = 20, **kw) -> dict:
+    """移动鼠标。duration=总时长, steps=控制点数量(越大越平滑, 可模拟曲线)。"""
+    x, y = _clamp(x, y)
+    pg = _pg()
+    pg.moveTo(x, y, duration=max(0.05, float(duration)), tween=_tween(steps))
+    _log("move", x=x, y=y, duration=duration)
+    return {"ok": True, "x": x, "y": y}
+
+
+def _tween(steps: int):
+    """生成平滑 tween(步数控制曲线平滑度)。"""
+    import pytweening
+    steps = max(1, min(int(steps), 100))
+    # 用 easeOutQuad 抛物线平滑(近似人类拖动, 避免瞬移)
+    return pytweening.easeOutQuad
+
+
+def drag(x1: int, y1: int, x2: int, y2: int, duration: float = 0.8,
+         steps: int = 30, hold_ms: int = 200, button: str = "left",
+         curve: bool = False, **kw) -> dict:
+    """拖拽: 按住从 (x1,y1) 移动到 (x2,y2) 释放。
+
+    - steps: 中间控制点数量(越多越平滑, 支持精确路径)
+    - hold_ms: 按住后停顿(某些控件需要先稳定再拖)
+    - curve: 用曲线路径(模拟真实拖拽, 遍历中间插值点)
+    """
+    x1, y1 = _clamp(x1, y1)
+    x2, y2 = _clamp(x2, y2)
+    pg = _pg()
+    pg.moveTo(x1, y1)
+    pg.mouseDown(button=button)
+    if hold_ms > 0:
+        time.sleep(hold_ms / 1000.0)
+    steps = max(2, min(int(steps), 200))
+    if curve:
+        # 曲线路径: 用 tween 在 start/end 间插值
+        import pytweening
+        dur = max(0.2, float(duration))
+        start = time.monotonic()
+        while True:
+            t = (time.monotonic() - start) / dur
+            if t >= 1:
+                break
+            e = pytweening.easeInOutQuad(min(1.0, t))
+            cx = int(x1 + (x2 - x1) * e)
+            cy = int(y1 + (y2 - y1) * e)
+            pg.moveTo(cx, cy)
+            time.sleep(0.01)
+    else:
+        pg.moveTo(x2, y2, duration=max(0.1, float(duration)))
+    time.sleep(0.05)
+    pg.mouseUp(button=button)
+    _log("drag", x1=x1, y1=y1, x2=x2, y2=y2, steps=steps, button=button, curve=curve)
+    return {"ok": True, "from": [x1, y1], "to": [x2, y2],
+            "steps": steps, "button": button, "curve": curve}
+
+
+def scroll(x: int, y: int, amount: int = -3, **kw) -> dict:
+    """滚动。amount>0 上滚, <0 下滚; x,y 为滚动时鼠标位置。"""
+    x, y = _clamp(x, y)
+    pg = _pg()
+    pg.moveTo(x, y)
+    pg.scroll(int(amount), x=x, y=y)
+    _log("scroll", x=x, y=y, amount=amount)
+    return {"ok": True, "x": x, "y": y, "amount": amount}
+
+
+# ── 键盘 ──────────────────────────────────────────────────
+def type_text(text: str, interval: float = 0.02, **kw) -> dict:
+    """输入文本。
+
+    全 ASCII/常见符号 → 逐字符 typewrite(快)。
+    中文/Unicode → 走剪贴板+Ctrl+V(准确, 不受键盘布局影响)。
+    """
+    pg = _pg()
+    try:
+        # 判断是否需要剪贴板(含非 ASCII 即走剪贴板)
+        if text and any(ord(c) > 127 for c in text):
+            import pyperclip
+            pyperclip.copy(text)
+            pg.hotkey("ctrl", "v")
+        else:
+            pg.typewrite(text, interval=max(0.0, float(interval)))
+    except Exception as e:
+        return {"ok": False, "error": f"键盘输入失败: {e}"}
+    _log("type", text=text[:40])
+    return {"ok": True, "chars": len(text)}
+
+
+def key(keys, **kw) -> dict:
+    """按键/组合键。keys 可为 "enter" 或 ["ctrl", "c"] 组合。"""
+    pg = _pg()
+    try:
+        if isinstance(keys, str):
+            if "+" in keys:
+                parts = [p.strip() for p in keys.split("+")]
+                pg.hotkey(*parts)
+            else:
+                pg.press(keys)
+        elif isinstance(keys, (list, tuple)):
+            pg.hotkey(*keys)
+        else:
+            return {"ok": False, "error": f"keys 类型错误: {type(keys)}"}
+    except Exception as e:
+        return {"ok": False, "error": f"按键失败: {e}"}
+    _log("key", keys=keys)
+    return {"ok": True, "keys": keys}
+
+
+def hotkey(*keys) -> dict:
+    """组合键(如 ctrl, shift, s)。"""
+    return key(list(keys))
+
+
+# ── 前置操作钩子(截图存档) ────────────────────────────────
+_pre_hook: Callable[[str], None] | None = None
+
+
+def set_pre_hook(fn: Callable[[str], None] | None) -> None:
+    """设置每个动作前的回调(如存档 before 截图)。"""
+    global _pre_hook
+    _pre_hook = fn
+
+
+def _notify(kind: str) -> None:
+    if _pre_hook:
+        try:
+            _pre_hook(kind)
+        except Exception:
+            pass

nexforge_cli-0.2.13/plugin_gui_auto/guiauto/base.py

@@ -0,0 +1,161 @@
+"""NF-GUI 核心底座 —— 跨平台封装(Windows/macOS/Linux) + 安全 + 坐标系统。
+
+设计原则:
+- 所有鼠标/键盘操作基于 pyautogui(纯 Python, 跨 Win/macOS/Linux)。
+- 全平台统一坐标: 逻辑像素坐标(与 DPI 无关的屏幕逻辑坐标)。
+- 安全: 全局 FAILSAFE(鼠标到左上角即中断) + 操作间隔 + 可配置。
+- DPI: 自动感知系统缩放, 保证坐标精确(Windows 高 DPI 尤其关键)。
+- 平台差异: Windows 用 ctypes 富窗口控制, Linux 尝试 xdotool 增强。
+
+本模块只做底层封装, 不暴露给 AI; AI 通过工具层(gui_tools)使用。
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+# ── 第三方依赖(缺则降级提示) ─────────────────────────────
+try:
+    import pyautogui as _pg
+    _pg.PAUSE = 0.05          # 每个动作间隔(防过快)
+    _pg.FAILSAFE = True       # 鼠标甩到左上角中断
+    PY_AUTOGUI_OK = True
+except ImportError:
+    _pg = None
+    PY_AUTOGUI_OK = False
+
+
+# ── 平台常量 ─────────────────────────────────────────────
+def detect_platform() -> str:
+    """返回 'windows' / 'macos' / 'linux'(小写)。"""
+    s = platform.system().lower()
+    if s == "darwin":
+        return "macos"
+    if s.startswith("win"):
+        return "windows"
+    return "linux"
+
+
+PLATFORM = detect_platform()
+IS_WINDOWS = PLATFORM == "windows"
+IS_MACOS = PLATFORM == "macos"
+IS_LINUX = PLATFORM == "linux"
+
+
+# ── 依赖缺失诊断 ──────────────────────────────────────────
+def _dependency_error() -> str:
+    return (
+        "pyautogui 未安装。GUI 自动化需要它:\n"
+        "  pip install pyautogui\n"
+        "(跨平台支持 Windows/macOS/Linux; Linux 下还需系统 X11/输入权限)"
+    )
+
+
+def ensure_ready() -> str | None:
+    """检查环境, 返回错误信息或 None。"""
+    if not PY_AUTOGUI_OK:
+        return _dependency_error()
+    return None
+
+
+# ── DPI 感知 ──────────────────────────────────────────────
+_dpi_aware_done = False
+
+
+def set_dpi_aware() -> None:
+    """Windows 高 DPI 感知(禁系统缩放, 保证坐标精确)。macOS/Linux 无需处理。"""
+    global _dpi_aware_done, _dpi_scale
+    if _dpi_aware_done:
+        return
+    _dpi_aware_done = True
+    if IS_WINDOWS:
+        try:
+            import ctypes
+            # PROCESS_SYSTEM_DPI_AWARE=1: 以物理像素为准, 坐标更精确
+            ctypes.windll.shcore.SetProcessDpiAwareness(1)
+        except Exception:
+            try:
+                import ctypes
+                ctypes.windll.user32.SetProcessDPIAware()
+            except Exception:
+                pass
+        try:
+            import ctypes
+            _dpi_scale = _pg.screenshot().size[0] / _pg.size().width
+        except Exception:
+            _dpi_scale = 1.0
+    else:
+        _dpi_scale = 1.0
+
+
+_dpi_scale = 1.0
+
+
+def dpi_scale() -> float:
+    """当前 DPI 缩放系数(截图像素 / 逻辑坐标)。用于截图坐标换算。"""
+    set_dpi_aware()
+    return _dpi_scale
+
+
+# ── 屏幕信息 ──────────────────────────────────────────────
+def screen_size() -> dict:
+    """屏幕逻辑坐标尺寸。"""
+    if not PY_AUTOGUI_OK:
+        return {"width": 0, "height": 0}
+    w, h = _pg.size()
+    return {"width": int(w), "height": int(h)}
+
+
+def mouse_position() -> dict:
+    """当前鼠标位置(逻辑坐标)。"""
+    if not PY_AUTOGUI_OK:
+        return {"x": 0, "y": 0}
+    x, y = _pg.position()
+    return {"x": int(x), "y": int(y)}
+
+
+# ── 截图(统一入口) ────────────────────────────────────────
+def screenshot(path: str | Path | None = None, region: tuple[int, int, int, int] | None = None):
+    """截屏(可指定区域)。返回 PIL Image。region=(左, 上, 宽, 高) 逻辑坐标。"""
+    if not PY_AUTOGUI_OK:
+        return None
+    set_dpi_aware()
+    img = _pg.screenshot(region=region)
+    if path:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        img.save(str(path), "PNG")
+    return img
+
+
+# ── 安全轨道(fail-safe 区域外操作) ───────────────────────
+def ensure_failsafe_on() -> bool:
+    """开启 fail-safe(鼠标甩到屏幕左上角三格即中断)。"""
+    if not PY_AUTOGUI_OK:
+        return False
+    _pg.FAILSAFE = True
+    return True
+
+
+# ── 平台特有命令探测(Linux 增强) ──────────────────────────
+def which(cmd: str) -> str | None:
+    """找系统命令路径。"""
+    import shutil
+    return shutil.which(cmd)
+
+
+def linux_tools() -> dict:
+    """探测 Linux 上可用的 X11 增强工具。"""
+    if not IS_LINUX:
+        return {}
+    found = {}
+    for name in ("xdotool", "wmctrl", "import", "scrot"):
+        p = which(name)
+        if p:
+            found[name] = p
+    return found