English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia
# dsh-harbor Зеркало только для чтения установленных у вас плагинов [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): что каждый из них **умеет**, где они **конфликтуют** и что **изменилось** с момента последнего сканирования — с проверяемыми свидетельствами для каждой обнаруженной возможности. Решение о том, нужно ли что-либо приводить в порядок, остаётся за вами. harbor сообщает факты; он не выносит оценок, не ограничивает установку и ничего не перехватывает. ## Что это такое — и чем оно не является harbor делает ровно одно: ведёт постоянно обновляемый, подкреплённый свидетельствами реестр установленных плагинов. В нём три раздела — собственно инвентарь (каждый установленный сторонний плагин с расположением исходников там, где детектор может его определить), сверка заявлений каждого плагина с тем, что фактически делает его код, и хронология изменений между сканированиями. То, чего harbor намеренно не делает, в равной степени является частью его замысла. Он не проверяет и не блокирует плагины до установки — контроль допуска относится к инструментам магазина плагинов. Он не углубляется в мониторинг вышестоящих зависимостей; проверка upstream охватывает только версии плагинов и на этом заканчивается. Он не выполняет общий аудит кода и не перехватывает, не блокирует и не помещает поведение плагинов в песочницу. Последнее — не решение об области применения, а свойство хоста. В среде выполнения Cordis от DSH нет песочницы возможностей: плагин работает в основном Node realm хоста с теми же привилегиями, что и сам хост. harbor может сделать возможности **видимыми**, **обнаружить** их и **сверить** с декларациями, но не может отключить их. Для ограничения поведения плагинов нужна поддержка в самом загрузчике DSH, а описанный ниже процесс декларации помогает выработать такой стандарт на основе данных, а не отвлечённых споров. Наконец, harbor сообщает факты, а не оценки. Его вывод всегда отвечает на вопросы «что обнаружено и где находятся свидетельства» — без уровня риска и без оценки качества. Что означает находка именно для вас, решаете вы, а не harbor. > **Статус: `0.1.0-rc.3`, укрепление релиз-кандидата.** Доступны CLI, маршруты hub только для loopback, панель настроек DSH, расхождения между profile и необязательная проверка upstream. Активный хост добавляет сведения о runtime tools, providers и routes; вне него данные среды выполнения явно переходят в состояние `available: false`. Детекторы остаются эвристическими и калибруются на более широкой экосистеме, поэтому проверяйте свидетельства и не считайте отсутствие находки доказательством отсутствия возможности. ## Что проверяется ``` ~/.dsh/profiles/* → установленные сторонние bundles (как npm, так и link:) ├─ declared package.json / cordis.patch.yml — что плагин сообщает о себе ├─ runtime tools / routes / providers, фактически зарегистрированные в хосте ├─ static subprocess, egress, записи во внешние конфигурации — с file:line ├─ versions расхождение (локально, всегда) + upstream (по сети, по запросу) └─ snapshot diff с предыдущим сканированием: новые версии, новые возможности └─ сверка: заявленные dsh.capabilities и фактически обнаруженные ``` Набор возможностей фиксирован и состоит из тринадцати пунктов: внедрение клиента, риски realm, копии realm, глобальные hooks, адаптеры LLM, subprocesses, сетевой egress, web routes, регистрация tools, серверы MCP, запись во внешние конфигурации, обработка учётных данных и чтение переменных среды. Фиксированный набор позволяет сравнивать отчёты и строить diff между сканированиями. Официальный список приведён в [SPEC.md](./SPEC.md) §2; машиночитаемый источник истины — `src/scan/detectors.mjs`. Терминология намеренно нейтральна: **возможность**, а не риск. Для некоторых плагинов запуск subprocesses — основная цель. Отчёт отвечает на вопрос «что это может делать», а вопрос «следует ли ему это делать» оставляет вам. ## Предпроверка обновления Прежде чем переводить DSH на новую версию, Harbor устанавливает именно эту версию в собственный кэш, импортирует каждый установленный плагин в дочернем процессе против неё, сверяет id из `dsh.client.inject` с графом клиентских модулей цели и проверяет peer-диапазоны хоста. Ответ даётся по profile: запустится после обновления или заблокирован — каким плагином, с реальной ошибкой на этапе линковки. Также проверяется, что `agent-presets.default` из `settings.yaml` всё ещё есть среди встроенных пресетов цели (DSH 0.1.2 переименовал `code` в `ptc`, не мигрировав сохранённое значение, после чего каждая новая сессия падает). ```sh harbor preflight --list # dist-tags апстрима, свежие версии, локально закэшированные деревья хоста harbor preflight --dsh next # или конкретная версия: --dsh 0.1.5-rc.2 harbor preflight --dsh 0.1.5-rc.2 --json # полный машиночитаемый отчёт ``` Вердикты выдаются по плагину (**блокирует запуск** / **загружается** / **не проверен**) и по profile; peer-диапазоны и мёртвые inject — лишь предупреждения и никогда не меняют вердикт. Код выхода 3 означает, что хотя бы один profile не запустится. Всё выполняется в дочерних процессах; глобальный префикс npm и ваши profiles никогда не изменяются. Хук резолва требует Node ≥ 20.6. ## Версии harbor отвечает на два вопроса о версиях и не смешивает их. **Расхождение между profile** определяется исключительно локально. Разные версии одного плагина в разных profile — факт об этой машине, поэтому он вычисляется бесплатно при каждом сканировании. Установка через `link:` или `file:` не считается базовой «самой новой» версией: рабочее дерево, опережающее опубликованную версию, — обычная ситуация, а не расхождение. **Проверка upstream** обращается за пределы машины, поэтому никогда не входит в сканирование по умолчанию. Для CLI требуется `harbor scan --check-updates`; на панели нужно явно нажать кнопку, и текст рядом с ней это сообщает — это единственное действие на странице, которое обращается за пределы вашей машины. Каждый результат находится в одном из пяти состояний: - **behind** — в registry есть более новая версия - **current** — установленная версия совпадает с версией в registry - **ahead** — установленная версия новее версии в registry (реальная ситуация на машине сопровождающего) - **local** — установка через `link:` / `file:`, для которой нет upstream для сравнения и которая никогда не отображается как «актуальная» - **unknown** — запрос завершился неудачно registry берётся из вашего собственного `.npmrc` (включая переопределения `@scope:registry`) и никогда не привязывается жёстко к npmjs. Результаты кэшируются на диске на шесть часов. ## Установка Для локальной разработки установите пакет из checkout: ```bash dsh plugin --profile web add link:/path/to/dsh-harbor ``` `dsh plugin` передаёт остальные аргументы pnpm внутри каталога profile, а `link:` создаёт символическую ссылку зависимости profile на этот checkout, поэтому результаты повторной сборки видны сразу. Для установки из registry используйте кандидатный tag `next`: ```bash dsh plugin --profile web add @zseven-w/dsh-harbor@next ``` После этого перезапустите DSH, чтобы загрузился новый слой profile. Панель появляется в Web UI DSH в разделе **Settings** под названием **DSH Harbor** — это то же зеркало, что и CLI: инвентарь со свидетельствами, конфликты, версии и diff с последнего сканирования. Кнопка **Check for updates** — единственное действие на этой странице, которое обращается за пределы вашей машины. Панель относится к hub-части плагина и монтируется только в profile с web-сервером. Исполняемый файл плагина устанавливается внутри выбранного profile; добавление его в `web` не помещает `harbor` в глобальный `PATH` вашей оболочки. Запускайте его через этот profile: ```bash pnpm --dir ~/.dsh/profiles/web exec harbor scan ``` Для запуска из checkout или однократного запуска из registry используйте один из следующих вариантов: ```bash node /path/to/dsh-harbor/src/cli.mjs scan pnpm dlx @zseven-w/dsh-harbor@next scan ``` ## Использование В примерах ниже `harbor` служит сокращением для одного из приведённых выше способов запуска. ```bash harbor scan # инвентарь, конфликты и изменения с последнего сканирования harbor scan --check-updates # + необязательная сетевая проверка upstream по registry harbor manifest ./my-plugin # создать черновик блока dsh.capabilities для вашего плагина harbor preflight --dsh next # предпроверка: какие profiles всё ещё запускаются на этой версии DSH ``` Добавьте `--evidence`, чтобы вывести доступные исходные свидетельства `file:line`, `--json` — чтобы получить полный машиночитаемый отчёт, и `--no-snapshot` — чтобы не записывать базовый снимок для diff. Факты из manifest, файловой системы или среды выполнения могут не иметь строки исходного кода и помечаются соответствующим образом. Сканер не имеет зависимостей и не требует установленного DSH, поэтому может работать и в CI. ## Для авторов плагинов `harbor manifest` читает ваш плагин так же, как все остальные, и создаёт черновик элемента `capabilities`, который нужно объединить с существующим объектом `dsh` в вашем `package.json`; он никогда не предлагает заменить весь объект и потерять настройки `bundle` или `client`. После декларации проверка harbor превращается в сверку **заявлено и обнаружено**: возможности, которые вы заявили, но никогда не используете, — шум, который можно удалить, а обнаруженные, но незаявленные возможности стоит объяснить. harbor также декларирует собственные `dsh.capabilities`, поэтому этот процесс можно воспроизвести на самом инструменте: выполните `harbor manifest .` в этом репозитории. Само соглашение описано в [SPEC.md](./SPEC.md) ([SPEC.zh.md](./SPEC.zh.md)). В одном предложении: `dsh.capabilities` — обычный список в `package.json`, указывающий, что фактически делает код вашего плагина. Декларация не требует больших усилий и приносит двойную пользу: инструменты аудита вроде harbor могут сверить ваши слова с кодом, а пользователи плагина видят, что вы ничего не скрываете. В любой момент можно самостоятельно проверить декларацию командой `harbor manifest