v0.6.2 — 双端适配（engines.dsh）

双端适配：显式声明 DSH 兼容范围。

Changed

• package.json 新增 engines.dsh >=0.1.2-rc.1（单边开区间、不设上界），版本 0.6.1 → 0.6.2
• README 新增「DSH 兼容性」一节，记录两个生产 profile 上的实测结论

Notes

• peer 保持 * —— 只依赖 cordis 与 dsh-tools，不锁定宿主版本

v0.5.1

release: v0.5.1 — 改名 sage-guikit -> dsh-guikit

• 包名与 cordis.patch.yml 的 id / name、lib/index.js 的 export const name 同步跟进
  （三者不一致会崩在 readiness 之前）
• 环境变量 SAGE_GUIKIT_DIR -> DSH_GUIKIT_DIR，缓存目录 %TEMP%\dsh-guikit
  （breaking change，缓存可再生、无数据损失）
• keywords 补 dsh-plugin / deepseek / cordis / computer-use / uiautomation 等
• 脱敏：清 README 与 NOTICE 的真名署名、CHANGELOG 的开发机绝对路径
• .gitignore 忽略未发布的设计稿，避免误提交

v0.5.0 之后的提交

• 5e97fe5 release: v0.5.1 — 改名 sage-guikit -> dsh-guikit

本 Release 为补齐历史补建 —— 该版本发布时未打 tag。

v0.6.1 — 文档：scale 语义与混合缩放限制

0.6.1 只改文档，lib/index.js 与 0.6.0 逐字节相同（SHA256 C9C56D7A…）。发它只有一个原因：把一条容易被误判的边界写清楚，免得别人把正常行为当成 bug 去改。

README「已知边界」里那条 DPI 说明原来只写了 scale > 1（DPI-unaware 应用的情形），漏了另一半：DPI-aware 的应用跑在「缩放百分比与主屏不同」的显示器上时，scale 会小于 1。实测这台机器主屏 175% + 副屏 200% ⇒ 168/192 = 0.875。现在三种取值（= 1 / > 1 / < 1）连同各自的成因、现象与用法一次写清。

顺带记了一条新的限制：混合缩放下 gui_window_shot 的图不完整——位图画布按虚拟桌面坐标空间分配，而 PrintWindow 按窗口自身像素渲染内容。scale < 1 时内容比画布大、右下被裁（实测少了整条底部播放条）；scale > 1 时右/下多出纯黑边。这只影响「图里能看到多少」，不影响坐标正确性。

还有一段自曝：我一度认定 scale 的算法有 bug 并改了它，随后用「黑边测量 + 高亮条目像素检测 + 两次点击对照」把自己证伪——原公式是对的，改动会给 DPI-aware 窗口引入 12.5%~14% 的系统性点偏，已完整回滚。这条纠错也进了 CHANGELOG。想彻底避开混合缩放的麻烦，把各显示器设成同一个缩放百分比就行。

v0.6.0 — 坐标契约 + UIA 五态 + gui_locate

0.6.0 的主线不是加功能，是把三套坐标空间收敛成一条可自证的契约，并把「看图猜坐标」这个环节整体删掉。

gui_uia：walker 从 ControlViewWalker 换成 RawViewWalker，depth 默认 10 → 40，max 默认 300 → 2000（硬顶 8000），新增返回预算 maxRows（默认 120）。这两个 walker 的 depth 预算并不等价——RawView 的中间层把真实内容推深（本机同一窗口 RawView@10 只有 14 个元素，@40 才 1500+），所以只换 walker 不提 depth 会比 0.5.x 更差。状态从「查不到就回 0 条」改成五态：found / empty-but-accessible / not-exposed / inconclusive / truncated；只有 empty-but-accessible 能读成「确实没有」。

坐标契约：gui_screen 每屏回带 physical_rect / logical_rect / dpi_scale / is_primary / display_id，顶层加 virtual_desktop_origin / space；gui_screenshot 与 gui_window_shot 回带 space / origin / scale / image_px，标注图里烧进标尺与左下角水印。

