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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.12
+Version: 0.2.14
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.11** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.2.14** · PyPI: `pip install nexforge-cli`
 
 ---
 

{nexforge_cli-0.2.12 → nexforge_cli-0.2.14}/README.md

@@ -8,7 +8,7 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.11** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.2.14** · PyPI: `pip install nexforge-cli`
 
 ---
 

{nexforge_cli-0.2.12 → nexforge_cli-0.2.14}/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.14
 
 ## 环境要求
 
@@ -72,6 +72,8 @@ API Key 保存在 `~/.nexforge/auth.toml`，不会被 Git 追踪。
 pip install --upgrade nexforge-cli
 ```
 
+启动 nf 时会自动检查 PyPI 最新版本（24 小时缓存一次，失败静默），若有新版本会在界面提示升级命令。
+
 ## 卸载
 
 ```bash

{nexforge_cli-0.2.12 → nexforge_cli-0.2.14}/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.14}/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 模式下的升级触发条件：
 - 关键词(重构/架构/算法/证明/调试/为什么/设计)
@@ -123,6 +125,27 @@ models = ["claude-sonnet-4-20250514"]
 
 切换后自动持久化，重启 nf 保持选中。
 
+### 动态模型列表（千问 / OpenAI 兼容）
+
+大模型更新太快，`models.toml` 里手写的模型名可能过时。对 **千问** 和 **OpenAI 兼容**（`type = "openai"`）provider，F6 侧边栏会：
+
+- 自动调用该平台的 `/models` 接口，拉取当前 API Key 下**实际可用**的模型列表
+- 拉取结果缓存 24 小时，失败时回退 `models.toml` 里写的静态列表
+- 每个模型名都是一个可点击按钮，直接点选切换具体模型（当前使用的模型标绿点 ●）
+
+```
+│ ● qianwen  ✓            │
+│   类型: qianwen          │
+│   ● qwen3.8-max          │  ← 当前使用
+│     qwen-vision-plus     │  ← 动态拉取到的新模型, 点选即切换
+│     qwen-long            │
+│   [🔄 刷新模型]          │  ← 强制重新拉取最新列表
+```
+
+点「🔄 刷新模型」可强制清缓存重新拉取（比如平台刚上线了新模型）。
+
+**选择持久化**：点选的具体模型记录到 `~/.nexforge/model_selection.json`（独立于只读的 `models.toml`，不污染配置），重启 nf 保持选中。
+
 ## 自动路由 vs 多模型切换
 
 - **自动路由**（DeepSeek auto 档）：同一个模型内，根据任务复杂度自动选择 flash 或 pro

{nexforge_cli-0.2.12 → nexforge_cli-0.2.14}/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` | 知识沉淀(写入项目/全局知识库) |
@@ -87,7 +87,7 @@ NexForgeCLI 内置 **35 个工具**供 AI 调用（`git_commit` 需在 config.to
 
 | 限制 | 值 | 说明 |
 |------|-----|------|
-| 工具调用轮数 | 200 | 防死循环 |
+| 工具调用轮数 | 300(目标模式 500) | 防死循环; 单轮内连续调工具上限, 目标模式自动放大 |
 | 单轮总超时 | 0 秒(不限额) | 默认不限额; 可 /timeout <秒> 或 config.toml 的 `turn_timeout` 设置 |
 | 单工具超时 | 60 秒 | |
 

{nexforge_cli-0.2.12 → nexforge_cli-0.2.14}/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.14}/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), 长思考会吃配额, 不够可调大
@@ -59,6 +59,7 @@ model = "qwen-audio-3.0-tts-flash"  # 千问 TTS 模型
 voice = "loongmary"             # 音色(flash 用 loong 系列: loongmary/loongeva/loongJohn 等)
 engine = "auto"                 # auto | qianwen | local
 max_chars = 100                 # 简报最大字符数
+enabled = true                  # 语音播报总开关
 
 [search]
 engine = "bing"              # bing | duckduckgo | google | searxng

{nexforge_cli-0.2.12 → nexforge_cli-0.2.14}/manual/10-/346/217/222/344/273/266/345/274/200/345/217/221.md

@@ -70,9 +70,9 @@ def register(api):
 
 `~/.nexforge/plugins/speech_summary.py`（已随本机安装）——每轮任务结束用 TTS 播报简报：
 
-- **引擎**：千问语音合成（qwen-audio-3.0-tts-plus，官方 dashscope SDK WebSocket 方式）优先，失败自动回退 Windows 本地语音（SAPI）
+- **引擎**：千问语音合成（qwen-audio-3.0-tts-flash，官方 dashscope SDK WebSocket 方式）优先，失败自动回退 Windows 本地语音（SAPI）
 - **配置**（config.toml `[tts]` 段）：`engine=auto|qianwen|local`、`voice`、`api_key`（留空用 [image] 按量 key）、`ws_url`、`max_chars`、`enabled`
 - **不阻塞**：合成+播放在后台线程，回合结束流程零延迟
 - **简报内容**：项目名 + 工具调用次数 + AI 最终总结摘要（自动清理 Markdown 符号）
 
-> 千问 TTS 使用条件：① `pip install dashscope`；② 平台控制台**开通 qwen-audio-3.0-tts-plus 按量服务**（¥1.4/万字符，Token Plan 套餐不含）。未满足时自动回退本地语音，不打断工作。
+> 千问 TTS 使用条件：① `pip install dashscope`；② 平台控制台**开通 qwen-audio-3.0-tts-flash 按量服务**（¥1.4/万字符，Token Plan 套餐不含）。未满足时自动回退本地语音，不打断工作。

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

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

nexforge_cli-0.2.14/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.14/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.14/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