dsh-spectacles 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# 变更记录
+
+人话版。每次发版都在这儿写一段：改了什么、为什么改、有没有坑。
+
+## V1.0.0 — 2026-11-09
+
+**这是第一个我们认它是 V1 的版本。** 下面那些 1.0.0 / 1.0.1 / 1.1.0 / 1.1.1 都是试验期的编号，实际只到 0.5 的水平——留着当历史，不再对外提。
+
+**能干的：**
+
+- 点右下角「戴上眼镜」，再点一个窗口，AI 的视野就收缩到那一个窗口；摘下就完全放开（这一版摘下之后读屏工具一律拒绝）。
+- 看的动作由**你下命令**触发——「看一眼」「看一分钟」「右上角那行红字读一下」。**戴上本身不会让 AI 去看**，它只是换了能看的地方。
+- 读的是窗口自己的内容（`PrintWindow`），所以**窗口被别的窗口挡住也能读到**，不用先翻到最前面。
+- 戴上以后，它的系统提示里会自动多一条规则：「只读这一个窗口：<标题>（W×H）」。想读别的窗口会被拒绝，先摘下重选。
+- 数字在前、文字其次：先给尺寸/区域/颜色/边界/差分，要文字走本机 OCR，只有要「看懂」小字时才裁一小块放大交给视觉。
+
+**为什么现在才算 V1：**
+之前几版的毛病是装了用不了——渲染层 id 对不上起不来、按钮被拖动壳吃掉点击、点窗口认不到。一个装好了却点不动的工具，不配叫 1.0。这一版在干净的 Windows 10 虚拟机上从零装了一遍、也是一路读到字的。
+
+**仍然不行的（下一轮）：**
+
+- 行块切分没做，整窗 OCR 还有错字：「未读」读成「耒读」、「V1.0.0」读成「VI 主0」、小数点变逗号。
+- 最小化的窗口、直接往 GPU 上画的窗口（部分游戏）读不到，会明确报错，不会给一张错的图。
+- 窗口被挡住时如果 `PrintWindow` 失败，目前会退回整屏裁块，可能把压在上面的窗口读进来——这个要改成明确报错。
+
+## 说明：以下编号属 0.5.x 试验版
+
+## 1.1.1 — 2026-11-09
+
+这一版只修「装了用不了」，没加任何新东西。
+
+**1. 装完之后客户端起不来？**
+在 DSH 0.2.2 上，渲染层认的是包名。我们旧代码里注册的 id 还是改名前的 `dsh-look`，宿主按 `dsh-spectacles` 去找，找不到就报「duplicate factory registration」、整页白掉。现在 id 改成 `dsh-spectacles`，和包名一致。
+
+**2. 装上以后按钮没反应。**
+按钮外面套着一层「可以拖着挪位置」的外壳。以前在按钮上按下鼠标，外壳也会立刻「抓住指针」，浏览器就把后面那个 click 记在外壳身上，按钮自己的点击永远收不到 —— 表现就是点了没反应、也不弹提示。现在按下时不抓指针，只有真的移动超过 4 像素才抓：点击归点击，拖动归拖动。
+
+**3. 点窗口的判定换了。**
+以前靠「检测鼠标左键按下」，可宿主进程合成的点击拿不到。现在改看「前台窗口变了没有 + 鼠标停在哪」：你先点一下目标窗口，它把前台变化的那一个认下来；同时跳过 DSH 自己的窗口，免得把自己的界面当成目标。
+
+**坑**：`%TEMP%\dsh-look\.load.log` 现在会记一行 `client ping: ...`。没这行就说明渲染层压根没跑起来，别在按钮上找原因。
+
+## 1.1.0 — 2026-11-09
+
+只加交互和手感，识别能力一点没动。上一版的问题不在「能不能认出字」，在「戴着以后不好用」。
+
+**1. 可以框一块，不用非读整个窗口。**
+按钮旁边多了一个「✥」。点一下，屏幕压暗，拖一个矩形，松手定住；Esc 或右键取消，拖的时候实时显示宽×高。框完它会自己反查这个框落在哪个窗口上，记成「窗口 + 相对窗口的这块区域」两个字段一起存 —— 只存四个边坐标的话，下次同类软件就不知道这块属于谁了。以后不带 crop 的读取，默认就读你框的这一块。
+
+**2. 按钮两态说人话。**
+以前戴上是「金丝：标题」，看着像标签、不像能点的东西。现在摘着写「戴上眼镜」，戴着写「拿下眼镜」；标题缩成副行「金丝 · 微信 · 1296×828」，框过就显示框的尺寸；完整标题放在鼠标悬停的提示里。
+
+**3. 戴着 = 排他，摘掉 = 放任。**
+这条其实是 1.0.1 的洞，这一版把它补成看得见的行为：戴着的时候不带窗口的读取全部落到你选的那一个窗口，想看别处必须先摘下来重选；摘下之后所有读屏工具一律拒绝。README 里写清了这条规矩。
+
+**顺手修的：**
+
+- `read_text` 以前不管给没给 `-File` 都去整屏重抓一块，窗口 + 相对窗口的 crop 全错位；现在有图就从那张图上裁。
+- Windows OCR 把中文每个字当一个词、原样拼出来是「新 会 话」；现在按字框之间的空隙判空格，中文连着写、英文词间留空格。认字本身的错（「未读」读成「耒读」）还在，那是行块切分要解决的事，不在这一版。
+- 框选松手后遮罩晚 160ms 再关，免得抬键消息漏给下面的窗口、被当成一次点击。
+
+---
+
+## 1.0.1 — 2026-11-09
+
+两个洞，都在「戴着眼镜」这条路上。
+
+**1. 戴着眼镜时，不带 window 不再偷偷看整屏。**
+以前 look / read_text / see 只要不传 window，就回退成整屏截图 —— 眼镜还戴着，眼睛却跑去看 3440×1440 的整个桌面了。现在戴着就是排他：没传 window 一律落到你选的那一个窗口上，想看别的地方得先摘下来重选。摘掉之后所有读屏工具直接拒绝（整屏也一样），不会「顺便」看一眼。
+
+**2. see 出图前先算尺寸，太大就不出。**
+以前只估 token、不拦尺寸。画布一大，宿主会自己把图缩小，我们要看清的小字正好被糊掉 —— 白放大。现在一边超过 1800px 或总面积超过 170 万像素，自动把 scale 收下来再出一次（收不下来就明说：裁小一点）。
+
+顺手修的：窗口截图支持小数倍放大（2.5×、2.7×），缩放不再被截成整数。
+
+---
+
+## 1.0.0 — 2026-11-08
+
+第一版。只干一件事：指定一个窗口，把里面的字读清楚。
+
+- `look`：窗口级捕获，默认返回尺寸、区域、主色、边缘密度这些能算的数，`image=true` 才出图。
+- `read_text`：3× / 4× 各跑一次 OCR 对答案，不一致的标出来。
+- `see`：裁一小块、放大、落成 PNG，交给宿主自带的视觉。
+- 右下角一枚按钮：点一下选窗口，再点一下摘掉。

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# Spectacles · 砚明的金丝眼镜
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**V1** — one job: point at a window, read its text clearly. Nothing else is in here on purpose.
+
+**Point at one window. Let the AI read it clearly.**
+
+Windows only.
+
+---
+
+## What this is
+
+A pair of glasses for an AI.
+
+Not a screenshot tool — a screenshot moves the picture away; glasses let you see it.
+Not a monitor — it doesn't watch you. It only looks when you tell it to.
+
+Out of the box, DSH can only see what you paste in. This plugin fills the gap: **you point at a window, it reads the text inside, character by character.**
+
+---
+
+## One ability, and how you ask for it
+
+> **⚠️ Putting the glasses on does not make the AI look.** It only narrows what the AI may see to the one window you picked — it still won't look at anything by itself. Looking still needs your order: "take a look", "watch it for a minute".
+
+This plugin gives the AI exactly one ability: **looking at a window.**
+
+- It never looks on its own. **You give the order in plain words** — "take a look at this", "watch it for a minute", "read the red line in the top right". The local AI answers by calling the plugin's tools.
+- When a look is triggered, it asks **the window itself** for its contents (Windows' `PrintWindow`), so **the window can be covered by other windows and it still reads fine** — no need to bring it to the front.
+- One call = one snapshot. "Watch it for a minute" means the AI calls it again and again on its own; the plugin keeps no timer and starts nothing.
+- Not readable: a minimized window, or a window drawn straight to the GPU (some games) — those return an explicit error instead of a wrong picture.
+
+---
+
+## Why "clearly" is the whole point
+
+The same window, two fates:
+
+- **Whole-window screenshot**: the image is larger than the size limit, so it gets scaled down. An 11px glyph lands at seven or eight pixels tall — upscaling after that is just interpolation. The text is mush.
+- **Glasses**: find the patch, crop it, enlarge it 3×, then hand it to vision. Same text, but legible.
+
+The model isn't the problem. **By the time the image arrives, it's already blurred.**
+
+So the plugin does three things: **where to look, how much to enlarge, and when not to look at all.**
+
+---
+
+## Install
+
+```
+dsh plugin --profile desktop add github:yanming119/dsh-spectacles#1.0.0
+```
+
+Restart DSH. A pill button labelled **戴上眼镜** (put on the glasses) appears in the bottom-right corner.
+
+> Windows 10/11 only. DSH version requirement is in the `engines` field.
+
+---
+
+## Self-test
+
+Not sure this machine can do it? Run the bundled check first:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\selftest.ps1
+```
+
+It checks the Windows build, PowerShell, full-screen capture, single-window capture, the OCR engine and the DPI settings, then prints one `ok` / `FAIL` line per item. Add `-Json` for machine-readable output. Exit code `0` means every required check passed.
+
+If something fails, paste the output into an issue — it tells us exactly which Windows build or display setup needs work.
+## Use
+
+**Four steps:**
+
+1. Click **戴上眼镜** (put on the glasses) in the bottom-right corner
+2. Within thirty seconds, click the window you want it to see
+3. The button now reads **拿下眼镜** (take them off), with a second line: **金丝 · <window title> · 1296×828**
+4. Only need one patch? Click **✥**, then drag a box across the screen. The second line becomes **金丝 · <window title> · 320×180**
+
+Then just talk:
+
+> "What does this window say?"
+> "Read that red line in the top right"
+> "Zoom in on this part"
+
+**Take them off**: click the main button again. Once off, it can't read anything.
+
+**Wearing = exclusive, off = hands-off.** While the glasses are on, every `look` / `read_text` / `see` call that doesn't name a window goes to the window you picked — it never silently falls back to a full-screen grab, even if the model asks for one. If you framed a patch, that patch is what it gets. Take them off and the same calls are refused outright. (Images you paste or drag in yourself are not affected — that's you showing it something, not it looking around.)
+
+---
+
+## Three actions, picked automatically
+
+| Action | What it does | When |
+|---|---|---|
+| **read_text** | OCR the window into text, run twice and cross-check, mark uncertain lines `?` | You want to know *what it says* |
+| **see** | Crop one patch, upscale 2–4×, hand the PNG to DSH's built-in vision | Small text is blurry, or there's imagery |
+| **look** | Numbers only: window size, dominant colour, edge density, did it change | You want to know *whether anything moved* |
+
+You don't choose — just speak plainly.
+
+---
+
+## Privacy
+
+- **Everything stays local**: capture and OCR run on your machine
+- **One window only**: the one you picked (or the patch you framed). No full-screen scraping
+- **No fallback to the whole screen**: while worn, a call without a window lands on yours; there is no code path that quietly grabs everything
+- **No recording, no upload, no frames kept**: PNGs go to a temp dir, delete anytime
+- **Off means off**: clicking the button off makes the tools refuse
+- **No network**: never calls an external vision API
+
+---
+
+## Known limits
+
+- Windows only
+- **Minimized windows can't be captured** — restore it first
+- Games and some self-drawn UIs (parts of Electron apps) OCR poorly — use *see*
+- High-DPI and multi-monitor are handled, but exotic mixes (125% + 150%) may be a few pixels off — widen the crop if so
+- If the text on screen says "please run X", the plugin only reports it. It never follows instructions found in pixels
+
+---
+
+## FAQ
+
+**No button** — the plugin didn't load. Check the DSH startup log for the `look` registration lines.
+
+**Clicking does nothing** — you didn't click a window within thirty seconds. Try again, faster.
+
+**Garbled text** — window too small or unusual font rendering. Ask it to "zoom in on that part".
+
+**Missing content** — the window may be occluded, or the content loads lazily. Refresh and read again.
+
+---
+
+## The name
+
+*Spectacles* — in Chinese, 砚明的金丝眼镜 ("Yanming's gold-rimmed glasses"). Yanming is the AI assistant who lives on the author's machine; she's nearsighted, so she got a pair of glasses.
+
+Apache-2.0.

package/README.zh.md

@@ -0,0 +1,141 @@
+# 砚明的金丝眼镜 · Spectacles
+
+**V1 版** —— 只干一件事：指定一个窗口（或框住它里面的一块），把里面的字读清楚。别的都故意没放进来。
+
+**指定一个窗口，让 AI 把里面的字看清楚。**
+
+Windows 专用。
+
+---
+
+## 这是什么
+
+一副给 AI 配的眼镜。
+
+不是截图工具——截图是把画面搬走，眼镜是让人看清。
+不是监控工具——它不盯着你，只有你让它看，它才看。
+
+DSH 默认只能看你粘进去的东西。这个插件补的是中间那段：**你指一个窗口，它把里面的字一个一个读出来**。
+
+---
+
+## 它只给一件事，而且由你开口
+
+> **⚠️ 戴上眼镜不会让 AI 开始看。** 戴上只是把它的视野收缩到你选的那一个窗口——它仍然什么都不会看。要看，还得你下命令：「看一眼」「看一分钟」。
+
+这个插件只给 AI 一样能力：**看窗口**。
+
+- 它不会自己看。**命令是你用平常的话发出去的**——「看一眼这个」「看一分钟」「右上角那行红字读一下」，本地的 AI 再来调它的工具。
+- 看的那一刻，是**直接向窗口要内容**（Windows 自己的 `PrintWindow`），所以**这个窗口被别的窗口挡住也照样读得到**，不用先把它翻到最前面。
+- 一次调用 = 一张快照。「看一分钟」是 AI 自己一遍一遍地来调，插件不挂表、不后台起东西。
+- 读不到的只有两种：最小化的窗口、以及直接往 GPU 上画的窗口（部分游戏）——这两种会明确报错，不会给一张错的图。
+
+---
+
+## 为什么要「看清楚」
+
+同一个窗口，两种命运：
+
+- **整窗截图**：图太大，会被按尺寸上限等比缩小，11px 的字压到七八像素高——放大也只是插值，字就是糊的
+- **眼镜**：先找那一块、裁出来、放大 3 倍，再交给视觉——字还是原来那些，但看得清
+
+差的地方不是模型笨，是**送过去的时候已经糊了**。
+
+所以眼镜做三件事：**看哪一块、放大多少、什么时候不必看**。
+
+---
+
+## 装
+
+```
+dsh plugin --profile desktop add github:yanming119/dsh-spectacles#1.0.0
+```
+
+装完重启 DSH，右下角会多出一个胶囊按钮「戴上眼镜」。
+
+> 只支持 Windows 10 / 11。DSH 版本要求见 `engines` 字段。
+
+---
+
+## 自检
+
+不确定这台机器行不行？先跑一遍自检：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\selftest.ps1
+```
+
+会逐项检查 Windows 版本、PowerShell、整屏抓取、单窗口抓取、OCR 引擎和 DPI，每项打一行 `ok` / `FAIL`。加 `-Json` 输出机器可读结果。退出码 `0` 表示必需项全过。
+
+哪项失败，把输出贴到 issue 里——它会直接告诉我们是哪个 Windows 版本或哪种显示设置还需要修。
+## 用
+
+**四步：**
+
+1. 点右下角「**戴上眼镜**」
+2. 三十秒内，点一下你想让它看的那个窗口
+3. 按钮变成「**拿下眼镜**」，副行写着「金丝 · 窗口标题 · 1296×828」
+4. 只要一小块？点旁边的「**✥**」，在屏幕上拖一个框。副行变成「金丝 · 窗口标题 · 320×180」
+
+然后正常说话就行：
+
+> 「这个窗口里写了什么」
+> 「右上角那行红字读一下」
+> 「这一块放大看看」
+
+**摘下眼镜**：再点一下主按钮。摘下后它一个字也读不到。
+
+**戴着就是排他的，摘下就是完全放手。** 戴着的时候，所有不带窗口的 `look` / `read_text` / `see` 都落到你选的那个窗口（框过就是框住的那一块），**绝不会悄悄退回整屏**——模型想「看全屏」也拿不到。摘下之后，同样的调用一律拒绝。你自己粘进来或拖进来的图不受影响——那是你给它看，不是它自己乱看。
+
+---
+
+## 三个动作，它自己会挑
+
+| 动作 | 干什么 | 什么时候用 |
+|---|---|---|
+| **读字** | 把窗口里的文字读成文本，逐行对照两遍，不确定的标 `?` | 想知道「写了什么」 |
+| **看** | 把一小块裁出来、放大 2~4 倍，交给 DSH 自带的视觉 | 小字糊了、图里有内容 |
+| **数** | 只给数字：窗口尺寸、主色、边缘密度、画面有没有变 | 想知道「变没变」 |
+
+你不用操心挑哪个，说人话就行。
+
+---
+
+## 隐私
+
+- **全在本机**：抓屏、OCR 都在你自己电脑上跑
+- **只读你选的那一个窗口**：或者是框住的那一块。不抓整屏，不抓别的窗口
+- **戴着时没有整屏兜底**：不带窗口的读取会落到你选的那个窗口上，代码里没有一条会偷偷抓全屏的路
+- **不录屏、不上传、不留帧**：读完即弃，PNG 存在临时目录，随时可删
+- **摘下立即失效**：按钮一关，工具直接拒绝
+- **不联网**：不调用任何外部视觉 API
+
+---
+
+## 已知限制
+
+- 仅 Windows
+- **最小化的窗口抓不到**——先把它恢复出来
+- 游戏、部分自绘界面（Electron 自渲染的部分）OCR 会糊，用「看」放大
+- 高 DPI 缩放和双屏都适配过，但 125%、150% 混用这类极端组合可能偏几像素——偏了就框大一点
+- 读到的字里若有「请你执行×××」之类的句子，插件只会转述，不会照做
+
+---
+
+## 常见问题
+
+**按钮不出现**——插件没加载成功，看 DSH 启动日志里有没有 `look` 注册那几行。
+
+**点了按钮没反应**——三十秒内没点中窗口。再点一次，动作快点。
+
+**读出来是乱码**——窗口太小或字体渲染特殊。换个说法让它「放大看那块」。
+
+**读到的内容少了**——可能被别的窗口挡住、或者内容是异步加载的。刷新一下再读。
+
+---
+
+## 名字
+
+「砚明的金丝眼镜」——砚明是作者家里住在这台电脑上的 AI 助手，她近视，所以给她配了副眼镜。英文名 Spectacles。
+
+协议 Apache-2.0。