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

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

@@ -0,0 +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
+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

@@ -0,0 +1,169 @@
+# 发布链路
+
+CI 与发布相关的事实都写在这里。
+
+⚠️ **不要在本目录之外再建 `.github/README.md`。** GitHub 的首页 README 解析顺序是
+`.github/README.md` → 根 `README.md` → `docs/README.md`。放了前者，仓库首页会变成这份
+维护者文档，把面向用户的根 README 顶掉。判据：本仓只有根 `README.md` 与本案的
+`docs/README.md`，`.github/` 下只有 `workflows/`。
+
+## workflows
+
+| 文件                                                      | 触发                                  | 做什么                                                                                                                                                                                                                       |
+| --------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [workflows/ci.yml](../.github/workflows/ci.yml)           | `push` / `pull_request` / 手动        | Ubuntu 与 Windows 双跑：`npm run check` → 真实 Chromium 存储回归 → 校验补丁基线 → 构建宿主提供方 → 窄范围类型检查 → `npm pack --dry-run --json`（经 `prepack` 做产物完整性断言）                                             |
+| [workflows/release.yml](../.github/workflows/release.yml) | `push` 标签 `v*` / 手动（显式 `tag`） | 构建并验收**要发布的那个** tgz，再建 Release，最后发 npm：`npm run check` → 存储回归 → 补丁校验 → 构建宿主提供方 → `npm pack` → 真实宿主验收 → `verify:delivery` → 挂上 tgz、源码 ZIP 与验证记录 → Trusted Publishing 发 npm |
+
+`ci.yml` 检出官方 Harness 的精确基线到 `.host-source`，并把该路径经 `DSH_HOST_CHECKOUT`
+交给构建与校验脚本。`.host-source/` 已被 `.gitignore` 忽略。
+Node 版本只从 [../.node-version](../.node-version) 读。
+
+CI 不跑 `test:acceptance` / `test:harness`：它们需要打包产物、真实 Chromium 与一个完整
+Harness 安装。**发布链路自己跑这一套** —— 那是发版门禁，不是日常门禁，见下。
+
+## 发版
+
+版本号必须在打标签**之前**已经在 `package.json` 里 bump 过，并且 `CHANGELOG.md` 里要有
+对应的一节：Release 正文就从那里取（`npm run release:assets`），
+**缺这一节时脚本直接失败**，不会退化成一份空正文。
+
+```powershell
+# 1. 改 package.json 的 version、CHANGELOG 的对应一节，以及市场条目的 tarball 行
+#    （见 [分发说明](distribution.md) 的「条目里的 tarball 必须跟着版本走」—— 漏改不报错）
+# 2. 打标签再推 —— 这一下触发发布
+git tag v<版本>
+git push origin v<版本>
+```
+
+`release.yml` 随后在 Windows runner 上依次：核对标签与 `package.json` 一致 → `npm run check`
+→ 真实 Chromium 存储回归 → 打补丁并按精确基线校验 → `build:host` → 窄范围类型检查
+→ `npm pack` → 安装精确版本 Harness 并用**打包产物**跑 `test:acceptance` →
+`verify:delivery` → `npm run release:assets` → 建（或更新）Release 并挂附件
+→ 发 npm（见下）。
+
+⚠️ **验收失败就不发。** 这是「交付的 tgz 与验收时安装的运行时逐字节一致」的唯一可靠路径：
+换一台机器、换一个检出目录名重建 provider，产物里的 sourcemap `sources` 会带上那个目录名
+（实测 `../../../../harness-browser-integration/packages/...` 会变成 `-alt` 版本，字节就不同了），
+所以发布必须用**验收用的那一份**，而不是另建一份。
+
+想在没有 Release 的情况下重来一遍，用 `workflow_dispatch` 传一个**已存在**的标签重跑；
+它是幂等的：Release 已存在就更新正文与附件。
+
+⚠️ **runner 与开发机不一样。** 第一次跑通之前会依次踩到三处差别：Harness CLI 的安装位置
+（`setup-node` 把全局前缀指到工具缓存，不是 `%APPDATA%\npm`）、插件管理器装 tgz 要靠
+`pnpm`（runner 上没有）、界面语言取自 `navigator.languages`（en-US 的机器上渲染成英文，
+而验收断言的是中文按钮）。三处都写在 [release.yml](../.github/workflows/release.yml)
+对应步骤的注释里 —— 症状都是「验收挂了」，而真正的原因都不在报错里。
+
+⚠️ **别只看 workflow 的颜色。** 第一次发 alpha.10 时 workflow 全绿，Release 上却**没有安装包**
+（`npm pack` 的产物在仓库根目录，而上传只挂附件目录），所以
+[`npm run release:assets`](../scripts/README.md) 现在自己断言附件齐不齐；复核时也要亲眼看一下
+Release 的附件列表。
+
+## npm 发布
+
+认证走 **Trusted Publishing（OIDC）**，与 [dsh-cpa-switch](https://github.com/cslkkl/dsh-cpa-switch)
+同一套做法：**仓库里不存任何 npm token**，npm 侧凭「本仓库的 `release.yml`」授权，
+所以 `release.yml` 里必须有 `id-token: write`。**不要**加 `NPM_TOKEN` secret ——
+OIDC 已替代它，加了反而会在 token 过期后静默回到「workflow 能跑、包发不出去」的状态。
+配好之后建议把包的 Publishing access 改成「**Require two-factor authentication and
+disallow bypass 2fa tokens**」，堵掉 token 这条并行通道。
+
+环境要求 npm CLI ≥ 11.5.1（Node 24 自带的够新），registry 由 `setup-node` 的
+`registry-url` 显式钉到 `https://registry.npmjs.org`。
+
+### npm 侧怎么配（一次性）
+
+Trusted Publishing 配在**已存在的包**上，所以顺序不能颠倒：先让包存在，再配连接。
+登录 npmjs.com → **Packages → 本包 → Settings → Trusted publishing** →
+**Add trusted publisher** → 选 **GitHub Actions**：
+
+| 字段                 | 值                                               |
+| -------------------- | ------------------------------------------------ |
+| Organization or user | `cslkkl`                                         |
+| Repository           | `dsh-web-annotator`                              |
+| Workflow filename    | `release.yml`（**只填文件名**，不带 `.github/`） |
+| Environment name     | 留空                                             |
+
+⚠️ **`Allowed actions` 里必须勾 `Allow npm publish`。** 2026-09-03 之后新建的连接
+**默认只允许 `npm stage publish`**（暂存发布，要人工批准才上线）。漏勾时包只会进暂存区，
+而 **workflow 依然全绿** —— 症状是「CI 成功、npm 上看不到新版本」，最难查的一类。
+`Allow npm dist-tag` 不用勾：发稳定版用的是 `npm publish --tag latest`，属于 publish 权限。
+
+⚠️ **字段建好不可改** —— provider 与必填项一旦创建即固定，填错只能删掉重建。
+
+⚠️ **新建的连接有 2 天激活期**：必须在 2 天内成功发布一次，否则连接**过期且不可编辑**，
+只能删除重建。所以「配好」与「发一版」要挨着做；而为了激活而发的那一版本身也得有内容，
+不要为了跑通链路发一个空版本。
+
+包还不存在时，`release.yml` 里的 npm 这一步会**明确警告后跳过**（Release 已经建好了，
+缺的只是 npm 这一路），不会让发布无故变红。
+
+### 备用路径：本机手发
+
+OIDC 不可用时，所有者可在本机发布，但**只用于建包这类一次性动作**。本机打包的字节与
+CI 验收过的那份**不同**：provider 产物里会写进检出目录名（`../harness-browser-integration/…`
+而不是 `.host-source/…`），sourcemap 也跟着变 —— 长期走这条路等于让「发出去的就是验收过的
+那一份」失效。首个版本之后一律由 CI 发。
+
+⚠️ 本机 `npm` 若指向镜像（如 `registry.npmmirror.com`），`npm login` / `npm publish` 会报
+`Public registration is not allowed` —— 镜像只读，不提供账号与发布。发布时显式指定官方源：
+
+```powershell
+npm publish <tgz 或 .> --registry=https://registry.npmjs.org --access public --tag alpha
+```
+
+装包仍走镜像（快），所以**不要**改全局 registry。
+
+### dist-tag 与 `latest`
+
+发布命令固定 `--tag alpha`，用户按 `@alpha` 取预览版。
+
+⚠️ **全新包的第一个版本会被 npm 强制占住 `latest`** —— 包必须有一个 `latest`，
+`--tag alpha` 拦不住这件事。所以在**还没有稳定版**期间，`latest` 会指向某个 alpha。
+这不等于「预览冒充稳定版」（用户显式要 `@alpha` 拿到的才是我们承诺的那条），
+但意味着 Desktop 社区市场**仍不会收录**：它要求 `latest` 是稳定精确版本
+（见 [分发说明](distribution.md)）。发稳定版时才把 `latest` 指过去。
+
+### 发布后复核
+
+1. `npm view dsh-web-annotator dist-tags` —— `alpha` 应指向刚发的版本。
+2. `npm install dsh-web-annotator@alpha` 真装一次。
+   ⚠️ 头几分钟可能报 `ETARGET … No matching version found`：那是 npm/CDN 的**传播延迟**，
+   而 `npm view` 同时已经能看到新版本。**等几分钟再试，不是失败。**
+
+## 不在这里的事
+
+- **分支保护**：在平台设置界面人工开启，不是仓库文件。
+- **市场条目**：向目录仓库提 PR，见 [分发说明](distribution.md)。
+
+## 截图声明
+
+[screenshots.json](../screenshots.json) 是随包发布的截图清单，供市场条目引用。
+它是"目录清单"的手写副本，所以由 `npm run check:doc-paths` **双向**校验：
+声明的文件必须存在，`docs/images/` 下的截图必须都已登记。
+新增截图要同批登记，否则门禁报红。
+
+## 门禁的分工
+
+| 层              | 时机        | 做什么                                                                                              |
+| --------------- | ----------- | --------------------------------------------------------------------------------------------------- |
+| 本地 pre-commit | 提交前      | 只跑秒级的格式化与 lint，能自动修的自动修，见 [.pre-commit-config.yaml](../.pre-commit-config.yaml) |
+| `npm run check` | 提交前 / CI | format → lint → 分层 → 文档路径 → build → typecheck → 产物断言 → 测试                               |
+| CI              | push / PR   | 上面全部，另加真实 Chromium 存储回归、补丁基线校验、宿主提供方构建与打包                            |
+
+`check` 的顺序有依赖：`build` 必须在 `typecheck` 与 `verify:artifacts` 之前，
+因为两者都读 `lib/`（类型检查读 `lib/vite.d.ts`，产物断言读 `lib/client.js`）。
+调整顺序前先看 [../scripts/README.md](../scripts/README.md) 的依赖说明。
+
+钩子按**暂存文件**跑，`check` 跑全量 —— 「钩子绿了」不等于「门禁绿了」。
+钩子的 `files:` 与 `package.json` 的 `format:check` glob 是两个家，
+由 `tests/format-scope.test.ts` 钉住「门禁 ⊇ 钩子」这个方向。
+
+## 变更影响路由
+
+- 改任一 workflow → 同步本文件与 [分发说明](distribution.md)。
+- 改 `npm run check` 的内容或顺序 → 同步根 [AGENTS.md](../AGENTS.md) 的常用命令、
+  [../scripts/README.md](../scripts/README.md) 与本案的门禁分工表。
+- 改钩子的 `files:` 或 `format:check` 的 glob → 另一处必须同步；
+  判据 `tests/format-scope.test.ts` 会拦。

package/docs/roadmap.md

@@ -0,0 +1,31 @@
+# 路线图
+
+长期主线：直接在网页上指出位置，让 Agent 理解问题并给出可验证的答复或修改。
+优先级排序以“让常用流程稳定”为准，不靠增加检测规则扩大范围。
+
+## 1. 让安装不再依赖替换官方提供方
+
+Browser 补丁合入官方 Harness 之前，用户装的包会替换 Browser / Chat / Layout 三行。
+这是当前最大的安装摩擦，也是“用户能正常安装”的前置。
+
+## 2. 补上截图与附件的完整验收
+
+原生视口捕获目前只经人工验证，自动化里用测试替身代替了 Electron 边界。
+需要验证缩放、滚动、跨屏像素比例与实际附件日志，再声称视觉证据完整送达。
+
+## 3. 验证真实模型改动源码
+
+需要真实模型按批注定位并修改前端源码，并覆盖“提问只回答、不改代码”的回归场景。
+在此之前，任何“全流程通过”的说法都不成立。
+
+## 4. 长期使用
+
+批注编辑、过期定位提示、页面变化后的重新定位、批注导出与格式版本迁移。
+
+## 5. 支持矩阵与发布流程
+
+先明确验证过的 Harness / 浏览器 / 项目组合，再扩大兼容范围；
+稳定版发布前补齐官方 monorepo 门禁与稳定 dist-tag。
+
+以上是维护优先级，不代表已实现功能或发布时间承诺。
+独立插件负责批注流程与请求质量；浏览器载体、权限与扩展接口应由 Harness 维护。

package/docs/verification.md

@@ -0,0 +1,179 @@
+# 验证
+
+分三层：常规门禁、存储回归、真实宿主验收。三者不可互相替代。
+
+## 一、常规门禁
+
+```powershell
+npm run check
+```
+
+格式 → lint → 分层 → 文档路径 → build → typecheck → 单元与真实 Vite 测试。
+不读个人 Profile、不联网。覆盖范围见 [../tests/README.md](../tests/README.md)。
+请求快照保存在 `tests/snapshots/annotation-request.zh.txt`。
+
+## 二、存储回归（真实 Chromium）
+
+```powershell
+$env:WEB_ANNOTATOR_BROWSER_CHANNEL = 'msedge'   # 或 chrome
+npm run test:storage
+```
+
+覆盖：旧键迁移只在新键提交后删除、超过 localStorage 配额的真实 JPEG 队列重载、
+逐条编辑与会话隔离、写入失败保留并重试、只移除本次发送的 ID、显式删除持久数据。
+
+结果写到 `integration/storage-verification.json`。
+
+## 三、真实宿主验收
+
+需要精确版本 Harness 0.2.0-rc.2、配套提供方、已安装 Chromium，以及一个打包产物。
+
+```powershell
+npm run build                      # 先产出 lib/
+npm run build:host                 # 三个宿主提供方 → lib/host
+npm pack
+$env:WEB_ANNOTATOR_TARBALL = (Resolve-Path ./dsh-web-annotator-<版本>.tgz).Path
+$env:WEB_ANNOTATOR_BUNDLED_HOST = '1'
+npm run test:acceptance            # 真实 Browser + 打包产物 + replay 模型
+```
+
+测试 home 落在**仓库父目录**的 `work/`，由脚本创建并清理；不写个人 Profile。
+`session/list` 的线上参数是 `_request`。
+
+覆盖：工具栏挂载位置、点选不触发网页按钮、评论中的空格、按住空格操作网页、
+真实拖动矩形、空白位置、Shadow DOM、滚动与 Escape、明暗主题、页面隔离、失败重试、
+全屏与壁纸玻璃下的命中与恢复、属性框中文输入法确认、保存后编辑、分批勾选预览、
+窄窗口、目标删除后的确认按钮、聊天内“N 条注释”折叠与逐条卡片、附件截图上的序号徽标
+（在真实页面里重画后按像素判定）、混合队列的图片序号与附件入库、满队列分批发送。
+
+这一套命令就是 [release workflow](../.github/workflows/release.yml) 在标签上跑的那一套：
+**发出去的 tgz 必须就是这里验收过的那一份**，所以发布链路自己构建、自己验收、自己发，
+不会「在别处重建一份同一份代码」再挂上去（换台机器重建，产物的 sourcemap 就变了字节）。
+本机先跑一遍只是为了早失败，它不是发布门禁。
+
+结果写到 `integration/annotation-artifacts/`（截图、请求正文、transcript、`report.json`）。
+
+### 只验 replay 的部分
+
+模型端使用官方 `dsh-llm-replay`，不调用真实模型。
+replay 证明的是**请求路由与持久化日志**，不是模型真的改了源码。
+
+## 四、打包一致性
+
+```powershell
+npm run verify:delivery
+```
+
+把当前 tgz 逐文件与验收时安装的运行时比对：`lib/**` 与 `cordis.patch.yml` 必须逐字节相同，
+`package.json` 除 `devDependencies` 外必须相同。需要先跑过 `test:acceptance`。
+
+## 五、验到了什么 / 没验什么
+
+按版本记录的结论在 `integration/*.json`，不抄进本文档。以下边界在任何版本都成立：
+
+| 项目                                            | 状态                                   |
+| ----------------------------------------------- | -------------------------------------- |
+| 带扩展的真实 Harness Web 中的批注流程           | 已验证                                 |
+| 元素点选、矩形框选、空白位置、空格临时操作      | 已验证                                 |
+| 图片与详细资料折叠、真实附件入库                | 已验证（截图边界用测试替代 Electron）  |
+| 真实 DSH Desktop 的元素点选、属性卡片、原生截图 | 人工验证过，未随每次发布复验           |
+| **真实模型据此修改源码**                        | **未验证**                             |
+| **Electron 原生截图边界的自动化验收**           | **未验证**（Web 测试替代了该边界）     |
+| 其他远程页面、跨源与嵌套 iframe 内部            | 逐个页面分别验收                       |
+| 官方 monorepo 的覆盖率与平台门禁                | 未运行；本包的窄范围类型检查不等同于它 |
+| 市场 UI 中的搜索与一键安装                      | 未验证                                 |
+
+不要用单测绿色代替真实宿主验收，也不要用 Web 结果代替 Desktop 结果。
+
+## 六、按版本的验收记录
+
+明细落在本地未入库的 `integration/*.json`；这里只留可复述的结论。
+
+### 0.2.0-alpha.11（2026-10-11）
+
+本轮只有一个改动：输入框左侧的“批注网页”从 `variant="toolbar"` 改成 `ghost`。
+`toolbar` 是给 Browser 标签页工具栏准备的实心样式，放在输入框那一排会显得像被选中，
+与旁边同为透明的“工作区内修改”不一致；Browser 工具栏里的同名按钮**保持实心**不变。
+
+| 项目                      | 结果                                                            |
+| ------------------------- | --------------------------------------------------------------- |
+| `npm run check`           | 49 项单元测试全绿                                               |
+| `npm run test:storage`    | 4 项通过                                                        |
+| `npm run test:acceptance` | 打包产物 + 包内提供方，**26 项 Browser 检查通过**，0 个页面错误 |
+| `npm run verify:delivery` | 交付的 tgz 与验收时安装的运行时逐字节一致，无变更文件           |
+| Release                   | 三个附件齐全（tgz / 源码 ZIP / 验证记录），发布链一次通过       |
+
+判据不是“看着顺眼”，而是量出来的：在隔离 profile 里用 `getComputedStyle` 取相邻控件的
+`background-color`，改后“批注网页”与“工作区内修改”同为 `rgba(0, 0, 0, 0)`。
+宿主提供方、补丁与存储格式都没动，因此这一版不可能影响已有草稿。
+
+这一版还多了一层只可能由人给出的证据：alpha.11 以**已发布的 URL** 装进本机 `web` profile、
+重启之后，**由人确认输入框那一行的按钮确实变透明了**。“量出来是透明的”与“看起来是透明的”
+在这里是两件事，所以两条分开记。
+
+### 0.2.0-alpha.10（2026-10-08）
+
+本轮改动是聊天内的批注呈现（折叠成“N 条注释”与逐条卡片、附件上的序号徽标重画），
+并把从未发布过的 0.2.0-alpha.9 一并带出去。**整条发布链路在本机完整跑了一遍**，
+与 [release workflow](../.github/workflows/release.yml) 在标签上跑的是同一套命令：
+
+| 项目                      | 结果                                                                                          |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `npm run check`           | 格式 / lint / 分层 7 条规则 / 文档路径 / build / typecheck / 产物断言 / **49 项单元测试**全绿 |
+| `npm run test:storage`    | 4 项通过：旧键迁移只在新键提交后删除、>8 MB 队列重载、写入失败保留与重试、显式删除            |
+| `npm run test:acceptance` | 打包产物 + 包内提供方，**26 项 Browser 检查通过**，0 个页面错误                               |
+| `npm run verify:delivery` | 交付的 tgz 与验收时安装的运行时逐字节一致，无变更文件                                         |
+| `npm run release:assets`  | Release 正文、源码 ZIP 与验证记录齐备                                                         |
+| `npm pack`                | `prepack` 完整性断言通过                                                                      |
+
+本轮新增的两项机器判据：折叠状态的文案与展开后的卡片数，以及在本页里重画附件后
+按像素确认序号徽标落在所选范围的角上。
+
+发布链路本身的顺序也是这一轮修的：`ci.yml` 里的 `verify:browser-patch` 曾经排在打补丁**之前**，
+在干净的 `.host-source` 上第一个文件就必挂；已改成先 apply 再 verify，`release.yml` 同序。
+
+**仍未验收**：原生 Desktop 的 guest / 截图 / 快捷键、真实模型改动源码、其他远程页面、
+官方 monorepo 门禁、市场 UI 安装。不要据此声称这些已支持。
+
+### 0.2.0-alpha.9（2026-10-07，打好了包但从未发布）
+
+这一版 bump 了版本号、也打过 tgz，却没有推标签、没有建 Release，随后又被 alpha.10 覆盖，
+所以它的改动随 alpha.10 一并发布 —— **不要**把它当成一个用户下载得到的版本。
+
+本轮改动是删除 0.1 遗留层、统一 `web-annotator` 命名并迁移存储键，因此重点验证真实的安装与发送路径。
+
+| 项目                           | 结果                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `npm run check`                | 格式 / lint / 分层 7 条规则 / 文档路径 / build / typecheck / 单元测试全绿          |
+| `npm run test:storage`         | 4 项通过：旧键迁移只在新键提交后删除、>8 MB 队列重载、写入失败保留与重试、显式删除 |
+| `npm run test:harness`         | 真实 Harness 0.2.0-rc.2 + 官方 replay，2 轮对话通过                                |
+| `npm run test:acceptance`      | 打包产物 + 包内提供方，**24 项 Browser 检查通过**，0 个页面错误                    |
+| `npm run verify:browser-patch` | 补丁可应用到精确基线，并复现 26 个已审阅文件                                       |
+| `npm run verify:delivery`      | 交付的 tgz 与验收时运行的包逐字节一致，无变更文件                                  |
+| `npm pack`                     | `prepack` 完整性断言通过                                                           |
+
+验收还确认了一件与本轮修复直接相关的事：测试 home 现在落在**检出目录的父目录** `work/` 下，
+不再越级写到上层目录。
+
+**仍未验收**：原生 Desktop 的 guest / 截图 / 快捷键、真实模型改动源码、其他远程页面、
+官方 monorepo 门禁、市场 UI 安装。不要据此声称这些已支持。
+
+### 未发布记录（2026-10-07）
+
+聊天内批注呈现最初是在`未发布`状态下验的：只改 Client 半端的呈现与发送前的附件重画，
+宿主提供方与补丁未动，所以当时按“本包 + 已构建提供方”跑真实宿主验收，没有重新打包 tgz。
+那一批改动已并入 0.2.0-alpha.10 的验收（见上），这里只留当时的边界结论。
+
+## 七、手工验收清单（无自动化时）
+
+无法跑脚本时的最小手工路径：
+
+1. 安装打包 tgz，重启 Desktop。
+2. 打开 Browser，确认工具栏出现“批注网页”，且位于“刷新”左侧。
+3. 点选一个元素，确认网页自身的按钮没有触发。
+4. 框选一块区域，确认矩形与选区一致。
+5. 输入中文并切换输入法确认，确认不会误保存。
+6. 按住空格操作网页，松开回到批注。
+7. 发送到当前会话，确认聊天里只显示“N 条注释”，展开后逐条给出目标元素与你的输入，
+   点“查看定位资料”能看到完整请求；图片模式再看一眼截图上的序号徽标。
+8. 卸载 bundle，重启，确认官方 Browser 恢复。

package/dsh-plugin.naming.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "policy": "dsh-plugin-naming/v1",
+  "plugin": {
+    "namespace": "cslkkl",
+    "name": "web-annotator",
+    "coordinate": "cslkkl/web-annotator",
+    "packageName": "dsh-web-annotator"
+  },
+  "names": {
+    "pluginNames": ["cslkkl-web-annotator"],
+    "loaderIds": [
+      "cslkkl-web-annotator",
+      "cslkkl-web-annotator-browser",
+      "cslkkl-web-annotator-chat",
+      "cslkkl-web-annotator-layout"
+    ],
+    "services": [],
+    "tools": [],
+    "commands": [],
+    "skills": [],
+    "skillProviders": [],
+    "events": [],
+    "settingsNamespaces": [],
+    "routes": []
+  }
+}

