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

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+## 0.2.0-alpha.12 — 发布链路接上 npm 的 OIDC
+
+- 发布链路新增 npm 一路：推 `v*` 标签后，Release 建完再由 **Trusted Publishing（OIDC）**
+  把同一份产物发到 npm 的 `alpha` dist-tag，仓库里不存 token（`id-token: write` + `--provenance`）。
+  它排在建 Release **之后**：npm 那半失败时用户仍拿得到安装包，也排除了「npm 有、GitHub 没有」。
+- 本版是这条路径的第一次真实运行，兼作 npm Trusted Publisher 连接的激活发布 ——
+  新建的连接**有 2 天激活期**，过期后连字段都不可改。
+- 文档补上这轮踩到的三处，都写在 [发布链路](docs/publishing.md) 与 [AGENTS.md](AGENTS.md)
+  的「活跃坑」：本机 npm 指向镜像时登录/发布报 `Public registration is not allowed`；
+  Trusted Publisher 的 `Allowed actions` 默认**不含**直接发布（漏勾则 CI 全绿而 npm 上没有新版本）；
+  发布成功后头几分钟 `npm install` 会因传播延迟报 `ETARGET`，那不是失败。
+- 插件代码与宿主提供方**没有变化**，界面行为与 alpha.11 相同。
+
+## 0.2.0-alpha.11 — 输入框入口不再显成“被选中”
+
+- 输入框左侧的“批注网页”不再是一块恒有灰底的实心按钮。它原先借用了 `variant="toolbar"`
+  —— 那是给 **Browser 标签页工具栏**准备的实心样式，放在输入框这一排会显得像被选中/按下，
+  与旁边同样透明的“工作区内修改”不一致。现在改用 `ghost`：平时透明，悬停才显色。
+- **Browser 工具栏里的同一个按钮保持实心不变**：那里与“刷新”同处一个工具栏表面，实心是对的。
+  两处从此各用各的变体，不再共用。
+- 只动 Client 半端。宿主提供方、补丁与存储格式都没变，因此这一版不影响已有草稿。
+
+## 0.2.0-alpha.10 — 聊天内批注呈现
+
+- 本插件发出的批注消息不再平铺正文，改为默认显示“N 条注释”：展开后逐条给出序号、目标元素
+  （最近候选元素的标签与文本，缺候选时回落到“框选区域”／“页面位置”）和你的评论或提问。
+  定位资料仍是独立的折叠，默认收起。
+- 图片模式与混合模式的附件在 Client 半端重画：在宿主截图之上叠加与附图序号一致的蓝底白字徽标，
+  并补齐所选范围的蓝框；拿不到 canvas 或重画失败时保留宿主截图，证据不因绘制失败而丢失。
+- 新增 `annotation-thumbnail.ts`（目标标签、徽标锚点、重画）与 `tests/annotation-message.test.ts`。
+  序号只用于呈现：请求正文、`screenshotIndex` 与识别逻辑都不变，历史消息照旧折叠。
+- **0.2.0-alpha.9 的改动一并随本版发布**：那一版打好了包却从未发布过 Release，
+  留着就会出现一个用户下不到的版本号。条目见下，不另发。
+
+## 0.2.0-alpha.9 — 清理 0.1 遗留层，补齐门禁（未单独发布，内容并入 alpha.10）
+
+- 删除 0.1 的布局扫描 / 保留区域整层：`src/bridge/`、`src/shared/`、`src/client/bridge-client.ts`、
+  `review-storage.ts`、`copy.ts`、`styles.ts`。`lib/bridge.js` 现在只包含开发页批注传输。
+- 运行时名字统一为 `web-annotator`。**接入 Vite 的项目需要同步改名**：
+  桥接路由 `__web-annotator__/bridge.js`、源码提示属性 `data-web-annotator-source`、
+  内联配置全局 `__WEB_ANNOTATOR_CONFIG__`。函数名 `webAnnotator` 不变，旧 `layoutCare` 别名保留。
+- 批注存储键改为 `dsh.web-annotator.browser-annotations.v1`。
+  旧的 `dsh.layout-care.browser-annotations.v1` 会读一次并自动迁移，新键提交成功后才删除旧值。
+- 新增质量门禁：ESLint、依赖分层检查、文档路径检查，均随 `npm run check` 运行。
+  `.node-version` 固定 Node 24.15.0，CI 改为从该文件读取版本。
+- 开发页传输层可注入拾取器，因此第一次有了覆盖来源白名单、通道生命周期与取消的单元测试。
+- 修复 `DSH_HOST_CHECKOUT` 对局部类型检查不生效（CI 里会看不到 `.host-source`）；
+  测试 home 改为落在仓库父目录，不再越级到上层目录；补丁校验的临时目录用后即删。
+- 文档网络重建：根维护索引、架构说明、各子树 `AGENTS.md` + `README.md`、决策记录。
+  示例页面与贡献说明不再描述已删除的扫描流程。
+
+## 0.2.0-alpha.8 — 草稿可靠性与操作修复
+
+- 截图队列改用 IndexedDB，修复超过 localStorage 配额后刷新丢草稿的问题；自动迁移旧记录，显示保存失败提示。
+- 修复属性框在中文输入法确认时误保存，以及目标被页面删除后展开确认按钮仍可点击的问题。
+- 图片和定位资料混合发送保留可用截图，并准确标明附图序号；纯图片请求不再受未发送的 DOM 资料大小影响。
+- 保存后的批注可以编辑，队列支持逐条勾选分批发送；满队列提前拦截，避免写完才发现无法保存。
+- 新增大截图重载、存储失败恢复、编辑、中文输入法、窄窗口与混合附件的实际浏览器回归。
+
+## 0.2.0-alpha.7 — 项目命名与单包安装
+
+- 项目改名为 DSH Web Annotator（DSH 网页批注），包名改为 `dsh-web-annotator`。
+- Vite 接入函数改为 `webAnnotator`，保留旧 `layoutCare` 别名；批注存储键与页面连接协议保持兼容。
+- 这是首次开源前的命名调整。配套宿主扩展仍以精确 Harness 0.2.0-rc.2 为目标。
+- Browser、Chat 与 Layout 扩展随主包预构建分发，通过官方插件管理只安装一个包；卸载 bundle 会恢复官方提供方。
+- 增加宿主来源与许可证、打包完整性检查、市场截图声明及单包安装验收。
+
+## 0.2.0-alpha.6 — 全屏浏览器遮挡修复
+
+- 修复壁纸玻璃效果下，聊天首页或对话输入框浮到全屏网页上方的问题。
+- 全屏期间隐藏并禁用后方主内容，保持布局与组件挂载；退出后恢复同一输入框及草稿。
+- 配套增加 Layout 提供方，以及首页、已有对话、玻璃开关和网页输入的真实宿主验收。
+
+## 0.2.0-alpha.5 — 草稿生命周期修复
+
+- 批注编辑不再在两分钟后自动关闭，保留取消与导航清理，以及连接握手的超时检查。
+- 增加超过两分钟仍可编辑、保存及取消的真实宿主验收。
+- 实际 DSH Desktop 已验证 GitHub 页面的元素点选、属性卡片、原生截图与蓝框预览、三种发送选项；未调用真实模型。
+
+## 0.2.0-alpha.4 — 属性卡片与图片发送
+
+- 展开选项改为同一张属性卡片，包含颜色、字体、透明度等输入；修改要求随批注发送给 AI，取消不改写网页。
+- 桌面 Browser 保存时捕获实际视口并标出所选位置；支持图片、定位资料和两者一起发送。有截图时默认发送图片。
+- 通过正式会话图片附件流程提交；没有截图的旧记录保留并提示发送定位资料。
+- 新增 Chat 用户正文扩展，详细批注默认仅显示用户文字，定位资料按需展开；已有格式匹配的批注消息也可折叠。
+- 增加真实图片入库、详细消息重载、普通消息回退和属性校验验收。原生截图捕获与真实模型识图仍待验证。
+
+## 0.2.0-alpha.3 — 简洁批注输入框
+
+- 默认浮层改为单行胶囊：选项图标、无边框输入区、灰色圆形确认按钮。
+- 评论／提问、元素路径和上下级选择收进选项面板；Esc 或点击外部关闭面板并保留文字。
+- Shift+Enter 换行时输入区自动增高，空内容禁用确认。
+
+## 0.2.0-alpha.2 — 工具栏入口位置
+
+- “批注网页”直接显示在原有 Browser 工具栏中，紧挨“刷新”左侧。
+- 工具栏按钮显示文字，进入批注后显示“退出批注”。
+
+## 0.2.0-alpha.1 — Browser 内批注
+
+- 主入口改为 Harness 原有 Browser 标签页的工具栏。
+- 支持点击元素、点击空白位置与拖动框选实际矩形区域；就地输入评论或提问。
+- 按住空格临时操作网页，松开恢复批注；输入框中的空格保持正常输入。
+- 按会话和完整 URL 保留批注队列，发送前可预览；失败保留批注。
+- 提问与评论分别表达意图，区域候选元素不会替代框选范围。
+- 配套的 Browser 源码扩展针对 0.2.0-rc.2；未经此扩展的原版宿主不支持本功能。
+- Web 已验证开发页面连接；Desktop 原生网页接入代码尚未在真实 DSH Desktop 中验证。
+
+这是集成预览版，尚未公开发布。批注请求包含坐标与 DOM 资料，不附网页截图；真实模型修改源码仍未验收。
+
+## 0.1.0 — 初始实现
+
+- 本地开发网页的右侧预览与元素批注。
+- 水平内容溢出、元素视口越界候选检测与 CSS 选择器排除。
+- 记录保留区域，并比较文本、部分计算样式与几何位置。
+- 将批注和引用证据通过当前 Harness 会话的正常请求流程发送。
+- Vite 开发桥接、精确父页面来源验证、页面重载后重新握手。
+- 同一父页面重新连接可更换 token；回复完整页面 URL，防止导航后混用旧页面资料。
+- AST 添加 JSX 原生 DOM 节点源码提示，保留源码映射；可关闭提示。
+- 手机卡片越界、正常横滚区域与保留页眉的演示页面。
+- 逻辑、协议、实际 Vite 发布入口及生产排除测试。
+
+目标宿主为 Harness 0.2.0-rc.2。此版本不提供截图采集、像素对比或自动源码修改。具体运行验证以对应验证记录为准。

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# 参与 DSH Web Annotator
+
+欢迎用真实页面复现问题、改进批注交互、补充测试和完善说明。
+
+主流程是 Harness 原有 Browser 内的点选 / 框选 / 评论 / 提问。
+宿主接入方式与验证边界见 [Browser 集成说明](docs/browser-integration.md)。
+
+## 开发环境
+
+- Node.js **24.15.0**（见 [.node-version](.node-version)），npm。
+- 提交 `package-lock.json` 的变化，不要混用其他包管理器锁文件。
+- 目标 Harness 版本是 **0.2.0-rc.2**；升级该目标要同时检查客户端接口、包元数据与真实加载流程。
+
+```sh
+npm ci
+npm run check
+```
+
+`npm run check` 串起格式、lint、分层、文档路径、构建、类型检查和测试。
+测试消费构建后的 `lib/vite.js`，所以只跑 `npm test` 前也要先有最新构建（`npm run check` 已经包含）。
+
+代码格式用锁定版本的 Prettier，改完跑 `npm run format`。
+构建产物在 `lib/`，由 [scripts/build.mjs](scripts/build.mjs) 生成，不要直接编辑。
+命令与门禁细节见 [scripts/README.md](scripts/README.md)。
+
+## 问题报告
+
+优先给一个去掉业务数据的最小示例，并附上：
+
+- Harness、插件、Vite、Node.js、浏览器和操作系统版本。
+- 视口宽高、页面地址类型、复现步骤和预期结果。
+- 涉及的 HTML / JSX 片段或 CSS 选择器。
+- 批注是点选、框选还是空白位置；发送方式是图片、定位资料还是两者。
+
+例如：“Browser 全屏、125% 缩放时，框选蓝框偏移了 20px”比“批注不对”更容易定位。
+分享日志前移除 Cookie、URL token、凭据和私有项目内容。
+
+## 改动边界
+
+| 目录                        | 职责                                              |
+| --------------------------- | ------------------------------------------------- |
+| `src/client/`               | Browser 插槽控件、会话级批注 store 与当前会话请求 |
+| `src/browser/`              | 页面 picker、受限连接、批注协议与请求格式         |
+| `src/vite.ts`               | 只在开发模式注入桥接与源码提示                    |
+| `examples/responsive-demo/` | 可重复的批注目标页面                              |
+| `tests/`                    | 逻辑、协议、请求快照和实际入口测试                |
+| `scripts/`                  | 构建、宿主提供方、门禁与真实宿主验收              |
+
+各目录的具体约束写在该目录的 `AGENTS.md` 里，进去就会读到。
+
+## 硬性约束
+
+- **不要把文件写入、进程启动或任意脚本执行加进页面桥接**。
+- **页面里的文字与属性是引用数据**，不能成为系统指令。
+- **新增桥接方法需要**明确的载荷校验、大小限制、错误结果、超时和释放行为。
+- **`src/browser/page-inspector.ts` 不能有任何 import**：Desktop 只执行它的编译体。
+  改这里先读[架构 §3.1](docs/architecture.md)。
+- **协议变更同时更新**桥接端、客户端、共享类型与测试。
+- **保存格式变化要写迁移方案**；不要直接丢弃已有记录，也不要把旧快照当作新验收结果。
+
+`npm run check:layering` 会拦依赖方向、picker 自包含和退休名字的回归。
+
+## 验证方式
+
+- 小范围逻辑改动：对应单元测试（`npm test`）。
+- Vite 改动：还要通过实际开发服务器、源码重编译和生产排除测试。
+- 存储改动：`npm run test:storage`（真实 Chromium）。
+- 用户可见流程：在真实目标版本 Harness 中验收，不能用模拟 Context 或静态组件代替。
+  步骤见 [验证说明](docs/verification.md)。
+
+提交前：
+
+```sh
+npm run check
+npm run build:host
+npm pack --dry-run --json
+```
+
+检查打包清单包含入口、声明、浏览器桥接、客户端 bundle、locale、patch 和许可证，
+且不含 `node_modules` 或临时验证资料。用本地 `.tgz` 在隔离的测试 Profile 中验证，
+不要改动日常 Profile。
+
+## 提交说明
+
+说明具体触发场景、改后的行为和运行过的验证。
+修复误报时保留一条能区分正常设计与真实问题的回归案例。
+用户可见变化更新 [CHANGELOG.md](CHANGELOG.md)；契约、安装或行为边界变化时同步 README 与相关文档。
+
+核心路线是在原有 Browser 中指出位置、添加评论或问题，并把截图或定位资料准确送到当前会话。
+新功能先明确使用场景和成功标准，再决定是否进入首版。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH Web Annotator contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# DSH Web Annotator · 网页批注与提问
 
