npm - @goodandready/dsh-cron - Versions diffs - 0.1.23 → 0.2.0 - Mend

@goodandready/dsh-cron 0.1.23 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/docs/README.ru.md CHANGED Viewed

@@ -2,11 +2,11 @@
 <div align="center">
-<h3>Планировщик фоновых задач, cron-автоматизация и выполнение сценариев агентом для DeepSeek Harness</h3>
+<h3>Планировщик cron-задач, фоновая автоматизация и выполнение сценариев агентом для DeepSeek Harness</h3>
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-cron"><img src="https://img.shields.io/npm/v/@goodandready/dsh-cron.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-cron.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="../LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-cron.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
   <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
 </p>
@@ -25,158 +25,206 @@
 ---
-## ⚡ Назначение и решаемая проблема
+## ⚡ Обзор и проблема
-При повседневной работе автономные ИИ-агенты часто должны выполнять повторяющиеся рутинные обязанности: собирать утренние сводки изменений, мониторить статус открытых пулл-реквестов, проверять работоспособность внешних API, проводить регулярную очистку кэша или запускать сценарии тестирования. Без встроенного планировщика пользователю приходится настраивать внешние утилиты crontab, сложные вебхуки или вручную запускать нужные команды каждый день.
+Автономным AI-агентам регулярно нужны повторяющиеся действия: утренние сводки, разбор трекеров задач, проверка доступности API, синхронизация баз данных, периодическая гигиена Git. Без штатного планировщика внутри харнесса приходится использовать внешние обёртки над crontab, сложные webhook-схемы или ручной запуск.
-**`@goodandready/dsh-cron`** — полнофункциональный плагин планировщика и фоновой автоматизации для DeepSeek Harness. Он объединяет стандартные cron-выражения и удобные человекопонятные интервалы с автономным запуском агентских сессий:
+**`@goodandready/dsh-cron`** — нативный полноформатный плагин планирования и фоновой автоматизации для DeepSeek Harness. Он связывает стандартные cron-выражения и естественные интервалы с автономным исполнением агентами:
-1. **Визуальный интерфейс «Запланированные задачи»**: удобная кнопка с часами в боковом меню DSH (рядом с канбан-доской и чатом) и полноэкранный интерфейс со вкладками фильтрации, историей запусков и ручным управлением.
-2. **Интерактивный диалог «Создать с DSH»**: постановка задач агенту на естественном языке с автоматическим формированием cron-расписания и выбором рабочей языковой модели.
-3. **Команда `/cron` прямо в чате**: быстрое управление задачами с клавиатуры (`/cron list`, `/cron add`, `/cron pause`, `/cron run`).
-4. **Инструменты модели (AI Tool Calling)**: агент может самостоятельно планировать свои будущие действия в ходе выполнения задачи через встроенные инструменты (`cron_schedule_task`, `cron_list_tasks`, `cron_toggle_task`).
-5. **Надёжный движок и атомарное хранение**: построен на библиотеке `croner`, поддерживает таймзоны, интервалы (`every 15m`, `daily`, `weekdays`), атомарную запись JSON-хранилища и историю выполнения.
+1. **Развитый визуальный менеджер задач** — кнопка в сайдбаре и полноценная панель: просмотр, фильтры, пауза, немедленный запуск, создание задач.
+2. **Интерактивный сценарий «Создать с DSH»** — опишите задачу словами, агент уточнит детали и оформит расписание.
+3. **Автономный tool calling** — нативные инструменты `cron_*` позволяют агентам планировать собственные последующие действия прямо в диалоге.
+4. **Надёжный планировщик и атомарное хранилище** — на базе `croner`: интервалы, разовые задачи с задержкой, атомарная запись, история запусков, учёт стоимости.
 ---
