snapstep 0.2.0__tar.gz

snapstep-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felixssss-106
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snapstep-0.2.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: snapstep
+Version: 0.2.0
+Summary: 录屏自动生成图文教程 / Record your screen, get a step-by-step guide with screenshots — automatically.
+Author: Felixssss-106
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Felixssss-106/snapstep
+Project-URL: Issues, https://github.com/Felixssss-106/snapstep/issues
+Keywords: screenshot,documentation,scribe,sop,tutorial,screen-recording,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Classifier: Topic :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pynput>=1.7
+Requires-Dist: mss>=9.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-docx>=1.1
+Requires-Dist: PySide6>=6.6
+Requires-Dist: uiautomation>=2.0; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyinstaller>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# SnapStep 📸
+
+**按一次快捷键，把你的操作变成图文教程。**
+Record your screen, get a step-by-step guide — automatically.
+
+[![Test](https://github.com/Felixssss-106/snapstep/actions/workflows/test.yml/badge.svg)](https://github.com/Felixssss-106/snapstep/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+![SnapStep 演示：录屏自动生成图文教程](docs/demo.gif)
+
+| 生成的 HTML 教程 | 导出的 Markdown |
+|---|---|
+| ![HTML 教程](docs/screenshots/guide-html.png) | ![Markdown 成品](docs/screenshots/guide-md.png) |
+
+SnapStep 在后台监听你的鼠标和键盘：每次点击自动截图并标记位置，输入的文本自动记录。
+停止录制后，一份带序号截图的图文教程就生成好了 —— 支持 **Markdown / HTML / Word**，
+可选接入大模型把文案写得更自然。**开源版 Scribe / Tango 平替，数据完全保存在本地。**
+
+---
+
+## ✨ 特性
+
+- **一键录制**：系统托盘常驻，全局快捷键（默认 `Ctrl+Alt+S`）随时开始/停止
+- **自动截屏标注**：点击处自动画高亮圈 + 步骤序号，输入的文本自动记进步骤里
+- **三种导出**：Markdown（贴 wiki/仓库）、HTML（单文件内嵌截图，直接发人）、Word（正式文档）
+- **AI 文案（可选）**：填一个 OpenAI 兼容 API 即可让大模型写标题和步骤描述，
+  预设支持 GLM / DeepSeek / OpenAI，本地模型（Ollama / LM Studio）也行
+- **零配置可用**：不配 AI 也能用，本地模板自动生成每步文案
+- **隐私优先**：本机处理，无任何遥测；隐私模式一键停止截屏；密码框输入自动隐藏（尽力检测）
+
+## 📦 安装
+
+**Windows（推荐）**：从 [Releases](https://github.com/Felixssss-106/snapstep/releases) 下载 `SnapStep.exe`，双击即用。
+
+**pip**：
+
+```bash
+pip install snapstep        # PyPI 正式包
+pip install git+https://github.com/Felixssss-106/snapstep.git   # 或直接从源码安装
+snapstep          # 启动托盘 GUI
+```
+
+**从源码**：
+
+```bash
+git clone https://github.com/Felixssss-106/snapstep.git
+cd snapstep
+pip install -e ".[dev]"
+pytest            # 跑测试
+```
+
+## 🚀 快速开始
+
+### 托盘 GUI（默认）
+
+启动后托盘出现图标：
+
+1. 按 `Ctrl+Alt+S`（或托盘菜单「开始录制」）
+2. 像平常一样操作 —— 每次左键点击自动成为一步
+3. 再按 `Ctrl+Alt+S` 停止，教程自动导出并弹窗提示
+
+右键托盘图标可打开会话文件夹、重新导出、修改设置。
+
+### 命令行
+
+```bash
+snapstep record                     # 录制，回车结束，自动导出
+snapstep record --format md --no-ai # 指定格式、跳过 AI
+snapstep export ~/.snapstep/sessions/20260912-101010 -f all   # 导出已有会话
+snapstep config set api.base_url https://api.deepseek.com/v1  # 命令行改配置
+snapstep demo                       # 不录制，直接生成一份示例教程验证安装
+```
+
+## 🤖 AI 文案配置
+
+设置界面选预设填 API Key 即可；也可命令行：
+
+```bash
+snapstep config set api.base_url https://open.bigmodel.cn/api/paas/v4
+snapstep config set api.model glm-4-flash
+snapstep config set api.api_key 你的key
+```
+
+| 预设 | Base URL | 模型示例 |
+|---|---|---|
+| GLM 智谱 | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` |
+| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
+| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
+| 本地模型 | `http://127.0.0.1:11434/v1` | Ollama / LM Studio 任意模型 |
+
+不配置或调用失败时自动退回本地模板文案，**教程永远能生成**。
+
+## 🔒 隐私设计
+
+- 截图、文案、导出全部在本机完成；只有你主动配置了 AI 才会把**操作文字摘要**发给该 API
+- 「隐私模式」：完全不截屏，只记录步骤文字
+- 「密码隐藏」：通过 Windows UI Automation 尽力识别密码框，其中的键入以 `••••` 代替
+- API 端点仅允许 http/https，并阻止云元数据地址与重定向，防止密钥被转发
+- 配置与数据都在 `~/.snapstep/`，删掉目录即彻底清除
+
+## 🆚 与在线 SaaS 工具对比
+
+| | SnapStep | Scribe / Tango |
+|---|---|---|
+| 价格 | 免费开源（MIT） | 免费档限步数，完整功能按席位付费 |
+| 数据 | 全程本机 | 操作录屏上传云端 |
+| 离线 | 完全可用（无 AI 模式） | 不可用 |
+| 导出 | Markdown / HTML / Word | 受付费档限制 |
+| AI | 自带 key，任意 OpenAI 兼容模型 | 内置不可换 |
+| 平台 | Windows（macOS 在路线图） | 浏览器扩展 |
+
+## 🗺 Roadmap
+
+- [ ] 录屏讲解语音 → 自动转写进步骤文案（ASR）
+- [ ] AI 视觉模型读懂截图，写出更准确的按钮/控件描述
+- [ ] 敏感信息智能打码（手机号/邮箱/头像区域）
+- [ ] PDF 导出、团队模板
+- [ ] macOS 支持
+
+## 注意：软件可能存在问题
+V0.1.0版本已知问题：快捷键无法使用，截屏延迟不合适，v0.2.0已修复（v0.1.0已废弃）；
+自动过滤无效点击功能可能会漏记录，目前正在修复
+
+欢迎按 [issues](https://github.com/Felixssss-106/snapstep/issues) 提需求。
+
+## 🧪 开发
+
+```bash
+pip install -e ".[dev]"
+pytest                       # 测试
+ruff check src tests scripts # lint
+python scripts/make_icon.py  # 重新生成图标
+pyinstaller snapstep.spec    # 本地打包 exe
+```
+
+架构速览：`recorder.py`（pynput 钩子 + 事件聚合）→ `capture.py`（mss 截屏 + Pillow 标注）
+→ `writer.py`（AI/模板双路文案）→ `export/`（md/html/docx）。核心逻辑不依赖输入钩子，纯逻辑可单测。
+
+## 🤝 贡献
+
+Issue / PR 都欢迎。提交前请跑通 `pytest` 和 `ruff check`。
+
+## License
+
+[MIT](LICENSE)
+See the Chinese sections above for full docs — the UI is Chinese-first,
+and English UI is on the roadmap. English issues/PRs are welcome!

snapstep-0.2.0/README.md

@@ -0,0 +1,148 @@
+# SnapStep 📸
+
+**按一次快捷键，把你的操作变成图文教程。**
+Record your screen, get a step-by-step guide — automatically.
+
+[![Test](https://github.com/Felixssss-106/snapstep/actions/workflows/test.yml/badge.svg)](https://github.com/Felixssss-106/snapstep/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+![SnapStep 演示：录屏自动生成图文教程](docs/demo.gif)
+
+| 生成的 HTML 教程 | 导出的 Markdown |
+|---|---|
+| ![HTML 教程](docs/screenshots/guide-html.png) | ![Markdown 成品](docs/screenshots/guide-md.png) |
+
+SnapStep 在后台监听你的鼠标和键盘：每次点击自动截图并标记位置，输入的文本自动记录。
+停止录制后，一份带序号截图的图文教程就生成好了 —— 支持 **Markdown / HTML / Word**，
+可选接入大模型把文案写得更自然。**开源版 Scribe / Tango 平替，数据完全保存在本地。**
+
+---
+
+## ✨ 特性
+
+- **一键录制**：系统托盘常驻，全局快捷键（默认 `Ctrl+Alt+S`）随时开始/停止
+- **自动截屏标注**：点击处自动画高亮圈 + 步骤序号，输入的文本自动记进步骤里
+- **三种导出**：Markdown（贴 wiki/仓库）、HTML（单文件内嵌截图，直接发人）、Word（正式文档）
+- **AI 文案（可选）**：填一个 OpenAI 兼容 API 即可让大模型写标题和步骤描述，
+  预设支持 GLM / DeepSeek / OpenAI，本地模型（Ollama / LM Studio）也行
+- **零配置可用**：不配 AI 也能用，本地模板自动生成每步文案
+- **隐私优先**：本机处理，无任何遥测；隐私模式一键停止截屏；密码框输入自动隐藏（尽力检测）
+
+## 📦 安装
+
+**Windows（推荐）**：从 [Releases](https://github.com/Felixssss-106/snapstep/releases) 下载 `SnapStep.exe`，双击即用。
+
+**pip**：
+
+```bash
+pip install snapstep        # PyPI 正式包
+pip install git+https://github.com/Felixssss-106/snapstep.git   # 或直接从源码安装
+snapstep          # 启动托盘 GUI
+```
+
+**从源码**：
+
+```bash
+git clone https://github.com/Felixssss-106/snapstep.git
+cd snapstep
+pip install -e ".[dev]"
+pytest            # 跑测试
+```
+
+## 🚀 快速开始
+
+### 托盘 GUI（默认）
+
+启动后托盘出现图标：
+
+1. 按 `Ctrl+Alt+S`（或托盘菜单「开始录制」）
+2. 像平常一样操作 —— 每次左键点击自动成为一步
+3. 再按 `Ctrl+Alt+S` 停止，教程自动导出并弹窗提示
+
+右键托盘图标可打开会话文件夹、重新导出、修改设置。
+
+### 命令行
+
+```bash
+snapstep record                     # 录制，回车结束，自动导出
+snapstep record --format md --no-ai # 指定格式、跳过 AI
+snapstep export ~/.snapstep/sessions/20260912-101010 -f all   # 导出已有会话
+snapstep config set api.base_url https://api.deepseek.com/v1  # 命令行改配置
+snapstep demo                       # 不录制，直接生成一份示例教程验证安装
+```
+
+## 🤖 AI 文案配置
+
+设置界面选预设填 API Key 即可；也可命令行：
+
+```bash
+snapstep config set api.base_url https://open.bigmodel.cn/api/paas/v4
+snapstep config set api.model glm-4-flash
+snapstep config set api.api_key 你的key
+```
+
+| 预设 | Base URL | 模型示例 |
+|---|---|---|
+| GLM 智谱 | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` |
+| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
+| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
+| 本地模型 | `http://127.0.0.1:11434/v1` | Ollama / LM Studio 任意模型 |
+
+不配置或调用失败时自动退回本地模板文案，**教程永远能生成**。
+
+## 🔒 隐私设计
+
+- 截图、文案、导出全部在本机完成；只有你主动配置了 AI 才会把**操作文字摘要**发给该 API
+- 「隐私模式」：完全不截屏，只记录步骤文字
+- 「密码隐藏」：通过 Windows UI Automation 尽力识别密码框，其中的键入以 `••••` 代替
+- API 端点仅允许 http/https，并阻止云元数据地址与重定向，防止密钥被转发
+- 配置与数据都在 `~/.snapstep/`，删掉目录即彻底清除
+
+## 🆚 与在线 SaaS 工具对比
+
+| | SnapStep | Scribe / Tango |
+|---|---|---|
+| 价格 | 免费开源（MIT） | 免费档限步数，完整功能按席位付费 |
+| 数据 | 全程本机 | 操作录屏上传云端 |
+| 离线 | 完全可用（无 AI 模式） | 不可用 |
+| 导出 | Markdown / HTML / Word | 受付费档限制 |
+| AI | 自带 key，任意 OpenAI 兼容模型 | 内置不可换 |
+| 平台 | Windows（macOS 在路线图） | 浏览器扩展 |
+
+## 🗺 Roadmap
+
+- [ ] 录屏讲解语音 → 自动转写进步骤文案（ASR）
+- [ ] AI 视觉模型读懂截图，写出更准确的按钮/控件描述
+- [ ] 敏感信息智能打码（手机号/邮箱/头像区域）
+- [ ] PDF 导出、团队模板
+- [ ] macOS 支持
+
+## 注意：软件可能存在问题
+V0.1.0版本已知问题：快捷键无法使用，截屏延迟不合适，v0.2.0已修复（v0.1.0已废弃）；
+自动过滤无效点击功能可能会漏记录，目前正在修复
+
+欢迎按 [issues](https://github.com/Felixssss-106/snapstep/issues) 提需求。
+
+## 🧪 开发
+
+```bash
+pip install -e ".[dev]"
+pytest                       # 测试
+ruff check src tests scripts # lint
+python scripts/make_icon.py  # 重新生成图标
+pyinstaller snapstep.spec    # 本地打包 exe
+```
+
+架构速览：`recorder.py`（pynput 钩子 + 事件聚合）→ `capture.py`（mss 截屏 + Pillow 标注）
+→ `writer.py`（AI/模板双路文案）→ `export/`（md/html/docx）。核心逻辑不依赖输入钩子，纯逻辑可单测。
+
+## 🤝 贡献
+
+Issue / PR 都欢迎。提交前请跑通 `pytest` 和 `ruff check`。
+
+## License
+
+[MIT](LICENSE)
+See the Chinese sections above for full docs — the UI is Chinese-first,
+and English UI is on the roadmap. English issues/PRs are welcome!

snapstep-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snapstep"
+version = "0.2.0"
+description = "录屏自动生成图文教程 / Record your screen, get a step-by-step guide with screenshots — automatically."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Felixssss-106" }]
+keywords = [
+    "screenshot",
+    "documentation",
+    "scribe",
+    "sop",
+    "tutorial",
+    "screen-recording",
+    "ai",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics :: Capture :: Screen Capture",
+    "Topic :: Documentation",
+]
+dependencies = [
+    "pynput>=1.7",
+    "mss>=9.0",
+    "pillow>=10.0",
+    "jinja2>=3.1",
+    "python-docx>=1.1",
+    "PySide6>=6.6",
+    "uiautomation>=2.0; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pyinstaller>=6.0", "ruff>=0.6"]
+
+[project.scripts]
+snapstep = "snapstep.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Felixssss-106/snapstep"
+Issues = "https://github.com/Felixssss-106/snapstep/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+snapstep = ["resources/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

snapstep-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snapstep-0.2.0/src/snapstep/__init__.py

@@ -0,0 +1,3 @@
+"""SnapStep — 录屏自动生成图文教程。"""
+
+__version__ = "0.2.0"

snapstep-0.2.0/src/snapstep/__main__.py

@@ -0,0 +1,6 @@
+"""python -m snapstep 入口。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

snapstep-0.2.0/src/snapstep/capture.py

@@ -0,0 +1,161 @@
+"""屏幕截图与步骤标注。
+
+导入本模块只需 Pillow；mss 延迟到真正截屏时才加载，
+保证导出器/测试在没有屏幕的环境里也能工作。
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+# 点击高亮圈颜色（快照红）
+ACCENT = (245, 63, 63)
+
+
+class ScreenCapture:
+    """基于 mss 的截屏器。线程注意：mss 实例不跨线程，按线程懒加载。"""
+
+    def __init__(self) -> None:
+        self._sct = None
+
+    def _client(self):
+        if self._sct is None:
+            import mss
+
+            self._sct = mss.mss()
+        return self._sct
+
+    def monitor_for_point(self, x: int, y: int) -> dict:
+        """返回包含该点显示器的 mss monitor 字典；找不到时退回主显示器。"""
+        monitors = self._client().monitors
+        for mon in monitors[1:]:
+            if (
+                mon["left"] <= x < mon["left"] + mon["width"]
+                and mon["top"] <= y < mon["top"] + mon["height"]
+            ):
+                return dict(mon)
+        return dict(monitors[1] if len(monitors) > 1 else monitors[0])
+
+    def capture_point(self, x: int, y: int) -> tuple[Image.Image, dict]:
+        """截取包含 (x, y) 的显示器，返回 (PIL 图像, monitor 字典)。"""
+        mon = self.monitor_for_point(x, y)
+        shot = self._client().grab(mon)
+        img = Image.frombytes("RGB", shot.size, shot.bgra, "raw", "BGRX")
+        return img, mon
+
+
+def save_screenshot(
+    img: Image.Image,
+    session_dir: Path,
+    index: int,
+    image_format: str = "png",
+    suffix: str = "",
+) -> str:
+    """保存原始截图，返回相对 session 目录的 POSIX 风格路径。
+
+    suffix 用于区分同一步骤的候选帧（如 "-imm" / "-set"）。
+    """
+    images_dir = session_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    path = images_dir / f"step-{index:02d}{suffix}.{image_format}"
+    img.save(path)
+    return path.relative_to(session_dir).as_posix()
+
+
+# 图片相似度：缩到 96x54 灰度后逐像素求平均绝对差（0~255）。
+# < 2.0 视为「画面没变」，> 4.0 视为「明显变化」。
+_SIMILARITY_SIZE = (96, 54)
+
+
+def mean_diff(a: Path | Image.Image, b: Path | Image.Image) -> float:
+    """两张截图的平均像素差（0~255），越小越相似。"""
+    pa = a if isinstance(a, Image.Image) else Image.open(a)
+    pb = b if isinstance(b, Image.Image) else Image.open(b)
+    ga = pa.convert("L").resize(_SIMILARITY_SIZE)
+    gb = pb.convert("L").resize(_SIMILARITY_SIZE)
+    da = list(ga.getdata())
+    db = list(gb.getdata())
+    total = sum(abs(x - y) for x, y in zip(da, db, strict=True))
+    return total / len(da)
+
+
+def settle_grab(
+    capture: ScreenCapture,
+    monitor: dict,
+    max_wait_ms: int,
+    poll_ms: int = 150,
+    stable_diff: float = 1.5,
+) -> tuple[Image.Image, int]:
+    """轮询截屏直到画面连续两帧几乎不变（界面稳定），或超时。
+
+    返回 (稳定帧图像, 实际等待毫秒数)。
+    """
+    deadline = time.monotonic() + max(max_wait_ms, 0) / 1000
+    last = capture.grab_monitor(monitor)
+    waited = 0
+    while True:
+        if time.monotonic() >= deadline:
+            return last, waited
+        time.sleep(poll_ms / 1000)
+        waited += poll_ms
+        current = capture.grab_monitor(monitor)
+        if mean_diff(last, current) < stable_diff:
+            return current, waited
+        last = current
+
+
+def _load_font(size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    for name in ("msyh.ttc", "arial.ttf"):  # 优先微软雅黑，回退 Arial
+        try:
+            return ImageFont.truetype(name, size)
+        except OSError:
+            continue
+    return ImageFont.load_default()
+
+
+def annotate(
+    img: Image.Image, rel_x: float, rel_y: float, number: int, radius: int = 28
+) -> Image.Image:
+    """在截图上标注点击位置：红色高亮圈 + 序号徽章，返回新图。"""
+    out = img.convert("RGBA")
+    overlay = Image.new("RGBA", out.size, (0, 0, 0, 0))
+    d = ImageDraw.Draw(overlay)
+
+    cx, cy = rel_x * out.width, rel_y * out.height
+    ring_w = max(3, out.width // 450)
+    # 外圈柔光 + 内圈实线
+    d.ellipse(
+        [cx - radius - 8, cy - radius - 8, cx + radius + 8, cy + radius + 8],
+        outline=ACCENT + (80,),
+        width=ring_w + 3,
+    )
+    d.ellipse(
+        [cx - radius, cy - radius, cx + radius, cy + radius],
+        outline=ACCENT + (255,),
+        width=ring_w,
+    )
+
+    # 序号徽章放在圈右上，越界时往里收
+    badge_r = max(14, int(radius * 0.62))
+    bx = min(max(cx + radius + 6, badge_r), out.width - badge_r - 2)
+    by = max(min(cy - radius - 6, out.height - badge_r - 2), badge_r + 2)
+    d.ellipse(
+        [bx - badge_r, by - badge_r, bx + badge_r, by + badge_r],
+        fill=ACCENT + (235,),
+    )
+    out = Image.alpha_composite(out, overlay)
+
+    dd = ImageDraw.Draw(out)
+    text = str(number)
+    font = _load_font(badge_r * 2 - 4)
+    left, top, right, bottom = dd.textbbox((0, 0), text, font=font)
+    dd.text(
+        (bx - (right - left) / 2 - left, by - (bottom - top) / 2 - top),
+        text,
+        font=font,
+        fill=(255, 255, 255, 255),
+    )
+    return out.convert("RGB")