dsh-web-annotator 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.1 — 文档与截图重做
+
+**插件行为没有变化**，界面与 0.2.0 完全相同；本版只为把 README 修对。
+
+- **截图全部换新**。旧图停在 2026-10-04，早于输入框入口改成透明按钮，
+  所以文档里展示的是用户已经拿不到的界面；其中一张还带着已退休的产品名与一条失败提示
+  （那是验收脚本故意中断提交留下的横幅，适合当证据、不适合当宣传图）。
+  新图按当前版本重截，并逐张裁到对应段落讲的那块区域 —— 整窗截图缩进文档栏后看不清。
+- **排版**：顶部加一句话定位与安装命令；“三步走”（选 → 写 → 发）逐张配图；
+  “它能做什么”由七条长句改为表格。
+- 修掉一个由换图引入的问题：npm 把相对路径的图重写成
+  `raw.githubusercontent.com/<repo>/HEAD/...`，取的是**仓库 HEAD** 而不是包内副本，
+  所以删掉「已发布 README 仍引用的文件名」会让线上页面出现破图。文件名已沿用，教训记进
+  [AGENTS.md](AGENTS.md) 的「活跃坑」。
+
 ## 0.2.0 — 第一个稳定版
 
 把 `0.2.0-alpha` 系列收成一个稳定版：在 Harness 原有 Browser 里点选或框选网页元素、

package/README.md

@@ -1,6 +1,7 @@
 # DSH Web Annotator · 网页批注与提问
 
