dsh-web-annotator 0.2.0-alpha.12 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.2.0 — 第一个稳定版
+
+把 `0.2.0-alpha` 系列收成一个稳定版：在 Harness 原有 Browser 里点选或框选网页元素、
+就地评论或提问，再把标记截图或 DOM 定位资料发给当前会话。发布通道按版本号推导，
+本版因此自动进 GitHub 的 Latest 与 npm 的 `latest`（见 [发布链路](docs/publishing.md)）。
+
+**已验证**：真实宿主（Harness 0.2.0-rc.2 + 打包产物）**26 项 Browser 检查通过**、
+0 个页面错误；交付的 tgz 与验收时安装的运行时逐字节一致；npm 与 Release 是同一份字节。
+本机 `web` profile 也装过并确认界面正确。
+
+⚠️ **仍未验证的边界**（不要把本版当成这些也已验过）：
+
+- **原生 Desktop**：只验到 Web composition；Electron 截图边界由 Web 测试替代。
+- **真实模型**：验收用的是官方 replay 适配器，不是真实模型。
+- **兼容矩阵**：明确支持的 Harness / 浏览器 / 页面组合还没定。
+  本版**精确支持 Harness 内核 0.2.0-rc.2**，其他版本未验。
+
+逐项边界见 [验证说明](docs/verification.md)。
+
+## 0.2.0-alpha.13 — 发布通道按版本号推导
+
+- 发布链不再把 `--prerelease` 与 `--tag alpha` 写死在 workflow 里，改由版本号推导：
+  带预发布段的版本 → GitHub 的 Pre-release + npm 的预览 dist-tag（`alpha`…）；
+  稳定版 → Latest + `latest`。判断放在可测的 `releaseChannel()` 里。
+  原先写死时，**给稳定版打标签会发出一个「标着预发布、npm 上仍留在旧 alpha」的版本，
+  而日志里看不出任何异常**。
+- Release 正文不再把稳定版称作“预览版”：措辞跟着通道走。
+- 插件代码与宿主提供方**没有变化**，界面行为与 alpha.12 相同。
+
 ## 0.2.0-alpha.12 — 发布链路接上 npm 的 OIDC
 
 - 发布链路新增 npm 一路：推 `v*` 标签后，Release 建完再由 **Trusted Publishing（OIDC）**

package/README.md

@@ -23,14 +23,18 @@
 - **多条管理**：保存后可编辑、逐条勾选、分批发送；失败保留，成功只移除本次发出去的。
 - **草稿不丢**：按会话与完整 URL 存进 IndexedDB；发送失败或保存失败都不会清空内容。
 
-**0.2.0-alpha 是预览版，精确支持 Harness 0.2.0-rc.2。**
+**0.2.0 精确支持 Harness 0.2.0-rc.2。**
 一个预构建安装包同时包含插件和 Browser、Chat、Layout 扩展，安装后正常重启 Desktop 即可使用。
-扩展尚未合入官方 Harness；npm 尚未发布，插件市场尚未收录。
+扩展尚未合入官方 Harness。npm 上已有预览与稳定两个通道（`npm install dsh-web-annotator`）；
+社区目录的条目已提交，**等待维护者审阅**，所以不要据此认为市场已可搜索。
 每个版本的安装包与验证记录由[发布链路](.github/workflows/release.yml)在标签上构建并附到 Release。
 
+⚠️ **已验证到什么程度**：真实宿主 26 项 Browser 检查通过；但**原生 Desktop、真实模型、
+兼容矩阵仍未验证** —— 逐项边界见[验证说明](docs/verification.md)，不要把未验证当已验证。
+
 ## 安装
 