新增第 13 个工具 gui_locate：给 name（+ 可选 window / title / elType / index）直接回可喂给 gui_click 的虚拟桌面物理坐标。七态，只有 found 给顶层 point；多命中回 ambiguous + candidates[]，元素离屏时回 offscreen 且不给坐标。

gui_click / gui_drag：新增 window 与 space=window-local，回执带 origin / scale / requested / absolute / insideWindow / target；gui_click 可选 verify 自校验，delivery.verified 只在判定 satisfied 时为 true。

已知限制留到 0.6.1：annotate 在大区域会自动粗化 step 且回执不自报实际值；未知参数被静默忽略。

v0.5.0

feat(0.5.0): gui_verify semantic verification + honest delivery receipts

Borrowed two things from cua-driver (DSH's official experimental computer-use plugin):

1. gui_verify - one predicate (element exists / enabled / valueEquals, or window
   exists / bounds) polled until stableSamples consecutive checks agree, returning
   satisfied | unsatisfied | unknown. unknown means undecidable (target window
   absent, UIA walk not exhaustive) and must never be read as success. Absence is
   not provable, so exists:false is rejected.

2. delivery:{sent:true,verified:false} on all input tools (click/drag/type/key/scroll).
   Input reaching the OS is not evidence the target reacted; 2026-09-25 we hit a
   click reporting ok while the UI did not move at all.

gui_click also echoes requested:{x,y} next to the landed x,y.

Verified: 12 tools register; 5 pwsh probe cases behave (hit=satisfied,
missing=unknown, wrong bounds=unsatisfied with exact delta); delivery appears on
input tools only; 4 argument guards reject correctly.

v0.4.0 之后的提交

• baf76a6 feat(0.5.0): gui_verify semantic verification + honest delivery receipts
• 067bced chore: snapshot 0.4.0 work (gui_window_shot, gui_drag, annotate grid) before adding verification tooling

本 Release 为补齐历史补建。

v0.4.0

release: v0.4.0 — MIT 换 Apache-2.0，加 NOTICE

代码一行未改（lib/index.js 与 cordis.patch.yml 的 hash 与 0.3.0 相同），功能完全一致。换协议的理由是 Apache-2.0 第 3 条给专利授权、第 4(d) 条要求 NOTICE 随下游分发保留——后者 MIT 没有，别人 fork 走可以把署名合法删掉。

配套：LICENSE 换 Apache-2.0 全文；新增 NOTICE（Copyright 2026 Bowen Zheng (gezi-wen)）；package.json 的 license 字段改为 Apache-2.0，files 白名单加 NOTICE（不加就不会进 npm 包）。

v0.3.0 之后的提交

• 896327c release: v0.4.0 — MIT 换 Apache-2.0，加 NOTICE
• d5282b2 chore: sync pnpm-lock with the devDependencies removal
• 906ee06 chore: drop @deepseek-ai/* devDependencies so pnpm install cannot shadow the junction bridge

本 Release 为补齐历史补建。

v0.3.0 — gui_drag + gui_window_shot

新增两个工具：

• gui_drag —— 按住拖动：选文字、拖窗口标题栏、拉滑块滚动条、拖放。移动是插值发出的 SendInput 绝对坐标（VIRTUALDESK，多屏负坐标安全），只调 SetCursorPos 不产生拖拽事件、多数程序不认。try/finally 保证无论成败都松开按键。
• gui_window_shot —— 单窗口截图：走 PrintWindow，窗口被别的窗口盖住也照样抓到它自己的内容，而且不激活、不移动任何东西。返回 x/y 原点与 scale（DPI-unaware 窗口的换算系数）。实测 2584×1464 的窗口图 298 KB，整屏那张 8.8 MB。

另外修了一个缓存坑：DLL 编译缓存原先用固定版本号，加了新方法后会加载到缺方法的旧 DLL；现在文件名取自 C# 源码内容哈希，源码一改自动重编。

还有一个非显然的约束写进 README 了：窗口截图不能塞进 gui_screenshot 的脚本里——「按标题找窗口 + GetWindowRect + PrintWindow + 画网格」凑成胖脚本会被 Windows Defender 经 AMSI 判为恶意脚本直接拒绝执行（稳定复现），拆成独立工具并压瘦脚本后不再触发。

⚠️ 撤销了 0.2.2 对 peer 范围的收紧，@deepseek-ai/dsh-tools 回到 *：插件目录用 junction 桥时 peer 由 DSH 闭包提供，写死范围反而挡住闭包版本。

v0.2.2 — 首次发布

Windows 桌面控制工具集，给 DeepSeek Harness（DSH）的 agent 装上眼睛和手：看屏幕、点鼠标、打字、按快捷键、滚动、等生效、管窗口，并能对标准控件做 Windows UI Automation 结构化定位。9 个工具，零外部依赖——无常驻服务、无 Python、无 API key。

首次发布（npm + GitHub）

• 修复：中文界面文本回传乱码。子进程没有控制台时 .NET 的 [Console]::OutputEncoding 回退到系统 ANSI 代码页（中文 Windows = gb2312），PowerShell 于是把 GBK 字节写进 stdout，宿主按 UTF-8 解码后 UIA 元素名与窗口标题里的中文全部变 U+FFFD（ASCII 部分正常，所以很隐蔽）。现在 PRELUDE 第一句把 stdout 钉死为 UTF-8。
• 修复：去掉硬编码的本机路径，截图与编译缓存目录改为 %TEMP%\sage-guikit，可用 SAGE_GUIKIT_DIR 覆盖。
• 收紧 @deepseek-ai/dsh-tools peer 范围到 >=0.1.0-rc.1（* 会解析到 latest 标签上的 0.0.1-rc.1）。

安装：pnpm add sage-guikit，在 profile 的 dsh.profile.bundles 里加上 sage-guikit，重启 dsh web。

v0.2.1

release: v0.2.1 — 首次发布（GitHub + npm）

fix: 子进程 stdout 在 PRELUDE 第一句钉死 UTF-8。无控制台 spawn 时 .NET 的 [Console]::OutputEncoding 回退到系统 ANSI 代码页（中文 Windows = gb2312），PowerShell 于是把 GBK 字节写进 stdout、宿主按 UTF-8 解码，导致 UIA 元素名与窗口标题里的中文全部变 U+FFFD（ASCII 部分正常，所以一直没暴露）。

fix: 去掉硬编码的 E:\workspace\sage-gui / E:\workspace——截图与编译缓存目录改为 %TEMP%\sage-guikit，可用 SAGE_GUIKIT_DIR 覆盖；子进程 cwd 同步跟随（cwd 不存在会让 spawn 直接 ENOENT）。

docs: README 重写为可发布版（安装 / 9 工具表 / 三层精度栈 / 已知边界 / 定位），补 CHANGELOG 与 MIT LICENSE。

chore: package.json 补 engines / repository / homepage / bugs 与 devDependencies；smoke 挂具加截图用例；pnpm-workspace 允许自动装 peer（裸导入要解析 dsh-tools 的传递依赖）。

v0.2.0 之后的提交

• 16b314c release: v0.2.1 — 首次发布（GitHub + npm）
• da3f974 chore: bump DSH peer deps to 0.1.2-rc.1; drop dsh-client-runtime (removed in 0.1.2)
• 48b47ac docs: record two runtime pitfalls from first real-app session (DPI-unaware foreground, lock-screen silent failure)
• 8f8d74b fix: tool body joins used literal \n instead of newline (static port slip); add smoke.mjs harness
• a8b9147 docs: README for v0.2.0 (precision stack, 9 tools, pitfalls)

本 Release 为补齐历史补建。