-在 Harness 原有 Browser 标签页里，点击或框选网页，然后就地添加评论、向当前 Agent 提问。
+在 DeepSeek Harness **原有的 Browser 标签页**里点选或框选网页，就地写评论、向当前 Agent 提问，
+再把标记截图或 DOM 定位资料发给当前会话。
 
 [![Package checks](https://github.com/cslkkl/dsh-web-annotator/actions/workflows/ci.yml/badge.svg)](https://github.com/cslkkl/dsh-web-annotator/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -9,28 +10,40 @@
 
 **简体中文** · [English](README_en.md)
 
-![真实 Harness Browser 中的框选批注](docs/images/annotation-region.png)
+![在 Harness Browser 中框选页面并就地评论](docs/images/annotation-browser.png)
+
+```sh
+# 装这一个包，然后正常退出并重开 Desktop
+dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotator-<版本>.tgz
+```
+
+包内已有运行产物，不需要编译，也不需要放行构建脚本。完整说明见[安装](#安装)。
+
+## 三步走
+
+**1 · 选** —— 点元素、点空白位置，或拖动框选矩形区域。
+
+![点选元素或框选区域](docs/images/annotation-element.png)
+
+**2 · 写** —— 在选区旁写评论或提问；展开同一张卡片可看标签、颜色、字体，也能直接改。
+
+![展开属性卡片，调整颜色字体间距](docs/images/annotation-expanded.png)
+
+**3 · 发** —— 勾选要发的批注，选发送方式，预览后发到当前会话；聊天里收成“N 条注释”。
+
+![聊天里收成“N 条注释”](docs/images/annotation-message.png)
 
 ## 它能做什么
 
-- **就地批注**：点选元素、点击空白位置，或拖动框选矩形区域，在选区旁写评论或提问。
-- **边看边改属性**：展开同一张属性卡片调整颜色、字体、间距，改动随批注交给 Agent，保存前不改写网页。
-- **临时操作网页**：按住空格键与网页交互，松开回到批注；输入框里的空格照常打字。
-- **带图或带定位资料发送**：截图会用蓝框或蓝圈标出所选位置，并叠加与附图一致的序号徽标；
-  没有截图时可只发坐标与 DOM 证据，也可两者一起发。
-- **聊天里一眼看清**：本插件发出的批注消息只显示“N 条注释”，展开后逐条给出序号、目标元素与
-  你的评论／提问；完整定位资料仍在同一个折叠里。
-- **多条管理**：保存后可编辑、逐条勾选、分批发送；失败保留，成功只移除本次发出去的。
-- **草稿不丢**：按会话与完整 URL 存进 IndexedDB；发送失败或保存失败都不会清空内容。
-
-**0.2.0 精确支持 Harness 0.2.0-rc.2。**
-一个预构建安装包同时包含插件和 Browser、Chat、Layout 扩展，安装后正常重启 Desktop 即可使用。
-扩展尚未合入官方 Harness。npm 上已有预览与稳定两个通道（`npm install dsh-web-annotator`）；
-社区目录的条目已提交，**等待维护者审阅**，所以不要据此认为市场已可搜索。
-每个版本的安装包与验证记录由[发布链路](.github/workflows/release.yml)在标签上构建并附到 Release。
-
-⚠️ **已验证到什么程度**：真实宿主 26 项 Browser 检查通过；但**原生 Desktop、真实模型、
-兼容矩阵仍未验证** —— 逐项边界见[验证说明](docs/verification.md)，不要把未验证当已验证。
+| 能力                 | 说明                                                                              |
+| -------------------- | --------------------------------------------------------------------------------- |
+| **就地批注**         | 点选元素、点击空白位置或拖动框选，在选区旁写评论或提问                            |
+| **边看边改属性**     | 展开同一张卡片调颜色、字体、间距，改动随批注交给 Agent，保存前不改写网页          |
+| **临时操作网页**     | 按住空格与网页交互，松开回到批注；输入框里的空格照常打字                          |
+| **带图或带定位资料** | 截图用蓝框或蓝圈标出所选位置，并叠加与附图一致的序号徽标；也可只发坐标与 DOM 证据 |
+| **聊天里一眼看清**   | 批注消息默认只显示“N 条注释”，展开后逐条给出序号、目标元素与你的评论／提问        |
+| **多条管理**         | 保存后可编辑、逐条勾选、分批发送；失败保留，成功只移除本次发出去的                |
+| **草稿不丢**         | 按会话与完整 URL 存进 IndexedDB；发送或保存失败都不会清空内容                     |
 
 ## 安装
 
@@ -42,18 +55,20 @@ dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotat
 ```
 
 只装这一个包，然后正常退出并重开 Desktop。使用其他 Profile 时替换 `desktop`。
-包内已有运行产物，不需要用户编译或放行构建脚本。
 
 该 bundle 在启用期间**替换官方 Browser、Chat 和 Layout 提供方**。
 请先确认 Harness 内核是 **0.2.0-rc.2**，不要在其他版本或另一套同类提供方上混装。
 卸载整个 bundle 会撤销这些替换，重启后恢复官方提供方。
 
 旧本地预览用户先移除 `dsh-layout-care` 和 `dsh-layout-care-browser-preview` 再安装新包。
-已有批注会自动迁移。详见 [安装和市场发布](docs/distribution.md)。
+已有批注会自动迁移。详见[安装和市场发布](docs/distribution.md)。
 
 ## 使用方式
 
 1. 在当前会话点击“批注网页”，打开 Harness 原有的 Browser。
+
+   ![输入框里的“批注网页”入口](docs/images/annotation-entry.png)
+
 2. 输入网页地址，点击工具栏中“刷新”左边的“批注网页”。
 3. 点击元素或空白位置，或者拖动鼠标框选区域，在选区旁输入内容。
 4. 浮层默认只有选项图标、输入区和圆形 ✓。点左侧图标展开属性卡片，查看标签、颜色、字体等，
@@ -62,13 +77,13 @@ dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotat
 5. 需要操作网页时按住空格键，松开回到批注。
 6. 保存后可编辑文字，勾选本次要发送的批注，再选择发送方式，预览后发送到当前会话。
 
-![实际展开的属性卡片](docs/images/annotation-expanded.png)
-
 图片通过 Harness 的正式图片附件流程发送。图片模式只发批注正文、网页 URL 和对应截图；
 详细模式保留坐标与 DOM 证据，但聊天默认只显示“N 条注释”，点击展开逐条卡片（序号、目标元素、
 评论或提问），再点“查看定位资料”展开完整请求；附件截图上的序号与卡片序号一致。
 模型能否直接识别图片取决于当前模型的图片能力。
 
+![图片模式的发送预览](docs/images/annotation-image.png)
+
 ## 当前支持范围
 
 | 能力                                           | 状态                                     |
@@ -83,7 +98,7 @@ dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotat
 | 其他远程页面                                   | 逐个页面分别验收；Web 仍受跨源与嵌入限制 |
 | iframe 内部与 closed Shadow DOM 的子元素       | 只定位外层载体，不能穿透                 |
 
-逐项的验证边界与手工清单见 [验证说明](docs/verification.md)。
+逐项的验证边界与手工清单见[验证说明](docs/verification.md)。
 
 ## 接入自己的 Vite 页面
 
@@ -105,9 +120,9 @@ export default defineConfig({ plugins: [webAnnotator()] });
 且 Web 版下只有带桥接的页面能被批注。所以本地项目要先变成一个 HTTP 地址：
 
 ```sh
-npm run build                                   # 首次需要，产出 lib/bridge.js
-npm run annotate -- "C:\路径\到\你的项目"        # 服务静态目录
-npm run annotate -- --proxy http://127.0.0.1:5173   # 套在已有 dev server 前面
+npm run build                                        # 首次需要，产出 lib/bridge.js
+npm run annotate -- "C:\路径\到\你的项目"             # 服务静态目录
+npm run annotate -- --proxy http://127.0.0.1:5173    # 套在已有 dev server 前面
 ```
 
 然后点「批注网页」，输入打印出来的 `http://127.0.0.1:4180`。

package/README_en.md

@@ -12,7 +12,31 @@ Click or drag inside the Browser tab Harness already has, then comment or ask th
 > The maintainer documentation is written in Chinese. This file mirrors [README.md](README.md) item by
 > item; every document it links to is Chinese-only.
 
-![A rectangle annotation in the real Harness Browser](docs/images/annotation-region.png)
+![Annotating a page inside the Harness Browser](docs/images/annotation-browser.png)
+
+```sh
+# Install this one package, then quit and reopen Desktop normally
+dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotator-<version>.tgz
+```
+
+The package ships its build output, so there is nothing to compile and no build script to allow.
+Full instructions under [Install](#install).
+
+## Three steps
+
+**1 · Pick** — click an element, click empty space, or drag a rectangle.
+
+![Click an element or drag a rectangle](docs/images/annotation-element.png)
+
+**2 · Write** — comment or ask next to the selection; expand the same card to read the tag, colour
+and font, and change them.
+
+![Expand the properties card to adjust colour, font and spacing](docs/images/annotation-expanded.png)
+
+**3 · Send** — tick the notes to send, choose how, preview, then send to the session; the chat
+collapses them into one "N notes" chip.
+
+![The chat collapses the notes into one "N notes" chip](docs/images/annotation-message.png)
 
 ## What it does
 

package/docs/distribution.md

@@ -49,8 +49,22 @@
 [marketplace 条目](marketplace/cslkkl__dsh-web-annotator.yml) 的 `tarball` 钉的是**具体标签**
 （`releases/download/v<版本>/…`），不是 `releases/latest/download/…`：
 
-- **为什么不能用 `latest`**：本仓所有 Release 都是预发布版，`/releases/latest` **解析不到任何 Release**
-  （实测 `latest/download/<文件>` 直接 404）。上游两种写法都接受，而这里只有钉标签一种可用。
+- **为什么不能用 `latest`**：`latest/download/<文件名>` 只会在**当前 Latest 那个 Release** 里
+  找同名资产，而安装包的文件名里带版本号 —— 所以它只在文件名碰巧属于当前 Latest 时可用。
+  发下一版时 Latest 一移动，旧文件名就 404：
+
+  ```
+  Latest = v0.2.0 时的资产名：
+    dsh-web-annotator-0.2.0.tgz          ← 滚动链接能找到
+    dsh-web-annotator-source-0.2.0.zip
+    dsh-web-annotator-verification-0.2.0.json
+  换成 v0.2.1 之后，上面这些名字全部 404。
+  ```
+
+  也就是说滚动链接不会「一劳永逸」，只会在发下一版时**静默 404**。
+  （判据是 `gh api repos/<owner>/<repo>/releases/latest --jq '.assets[].name'` ——
+  不依赖网络实测，只看资产清单就能判定。）
+
 - **代价**：钉标签意味着**每发一版都要同步改这一行**，否则市场指向的是旧包。
   上游的每日探测会在 URL 404 时把 tarball 从站点上摘掉（不会报错，只是静默回落成源码安装），
   所以这行漏改不会有红信号 —— 判据是发版后手跑一次

package/docs/marketplace/cslkkl__dsh-web-annotator.yml

@@ -1,7 +1,7 @@
 url: https://github.com/cslkkl/dsh-web-annotator
 name: cslkkl/dsh-web-annotator
 category: browser
-tarball: https://github.com/cslkkl/dsh-web-annotator/releases/download/v0.2.0/dsh-web-annotator-0.2.0.tgz
+tarball: https://github.com/cslkkl/dsh-web-annotator/releases/download/v0.2.1/dsh-web-annotator-0.2.1.tgz
 description:
   en: 'Annotate pages inside the existing Harness Browser: click or drag to select, comment or ask, then send marked screenshots or DOM location details to the current session. While enabled it replaces the official Browser, Chat and Layout providers; targets Harness 0.2.0-rc.2.'
   zh: '在 Harness 原有 Browser 内批注网页：点选或框选后就地评论、提问，可把标记截图或 DOM 定位资料发给当前会话；启用期间替换官方 Browser、Chat 与 Layout 提供方，精确支持 Harness 0.2.0-rc.2。'

package/lib/host/bundle.json

@@ -1,6 +1,6 @@
 {
   "packageName": "dsh-web-annotator",
-  "packageVersion": "0.2.0",
+  "packageVersion": "0.2.1",
   "targetHarness": "0.2.0-rc.2",
   "upstreamCommit": "639ed015397290b3745d163aafe02ffee4aa3f84",
   "patchSha256": "b8701aa99139478e2b17a78a3d75bc22d2bce9d6c6952d1f2551271d7211a63f",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-web-annotator",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Click or drag to annotate pages in the existing DeepSeek Harness Browser and ask the current agent.",
   "license": "MIT",
   "type": "module",

package/screenshots.json

@@ -1,7 +1,9 @@
 [
-  "docs/images/annotation-region.png",
+  "docs/images/annotation-browser.png",
+  "docs/images/annotation-element.png",
+  "docs/images/annotation-entry.png",
   "docs/images/annotation-expanded.png",
-  "docs/images/annotation-expanded-dark.png",
   "docs/images/annotation-image.png",
-  "docs/images/annotation-message.png"
+  "docs/images/annotation-message.png",
+  "docs/images/annotation-region.png"
 ]