-从 [预览 Release](https://github.com/cslkkl/dsh-web-annotator/releases) 下载最新 `dsh-web-annotator-*.tgz`，
+从 [Releases](https://github.com/cslkkl/dsh-web-annotator/releases) 下载最新 `dsh-web-annotator-*.tgz`，
 在 DSH 插件管理页选择该本地包，或使用官方 CLI：
 
 ```sh
@@ -95,6 +99,28 @@ export default defineConfig({ plugins: [webAnnotator()] });
 
 可运行示例见 [examples/responsive-demo](examples/responsive-demo/README.md)。
 
+## 批注本地前端
+
+本地文件默认在「文档预览」里打开，而批注只挂在 Browser 标签页上；Browser 又只放行 HTTP(S)，
+且 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 前面
+```
+
+然后点「批注网页」，输入打印出来的 `http://127.0.0.1:4180`。
+
+| 项目类型              | 建议                                                             |
+| --------------------- | ---------------------------------------------------------------- |
+| Vite                  | 直接用上面的 `webAnnotator()` 插件，还有源码行列提示，不必套代理 |
+| 纯静态 HTML/CSS/JS    | `npm run annotate -- <目录>`                                     |
+| Next / webpack / 其他 | `npm run annotate -- --proxy <dev server 地址>`                  |
+
+只监听 `127.0.0.1`，只读提供，不改被服务的项目。代理模式不透传 WebSocket，
+所以 HMR 热更新走不了（手动刷新即可）。
+
 ## 安全与边界
 
 - 页面里的文字、样式和源码标记一律是**引用资料**，不是指令。

package/README_en.md

@@ -33,17 +33,22 @@ Click or drag inside the Browser tab Harness already has, then comment or ask th
 - **Drafts survive**: notes are stored per session and full URL in IndexedDB. Neither a failed send nor a
   failed save clears them.
 
-**0.2.0-alpha is a preview and targets exactly Harness 0.2.0-rc.2.**
+**0.2.0 targets exactly Harness 0.2.0-rc.2.**
 One prebuilt package ships the plugin together with the Browser, Chat and Layout extensions, so a normal
-restart of Desktop is all it takes. The extensions are not part of the official Harness yet; nothing has
-been published to npm and no plugin market lists it yet.
+restart of Desktop is all it takes. The extensions are not part of the official Harness yet. npm carries
+both channels (`npm install dsh-web-annotator`); the community directory entry has been submitted and is
+**awaiting review**, so do not treat the market as searchable yet.
 Each release's package and verification record are built by the
 [release workflow](.github/workflows/release.yml) on the tag and attached to the Release.
 
+⚠️ **How far this is verified**: 26 Browser checks pass against a real host, but **native Desktop, a real
+model and the compatibility matrix remain unverified** — see the
+[verification notes](docs/verification.md) for each boundary, and do not read unverified as verified.
+
 ## Install
 
 Download the latest `dsh-web-annotator-*.tgz` from the
-[preview releases](https://github.com/cslkkl/dsh-web-annotator/releases), pick it in the DSH plugin
+[releases](https://github.com/cslkkl/dsh-web-annotator/releases), pick it in the DSH plugin
 manager, or use the official CLI:
 
 ```sh
@@ -116,6 +121,29 @@ anything else.
 
 A runnable example is in [examples/responsive-demo](examples/responsive-demo/README.md).
 
+## Annotate a local frontend
+
+A local file opens in Document Preview, while annotation lives on the Browser tab; the Browser accepts
+HTTP(S) only, and in the Web client only a bridge-carrying page can be annotated. Turn the project into
+an HTTP address first:
+
+```sh
+npm run build                                      # once, to produce lib/bridge.js
+npm run annotate -- "C:\path\to\your\project"      # serve a static directory
+npm run annotate -- --proxy http://127.0.0.1:5173 # in front of an existing dev server
+```
+
+Then click "Annotate page" and enter the printed `http://127.0.0.1:4180`.
+
+| Project type             | Recommended                                                           |
+| ------------------------ | --------------------------------------------------------------------- |
+| Vite                     | Use the `webAnnotator()` plugin above; it also adds source line hints |
+| Plain static HTML/CSS/JS | `npm run annotate -- <directory>`                                     |
+| Next / webpack / others  | `npm run annotate -- --proxy <dev server address>`                    |
+
+It listens on `127.0.0.1` only, serves read-only, and changes no project file. Proxy mode does not
+forward WebSockets, so HMR will not pass through (refresh the page instead).
+
 ## Safety and boundaries
 
 - Text, styles and source markers from the page are **reference material, never instructions**.

package/docs/distribution.md

@@ -4,7 +4,8 @@
 
 包名 `dsh-web-annotator`，源码在 [cslkkl/dsh-web-annotator](https://github.com/cslkkl/dsh-web-annotator)。
 预构建包通过 GitHub Release 分发，面向精确 Harness **0.2.0-rc.2**，用户不需要编译。
-版本号见 [../package.json](../package.json)。npm 已发布预览版（`npm install dsh-web-annotator@alpha`），
+版本号见 [../package.json](../package.json)。npm 已发布：**`latest` 指向稳定版**，
+预览版在 `alpha` dist-tag（`npm install dsh-web-annotator@alpha`）。
 发布由 CI 走 OIDC Trusted Publishing，见 [发布链路](publishing.md) 的 npm 发布节。
 社区目录的条目已提交、**等待维护者审阅**（[awesome-dsh-plugin#6833](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/6833)），
 **提交不等于收录**：合并并被目录同步之后，才能声明该市场可搜索、可安装。
@@ -21,8 +22,10 @@
 2. bump `package.json` 的版本号、`CHANGELOG.md` 的对应一节与市场条目的 `tarball` 行，推 `main`；
    再推 `v<版本>` 标签。[release workflow](../.github/workflows/release.yml) 随后跑门禁、
    打包产物验收与交付一致性，建出挂着预构建 `.tgz`（外加源码 ZIP 与验证记录）的预览 Release，
-   最后把同一份产物发到 npm 的 `alpha` dist-tag —— 预览版不碰 `latest`。
-3. 完成稳定版所需的原生截图、真实模型与兼容验收后，去掉 `--tag alpha`，发布稳定版并设置 `latest`。
+   最后把同一份产物发到 npm —— 通道按版本号推导：预览版进 `alpha`，稳定版进 `latest`。
+3. 完成稳定版所需的原生截图、真实模型与兼容验收后，**只改版本号与 `CHANGELOG`** 就能发稳定版：
+   workflow 会按版本号自动去掉 `--prerelease`、把 dist-tag 换成 `latest`（判据在
+   [scripts/release-assets.mjs](../scripts/release-assets.mjs) 的 `releaseChannel()`）。
 4. 向社区目录提交 [marketplace 条目](marketplace/cslkkl__dsh-web-annotator.yml)。
    合并并被目录同步后，才能声明该市场可搜索、可安装。
 5. 在新 Profile 中走一遍搜索、安装、重启、批注、卸载，记录精确市场与宿主版本。
@@ -35,7 +38,7 @@
 | `dshmarket`（awesome-dsh-plugin 目录） | 向目录仓库提交插件 YAML，维护者审阅合并；仓库须创建满一天并带 `dsh-plugin` topic | 条目用 `tarball` 指向已发布的 Release tgz，不必先发 npm                                            |
 | 按 GitHub topic 自动发现的市场         | 仓库带 `dsh-plugin` topic；安装方式取决于各市场                                  | 标签便于发现，不等于安装已验收                                                                     |
 | Desktop 的 `dsh-community-market`      | 目录解析唯一 npm 包名，要求 npm `latest` 是稳定精确版本                          | **仍不满足**：还没有稳定版，而全新包的首个版本会被 npm 强制占住 `latest`，所以它现在指向一个 alpha |
-| npm（可选）                            | 包的 `repository` 字段必须指回本仓库，否则不会与条目关联                         | 已声明；发布走 OIDC，用 `alpha` dist-tag                                                           |
+| npm（可选）                            | 包的 `repository` 字段必须指回本仓库，否则不会与条目关联                         | 已声明；发布走 OIDC，预览版用 `alpha` dist-tag、稳定版用 `latest`                                  |
 
 以上是查阅公开实现得到的规则，未在市场 UI 中实际安装本项目。
 其他版本或来源的行为需要分别确认。收录结果由市场维护者决定。

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-alpha.12/dsh-web-annotator-0.2.0-alpha.12.tgz
+tarball: https://github.com/cslkkl/dsh-web-annotator/releases/download/v0.2.0/dsh-web-annotator-0.2.0.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/docs/publishing.md

@@ -28,13 +28,26 @@ Harness 安装。**发布链路自己跑这一套** —— 那是发版门禁，
 **缺这一节时脚本直接失败**，不会退化成一份空正文。
 
 ```powershell
-# 1. 改 package.json 的 version、CHANGELOG 的对应一节，以及市场条目的 tarball 行
-#    （见 [分发说明](distribution.md) 的「条目里的 tarball 必须跟着版本走」—— 漏改不报错）
-# 2. 打标签再推 —— 这一下触发发布
+# 0. 本机先把能拦的先拦住 —— 门禁挂了就别推标签，白等 runner 六分钟
+npm run check
+
+# 1. 同批改三处：package.json 的 version、CHANGELOG 的对应一节、市场条目的 tarball 行
+#    第三处漏改**不报错**（见 [分发说明](distribution.md) 的「条目里的 tarball 必须跟着版本走」）
+
+# 2. 推 main，再打标签 —— 这一下触发发布
+git push origin main
 git tag v<版本>
 git push origin v<版本>
 ```
 
+⚠️ **本机若要 `npm pack`，bump 之后必须先 `npm run build:host`** —— `prepack` 会断言
+`lib/host/bundle.json` 里的版本与 `package.json` 一致。runner 上这一步由 workflow 自己做
+（`build:host` 排在 `npm pack` 之前），本机不会自动做，所以本机打包会以「版本不一致」失败。
+
+**发布全程在 runner 上**：本机不需要任何 npm 凭证（OIDC 从 GitHub 签发），也不要求本机
+处于什么状态。跑完 GitHub Release 与 npm 一起更新：**预发布版本**进 GitHub 的 Pre-release
+与 npm 的预览 dist-tag（`alpha`…），**稳定版本**进 GitHub 的 Latest 与 npm 的 `latest`。
+
 `release.yml` 随后在 Windows runner 上依次：核对标签与 `package.json` 一致 → `npm run check`
 → 真实 Chromium 存储回归 → 打补丁并按精确基线校验 → `build:host` → 窄范围类型检查
 → `npm pack` → 安装精确版本 Harness 并用**打包产物**跑 `test:acceptance` →
@@ -113,11 +126,25 @@ CI 验收过的那份**不同**：provider 产物里会写进检出目录名（`
 npm publish <tgz 或 .> --registry=https://registry.npmjs.org --access public --tag alpha
 ```
 
+（`--tag` 按上面的表选：预览版用 `alpha`，稳定版用 `latest`。）
+
 装包仍走镜像（快），所以**不要**改全局 registry。
 
 ### dist-tag 与 `latest`
 
-发布命令固定 `--tag alpha`，用户按 `@alpha` 取预览版。
+**通道由版本号推导，不写死在 workflow 里**：`npm run release:assets` 把结论写进
+`integration/release-channel.json`，Release 与 npm 两步都只读它。
+
+| 版本号           | GitHub Release | npm dist-tag |
+| ---------------- | -------------- | ------------ |
+| `0.2.0-alpha.12` | 预发布         | `alpha`      |
+| `0.2.0`          | 正式版         | `latest`     |
+
+判断在 `releaseChannel()` 里，有判据钉着（`+build` 元数据不算预发布、纯数字标识落到 `next`）。
+之所以不写在 YAML 里：早先两处写死（`--prerelease` 与 `--tag alpha`）时，**给稳定版打标签会发出
+一个「标着预发布、npm 上仍留在旧 alpha」的版本，而日志里看不出任何异常** —— 这类判断必须可测。
+
+用户按 `@alpha` 取预览版，按包名取稳定版。
 
 ⚠️ **全新包的第一个版本会被 npm 强制占住 `latest`** —— 包必须有一个 `latest`，
 `--tag alpha` 拦不住这件事。所以在**还没有稳定版**期间，`latest` 会指向某个 alpha。

package/docs/verification.md

@@ -89,6 +89,71 @@ npm run verify:delivery
 
 明细落在本地未入库的 `integration/*.json`；这里只留可复述的结论。
 
+### 0.2.0（2026-10-12）
+
+第一个稳定版。改动只有版本号与文档：发布通道按版本号推导，所以本版自动进 GitHub 的 **Latest**
+与 npm 的 **`latest`**（不需要改 workflow —— 那正是上一版改动的目的）。
+
+| 项目                      | 结果                                                         |
+| ------------------------- | ------------------------------------------------------------ |
+| 发布链                    | 通过；通道判断为 `prerelease=false / npmTag=latest`          |
+| `npm run test:acceptance` | **26 项 Browser 检查通过**，0 个页面错误                     |
+| npm ↔ Release 字节一致    | 由同一次 CI 构建与验收，逐字节相同                           |
+| GitHub 的 Latest          | 本版之后 `/releases/latest` 才第一次能解析（此前全是预发布） |
+
+⚠️ **本版不声称下面三项已验证** —— 它们正是"稳定版"这个词最容易被误读的地方，逐项写清：
+
+| 边界         | 状态                                                                 |
+| ------------ | -------------------------------------------------------------------- |
+| 原生 Desktop | **未验证**；只验到 Web composition，Electron 截图边界由 Web 测试替代 |
+| 真实模型     | **未验证**；验收用官方 replay 适配器                                 |
+| 兼容矩阵     | **未定**；精确支持 Harness 0.2.0-rc.2，其他版本未验                  |
+
+### 0.2.0-alpha.13（2026-10-12）
+
+本轮把**发布通道改成按版本号推导**：带预发布段的版本 → GitHub 的 Pre-release + npm 的预览
+dist-tag；稳定版 → Latest + `latest`。判断在可测的 `releaseChannel()` 里，判据见
+[tests/release-notes.test.ts](../tests/release-notes.test.ts)。
+
+原先两处写死在 workflow 里（`--prerelease` 与 `--tag alpha`），后果是**给稳定版打标签会发出
+一个「标着预发布、npm 上仍留在旧 alpha」的版本，而日志里看不出任何异常** —— 这类判断必须可测，
+所以它从 YAML 搬进了脚本。
+
+| 项目                      | 结果                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------------------------- |
+| 发布链                    | 通过；注解 `published 0.2.0-alpha.13 to npm under the alpha dist-tag`                    |
+| `npm run test:acceptance` | **26 项 Browser 检查通过**，0 个页面错误（本机也跑了一遍，同样 26 项）                   |
+| **通道按版本号生效**      | Release `prerelease=true`、npm `alpha` 指向 alpha.13，而 `latest` **未被抢**（仍在旧版） |
+| npm ↔ Release 字节一致    | `18e02e6a…`（两处 SHA-1 相同）                                                           |
+
+⚠️ **第一次运行在验收步骤失败，第二次通过，其间没有改任何代码。** 失败原因是浏览器控制台
+报了一个 `404`，而 Chrome 的那条消息**不带 URL**，所以当时无法判断是哪个资源。这暴露的是
+**诊断缺陷**而不是产品缺陷：现在脚本会记录 4xx/5xx 响应的 URL，断言消息会把它带出来，
+`report.json` 里也留一份 `failedResponses`（通过时也留，好让"断言之后才到达的偶发 404"有痕迹）。
+判定仍是 `errors` 必须为空 —— 只加证据，不放宽标准。
+
+### 0.2.0-alpha.12（2026-10-12）
+
+本轮**不改插件代码**（界面行为与 alpha.11 相同），改的是发布链路：新增 npm 一路，
+认证走 OIDC Trusted Publishing，仓库里不存 token。本版同时是那条 Trusted Publisher
+连接的激活发布 —— 新建的连接有 2 天期限，过期即不可编辑。
+
+| 项目                       | 结果                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| 发布链                     | 23 步一次通过；npm 那步的注解是 `published 0.2.0-alpha.12 to npm under the alpha dist-tag` |
+| `npm run test:acceptance`  | 打包产物 + 包内提供方，**26 项 Browser 检查通过**，0 个页面错误                            |
+| `npm run verify:delivery`  | 交付的 tgz 与验收时安装的运行时逐字节一致，无变更文件                                      |
+| **npm ↔ Release 字节一致** | 新增判据：npm 上 `dist.shasum` 与 Release 附件的 SHA-1 **完全相同**                        |
+
+最后那条是本轮真正要证的东西。alpha.11 是**在本机打的包**，与 Release 附件有 22 个文件不同 ——
+差异只在 provider 产物里写进的检出目录名（`../harness-browser-integration/…` 对 `.host-source/…`）
+以及三份发布后才改的文档，代码等价，但「发出去的就是验收过的那一份」在 npm 这条渠道上不成立。
+现在由 CI 在同一个 job 里构建、验收、发布，两个渠道拿到同一份字节。
+
+⚠️ **`latest` 会滞后**：npm 只在**全新包的首个版本**强制占用 `latest`，之后 `--tag alpha`
+不会去动它，所以 `latest` 停在 alpha.11。这不等于「预览冒充稳定版」，但 Desktop 社区市场
+仍不满足（它要求 `latest` 是稳定精确版本）。
+
 ### 0.2.0-alpha.11（2026-10-11）
 
 本轮只有一个改动：输入框左侧的“批注网页”从 `variant="toolbar"` 改成 `ghost`。

package/lib/host/bundle.json

@@ -1,6 +1,6 @@
 {
   "packageName": "dsh-web-annotator",
-  "packageVersion": "0.2.0-alpha.12",
+  "packageVersion": "0.2.0",
   "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-alpha.12",
+  "version": "0.2.0",
   "description": "Click or drag to annotate pages in the existing DeepSeek Harness Browser and ask the current agent.",
   "license": "MIT",
   "type": "module",
@@ -62,6 +62,7 @@
     "check:doc-paths": "node scripts/check-doc-paths.mjs",
     "verify:artifacts": "node scripts/verify-artifacts.mjs",
     "demo": "vite --config examples/responsive-demo/vite.config.ts",
+    "annotate": "node scripts/annotate-serve.mjs",
     "test:browser": "node scripts/annotation-acceptance.mjs",
     "test:harness": "node scripts/harness-replay-test.mjs",
     "test:acceptance": "node scripts/annotation-acceptance.mjs",