前言¶
给软件写使用手册、操作说明或流程文档时，常见做法是在截图上手工画框、标序号、写说明。框的位置一旦和真实控件对不齐，读者会误解点击区域；改分辨率或换主题后，旧图往往要整张重画。DeepSeek Harness（DSH）社区里有一类「工作流」插件，把「量坐标 → 出图 → 验图」串成可重复执行的步骤。下面介绍维护者 HtO404 发布的 screenshotpro：它强调矩形来自测量而非手调，渲染结果还要通过固定断言集，失败则非零退出。
这是什么¶
Screenshot Pro（npm 包名 screenshotpro，GitHub：HtO404/screenshotpro）的定位是：带标注的 UI 截图，坐标来自实测，而不是手绘估计。
仓库同时提供两种形态，彼此不依赖：
| 形态 | 内容 | 是否需要 DSH |
|---|---|---|
| 独立 CLI | tools/render.py、tools/verify.py（Windows 上还有 tools/measure_win.py） |
否，需 Python 3.9+ 与 Pillow |
| DSH 插件包 | 名为 Screenshot Pro 的 Agent 预设，挂载本仓库 skill 与所需工具 |
是，任意 DSH 宿主 |
插件在 SkillHub 目录页分类为「工作流」：hto404/screenshotpro。
核心设计：坐标只测量，不估计¶
仓库贯穿一条规则：
Coordinates are measured, never estimated.
Windows 桌面场景下：你提供可执行文件，工具启动应用，用 PrintWindow 抓整窗，并导出完整 UI Automation 控件树；spec.json 只描述指向哪个控件（例如 automation_id），不写像素坐标。渲染器根据 dump 生成框体、数字徽章、箭头、像素化遮罩和底部图例；验证器用 15 项断言检查报告与 dump、PNG 是否一致，任一失败则退出码非 0。
公开网页 demo（Wikipedia、MDN）则矩形来自 live DOM 的 getBoundingClientRect，spec.json 里同样没有手填坐标。断言 3 会逐字段对照 dump；断言 8 会在框落在空白像素时失败——这正是「猜坐标」时容易出现的情况。
图上的能力包括：带 padding 的高亮框、编号圆形徽章（避免碰撞且尽量不盖住控件）、从徽章到框边的箭头、对实测矩形做 pixelate 打码，以及在截图下方追加自适应高度的图例条（画布宽度与输入截图一致，说明文字放在图例里，避免盖住正文）。
流水线阶段¶
| 阶段 | 独立命令 | 读 | 写 | 约定摘要 |
|---|---|---|---|---|
| Measure | python tools/measure_win.py --exe <app.exe> --out figures/<name> |
运行中的应用（UI Automation） | shot.png、dump.json、measure-log.txt |
dump schema 为 uia-dump/1 等 |
| Annotate | python tools/render.py figures/<name>/spec.json |
spec.json、shot.png、dump.json |
out/<name>.png、out/render-report.json |
spec.schema = annot-spec/1，输出宽等于输入宽 |
| Verify | python tools/verify.py figures/<name>/spec.json |
spec、dump、report、渲染 PNG | PASS/FAIL 表 | 仅当 15/15 通过时 exit 0 |
| 自测 | python tests/run_tests.py |
内置合成 fixture | 临时目录中的 fixture 与图 | 15/15 PASS，并含故意失败用例 |
典型顺序：先 render.py，再 verify.py。
安装与启用（DSH 插件）¶
安装命令来自仓库 README（npm registry，当前 package 版本 1.0.1，许可证 MIT）：
pnpm add screenshotpro
在同一 DSH profile 目录（~/.dsh/profiles/<name>/）中：
- 在
package.json的dsh.profile.bundles中加入screenshotpro。 - 修改包内
cordis.patch.yml中 一行customSkillDirs：必须写成该包skills/目录的绝对路径。dsh-skill-filesystem会对数组里每一项做path.resolve()，相对路径会相对 DSH 宿主进程 cwd 解析，且不会展开占位符。
示例（路径需改成你本机实际位置）：
- id: skill-filesystem
name: '@deepseek-ai/dsh-skill-filesystem'
config:
customSkillDirs:
- '/home/me/screenshotpro/skills'
重启 DSH 后，目录中会出现 Screenshot Pro 预设与 screenshot-pro skill。包体是 Python 源码加 YAML patch，无需编译打包。
注意： 插件以当前 DSH 进程权限运行；安装前请自行查看源码与 MIT 许可证，确认可接受再启用。
典型用法¶
最小可复现闭环（无需真实应用与网络）¶
python tools/make_fixture.py /tmp/fx
python tools/render.py /tmp/fx/spec.json
python tools/verify.py /tmp/fx/spec.json
第三步应输出 15 行均为 [PASS]，并以 exit 0 结束（验证器会打印中文结果摘要，例如「15/15 断言通过 -> PASS」）。
spec.json 使用 schema annot-spec/1，通过 steps 里的 target（如 automation_id）和 label 描述标注步骤，可选 redact 做像素化，legend 控制底部图例。完整字段见仓库 README 的 spec 参考与 examples/minimal-spec.json。
仓库内网页 demo（离线可复现）¶
python tools/render.py demo/wikipedia/spec.json && python tools/verify.py demo/wikipedia/spec.json
python tools/render.py demo/mdn/spec.json && python tools/verify.py demo/mdn/spec.json
Wikipedia 示例含四步标注与账号区域打码；MDN 示例含三步标注与第三方广告条打码，并可选用 style.badge_avoid_dense_pixels（详见 demo/README.md）。
Windows 桌面应用¶
对真实 .exe 先测量再渲染、验证：
python tools/measure_win.py --exe <app.exe> --out figures/<name>
python tools/render.py figures/<name>/spec.json
python tools/verify.py figures/<name>/spec.json
测量与 measure_win.py 依赖 Windows 与 UI Automation；在 DSH 会话里由 Screenshot Pro 预设挂载的 skill 与工具，目的是在同一工作流里编排上述步骤，而不是替代 Python 环境依赖。
适用场景与限制¶
适合：需要可验证的 UI 说明图——使用手册、操作说明、流程文档、工具功能演示等；希望框、箭头、图例与实测控件一致，并能在 CI 或脚本里用 exit 码卡质量。
需知：measure_win.py 面向 Windows 可执行程序；网页 demo 走的是已提交的 shot/dump 与 DOM 测量流程，与 WinForms 等桌面路径不同。独立 CLI 不装 DSH 也能用；装 DSH 插件是为了在 Agent 预设里直接使用 skill 与配套工具。
SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系；选插件时以仓库 README 与源码为准。
结尾¶
Screenshot Pro 把「测量 → 标注渲染 → 15 项断言验证」做成一条可重复流水线，避免手调坐标带来的文档漂移。进一步细节、断言列表与 spec.json 字段说明见 GitHub 仓库（含 README.zh-CN.md）；目录入口见 SkillHub 插件页。
