kingkont 0.2.0 → 0.4.0

package/README.md

@@ -60,6 +60,19 @@ macOS) — переустановка приложения их не теряе
 | Cut / Copy / Paste | `Cmd+X` / `Cmd+C` / `Cmd+V` |
 | Esc | закрыть любую модалку |
 
+## Скилл для Claude Code
+
+Чтобы Claude Code в любой сессии умел запускать редактор для текущей папки:
+
+```bash
+npx kingkont install-skill            # для всех проектов: ~/.claude/skills/kingkont/
+npx kingkont install-skill --project  # только для текущего проекта: ./.claude/skills/kingkont/
+```
+
+После этого в новой сессии Claude Code достаточно сказать «открой kingkont»
+или «запусти редактор» — Claude увидит скилл, выполнит `npx -y kingkont serve`
+в текущей папке и подскажет URL для Chrome.
+
 ## Разработка
 
 ```bash

package/bin/kingkont.js

@@ -12,16 +12,37 @@ function showHelp() {
 KingKont · Chatium — видео-редактор сериала
 
 Запуск:
-  npx kingkont               запустить Electron-приложение (рекомендуется)
-  npx kingkont serve         запустить только HTTP-сервер; URL для Chrome
-  npx kingkont serve <path>  то же, путь к проекту/cwd по умолчанию
+  npx kingkont                запустить Electron-приложение (рекомендуется)
+  npx kingkont serve          запустить только HTTP-сервер; URL для Chrome
+  npx kingkont serve <path>   то же, путь к проекту/cwd по умолчанию
+  npx kingkont install-skill  установить Skill для Claude Code (~/.claude/skills/kingkont)
 
 Опции:
   --port <N>   порт сервера (по умолчанию 17893)
+  --project    install-skill: положить в .claude/skills/ текущей папки
   --help, -h   эта справка
 `);
 }
 
