kingkont 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kingkont",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "KingKont · Chatium — нод-редактор сцен с AI-генерацией (картинки/видео/голос/SFX/музыка/текст)",
   "main": "main.js",
   "bin": {

package/skill/SKILL.md

@@ -1,84 +1,315 @@
 ---
 name: kingkont
-description: Use this skill when the user asks to open the KingKont editor, edit scenes, work on a film/series project, or generate content (images, video, voice, SFX, music, text) for a movie project in the current folder. The skill starts the KingKont HTTP server on the current working directory and gives the user a localhost URL to open in Chrome.
+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 is a node-graph editor for film/series scenes with AI generation
-(images via KIE, voice/SFX/music via ElevenLabs, text via OpenRouter).
-Each "scene" is a folder on disk with `scene.json`, files live next to it.
+KingKont — нод-редактор сцен фильма/сериала с AI-генерацией. Каждая сцена/
+персонаж/локация — папка на диске с `scene.json` и подпапками для медиа.
+Формат plain JSON + plain files: всё можно читать и менять руками или
+через AI-агента, не запуская сам редактор.
 
-## When to use
+## Когда использовать этот skill
 
-The user is working with a film/series project in the current folder and asks
-to open the KingKont editor, edit scenes, view boards visually, or generate
-media. Trigger phrases:
+- Юзер работает в папке-проекте KingKont (есть `_characters/`,
+  `_locations/`, любая папка с `scene.json`, или файл `CLAUDE.md` в корне).
+- Просит «открой редактор», «запусти kingkont», «открой проект» —
+  поднимаешь UI через `npx -y kingkont serve` (см. ниже).
+- Просит править данные: «добавь персонажа Анна», «добавь сцену
+  «Прощание»», «вставь текстовую ноду на сцену 3 с этим текстом», «свяжи
+  ноды @Анна и @сценарий», «сгенерируй картинку», «озвучь реплику» — это
+  работа со scene.json и/или вызов API; делается без открытия UI.
+- Любые правки тексту, перестановка нод, чистка истории, бэкап — все
+  через прямую правку `scene.json` и `texts/*.md`.
 
-- "открой kingkont", "запусти kingkont", "open kingkont"
-- "редактор сцен", "scene editor"
-- "видео-редактор", "film editor"
-- if the current folder contains `CLAUDE.md` mentioning "KingKont" or
-  has subfolders like `_characters/`, `_locations/` and `scene.json` files
-  — this is a KingKont project.
-
-## How to launch
-
-Run **in the current working directory** (the project root):
+## Как открыть UI редактора
 
 ```bash
 npx -y kingkont serve
 ```
 
-It will:
-1. Auto-install `kingkont` from npm (if not cached).
-2. Spawn the HTTP server on port 17893.
-3. Print `▶ KingKont готов: http://localhost:17893/` when ready.
-
-Then tell the user to open the URL in **Chrome / Edge / Brave** (Safari and
-Firefox do not support the File System Access API needed to open project
-folders). On macOS you can open it for the user:
+Печатает `▶ KingKont готов: http://localhost:17893/`. Скажи юзеру открыть
+этот URL в **Chrome / Edge / Brave** (Safari/Firefox не поддерживают
+File System Access API). На macOS можно открыть автоматом:
 
 ```bash
 open -a "Google Chrome" "http://localhost:17893/"
 ```
 
-The user clicks "Открыть проект" in the editor and selects the current
-folder.
+Альтернатива — Electron-приложение (без браузера): `npx -y kingkont`.
 
-## Project structure (for reference)
+## Формат проектной папки
 
 ```
-<project root>/
-├── CLAUDE.md           # auto-created on first open, describes format
-├── _characters/<name>/ # one board per character
-├── _locations/<name>/  # one board per location
-├── <scene name>/       # scenes live as folders in the root
-│   ├── scene.json      # all metadata (nodes, connections, timeline, history)
-│   ├── clips/          # videos
-│   ├── images/         # frames
-│   ├── audio/          # mp3/wav
-│   └── texts/          # .md files for text nodes
-└── _deleted/           # trash; Cmd+Z restores
+<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` is plain JSON, you can read/edit it directly.
+## Формат `scene.json` (полный)
 
-## API keys
+```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": [...]
+  }
+}
+```
 
-If the user hasn't set them, the editor will ask via Cmd+, modal:
-- **KIE** for images/video
-- **ElevenLabs** for voice/SFX/music
-- **OpenRouter** for text and vision
+## Текстовые ноды
 
-Stored at `~/Library/Application Support/KingKont/settings.json` (macOS)
-or `~/.config/KingKont/settings.json` (Linux).
+`node.text` в JSON отсутствует. Контент текстовой ноды лежит в
+`texts/<filename>.md` (путь в `node.file`). Редактируй .md руками; редактор
+подхватит изменения при следующем открытии доски.
 
-## If user wants the Electron app instead of browser
+Чтобы создать новую текстовую ноду через правку файлов:
 
-```bash
-npx -y kingkont
+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)
+}
 ```
 
-This launches the desktop Electron app (downloads electron@32 on first run,
-≈70 MB).
+Если ключа не хватает — попроси юзера задать в редакторе через `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 нод и клипов
+- ПКМ по ноде / клипу / папке — контекст-меню
+- ПКМ на пустом холсте — добавить новую ноду (Текст / Сгенерить ...)
+- Тяга от точки на правом краю ноды → меню «что генерить»