# WinMacro **Repository Path**: ChenMuShan/win-macro ## Basic Information - **Project Name**: WinMacro - **Description**: 按键宏 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-30 - **Last Updated**: 2026-10-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 顺手坞（shunshouwu） 一个常驻托盘的 Windows 桌面小工具，把两件事装进同一个进程、同一个 exe： 1. **窗口宏录制 / 回放**（原「顺手宏 / WinMacro」）：盯住某个窗口，把你在上面的点击、键盘操作录成步骤，之后一键回放，可定时、可循环。 2. **剪贴板历史 + 打卡提醒**（原 ClipTrace）：记录每次复制的内容，24 小时自动销毁；到点弹一张常驻打卡卡片。 版本 0.2.0。架构是**单进程双窗口**：宏主窗口与剪贴板面板各自独立，共用一个托盘、一把单实例锁、一份退出路径。 深入阅读： - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) —— 进程模型、模块划分、数据流、并发约定、存储与打包结构、技术债（正文以剪贴板子系统为主线，文首有合并后的路径对照） - [docs/FEATURES.md](docs/FEATURES.md) —— 功能矩阵、面板与托盘、快捷键、保留策略、隐私边界、已知限制、测试覆盖 ## 功能 ### 宏录制 / 回放 - **选择目标窗口**：按标题通配（如 `开票系统*`）匹配，或直接在屏幕上点选；记录客户区尺寸与 DPI，回放前自动把窗口调回录制时的位置和大小 - **录制**：点「开始录制」后在目标窗口正常操作，点击与键盘自动变成步骤；按 `F9` 停止 - **真人模拟点击**：默认开启，鼠标走曲线路径而不是瞬移 - **点击范围**：给某个点击步骤框一个矩形，回放时在区域内随机取点；也可以「批量框选」一次性给所有点击步骤画范围（右键跳过、`Esc` 提前结束，已有点/范围会回显） - **步骤编辑**：拖拽排序、`＋ 添加步骤` 下拉（点击 / 按键 / 等待 / 文本）、按键可视化选键（含组合键） - **分组**：多选步骤打组，组可折叠、可拖拽排序，关掉整个组即整组跳过回放 - **定时执行**：单次 / 每天 / 循环（固定次数 + 间隔），到点排队串行执行；电脑锁屏时本次跳过，重启后不会重复补跑已执行过的任务 - **脚本管理**：新建、复制、删除；回放时可从「开始回放」或「试运行」；运行日志在界面里可查 ### 剪贴板历史 - 记录文本、图片、文件列表（CF_HDROP）、HTML、RTF 以及各种原始格式；六类内容（文本 / 图片 / 文件 / 二进制 / 数值 / 其他）可分别开关，改完常驻引擎立刻跟上，不用重启 - 每条记录落在本地缓存里，**超过 24 小时自动销毁**；另有条数上限与总容量上限 - 面板支持搜索、四个预览页签（文本 / 图片 / 文件 / 详情）、单条删除、一键回写剪贴板（回写后自动收起面板，直接 `Ctrl+V`） - 备份 / 恢复：把整份缓存（可连设置与打卡提醒）拷到空文件夹，之后按未过期记录恢复 ### 打卡提醒 - 多条提醒，每条自选时间与星期 - 到点在工作区正中弹出简约白底**常驻**卡片（宽度约占屏幕 60%，高度随条目数收缩，顶部实时时钟 + 待打卡条数） - 每行「打卡」只消掉自己；全部点掉或按 ✕ 才关窗，不写历史、不自动消失 - 过点 2 分钟以上、星期不匹配的不会补弹 ## 快速开始（开发） ```powershell # 首次安装依赖（约 266 MB；本机 GitHub 不可达，走 npmmirror 镜像） $env:ELECTRON_MIRROR = 'https://npmmirror.com/mirrors/electron/' npm install npm run app # 构建宏界面（vite）后启动 Electron npm start # 不重新构建，直接启动已构建的 dist/macro-ui ``` > 本机默认 shell 的 node 可能是 v14（npm 6），koffi 的原生安装脚本会失败。用 Node 22 跑 `npm`： > `export PATH="/c/Users/admin/.workbuddy/binaries/node/versions/22.22.2-6:$PATH"`（Git Bash）。 > 从 Qoder/VS Code 终端启动 Electron 前要 `unset ELECTRON_RUN_AS_NODE`，否则 exe 会退化成纯 node 直接崩。 ## 打包 ```powershell npm run dist ``` 产物在 `release\`： | 文件 | 说明 | | --- | --- | | `顺手坞-Setup-0.2.0.exe` | NSIS 安装包（可选安装目录、桌面 + 开始菜单快捷方式） | | `顺手坞.exe` | 免安装绿色版 | | `win-unpacked\顺手坞.exe` | 解包目录，测试脚本默认用它（`npm run test:clip:package`） | 打包要点（配置在 `package.json` 的 `build` 字段）： - `asar: true`，但 `node_modules/koffi/**` 与 `node_modules/@koromix/**` 必须 `asarUnpack` —— koffi 的原生 `koffi.node` 实际由平台包 `@koromix/koffi-win32-x64` 提供，解包漏了会在启动时报「找不到模块」 - `extraResources` 把 `engine\`（PowerShell 记录引擎 + lib）整目录放到 `resources\engine\` - `directories.app` 显式写成 `.`：仓库里还留着旧版 ClipTrace 的 `app\` 目录，不写死的话 electron-builder 会把它当成应用目录，打出一个「旧版」安装包 ## 日常使用 托盘图标左键 / 双击打开宏主窗口；右键是统一菜单： | 菜单项 | 行为 | | --- | --- | | 打开顺手坞（宏录制） | 显示宏主窗口 | | 剪贴板历史（n 条） | 展开剪贴板面板 | | 暂停 / 恢复剪贴板记录 | 暂停期间引擎不记录新内容 | | 立即清理过期记录 | 立刻跑一次 24h / 条数 / 容量裁剪 | | 打开剪贴板缓存目录 | 资源管理器打开缓存根目录 | | 面板失焦时自动收起 | 面板失焦即隐藏（默认开） | | 退出顺手坞 | 收掉引擎与所有窗口，真正退出 | - **全局快捷键** `Ctrl+Shift+V`：打开 / 收起剪贴板面板（测试模式不注册） - **单实例**：再运行一次程序只会唤醒已有实例（有宏窗口就显示宏窗口；带 `--open` 会展开剪贴板面板），带 `--quit` 则让正在跑的实例退出 - 关窗口只是收进托盘：宏窗口和面板都常驻，宏的定时任务也因此能继续跑 ## 数据与日志 | 路径 | 内容 | | --- | --- | | `%APPDATA%\winmacro\` | 宏脚本、定时状态、`logs\main.log`（合并后继续沿用旧 WinMacro 目录，老数据零迁移） | | `%LOCALAPPDATA%\ClipTrace\` | 剪贴板记录缓存、`config.json`、`app-state.json`、`reminders.json`、`logs\app.log` | 测试的缓存与 userData 一律放在 `%LOCALAPPDATA%\ClipTrace*Test`、仓库 `tests\tmp\` 这类沙箱目录里，不会写上面两份真实数据。 `%LOCALAPPDATA%\ClipTrace` 可用环境变量 `CLIPTRACE_ROOT` 覆盖（面板与引擎都读它）。 ## 目录结构 ``` main.js 统一入口：userData、单实例锁、argv 路由、托盘装配、退出 tray.js 统一托盘（图标 + 菜单），从两个子系统取状态 vite.config.mjs 宏界面（src/macro-ui）的构建配置，输出 dist/macro-ui src/macro/ 宏子系统：win32 / recorder / player / scheduler / store / overlay ... src/macro-ui/ 宏界面（Vue 3 + Vite） src/clip/ 剪贴板子系统：窗口、面板 IPC、打卡提醒、测试驱动、引擎进程管理 src/clip-ui/ 剪贴板面板 / 打卡弹窗（原生 HTML + CSS + JS） src/preload/ 宏窗口与 overlay 的 preload src/overlay/ 区域框选、点击点选用的透明覆盖层 src/shared/ 两端共用（键名表） engine/ PowerShell 记录引擎：ClipTrace.ps1 + lib\{Store,Capture,Engine}.ps1 assets/ 图标（assets/clip 是剪贴板面板与旧托盘用的图标） tests/macro/ 宏的单元测试 / UI 套件 / e2e tests/clip/ 剪贴板的 smoke / CLI / 面板 / 提醒 / 打包验证（PowerShell 5.1） tools/ 测试目标窗口、UIA 探针 app/ lib/ dist/ 旧版 ClipTrace 的源码与产物，合并后已不被引用（待清理，见下） ClipTrace.cmd / ClipTrace.ps1 / build-exe.ps1 / autostart.ps1 旧版启动与打包脚本（待清理） ``` ## 测试 宏： ```powershell npm test # 单元测试（node --test，player / scheduler / store ...） npm run test:ui # UI 套件：无侵入驱动（不抢鼠标/焦点），报告在 tests/macro/tmp/out/ui-record.json npm run test:e2e # 端到端；加 --input 才会真的注入输入（会抢键鼠，自己看着跑） ``` 剪贴板（PowerShell 5.1，均需管理员无关的普通权限即可）： ```powershell npm run test:clip # tests/clip/smoke.ps1 存储与抓取层 npm run test:clip:cli # tests/clip/cli.ps1 引擎 CLI、类型开关热重载、备份/恢复 npm run test:clip:ui # tests/clip/electron.ps1 面板、--open、--quit、滚动位置、暂停 npm run test:clip:remind # tests/clip/remind.ps1 打卡弹窗尺寸/常驻/打卡/设置页 npm run test:clip:package # tests/clip/package-check.ps1 打包版 exe 全链路（先跑 npm run dist） ``` 无侵入约定：界面操作全部交给主进程的测试驱动（`executeJavaScript` 判据 + `capturePage` 截图），窗口用 `CLIPTRACE_NO_FOCUS=1` 只现形不抢焦点；必须写真剪贴板的套件会先 `Protect-Clip` 存下你当前剪贴板，跑完 `Restore-Clip` 原样还回去。异常中断留下常驻引擎时跑 `powershell -File tests/clip/cleanup.ps1` 收干净。 测试相关环境变量： | 变量 | 作用 | | --- | --- | | `WINMACRO_USER_DATA` | 强制 userData（单实例锁作用域、宏数据、日志都跟着走）；测试必须指到沙箱 | | `WINMACRO_UI_TEST` | 只启动宏侧（不装剪贴板），宏的 UI/e2e 套件用它 | | `CLIPTRACE_ROOT` | 剪贴板缓存根目录 | | `CLIPTRACE_TEST_MODE=1` | 测试模式；若缓存目录仍指向真实 `%LOCALAPPDATA%\ClipTrace` 会直接退出 | | `CLIPTRACE_NO_FOCUS=1` | 窗口只现形不抢焦点、不注册全局钩子；同时表示「只启动剪贴板侧」 | | `CLIPTRACE_TEST_SCRIPT` / `_REPORT` / `_OUT` | 步骤脚本 JSON、报告路径、截图输出目录 | | `CLIPTRACE_KEEP_OPEN=1` | 关掉「失焦自动收起」，方便截图与自动化 | ## 技术栈 - Electron 31.7.7（单版本）、Vue 3 `