-## 🏗️ Архитектура работы
+## 🏗️ Архитектура
 ```mermaid
 graph TD
-    subgraph Client ["Клиентская часть (DSH Web UI)"]
-        SidebarBtn["Кнопка с часами в меню<br/>(Слот интерфейса DSH)"]
-        Overlay["Оверлей 'Запланированные задачи'<br/>(Табы: Все, Активные, Пауза, Завершено)"]
-        CreateWithDSH["Модальное окно 'Создать с DSH'<br/>(Выбор модели и промпт)"]
-        ManualForm["Форма ручной настройки<br/>(Cron-выражение, таймзона, модель)"]
-        SlashCmd["Парсер команды /cron<br/>(/cron add, list, pause, run)"]
+    subgraph Client ["Клиентская поверхность (DSH UI)"]
+        SidebarBtn["Кнопка-часы в сайдбаре<br/>(слот DSH Client UI)"]
+        Overlay["Панель управления задачами<br/>(табы: Все, Активные, На паузе, Завершённые)"]
+        CreateWithDSH["Диалог «Создать с DSH»<br/>(задача на естественном языке)"]
+        ManualForm["Ручная форма задачи<br/>(cron, таймаут, overlap, модель)"]
+        SettingsCard["Карточка настроек<br/>(интеграции Telegram / Kanban)"]
     end
-    subgraph Server ["Серверная часть (Cordis и службы DSH)"]
-        HttpRoutes["HTTP REST API маршруты<br/>(/dsh-cron/tasks, /models, /chat-start)"]
-        AgentTools["Шлюз инструментов агента<br/>(cron_schedule_task, cron_list_tasks)"]
-        Scheduler["Движок TaskScheduler<br/>(Управление инстансами Croner)"]
-        Store["Атомарный TaskStore<br/>(tasks.json с безопасной перезаписью)"]
-        AgentRunner["Диспетчер сессий агента<br/>(Исполнение промпта в изолированном контексте)"]
+    subgraph Server ["Серверная часть (Cordis и сервисы DSH)"]
+        HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
+        AgentTools["Шлюз tool calling<br/>(cron_create_task, cron_list_tasks, ...)"]
+        Scheduler["Движок TaskScheduler<br/>(экземпляры Croner + таймеры one-shot)"]
+        Store["Атомарный TaskStore<br/>(tasks.json, атомарная запись)"]
+        AgentRunner["Диспетчер агентских сессий<br/>(запуск промпта выбранной моделью)"]
+        Notify["Доставка<br/>(Telegram Bot API, карточки dsh-kanban)"]
     end
     SidebarBtn --> Overlay
     Overlay --> CreateWithDSH
     Overlay --> ManualForm
-    CreateWithDSH -->|POST /chat-start| HttpRoutes
+    SettingsCard --> HttpRoutes
+    CreateWithDSH -->|POST /chat/start| HttpRoutes
     ManualForm -->|POST /tasks| HttpRoutes
-    SlashCmd -->|Диспетчеризация команд| HttpRoutes
     HttpRoutes --> Scheduler
     AgentTools --> Scheduler
     Scheduler --> Store
-    Scheduler -->|Запуск по расписанию| AgentRunner
+    Scheduler -->|Запуск по интервалу/one-shot| AgentRunner
+    Scheduler --> Notify
 ```
 ---