-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.
+在 Harness 原有 Browser 标签页里，点击或框选网页，然后就地添加评论、向当前 Agent 提问。
+
+[![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)
+[![Node](https://img.shields.io/badge/node-24.15.0-informational.svg)](.node-version)
+[![Harness](https://img.shields.io/badge/harness-0.2.0--rc.2-informational.svg)](docs/browser-integration.md)
+
+**简体中文** · [English](README_en.md)
+
+![真实 Harness Browser 中的框选批注](docs/images/annotation-region.png)
+
+## 它能做什么
+
+- **就地批注**：点选元素、点击空白位置，或拖动框选矩形区域，在选区旁写评论或提问。
+- **边看边改属性**：展开同一张属性卡片调整颜色、字体、间距，改动随批注交给 Agent，保存前不改写网页。
+- **临时操作网页**：按住空格键与网页交互，松开回到批注；输入框里的空格照常打字。
+- **带图或带定位资料发送**：截图会用蓝框或蓝圈标出所选位置，并叠加与附图一致的序号徽标；
+  没有截图时可只发坐标与 DOM 证据，也可两者一起发。
+- **聊天里一眼看清**：本插件发出的批注消息只显示“N 条注释”，展开后逐条给出序号、目标元素与
+  你的评论／提问；完整定位资料仍在同一个折叠里。
+- **多条管理**：保存后可编辑、逐条勾选、分批发送；失败保留，成功只移除本次发出去的。
+- **草稿不丢**：按会话与完整 URL 存进 IndexedDB；发送失败或保存失败都不会清空内容。
+
+**0.2.0-alpha 是预览版，精确支持 Harness 0.2.0-rc.2。**
+一个预构建安装包同时包含插件和 Browser、Chat、Layout 扩展，安装后正常重启 Desktop 即可使用。
+扩展尚未合入官方 Harness；npm 尚未发布，插件市场尚未收录。
+每个版本的安装包与验证记录由[发布链路](.github/workflows/release.yml)在标签上构建并附到 Release。
+
+## 安装
+
+从 [预览 Release](https://github.com/cslkkl/dsh-web-annotator/releases) 下载最新 `dsh-web-annotator-*.tgz`，
+在 DSH 插件管理页选择该本地包，或使用官方 CLI：
+
+```sh
+dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotator-<版本>.tgz
+```
+
+只装这一个包，然后正常退出并重开 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)。
+
+## 使用方式
+
+1. 在当前会话点击“批注网页”，打开 Harness 原有的 Browser。
+2. 输入网页地址，点击工具栏中“刷新”左边的“批注网页”。
+3. 点击元素或空白位置，或者拖动鼠标框选区域，在选区旁输入内容。
+4. 浮层默认只有选项图标、输入区和圆形 ✓。点左侧图标展开属性卡片，查看标签、颜色、字体等，
+   也可切换“评论／提问”和元素层级。点击 ✓ 或按 Enter 保存；Shift+Enter 换行并自动增高；
+   Esc 先收起卡片，再取消批注。
+5. 需要操作网页时按住空格键，松开回到批注。
+6. 保存后可编辑文字，勾选本次要发送的批注，再选择发送方式，预览后发送到当前会话。
+
+![实际展开的属性卡片](docs/images/annotation-expanded.png)
+
+图片通过 Harness 的正式图片附件流程发送。图片模式只发批注正文、网页 URL 和对应截图；
+详细模式保留坐标与 DOM 证据，但聊天默认只显示“N 条注释”，点击展开逐条卡片（序号、目标元素、
+评论或提问），再点“查看定位资料”展开完整请求；附件截图上的序号与卡片序号一致。
+模型能否直接识别图片取决于当前模型的图片能力。
+
+## 当前支持范围
+
+| 能力                                           | 状态                                     |
+| ---------------------------------------------- | ---------------------------------------- |
+| 原有 Browser 工具栏与网页内批注浮层            | 已验证                                   |
+| 元素点选、空白位置、矩形框选、空格临时操作     | 已验证                                   |
+| 多条批注、预览、失败重试、会话请求与持久化日志 | 已验证（模型端用官方 replay）            |
+| 图片附件与详细资料折叠                         | 已验证；Electron 截图边界用测试替代      |
+| 聊天内“N 条注释”折叠与逐条卡片                 | 已验证（附件序号徽标随图片模式验收）     |
+| Desktop 原生网页点选、属性卡片与原生截图       | 人工验证过，未随每次发布复验             |
+| **真实模型据此修改源码**                       | **尚未验收**                             |
+| 其他远程页面                                   | 逐个页面分别验收；Web 仍受跨源与嵌入限制 |
+| iframe 内部与 closed Shadow DOM 的子元素       | 只定位外层载体，不能穿透                 |
+
+逐项的验证边界与手工清单见 [验证说明](docs/verification.md)。
+
+## 接入自己的 Vite 页面
+
+```ts
+import { defineConfig } from 'vite';
+import { webAnnotator } from 'dsh-web-annotator/vite';
+
+export default defineConfig({ plugins: [webAnnotator()] });
+```
+
+只在开发服务器生效。JSX/TSX 原生标签会附带文件、行、列提示；生产构建不注入连接脚本或源码标记。
+连接默认允许 HTTP loopback 的 Harness；其他来源通过 `allowedParentOrigins` 指定精确 HTTP(S) origin。
+
+可运行示例见 [examples/responsive-demo](examples/responsive-demo/README.md)。
+
+## 安全与边界
+
+- 页面里的文字、样式和源码标记一律是**引用资料**，不是指令。
+- 插件回调只暴露有界数据与动作，**不向页面暴露 DOM、任意求值器或宿主能力**。
+- 批注与截图只存在你本机的浏览器存储中，通过当前会话的正常请求流程发送。
+- 文件写入与源码修改由你当前会话中的 Agent 完成，插件本身不执行任何脚本。
+
+## 许可与参与
+
+MIT 许可证，见 [LICENSE](LICENSE)。第三方声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+
+欢迎用真实页面复现问题、改进交互、补测试或完善文档，见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+维护者文档地图、构建与门禁命令见 [AGENTS.md](AGENTS.md)。

package/README_en.md

@@ -0,0 +1,136 @@
+# DSH Web Annotator · Annotate a page and ask the agent about it
+
+Click or drag inside the Browser tab Harness already has, then comment or ask the current agent in place.
+
+[![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)
+[![Node](https://img.shields.io/badge/node-24.15.0-informational.svg)](.node-version)
+[![Harness](https://img.shields.io/badge/harness-0.2.0--rc.2-informational.svg)](docs/browser-integration.md)
+
+**English** · [简体中文](README.md)
+
+> 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)
+
+## What it does
+
+- **Annotate in place**: click an element, click empty space, or drag a rectangle, then write a comment
+  or a question next to the selection.
+- **Change attributes while you look**: expand the same card to adjust colour, font and spacing. The
+  changes travel with the annotation to the agent and never rewrite the page before you save.
+- **Operate the page temporarily**: hold Space to interact with the page and release it to return to
+  annotating; spaces typed into the editor stay spaces.
+- **Send with an image or with location details**: the screenshot marks your selection with a blue frame
+  or circle and adds an index badge that matches the attachment; without a screenshot you can send the
+  coordinates and DOM evidence, or both together.
+- **Readable in the chat**: an annotation message shows "N notes" instead of a wall of text. Expanding it
+  lists each note's index, target element and your comment or question; the full location details stay in
+  the same collapsible block.
+- **Manage several notes**: edit a saved note, tick the ones to send, and send them in batches. A failed
+  send keeps the note; a successful one removes only what that send included.
+- **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.**
+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.
+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.
+
+## 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
+manager, or use the official CLI:
+
+```sh
+dsh plugin --profile desktop add --ignore-scripts /absolute/path/dsh-web-annotator-<version>.tgz
+```
+
+Install this one package, then quit and reopen Desktop normally. Substitute your own profile name for
+`desktop`. The package already contains its runtime artifacts, so nothing has to be compiled and no build
+script has to be approved.
+
+While the bundle is enabled it **replaces the official Browser, Chat and Layout providers**. Check first
+that the Harness kernel is **0.2.0-rc.2**, and do not mix it with another plugin that provides the same
+rows. Uninstalling the whole bundle undoes the replacement and a restart brings the official providers
+back.
+
+If you used an earlier local preview, remove `dsh-layout-care` and `dsh-layout-care-browser-preview`
+first. Existing annotations migrate automatically. Details are in
+[distribution](docs/distribution.md) (Chinese).
+
+## Using it
+
+1. In the current session click "批注网页" to open the Browser Harness already has.
+2. Enter a page address, then click "批注网页" in the toolbar, to the left of the reload button.
+3. Click an element or empty space, or drag to select a region, and type next to the selection.
+4. The floating editor is a single line by default: an options icon, the input and a round ✓. The icon on
+   the left expands the attribute card with the tag, colour, font and so on, and switches between
+   comment/question and element level. Click ✓ or press Enter to save; Shift+Enter adds a line and grows
+   the box; Esc collapses the card first and cancels the annotation second.
+5. Hold Space when you need to operate the page, and release it to return to annotating.
+6. After saving you can edit the text, tick the notes to send, choose how to send them, preview, and send
+   them into the current session.
+
+![The attribute card expanded](docs/images/annotation-expanded.png)
+
+Images travel through Harness's own image-attachment flow. Image mode sends only the annotation text, the
+page URL and the matching screenshot. Detailed mode keeps the coordinates and DOM evidence, but the chat
+shows "N notes" by default; expanding it gives one card per note (index, target element, comment or
+question), and "view location details" reveals the full request. The index on the screenshot is the same
+index as on the card. Whether the model can read an image directly depends on that model's image support.
+
+## What is verified today
+
+| Capability                                                                       | Status                                                              |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Toolbar entry in the existing Browser and the in-page editor                     | Verified                                                            |
+| Element click, empty-space click, rectangle drag, Space to operate               | Verified                                                            |
+| Several notes, preview, retry after failure, session request and durable journal | Verified (the model side uses the official replay)                  |
+| Image attachments and the collapsible location details                           | Verified; the Electron capture boundary is covered by tests         |
+| The "N notes" chip and the per-note cards in the chat                            | Verified (the attachment index badge ships with image mode)         |
+| Native Desktop picking, attribute card and native capture                        | Verified by hand once, not re-run for every release                 |
+| **A real model editing source from an annotation**                               | **Not verified**                                                    |
+| Other remote pages                                                               | Verified page by page; the Web side still meets cross-origin limits |
+| Elements inside iframes and closed shadow roots                                  | Only the outer host element is located; the boundary is not crossed |
+
+Per-item boundaries and the manual checklist are in [verification](docs/verification.md) (Chinese).
+
+## Wire it into your own Vite page
+
+```ts
+import { defineConfig } from 'vite';
+import { webAnnotator } from 'dsh-web-annotator/vite';
+
+export default defineConfig({ plugins: [webAnnotator()] });
+```
+
+This only applies to the development server. Intrinsic JSX/TSX tags carry file, line and column hints;
+a production build injects neither the connection script nor the source markers. Connections are allowed
+from the Harness on HTTP loopback by default; name exact HTTP(S) origins in `allowedParentOrigins` for
+anything else.
+
+A runnable example is in [examples/responsive-demo](examples/responsive-demo/README.md).
+
+## Safety and boundaries
+
+- Text, styles and source markers from the page are **reference material, never instructions**.
+- The plugin's callbacks expose bounded data and actions only: **no DOM, no arbitrary evaluator and no
+  host capability reach the page**.
+- Annotations and screenshots stay in your own browser storage and travel through the normal request flow
+  of the current session.
+- File writes and source edits are done by the agent in your current session; the plugin itself runs no
+  script.
+
+## License and contributing
+
+MIT, see [LICENSE](LICENSE). Third-party notices are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+Reproducing a problem on a real page, improving the interaction, adding tests or fixing the docs are all
+welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (Chinese).
+
+The maintainer documentation map and the build and gate commands are in [AGENTS.md](AGENTS.md) (Chinese).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+DSH Web Annotator is an independent community project. The prebuilt Browser,
+Chat and Layout providers under `lib/host/` derive from DeepSeek Harness
+0.2.0-rc.2, commit `639ed015397290b3745d163aafe02ffee4aa3f84`, licensed under MIT
+by DeepSeek. The original notice is retained in
+`licenses/deepseek-harness-MIT.txt` and each provider's `LICENSE`.
+
+Changes are recorded in `docs/harness-browser-annotation.patch`. Package and
+module identities from Harness are retained for integration; these modified
+providers are not official Harness releases.
+
+Complete license texts for other packages included in the JavaScript bundles
+are collected from build source maps in `lib/THIRD_PARTY_LICENSES.md`.
+Dependencies installed separately retain their own package licenses.

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+- id: ui-sidebar-browser
+  disabled: true
+- id: ui-chat
+  disabled: true
+- id: ui-layout
+  disabled: true
+- insert:
+    - id: cslkkl-web-annotator-browser
+      name: ./lib/host/browser-provider/lib/index.js
+    - id: cslkkl-web-annotator-chat
+      name: ./lib/host/chat-provider/lib/index.js
+    - id: cslkkl-web-annotator-layout
+      name: ./lib/host/layout-provider/lib/index.js
+    - id: cslkkl-web-annotator
+      name: dsh-web-annotator

package/docs/AGENTS.md

@@ -0,0 +1,16 @@
+# docs/ — 规则层
+
+继承 [../AGENTS.md](../AGENTS.md)。
+
+docs/ 特有约束：
+
+- **只放辅助文档**：设计决策、宿主接入、验证记录、分发与优先级。
+  文件级清单归各子树 `README.md`，不写在这里。
+- **写“为什么”，不写步骤手册**：`architecture.md` 是设计圣经；
+  操作步骤进 `browser-integration.md` 或 `verification.md`。
+- **不抄会漂的值**：版本号、测试数量、产物哈希都指向自更新来源（`package.json`、
+  CI 记录、`integration/*.json`），不要写死在正文里。
+- **`harness-browser-annotation.patch` 是生成物**：由宿主检出 `git diff HEAD` 生成，
+  不要手改。生成方式见 [browser-integration.md](browser-integration.md)。
+- **相对链接必须可解析**：`npm run check:doc-paths` 会拦；改文件名时同批改引用。
+- 有什么文档、改哪见 [README.md](README.md)。

package/docs/README.md

@@ -0,0 +1,25 @@
+# docs/ — 辅助文档索引
+
+- 约束与写作偏好 → 见 [AGENTS.md](AGENTS.md)。
+
+| 文档                                             | 回答什么                                           | 改它的时机                   |
+| ------------------------------------------------ | -------------------------------------------------- | ---------------------------- |
+| [architecture.md](architecture.md)               | 不变的设计决策、契约、失败模式、分层与编号防错清单 | 契约、边界或门禁变化时       |
+| [browser-integration.md](browser-integration.md) | 宿主补丁是什么、怎么应用、怎么构建与打包           | 补丁、提供方或打包流程变化时 |
+| [verification.md](verification.md)               | 验到了什么程度、哪些**没有**验证                   | 每次真实验收之后             |
+| [distribution.md](distribution.md)               | 安装方式、各市场收录规则、发布顺序                 | 分发渠道或版本状态变化时     |
+| [publishing.md](publishing.md)                   | CI 跑什么、门禁怎么分工、`.github/` 的规矩         | workflow 或门禁串联变化时    |
+| [roadmap.md](roadmap.md)                         | 维护优先级与未立项方向                             | 优先级变化时                 |
+| [images/](images/)                               | 文档截图                                           | 界面变化时同时更新           |
+| [marketplace/](marketplace/)                     | 向社区目录提交的条目                               | 提交或更新市场条目时         |
+
+## 生成物
+
+[harness-browser-annotation.patch](harness-browser-annotation.patch) 由宿主检出生成，不是手写文档：
+
+```powershell
+git -C ../harness-browser-integration diff HEAD --output docs/harness-browser-annotation.patch
+```
+
+生成后必须跑 `npm run verify:browser-patch` 确认它仍能应用到精确基线。
+生成产物不得入库到别处；`prepack` 会用它的哈希拦住不一致的包。