+function installSkill() {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const isProject = args.includes('--project');
+  const dest = isProject
+    ? path.resolve(process.cwd(), '.claude', 'skills', 'kingkont')
+    : path.join(os.homedir(), '.claude', 'skills', 'kingkont');
+  const src = path.join(root, 'skill', 'SKILL.md');
+  if (!fs.existsSync(src)) {
+    console.error('Шаблон SKILL.md не найден в пакете:', src);
+    process.exit(1);
+  }
+  fs.mkdirSync(dest, { recursive: true });
+  fs.copyFileSync(src, path.join(dest, 'SKILL.md'));
+  console.log(`✓ KingKont skill установлен: ${path.join(dest, 'SKILL.md')}`);
+  console.log('  В новой сессии Claude Code (или после /reload) скилл будет доступен:');
+  console.log('  попроси «открой kingkont» в папке проекта.');
+}
+
 if (args.includes('--help') || args.includes('-h')) {
   showHelp();
   process.exit(0);
@@ -30,6 +51,11 @@ if (args.includes('--help') || args.includes('-h')) {
 const portIdx = args.indexOf('--port');
 const port = portIdx >= 0 ? parseInt(args[portIdx + 1], 10) : 17893;
 
+if (args[0] === 'install-skill') {
+  installSkill();
+  process.exit(0);
+}
+
 if (args[0] === 'serve') {
   // Только Node-сервер. FSAH-API в Chrome требует user-gesture для
   // showDirectoryPicker — юзер сам выбирает папку через UI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kingkont",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "KingKont · Chatium — нод-редактор сцен с AI-генерацией (картинки/видео/голос/SFX/музыка/текст)",
   "main": "main.js",
   "bin": {
@@ -14,6 +14,7 @@
     "assets/**/*",
     "bin/**/*",
     "scripts/**/*",
+    "skill/**/*",
     "README.md"
   ],
   "engines": {

package/skill/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: kingkont
+description: Use this skill when the user works with a KingKont project — a film/series scene editor where each scene is a folder with scene.json. Triggers — fraзы вроде «открой/запусти kingkont», «открой редактор сцен», «добавь сцену/персонажа/локацию», «добавь ноду на холст», «сгенерируй картинку/видео/голос/SFX/музыку/текст», или работа с папкой содержащей _characters/ _locations/ <scene>/scene.json. Skill знает формат данных и API-ключи из настроек kingkont, может править scene.json напрямую и запускать UI редактора через `npx -y kingkont serve` для визуальной работы.
+---
+
+# KingKont · Chatium — Skill
+
+KingKont — нод-редактор сцен фильма/сериала с AI-генерацией. Каждая сцена/
+персонаж/локация — папка на диске с `scene.json` и подпапками для медиа.
+Формат plain JSON + plain files: всё можно читать и менять руками или
+через AI-агента, не запуская сам редактор.
+
+## Когда использовать этот skill
+
+- Юзер работает в папке-проекте KingKont (есть `_characters/`,
+  `_locations/`, любая папка с `scene.json`, или файл `CLAUDE.md` в корне).
+- Просит «открой редактор», «запусти kingkont», «открой проект» —
+  поднимаешь UI через `npx -y kingkont serve` (см. ниже).
+- Просит править данные: «добавь персонажа Анна», «добавь сцену
+  «Прощание»», «вставь текстовую ноду на сцену 3 с этим текстом», «свяжи
+  ноды @Анна и @сценарий», «сгенерируй картинку», «озвучь реплику» — это
+  работа со scene.json и/или вызов API; делается без открытия UI.
+- Любые правки тексту, перестановка нод, чистка истории, бэкап — все
+  через прямую правку `scene.json` и `texts/*.md`.
+
+## Как открыть UI редактора
+
+```bash
+npx -y kingkont serve
+```
+
+Печатает `▶ KingKont готов: http://localhost:17893/`. Скажи юзеру открыть
+этот URL в **Chrome / Edge / Brave** (Safari/Firefox не поддерживают
+File System Access API). На macOS можно открыть автоматом:
+
+```bash
+open -a "Google Chrome" "http://localhost:17893/"
+```
+
+Альтернатива — Electron-приложение (без браузера): `npx -y kingkont`.
+
+## Формат проектной папки
+
+```
+<root>/
+├── CLAUDE.md             ← подробный формат (создаётся редактором при первом
+│                            открытии в его UI; идентичен этому skill, но
+│                            живёт рядом с проектом)
+├── _characters/
+│   └── <имя>/            ← одна доска на персонажа
+├── _locations/
+│   └── <имя>/            ← одна доска на локацию
+├── <имя сцены>/          ← сцены лежат в корне как любые папки
+│   │                       (имена не начинающиеся с `_` и `.`,
+│   │                        не равные _characters / _locations)
+│   ├── scene.json        ← главный файл — описан ниже
+│   ├── clips/            ← видео (mp4, mov, webm)
+│   ├── images/           ← картинки (jpg, png, webp)
+│   ├── audio/            ← аудио (mp3, wav, m4a)
+│   └── texts/            ← .md-файлы текстовых нод
+├── _deleted/             ← корзина: при удалении ноды/доски файл/папка
+│                            переезжает сюда. Cmd+Z в редакторе
+│                            восстанавливает.
+└── (любые другие файлы редактор не трогает)
+```
+
+## Формат `scene.json` (полный)
+
+```json5
+{
+  "nodes": [
+    {
+      "id": "uuid",                          // UUID v4, уникальный в пределах доски
+      "type": "image" | "video" | "audio" | "text",
+      "name": "опц. имя для @-ссылок",       // используется в [@name] и автокомплите
+      "file": "images/foo.jpg",              // относительный путь в папке доски
+      "x": 100, "y": 200,                    // координаты на холсте (логические px)
+      "width": 280, "height": 320,           // опц., если юзер ресайзил
+      "generated": {                          // опц., если создано генерацией
+        "kind": "image" | "video" | "audio" | "text",
+        "subKind": "sfx" | "music",          // только для audio: тип эффекта
+        "prompt": "...",                     // финальный промпт после resolve
+        "rawPrompt": "...",                  // исходный с [@ref]
+        "translatedPrompt": "...",           // для SFX/music: en-перевод (для ElevenLabs)
+        "model": "nano-banana-2" | "bytedance/seedance-2"
+               | "eleven_v3" | "eleven-sfx" | "eleven-music"
+               | "anthropic/claude-sonnet-4" | ...,
+        "modelKey": "ключ модели для KIE",
+        "voiceId": "...",                    // для голоса
+        "voiceName": "...",
+        "tones": ["шепот", ...],             // ElevenLabs v3 audio-tags
+        "durationSeconds": 3,                // для SFX
+        "durationMs": 30000,                 // для music
+        "refs": [{ "name": "...", "type": "image", "file": "..." }],
+        "state": "submitting" | "queued" | "generating" | "success" | "error",
+        "taskId": "..."                      // KIE job id
+      },
+      "status": "generating" | "draft" | "error",  // отсутствует если нода готова
+      "error": "...",
+      "history": [...],                      // история правок (через ⇄ Заменить)
+      "historyIndex": 0
+    }
+    // Текст ноды (n.text для type=text) в JSON НЕ хранится; контент лежит в texts/<file>.md
+  ],
+  "connections": [
+    { "from": "node-id", "to": "node-id" }   // направленная связь
+  ],
+  "view": {
+    "scrollLeft": 0,                          // pan/zoom холста для восстановления
+    "scrollTop": 0,
+    "zoom": 1.0
+  },
+  "character": {                              // только для _characters/<name>/scene.json
+    "characterSheet": "images/sheet.jpg",     // референс-картинка персонажа
+    "voice": "elevenlabs-voice-id",           // дефолтный голос для генерации
+    "voiceName": "...",
+    "tone": "по умолчанию",
+    "commonTones": ["шепот", "крик", ...],
+    "lastTones": [],
+    "replicas": [
+      { "id": "...", "text": "...", "audio": "audio/replica_1.mp3", ... }
+    ]
+  },
+  "location": {                               // только для _locations/<name>/scene.json
+    "sheet": "images/sheet.jpg"
+  },
+  "timeline": {                               // монтажный лист сцены
+    "tracks": [
+      {
+        "id": "tv",
+        "name": "Видео" | "Голос" | "Эффекты" | "Музыка" | ...,
+        "kind": "video" | "audio",
+        "clips": [
+          {
+            "id": "uuid",
+            "nodeId": "node-id" | null,       // привязка к ноде (если из неё)
+            "type": "video" | "image" | "audio",
+            "file": "clips/foo.mp4",
+            "name": "...",
+            "duration": 5.0,                  // в секундах
+            "start": 0,                       // позиция начала на дорожке
+            "trimStart": 0,                   // обрезка спереди
+            "sourceDuration": 5.0,            // полная длительность файла
+            "_durationLoaded": true,
+            "groupId": "...",                 // опц., группа клипов
+            "disabled": false                 // skip при playback
+          }
+        ]
+      }
+    ],
+    "playhead": 0.27                          // секунды
+  },
+  "history": {                                // undo/redo стек редактора
+    "past":  [{ "ts": ..., "label": "...", "snap": "JSON-string", "movedFiles": [...] }],
+    "future": [...]
+  }
+}
+```
+
+## Текстовые ноды
+
+`node.text` в JSON отсутствует. Контент текстовой ноды лежит в
+`texts/<filename>.md` (путь в `node.file`). Редактируй .md руками; редактор
+подхватит изменения при следующем открытии доски.
+
+Чтобы создать новую текстовую ноду через правку файлов:
+
+1. Записать содержимое в `<board>/texts/some-name.md`.
+2. Добавить ноду в `<board>/scene.json`:
+   ```json5
+   {
+     "id": "<uuid v4>",
+     "type": "text",
+     "name": "опционально, для @-ссылок",
+     "file": "texts/some-name.md",
+     "x": 100, "y": 100
+   }
+   ```
+
+## Файловые операции
+
+- **Удаление ноды**: файл переезжает в `<root>/_deleted/<уникальное-имя>`.
+  Cmd+Z в редакторе восстанавливает (через movedFiles в history).
+- **Замена/перегенерация**: новый файл записывается в подпапку, старый
+  сохраняется в `node.history[]` для отката (⇄ Заменить).
+- **Импорт через drag-drop**: файлы копируются в правильную подпапку с
+  уникальным именем, нода создаётся автоматически.
+
+## API-ключи (для генерации)
+
+Хранятся в `~/Library/Application Support/KingKont/settings.json` (macOS)
+или `~/.config/KingKont/settings.json` (Linux):
+
+```json
+{
+  "kieKey":         "...",   // для картинок и видео (api.kie.ai)
+  "elevenKey":      "...",   // для голоса/SFX/музыки (elevenlabs.io)
+  "openrouterKey":  "..."    // для текста и vision (openrouter.ai)
+}
+```
+
+Если ключа не хватает — попроси юзера задать в редакторе через `Cmd+,`.
+
+## Программная генерация (без UI)
+
+Запусти `npx kingkont serve` в фоне — сервер становится прокси к KIE/
+ElevenLabs/OpenRouter с уже подставленными ключами из settings.json.
+Дёргай endpoints прямым curl/fetch:
+
+### `POST http://localhost:17893/api/text` — текст (OpenRouter)
+```json
+{
+  "prompt": "...",
+  "model": "anthropic/claude-sonnet-4",  // или openai/gpt-4o, google/gemini-..., etc
+  "system": "опционально system prompt",
+  "images": [{ "url": "data:image/jpeg;base64,..." }]  // vision-режим
+}
+```
+Возвращает `{ "text": "...", "model": "..." }`.
+
+### `POST http://localhost:17893/api/sfx` — звуковой эффект (ElevenLabs)
+```json
+{
+  "text": "heavy door slamming with echo",   // лучше английский
+  "durationSeconds": 3,                       // 0.5–22, опц.
+  "promptInfluence": 0.3                      // 0–1, опц.
+}
+```
+Возвращает `audio/mpeg` (mp3 stream). Сохрани в `<board>/audio/sfx_<ts>.mp3`.
+
+### `POST http://localhost:17893/api/music` — музыка (ElevenLabs)
+```json
+{
+  "prompt": "epic orchestral cinematic, slow buildup, hopeful",
+  "durationMs": 30000   // опц.
+}
+```
+Возвращает `audio/mpeg`.
+
+### `POST http://localhost:17893/api/tts` — речь (ElevenLabs)
+```json
+{
+  "text": "...",
+  "voiceId": "JBFqnCBsd6RMkjVDRZzb",   // ElevenLabs voice id
+  "modelId": "eleven_v3"
+}
+```
+Возвращает `audio/mpeg`.
+
+### `POST http://localhost:17893/api/generate` — image/video (KIE, async)
+```json
+{
+  "kind": "image" | "video",
+  "prompt": "...",
+  "model": "nano-banana-2" | "flux-schnell" | "sdxl-lightning"
+         | "seedream" | "seedream-5-lite" | "grok"
+         | "seedance-2",  // для video — bytedance/seedance-2
+  "imageInputs": ["http(s) URL"],        // опц., референсы
+  "aspectRatio": "16:9",
+  "resolution": "1K"
+}
+```
+Возвращает `{ "taskId": "..." }`. Затем поллить:
+
+### `GET http://localhost:17893/api/poll?taskId=...`
+Возвращает `{ "status": "pending" | "done" | "error", "url": "https://..." }`.
+Когда `done` — скачай `url` (это публичный URL картинки/видео).
+
+### `POST http://localhost:17893/api/upload` — загрузить локальный файл в KIE
+Передай binary в body, заголовок `X-File-Name: filename.jpg`.
+Возвращает `{ "url": "https://..." }` — этот URL можно класть в
+`imageInputs`.
+
+### `GET http://localhost:17893/api/proxy?url=...`
+Прокси для скачивания произвольных http(s)-URL минуя CORS.
+
+## Распространённые сценарии для агента
+
+**«Открой редактор»** → `npx -y kingkont serve` + сообщить URL.
+
+**«Добавь персонажа Анна»** → `mkdir -p _characters/Анна`, создать
+минимальный `_characters/Анна/scene.json`:
+```json
+{ "nodes": [], "connections": [], "character": { "voice": null }, "view": { "zoom": 1, "scrollLeft": 0, "scrollTop": 0 }, "timeline": { "tracks": [], "playhead": 0 } }
+```
+
+**«Добавь текстовую ноду на сцену "Прощание" с таким текстом ...»**:
+1. Записать `Прощание/texts/<slug>.md` с текстом.
+2. Прочитать `Прощание/scene.json`, добавить новую node-запись (`type: 'text'`,
+   уникальный uuid v4, `file: "texts/<slug>.md"`, `x/y` подальше от
+   существующих), записать обратно.
+
+**«Свяжи ноды @А и @Б»** → найти их id по `name` в `scene.json`, добавить
+`{from: "<id-A>", to: "<id-Б>"}` в `connections[]`.
+
+**«Сгенерируй SFX "камни сыпятся"»** → `POST /api/sfx` с translated en-промптом
+(модель Sound Generation на не-en тексте делает TTS-fallback), сохранить mp3
+в `<board>/audio/sfx_<ts>.mp3`, добавить audio-ноду в scene.json с
+`generated.subKind = "sfx"`.
+
+**Не трогай**: `node.history[]`, `metadata.history.past/future` — это
+снимки сцены для Cmd+Z. Поломав, потеряешь возможность отката. Поля с
+UUID `id` тоже не меняй — на них завязаны связи и timeline-clips.
+
+## Шорткаты редактора (для подсказок юзеру)
+
+- `Cmd+O` — открыть проект
+- `Cmd+N` — новая сцена
+- `Cmd+W` — закрыть проект (при втором нажатии — свернуть)
+- `Cmd+,` — настройки (API-ключи)
+- `Cmd+Z` / `Cmd+Shift+Z` — undo/redo
+- `Cmd+X / C / V` — cut/copy/paste нод и клипов
+- ПКМ по ноде / клипу / папке — контекст-меню
+- ПКМ на пустом холсте — добавить новую ноду (Текст / Сгенерить ...)
+- Тяга от точки на правом краю ноды → меню «что генерить»