dsh-site-bridge 0.3.3 → 0.4.1

package/README.md

@@ -59,6 +59,20 @@ that code in the live page, so "it should work" becomes "it works here".
   focused (Chrome throttles only timers and animation there).
 - **No stored credentials** — see [Security](#security).
 
+### How this differs from browser automation plugins
+
+There are plugins that hand an agent `browser_*` tools: navigate, click, type, read the page. This is
+not one of them, even though it can do those things — input here is the instrument that verifies a
+capture, not the product.
+
+The product is the capture: the DOM with boxes and computed styles, theme CSS variables, selector
+candidates checked for uniqueness, and the site's own xhr/fetch calls with headers and bodies, all
+written to files an agent can read. Automation exists so that "this selector works" and "this BFF call
+passes with my cookies" are checked against the live page instead of assumed.
+
+The practical consequence: this plugin is built for writing an extension for one specific site, and
+the input tools exist to verify that work against the live page rather than to browse the web.
+
 ## Requirements
 
 - DeepSeek Harness with the `dsh` CLI and a profile (Desktop or Web).
@@ -69,6 +83,12 @@ that code in the live page, so "it should work" becomes "it works here".
 
 ### 1. Host half
 
+```powershell
+dsh plugin --profile desktop add dsh-site-bridge
+```
+
+That pulls the published package. From a local checkout instead:
+
 ```powershell
 # from the repository root
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
@@ -160,6 +180,13 @@ The wire protocol is small and documented in [docs/protocol.md](docs/protocol.md
   puts a secret under an unusual key, redaction will not recognise it. Treat a capture bundle as
   sensitive, exactly like any traffic dump.
 
+### Trust model
+
+The bridge accepts only requests that carry the pairing token. The extension asks for `debugger`
+instead of `<all_urls>` and does not inject a content script into every page. The cost is a pairing
+step and Chrome's debugging banner. In exchange the permission is granted per tab, for the duration
+of a session, and requests are read where they are made — no credential is copied out of the browser.
+
 ## Limitations
 
 Cross-origin iframes, closed shadow roots and body size caps are analysed in

package/README.ru.md

@@ -59,6 +59,20 @@ site_capture → captures/<host>/<timestamp>/
   фокусе (Chrome тротлит там только таймеры и анимации).
 - **Ничего не хранится из авторизации** — см. [Безопасность](#безопасность).
 
+### Чем это отличается от плагинов автоматизации браузера
+
+Есть плагины, которые дают агенту инструменты `browser_*`: навигация, клик, ввод, чтение страницы.
+Это не один из них, хотя всё перечисленное умеет: ввод здесь — инструмент проверки снимка, а не
+продукт.
+
+Продукт — снимок: DOM с боксами и computed-стилями, CSS-переменные темы, кандидаты селекторов с
+проверкой уникальности и собственные xhr/fetch сайта с заголовками и телами, разложенные по файлам,
+которые агент читает. Автоматизация нужна, чтобы «этот селектор работает» и «этот вызов BFF проходит
+с моими куками» проверялись на живой странице, а не предполагались.
+
+Практическое следствие: плагин сделан для написания расширения под конкретный сайт, а инструменты
+ввода нужны, чтобы проверять эту работу на живой странице, а не для браузинга.
+
 ## Требования
 
 - DeepSeek Harness с CLI `dsh` и профилем (Desktop или Web).
@@ -69,6 +83,12 @@ site_capture → captures/<host>/<timestamp>/
 
 ### 1. Host-половина
 
+```powershell
+dsh plugin --profile desktop add dsh-site-bridge
+```
+
+Это ставит опубликованный пакет. Из локального клона вместо этого:
+
 ```powershell
 # из корня репозитория
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
@@ -159,6 +179,13 @@ site_inject {js:"..."}          → выполнить ваш скрипт в с
   сайт кладёт секрет под нестандартным ключом, редакция его не узнает. Считайте пакет снимка
   чувствительным, как и любой дамп трафика.
 
+### Модель доверия
+
+Мост принимает только запросы с токеном сопряжения. Расширение просит `debugger`, а не
+`<all_urls>`, и не внедряет content script в каждую страницу. Цена — шаг сопряжения и плашка отладки
+Chrome. Взамен право выдаётся на вкладку и на время сессии, а запросы читаются там, где они сделаны:
+учётные данные не покидают браузер.
+
 ## Ограничения
 
 Кросс-доменные iframe, закрытые shadow-корни и лимиты тела разобраны в

package/README.zh-CN.md

@@ -47,6 +47,18 @@ site_capture → captures/<host>/<timestamp>/
 - **后台标签页可用** —— 标签页不在前台时，读取、点击、输入和截图仍然可用（Chrome 只在后台限制定时器与动画）。
 - **不保存任何凭据** —— 见[安全](#安全)。
 
+### 与浏览器自动化插件的区别
+
+有些插件给智能体提供 `browser_*` 工具：导航、点击、输入、读取页面。本项目不是其中之一，虽然这些都
+能做——这里的输入是用来验证抓取结果的工具，而不是产品本身。
+
+产品是抓取：带盒子与计算样式的 DOM、主题 CSS 变量、经过唯一性校验的选择器候选，以及站点自身的
+xhr/fetch（含请求头与请求体），全部写成智能体可读的文件。自动化的作用是让「这个选择器可用」和
+「这个 BFF 调用能带着我的 Cookie 通过」在活页面上被验证，而不是被假设。
+
+实际后果：本项目是为编写面向某个具体网站的扩展而做的，输入工具用来在活页面上验证这些工作，而不是
+用来浏览网页。
+
 ## 环境要求
 
 - 带 `dsh` CLI 与配置档（Desktop 或 Web）的 DeepSeek Harness。
@@ -57,6 +69,12 @@ site_capture → captures/<host>/<timestamp>/
 
 ### 1. 宿主部分
 
+```powershell
+dsh plugin --profile desktop add dsh-site-bridge
+```
+
+以上会安装已发布的 npm 包。从本地克隆安装则用：
+
 ```powershell
 # 在仓库根目录
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
@@ -129,6 +147,12 @@ site_inject {js:"..."}          → 在页面中执行你的脚本以验证
 - **仅回环。** 网桥只绑定 `127.0.0.1`，任何没有 32 字节配对令牌的请求都会被拒绝。`site_status` 打印的是令牌文件路径，而不是令牌本身。
 - **残余风险。** 请求头与请求体仍会经过 DSH 进程的内存。如果站点把密钥放在非常规字段名下，脱敏无法识别。请像对待任何流量转储一样，把快照包视为敏感数据。
 
+### 信任模型
+
+网桥只接受携带配对令牌的请求。扩展申请 `debugger` 而不是 `<all_urls>`，也不会向每个页面注入
+content script。代价是配对步骤与 Chrome 的调试提示条。换来的是：权限按标签页、按会话授予，请求在
+产生的地方被读取，凭据不离开浏览器。
+
 ## 限制
 
 跨域 iframe、封闭的 shadow root 与响应体大小上限在 [docs/limitations.md](docs/limitations.md) 中逐条分析 —— 包含代码位置、消除方案与预估成本。

package/extension/_locales/en/messages.json

@@ -1,50 +1,112 @@
 {
-  "appName": { "message": "DSH Site Bridge" },
+  "appName": {
+    "message": "DSH Site Bridge"
+  },
   "appDesc": {
     "message": "Hands and eyes for DeepSeek Harness in your own browser: page markup, BFF traffic, trusted input and a virtual cursor. Credentials stay in the browser."
   },
-  "tagline": { "message": "DeepSeek Harness in your browser" },
-
-  "statusConnecting": { "message": "Checking…" },
-  "statusConnected": { "message": "Bridge connected" },
-  "statusNoBridge": { "message": "Bridge not responding" },
+  "tagline": {
+    "message": "DeepSeek Harness in your browser"
+  },
+  "statusConnecting": {
+    "message": "Checking…"
+  },
+  "statusConnected": {
+    "message": "Bridge connected"
+  },
+  "statusNoBridge": {
+    "message": "Bridge not responding"
+  },
   "statusRetrying": {
     "message": "Waiting for the bridge… attempt $COUNT$",
-    "placeholders": { "count": { "content": "$1" } }
-  },
-  "statusNotConfigured": { "message": "Not configured" },
-  "statusWorkerDown": { "message": "Extension service is not responding" },
-  "errorToken": { "message": "Token does not match the bridge — import bridge.json again" },
-  "errorNoBridge": { "message": "DSH is not running, or the bridge is not listening on this port" },
-
-  "disconnect": { "message": "Disconnect" },
-  "targetNoneTitle": { "message": "No tab connected" },
-  "targetNoneUrl": { "message": "Open the page you need and connect it" },
-  "connectTab": { "message": "Connect this tab" },
-  "tabConnected": { "message": "Tab connected" },
-  "tabsLabel": { "message": "Tabs" },
-
-  "connectionTitle": { "message": "Pairing" },
-  "importBridge": { "message": "Import bridge.json" },
-  "portLabel": { "message": "Bridge port" },
-  "tokenLabel": { "message": "Token" },
-  "tokenPlaceholder": { "message": "paste the token or import the file" },
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "statusNotConfigured": {
+    "message": "Not configured"
+  },
+  "statusWorkerDown": {
+    "message": "Extension service is not responding"
+  },
+  "errorToken": {
+    "message": "Token does not match the bridge — import bridge.json again"
+  },
+  "errorNoBridge": {
+    "message": "DSH is not running, or the bridge is not listening on this port"
+  },
+  "disconnect": {
+    "message": "Disconnect"
+  },
+  "targetNoneTitle": {
+    "message": "No tab connected"
+  },
+  "targetNoneUrl": {
+    "message": "Open the page you need and connect it"
+  },
+  "connectTab": {
+    "message": "Connect this tab"
+  },
+  "tabConnected": {
+    "message": "Tab connected"
+  },
+  "tabsLabel": {
+    "message": "Tabs"
+  },
+  "connectionTitle": {
+    "message": "Pairing"
+  },
+  "importBridge": {
+    "message": "Import bridge.json"
+  },
+  "portLabel": {
+    "message": "Bridge port"
+  },
+  "tokenLabel": {
+    "message": "Token"
+  },
+  "tokenPlaceholder": {
+    "message": "paste the token or import the file"
+  },
   "tokenLength": {
     "message": "$COUNT$ characters",
-    "placeholders": { "count": { "content": "$1" } }
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "hintAutosave": {
+    "message": "Saved automatically, no buttons. Token file:"
+  },
+  "hintFile": {
+    "message": "~/.dsh/site-bridge/bridge.json"
+  },
+  "captureTitle": {
+    "message": "API recording"
   },
-  "hintAutosave": { "message": "Saved automatically, no buttons. Token file:" },
-  "hintFile": { "message": "~/.dsh/site-bridge/bridge.json" },
-
-  "captureTitle": { "message": "API recording" },
   "records": {
     "message": "$COUNT$ requests",
-    "placeholders": { "count": { "content": "$1" } }
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "captureStart": {
+    "message": "Start recording"
+  },
+  "captureStop": {
+    "message": "Stop recording"
+  },
+  "captureShortOn": {
+    "message": "API capture: on"
+  },
+  "captureShortOff": {
+    "message": "API capture: off"
   },
-  "captureStart": { "message": "Start recording" },
-  "captureStop": { "message": "Stop recording" },
-  "captureShortOn": { "message": "API capture: on" },
-  "captureShortOff": { "message": "API capture: off" },
   "bannerHintShort": {
     "message": "The “started debugging” banner in Chrome is expected: input and network capture run over it."
   },
@@ -54,15 +116,32 @@
   "bannerHint": {
     "message": "Chrome will show a “started debugging this browser” banner — that is expected: input and network capture run over it."
   },
-
-  "imported": { "message": "Settings imported" },
+  "imported": {
+    "message": "Settings imported"
+  },
   "importFailed": {
     "message": "Import failed: $ERROR$",
-    "placeholders": { "error": { "content": "$1" } }
+    "placeholders": {
+      "error": {
+        "content": "$1"
+      }
+    }
   },
   "claimFailed": {
     "message": "Could not connect: $ERROR$",
-    "placeholders": { "error": { "content": "$1" } }
+    "placeholders": {
+      "error": {
+        "content": "$1"
+      }
+    }
+  },
+  "claimFailedUnknown": {
+    "message": "unknown error"
+  },
+  "pickHint": {
+    "message": "Pick an element on the page"
   },
-  "claimFailedUnknown": { "message": "unknown error" }
+  "pickArmed": {
+    "message": "Click an element on the page — Enter adds a note, Esc cancels"
+  }
 }

package/extension/_locales/ru/messages.json

@@ -1,50 +1,112 @@
 {
-  "appName": { "message": "DSH Site Bridge" },
+  "appName": {
+    "message": "DSH Site Bridge"
+  },
   "appDesc": {
     "message": "Глаза и руки DeepSeek Harness в вашем браузере: разметка страницы, трафик BFF, доверенный ввод и виртуальный курсор. Авторизация остаётся в браузере."
   },
-  "tagline": { "message": "DeepSeek Harness в вашем браузере" },
-
-  "statusConnecting": { "message": "Проверяю…" },
-  "statusConnected": { "message": "Мост подключён" },
-  "statusNoBridge": { "message": "Мост не отвечает" },
+  "tagline": {
+    "message": "DeepSeek Harness в вашем браузере"
+  },
+  "statusConnecting": {
+    "message": "Проверяю…"
+  },
+  "statusConnected": {
+    "message": "Мост подключён"
+  },
+  "statusNoBridge": {
+    "message": "Мост не отвечает"
+  },
   "statusRetrying": {
     "message": "Подключаюсь к мосту… попытка $COUNT$",
-    "placeholders": { "count": { "content": "$1" } }
-  },
-  "statusNotConfigured": { "message": "Не настроен" },
-  "statusWorkerDown": { "message": "Служба расширения не отвечает" },
-  "errorToken": { "message": "Токен не совпал с мостом — импортируйте bridge.json заново" },
-  "errorNoBridge": { "message": "DSH не запущен или мост не слушает этот порт" },
-
-  "disconnect": { "message": "Отключить" },
-  "targetNoneTitle": { "message": "Вкладка не подключена" },
-  "targetNoneUrl": { "message": "Откройте нужную страницу и подключите её" },
-  "connectTab": { "message": "Подключить эту вкладку" },
-  "tabConnected": { "message": "Вкладка подключена" },
-  "tabsLabel": { "message": "Вкладки" },
-
-  "connectionTitle": { "message": "Подключение" },
-  "importBridge": { "message": "Импорт bridge.json" },
-  "portLabel": { "message": "Порт моста" },
-  "tokenLabel": { "message": "Токен" },
-  "tokenPlaceholder": { "message": "вставьте токен или импортируйте файл" },
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "statusNotConfigured": {
+    "message": "Не настроен"
+  },
+  "statusWorkerDown": {
+    "message": "Служба расширения не отвечает"
+  },
+  "errorToken": {
+    "message": "Токен не совпал с мостом — импортируйте bridge.json заново"
+  },
+  "errorNoBridge": {
+    "message": "DSH не запущен или мост не слушает этот порт"
+  },
+  "disconnect": {
+    "message": "Отключить"
+  },
+  "targetNoneTitle": {
+    "message": "Вкладка не подключена"
+  },
+  "targetNoneUrl": {
+    "message": "Откройте нужную страницу и подключите её"
+  },
+  "connectTab": {
+    "message": "Подключить эту вкладку"
+  },
+  "tabConnected": {
+    "message": "Вкладка подключена"
+  },
+  "tabsLabel": {
+    "message": "Вкладки"
+  },
+  "connectionTitle": {
+    "message": "Подключение"
+  },
+  "importBridge": {
+    "message": "Импорт bridge.json"
+  },
+  "portLabel": {
+    "message": "Порт моста"
+  },
+  "tokenLabel": {
+    "message": "Токен"
+  },
+  "tokenPlaceholder": {
+    "message": "вставьте токен или импортируйте файл"
+  },
   "tokenLength": {
     "message": "$COUNT$ символов",
-    "placeholders": { "count": { "content": "$1" } }
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "hintAutosave": {
+    "message": "Сохраняется само, без кнопок. Файл с токеном:"
+  },
+  "hintFile": {
+    "message": "~/.dsh/site-bridge/bridge.json"
+  },
+  "captureTitle": {
+    "message": "Запись API"
   },
-  "hintAutosave": { "message": "Сохраняется само, без кнопок. Файл с токеном:" },
-  "hintFile": { "message": "~/.dsh/site-bridge/bridge.json" },
-
-  "captureTitle": { "message": "Запись API" },
   "records": {
     "message": "$COUNT$ запросов",
-    "placeholders": { "count": { "content": "$1" } }
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "captureStart": {
+    "message": "Включить запись"
+  },
+  "captureStop": {
+    "message": "Остановить запись"
+  },
+  "captureShortOn": {
+    "message": "Запись API: вкл"
+  },
+  "captureShortOff": {
+    "message": "Запись API: выкл"
   },
-  "captureStart": { "message": "Включить запись" },
-  "captureStop": { "message": "Остановить запись" },
-  "captureShortOn": { "message": "Запись API: вкл" },
-  "captureShortOff": { "message": "Запись API: выкл" },
   "bannerHintShort": {
     "message": "Плашка «началась отладка» в Chrome — ожидаема: через неё идёт ввод и чтение сети."
   },
@@ -54,15 +116,32 @@
   "bannerHint": {
     "message": "Chrome покажет плашку «началась отладка» — это ожидаемо: через неё работает ввод и чтение сети."
   },
-
-  "imported": { "message": "Настройки импортированы" },
+  "imported": {
+    "message": "Настройки импортированы"
+  },
   "importFailed": {
     "message": "Импорт не удался: $ERROR$",
-    "placeholders": { "error": { "content": "$1" } }
+    "placeholders": {
+      "error": {
+        "content": "$1"
+      }
+    }
   },
   "claimFailed": {
     "message": "Не удалось подключить: $ERROR$",
-    "placeholders": { "error": { "content": "$1" } }
+    "placeholders": {
+      "error": {
+        "content": "$1"
+      }
+    }
+  },
+  "claimFailedUnknown": {
+    "message": "неизвестная ошибка"
+  },
+  "pickHint": {
+    "message": "Выбрать элемент на странице"
   },
-  "claimFailedUnknown": { "message": "неизвестная ошибка" }
+  "pickArmed": {
+    "message": "Кликните по элементу на странице — Enter добавит примечание, Esc отменит"
+  }
 }

package/extension/_locales/zh_CN/messages.json

@@ -1,50 +1,112 @@
 {
-  "appName": { "message": "DSH Site Bridge" },
+  "appName": {
+    "message": "DSH Site Bridge"
+  },
   "appDesc": {
     "message": "在您自己的浏览器中为 DeepSeek Harness 提供眼睛和双手：页面结构、BFF 流量、可信输入和虚拟光标。凭据始终留在浏览器中。"
   },
-  "tagline": { "message": "DeepSeek Harness 在您的浏览器中" },
-
-  "statusConnecting": { "message": "正在检查…" },
-  "statusConnected": { "message": "网桥已连接" },
-  "statusNoBridge": { "message": "网桥无响应" },
+  "tagline": {
+    "message": "DeepSeek Harness 在您的浏览器中"
+  },
+  "statusConnecting": {
+    "message": "正在检查…"
+  },
+  "statusConnected": {
+    "message": "网桥已连接"
+  },
+  "statusNoBridge": {
+    "message": "网桥无响应"
+  },
   "statusRetrying": {
     "message": "正在连接网桥… 第 $COUNT$ 次",
-    "placeholders": { "count": { "content": "$1" } }
-  },
-  "statusNotConfigured": { "message": "尚未配置" },
-  "statusWorkerDown": { "message": "扩展服务未响应" },
-  "errorToken": { "message": "令牌与网桥不匹配——请重新导入 bridge.json" },
-  "errorNoBridge": { "message": "DSH 未运行，或网桥未监听该端口" },
-
-  "disconnect": { "message": "断开" },
-  "targetNoneTitle": { "message": "未连接标签页" },
-  "targetNoneUrl": { "message": "打开需要的页面并连接它" },
-  "connectTab": { "message": "连接此标签页" },
-  "tabConnected": { "message": "标签页已连接" },
-  "tabsLabel": { "message": "标签页" },
-
-  "connectionTitle": { "message": "配对" },
-  "importBridge": { "message": "导入 bridge.json" },
-  "portLabel": { "message": "网桥端口" },
-  "tokenLabel": { "message": "令牌" },
-  "tokenPlaceholder": { "message": "粘贴令牌或导入文件" },
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "statusNotConfigured": {
+    "message": "尚未配置"
+  },
+  "statusWorkerDown": {
+    "message": "扩展服务未响应"
+  },
+  "errorToken": {
+    "message": "令牌与网桥不匹配——请重新导入 bridge.json"
+  },
+  "errorNoBridge": {
+    "message": "DSH 未运行，或网桥未监听该端口"
+  },
+  "disconnect": {
+    "message": "断开"
+  },
+  "targetNoneTitle": {
+    "message": "未连接标签页"
+  },
+  "targetNoneUrl": {
+    "message": "打开需要的页面并连接它"
+  },
+  "connectTab": {
+    "message": "连接此标签页"
+  },
+  "tabConnected": {
+    "message": "标签页已连接"
+  },
+  "tabsLabel": {
+    "message": "标签页"
+  },
+  "connectionTitle": {
+    "message": "配对"
+  },
+  "importBridge": {
+    "message": "导入 bridge.json"
+  },
+  "portLabel": {
+    "message": "网桥端口"
+  },
+  "tokenLabel": {
+    "message": "令牌"
+  },
+  "tokenPlaceholder": {
+    "message": "粘贴令牌或导入文件"
+  },
   "tokenLength": {
     "message": "$COUNT$ 个字符",
-    "placeholders": { "count": { "content": "$1" } }
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "hintAutosave": {
+    "message": "自动保存，无需按钮。令牌文件："
+  },
+  "hintFile": {
+    "message": "~/.dsh/site-bridge/bridge.json"
+  },
+  "captureTitle": {
+    "message": "API 录制"
   },
-  "hintAutosave": { "message": "自动保存，无需按钮。令牌文件：" },
-  "hintFile": { "message": "~/.dsh/site-bridge/bridge.json" },
-
-  "captureTitle": { "message": "API 录制" },
   "records": {
     "message": "$COUNT$ 条请求",
-    "placeholders": { "count": { "content": "$1" } }
+    "placeholders": {
+      "count": {
+        "content": "$1"
+      }
+    }
+  },
+  "captureStart": {
+    "message": "开始录制"
+  },
+  "captureStop": {
+    "message": "停止录制"
+  },
+  "captureShortOn": {
+    "message": "接口录制：开"
+  },
+  "captureShortOff": {
+    "message": "接口录制：关"
   },
-  "captureStart": { "message": "开始录制" },
-  "captureStop": { "message": "停止录制" },
-  "captureShortOn": { "message": "接口录制：开" },
-  "captureShortOff": { "message": "接口录制：关" },
   "bannerHintShort": {
     "message": "Chrome 的「已开始调试」提示条是正常的：输入与网络抓取都通过它进行。"
   },
@@ -54,15 +116,32 @@
   "bannerHint": {
     "message": "Chrome 会显示「已开始调试此浏览器」提示条——这是正常的：输入和网络抓取都通过它进行。"
   },
-
-  "imported": { "message": "设置已导入" },
+  "imported": {
+    "message": "设置已导入"
+  },
   "importFailed": {
     "message": "导入失败：$ERROR$",
-    "placeholders": { "error": { "content": "$1" } }
+    "placeholders": {
+      "error": {
+        "content": "$1"
+      }
+    }
   },
   "claimFailed": {
     "message": "连接失败：$ERROR$",
-    "placeholders": { "error": { "content": "$1" } }
+    "placeholders": {
+      "error": {
+        "content": "$1"
+      }
+    }
+  },
+  "claimFailedUnknown": {
+    "message": "未知错误"
+  },
+  "pickHint": {
+    "message": "在页面上选择元素"
   },
-  "claimFailedUnknown": { "message": "未知错误" }
+  "pickArmed": {
+    "message": "点击页面上的元素 — Enter 添加备注，Esc 取消"
+  }
 }

package/extension/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "default_locale": "en",
   "name": "__MSG_appName__",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "__MSG_appDesc__",
   "minimum_chrome_version": "116",
   "permissions": [

package/extension/popup.html

@@ -78,6 +78,13 @@
       button.primary:hover:not(:disabled) { background: #6b8aff; border-color: #6b8aff; }
       button.primary:disabled { background: #20242d; border-color: var(--line); color: var(--muted); font-weight: 500; }
       button.ghost { padding: 3px 8px; font-size: 11px; background: transparent; color: var(--muted); }
+      button.icon {
+        display: inline-flex; align-items: center; justify-content: center;
+        padding: 4px; width: 26px; height: 26px; background: transparent;
+        border: 1px solid var(--line); border-radius: 6px; color: var(--muted);
+      }
+      button.icon:hover:not(:disabled) { color: var(--text); border-color: #3a4150; }
+      button.icon.active { color: var(--accent); border-color: var(--accent); }
       button.ghost:hover:not(:disabled) { color: var(--text); }
       button.link {
         padding: 0; border: none; background: none; color: var(--accent);
@@ -132,7 +139,12 @@
     <section class="card">
       <div class="card-head">
         <span class="pill"><i class="dot" id="dot"></i><i class="spin" id="spin" hidden></i><span id="connection-text" data-i18n="statusConnecting">Проверяю…</span></span>
-        <button class="ghost" id="release" hidden data-i18n="disconnect">Отключить</button>
+        <span style="display:flex;gap:6px;align-items:center">
+          <button class="icon" id="pick" data-i18n-title="pickHint" title="Pick an element">
+            <svg width="14" height="14" viewBox="0 0 20 20" aria-hidden="true"><path d="M3 2 L3 16 L7.2 12.2 L9.6 17.6 L12.2 16.4 L9.8 11.2 L15 11.2 Z" fill="currentColor"/></svg>
+          </button>
+          <button class="ghost" id="release" hidden data-i18n="disconnect">Отключить</button>
+        </span>
       </div>
 
       <div class="target empty" id="target-block">

package/extension/popup.js

@@ -19,6 +19,10 @@ function applyLocale() {
     const message = t(node.dataset.i18n)
     if (message && message !== node.dataset.i18n) node.textContent = message
   }
+  for (const node of document.querySelectorAll('[data-i18n-title]')) {
+    const message = t(node.dataset.i18nTitle)
+    if (message && message !== node.dataset.i18nTitle) node.title = message
+  }
   for (const node of document.querySelectorAll('[data-i18n-placeholder]')) {
     const message = t(node.dataset.i18nPlaceholder)
     if (message && message !== node.dataset.i18nPlaceholder) node.placeholder = message
@@ -117,6 +121,10 @@ function render(status) {
   claim.textContent = hasTarget ? t('tabConnected') : t('connectTab')
   release.hidden = !hasTarget
 
+  const pick = $('pick')
+  pick.classList.toggle('active', status.picking === true)
+  pick.disabled = !connected || !hasTarget
+
   capture.disabled = !connected
   capture.textContent = status.recording ? t('captureShortOn') : t('captureShortOff')
   $('captured').textContent = t('records', [String(status.captured || 0)])
@@ -243,6 +251,22 @@ $('release').addEventListener('click', async () => {
   await refresh()
 })
 
+$('pick').addEventListener('click', async () => {
+  const status = await send({ type: 'status' })
+  if (status?.picking) {
+    await send({ type: 'release' }).catch(() => {})
+    await refresh()
+    return
+  }
+  const result = await send({ type: 'pick-arm' })
+  if (!result?.ok) {
+    setNote(String(result?.error ?? 'pick failed'), true)
+    return
+  }
+  setNote(t('pickArmed'))
+  await refresh()
+})
+
 $('tabs-select').addEventListener('change', async (event) => {
   const tabId = Number(event.target.value)
   if (!Number.isFinite(tabId)) return

package/extension/sw.js

@@ -194,9 +194,17 @@ async function handleMessageInner(message) {
         captured: session.entries.length
       })),
       recording: active?.recording ?? false,
-      captured: active?.entries.length ?? 0
+      captured: active?.entries.length ?? 0,
+      picking: active?.picking === true,
+      picks: active?.picks?.length ?? 0
     }
   }
+  if (message?.type === 'pick-arm') {
+    const session = requireSession(message.tabId)
+    await armPicker(session.tabId)
+    session.picking = true
+    return { ok: true, picking: true }
+  }
   if (message?.type === 'save') {
     await chrome.storage.local.set({ port: Number(message.port) || 47321, token: String(message.token || '') })
     state.lastPollOk = 0
@@ -252,7 +260,9 @@ async function attach(tabId) {
     tabId,
     target: { id: tab.id, url: tab.url, title: tab.title },
     recording: false,
-    entries: []
+    entries: [],
+    picking: false,
+    picks: []
   }
   state.sessions.set(tabId, session)
   state.activeTabId = tabId
@@ -426,6 +436,235 @@ async function setRecording(session, on) {
   return session.recording
 }
 
+/* ------------------------------------------------------------------ picker */
+
+/**
+ * Injected into the page: highlights the element under the cursor, and on click
+ * asks for a note, then publishes the result on `window.__dshPickResult`.
+ * Enter saves, Shift+Enter adds a line, Escape cancels the whole pick.
+ */
+function pickerInPage() {
+  const HOST_ID = '__dsh_pick_overlay__'
+  document.getElementById(HOST_ID)?.remove()
+  window.__dshPickResult = null
+
+  const box = document.createElement('div')
+  box.id = HOST_ID
+  box.style.cssText = [
+    'position:fixed', 'left:0', 'top:0', 'width:0', 'height:0', 'z-index:2147483646',
+    'pointer-events:none', 'border:2px solid #5b7cff', 'border-radius:4px',
+    'background:rgba(91,124,255,.12)'
+  ].join(';')
+
+  const tip = document.createElement('div')
+  tip.style.cssText = [
+    'position:fixed', 'z-index:2147483647', 'pointer-events:none', 'background:#14161b',
+    'color:#e8eaf0', 'border:1px solid #2a2f3a', 'border-radius:4px', 'padding:2px 6px',
+    'font:11px/1.5 monospace', 'max-width:70vw', 'white-space:nowrap', 'overflow:hidden',
+    'text-overflow:ellipsis'
+  ].join(';')
+  tip.hidden = true
+  document.documentElement.append(box, tip)
+
+  const cssEsc = (value) => (window.CSS && CSS.escape ? CSS.escape(value) : String(value).replace(/[^a-zA-Z0-9_-]/g, '\\$&'))
+  const count = (selector) => {
+    try { return document.querySelectorAll(selector).length } catch { return -1 }
+  }
+
+  function selectorFor(el) {
+    const candidates = []
+    if (el.id) candidates.push('#' + cssEsc(el.id))
+    for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+      const value = el.getAttribute(attr)
+      if (value) candidates.push('[' + attr + '="' + value.replace(/"/g, '\\"') + '"]')
+    }
+    if (el.getAttribute('name')) {
+      candidates.push(el.tagName.toLowerCase() + '[name="' + el.getAttribute('name').replace(/"/g, '\\"') + '"]')
+    }
+    if (el.getAttribute('aria-label')) {
+      candidates.push('[aria-label="' + el.getAttribute('aria-label').replace(/"/g, '\\"') + '"]')
+    }
+    const classes = [...el.classList].filter((name) => /^[a-zA-Z][\w-]{2,}$/.test(name)).slice(0, 2)
+    if (classes.length > 0) {
+      candidates.push(el.tagName.toLowerCase() + classes.map((name) => '.' + cssEsc(name)).join(''))
+    }
+    const parts = []
+    let current = el
+    while (current && current.nodeType === 1 && parts.length < 8) {
+      let part = current.tagName.toLowerCase()
+      if (current.id) { parts.unshift('#' + cssEsc(current.id)); break }
+      const parent = current.parentElement
+      if (parent) {
+        const siblings = [...parent.children].filter((node) => node.tagName === current.tagName)
+        if (siblings.length > 1) part += ':nth-of-type(' + (siblings.indexOf(current) + 1) + ')'
+      }
+      parts.unshift(part)
+      current = parent
+    }
+    candidates.push(parts.join(' > '))
+    const unique = candidates.find((selector) => count(selector) === 1)
+    return unique ?? candidates[candidates.length - 1]
+  }
+
+  function xpathFor(el) {
+    if (el.id && count('#' + cssEsc(el.id)) === 1) return '//*[@id="' + el.id + '"]'
+    const parts = []
+    let current = el
+    while (current && current.nodeType === 1) {
+      let index = 1
+      let sibling = current.previousElementSibling
+      while (sibling) {
+        if (sibling.tagName === current.tagName) index += 1
+        sibling = sibling.previousElementSibling
+      }
+      const total = current.parentElement
+        ? [...current.parentElement.children].filter((node) => node.tagName === current.tagName).length
+        : 1
+      parts.unshift(current.tagName.toLowerCase() + (total > 1 ? '[' + index + ']' : ''))
+      current = current.parentElement
+    }
+    return '/' + parts.join('/')
+  }
+
+  let panel = null
+  let hovered = null
+
+  function highlight(el) {
+    const rect = el.getBoundingClientRect()
+    box.style.left = rect.left + 'px'
+    box.style.top = rect.top + 'px'
+    box.style.width = rect.width + 'px'
+    box.style.height = rect.height + 'px'
+    tip.textContent = el.tagName.toLowerCase() + (el.id ? '#' + el.id : '')
+    tip.hidden = false
+    tip.style.left = Math.max(4, Math.min(rect.left, window.innerWidth - 40)) + 'px'
+    tip.style.top = Math.max(2, rect.top - 20) + 'px'
+  }
+
+  function hideBox() {
+    box.style.width = '0'
+    box.style.height = '0'
+    tip.hidden = true
+  }
+
+  function onMove(event) {
+    if (panel) return
+    const el = document.elementFromPoint(event.clientX, event.clientY)
+    if (!el || el === box || el === tip || (panel && panel.contains(el))) return
+    hovered = el
+    highlight(el)
+  }
+
+  function onClick(event) {
+    if (panel) return
+    event.preventDefault()
+    event.stopPropagation()
+    event.stopImmediatePropagation()
+    if (hovered) askNote(hovered)
+  }
+
+  function onKey(event) {
+    if (event.key === 'Escape' && !panel) finish(null, true)
+  }
+
+  function askNote(el) {
+    const rect = el.getBoundingClientRect()
+    panel = document.createElement('div')
+    panel.style.cssText = [
+      'position:fixed', 'z-index:2147483647', 'background:#14161b', 'color:#e8eaf0',
+      'border:1px solid #5b7cff', 'border-radius:8px', 'padding:8px', 'width:260px',
+      'font:12px/1.45 "Segoe UI",system-ui,sans-serif', 'box-shadow:0 8px 24px rgba(0,0,0,.45)'
+    ].join(';')
+    panel.style.left = Math.max(8, Math.min(rect.left, window.innerWidth - 272)) + 'px'
+    panel.style.top = Math.min(window.innerHeight - 120, Math.max(8, rect.bottom + 8)) + 'px'
+
+    const hint = document.createElement('div')
+    hint.textContent = 'Note — Enter to save, Esc to cancel'
+    hint.style.cssText = 'color:#99a1ae;font-size:11px;margin-bottom:4px'
+
+    const input = document.createElement('textarea')
+    input.placeholder = 'what is this element for?'
+    input.style.cssText = 'width:100%;height:46px;resize:none;background:#15181e;color:#e8eaf0;border:1px solid #2a2f3a;border-radius:6px;padding:5px;font:inherit'
+
+    panel.append(hint, input)
+    document.documentElement.appendChild(panel)
+    input.focus()
+
+    input.addEventListener('mousedown', (event) => event.stopPropagation())
+    input.addEventListener('click', (event) => event.stopPropagation())
+    input.addEventListener('keydown', (event) => {
+      event.stopPropagation()
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        closePanel()
+      }
+      if (event.key === 'Enter' && !event.shiftKey) {
+        event.preventDefault()
+        finish(el, false, input.value.trim())
+      }
+    })
+  }
+
+  function closePanel() {
+    panel?.remove()
+    panel = null
+  }
+
+  function cleanup() {
+    document.removeEventListener('mousemove', onMove, true)
+    document.removeEventListener('click', onClick, true)
+    document.removeEventListener('keydown', onKey, true)
+    box.remove()
+    tip.remove()
+    closePanel()
+    window.__dshPicker = null
+  }
+
+  function finish(el, cancelled, note) {
+    const rect = el ? el.getBoundingClientRect() : null
+    closePanel()
+    cleanup()
+    window.__dshPickResult = cancelled || !el
+      ? { cancelled: true }
+      : {
+          selector: selectorFor(el),
+          xpath: xpathFor(el),
+          text: (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 160),
+          tag: el.tagName.toLowerCase(),
+          note: note || '',
+          rect: { x: Math.round(rect.left), y: Math.round(rect.top), w: Math.round(rect.width), h: Math.round(rect.height) },
+          url: location.href,
+          at: Date.now()
+        }
+  }
+
+  hideBox()
+  document.addEventListener('mousemove', onMove, true)
+  document.addEventListener('click', onClick, true)
+  document.addEventListener('keydown', onKey, true)
+  window.__dshPicker = { stop: () => finish(null, true) }
+  return true
+}
+
+async function armPicker(tabId) {
+  await cdp('Runtime.evaluate', { expression: `(${pickerInPage.toString()})()`, returnByValue: true }, tabId)
+}
+
+async function stopPicker(tabId) {
+  await cdp('Runtime.evaluate', {
+    expression: 'window.__dshPicker && window.__dshPicker.stop ? window.__dshPicker.stop() : null',
+    returnByValue: true
+  }, tabId).catch(() => {})
+}
+
+async function readPick(tabId) {
+  const { result } = await cdp('Runtime.evaluate', {
+    expression: 'window.__dshPickResult || null',
+    returnByValue: true
+  }, tabId)
+  return result?.value ?? null
+}
+
 /* ------------------------------------------------------------------ cursor */
 
 const CURSOR_ID = '__dsh_site_bridge_cursor__'
@@ -877,6 +1116,25 @@ function snapshotInPage(options) {
     return parts.join(' > ')
   }
 
+  function xpathFor(el) {
+    const parts = []
+    let current = el
+    while (current && current.nodeType === 1) {
+      let index = 1
+      let sibling = current.previousElementSibling
+      while (sibling) {
+        if (sibling.tagName === current.tagName) index += 1
+        sibling = sibling.previousElementSibling
+      }
+      const total = current.parentElement
+        ? [...current.parentElement.children].filter((node) => node.tagName === current.tagName).length
+        : 1
+      parts.unshift(current.tagName.toLowerCase() + (total > 1 ? '[' + index + ']' : ''))
+      current = current.parentElement
+    }
+    return '/' + parts.join('/')
+  }
+
   // Everything is resolved inside `scope` (document or shadow root), and the
   // result is prefixed with the chain that reaches that scope.
   function candidates(el, scope, prefix) {
@@ -931,6 +1189,7 @@ function snapshotInPage(options) {
       vis: visible,
       d: depth,
       frame: prefix === '' ? null : prefix.replace(/ >>> $/, ''),
+      xpath: xpathFor(el),
       sel: candidates(el, scope, prefix)
     }
     nodes.push(node)
@@ -1109,6 +1368,54 @@ async function dispatch(op, args) {
       await evt('netclear', { tabId: session.tabId })
       return { captured: 0 }
     }
+    case 'pick.arm': {
+      const session = requireSession(args.tabId)
+      await armPicker(session.tabId)
+      session.picking = true
+      return { picking: true, tabId: session.tabId }
+    }
+    case 'pick.wait': {
+      const session = requireSession(args.tabId)
+      await armPicker(session.tabId)
+      session.picking = true
+      const deadline = Date.now() + Math.min(Number(args.timeoutMs ?? 60000), 120000)
+      while (Date.now() < deadline) {
+        const pick = await readPick(session.tabId)
+        if (pick) {
+          session.picking = false
+          if (pick.cancelled) throw new Error('выбор элемента отменён')
+          session.picks = [...(session.picks ?? []), pick].slice(-20)
+          await evt('pick', { tabId: session.tabId, pick })
+          return { pick }
+        }
+        await sleep(250)
+      }
+      session.picking = false
+      await stopPicker(session.tabId)
+      throw new Error('элемент не выбран за отведённое время')
+    }
+    case 'pick.last': {
+      const session = requireSession(args.tabId)
+      // A pick armed from the popup lands in the page, not in the queue: pull it
+      // in the first time someone asks for it.
+      const fresh = await readPick(session.tabId).catch(() => null)
+      if (fresh && !fresh.cancelled) {
+        session.picks = [...(session.picks ?? []), fresh].slice(-20)
+        session.picking = false
+        await cdp('Runtime.evaluate', { expression: 'window.__dshPickResult = null', returnByValue: true }, session.tabId).catch(() => {})
+      }
+      return { pick: session.picks?.[session.picks.length - 1] ?? null }
+    }
+    case 'pick.list': {
+      const session = requireSession(args.tabId)
+      return { picks: session.picks ?? [] }
+    }
+    case 'pick.stop': {
+      const session = requireSession(args.tabId)
+      session.picking = false
+      await stopPicker(session.tabId)
+      return { picking: false }
+    }
     case 'net.list': {
       const session = requireSession(args.tabId)
       const query = String(args.query ?? '').toLowerCase()

package/lib/index.js

@@ -17,7 +17,7 @@
  */
 import { homedir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
-import { mkdir, writeFile } from 'node:fs/promises'
+import { appendFile, mkdir, writeFile } from 'node:fs/promises'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { Bridge, loadOrCreateCredentials } from './bridge.js'
 import { writeBundle } from './artifacts.js'
@@ -596,6 +596,63 @@ export function apply(ctx, config) {
     )
   )
 
+  ctx.tools.register(
+    tool(
+      'site_pick',
+      'Выбор элемента человеком: в странице включается подсветка под курсором, клик по элементу просит примечание ' +
+      'и возвращает устойчивый CSS-селектор, XPath, текст и бокс. Результат дописывается в captures/picks.jsonl. ' +
+      'Полезно, когда агенту нужно понять, о каком элементе говорит пользователь.',
+      {
+        action: { type: 'string', description: 'wait (по умолчанию) | last | list' },
+        timeoutMs: { type: 'number', description: 'Сколько ждать клика для action=wait (по умолчанию 90000)' },
+        tab: { type: 'number', description: 'id вкладки (по умолчанию активная)' }
+      },
+      async (args, exec) => {
+        const instance = await ensureBridge()
+        const target = pickTarget(instance, args.tab)
+        const action = String(args.action ?? 'wait')
+
+        if (action === 'last' || action === 'list') {
+          const result = await instance.enqueue(action === 'last' ? 'pick.last' : 'pick.list', { ...tabArgs(args) }, { timeout: 20000 })
+          const picks = action === 'last' ? (result?.pick ? [result.pick] : []) : result?.picks ?? []
+          if (picks.length === 0) return ok('Пока ничего не выбрано.', { picks: [] })
+          const lines = picks.map(
+            (pick) => `· ${pick.selector}  →  ${pick.xpath}${pick.note ? `  («${pick.note}»)` : ''}`
+          )
+          return ok(`Выбранные элементы (${picks.length}):\n${lines.join('\n')}`, { picks })
+        }
+
+        const timeoutMs = Math.min(Number(args.timeoutMs ?? 90000), 120000)
+        const result = await instance.enqueue(
+          'pick.wait',
+          { timeoutMs, ...tabArgs(args) },
+          { timeout: timeoutMs + 15000 }
+        )
+        const pick = result?.pick
+        if (!pick) throw new Error('выбор не вернул результат')
+
+        const root = await captureRoot('', exec)
+        await mkdir(root, { recursive: true })
+        await appendFile(
+          join(root, 'picks.jsonl'),
+          `${JSON.stringify({ at: new Date().toISOString(), url: target?.url ?? pick.url, ...pick })}\n`,
+          'utf8'
+        )
+
+        return ok(
+          [
+            `Выбран элемент «${pick.tag}»: ${pick.selector}`,
+            `XPath: ${pick.xpath}`,
+            `Текст: ${truncate(pick.text || '—', 160)}`,
+            `Примечание: ${pick.note || '—'}`,
+            `Записано в ${join(root, 'picks.jsonl')}`
+          ].join('\n'),
+          { pick }
+        )
+      }
+    )
+  )
+
   if (settings.autoStart) {
     void ensureBridge().catch((error) => {
       ctx.logger?.warn?.(`[dsh-site-bridge] bridge did not start: ${String(error?.message ?? error)}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-site-bridge",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Chrome/Edge MV3 bridge for DeepSeek Harness: capture page markup (DOM, styles, selectors) and BFF traffic (xhr/fetch with headers and bodies) into a workspace snapshot bundle, drive the page with trusted CDP input, and verify injected scripts. Authorization never leaves the browser and is never written to disk.",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,7 +39,8 @@
     "icons": "node tools/make-icons.mjs",
     "version:check": "node tools/version.mjs check",
     "version:bump": "node tools/version.mjs bump",
-    "stage": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 -StageOnly"
+    "stage": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 -StageOnly",
+    "test:picker": "node test/picker.mjs"
   },
   "dsh": {
     "bundle": {