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

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

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

{nexforge_cli-0.2.11 → 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.11
+> NexForgeCLI v0.2.13
 
 ## 环境要求
 

{nexforge_cli-0.2.11 → 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.11 → 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.11 → nexforge_cli-0.2.13}/manual/04-/345/267/245/345/205/267/345/217/202/350/200/203.md

@@ -45,10 +45,12 @@ 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` | 知识沉淀(写入项目/全局知识库) |
+| `window_screenshot` | 指定窗口截图(Windows, 标题/进程定位, 遮挡也能截) |
+| `web_screenshot` | Web 页面离线渲染截图(无头浏览器, 不弹窗) |
 
 详见 [05-数据与搜索](05-数据与搜索.md)。
 
@@ -77,7 +79,9 @@ NexForgeCLI 内置 **35 个工具**供 AI 调用（`git_commit` 需在 config.to
 
 | 工具 | 功能 |
 |------|------|
-| `federation` | 多项目联结体管理 |
+| `federation` | 多项目联结体管理(init/add/remove/context/status/memory/sessions/handoff/close/task-add/task-list/task-done) |
+| `kb_search` | 知识检索(scope 支持 fed 聚合联结体成员、member:<名> 指定成员) |
+| `kb_write` | 知识沉淀(scope 支持 `member:<成员名>` 写回联结体成员知识库) |
 
 ## 工具限制
 

{nexforge_cli-0.2.11 → 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.13/manual/07-/344/274/232/350/257/235/344/270/216/350/256/260/345/277/206.md

@@ -0,0 +1,100 @@
+# 会话与记忆
+
+## 会话管理
+
+### 自动保存
+
+每次 AI 回复完成后自动保存当前会话到 `.nexforge/sessions/`，文件为可读 Markdown 格式。
+
+### 自动恢复
+
+启动时自动恢复当前项目最近一次会话，包括完整对话历史。
+
+### 长会话上下文压缩
+
+超过 60 轮时自动压缩：保留最近 20 轮全文，更早的对话压缩为**历史摘要**（恢复后可见，避免历史大段丢失）；被压缩的原始对话**完整归档**到 `.nexforge/sessions/<id>.archive.md`，随时可查。
+
+### 会话侧边栏
+
+按 `F5` 打开会话侧边栏：
+
+- **新建会话**：点击 `+ 新建会话`
+- **切换会话**：点击会话名，自动保存当前、加载选中
+- **重命名**：`/rename 新名称`
+- **删除**：点击 `✖` 按钮
+
+当前活跃会话有绿色圆点标记。
+
+### 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `/save [name]` | 保存并命名当前会话 |
+| `/rename <name>` | 重命名当前会话 |
+| `/sessions` | 列出历史会话 |
+| `/clear` | 清空当前会话 |
+| `/cost` | 显示累计 token 和费用 |
+
+## 项目记忆
+
+NexForgeCLI 支持多层记忆，让 AI 在多次对话中持久记住项目信息。
+
+### 记忆类型
+
+| 记忆层 | 文件 | 作用 |
+|--------|------|------|
+| **基础记忆** | `.nexforge/memory/base.md` | 所有场景共享的持久信息 |
+| **运维记忆** | `.nexforge/memory/ops.md` | 运维操作记录(服务器配置、常用命令) |
+| **目标记忆** | `.nexforge/memory/goal.md` | 目标模式专用上下文 |
+| **已验证方案** | `.nexforge/ops_known.md` | 运维已验证的成功命令/调用(读取复用,可手动维护) |
+
+启动时自动加载基础记忆。运维模式开启时额外加载运维记忆。
+
+### 联 结体
+
+联结体是**多项目协同工作区**。关联多个相关项目，为每个项目设定角色，AI 在联结体上下文中工作，
+**并把工作写回各成员项目自身结构**，保证成员回到各自的 nf 实例继续开发时零信息割裂。
+
+```bash
+# 在 nf 输入框里用 /federation 命令
+/federation init                     # 初始化联结体
+/federation add <项目路径> [角色]     # 添加成员(名称取目录名, 角色可选如 后端)
+/federation remove <名称>            # 移除成员
+/federation context                  # 查看联结体上下文(成员+角色+最近共享记忆)
+/federation status                   # 查看各成员实时状态(git分支/未提交/最近会话)
+/federation memory                   # 查看共享记忆
+/federation sessions                 # 列出各成员项目的会话历史
+/federation handoff                  # 为所有成员生成/更新交接文档
+/federation close                    # 结束本次协同: 全成员写回(交接+地图+纪要会话)
+```
+
+#### 双向同步机制（写回）
+
+联结体是**临时工作区**，各成员项目是**持久家园**。协同期间自动写回：
+
+| 写回内容 | 落点(成员项目内) | 触发 |
+|---------|-----------------|------|
+| 每轮操作日志 | `.nexforge/ops_log.md` | 每轮结束自动 |
+| 进展记忆 | `.nexforge/memory/base.md` | 每轮结束自动 |
+| 项目地图刷新 | `.nexforge/map/` | 轮末哈希比对,有变化才 sync |
+| 知识沉淀 | `.nexforge/kb/`(`kb_write scope=member:<名>`) | AI 主动 |
+| 交接文档 | `.nexforge/federation/handoff.md` | `/federation close` 或 `handoff` |
+| 工作纪要会话 | `.nexforge/sessions/session-*.md` | `/federation close` |
+
+成员项目回到自身 nf 启动时，若检测到 `handoff.md` 会自动注入交接上下文，AI 延续工作不割裂。
+`kb_write` 支持 `scope=member:<成员名>` 直接把知识写回指定成员的知识库；
+`kb_search` 支持 `scope=fed`(聚合检索所有成员知识库) 和 `scope=member:<名>`(检索指定成员)。
+
+#### 任务流转
+
+AI 通过 `federation` 工具管理跨成员任务(`.nexforge/federation/tasks.md`)：
+
+```
+federation task-add name=<成员> content=<任务描述>   # 分配任务, 返回 #id
+federation task-list                                # 列出所有任务及状态
+federation task-done content=<id>                   # 标记任务完成
+```
+
+#### 双向记忆
+
+共享记忆按「用户指令 + AI 决策」成对记录(每轮自动)，供联结体上下文读取，协同意图可追溯。

{nexforge_cli-0.2.11 → 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.11 → nexforge_cli-0.2.13}/manual/README.md

@@ -1,4 +1,4 @@
-# NexForgeCLI 用户手册 · v0.2.11
+# 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