dsh-site-bridge 0.0.0-stage → 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 k4 (kesha4)
+
+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,214 @@
-# Temporary Holding Version
+# dsh-site-bridge
 
-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.
+**English** · [Русский](README.ru.md) · [中文](README.zh-CN.md)
+
+**Hands and eyes for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) in your own browser.**
+Capture a page's markup and its BFF traffic into files an agent can read, drive the page with trusted
+input, and verify the extension you just wrote — live, in the same tab.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Two halves, one bridge:
+
+| Half | What it does |
+|---|---|
+| **DSH plugin** (`lib/`) | Owns the loopback bridge and exposes eight tools to the model. Writes the snapshot bundle into the session workspace. |
+| **MV3 extension** (`extension/`) | Lives in your Chrome/Edge profile, works with your cookies, captures markup and network over CDP, drives the page with real input events. Localized: English, Русский, 中文. |
+
+Neither half is useful alone: the plugin holds the model-facing surface and the files, the extension
+holds the browser session and the fidelity.
+
+---
+
+## Why
+
+Writing an extension that embeds into someone else's site is mostly archaeology: what the markup is
+actually made of, which selector survives the next deploy, and which BFF endpoint this button calls
+with which payload. By hand that means DevTools, copy-paste and guesses.
+
+This project turns the archaeology into a capture:
+
+```
+site_capture → captures/<host>/<timestamp>/
+  dom.html          serialized markup of the captured scope
+  dom.json          element tree: boxes, attributes, selector candidates
+  styles.json       computed styles of key nodes + CSS custom properties
+  selectors.md      shortlist of stable selectors, with why each is stable
+  network.jsonl     every captured xhr/fetch, one JSON object per line
+  api.md            endpoints grouped by method+path, with request/response contracts
+  screenshot.png    optional full-page render
+```
+
+The agent reads those files like any other source and writes the extension. Then `site_inject` runs
+that code in the live page, so "it should work" becomes "it works here".
+
+## Features
+
+- **Markup** — element tree with boxes and visibility, computed styles of interactive nodes, CSS
+  variables of the theme, and selector candidates ranked by stability (`data-testid` > `id` > `name` >
+  `aria-label` > class path > positional path), each checked for uniqueness against the live DOM.
+- **BFF traffic** — `xhr`/`fetch` with method, status, request headers, request body, response
+  headers and response body, scoped to the inspected site.
+- **Trusted input** — clicks, typing, select, key presses, scrolling and file uploads through CDP
+  `Input.*` / `DOM.setFileInputFiles`: events the page cannot tell apart from a human's.
+- **Virtual cursor** — a DOM overlay that moves to the target plus a real mouse event at those
+  coordinates, for controls that ignore synthetic `click()`.
+- **Deep selectors** — `host >>> inner` resolves through open shadow roots and same-origin iframes;
+  click coordinates are corrected for frame offsets.
+- **Works in background tabs** — reading, clicking, typing and screenshots work while the tab is not
+  focused (Chrome throttles only timers and animation there).
+- **No stored credentials** — see [Security](#security).
+
+## Requirements
+
+- DeepSeek Harness with the `dsh` CLI and a profile (Desktop or Web).
+- Chrome or Edge 125+ (the extension uses `chrome.debugger` and MV3 service workers).
+- Node.js 22+ for the tooling in `tools/` and for the tests.
+
+## Install
+
+### 1. Host half
+
+```powershell
+# from the repository root
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
+```
+
+The script links the plugin into your profile, adds it to `dsh.profile.bundles`, and stages the
+extension into `%USERPROFILE%\.dsh\site-bridge\extension`. Manual equivalent:
+
+```powershell
+dsh plugin --profile desktop add <path-to-this-repo>
+```
+
+Add `"dsh-site-bridge"` to `dsh.profile.bundles` in `%USERPROFILE%\.dsh\profiles\desktop\package.json`
+if the CLI did not, then restart DSH — the host half loads at profile start.
+
+### 2. Browser half
+
+1. `chrome://extensions` → enable **Developer mode** → **Load unpacked** →
+   `%USERPROFILE%\.dsh\site-bridge\extension`.
+2. Open the popup. It shows the port and the path to `bridge.json` (the same is printed by
+   `site_status`).
+3. Click **Import bridge.json** (`Импорт bridge.json` / `导入 bridge.json`) and pick that file, or
+   paste the token — it saves itself, no button.
+4. Open the page you want to work on and click **Connect this tab**.
+
+Chrome shows the "started debugging this browser" banner: that is the CDP session everything runs
+on. It disappears when you press **Disconnect**.
+
+The popup UI follows the browser language: English, Russian and Simplified Chinese ship in
+`extension/_locales`.
+
+## Usage
+
+```text
+site_status                     → bridge state, pairing path, current tab
+site_tabs {action:"list"}       → tabs; {action:"claim", tabId} binds one
+site_network {action:"start"}   → begin recording, then act on the page
+site_capture {screenshot:true}  → write the bundle into the workspace
+site_act {steps:"[...]"}        → click/fill/type/select/press/scroll/upload/wait/eval
+site_cursor {x,y,click:true}    → virtual cursor, real mouse event
+site_shot {fullPage:true}       → screenshot to captures/shots/*.png
+site_inject {js:"..."}          → run your script in the page to verify it
+```
+
+A typical loop for writing a page-embedded extension:
+
+1. `site_tabs` → bind the page.
+2. `site_capture` → read `selectors.md`, `styles.json`, `api.md`.
+3. Write the userscript / content script in your own repository.
+4. `site_inject` with the script body → check that the anchor is found and the BFF call passes with
+   the browser's cookies.
+5. Iterate on the selectors the capture marked as fragile.
+
+## Architecture
+
+```
+┌──────────────────────────── DSH host ────────────────────────────┐
+│  tools (site_*)  ──►  bridge: 127.0.0.1, token, long-poll queue    │
+│  redaction on ingest ──► in-memory buffer ──► artifacts writer     │
+└───────────────────────────────┬───────────────────────────────────┘
+                                │ HTTP long-poll (no websocket)
+┌───────────────────────────────┴───────────────────────────────────┐
+│  MV3 service worker: chrome.debugger ──► CDP                        │
+│    Network domain  → requests with headers and bodies              │
+│    Input domain    → trusted mouse/keyboard, file uploads          │
+│    Runtime domain  → DOM snapshot, selectors, injected scripts     │
+│  popup: pairing, target tab, capture toggle (ru / en / zh)         │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+The wire protocol is small and documented in [docs/protocol.md](docs/protocol.md).
+
+## Security
+
+- **Credentials never leave the browser.** The extension does not read cookies or tokens: the page
+  makes its own requests and the browser attaches them. The bridge sees them in flight, but values of
+  `cookie`, `authorization`, `x-csrf-token`, `x-api-key`, `set-cookie` and similar headers,
+  credential-shaped query parameters and credential-shaped JSON/form fields are replaced with
+  `«redacted»` **on ingest** — before anything is stored.
+- **Nothing credential-shaped is written to disk.** Header *names* are kept, because "this endpoint
+  needs `x-csrf-token`" is part of the contract; the value is not.
+- **Capture is site-scoped.** Only the inspected site's own `xhr`/`fetch` (same host, same
+  registrable domain, or third-party JSON) is recorded. Telemetry and security agents that POST a full
+  page dump to their servers are filtered out — otherwise page source with inline tokens would land in
+  the bundle.
+- **Loopback only.** The bridge binds `127.0.0.1` and rejects any request without the 32-byte pairing
+  token. `site_status` prints the path to the token file, not the token.
+- **Residual risk.** Header values and bodies still pass through the DSH process in memory. If a site
+  puts a secret under an unusual key, redaction will not recognise it. Treat a capture bundle as
+  sensitive, exactly like any traffic dump.
+
+## Limitations
+
+Cross-origin iframes, closed shadow roots and body size caps are analysed in
+[docs/limitations.md](docs/limitations.md) — with the exact code location, the plan to remove each and
+the expected cost.
+
+## Tests
+
+```powershell
+node test\redact.test.mjs     #  8 — redaction rules
+node test\bridge.test.mjs     #  8 — wire protocol, token, liveness
+node test\artifacts.test.mjs  #  5 — bundle layout and large-body spill
+node test\plugin.test.mjs     #  2 — tool registration and the full tool path
+node test\e2e.mjs             # 31 — real Chrome through the wire protocol
+node test\tools-chrome.mjs    # 19 — real Chrome through the tools
+```
+
+`e2e.mjs` and `tools-chrome.mjs` launch a throwaway Chrome, load the extension with
+`Extensions.loadUnpacked`, and exercise capture, trusted input, the virtual cursor, upload, injection
+and screenshots against a local page with a working BFF endpoint.
+
+## Repository layout
+
+```
+lib/            DSH plugin: tools, bridge, redaction, artifact writer
+extension/      MV3: service worker (CDP), popup, icons, locales
+docs/           protocol, limitations, detailed guide
+scripts/        install.ps1
+tools/          icon rasteriser, popup/icon previews, asar reader (dev only)
+test/           unit, integration, end-to-end
+```
+
+
+
+MIT — see [LICENSE](LICENSE).
+
+## Versioning
+
+The version lives in `package.json` and is mirrored into `extension/manifest.json`; `CHANGELOG.md`
+holds the history. Every commit that changes shipped code bumps the version, docs-only commits do not:
+
+```powershell
+node tools\version.mjs check                  # fail if the three files disagree
+node tools\version.mjs bump minor             # bump package.json + manifest.json + CHANGELOG stub
+```
+
+Releases are tagged `vX.Y.Z`. Versions below 0.3.0 were assigned retroactively from the commit
+history, so an old tag may pin commit content that still carried the 0.1.0 stamp.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.ru.md

@@ -0,0 +1,213 @@
+# dsh-site-bridge
+
+[English](README.md) · **Русский** · [中文](README.zh-CN.md)
+
+**Глаза и руки [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) в вашем браузере.**
+Снимает разметку страницы и её BFF-трафик в файлы, понятные агенту, управляет страницей доверенным
+вводом и проверяет расширение, которое вы только что написали, — сразу в той же вкладке.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Две половины, один мост:
+
+| Половина | Что делает |
+|---|---|
+| **Плагин DSH** (`lib/`) | Держит loopback-мост и даёт модели восемь инструментов. Пишет пакет снимка в рабочее пространство сессии. |
+| **Расширение MV3** (`extension/`) | Живёт в вашем профиле Chrome/Edge, работает с вашими куками, снимает разметку и сеть через CDP, управляет страницей настоящими событиями ввода. Локализовано: English, Русский, 中文. |
+
+По отдельности ни одна половина не решает задачу: плагин держит модель и файлы, расширение — сессию
+браузера и точность.
+
+---
+
+## Зачем
+
+Писать расширение, которое встраивается в чужой сайт, — это в основном археология: из чего на самом
+деле сделана разметка, какой селектор переживёт следующий деплой и какой BFF-эндпоинт вызывает эта
+кнопка и с каким телом. Вручную это DevTools, копипаст и догадки.
+
+Проект превращает археологию в снимок:
+
+```
+site_capture → captures/<host>/<timestamp>/
+  dom.html          сериализованная разметка снятой области
+  dom.json          дерево элементов: боксы, атрибуты, кандидаты селекторов
+  styles.json       computed-стили ключевых узлов + CSS-переменные темы
+  selectors.md      шорт-лист устойчивых селекторов с объяснением, почему они устойчивы
+  network.jsonl     каждый снятый xhr/fetch, один JSON на строку
+  api.md            эндпоинты, сгруппированные по method+path, с контрактами запроса/ответа
+  screenshot.png    опциональный рендер всей страницы
+```
+
+Агент читает эти файлы как обычный исходник и пишет расширение. Затем `site_inject` выполняет этот
+код в живой странице, и «должно работать» превращается в «работает здесь».
+
+## Возможности
+
+- **Разметка** — дерево элементов с боксами и видимостью, computed-стили интерактивных узлов,
+  CSS-переменные темы и кандидаты селекторов по устойчивости (`data-testid` > `id` > `name` >
+  `aria-label` > путь по классам > позиционный путь), каждый проверен на уникальность по живому DOM.
+- **BFF-трафик** — `xhr`/`fetch` с методом, статусом, заголовками запроса, телом запроса,
+  заголовками ответа и телом ответа, только для проверяемого сайта.
+- **Доверенный ввод** — клики, ввод, select, клавиши, прокрутка и загрузка файлов через CDP
+  `Input.*` / `DOM.setFileInputFiles`: события, которые страница не отличает от действий человека.
+- **Виртуальный курсор** — DOM-оверлей, который едет к цели, плюс настоящее событие мыши в этих
+  координатах — для контролов, игнорирующих программный `click()`.
+- **Глубокие селекторы** — `host >>> inner` проходит сквозь открытые shadow-корни и same-origin
+  iframe; координаты клика пересчитываются с учётом смещения фрейма.
+- **Работает в фоновых вкладках** — чтение, клики, ввод и скриншоты работают, когда вкладка не в
+  фокусе (Chrome тротлит там только таймеры и анимации).
+- **Ничего не хранится из авторизации** — см. [Безопасность](#безопасность).
+
+## Требования
+
+- DeepSeek Harness с CLI `dsh` и профилем (Desktop или Web).
+- Chrome или Edge 125+ (расширение использует `chrome.debugger` и MV3 service worker).
+- Node.js 22+ для инструментов в `tools/` и для тестов.
+
+## Установка
+
+### 1. Host-половина
+
+```powershell
+# из корня репозитория
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
+```
+
+Скрипт линкует плагин в ваш профиль, добавляет его в `dsh.profile.bundles` и раскладывает расширение
+в `%USERPROFILE%\.dsh\site-bridge\extension`. Вручную то же самое:
+
+```powershell
+dsh plugin --profile desktop add <путь-к-этому-репозиторию>
+```
+
+Если CLI не сделал этого сам, добавьте `"dsh-site-bridge"` в `dsh.profile.bundles` в
+`%USERPROFILE%\.dsh\profiles\desktop\package.json`, затем перезапустите DSH — host-половина
+загружается при старте профиля.
+
+### 2. Браузерная половина
+
+1. `chrome://extensions` → включите **Режим разработчика** → **Загрузить распакованное** →
+   `%USERPROFILE%\.dsh\site-bridge\extension`.
+2. Откройте попап. Он покажет порт и путь к `bridge.json` (то же печатает `site_status`).
+3. Нажмите **Импорт bridge.json** и выберите этот файл — или вставьте токен: он сохранится сам,
+   кнопки нет.
+4. Откройте нужную страницу и нажмите **Подключить эту вкладку**.
+
+Chrome покажет плашку «началась отладка этого браузера»: это и есть CDP-сессия, на которой всё
+работает. Она исчезнет после **Отключить**.
+
+Интерфейс попапа следует языку браузера: английский, русский и упрощённый китайский лежат в
+`extension/_locales`.
+
+## Использование
+
+```text
+site_status                     → состояние моста, путь к токену, текущая вкладка
+site_tabs {action:"list"}       → вкладки; {action:"claim", tabId} привязывает одну
+site_network {action:"start"}   → начать запись, затем действуйте на странице
+site_capture {screenshot:true}  → записать пакет в рабочее пространство
+site_act {steps:"[...]"}        → click/fill/type/select/press/scroll/upload/wait/eval
+site_cursor {x,y,click:true}    → виртуальный курсор, настоящее событие мыши
+site_shot {fullPage:true}       → скриншот в captures/shots/*.png
+site_inject {js:"..."}          → выполнить ваш скрипт в странице для проверки
+```
+
+Типичный цикл написания встраиваемого расширения:
+
+1. `site_tabs` → привязать страницу.
+2. `site_capture` → прочитать `selectors.md`, `styles.json`, `api.md`.
+3. Написать userscript / content script в своём репозитории.
+4. `site_inject` с телом скрипта → проверить, что якорь найден и вызов BFF проходит с куками
+   браузера.
+5. Доработать селекторы, которые снимок пометил как хрупкие.
+
+## Архитектура
+
+```
+┌──────────────────────────── DSH host ────────────────────────────┐
+│  инструменты (site_*) ──► мост: 127.0.0.1, токен, очередь long-poll│
+│  редакция на приёме ──► буфер в памяти ──► запись артефактов       │
+└───────────────────────────────┬───────────────────────────────────┘
+                                │ HTTP long-poll (без websocket)
+┌───────────────────────────────┴───────────────────────────────────┐
+│  MV3 service worker: chrome.debugger ──► CDP                        │
+│    Network domain  → запросы с заголовками и телами                │
+│    Input domain    → доверенные мышь/клавиатура, загрузка файлов   │
+│    Runtime domain  → снимок DOM, селекторы, внедрённые скрипты     │
+│  popup: подключение, вкладка, запись (ru / en / zh)                │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+Протокол небольшой и описан в [docs/protocol.md](docs/protocol.md).
+
+## Безопасность
+
+- **Авторизация не покидает браузер.** Расширение не читает куки и токены: запросы делает сама
+  страница, браузер прикладывает их. Мост видит их в полёте, но значения `cookie`, `authorization`,
+  `x-csrf-token`, `x-api-key`, `set-cookie` и подобных заголовков, credential-подобные query-параметры
+  и поля JSON/форм заменяются на `«redacted»` **на приёме** — до того, как что-то сохранено.
+- **На диск не попадает ничего авторизационного.** Имена заголовков сохраняются, потому что «этому
+  эндпоинту нужен `x-csrf-token`» — часть контракта; значения — нет.
+- **Захват ограничен сайтом.** Пишутся только свои `xhr`/`fetch` проверяемого сайта (тот же хост, тот
+  же домен второго уровня или сторонний JSON). Телеметрия и агенты безопасности, которые отправляют
+  дамп HTML страницы на свой сервер, отфильтровываются — иначе исходник с инлайн-токенами попадал бы
+  в пакет.
+- **Только loopback.** Мост слушает `127.0.0.1` и отклоняет любой запрос без 32-байтного токена
+  сопряжения. `site_status` печатает путь к файлу с токеном, а не сам токен.
+- **Остаточный риск.** Значения заголовков и тела всё равно проходят через процесс DSH в памяти. Если
+  сайт кладёт секрет под нестандартным ключом, редакция его не узнает. Считайте пакет снимка
+  чувствительным, как и любой дамп трафика.
+
+## Ограничения
+
+Кросс-доменные iframe, закрытые shadow-корни и лимиты тела разобраны в
+[docs/limitations.md](docs/limitations.md) — с точным местом в коде, планом снятия каждого и оценкой
+стоимости.
+
+## Тесты
+
+```powershell
+node test\redact.test.mjs     #  8 — правила редакции
+node test\bridge.test.mjs     #  8 — протокол, токен, живость
+node test\artifacts.test.mjs  #  5 — раскладка пакета и вынос больших тел
+node test\plugin.test.mjs     #  2 — регистрация инструментов и сквозной путь
+node test\e2e.mjs             # 31 — реальный Chrome через протокол
+node test\tools-chrome.mjs    # 19 — реальный Chrome через инструменты
+```
+
+`e2e.mjs` и `tools-chrome.mjs` поднимают одноразовый Chrome, загружают расширение через
+`Extensions.loadUnpacked` и проверяют захват, доверенный ввод, виртуальный курсор, загрузку файла,
+инъекцию и скриншоты на локальной странице с рабочим BFF-эндпоинтом.
+
+## Структура репозитория
+
+```
+lib/            плагин DSH: инструменты, мост, редакция, запись артефактов
+extension/      MV3: service worker (CDP), popup, иконки, локали
+docs/           протокол, ограничения, подробное руководство
+scripts/        install.ps1
+tools/          растеризация иконок, превью попапа/иконок, чтение asar (только для разработки)
+test/           юнит, интеграционные, end-to-end
+```
+
+
+
+MIT — см. [LICENSE](LICENSE).
+
+## Версионирование
+
+Версия живёт в `package.json` и зеркалится в `extension/manifest.json`; история — в `CHANGELOG.md`.
+Каждый коммит, меняющий поставляемый код, поднимает версию; коммиты только с документацией — нет:
+
+```powershell
+node tools\version.mjs check                  # упадёт, если три файла расходятся
+node tools\version.mjs bump minor             # поднимет package.json + manifest.json + заготовку в CHANGELOG
+```
+
+Релизы помечаются тегами `vX.Y.Z`. Версии ниже 0.3.0 проставлены задним числом по истории коммитов,
+поэтому старый тег может указывать на содержимое, где ещё стояла 0.1.0.
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,179 @@
+# dsh-site-bridge
+
+[English](README.md) · [Русский](README.ru.md) · **中文**
+
+**把 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的眼睛和双手放进你自己的浏览器。**
+把页面的结构与其 BFF 流量抓取成智能体可读的文件，用可信输入驱动页面，并在同一个标签页里验证你刚写好的扩展。
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+两部分，一座桥：
+
+| 部分 | 作用 |
+|---|---|
+| **DSH 插件**（`lib/`） | 维护本机回环桥接，向模型提供八个工具，并把快照包写入会话工作区。 |
+| **MV3 扩展**（`extension/`） | 运行在你的 Chrome/Edge 配置中，使用你的 Cookie，通过 CDP 抓取结构与网络，用真实输入事件驱动页面。已本地化：English、Русский、中文。 |
+
+两者缺一不可：插件承载面向模型的接口与文件，扩展承载浏览器会话与保真度。
+
+---
+
+## 为什么需要它
+
+写一个嵌入别人网站的扩展，本质上是一场考古：页面结构到底是什么、哪个选择器能活过下次发版、这个按钮调用了哪个 BFF 接口、请求体长什么样。手工做这些就是 DevTools、复制粘贴和猜测。
+
+这个项目把考古变成一次抓取：
+
+```
+site_capture → captures/<host>/<timestamp>/
+  dom.html          被抓区域序列化后的结构
+  dom.json          元素树：盒子、属性、选择器候选
+  styles.json       关键节点的计算样式 + 主题 CSS 变量
+  selectors.md      稳定选择器清单，并说明每个为什么稳定
+  network.jsonl     每个抓到的 xhr/fetch，每行一个 JSON
+  api.md            按 method+path 分组的接口，以及请求/响应契约
+  screenshot.png    可选的整页截图
+```
+
+智能体像读普通源码一样读这些文件，然后写扩展。接着 `site_inject` 把这段代码跑在活页面上，"应该能用" 就变成 "在这里能用"。
+
+## 功能
+
+- **结构** —— 带盒子与可见性的元素树、交互节点的计算样式、主题 CSS 变量，以及按稳定性排序的选择器候选（`data-testid` > `id` > `name` > `aria-label` > class 路径 > 位置路径），每个都在活的 DOM 上检查过唯一性。
+- **BFF 流量** —— `xhr`/`fetch` 的方法、状态、请求头、请求体、响应头、响应体，且只针对被检查的站点。
+- **可信输入** —— 通过 CDP `Input.*` / `DOM.setFileInputFiles` 完成点击、输入、下拉、按键、滚动和文件上传：这些事件页面无法与真人操作区分。
+- **虚拟光标** —— 一个移动到目标的 DOM 覆盖层，并在该坐标发出真实鼠标事件，用于忽略合成 `click()` 的控件。
+- **深层选择器** —— `host >>> inner` 可以穿过开放的 shadow root 与同源 iframe；点击坐标会按 iframe 偏移校正。
+- **后台标签页可用** —— 标签页不在前台时，读取、点击、输入和截图仍然可用（Chrome 只在后台限制定时器与动画）。
+- **不保存任何凭据** —— 见[安全](#安全)。
+
+## 环境要求
+
+- 带 `dsh` CLI 与配置档（Desktop 或 Web）的 DeepSeek Harness。
+- Chrome 或 Edge 125+（扩展依赖 `chrome.debugger` 与 MV3 service worker）。
+- Node.js 22+，用于 `tools/` 里的工具和测试。
+
+## 安装
+
+### 1. 宿主部分
+
+```powershell
+# 在仓库根目录
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
+```
+
+脚本会把插件链接进你的配置档、写入 `dsh.profile.bundles`，并把扩展复制到 `%USERPROFILE%\.dsh\site-bridge\extension`。等价的手工步骤：
+
+```powershell
+dsh plugin --profile desktop add <本仓库路径>
+```
+
+如果 CLI 没写入，请把 `"dsh-site-bridge"` 加到 `%USERPROFILE%\.dsh\profiles\desktop\package.json` 的 `dsh.profile.bundles` 中，然后重启 DSH —— 宿主部分在配置档启动时加载。
+
+### 2. 浏览器部分
+
+1. `chrome://extensions` → 打开**开发者模式** → **加载已解压的扩展程序** → `%USERPROFILE%\.dsh\site-bridge\extension`。
+2. 打开扩展弹窗。它会显示端口和 `bridge.json` 的路径（`site_status` 也会打印同样内容）。
+3. 点击 **导入 bridge.json**（Import bridge.json）并选择该文件，或直接粘贴令牌 —— 会自动保存，无需按钮。
+4. 打开要操作的页面，点击 **连接此标签页**。
+
+Chrome 会显示「已开始调试此浏览器」提示条：这正是全部功能所依赖的 CDP 会话。点击**断开**后消失。
+
+弹窗界面跟随浏览器语言：英语、俄语、简体中文位于 `extension/_locales`。
+
+## 用法
+
+```text
+site_status                     → 网桥状态、令牌路径、当前标签页
+site_tabs {action:"list"}       → 标签页列表；{action:"claim", tabId} 绑定其一
+site_network {action:"start"}   → 开始录制，然后在页面上操作
+site_capture {screenshot:true}  → 把快照包写入工作区
+site_act {steps:"[...]"}        → click/fill/type/select/press/scroll/upload/wait/eval
+site_cursor {x,y,click:true}    → 虚拟光标，真实鼠标事件
+site_shot {fullPage:true}       → 截图到 captures/shots/*.png
+site_inject {js:"..."}          → 在页面中执行你的脚本以验证
+```
+
+编写页内扩展的典型循环：
+
+1. `site_tabs` → 绑定页面。
+2. `site_capture` → 阅读 `selectors.md`、`styles.json`、`api.md`。
+3. 在你自己的仓库里写 userscript / content script。
+4. 用 `site_inject` 注入脚本体 → 确认锚点能找到、BFF 调用能带着浏览器 Cookie 通过。
+5. 针对快照标记为脆弱的选择器继续调整。
+
+## 架构
+
+```
+┌──────────────────────────── DSH 宿主 ────────────────────────────┐
+│  tools (site_*) ──► 网桥：127.0.0.1、令牌、long-poll 队列          │
+│  写入时脱敏 ──► 内存缓冲 ──► 快照包写入                            │
+└───────────────────────────────┬───────────────────────────────────┘
+                                │ HTTP long-poll（不使用 websocket）
+┌───────────────────────────────┴───────────────────────────────────┐
+│  MV3 service worker: chrome.debugger ──► CDP                        │
+│    Network domain  → 带请求头与请求体的请求                         │
+│    Input domain    → 可信鼠标/键盘、文件上传                        │
+│    Runtime domain  → DOM 快照、选择器、注入脚本                     │
+│  popup：配对、目标标签页、录制开关（ru / en / zh）                  │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+协议很小，详见 [docs/protocol.md](docs/protocol.md)。
+
+## 安全
+
+- **凭据不离开浏览器。** 扩展不读取 Cookie 或令牌：页面自己发请求，浏览器自动附带。网桥能看到传输中的值，但 `cookie`、`authorization`、`x-csrf-token`、`x-api-key`、`set-cookie` 等请求头的值、形似凭据的查询参数与 JSON/表单字段，都会在**接收时**替换为 `«redacted»` —— 早于任何保存动作。
+- **磁盘上不写任何凭据类内容。** 请求头的*名字*会保留，因为「这个接口需要 `x-csrf-token`」属于契约的一部分；值不会。
+- **录制限定站点。** 只记录被检查站点自身的 `xhr`/`fetch`（同主机、同可注册域，或第三方 JSON）。把整页 HTML 转储到自己服务器的遥测与安全代理会被过滤掉 —— 否则含内联令牌的页面源码就会落进快照包。
+- **仅回环。** 网桥只绑定 `127.0.0.1`，任何没有 32 字节配对令牌的请求都会被拒绝。`site_status` 打印的是令牌文件路径，而不是令牌本身。
+- **残余风险。** 请求头与请求体仍会经过 DSH 进程的内存。如果站点把密钥放在非常规字段名下，脱敏无法识别。请像对待任何流量转储一样，把快照包视为敏感数据。
+
+## 限制
+
+跨域 iframe、封闭的 shadow root 与响应体大小上限在 [docs/limitations.md](docs/limitations.md) 中逐条分析 —— 包含代码位置、消除方案与预估成本。
+
+## 测试
+
+```powershell
+node test\redact.test.mjs     #  8 —— 脱敏规则
+node test\bridge.test.mjs     #  8 —— 协议、令牌、在线判定
+node test\artifacts.test.mjs  #  5 —— 快照包布局与大体积响应体外置
+node test\plugin.test.mjs     #  2 —— 工具注册与完整工具路径
+node test\e2e.mjs             # 31 —— 真实 Chrome，走协议层
+node test\tools-chrome.mjs    # 19 —— 真实 Chrome，走工具层
+```
+
+`e2e.mjs` 与 `tools-chrome.mjs` 会启动一次性 Chrome，通过 `Extensions.loadUnpacked` 加载扩展，并针对带真实 BFF 接口的本地页面验证抓取、可信输入、虚拟光标、文件上传、注入与截图。
+
+## 仓库结构
+
+```
+lib/            DSH 插件：工具、网桥、脱敏、快照包写入
+extension/      MV3：service worker（CDP）、弹窗、图标、多语言
+docs/           协议、限制、详细指南
+scripts/        install.ps1
+tools/          图标栅格化、弹窗/图标预览、asar 读取（仅开发用）
+test/           单元、集成、端到端
+```
+
+
+
+MIT —— 见 [LICENSE](LICENSE)。
+
+## 版本管理
+
+版本号保存在 `package.json`，并同步到 `extension/manifest.json`；历史记录在 `CHANGELOG.md`。
+任何改动发布代码的提交都要提升版本号，仅文档的提交不需要：
+
+```powershell
+node tools\version.mjs check                  # 三个文件不一致时报错
+node tools\version.mjs bump minor             # 同步更新 package.json、manifest.json 与 CHANGELOG 条目
+```
+
+发布使用 `vX.Y.Z` 标签。0.3.0 之前的版本是按提交历史回溯标注的，因此旧标签指向的内容里
+可能仍写着 0.1.0。
+
+## 许可证
+
+MIT —— 见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh bundle patch: inserts the site-bridge row into a profile's layer stack.
+# The bridge itself starts lazily on the first tool call (or immediately when
+# `port` is set and `autoStart` is true).
+- insert:
+    - id: site-bridge
+      name: 'dsh-site-bridge'