package/examples/responsive-demo/AGENTS.md

@@ -0,0 +1,12 @@
+# responsive-demo — 规则层
+
+继承 [../../AGENTS.md](../../AGENTS.md)。
+
+本示例是**被批注的目标页面**，不是插件的一部分：
+
+- **不要在这里教已经删掉的扫描 / 保留区域流程** —— 主流程是 Browser 内点选 / 框选 + 评论 / 提问。
+- **保留用于定位的稳定锚点**：`#protected-header`、`#mobile-card`、`#intentional-carousel`。
+  验收与文档都按这些 id 描述。
+- **它通过构建产物接入**：`vite.config.ts` 引 `../../lib/vite.js`，所以先 `npm run build`。
+- 只在开发期生效；生产构建不注入连接脚本或源码标记。
+- 用法见 [README.md](README.md)。

package/examples/responsive-demo/README.md

@@ -0,0 +1,33 @@
+# responsive-demo — 响应式验收页面
+
+用于验收批注流程的目标页面。从插件仓库根目录先 `npm run build`，再 `npm run demo`。
+地址是 `http://127.0.0.1:4177`，只监听本机。
+
+`vite.config.ts` 引构建后的 `lib/vite.js`；开发服务器托管
+`__web-annotator__/bridge.js` 并把允许的父来源内联进页面。
+
+## 页面里有什么
+
+| 锚点                    | 用途                                              |
+| ----------------------- | ------------------------------------------------- |
+| `#protected-header`     | 页眉，适合演示“只改一处、别动这里”                |
+| `#mobile-card`          | 初始宽度 560 px，在窄视口下会横向溢出             |
+| `#intentional-carousel` | 有意使用 `overflow-x: auto`，属于正常设计而非缺陷 |
+
+`src/main.tsx` 的原生 DOM 元素带 `data-web-annotator-source` 提示（由 Vite 插件注入），
+点选后可以在批注里看到文件名、行与列。
+
+## 验收方式
+
+1. 在 Harness 里打开“批注网页”，输入上面的地址。
+2. 用 390 px 左右的视口，点选或框选 `#mobile-card`，写下要求。
+3. 点选 `#protected-header`，写明“这块保持原样”。
+4. 点选 `#intentional-carousel`，确认横滚区域不会被当作问题。
+5. 预览并发送到当前会话，由 Agent 修改源码；Vite 热更新会立刻反映结果。
+
+页面上的按钮只切换示例状态，用来演示“改前 / 改后”，不代表 AI 已经改过源码。
+
+## 常见问题
+
+- 页面能打开但无法批注：检查是否跑了 `npm run build`（`lib/bridge.js` 缺失时 Vite 中间件返回 500）。
+- 从非 loopback 来源连接：在 `webAnnotator({ allowedParentOrigins })` 里写精确的 HTTP(S) origin。

