289 lines
14 KiB
Markdown
289 lines
14 KiB
Markdown
# 按键精灵（anjianjingling）· 技术方案 v2.1
|
||
|
||
> 版本：v2.3（全 C# + 四区界面 + 榫卯积木 + **脚本 ⇄ 积木 双向转换**）
|
||
> 日期：2026-10-23
|
||
> 状态：已实现并可编译运行
|
||
|
||
---
|
||
|
||
## 0. 技术栈（全部 C# / .NET）
|
||
|
||
| 项 | 选型 | 说明 |
|
||
|---|---|---|
|
||
| 语言 / 框架 | **C# + WinForms + .NET 10**（`net10.0-windows`） | 单一技术栈，无前端工程 |
|
||
| 脚本引擎 | **MoonSharp 2.0.0**（纯托管 Lua 5.2） | 无 native 依赖，`dotnet build` 即可 |
|
||
| 积木编辑器 | **自绘 WinForms 控件 `BlockCanvas`** | GDI+ 圆角积木、拖拽排序、容器嵌套，**非网页** |
|
||
| 输入模拟 | `SendInput`（user32） | 系统级键鼠，坐标为屏幕物理像素 |
|
||
| 找图 | OpenCvSharp4 `MatchTemplate` | 相似度阈值 0~1 |
|
||
| 找色 | `LockBits` 逐像素扫描 | 支持容差 |
|
||
| 操作录制 | `WH_KEYBOARD_LL` / `WH_MOUSE_LL` 低级钩子 | 录制 → 智能聚合 → 生成 Lua |
|
||
| 屏幕录像 | GDI 抓帧 + JPEG + 自写 AVI(MJPG) 封装 | 不依赖 ffmpeg，输出可播放 avi |
|
||
| 内嵌浏览器 | WebView2（仅浏览器标签页用） | 与积木无关，可选功能 |
|
||
|
||
---
|
||
|
||
## 0.5 界面布局（四区）
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 菜单栏 文件 / 积木 / 工具 / 帮助 │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 工具栏 ▶启动 F8 ‖暂停 F9 ■停止 F10 │ ＋新建 复制 删除 │ 录制 截图 │
|
||
├──────────┬───────────────────────────────────┬───────────────┤
|
||
│ 任务列表 │ 任务详情 │ 插件 │
|
||
│ （左） │ ┌ 任务名 / 启用 / 循环 / 间隔 ─┐ │ 屏幕与定位 │
|
||
│ ·任务1 │ │ 脚本代码 积木 录制 浏览器 │ │ 坐标取色器 │
|
||
│ ·任务2 │ │ │ │ 框选截图 │
|
||
│ ·任务3 │ │ 编辑区 │ │ 找图测试 │
|
||
│ │ └───────────────────────────────┘ │ 录制 │
|
||
│ 共 N 个 │ │ 系统与帮助 │
|
||
├──────────┴───────────────────────────────────┴───────────────┤
|
||
│ 运行日志（跨全宽，可拖动高度） │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ 状态栏 状态：空闲 F8 启动 · F9 暂停 … 行1,列1 │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
| 区域 | 内容 | 行为 |
|
||
|---|---|---|
|
||
| 左：任务列表 | 自绘列表，每项显示任务名 + 循环次数/间隔 + 状态色条 + **启用勾选框** | 单击切换任务；点勾选框直接启/停；右键新建/复制/删除/上下移/立即运行 |
|
||
| 中：任务详情 | 顶部属性条（名称/启用/无限/次数/间隔/**启动热键 F1~F7**）+ 四个页签 | 改动实时回写任务，无需保存按钮 |
|
||
| 右：插件 | 分组卡片按钮：屏幕与定位 / 录制 / 脚本 / 系统与帮助 | 一键调用工具，不占主编辑区 |
|
||
| 下：日志 | 深色日志区，错误红、成功绿 | 跨全宽，分割条可拖 |
|
||
|
||
---
|
||
|
||
## 1. 功能清单
|
||
|
||
### 1.1 Lua 脚本
|
||
- 完整 Lua 语法（`if / for / while / function / table / string.format`…）
|
||
- 双写法并存：全局简写 `moveTo(100,200)` + 命名空间 `mouse.moveTo(100,200)`
|
||
- 语法着色 + 行号栏 + 中文错误提示
|
||
- F8 队列运行、F9 暂停、F10 停止、左上角 (0,0) 急停
|
||
|
||
### 1.2 积木编程（插片耦合 · 与脚本双向转换）
|
||
- **单一数据源**：任务只保存 Lua 脚本。积木页是脚本的另一种视图——切到积木页自动「脚本 → 积木」；在积木里增删改（含改参数）自动「积木 → 脚本」回写，两边永远一致，不存在两份代码
|
||
- 旧版任务里只有积木没有脚本的，打开时自动把积木转成脚本
|
||
- 解析覆盖目录全部命令：流程容器（for/while/if/elseif/else）、找图（ifExists 还原自 do+local __ix 结构）、赋值/自增、mouse.down 等；认不出的行进「自定义代码」块，原样保留不丢失
|
||
- 往返稳定：脚本 → 积木 → 脚本 内容一致（二次往返验证通过）
|
||
|
||
#### 插片耦合造型
|
||
- **榫卯咬合**：每块顶部有凹槽、底部有凸榫（7px），相邻块互相插接，视觉上是一条拼好的积木链
|
||
- **C 形容器**：`循环 N 次`、`当…时循环`、`无限循环`、`如果…否则` —— 左壁 + 内部插槽底 + 底部封口；空容器显示「把积木拖到这里」
|
||
- 「否则」是容器内腔里的横向分隔条，把插槽分成上下两半
|
||
- **参数 = 白色插槽**：标题里的参数值画成可嵌入的白色槽（Blockly 风格），选中块后右侧改参数即时刷新
|
||
- 双击或拖拽添加；拖动改序 / 拖进容器嵌套；黄色描边 = 选中
|
||
- 一键「生成 Lua →」「运行积木」，存为 `.ajb`（JSON）
|
||
|
||
### 1.3 操作录制（F12）
|
||
- 录制真实的键盘、鼠标点击、滚轮、拖动
|
||
- 连续鼠标移动合并为一次 `moveTo`（15ms/3px 采样节流）
|
||
- 连续可打印字符聚合为 `typeText("...")`
|
||
- `Ctrl/Alt/Win + X` 自动合成 `hotkey("Ctrl+X")`
|
||
- 时间差 → `delay(ms)`，可设最大延时截断
|
||
- 结果直接填入脚本页或直接运行
|
||
|
||
### 1.4 屏幕录像
|
||
- 全屏或框选区域录制，帧率 1~30，可含鼠标指针
|
||
- 输出 `recordings/rec_yyyyMMdd_HHmmss.avi`（MJPEG），任意播放器可播
|
||
- 固定帧率策略：抓不过来就丢帧，保证视频时长 = 真实时长
|
||
|
||
### 1.5 任务列表（左侧栏）
|
||
- 每个任务独立持有：脚本、积木、名称、启用、次数/无限、轮次间隔
|
||
- 单击任务 → 中间详情立即载入该任务的脚本与积木（互不干扰）
|
||
- 右键菜单：新建 / 复制 / 删除 / 上移 / 下移 / 立即运行此任务
|
||
- F8 依次执行所有「已启用」任务，每项可设次数 / 无限 / 轮次间隔
|
||
- 整个列表保存为 `.ajt`（JSON）
|
||
|
||
### 1.6 插件面板（右侧栏）
|
||
| 分组 | 插件 |
|
||
|---|---|
|
||
| 屏幕与定位 | 坐标取色器、框选截图、全屏截图、找图测试、打开图库目录 |
|
||
| 录制 | 键鼠录制、全屏录屏、区域录屏、停止录屏、打开录像目录 |
|
||
| 脚本 | 运行当前任务、生成 Lua、打开脚本、载入积木 |
|
||
| 系统与帮助 | 窗口列表、Lua 语法速查、关于 |
|
||
|
||
---
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
anjianjingling/
|
||
├── anjianjingling.csproj
|
||
├── app.manifest # requireAdministrator（控制管理员程序必需）
|
||
├── Program.cs
|
||
├── Forms/
|
||
│ ├── MainForm.cs # 主窗体：任务列表 / 详情 / 插件 / 日志 四区布局
|
||
│ ├── PickerForm.cs # ★ 坐标取色器（放大镜 + 实时坐标/颜色）
|
||
│ ├── BlockCanvas.cs # ★ 自绘积木画布（拖拽/嵌套/插入指示线）
|
||
│ ├── LuaEditor.cs # ★ Lua 编辑器（行号 + 语法着色）
|
||
│ └── OverlayForm.cs # 框选截图 / 取录屏区域
|
||
├── Lua/
|
||
│ ├── LuaEngine.cs # ★ MoonSharp 宿主 + 暂停/停止/急停 + 队列
|
||
│ ├── ScriptApi.cs # ★ Lua API 注册（mouse/key/screen/win/browser/clip）
|
||
│ ├── LuaBlocks.cs # ★ 积木定义表 + Lua 生成器 + JSON
|
||
│ ├── LuaTask.cs # 任务模型 + .ajt 读写
|
||
│ └── ILuaHost.cs # 能力接口（主窗体实现）
|
||
├── Capture/
|
||
│ ├── InputRecorder.cs # ★ 低级键鼠钩子录制 → Lua
|
||
│ └── ScreenRecorder.cs # ★ 屏幕录像 + AVI(MJPG) 封装
|
||
├── Input/ MouseInput.cs KeyboardInput.cs
|
||
├── Vision/ ScreenCapture.cs ImageFinder.cs ColorFinder.cs
|
||
├── Window/ WindowManager.cs
|
||
├── Browser/ WebViewBridge.cs
|
||
├── Native/ Win32.cs
|
||
├── Common/ LogBus.cs VirtualKeys.cs
|
||
├── Samples/ demo_loop.lua demo_text.lua demo_record.lua
|
||
└── images/ # 模板图目录（F11 框选截图默认存这里）
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Lua API 参考
|
||
|
||
### 3.1 基础
|
||
```lua
|
||
delay(ms) -- 等待（可被 F9/F10 打断）
|
||
delayRandom(min, max) -- 随机等待
|
||
log("文本") -- 写运行日志
|
||
stop() -- 主动结束脚本
|
||
random(1, 10) now() -- 随机数 / 时间戳
|
||
```
|
||
|
||
### 3.2 鼠标
|
||
```lua
|
||
moveTo(x, y) moveR(dx, dy)
|
||
leftClick() / leftClick(x, y)
|
||
rightClick() / rightClick(x, y)
|
||
middleClick() doubleClick(x, y)
|
||
wheel(-1) -- 正数向上，负数向下
|
||
drag(x1, y1, x2, y2, ms)
|
||
mouse.down("left") mouse.up("left")
|
||
local x, y = mouse.pos()
|
||
```
|
||
|
||
### 3.3 键盘
|
||
```lua
|
||
keyPress("ENTER") -- A~Z 0~9 F1~F12 ENTER SPACE TAB ESC LEFT UP RIGHT DOWN …
|
||
hotkey("Ctrl+Shift+Esc")
|
||
typeText("中文文本") -- Unicode 注入，不受输入法影响
|
||
keyDown("SHIFT") keyUp("SHIFT")
|
||
```
|
||
|
||
### 3.4 视觉
|
||
```lua
|
||
local x, y = findImage("images/btn.png", 0.85) -- 找不到 x = -1
|
||
local x, y = findColor("FF0000", 10)
|
||
local x, y = waitImage("images/btn.png", 10000) -- 轮询等待
|
||
if exists("images/btn.png") then … end
|
||
screenshot("shot.png")
|
||
screen.pick("images/btn.png") -- 运行时框选截图存模板
|
||
screen.color(x, y) -- "RRGGBB"
|
||
```
|
||
|
||
### 3.5 系统 / 剪贴板 / 浏览器
|
||
```lua
|
||
run("notepad.exe") activate("记事本") win.list()
|
||
clipSet("内容") local s = clipGet()
|
||
browser.open("https://…") browser.click("#btn")
|
||
browser.type("#input", "内容") browser.wait(".loaded", 10000)
|
||
local t = browser.text(".result") browser.js("document.title")
|
||
browser.back() browser.forward() browser.reload() browser.shot("web.png")
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 关键实现说明
|
||
|
||
### 4.1 积木 → Lua
|
||
`BlockCatalog` 中每个积木含 `Title`（显示模板）与 `Template`（Lua 模板）。
|
||
渲染与生成共用同一套 `{0} {1}` 占位，参数按 `ArgKind` 决定是否加引号：
|
||
|
||
| ArgKind | 用途 | 生成 |
|
||
|---|---|---|
|
||
| Number | 坐标、毫秒、相似度 | 原样 |
|
||
| Text | 文件路径、文本 | `"…"` 转义 |
|
||
| Key | 键名、鼠标键 | `"…"` |
|
||
| Expr | 条件表达式 | 原样 |
|
||
| Raw | 变量名、注释 | 原样 |
|
||
|
||
容器块（LoopN / LoopWhile / If / IfExists）在生成器里递归，缩进 4 空格。
|
||
|
||
### 4.2 中断模型
|
||
每条 Lua API 回调首先调用 `LuaEngine.Tick()`：
|
||
- `CancellationToken` 已取消 → 抛 `AbortSignal`（MoonSharp 会原样透传，不被 `pcall` 吞掉）
|
||
- 暂停 → 阻塞在 `ManualResetEventSlim`
|
||
- 急停 → 每 100ms 节流检测鼠标是否在 (0,0)，停留 120ms 即中止
|
||
|
||
`delay` 按 20ms 分片，期间同样响应暂停/停止。
|
||
|
||
### 4.3 录制聚合
|
||
原始事件（带时间戳）→ 单遍扫描：
|
||
1. 连续 `Move` → 只保留落点，生成一次 `moveTo`
|
||
2. `Down` + 500ms 内同名 `Up` → 合并成一次点击
|
||
3. 修饰键状态栈 + 主键 → `hotkey("Ctrl+X")`
|
||
4. 可打印字符进缓冲区，遇到非字符事件 flush 成 `typeText`
|
||
5. 事件间隔 ≥30ms → `delay(间隔)`，超过上限则截断
|
||
|
||
### 4.4 AVI 封装
|
||
```
|
||
RIFF/AVI
|
||
├ LIST hdrl → avih(56) + LIST strl(strh 56 + strf 40)
|
||
├ LIST movi → 00dc 帧 chunk（JPEG 数据，奇数长度补 0）
|
||
└ idx1 → 每帧 16 字节索引
|
||
```
|
||
写完回填 RIFF/movi 长度、总帧数、最大帧字节数。MJPEG 无需关键帧，所有帧都是关键帧（flag `0x10`）。
|
||
|
||
---
|
||
|
||
## 5. 热键
|
||
|
||
| 键 | 功能 |
|
||
|---|---|
|
||
| F8 | 启动任务队列 |
|
||
| F9 | 暂停 / 继续 |
|
||
| F10 | 停止 |
|
||
| F11 | 框选截图（直接存 `images/`，可当模板图） |
|
||
| F12 | 开始 / 停止操作录制 |
|
||
| 鼠标到 (0,0) | 紧急停止 |
|
||
|
||
---
|
||
|
||
## 6. 已验证项
|
||
|
||
| 项 | 结果 |
|
||
|---|---|
|
||
| `dotnet build` | 0 错误（仅 WebView2 自带的 WindowsBase 版本警告） |
|
||
| 积木 → Lua 生成 | 循环/条件/否则/找图/键盘/拖拽/注释全部正确 |
|
||
| Lua 执行 | 找图多返回值、`for`、`table`、剪贴板、`stop()` 正常 |
|
||
| 语法错误提示 | 中文提示并带位置 |
|
||
| 屏幕录像 | 1.5s @10fps → 16 帧，RIFF/idx1 结构正确 |
|
||
| 主窗体构造 | 四区布局全部正常渲染（1360×860） |
|
||
| 脚本⇄积木 | 演示脚本 581 字符 → 18 个积木（注释/循环/ifExists/赋值全命中）；改积木参数 delay(1234) 后脚本自动回写；往返一致 |
|
||
| 新任务 | 模板脚本 4 行 → 4 个积木自动转换 |
|
||
| 任务联动 | 改任务名即时同步左侧；切换任务脚本/积木各自恢复（积木 JSON 1345 字节往返正常） |
|
||
| 任务增删 | 新建→选中→载入模板脚本；删除后自动选中相邻任务 |
|
||
| 插件面板 | 17 个插件项，内容超高时垂直滚动条正常 |
|
||
|
||
---
|
||
|
||
## 7. 已知限制
|
||
|
||
| 限制 | 说明 |
|
||
|---|---|
|
||
| 管理员权限 | manifest 为 `requireAdministrator`，需以管理员身份运行才能控制系统级窗口 |
|
||
| 纯计算死循环 | 不调用任何 API 的 `while true do end` 无法被 F10 中断（无指令级钩子） |
|
||
| 中文输入法录制 | 低级钩子只能拿虚拟键码，输入法上屏的中文需改用 `typeText` |
|
||
| DirectX 独占全屏 | 抓图/后台消息无效，属系统限制 |
|
||
| 游戏内核反作弊 | 应用层模拟无法驱动，明确不支持 |
|
||
|
||
---
|
||
|
||
## 8. 后续可扩展
|
||
|
||
- OCR 文字识别（接 PaddleOCR / Windows.Media.Ocr）
|
||
- 录制时自动补找图锚点（点击位置周边取 32×32 模板）
|
||
- 积木 → 脚本 双向（Lua 子集解析回积木）
|
||
- 脚本加密打包（导出 exe / 加密 lua）
|
||
- 多坐标点绑定窗口（窗口相对坐标）
|