|
### 🖼️ Точные превью нескольких кадров
Установленный headless-экспортёр OpenPencil формирует точные превью: первый верхнеуровневый кадр — как крупный PNG, пригодный для воспроизведения, плюс горизонтально прокручиваемая лента миниатюр с выбором по клику и навигацией «предыдущий/следующий» для документов с несколькими кадрами.
|
### 🗺️ Интерактивный холст
«Открыть интерактивный холст» лениво монтирует доступный только для чтения Web SDK OpenPencil с панорамированием, масштабированием и подгонкой под размер — изучайте любую страницу, вложенный узел или неактивную страницу, не покидая диалог.
|
|
### ✏️ Управляемый редактор
С параметром `editable: true` действие «редактировать» открывает управляемый редактор OpenPencil — выделение, слои, свойства, инструменты рисования, отмена/повтор и явную семантику сохранения — в изменяемой по размеру правой боковой рабочей области с опцией полноэкранного режима.
|
### 🤖 Дизайн-инструменты, созданные для агентов
Пять инструментов — `openpencil_new`, `openpencil_create`, `openpencil_edit`, `openpencil_render`, `openpencil_selection` — позволяют агенту создавать, изменять и читать настоящий холст через транзакционные программы `batch_design`.
|
|
### 🔐 Гранты на основе возможностей
Гранты на изображения и документы — это подписанные возможности, привязанные к хешу. Метаданные браузера никогда не раскрывают произвольный путь на хосте, а подписанные возможности превью и редактора никогда не попадают в канонический результат инструмента или контекст модели.
|
### ⚡ Транзакционная безопасность
Новый документ публикуется только после успешного завершения всей программы `batch_design`. Инструмент никогда не перезаписывает существующий путь, неудачный батч не оставляет пустого файла, а сохранения используют оптимистичный хеш с атомарной заменой.
|
|
### 🌍 Соответствует стилю DSH
Карточка инструмента и управляемый редактор следуют китайской/английской локали DSH и светлой/тёмной теме без перезагрузки сессии редактирования.
|
### 🎯 Один полный рабочий процесс
«Требование в диалоге → агент редактирует настоящий холст → живое превью и проверка взаимодействия → продолжаем итерации» — единый цикл без пересылки скриншотов туда и обратно.
|
## Установка в DSH
DSH — отдельный пакет. Установите его один раз, если его ещё нет:
```sh
npm install -g @deepseek-ai/dsh@0.1.0-rc.6
```
Затем добавьте плагин в профиль и запустите веб-приложение:
```sh
dsh plugin --profile web add @zseven-w/dsh-openpencil@latest
dsh web
```
Не хотите ставить DSH глобально? Выполните те же два шага через `pnpm dlx`:
```sh
pnpm dlx --package=@deepseek-ai/dsh@0.1.0-rc.6 dsh plugin --profile web add @zseven-w/dsh-openpencil@latest
pnpm dlx --package=@deepseek-ai/dsh@0.1.0-rc.6 dsh web
```
> Плагин OpenPencil публичный и не требует npm-токена. Если сам пререлиз DSH требует аутентификации в реестре, храните эти учётные данные в пользовательском или временном npm-конфиге вне этого чекаута. Этот репозиторий намеренно не содержит учётных данных реестра.
## Дизайн-инструменты
| Инструмент | Что он делает |
| --- | --- |
| `openpencil_new` | Создаёт совершенно новый `.op` из одной транзакционной программы `batch_design`, сохраняет его атомарно через изолированную файловую систему DSH и не требует заранее открытого редактора. |
| `openpencil_create` | Применяет транзакционную программу `batch_design`, чтобы сгенерировать или перестроить узлы на существующем живом холсте. |
| `openpencil_edit` | Изменяет указанный узел или единственный узел, выбранный пользователем. |
| `openpencil_render` | Создаёт неизменяемый снапшот `.op` с адресацией по содержимому и рендерит каждый верхнеуровневый кадр на активной странице — с опциональными `scale` и `editable`. |
| `openpencil_selection` | Считывает точные узлы, выбранные на живом холсте редактора. |
## Рабочий процесс агента в дизайне
Для запроса на естественном языке без существующего документа агенту следует вызвать `openpencil_new` с новым путём `.op` относительно рабочей области и первой полной программой `batch_design`. Инструмент выполняет эту программу в приватном управляемом демоне OpenPencil и публикует авторитетный документ только после успешного завершения всего батча. Он никогда не перезаписывает существующий путь, а неудачный батч не оставляет пустого файла. Затем агенту следует вызвать `openpencil_render` с возвращённым путём, `editable: true` и `autoOpen: true`, чтобы показать галерею и один раз развернуть редактор. Воспроизведённые или изначально зафиксированные исторические карточки автоматически не открываются.
Используйте `openpencil_create` и `openpencil_edit` только для существующего живого холста. Их изменения остаются несохранёнными до действия «Сохранить» в редакторе.
## Контракт рендеринга
`openpencil_render` принимает путь `.op`, опциональный `scale` (`0 < scale <= 8`, по умолчанию `1`) и опциональный `editable` (по умолчанию `false`). Оставьте `width` и `height` незаданными для точного пути OpenPencil: они описывают окно просмотра времени выполнения, а не размеры экспорта дизайна, и принимаются только менее точным фолбэком Jian.
Поиск бинарника OpenPencil выполняется в следующем порядке:
1. `DSH_OPENPENCIL_BINARY` or `DSH_OPENPENCIL_DESKTOP`
2. `/Applications/OpenPencil.app/Contents/MacOS/openpencil-desktop`
3. `~/Applications/OpenPencil.app/Contents/MacOS/openpencil-desktop`
4. `openpencil-desktop` on `PATH`
Поиск фолбэка Jian использует `DSH_OPENPENCIL_JIAN`, известную локальную сборку релиза, а затем `PATH`. Если точный бинарник OpenPencil действительно недоступен, Jian может сформировать явно помеченный фолбэк `runtime-preview`. Ошибки точного рендерера, тайм-ауты и невалидные PNG не приводят к молчаливому фолбэку.
## Ассеты веб-просмотрщика
DSH обслуживает только `client.js` для клиентского плагина, поэтому ESM SDK OpenPencil, его WASM и CanvasKit подготавливаются как явные ассеты с тем же источником:
```sh
pnpm run sync:viewer-assets
```
Команда синхронизации предпочитает соседний чекаут `../openpencil` (локальная разработка) и переключается на вендорный субмодуль `vendor/openpencil` (CI и свежие клоны). Переопределите его с помощью `OPENPENCIL_ROOT` или `--openpencil-root`. Полный каталог предсобранных ассетов можно выбрать с помощью `DSH_OPENPENCIL_VIEWER_SOURCE`. Поиск во время выполнения можно переопределить с помощью `DSH_OPENPENCIL_VIEWER_ASSET_DIR`.
Ассеты просмотрщика загружаются лениво только после того, как пользователь откроет холст. Если они отсутствуют или невалидны, превью PNG остаётся доступным, а кнопка холста не предлагается.
## Управляемый редактор
Редактируемые сессии используют управляемый веб-хост OpenPencil — ту же архитектуру, что и `op-vscode`. Плагин запускает хост только после авторизованного действия пользователя, держит токен демона в памяти, проверяет источник и происхождение iframe и закрывает процесс при завершении сессии редактирования. Поверхность редактора выбирается постепенно: нативные детали инструмента, когда хост объявляет такой шов, в противном случае — правая боковая рабочая область плагина с изменением размера и полноэкранным управлением.
Если DSH перезагружает или выгружает плагин, пока холст «грязный», хост сохраняет непрозрачный локальный черновик восстановления на срок до семи дней. При повторном открытии того же источника плагин спрашивает, прежде чем восстановить его на живом холсте; восстановление никогда не перезаписывает файл `.op`, пока пользователь явно не сохранит.
Поиск бинарника и исходников можно переопределить с помощью:
- `DSH_OPENPENCIL_EDITOR_BINARY` для `op-host-web-server`;
- `DSH_OPENPENCIL_SOURCE_ROOT` (или `OPENPENCIL_SOURCE_ROOT`) для веб-бандла и ассетов CanvasKit.
Сохранения используют оптимистичный хеш источника, атомарную замену и наследуемую возможность. Если источник изменился вне редактора, плагин сообщает о конфликте вместо перезаписи.
## Метаданные результата
Видимый модели результат остаётся простым JSON. Только для браузера `presentationMeta.$dshOpenPencil` несёт дополнительные гранты для:
- `image`: путь PNG, URL превью/скачивания и реальные ширина/высота;
- `frames`: каждый точно отрендеренный верхнеуровневый кадр в порядке активной страницы, включая его id/имя/индекс узла и подписанные URL PNG;
- `document`: путь исходного действия плюс неизменяемый URL снапшота, байты и SHA-256;
- `viewer`: версионированные URL SDK/WASM/CanvasKit, когда подключён маршрут ассетов;
- `editor`: ограниченные возможности запуска/обновления, когда авторизовано `editable: true`.
Результат также фиксирует `renderer`, `rendererBinary`, `fidelity` и любые предупреждения. Существующие сообщения схемы v1 только с PNG остаются отображаемыми.
DSH `0.1.0-rc.6` не сохраняет метаданные презентации браузера для инструментов, вложенных под PTC/Code Mode. Плагин восстанавливает эту проекцию UI-only через конечную точку same-origin, session-bound: браузер отправляет только session id, call id и неизменяемый SHA-256 документа, а хост получает авторитетный результат из долговечного журнала сессий DSH и использует кратковременный внутрипроцессный маркер только для авторизации недавнего живого редактирования. Подписанные возможности превью и редактора никогда не попадают в канонический результат инструмента или контекст модели. Долговечная история может восстановить доступные только для чтения превью; гранты редактора выдаются только для недавних, доверенных живых результатов.
Для ограниченного воспроизведения восстановление вложенных метаданных принимает до 128 верхнеуровневых кадров; более крупные результаты Code Mode остаются доступными через их канонический JSON-фолбэк.
## Текущие ограничения
- Последующие правки существующего холста требуют уже открытого управляемого редактора. Изменения остаются несохранёнными, пока пользователь не вызовет его действие «Сохранить».
- Лёгкий холст Web SDK доступен только для чтения; полноценное редактирование использует отдельную поверхность управляемого редактора. На DSH `0.1.0-rc.6` плагин использует изменяемую по размеру правую рабочую область с опцией полноэкранного режима.
- Точная галерея охватывает верхнеуровневые кадры активной страницы; интерактивный холст остаётся способом изучать неактивные страницы и вложенные узлы.
- Для кэшей рендеринга и снапшотов всё ещё нужна политика хранения на уровне продукта.
## Структура проекта
```text
dsh-openpencil/
├── src/ Plugin sources (TypeScript)
│ ├── index.ts Host plugin entry — Cordis service, tools, assets
│ ├── tool.ts / design-tools.ts / new-tool.ts Host-side design tools
│ ├── renderer.ts Exact OpenPencil renderer + Jian fallback
│ ├── editor-host.ts / editor-recovery.ts Managed editor lifecycle + drafts
│ ├── viewer-assets.ts Web SDK / WASM / CanvasKit asset staging
│ ├── mcp-client.ts OpenPencil MCP connection
│ └── client/ Browser client — React workbench, gallery, selection dock
├── lib/ Compiled output (published to npm)
├── scripts/ Build helpers — viewer asset sync, client build, host tests
├── tests/ Node test suites (client, host API, MCP, viewer assets)
├── docs/images/ Documentation screenshots
├── vendor/openpencil/ OpenPencil checkout (git submodule — viewer asset source)
├── cordis.patch.yml DSH bundle patch that mounts the plugin
├── tsconfig.json Host / Node TypeScript config
└── tsconfig.client.json Browser client TypeScript config
```
## Сборка и проверка
```sh
pnpm run sync:viewer-assets
pnpm run build
pnpm run test:viewer-assets
pnpm run test:client
pnpm run test:host -- /absolute/path/to/design.op 375 1091
```
Для сборки требуется Node 24.11 или новее и pnpm. Пакеты хоста и клиента DSH — это peer-зависимости, поставляемые целевым профилем DSH. Инструменты сборки разрешаются из локальных dev-зависимостей, активного привязанного чекаута DSH или установленного бандла исходников DSH; `DSH_SOURCE_ROOT` может явно выбрать чекаут исходников. Lockfile фиксирует автономные публичные инструменты сборки, когда такое окружение подготавливается отдельно.
Для приватного пререлиза DSH храните выданные npm-учётные данные вне этого репозитория (например, в пользовательском или временном `.npmrc`) и запускайте запрошенную версию напрямую:
```sh
pnpm dlx --package=@deepseek-ai/dsh@0.1.0-rc.6 dsh web
```
Никогда не коммитьте `.npmrc`, `NPM_TOKEN` или скопированные учётные данные реестра. Этот репозиторий по умолчанию игнорирует локальную npm-конфигурацию.
`test:host` выполняет реальный точный рендер, проверяет геометрию IHDR PNG и SHA-256, проверяет по HTTP неизменяемые возможности изображений и документов и убеждается, что ассеты просмотрщика можно предоставлять. Ожидаемые размеры зависят от фикстуры.
## Экосистема
DSH OpenPencil — это плагин DeepSeek Harness для **[OpenPencil](https://github.com/ZSeven-W/openpencil)** — первого в мире открытого ИИ-нативного инструмента векторного дизайна — и часть семейства **[ZSeven-W](https://github.com/ZSeven-W)** чистых Rust-инструментов с ИИ-нативностью.
| Проект | Что это |
| ------- | ---------- |
| **[OpenPencil](https://github.com/ZSeven-W/openpencil)** | Инструмент дизайна, которым управляет этот плагин: генерация от промпта к холсту, параллельные команды агентов, файлы `.op` как дизайн-код и встроенный MCP-сервер. Точные превью, интерактивный холст и управляемый редактор здесь работают на самом OpenPencil. |
| **[agent-rs](https://github.com/ZSeven-W/agent-rs)** | Чистый Rust-асинхронный рантайм для запуска LLM-агентов: мульти-провайдерный, с инструментами на всём пути, структурированными разрешениями, настоящим MCP и нулём `unsafe`. Обеспечивает встроенный агентный рантайм OpenPencil. |
| **[jian](https://github.com/ZSeven-W/jian)** | Чистый Rust UI-фреймворк на GPU-Skia: виджеты, раскладка, события и горячая перезагрузка в одном стеке. UI-фреймворк OpenPencil и источник фолбэк-рендерера этого плагина. |
| **[Zode](https://github.com/ZSeven-W/zode)** | Открытый ИИ-нативный ассистент кодинга для вашего терминала: читает ваш код, выполняет команды и управляет OpenPencil через MCP. |
| **[noema](https://github.com/ZSeven-W/noema)** | Локальная, не векторная система памяти для агентов кодинга: долговечная память в виде обозримых файлов, работает в разных рантаймах. |
| **[openpencil-skill](https://github.com/ZSeven-W/openpencil-skill)** | Плагин-скилл для LLM, обучающий ИИ-агентов проектировать с помощью `op`, — компаньон этого DSH-плагина. |
## Участие в разработке
Вклад приветствуется! Форкните и клонируйте репозиторий, создайте ветку, запустите `pnpm run build` и тестовые наборы, коммитьте с [Conventional Commits](https://www.conventionalcommits.org/) и открывайте PR в `main`.
## Сообщество
Присоединяйтесь к нашему Discord
— Задавайте вопросы, делитесь дизайнами, предлагайте фичи.
**Признанное сообщество: [LINUX DO](https://linux.do/)**
## Лицензия
[MIT](./LICENSE) — Copyright (c) 2026 ZSeven-W
Сторонние компоненты перечислены в [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).