package/examples/responsive-demo/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#f7f5f0" />
+    <title>DSH Web Annotator · 响应式验收示例</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/responsive-demo/src/main.tsx

@@ -0,0 +1,110 @@
+import { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import './style.css';
+
+function Demo() {
+  const [repaired, setRepaired] = useState(false);
+  return (
+    <main className="workspace">
+      <header id="protected-header" className="site-header">
+        <a className="wordmark" href="#root">
+          Fieldnotes
+          <span className="wordmark-dot" aria-hidden="true">
+            ●
+          </span>
+        </a>
+        <span className="edition">设计与生活 / VOL. 008</span>
+      </header>
+
+      <section className="intro" aria-labelledby="page-title">
+        <p className="eyebrow">WEB ANNOTATOR · LIVE DEMO</p>
+        <h1 id="page-title">
+          一处修改，
+          <br />
+          也照顾其他地方。
+        </h1>
+        <p className="lede">
+          这是一张用于验收的真实页面：手机上的固定宽度卡片需要修复，页眉需要保留，横向作品集可以正常滚动。
+        </p>
+      </section>
+
+      <section className="review-controls" aria-label="示例操作">
+        <div>
+          <span className={`status-dot ${repaired ? 'good' : ''}`} aria-hidden="true" />
+          <strong>{repaired ? '已应用示例修复' : '等待检查手机布局'}</strong>
+          <p>
+            在 Harness 的批注网页里用 390 px 视口点选下方卡片并写下要求，再点选页眉说明需要保留。
+          </p>
+        </div>
+        <button
+          id="repair-toggle"
+          type="button"
+          aria-pressed={repaired}
+          onClick={() => setRepaired((value) => !value)}
+        >
+          {repaired ? '还原布局问题' : '应用示例修复'}
+          <span aria-hidden="true">↗</span>
+        </button>
+      </section>
+
+      <section className="feature-section" aria-labelledby="feature-title">
+        <div className="section-heading">
+          <h2 id="feature-title">本周精选</h2>
+          <span>01 / FEATURED</span>
+        </div>
+        <article id="mobile-card" className={`feature-card ${repaired ? 'repaired' : ''}`}>
+          <div className="card-art" aria-hidden="true">
+            <span className="art-circle" />
+            <span className="art-frame" />
+            <span className="art-line" />
+          </div>
+          <div className="card-body">
+            <p className="eyebrow">SPACES / 城市与空间</p>
+            <h3>让小空间，也有呼吸感。</h3>
+            <p>光线、留白与日常物件之间的距离，构成了一个可以慢下来的地方。</p>
+            <a href="#collection">
+              阅读这篇记录 <span aria-hidden="true">↗</span>
+            </a>
+          </div>
+        </article>
+        <p className="demo-note">
+          这张卡片初始宽度为 560 px。修复仅改变卡片宽度规则，页眉保持原样。
+        </p>
+      </section>
+
+      <section id="collection" className="collection-section" aria-labelledby="collection-title">
+        <div className="section-heading">
+          <h2 id="collection-title">可以横向浏览的作品集</h2>
+          <span>02 / COLLECTION</span>
+        </div>
+        <div
+          id="intentional-carousel"
+          className="carousel"
+          tabIndex={0}
+          aria-label="作品集，可横向滚动"
+        >
+          {[
+            ['01', '光的形状', 'warm'],
+            ['02', '窗边的下午', 'green'],
+            ['03', '安静的秩序', 'blue'],
+            ['04', '日常的纹理', 'pink'],
+          ].map(([number, title, tone]) => (
+            <article key={number} className={`collection-card ${tone}`}>
+              <span className="collection-number">{number}</span>
+              <div className="mini-art" aria-hidden="true" />
+              <h3>{title}</h3>
+            </article>
+          ))}
+        </div>
+        <p className="demo-note">
+          这里有意使用 overflow-x: auto，应保留横向滚动，而非当作页面越界修复。
+        </p>
+      </section>
+      <footer>
+        FIELDNOTES <span>Built for careful changes.</span>
+      </footer>
+    </main>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(<Demo />);