@ran-sh/dsh-crew 0.3.0

package/README.ru.md

@@ -0,0 +1,359 @@
+<p align="center">
+  <img src="./docs/images/dsh-crew-logo.png" alt="DSH Crew" width="120" />
+</p>
+
+<h1 align="center">DSH Crew</h1>
+
+<p align="center">
+  <strong>Плагин <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>: отправляйте работу агентам DSH из Claude Code / Codex, не отказываясь от встроенного интерфейса субагентов хоста.</strong><br />
+  <sub>Встроенный интерфейс прогресса &bull; Политика уровней и эскалация &bull; Сессии DSH внутри хоста &bull; Зрение и генерация изображений &bull; Установка в один клик</sub>
+</p>
+
+<p align="center">
+  <sub>GitHub: <code>Ran-sh/dsh-crew</code> &middot; Текущий релиз плагина: <code>0.1.0-rc.1</code> &middot; Проверено с DSH <code>0.1.0-rc.6</code></sub>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> &middot; <a href="./README.zh.md">简体中文</a> &middot; <a href="./README.zh-TW.md">繁體中文</a> &middot; <a href="./README.ja.md">日本語</a> &middot; <a href="./README.ko.md">한국어</a> &middot; <a href="./README.fr.md">Français</a> &middot; <a href="./README.es.md">Español</a> &middot; <a href="./README.de.md">Deutsch</a> &middot; <a href="./README.pt.md">Português</a> &middot; <a href="./README.ru.md"><b>Русский</b></a> &middot; <a href="./README.hi.md">हिन्दी</a> &middot; <a href="./README.tr.md">Türkçe</a> &middot; <a href="./README.th.md">ไทย</a> &middot; <a href="./README.vi.md">Tiếng Việt</a> &middot; <a href="./README.id.md">Bahasa Indonesia</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Ran-sh/dsh-crew/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Ran-sh/dsh-crew?color=64748b" alt="License" /></a>
+</p>
+
+<br />
+
+<p align="center">
+  <img src="./docs/images/dsh-crew-overview.png" alt="DSH Crew — settings page" width="100%" />
+</p>
+<p align="center"><sub>Страница настроек DSH Crew — интеграции хоста, политика отправки, выполнение и мультимодальный мост</sub></p>
+
+## Зачем нужен DSH Crew
+
+DSH Crew — плагин для [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), опенсорсного агентского харнесса. Он позволяет отправлять работу агентам DSH из Claude Code и Codex: оркестратор сохраняет собственную модель, работа выполняется на настоящем агенте DSH с инструментами, песочницей, пресетами и историей сессий этого харнесса, а хост по-прежнему отображает его как встроенного субагента с живым прогрессом.
+
+Работу выполняет агент DSH, а не голый вызов модели. Уровни (`flash` / `pro`) определяют, какой объём возможностей получает агент из настроенного списка моделей харнесса — сегодня это DeepSeek V4 Flash и V4 Pro, — поэтому смена модели в DSH не требует изменений здесь.
+
+<table>
+<tr>
+<td width="50%">
+
+### 🧵 Встроенный интерфейс прогресса
+
+Воркеры отображаются как обычные субагенты в Claude Code / Codex — счётчик отправок, текущий шаг, вызовы инструментов и расход токенов видны в собственной панели задач хоста, а также сегмент статусной строки claude-hud: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3`.
+
+</td>
+<td width="50%">
+
+### 🎚️ Политика уровней и эскалация
+
+`flash` для механической работы, `pro` для решения сложных задач, `effort` от `off` до `max`. `tier_policy` может ограничить каждую отправку одним уровнем на уровне инструмента, а `escalate_on_failure` один раз повторяет неудачный запуск flash на pro — на основе фактов, а не предположений о сложности заранее.
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🏛️ Сессии DSH внутри хоста
+
+Когда бандл установлен в профиле DSH, каждый воркер — это полноценная сессия DSH: она видна в веб-интерфейсе, сгруппирована по рабочей директории и подключена с выбранным вами пресетом Agent для каждого уровня. Если DSH не запущен, отправка переключается на автономный рантайм DSH, поэтому CI и среды без графического интерфейса продолжают работать.
+
+</td>
+<td width="50%">
+
+### 👁️ Зрение и генерация изображений
+
+Модели DSH работают только с текстом. `describe_image` и `generate_image` заимствуют «глаза» и «кисть» у уже имеющихся у вас CLI — Claude, Codex, Grok, Antigravity — или у любого настроенного вами OpenAI-совместимого API. Вставленные изображения остаются видимыми в диалоге и доходят до модели в виде текста.
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🔌 Собственные провайдеры
+
+Подключите собственную конечную точку (Base URL + API-ключ + модели) или шаблон локальной команды. У каждого провайдера есть тест подключения: он проверяет доступность и авторизацию, а затем делает один реальный вызов зрения — чтобы вы узнали о проблемах сейчас, а не посреди задачи.
+
+</td>
+<td width="50%">
+
+### 📦 Установка в один клик
+
+Страница настроек устанавливает и обновляет за вас плагин Claude Code и файлы ролей Codex — регистрация маркетплейса, список разрешений, подключение HUD, абсолютные пути, сформированные для этой машины, — и так же легко их восстанавливает. Перед изменениями все файлы настроек резервируются.
+
+</td>
+</tr>
+</table>
+
+## Как это работает
+
+```
+Claude Code / Codex (orchestrator, keeps its own model)
+  └─ ds-flash / ds-pro  ← native subagent shell (progress shows in the host's task UI)
+       └─ MCP: dsh_run_worker(tier, effort, cwd)
+            ├─ hub reachable → session inside DSH (visible in the Web UI, grouped by cwd)
+            └─ otherwise     → dsh-jsonrpc-agent runtime (worker.cordis.yml)
+                 └─ DeepSeek V4 Flash / Pro (DSH SDK, event stream → progress and token stats)
+```
+
+## Один запуск, два взгляда
+
+Диспетчеризация масштабируется вширь. Ниже восемнадцать worker'ов параллельно переводят этот README: хост считает их своими субагентами, а harness выполняет их как настоящие сессии.
+
+<p align="center">
+  <img src="./docs/images/dsh-crew-host.png" alt="Claude Code" width="100%" />
+</p>
+<p align="center"><sub>В Claude Code worker'ы dsh-crew выглядят как нативные субагенты; сегмент statusline показывает работающие tier'ы, время и токены.</sub></p>
+
+<p align="center">
+  <img src="./docs/images/dsh-crew-jobs.png" alt="DSH Crew" width="100%" />
+</p>
+<p align="center"><sub>Панель DSH Crew показывает тот же запуск со стороны harness: какой хост отправил задачу, её tier и effort, прогресс и расход токенов.</sub></p>
+
+## Установка
+
+Установить из GitHub в профиль DSH:
+
+```bash
+node scripts/setup.mjs install   # Safe install: see the canonical Install section of README.md (dedicated Crew home/profile; official web profile is never modified).
+Repository source: github:Ran-sh/dsh-crew
+npx -y @deepseek-ai/dsh web
+```
+
+Или для локальной разработки прямо из исходников:
+
+```bash
+node scripts/setup.mjs install   # Safe install: see the canonical Install section of README.md (dedicated Crew home/profile; official web profile is never modified).
+Repository source: github:Ran-sh/dsh-crew
+npx -y @deepseek-ai/dsh web
+```
+
+Протокол `link:` делает симлинк зависимости профиля на этот репозиторий, поэтому пересборка видна сразу.
+
+### Настроить учётные данные DeepSeek (только standalone)
+
+В режиме hub — установке выше — воркеры работают внутри экземпляра DSH и используют учётные данные DeepSeek, которые уже для него настроены. Ничего больше не нужно настраивать.
+
+Только standalone-режим (резервный вариант) требует собственного ключа: отправка из Claude Code / Codex без запущенного экземпляра DSH запускает worker runtime в отдельном процессе. Получите API-ключ на [platform.deepseek.com](https://platform.deepseek.com) и запишите его в `~/.config/dsh-crew/.env`:
+
+```
+DEEPSEEK_API_KEY=sk-...
+```
+
+### Проверка
+
+```bash
+node scripts/smoke.mjs
+```
+
+Smoke test отправляет одно дешёвое задание по доступному пути — hub, если запущен экземпляр DSH, иначе standalone — и выводит, какой из них был использован. Примерно через десять секунд должно появиться `smoke test passed — configuration OK`. При ошибке печатается причина, относящаяся к проверенному пути.
+
+Затем откройте Настройки → DSH Crew и установите интеграции Claude Code / Codex одним щелчком.
+
+## Контекст и терминология
+
+- **DSH** (DeepSeek Harness): опенсорсный агентский харнесс DeepSeek, кодовый агент в форме веб-интерфейса, похожий на Claude Code, но работающий на моделях DeepSeek.
+- **MCP** (Model Context Protocol): протокол интеграции ИИ-инструментов от Anthropic, позволяет LLM безопасно вызывать внешние инструменты и источники данных.
+- **Cordis bundle**: формат плагинов DSH; этот проект может работать автономно как MCP-сервис или устанавливаться в DSH Web в режиме hub.
+- **tier**: уровень возможностей — какой слот из настроенного списка моделей DSH получает воркер. `flash` — быстрый и дешёвый (простые задачи), `pro` — глубже рассуждает (сложные задачи). Сейчас они соответствуют DeepSeek V4 Flash и V4 Pro; поменяйте модели в DSH — и здесь ничего менять не нужно.
+- **worker**: агент DSH, выполняющий работу, — полноценная сессия со своими инструментами, песочницей и пресетом, а не голый вызов модели.
+- **effort**: сила рассуждений, `off` = без рассуждений, `high` = высокие вложения в рассуждения, `max` = максимальные вложения в рассуждения.
+
+## Claude Code
+
+### Установка
+
+Установка в один клик (выберите один вариант):
+
+- **Страница настроек DSH** (когда установлен режим hub): Settings → DSH Crew → "Install to Claude Code"
+- **Командная строка**: `node src/install/cli.mjs all`
+
+Оба варианта делают одно и то же: регистрируют локальный маркетплейс (родительская директория `dsh-plugins/` как корень маркетплейса) + `claude plugin install` + список разрешений инструментов MCP + настройка сегмента статуса воркеров claude-hud (автоматическое резервное копирование settings.json перед изменениями, идемпотентно). **После установки перезапустите сессию, чтобы изменения вступили в силу.**
+
+### Использование
+
+- Прямо в диалоге скажите "dispatch X to ds-flash" или "dispatch X to ds-pro", и субагент выполнит задачу
+- Счётчик отправок и прогресс в реальном времени отображаются в интерфейсе задач Claude Code
+- **Сегмент статусной строки HUD**: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3` (текущий уровень / затраченное время / расход токенов / количество завершённых)
+  - При локальной разработке `statusline/statusline.sh` или `statusline/worker-segment.sh` можно интегрировать отдельно
+- **Длительные задачи**: у CC есть лимиты таймаута для вызовов MCP (`MCP_TOOL_TIMEOUT` настраивается); для долгих задач оркестратор может использовать `dsh_spawn_worker` + опрос через `dsh_worker_result(wait_seconds)`
+- **Локальная разработка и отладка**: `claude --plugin-dir /path/to/dsh-crew` для временной загрузки
+
+
+### Команды сессии
+
+Переопределяют глобальные значения только для текущей сессии и применяются на уровне инструмента, а не через промпт:
+
+| Команда | Что делает |
+|---|---|
+| `/dsh-crew:config` | Показать или задать значения по умолчанию для сессии: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<секунды>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `reset` |
+| `/dsh-crew:on` · `/dsh-crew:off` | Включить или выключить диспетчеризацию в этой сессии (выключено — жёсткий запрет: инструмент отказывает) |
+| `/dsh-crew:status` | Статус worker-задач в реальном времени: tier, прогресс, токены, текущий инструмент |
+
+## Codex
+
+### Установка
+
+Рекомендуется использовать установщик (автоматически формирует пути для этой машины, копирует команды `/dsh-config`, `/dsh-status`):
+
+```bash
+node src/install/cli.mjs codex
+```
+
+Либо скопируйте вручную (после копирования потребуется вручную исправить пути):
+
+```bash
+cp codex/agents/*.toml ~/.codex/agents/    # global or project-level .codex/agents/
+```
+
+Файлы ролей поставляются с готовыми настройками:
+
+- конфигурация подключения MCP-сервера
+- `default_tools_approval_mode = "approve"` (**обязательно**, иначе вызовы инструментов автоматически отменяются в режиме exec)
+- `tool_timeout_sec = 3600`
+
+**Примечание**: при ручном копировании абсолютные пути в поле `args` нужно привести в соответствие с фактическим расположением установки; установщик делает это автоматически.
+
+### Использование
+
+- В интерактивном TUI выберите "spawn ds-pro to ...", чтобы отправить задачи; панели Active/Done показывают прогресс
+- Режим `codex exec` также может напрямую вызывать `dsh_run_worker`
+
+
+### Команды сессии
+
+Для Codex устанавливаются те же два промпта:
+
+| Команда | Что делает |
+|---|---|
+| `/dsh-config` | Показать или задать значения по умолчанию для сессии: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<секунды>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `reset` |
+| `/dsh-status` | Статус worker-задач в реальном времени: tier, прогресс, токены, текущий инструмент |
+
+## Инструменты MCP
+
+| Инструмент | Описание |
+|---|---|
+| `dsh_run_worker` | Синхронная отправка задачи (`tier`: flash/pro, `effort`: off/high/max, `cwd`), ожидает результат |
+| `dsh_spawn_worker` | Асинхронная отправка задачи, возвращает id задания (для параллельного веера) |
+| `dsh_worker_status` | Запрос прогресса всех заданий в реальном времени (ход/шаг/текущий инструмент/токены) |
+| `dsh_worker_result` | Получение результата, можно указать `wait_seconds` для ожидания |
+| `dsh_worker_cancel` | Отмена указанного задания и завершение его процесса рантайма |
+
+Прогресс одновременно зеркалируется в `~/.config/dsh-crew/status.d/` (по одному файлу-шарду на источник записи; его может читать statusline или внешний мониторинг).
+
+## Мультимодальность: зрение и генерация изображений
+
+**DeepSeek — текстовая модель**, не поддерживающая ввод и генерацию изображений. Этот плагин получает эти возможности извне через инструменты MCP:
+
+| Инструмент | Описание |
+|---|---|
+| `describe_image` | Отвечает на вопросы, просматривая изображения (скриншоты, макеты, диаграммы и т. д.), результаты кэшируются по ключу провайдер + модель + изображение + вопрос |
+| `generate_image` | Генерирует изображение по текстовому описанию, сохраняет по указанному абсолютному пути; результат — плоский растр (для редактирования слоёв требуется OpenPencil) |
+
+**Вставка изображений в сессию**: в DSH переключите модель на `DeepSeek (vision) ◉`, чтобы вставлять изображения напрямую. Изображения остаются в сессии и отображаются как обычно; плагин добавляет распознанный текст после них и удаляет изображения перед отправкой — вы видите изображение, модель читает текст.
+
+### Конфигурация
+
+На **странице настроек DSH → DSH Crew → Multimodal** (или отредактируйте `~/.config/dsh-crew/config.json` напрямую):
+
+**Провайдер зрения** (просмотр изображений):
+
+- `claude-code` (по умолчанию, использует haiku, недорого)
+- `codex` (использует GPT, можно указать конкретную модель)
+- `grok` (использует Grok)
+- `agy` (Antigravity)
+- `custom` (OpenAI-совместимый API или локальная команда)
+- `off` (отключено)
+
+**Провайдер генерации изображений** (генерация изображений):
+
+- `codex` (`$imagegen`, gpt-image-2)
+- `agy` (Nano Banana)
+- `grok` (Imagine)
+- `custom` (OpenAI-совместимый API или локальная команда)
+- `off` (отключено)
+
+### Собственный провайдер
+
+Два способа интеграции:
+
+**API**: любая OpenAI-совместимая конечная точка
+- Заполните Base URL, API Key, список моделей
+- Зрение использует `/chat/completions` со встроенными base64-изображениями
+- Генерация изображений использует `/images/generations`
+- **Чтобы получить возможность генерации, необходимо указать "image generation model"**, иначе провайдер появится только в списке выбора зрения
+
+**CLI**: шаблон локальной команды, плейсхолдеры подставляются безопасными ссылками
+- Зрение: `{image} {question} {model}` → ответ из stdout
+- Генерация изображений: `{prompt} {output} {size}` → команда должна записать файл в `{output}`
+- Заполните хотя бы одну команду; какая из них заполнена — та и определяет возможность
+
+**Тест подключения**: у каждого собственного провайдера есть кнопка проверки
+- API: проверка доступности конечной точки и авторизации, отправка реального запроса зрения для проверки
+- CLI: проверка исполняемого файла, запуск реальной команды для проверки
+- Генерация изображений: только валидация конфигурации, без реального вывода изображения
+
+**Заимствованные CLI по подписке** (claude / codex / grok / agy) требуют локального входа в систему; плагин не будет обходить их разрешения за вас.
+
+## Режим hub
+
+Этот пакет также является полноценным бандлом DSH (`dsh.bundle` + `cordis.patch.yml`). После установки в профиль DSH Web командой `dsh plugin add dsh-crew`:
+
+- **Сессии воркеров становятся полноценными**: выполняются как полноценные сессии в хосте DSH (`agents.create` + каскад модель/effort для каждой сессии + пресет по умолчанию), появляются в списке сессий веб-интерфейса, их можно открыть в любой момент, чтобы просмотреть полный ход выполнения
+- **Организация по рабочей директории**: управление сессиями воркеров по cwd в веб-интерфейсе
+- **Loopback API**:
+  - `POST/GET /_dsh/dsh-crew/jobs`: запуск задач, список, ожидание результатов (long-poll), отмена
+  - `GET /_dsh/dsh-crew/ping`: проверка работоспособности (MCP-прослойка использует её, чтобы определить, запущен ли hub)
+  - `POST /_dsh/dsh-crew/install`: установка интеграции Claude Code / Codex в один клик (бэкенд `src/install/`)
+- **Автоопределение**: MCP-прослойка CC/Codex автоматически определяет hub (переменная окружения `DSH_CREW_HUB`, по умолчанию `http://127.0.0.1:3080`)
+  - DSH Web запущен → задания выполняются в режиме hub (`mode: "hub"`)
+  - Не запущен → переключение на автономный рантайм
+
+## Выбор решения и ограничения
+
+### Обычные подписчики → подход с субагентом-оболочкой (рекомендуется)
+
+- **Текущее положение**: оболочка субагента Claude Code использует haiku как посредника; каждая отправка добавляет от сотен до тысяч токенов
+- **Компромисс**: небольшое количество токенов Anthropic в обмен на встроенный интерфейс задач, отображение прогресса в реальном времени и отсутствие дополнительной настройки
+- **Рекомендация**: если у вас уже есть подписка Claude Pro или вы используете Claude Code, выбирайте этот подход — удобно и прозрачно
+
+### Оплата по факту / CI-среды → подход с прямым роутером
+
+- **Текущее положение**: frontmatter субагента Claude Code не поддерживает прямое подключение сторонних моделей; эксперимент с роутером в scratchpad этого репозитория требует учётных данных API-ключа для Claude Code, но OAuth по подписке блокируется на стороне Anthropic ошибкой 403
+- **Рекомендации**:
+  - Если вы используете учётные данные API-ключа (не OAuth) и хотите экономить токены Anthropic, можно запустить локальный роутер для прямого подключения к DeepSeek
+  - CI-среды обычно тоже используют API-ключи; этот подход экономичнее (все токены — DeepSeek)
+  - Требуется самостоятельная проверка интеграции роутера (официально не поддерживается)
+
+### Запущенный DSH Web → режим hub включается автоматически
+
+- **Текущее положение**: если `dsh plugin add dsh-crew` установлен в профиль DSH Web, задания выполняются как полноценные сессии в хосте и появляются в списке сессий веб-интерфейса
+- **Рекомендация**: при итерациях локальной разработки рекомендуется включать режим hub — прогресс воркеров можно полностью наблюдать в веб-интерфейсе; для совместной работы на разных машинах или сред без веб-интерфейса используйте подход с оболочкой Claude Code / Codex
+
+### Известные моменты
+
+- Роль Codex теоретически может попробовать `model_provider`, указывающий напрямую на DeepSeek (не проверено); этот мост от него не зависит
+- Результат генерации изображений — плоский растр; для редактирования слоёв требуется OpenPencil
+- **Зависимости рантайма**: только `@modelcontextprotocol/sdk` и `zod`; `@deepseek-ai/*` — peerDependencies (предоставляются хостом DSH)
+- **Для Codex обязательно настроить**: `default_tools_approval_mode = "approve"`, иначе вызовы инструментов автоматически отменяются
+
+## Разработка
+
+```bash
+pnpm install
+node_modules/.bin/tsdown src/client/index.tsx --format cjs --platform browser \
+  --target es2022 --tsconfig tsconfig.client.json --out-dir .client-build --clean
+node scripts/build-client.mjs   # wraps the bundle for the DSH module loader
+node scripts/smoke.mjs          # dispatches one real flash task end to end
+```
+
+Зависимости рантайма — только `@modelcontextprotocol/sdk` и `zod`; каждый пакет `@deepseek-ai/*` является peer dependency, предоставляемой хостом DSH, что удерживает плагин в едином пространстве модулей хоста.
+
+## Экосистема
+
+- [DSH Noema](https://github.com/ZSeven-W/dsh-noema) — долговременная память для DSH
+- [DSH OpenPencil](https://github.com/ZSeven-W/dsh-openpencil) — просмотр и редактирование дизайн-документов `.op` прямо в диалоге
+
+## Лицензия
+
+MIT