-## ✨ Подробный разбор возможностей
+## ✨ Возможности
-### 1. Графический оверлей и кнопка в боковом меню
-По клику на значок часов в боковой панели DSH открывается удобный центр управления:
-* **Табы статусов**: быстрое переключение между категориями **Все**, **Активные**, **Приостановленные** и **Завершено**.
-* **Меню быстрых действий**: мгновенный запуск вне очереди (*«Запустить сейчас»*), постановка на паузу/возобновление и безопасное удаление задач.
-* **Готовые шаблоны в 1 клик**: предустановленные карточки популярных сценариев (*«Ежедневная сводка изменений»*, *«Еженедельный обзор репозитория»*, *«Мониторинг доступности»*).
-* **Журнал истории**: в карточке каждой задачи сохраняются отметки времени запуска, длительность работы в секундах, статус завершения и логи агента.
+### 1. Визуальный менеджер задач
+Нажмите на иконку-часы в сайдбаре DSH (рядом с кнопкой новой сессии), чтобы открыть панель:
+* **Табы фильтрации**: **Все**, **Активные**, **На паузе**, **Завершённые**.
+* **Мгновенные действия**: немедленный запуск (**Запустить**), пауза/возобновление расписания, удаление с подтверждением.
+* **Готовые шаблоны в один клик**: *Ежедневная сводка*, *Еженедельный обзор*, *Мониторинг дальнейших действий*.
+* **История запусков**: в карточке задачи — время, длительность и статусы предыдущих запусков (успех / сбой / таймаут / пропуск / пропущен по простою), вывод и ошибки.
+* **Сводная статистика**: активные задачи, всего запусков, израсходованные токены и оценочная стоимость в долларах.
-### 2. Режим создания «Создать с DSH»
-Позволяет формулировать периодические задачи на обычном разговорном языке:
+### 2. Диалог «Создать с DSH»
+Превратите естественный язык в задачу без подбора cron-синтаксиса:
 1. Нажмите **Создать ⌄** ➔ **Создать с DSH**.
-2. Выберите нужного провайдера и модель из выпадающего списка.
-3. Опишите задачу (например: *«Каждое утро в 9:00 проверять открытые тикеты в Gitea и формировать краткий дайджест»*).
-4. Плагин автоматически создаст отдельную диалоговую сессию с агентом, передаст системные инструкции планировщика и зарегистрирует задачу в `TaskStore`.
+2. Опишите, что нужно автоматизировать (например: *«Проверяй открытые PR по будням в 9:00 и готовь черновики комментариев»*).
+3. Плагин создаст отдельную агентскую сессию с системными инструкциями планировщика. Агент уточнит детали — LLM или NO-LLM shell-задача, точное cron-выражение, экономичная модель из доступных в вашей установке DSH, нужно ли «правило тишины» (алерт только при новых событиях или сбоях) — и создаст задачу через инструмент `cron_create_task` только после вашего подтверждения.
-### 3. Команда `/cron` в строке ввода чата
-Для тех, кто предпочитает работу с клавиатуры:
+### 3. Инструменты агентов (tool calling)
-| Команда | Синтаксис | Описание |
-|:---|:---|:---|
-| `/cron list` | `/cron list` | Выводит список всех зарегистрированных задач со статусами и ID |
-| `/cron add` | `/cron add "<расписание>" <промпт>` | Создаёт новую задачу. Пример: `/cron add "every 2h" Собрать статистику коммитов` |
-| `/cron pause` | `/cron pause <id>` | Приостанавливает выполнение задачи без её удаления |
-| `/cron resume` | `/cron resume <id>` | Возобновляет работу приостановленной задачи |
-| `/cron run` | `/cron run <id>` | Немедленно запускает задачу вне очереди |
-| `/cron delete` | `/cron delete <id>` | Полностью удаляет задачу из расписания |
+| Инструмент | Описание |
+|:---|:---|
+| `cron_create_task` | Создаёт задачу: `title`, `schedule`, `prompt`, опционально `type` (`llm`/`script`), `delivery`, `provider`, `model`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
+| `cron_schedule_task` | Псевдоним `cron_create_task` для совместимости с существующими промптами |
+| `cron_list_tasks` | Список задач со статусами, временем следующего запуска, токенами и стоимостью |
+| `cron_pause_task` | Приостанавливает расписание без удаления конфигурации |
+| `cron_resume_task` | Возобновляет приостановленное расписание |
+| `cron_delete_task` | Полностью удаляет задачу и её историю |
+| `cron_run_task` | Немедленный внеплановый запуск |
-### 4. Инструменты модели (Tool Calling)
-Агент может вызывать инструменты планировщика в процессе общения:
+Пример вызова модели в диалоге:
-* **`cron_schedule_task`**: создание задачи с параметрами `name`, `schedule`, `prompt` и опциональным выбором `model`.
-* **`cron_list_tasks`**: просмотр списка запланированных задач и времени их следующего срабатывания.
-* **`cron_toggle_task`**: включение или выключение задачи по её идентификатору `id`.
+```
+cron_create_task({
+  "title": "Утренняя сводка",
+  "schedule": "0 8 * * 1-5",
+  "prompt": "Подготовь короткую утреннюю сводку активных задач и открытых тикетов.",
+  "type": "llm",
+  "delivery": "isolated"
+})
+```
-### 5. Поддерживаемый синтаксис расписаний
-Благодаря библиотеке `croner` поддерживаются как классические cron-выражения, так и дружественные интервалы:
+### 4. Синтаксис расписаний
+На базе `croner`: стандартные 5-полевые cron-выражения и дружелюбные алиасы:
-* `0 9 * * 1-5` — по будням в 09:00 утра
+* `0 9 * * 1-5` — по будням в 09:00
 * `*/15 * * * *` — каждые 15 минут
 * `0 0 * * 0` — каждое воскресенье в полночь
