前言¶
給軟件寫使用手冊、操作說明或流程文檔時，常見做法是在截圖上手工畫框、標序號、寫說明。框的位置一旦和真實控件對不齊，讀者會誤解點擊區域；改分辨率或換主題後，舊圖往往要整張重畫。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 插件頁。
