Skip to content

SPEC.md

Latest commit

 

History

History
157 lines (114 loc) · 6.5 KB

SPEC.md

File metadata and controls

157 lines (114 loc) · 6.5 KB
Raw

AutoTyper — 需求规格文档

版本：v2.0.0
日期：2026-09-20
状态：已实现（本文档保留作需求追溯；v2.0 起为 Rust 实现，v1.x Python 实现归档于 legacy-python/）

1. 项目概述

1.1 背景

部分在线学习平台（如学习通、超星）的在线答题输入框对文本输入做了限制——仅允许通过剪贴板粘贴内容，或者对 keydown / keypress 等键盘事件做了拦截，导致用户无法正常通过键盘或自动化工具输入文本。

1.2 项目目标

AutoTyper 是一款通用的 Windows 桌面输入工具，通过调用 Windows 用户态 API（user32.dll 的 PostMessageW），向目标窗口的消息队列直接投递 WM_CHAR 消息，从而绕过剪贴板、绕过键盘事件拦截，在任何输入框中模拟真实的字符输入。

1.3 核心定位

维度 说明
输入方式 PostMessageW → WM_CHAR（Unicode 字符级注入）
绕过机制 不经过剪贴板、不触发键盘 Hook、不依赖 SendInput
适用范围 任意 Windows 桌面应用程序的输入框
目标用户 需要自动化文本输入的学生、办公人员、测试工程师

2. 功能需求

2.1 核心引擎（P0 — 必须实现）

编号 功能 描述
F-01 字符注入 通过 PostMessageW(WM_CHAR) 向目标窗口逐字符发送 Unicode 文本
F-02 特殊键支持 支持回车（VK_RETURN）、制表符（VK_TAB）等特殊按键
F-03 输入速度控制 可配置字符间隔（默认 10ms）和行间延迟（默认 50ms）
F-04 倒计时启动 输入前提供 5 秒倒计时，让用户切换至目标窗口
F-05 紧急停止 支持鼠标移至屏幕四角（GetCursorPos 角落检测，行为对齐 PyAutoGUI Failsafe）或 Ctrl+C 中断

2.2 CLI 模式（P0 — 必须实现）

编号 功能 描述
F-06 命令行参数 支持 --text、--file、--interval、--countdown 等参数
F-07 文件输入 从 .txt / .py / .java 等源代码文件读取待输入内容
F-08 实时状态 显示倒计时、当前行号、总进度

2.3 GUI 模式（P1 — 重要）

编号 功能 描述
F-09 文本编辑区 提供多行文本编辑框，支持直接粘贴或编辑待输入内容
F-10 参数面板 可视化调节字符间隔、行间延迟、倒计时秒数
F-11 启动/停止 提供「开始输入」按钮和紧急停止按钮
F-12 进度显示 实时显示输入进度和当前字符

2.4 配置管理（P1 — 重要）

编号 功能 描述
F-13 配置文件 支持 config.json 持久化用户偏好设置
F-14 多段文本 支持保存和管理多段常用文本，按名称快速调用
F-15 导入/导出 支持文本片段的 JSON 导入和导出

3. 非功能需求

3.1 兼容性

  • 操作系统：Windows 10 / 11（依赖 user32.dll）
  • 工具链：Rust 1.74+（stable-msvc）
  • 依赖最小化：GUI 用 eframe/egui，对话框用 rfd，序列化用 serde；Win32 API 全部手写 FFI 声明，不依赖 windows crate

3.2 性能

  • 字符间隔可低至 5ms，不丢字
  • 单次支持输入 10,000+ 字符不崩溃

3.3 可用性

  • 零安装使用：通过 GitHub Releases 提供独立 EXE（无运行时依赖）；源码模式一条命令 cargo run 启动
  • GUI 模式零配置：双击即可使用
  • CLI 模式支持脚本化调用

3.4 安全性

  • 不收集、不上传任何用户数据
  • 不修改系统设置
  • 不注入其他进程内存（仅通过合法消息队列通信）

4. 技术架构

4.1 模块划分

AutoTyper/
├── src/
│   ├── main.rs                # 统一入口（--cli 开关）
│   ├── lib.rs                 # 库根（平台门禁、版本号）
│   ├── win32.rs               # Win32 FFI 声明
│   ├── engine.rs              # 输入引擎：PostMessageW 封装
│   ├── cli.rs                 # CLI 入口
│   ├── gui.rs                 # GUI 界面（egui/eframe）
│   └── config.rs              # 配置文件管理
├── tests/                     # 端到端注入测试
├── docs/                      # 文档
├── legacy-python/             # v1.x Python 实现归档
├── Cargo.toml                 # 项目清单（版本号唯一来源）
└── config.example.json        # 配置模板（运行时生成 config.json）

4.2 核心调用链

用户启动 → main.rs
            ├── --cli → cli.rs → engine.rs → win32.rs::PostMessageW
            └── 默认  → gui.rs → engine.rs → win32.rs::PostMessageW

4.3 关键技术决策

决策点 选择 理由
实现语言 Rust（v2.0 起，替代 Python） 零运行时依赖、单文件小体积 EXE、原生并发安全；原实现归档保留
输入方式 PostMessageW(WM_CHAR) 绕过剪贴板和键盘事件拦截
Win32 绑定 手写 FFI（不用 windows crate） API 面极小（十余个函数），避免依赖体积与版本漂移
GUI 框架 egui / eframe 纯 Rust、即时模式、高 DPI 原生支持
配置格式 JSON（serde，保持键序） 人类可读，与 v1.x config.json 完全兼容
打包方式 cargo build --release（GitHub Actions 自动构建） 推送版本标签即发布独立 .exe 到 GitHub Releases，仓库不含二进制

5. 项目里程碑

阶段 内容 交付物
M1 项目初始化 + 核心引擎 engine.py + 可运行 demo
M2 CLI 模式 cli/main.py + 命令行参数
M3 GUI 模式 gui/app.py + tkinter 界面
M4 配置管理 config/manager.py + config.json
M5 测试 + 文档 单元测试 + README + SPEC
M6 Rust 重写（v2.0） src/*.rs 全模块 + 端到端注入测试 + CI 切换 cargo

6. 风险与限制

风险 影响 缓解措施
部分应用拦截 WM_CHAR 输入无效 尚未实现备选方案；如有需求可扩展 SendInput 路径（见风险登记，非当前范围）
高 DPI 缩放导致窗口定位偏移 输入到错误窗口 提示用户手动确认焦点窗口
输入速度过快导致丢字 内容不完整 提供速度调节，推荐 ≥10ms