-* `every 10m` / `every 2h` / `every 30s` — интервалы на понятном языке
-* `daily` / `hourly` / `weekly` — быстрые алиасы
+* `every 10m` / `every 2h` / `every 30s` — естественные интервалы
+* алиасы `daily` / `hourly` / `weekdays` (`weekdays` → `0 9 * * 1-5`)
+* **Разовые задачи**: `at: 2026-09-05T15:00:00Z` (точный ISO-таймстемп) или относительные задержки `in 20m` / `in 2h` (принимаются и русские варианты вроде `через 15 минут`). После единственного запуска задача автоматически переходит в `completed` и отображается на табе **Завершённые**.
+### 5. Уведомления Telegram
+Прямая интеграция с Telegram Bot API доставляет отчёты о запусках и трейсы ошибок в мессенджер:
+* **Автоматические или собственные креденшелы** — введите свои `botToken` и `chatId` в диалоге настроек или позвольте плагину унаследовать значения по умолчанию из секции `dsh-messenger-gateway` вашего DSH `settings.yaml` (best-effort).
+* **Режим «только при сбоях»** — включите `onlyOnFailure` глобально или для отдельной задачи. Успешные запуски молчат; сбои (статусы `error` и `timeout`) отправляют алерт с трейсом.
+* **Markdown-оформление** — статусные значки (✅ / ❌), длительность, описание расписания и monospace-блоки вывода; динамические значения экранируются, поэтому нестандартные символы в названии не сломают сообщение.
+* **Кнопка проверки** — проверьте доставку в Telegram до запуска критичных задач.
+### 6. Интеграция с Kanban и учёт стоимости
+* **Автоматические карточки Kanban** — при `kanbanMode` = `on_failure` или `always` плагин создаёт карточки в `dsh-kanban` (`on_failure` → *Backlog* при `error`/`timeout`; `always` → *Done*/*Backlog* по завершении).
+* **Счётчик токенов и стоимости** — потребление токенов (ввод, вывод, чтения из кэша) учитывается по запускам и задачам с оценкой в USD по встроенной таблице цен и сводной панелью аналитики.
+### 7. Политики наложения и таймаут выполнения
+* **Таймаут (`timeoutSeconds`)** — по достижении лимита shell-процесс немедленно завершается через abort-сигнал, а агентская сессия закрывается, чтобы не расходовать токены. По умолчанию `1800` (30 минут).
+* **Политика наложения (`overlapPolicy`)** — что делать, когда тик срабатывает при ещё активном предыдущем запуске:
+  * **`skip`** (по умолчанию): накладывающийся запуск отбрасывается, в истории появляется запись `skipped`;
+  * **`queue`**: следующий запуск ставится в очередь и стартует по завершении активного;
+  * **`replace`**: активный запуск прерывается через `AbortController`, запускается свежий.
+Если сервис был выключен в момент планового запуска, при старте в истории появится запись `missed` — пробелы в истории остаются видимыми.
 ---
 ## 📦 Установка
-Установка через командную строку DeepSeek Harness:
 ```bash
 dsh plugin --profile web add @goodandready/dsh-cron
 ```
-Перезапустите DSH и обновите вкладку в браузере.
+Перезапустите DeepSeek Harness и обновите страницу в браузере.
 ---
 ## ⚙️ Конфигурация (`settings.yaml`)
-Настройка доступна через файл конфигурации или панель настроек DSH:
+Конфигурацию можно задать в `settings.yaml` или интерактивно через карточку настроек плагина в DSH:
 ```yaml
 # settings.yaml
 dsh-cron:
-  storagePath: "data/cron-tasks.json"
-  maxHistoryEntries: 50
-  defaultTimezone: "Europe/Moscow"
-  defaultModel: ""
-  notifyOnFailure: true
+  botToken: ""                 # токен Telegram Bot API (секретное поле)
+  chatId: ""                   # ID чата Telegram для отчётов
+  notifyTelegram: false        # глобально отправлять отчёты о всех задачах
+  onlyOnFailure: false         # отправлять отчёты только при сбоях
+  kanbanBaseUrl: "http://127.0.0.1:3000"  # базовый URL HTTP API dsh-kanban
 ```
-### Таблица параметров конфигурации
+### Параметры
 | Параметр | Тип | По умолчанию | Описание |
 |:---|:---|:---|:---|
-| `storagePath` | `string` | `"data/cron-tasks.json"` | Путь к файлу атомарного сохранения задач и истории |
-| `maxHistoryEntries` | `number` | `50` | Максимальное количество записей журнала запусков на задачу |
-| `defaultTimezone` | `string` | `"UTC"` | Часовой пояс IANA для расчёта cron-выражений |
-| `defaultModel` | `string` | `""` | Модель по умолчанию, если не выбрана вручную |
-| `notifyOnFailure` | `boolean` | `true` | Показывать уведомление в интерфейсе при сбое фоновой задачи |
+| `botToken` | `string` | `""` | Токен Telegram Bot API. Если пусто, плагин пытается унаследовать бота, настроенного для `dsh-messenger-gateway` в настройках DSH (best-effort). Секретное поле: в интерфейсе отображается только замаскированное значение |
+| `chatId` | `string` | `""` | ID чата Telegram для отчётов. Пустое значение — откат к первому разрешённому чату `dsh-messenger-gateway` |
+| `notifyTelegram` | `boolean` | `false` | Глобальный выключатель доставки отчётов в Telegram |
+| `onlyOnFailure` | `boolean` | `false` | Глобальный режим «только при сбоях» (`error`/`timeout`) |
+| `kanbanBaseUrl` | `string` | `"http://127.0.0.1:3000"` | Базовый URL HTTP API `dsh-kanban` для автоматических карточек |
+Примечания:
+* История запусков ограничена **50 записями на задачу** (фиксировано); в записи хранится до 4000 символов вывода.
+* Задачи выполняются в **локальном часовом поясе сервера**; cron-выражения вычисляет `croner` по часам хоста.
+* Задачи сохраняются в каталоге данных DSH (`cron/tasks.json`) и переживают перезапуск; пропущенные one-shot запуски обнаруживаются при старте.
 ---
-## 🧪 Тестирование
+## 🔌 HTTP API
+Все эндпоинты обслуживаются веб-сервером DSH под `/dsh-cron/`. Чтение открыто локальному интерфейсу; **мутирующие эндпоинты отклоняют cross-origin запросы** и принимают тела до 1 МБ. Для создания `script`-задач по HTTP дополнительно требуется заголовок `x-dsh-cron-confirm: script`, который подделанный межсайтовый запрос приложить не может.
-Запуск набора юнит-тестов:
+| Метод | Путь | Описание |
+|:---|:---|:---|
+| `GET` | `/dsh-cron/tasks` | Список задач; параметры `status` (`all/active/paused/completed`), `query` (подстрока). Возвращает задачи, шаблоны рекомендаций и сводную статистику |
+| `POST` | `/dsh-cron/tasks` | Создание или обновление задачи (при наличии `id` — обновление). Обязательны `title`, `schedule`, `prompt` |
+| `GET` | `/dsh-cron/tasks/:id/history` | История запусков, `?limit=20` |
+| `POST` | `/dsh-cron/tasks/:id/run` | Немедленный ручной запуск |
+| `POST` | `/dsh-cron/tasks/:id/pause` | Пауза расписания |
+| `POST` | `/dsh-cron/tasks/:id/resume` | Возобновление расписания |
+| `POST` | `/dsh-cron/tasks/:id/toggle` | Переключение активна/на паузе |
+| `PATCH` | `/dsh-cron/tasks/:id` | Частичное обновление (только whitelisted-поля: `title`, `schedule`, `prompt`, `type`, `delivery`, `provider`, `model`, настройки уведомлений/таймаута/overlap/kanban, `status`, `oneShot`) |
+| `DELETE` | `/dsh-cron/tasks/:id` | Удаление задачи |
+| `GET` | `/dsh-cron/models` | Список LLM-провайдеров; `?provider=<id>` — модели |
+| `POST` | `/dsh-cron/chat/start` | Старт агентской сессии «Создать с DSH» с инструкциями планировщика |
+| `GET` | `/dsh-cron/settings` | Настройки для клиента (токен замаскирован) |
+| `POST` | `/dsh-cron/settings` | Обновление настроек интеграций |
+| `POST` | `/dsh-cron/telegram/test` | Тестовое сообщение в Telegram |
+| `POST` | `/dsh-cron/kanban/test` | Тестовая карточка в Kanban |
+| `*` | `/dsh-cron/action/:id/:action` | Legacy-алиас действий над задачей (`run`, `toggle`, `delete`, `history`) |
+---
+## 🧪 Тестирование
 ```bash
 npm test
 ```
+Набор покрывает разбор расписаний, движок планировщика, атомарное хранилище, HTTP-хелперы, уведомления и контракт инструментов.
 ---
 ## 📄 Лицензия
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
-### Интеграция с Kanban и счетчик стоимости токенов (v0.1.17)
-- **Автосоздание карточек в Kanban**: Автоматическое заведение задач в бэклог `dsh-kanban` при обнаружении сбоев/ошибок (`on_failure`) или при каждом завершении (`always`).
-- **Трекинг токенов и расчет расходов (USD)**: Подсчет потребления токенов (input, output, cacheRead) для каждой задачи и запуск с расчетом примерной стоимости в долларах США.
-- **Сводная панель статистики**: Отображение общего числа запусков, активных задач, суммарного расхода токенов и совокупных затрат прямо в заголовке планировщика.
-### Разовые отложенные задачи (v0.1.18)
-- **Точное время и относительные задержки**: Поддержка однократных задач, запускаемых в конкретный момент времени по стандарту ISO 8601 (`at: 2026-09-05T12:00:00Z`) или через заданный интервал (`in 20m`, `in 2h`, `через 15 минут`).
-- **Автоматический перевод в «Завершенные»**: После единичного выполнения задача автоматически переходит в статус `completed`, исключая повторные старты.
-- **Индикация в интерфейсе**: Разовые задачи помечаются специальным бейджем «Разовая» и фильтруются по вкладке «Завершенные».