ktalk-cli 2.0.0__tar.gz → 3.0.0__tar.gz

{ktalk_cli-2.0.0 → ktalk_cli-3.0.0}/.gitignore

@@ -25,5 +25,9 @@ docs/*.har
 *.db
 .beads-credential-key
 .beads/proxieddb/
+# Аудиторский сайдкар взаимодействий агентов (bd, audit.enabled) — локальная
+# телеметрия прогона, не состояние трекера: оно живёт в Dolt и уезжает через
+# refs/dolt/data (sync.remote в .beads/config.yaml), а не через этот файл.
+.beads/interactions.jsonl
 *.gate.lock*
 packaging/*/dist/

{ktalk_cli-2.0.0 → ktalk_cli-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ktalk-cli
-Version: 2.0.0
+Version: 3.0.0
 Summary: CLI for accessing Kontur Talk (KTalk) recordings, transcripts and summaries
 Project-URL: Homepage, https://github.com/mdemyanov/ktalk-cli
 Project-URL: Repository, https://github.com/mdemyanov/ktalk-cli
@@ -26,15 +26,18 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/ktalk-cli)](https://pypi.org/project/ktalk-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/ktalk-cli)](https://pypi.org/project/ktalk-cli/)
 
-CLI `ktalk` для доступа к записям [Контур.Толк](https://ktalk.ru) (KTalk) — чтение
-записей, транскриптов и саммари, работа с расписанием, операционный реестр
-обработки записей на SQLite.
+CLI `ktalk` — интерфейс командной строки для тех, кто работает с записями видеовстреч
+[Контур.Толк](https://ktalk.ru) (KTalk) программно: читает записи, транскрипты и саммари,
+управляет расписанием, ведёт локальный реестр обработки записей на SQLite. Годится и как
+самостоятельный инструмент, и как предусловие плагина Claude Code `ktalk` — подробнее в
+разделе «Пакет и плагин Claude Code» ниже.
 
 > Раньше пакет назывался `ktalk-mcp` и, помимо CLI, поднимал MCP-сервер для
 > Claude Code (инструменты вида `ktalk_list_recordings`). Этот слой снят
 > целиком — MCP в пакете больше нет, единственная точка входа — команда
-> `ktalk`. Нужна интеграция с Claude Code — отдельный плагин `ktalk` вызывает
-> эту же CLI напрямую, без MCP-сервера.
+> `ktalk`. Пришли по старой ссылке или ищете `ktalk-mcp` — это тот же проект
+> под новым именем, старый пакет дальше не развивается (о конфликте имени
+> команды при апгрейде — ниже, в «Установке»).
 
 Умеет:
 - Список записей конференций и детали одной записи.
@@ -42,11 +45,11 @@ CLI `ktalk` для доступа к записям [Контур.Толк](http
 - Саммари и протоколы встреч.
 - Полный состав участников записи (обходит лимит в 6 из списковых ответов).
 - Скачивание видеофайла записи.
-- Архив встреч и историю чата (только с персональным API-ключом).
-- Конфигурацию комнаты и календарь запланированных встреч (только с session token).
+- Историю чата встречи.
+- Конфигурацию комнаты и календарь запланированных встреч.
 - Предпросмотр и создание новой встречи — создание требует интерактивного
   терминала и явного подтверждения, см. «Планирование встречи» ниже.
-- Диагностику авторизации — какой ключ/токен активен и почему запрос не проходит.
+- Диагностику авторизации — жив ли токен и почему запрос не проходит.
 - Операционный реестр обработки записей на SQLite — синхронизация, статусы,
   markdown-зеркало для git, см. «Реестр записей» ниже.
 
@@ -73,22 +76,41 @@ uv tool uninstall ktalk-mcp
 uv tool install ktalk-cli
 ```
 
+**Проверка версии** — после установки или обновления:
+
+```bash
+ktalk --version    # печатает, например: ktalk-cli 2.1.0
+```
+
+**Обновление** до последней версии — та же команда `install`, только `upgrade`:
+
+```bash
+uv tool upgrade ktalk-cli
+```
+
 ## Авторизация
 
-CLI поддерживает два способа авторизации: session token (кука браузера) и
-персональный API-ключ. Способы исключают друг друга: если задать обе переменные,
-побеждает `KTALK_PERSONAL_API_KEY` — `KTALK_SESSION_TOKEN` в этом случае вообще не
-читается. Не задать ни один — команда завершится понятной ошибкой.
+**С версии 3.0.0 CLI работает только через session token** (кука браузера) — режим
+персонального API-ключа (`KTALK_PERSONAL_API_KEY`) снят целиком (ADR-025): он
+конкурировал с сессией молча (при обеих заданных переменных побеждал ключ без
+объяснения в тексте отказа) и диагностика `auth-status` объявляла заведомо
+невалидный ключ «валидным» на 403.
+
+**Цена снятия для тех, кто держал постоянный ключ:** персональный ключ не протухал
+без предупреждения, session token — протухает. Постоянная работа теперь требует
+ручного обновления токена по мере его протухания (`ktalk token set -`, см. ниже) —
+это не восстанавливается автоматически снятием ключа.
 
-Персональный API-ключ не привязан к браузерной сессии и не протухает без предупреждения,
-в отличие от session token. Берите его, если нужна стабильная работа без ручного
-обновления, а не только разовый запрос.
+Переменная `KTALK_PERSONAL_API_KEY`, если она всё ещё задана в окружении, не
+читается как credential ни на одном шаге — CLI печатает об этом одно предупреждение
+на stderr при каждом вызове и продолжает работу на сессионном токене.
 
 ### Session token
 
-Session token — токен вашей браузерной сессии Толка. Быстрый способ начать, но
-токен живёт недолго и протухает без предупреждения — при регулярном
-использовании удобнее персональный API-ключ (ниже).
+Session token — токен вашей браузерной сессии Толка. Единственный поддерживаемый
+источник credential (ADR-025). Живёт недолго и протухает без предупреждения — при
+регулярной работе повторяйте те же два шага ниже, когда команда начнёт отказывать
+кодом авторизации.
 
 **Два шага.** На вкладке, где вы залогинены в `https://your-domain.ktalk.ru`, откройте
 DevTools (`F12`, или `Cmd+Option+I` на Mac) → **Console** и выполните:
@@ -118,9 +140,11 @@ ktalk auth-status     # жива ли авторизация — реальны
 
 | # | Источник | Комментарий |
 |---|---|---|
-| 1 | `KTALK_PERSONAL_API_KEY` | режим персонального ключа, сессия дальше не читается |
-| 2 | `KTALK_SESSION_TOKEN` (окружение или `.env` в рабочей директории) | заданное явно сильнее лежащего на диске |
-| 3 | `~/.config/ktalk-mcp/token` | дефолтный путь для повседневной работы |
+| 1 | `KTALK_SESSION_TOKEN` (окружение или `.env` в рабочей директории) | заданное явно сильнее лежащего на диске |
+| 2 | `~/.config/ktalk-mcp/token` | дефолтный путь для повседневной работы |
+
+Ни один запрос не несёт заголовок `X-Auth-Token` — единственный транспорт credential
+теперь query-параметр `sessionToken`.
 
 > Путь `~/.config/ktalk-mcp/token` не переименован вместе с пакетом и остаётся
 > таким намеренно: он выбран независимо от имени дистрибутива (каталог
@@ -141,57 +165,20 @@ ktalk auth-status     # жива ли авторизация — реальны
 > ошибку авторизации, повторите те же два шага — `ktalk token set -` перезаписывает
 > файл, права переставлять не нужно.
 
-### Персональный API-ключ
-
-Персональный API-ключ выдаётся в админке Толка на конкретного пользователя на
-настраиваемый срок и не зависит от того, открыт ли браузер. Передаётся заголовком
-`X-Auth-Token`, а не в URL — секрет не попадает в query-параметры и логи веб-сервера.
-
-Выпускается и ротируется в разделе **Управление → API-ключи** админки Толка (UI-шаг,
-CLI-эквивалента нет; экранные шаги здесь не расписываем — актуальный порядок действий
-смотрите в справке Контура:
-[«Персональный API-ключ доступа в Толке»](https://support.kontur.ru/talk/86797)).
-Значение ключа показывается один раз в течение часа после создания — не скопировали
-вовремя, придётся выпускать новый.
-
-**Не путайте с ключом пространства.** В Толке есть второй, отдельный ключ —
-пространственный, с заголовком `X-API-Key`, выдаётся не на пользователя, а на всё
-пространство целиком. `ktalk-cli` работает только с персональным ключом
-(`X-Auth-Token`); ключ пространства не поддерживается — переменная называется
-`KTALK_PERSONAL_API_KEY`, а не `KTALK_API_KEY`, намеренно, чтобы их не перепутать.
-
-При выпуске ключа в админке выбираются права (scope). Не хватает прав — запрос вернёт
-403, и по виду это неотличимо от «ключ невалиден», хотя ключ рабочий (подробнее —
-«Диагностика авторизации» ниже).
-
-| Право (scope) | Даёт доступ к |
-|---|---|
-| `application.recording.read` | Список записей, детали, транскрипт, саммари, скачивание файла, участники |
-| `application.reporting.read` | Архив встреч, чат встречи, отчёты по участникам |
-| `application.applications.read` | Опционально. Без него `ktalk auth-status` не покажет состав прав и срок действия ключа — только «ключ живой / не живой» |
-
-> **Если реестр `ktalk` уже накопил записи в session-режиме,** перед первым `ktalk sync`
-> после переключения на персональный ключ обязательно выполните `ktalk sync --dry-run`.
-> Внутренний и официальный контуры API отдают идентификаторы записей по-разному, и без
-> сверки первый боевой sync под ключом рискует задвоить весь реестр. Команда только
-> сверяет id и ничего не пишет — см. таблицу команд реестра ниже.
-
 ### Переменные окружения
 
 ```bash
-export KTALK_PERSONAL_API_KEY="ваш_персональный_api_ключ"
-# или
 export KTALK_SESSION_TOKEN="ваш_session_token"
 export KTALK_BASE_URL="https://your-domain.ktalk.ru"
 ```
 
-Для session-режима переменная не обязательна: без неё читается файл
-`~/.config/ktalk-mcp/token` (см. «Session token»).
+Переменная не обязательна: без неё читается файл `~/.config/ktalk-mcp/token`
+(см. «Session token»).
 
 Также поддерживается файл `.env` в рабочей директории:
 
 ```env
-KTALK_PERSONAL_API_KEY=ваш_персональный_api_ключ
+KTALK_SESSION_TOKEN=ваш_session_token
 KTALK_BASE_URL=https://your-domain.ktalk.ru
 ```
 
@@ -206,35 +193,45 @@ ktalk auth-status
 Диагностика различает два случая, которые снаружи выглядят одинаково — просто ошибка, —
 но чинятся по-разному:
 
-- **401** — ключ или токен невалиден либо истёк. Перевыпустите его.
-- **403** — ключ рабочий, но конкретному запросу не хватает прав (scope). Отредактируйте
-  права ключа в админке Толка (см. таблицу в разделе «Персональный API-ключ» выше) —
-  перевыпускать ключ не нужно.
+- **401** — токен невалиден либо истёк. Обновите его: `ktalk token set -` (или
+  переменную `KTALK_SESSION_TOKEN`, если она задана).
+- **403** — токен рабочий, но у текущей сессии нет прав на эту операцию.
+  Перевыпускать токен не нужно.
 
-У session token понятия scope нет — диагностика в этом режиме пробным запросом списка
-записей сообщает только «токен работает / не работает», без прав и срока действия.
+У session token понятия scope и срока действия нет — диагностика выполняет реальный
+пробный запрос (список записей), а не имитацию без сети.
 
-Режим ключа не проверен полностью на боевом окружении — команда описывает задуманное
-поведение, а не гарантию для любого ключа.
+`--json`-ответ — `{"alive": bool, "note": str | None}`. Отказ пробного запроса виден
+по обоим каналам сразу: поле `alive: false` в теле ответа И ненулевой код возврата
+процесса — полагаться только на один из двух нельзя.
 
 ## Команды чтения записей и справочников
 
 Все команды поддерживают `--json` (валидный JSON в stdout; ошибки — в stderr с
 ненулевым кодом возврата).
 
+### Коды возврата
+
+| Код | Значение |
+|---|---|
+| `0` | Успех. |
+| `1` | Отказ вызова — сеть, сервер, конфигурация. |
+| `2` | Usage error — неверные аргументы CLI (`argparse`). |
+| `3` | Только `ktalk get-transcript`. Данные получены и напечатаны полностью, но независимая сверка идентичности не сошлась (`identity_check.result == "mismatch"`) — состав участников транскрипта разошёлся с составом записи. Это не сбой команды: код 3 отличает «данные есть, но сверка не сошлась» от `0` (сошлось или не проверялось) и от `1`/`2` (данных нет вовсе). Подробности — в самом теле ответа, поле `identity_check` (ADR-024 §Д1). |
+
 | Команда | Назначение |
 |---|---|
 | `ktalk list-recordings [--query Q] [--start-from ISO] [--start-to ISO] [--top N] [--order O] [--page-token T]` | Список записей. `--top` 1–1000 (по умолчанию 30); `--order`: `byTimeNewFirst` (умолчание), `byTimeOldFirst`, `byTitle`, `bySizeBigFirst`, `bySizeSmallFirst`. |
 | `ktalk get-recording <recording_key>` | Детали записи — автор, дата, длительность, участники (список ограничен 6, полный состав — `get-participants`). |
-| `ktalk get-transcript <recording_key> [--chunk N] [--chunk-size N]` | Транскрипт по спикерам с таймкодами. Длинный транскрипт режется на чанки по границам реплик: `--chunk 0` (умолчание) — целиком или первый чанк; `--chunk-size` — макс. символов в чанке (умолчание 30000, ~7500 токенов). |
+| `ktalk get-transcript <recording_key> [--chunk N] [--chunk-size N]` | Транскрипт по спикерам с таймкодами. Длинный транскрипт режется на чанки по границам реплик: `--chunk 0` (умолчание) — целиком или первый чанк; `--chunk-size` — макс. символов в чанке (умолчание 30000, ~7500 токенов). Независимая сверка идентичности включена по умолчанию (`--no-verify-identity` отключает); `--chunk` вне диапазона сверку по сети не запускает вовсе, `identity_check.result == "not_checked"`/`reason: "chunk_out_of_range"`. |
 | `ktalk get-summary <recording_key>` | Полное саммари (краткое резюме + протокол). |
 | `ktalk get-summary-type <recording_key> --type shortSummary\|protocol` | Саммари одного типа. |
 | `ktalk get-participants <recording_key>` | Полный состав участников, включая анонимных — обходит лимит в 6, который отдают `get-recording`/`list-recordings`. |
 | `ktalk download-recording <recording_key> --target PATH [--quality Q]` | Скачивает видеофайл потоково, без буферизации в памяти. Существующий файл не перезаписывается; `--quality` не указано — берётся дефолт для записи (например `900p`). |
-| `ktalk list-archive --from ISO --to ISO [--room-name N]` | Архив встреч за период. Только режим персонального ключа (право `application.reporting.read`). Читает всё окно на клиенте, без постраничного чтения. |
-| `ktalk get-chat-messages [--recording-key K \| --conference-key K] [--channel C]` | Сообщения чата встречи; один из двух ключей обязателен. Только режим персонального ключа. Канал не указан — определяется автоматически. |
-| `ktalk get-room <room_name>` | Конфигурация комнаты — политики аудио/видео/демонстрации, модераторы, SIP, чат, маскирование. Только режим session token. **Побочный эффект:** если комнаты с таким именем ещё нет, она создаётся. |
-| `ktalk list-calendar --start ISO --end ISO [--room-name N]` | Встречи за окно дат, видимые активной авторизации — это не «ваш личный календарь», а всё, что видит текущая авторизация, включая чужие встречи. Только режим session token. Сервер лимитирует один запрос семью днями и сотней встреч на сегмент — команда сама режет произвольное окно на сегменты; при упоре в потолок ответ предупреждает о возможно неполной выдаче. |
+| `ktalk list-archive --from ISO --to ISO [--room-name N]` | Архив встреч за период. **Недоступна** — архив никогда не имел рабочего пути под session token; команда отказывает до сети с явным сообщением на каждый вызов (ADR-025). |
+| `ktalk get-chat-messages [--recording-key K \| --conference-key K] [--channel C]` | Сообщения чата встречи; один из двух ключей обязателен. Канал не указан — определяется автоматически. |
+| `ktalk get-room <room_name>` | Конфигурация комнаты — политики аудио/видео/демонстрации, модераторы, SIP, чат, маскирование. **Побочный эффект:** если комнаты с таким именем ещё нет, она создаётся. |
+| `ktalk list-calendar --start ISO --end ISO [--room-name N]` | Встречи за окно дат, видимые активной авторизации — это не «ваш личный календарь», а всё, что видит текущая авторизация, включая чужие встречи. Сервер лимитирует один запрос семью днями и сотней встреч на сегмент — команда сама режет произвольное окно на сегменты; при упоре в потолок ответ предупреждает о возможно неполной выдаче. |
 
 ## Планирование встречи
 
@@ -247,8 +244,8 @@ ktalk auth-status
   перед отправкой печатает предпросмотр и требует набрать слово `да`.
 - Предпросмотр без создания — `ktalk create-meeting-preview`, не делает ни
   одного сетевого запроса.
-- Обе команды работают только в режиме session token — в режиме персонального
-  ключа создание встречи не подтверждено ни разу и потому отключено.
+- Обе команды используют session token — единственный оставшийся режим
+  авторизации (ADR-025).
 
 **Ни одно поле не имеет значения по умолчанию** (кроме описания встречи — пустая
 строка, если не задано). Тема, начало, конец, часовой пояс, комната, участники,
@@ -302,33 +299,22 @@ ktalk create-meeting-confirm \
 
 ## API
 
-CLI работает с KTalk Web API. Набор путей, которые вызывает клиент, зависит от
-активного режима авторизации (см. «Авторизация» выше):
-
-- **Session-режим** — авторизация query-параметром `sessionToken`, используется
-  внутренний контур API.
-- **Режим персонального ключа** — авторизация заголовком `X-Auth-Token`, используются
-  официальные пути интеграторского API (`talk.public.api-api-2.json`).
-
-Транскрипт и саммари используют один и тот же путь в обоих режимах:
+CLI работает с KTalk Web API через единственный (session token) режим авторизации
+(см. «Авторизация» выше) — query-параметр `sessionToken`, внутренний недокументированный
+контур API:
 
 | Эндпоинт | Описание |
 |----------|----------|
+| `GET /api/recordings` | Список записей |
+| `GET /api/recordings/{id}` | Детали записи |
 | `GET /api/recordings/{id}/transcript` | Транскрипт |
 | `GET /api/recordings/v2/{id}/summary` | Полное саммари (v2) |
 | `GET /api/recordings/{id}/summary/{type}` | Саммари по типу |
 
-Список записей и детали записи используют разные пути в session- и api-key-режимах.
-Архив встреч, чат, полный состав участников, скачивание файла и диагностика ключа
-доступны только в режиме персонального ключа (нужные права — в таблице раздела
-«Персональный API-ключ» выше).
+Архив встреч (`list-archive`) недоступен: под session token у него нет и никогда не
+было рабочего пути (ADR-025) — команда отказывает до сети с явным сообщением.
 
-Комната, календарь и создание встречи работают только в режиме session token — в
-режиме персонального ключа эти операции отказывают осознанно, а не по случайному
-пробелу: путь на api-key либо не подтверждён вовсе, либо ведёт себя необъяснимо
-непоследовательно при проверке.
-
-> OpenAPI спецификация `talk.public.api-api-2.json` включена как справочник, но содержит расхождения с реальным API (пути, формат авторизации, структура ответов).
+> OpenAPI спецификация `talk.public.api-api-2.json` включена как справочник, но содержит расхождения с реальным API (пути, формат авторизации, структура ответов). Пути, достижимые только под снятым режимом персонального ключа (`X-Auth-Token`), больше не применимы к этому CLI.
 
 ## Реестр записей (`ktalk`)
 
@@ -351,10 +337,10 @@ CLI работает с KTalk Web API. Набор путей, которые в
 
 | Команда | Назначение |
 |---|---|
-| `ktalk sync [--days 7] [--json] [--dry-run]` | Загрузить записи из KTalk, upsert новых (`new`), экспирировать `new` старше N дней → `skipped`, показать дашборд. Идемпотентно. `--dry-run` — сверить id с реестром без записи, ничего не пишет (обязателен перед первым `sync` в режиме персонального ключа — см. «Персональный API-ключ»). |
+| `ktalk sync [--days 7] [--json] [--dry-run]` | Загрузить записи из KTalk, upsert новых (`new`), экспирировать `new` старше N дней → `skipped`, показать дашборд. Идемпотентно. `--dry-run` — сверить id с реестром без записи, ничего не пишет. |
 | `ktalk token set <значение\|->` | Записать session-токен в `~/.config/ktalk-mcp/token` (`0600`). `-` — прочитать из stdin: `pbpaste \| ktalk token set -`. Значение не печатается. |
 | `ktalk token status [--json]` | Есть ли файл токена, его права и маска значения. |
-| `ktalk auth-status [--json]` | Диагностика активной авторизации — жив ли ключ/токен, какие права у ключа. См. «Диагностика авторизации». |
+| `ktalk auth-status [--json]` | Диагностика активной авторизации — жив ли токен. См. «Диагностика авторизации». |
 | `ktalk dashboard [--json]` | Дашборд: новые записи, статистика по статусам. |
 | `ktalk list [--status S] [--json]` | Список записей с фильтром по статусу. |
 | `ktalk show <id> [--json]` | Детали записи: участники, статус, пути, длительность. |
@@ -382,10 +368,34 @@ uv run pytest -v
 # Линтинг
 uv run ruff check .
 
-# Локальный запуск CLI (session token или KTALK_PERSONAL_API_KEY — см. «Авторизация»)
+# Локальный запуск CLI (session token — см. «Авторизация»)
 KTALK_SESSION_TOKEN=... KTALK_BASE_URL=... uv run ktalk auth-status
 ```
 
+## Пакет и плагин Claude Code
+
+`ktalk-cli` работает и сам по себе, и как предусловие плагина Claude Code `ktalk`. Плагин не
+обращается к KTalk напрямую и не поднимает MCP-сервер — он вызывает эту же команду `ktalk`
+как единственную точку входа в контур.
+
+Плагин пинует точную версию пакета (не нижний порог: «ровно эта версия», не «эта или новее») в
+собственном файле совместимости. Если что-то в интеграции с плагином ведёт себя не так, как
+описано в его документации, — первым делом сверьте версию:
+
+```bash
+ktalk --version    # см. «Проверка версии» в разделе «Установка»
+```
+
+Версия не совпадает с той, что требует плагин, — обновите пакет тем же способом, что при
+установке (`uv tool upgrade ktalk-cli`, см. «Установка»); не совпадает в другую сторону
+(пакет новее, чем ожидает плагин) — не откатывайте его самостоятельно, сверьтесь с тем, кто
+настраивал плагин.
+
+## Проблемы и вопросы
+
+Нашли баг, некорректное поведение или неточность в документации — заведите issue в этом
+репозитории: https://github.com/mdemyanov/ktalk-cli/issues.
+
 ## Лицензия
 
 MIT