@goodandready/dsh-cron 0.1.11 → 0.1.12

package/README.md

@@ -1,45 +1,172 @@
-# @goodandready/dsh-cron
-
-Плагин планировщика и фоновой автоматизации для DeepSeek Harness. Позволяет запускать агентские сессии и автоматические сценарии по расписанию через cron-выражения или интервалы, а также управлять ими через графический оверлей, команду `/cron` и инструмент вызова для модели (Tool Calling).
-
-## Возможности
-
-- **Визуальный интерфейс «Запланированные задачи»**:
-  - Открытие из бокового меню DSH (кнопка рядом с канбаном).
-  - Полноэкранный оверлей со списком активных и приостановленных задач.
-  - Поиск и фильтрация по табам: «Все», «Активные», «Приостановленные», «Завершено».
-  - Выпадающее меню «Создать ⌄»:
-    - 💬 **Создать с DSH** (интерактивная постановка задачи агенту в чате).
-    - ✏️ **Настроить вручную** (модальное окно с выбором параметров расписания, промпта и режима).
-  - Готовые рекомендации в 1 клик («Ежедневная сводка», «Еженедельный обзор», «Мониторинг дальнейших действий»).
-  - Быстрые действия: запуск немедленно («Запустить сейчас»), пауза/возобновление, удаление.
-- **Команда `/cron` в чате**:
-  - `/cron list` — вывод списка активных задач.
-  - `/cron add "<расписание>" <промпт>` — быстрое создание задачи.
-  - `/cron pause <id>` / `/cron resume <id>` — пауза и возобновление.
-  - `/cron run <id>` — немедленный запуск.
-- **Инструменты модели (AI Tool Calling)**:
-  - `cron_schedule_task` — агент может сам запланировать задачу в ходе диалога.
-  - `cron_list_tasks` — просмотр задач.
-  - `cron_toggle_task` — управление жизненным циклом.
-- **Движок планировщика**:
-  - Построен на базе `croner` с поддержкой выражений стандартного cron (`0 9 * * 1-5`) и интервалов (`every 15m`, `daily`, `weekdays`).
-  - Персистентное хранение состояния в JSON с атомарной записью.
-  - Журналирование запусков и сохранение истории выполнения (длительность, статус, вывод).
-
-## Установка
+# 📦 @goodandready/dsh-cron
+
+<div align="center">
+
+<h3>Automated Cron Scheduling, Background Automation & Agent Execution Engine for 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="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>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Overview & The Problem
+
+Autonomous AI agents often need to perform recurring duties: generating daily morning digests, triaging bug trackers, checking API health, syncing databases, or running periodic Git hygiene. Without a dedicated scheduler inside the harness, users must rely on external crontab wrappers, complex webhook setups, or manual intervention.
+
+**`@goodandready/dsh-cron`** is a native full-stack scheduling and background automation plugin for DeepSeek Harness. It bridges standard cron expressions and natural interval syntax with autonomous agent execution, providing:
+
+1. **Rich Visual Task Manager**: A dedicated sidebar navigation button and full-featured visual overlay to inspect, filter, pause, trigger, and create recurring tasks.
+2. **Interactive "Create with DSH" Workflow**: Chat directly with your agent to translate high-level requirements into scheduled tasks, complete with custom model selection and prompt synthesis.
+3. **Chat Slash Commands (`/cron`)**: Fast command-line control directly from the chat prompt (`/cron list`, `/cron add`, `/cron pause`, `/cron run`).
+4. **Autonomous AI Tool Calling**: Gives agents native tools (`cron_schedule_task`, `cron_list_tasks`, `cron_toggle_task`) so they can schedule their own follow-up executions during conversations.
+5. **Robust Scheduler & Atomic Storage**: Built on `croner` with timezone support, interval aliases (`every 15m`, `daily`, `weekdays`), atomic file persistence, and run execution histories.
+
+---
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    subgraph Client ["Web Client Surface (DSH UI)"]
+        SidebarBtn["Sidebar Clock Action<br/>(DSH Client UI Slot)"]
+        Overlay["Visual Task Manager Modal<br/>(Tabs: All, Active, Paused, History)"]
+        CreateWithDSH["'Create with DSH' Modal<br/>(Model Picker & Task Prompt)"]
+        ManualForm["Manual Task Creation Modal<br/>(Cron Expression, Timezone, Model)"]
+        SlashCmd["Slash Command Parser<br/>(/cron add, list, pause, run)"]
+    end
+
+    subgraph Server ["Server Runtime (Cordis & DSH Services)"]
+        HttpRoutes["HTTP REST API Endpoints<br/>(/dsh-cron/tasks, /models, /chat-start)"]
+        AgentTools["AI Tool Calling Gateway<br/>(cron_schedule_task, cron_list_tasks)"]
+        Scheduler["TaskScheduler Engine<br/>(Croner instance management)"]
+        Store["Atomic TaskStore<br/>(tasks.json with atomic write)"]
+        AgentRunner["Agent Session Dispatcher<br/>(Executes prompt with chosen model)"]
+    end
+
+    SidebarBtn --> Overlay
+    Overlay --> CreateWithDSH
+    Overlay --> ManualForm
+    CreateWithDSH -->|POST /chat-start| HttpRoutes
+    ManualForm -->|POST /tasks| HttpRoutes
+    SlashCmd -->|Command dispatch| HttpRoutes
+    HttpRoutes --> Scheduler
+    AgentTools --> Scheduler
+    Scheduler --> Store
+    Scheduler -->|Trigger on interval/cron| AgentRunner
+```
+
+---
+
+## ✨ Features & Capabilities
+
+### 1. Visual Task Manager & Sidebar Action
+Click the clock icon in the DSH sidebar (positioned conveniently next to Kanban and Chat) to open the management overlay:
+* **Status Filter Tabs**: Seamlessly toggle between **All**, **Active**, **Paused**, and **Completed** tasks.
+* **Instant Action Menu**: Trigger manual one-off executions (`Run Now`), pause/resume intervals, or delete obsolete schedules with confirmation safeguards.
+* **1-Click Preset Templates**: Quickly scaffold common workflows like *Daily Development Digest*, *Weekly Repo Review*, and *Health Heartbeat*.
+* **Execution History**: Expand any task card to review previous execution timestamps, elapsed durations, exit statuses, and generated outputs.
+
+### 2. "Create with DSH" AI Chat Modal
+Transform natural language into scheduled jobs without manually guessing cron expressions:
+1. Click **Create ⌄** ➔ **Create with DSH**.
+2. Select your target AI provider and model from the live model dropdown.
+3. Describe what you want the agent to automate (e.g. *"Check open PRs every weekday at 9:00 AM and draft review comments"*).
+4. The plugin automatically spawns a dedicated agent session pre-injected with scheduler system instructions to formulate the task and register it into `TaskStore`.
+
+### 3. Chat Slash Command (`/cron`)
+For keyboard-first workflows, manage tasks directly inside the chat window:
+
+| Command | Syntax | Description |
+|:---|:---|:---|
+| `/cron list` | `/cron list` | Lists all registered tasks with IDs, schedules, and active statuses |
+| `/cron add` | `/cron add "<schedule>" <prompt>` | Creates a task. Example: `/cron add "every 2h" Run git fetch and summarize changes` |
+| `/cron pause` | `/cron pause <id>` | Pauses a running schedule without deleting its configuration |
+| `/cron resume` | `/cron resume <id>` | Resumes a previously paused task schedule |
+| `/cron run` | `/cron run <id>` | Triggers immediate out-of-band execution of the task |
+| `/cron delete` | `/cron delete <id>` | Permanently removes the task from the schedule |
+
+### 4. Agent Tools (Tool Calling)
+When autonomous agents need to set up delayed or recurring actions, they can invoke these tools:
+
+* **`cron_schedule_task`**: Schedules a recurring or interval-based task with `name`, `schedule`, `prompt`, and optional `model` override.
+* **`cron_list_tasks`**: Retrieves an overview of active schedules and next scheduled run timestamps.
+* **`cron_toggle_task`**: Enables or disables an existing task by `id`.
+
+### 5. Schedule Expression Syntax
+Powered by `croner`, supporting both standard 5-part/6-part cron expressions and user-friendly interval aliases:
+
+* `0 9 * * 1-5` — Every weekday at 09:00 AM
+* `*/15 * * * *` — Every 15 minutes
+* `0 0 * * 0` — Every Sunday at midnight
+* `every 10m` / `every 2h` / `every 30s` — Natural duration intervals
+* `daily` / `hourly` / `weekly` — Standard predefined shortcuts
+
+---
+
+## 📦 Installation
+
+Install into your DeepSeek Harness web profile:
 
 ```bash
-dsh plugin --profile web add @goodandready/dsh-cron@0.1.0
+dsh plugin --profile web add @goodandready/dsh-cron
+```
+
+Restart your DeepSeek Harness instance and refresh the browser.
+
+---
+
+## ⚙️ Configuration (`settings.yaml`)
+
+Configuration can be applied in `settings.yaml` or managed interactively via the DSH Settings UI:
+
+```yaml
+# settings.yaml
+dsh-cron:
+  storagePath: "data/cron-tasks.json"
+  maxHistoryEntries: 50
+  defaultTimezone: "UTC"
+  defaultModel: ""
+  notifyOnFailure: true
 ```
 
-## Разработка и тестирование
+### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `storagePath` | `string` | `"data/cron-tasks.json"` | Relative or absolute path where scheduled tasks and run histories are persisted atomically |
+| `maxHistoryEntries` | `number` | `50` | Maximum number of run history records preserved per task card |
+| `defaultTimezone` | `string` | `"UTC"` | Default IANA timezone used for cron calculations (e.g., `"Europe/Berlin"`, `"America/New_York"`) |
+| `defaultModel` | `string` | `""` | Fallback model identifier for tasks created without an explicit model selection |
+| `notifyOnFailure` | `boolean` | `true` | Emits a notification badge in the UI if a scheduled background task encounters a failure |
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite covering schedulers, atomic storage, and HTTP handlers:
 
 ```bash
-# Запуск юнит-тестов
-node --test test/*.test.mjs
+npm test
 ```
 
-## Лицензия
+---
+
+## 📄 License
 
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.ru.md

@@ -0,0 +1,172 @@
+# 📦 @goodandready/dsh-cron
+
+<div align="center">
+
+<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="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>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Назначение и решаемая проблема
+
+При повседневной работе автономные ИИ-агенты часто должны выполнять повторяющиеся рутинные обязанности: собирать утренние сводки изменений, мониторить статус открытых пулл-реквестов, проверять работоспособность внешних API, проводить регулярную очистку кэша или запускать сценарии тестирования. Без встроенного планировщика пользователю приходится настраивать внешние утилиты crontab, сложные вебхуки или вручную запускать нужные команды каждый день.
+
+**`@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-хранилища и историю выполнения.
+
+---
+
+## 🏗️ Архитектура работы
+
+```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)"]
+    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/>(Исполнение промпта в изолированном контексте)"]
+    end
+
+    SidebarBtn --> Overlay
+    Overlay --> CreateWithDSH
+    Overlay --> ManualForm
+    CreateWithDSH -->|POST /chat-start| HttpRoutes
+    ManualForm -->|POST /tasks| HttpRoutes
+    SlashCmd -->|Диспетчеризация команд| HttpRoutes
+    HttpRoutes --> Scheduler
+    AgentTools --> Scheduler
+    Scheduler --> Store
+    Scheduler -->|Запуск по расписанию| AgentRunner
+```
+
+---
+
+## ✨ Подробный разбор возможностей
+
+### 1. Графический оверлей и кнопка в боковом меню
+По клику на значок часов в боковой панели DSH открывается удобный центр управления:
+* **Табы статусов**: быстрое переключение между категориями **Все**, **Активные**, **Приостановленные** и **Завершено**.
+* **Меню быстрых действий**: мгновенный запуск вне очереди (*«Запустить сейчас»*), постановка на паузу/возобновление и безопасное удаление задач.
+* **Готовые шаблоны в 1 клик**: предустановленные карточки популярных сценариев (*«Ежедневная сводка изменений»*, *«Еженедельный обзор репозитория»*, *«Мониторинг доступности»*).
+* **Журнал истории**: в карточке каждой задачи сохраняются отметки времени запуска, длительность работы в секундах, статус завершения и логи агента.
+
+### 2. Режим создания «Создать с DSH»
+Позволяет формулировать периодические задачи на обычном разговорном языке:
+1. Нажмите **Создать ⌄** ➔ **Создать с DSH**.
+2. Выберите нужного провайдера и модель из выпадающего списка.
+3. Опишите задачу (например: *«Каждое утро в 9:00 проверять открытые тикеты в Gitea и формировать краткий дайджест»*).
+4. Плагин автоматически создаст отдельную диалоговую сессию с агентом, передаст системные инструкции планировщика и зарегистрирует задачу в `TaskStore`.
+
+### 3. Команда `/cron` в строке ввода чата
+Для тех, кто предпочитает работу с клавиатуры:
+
+| Команда | Синтаксис | Описание |
+|:---|:---|:---|
+| `/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>` | Полностью удаляет задачу из расписания |
+
+### 4. Инструменты модели (Tool Calling)
+Агент может вызывать инструменты планировщика в процессе общения:
+
+* **`cron_schedule_task`**: создание задачи с параметрами `name`, `schedule`, `prompt` и опциональным выбором `model`.
+* **`cron_list_tasks`**: просмотр списка запланированных задач и времени их следующего срабатывания.
+* **`cron_toggle_task`**: включение или выключение задачи по её идентификатору `id`.
+
+### 5. Поддерживаемый синтаксис расписаний
+Благодаря библиотеке `croner` поддерживаются как классические cron-выражения, так и дружественные интервалы:
+
+* `0 9 * * 1-5` — по будням в 09:00 утра
+* `*/15 * * * *` — каждые 15 минут
+* `0 0 * * 0` — каждое воскресенье в полночь
+* `every 10m` / `every 2h` / `every 30s` — интервалы на понятном языке
+* `daily` / `hourly` / `weekly` — быстрые алиасы
+
+---
+
+## 📦 Установка
+
+Установка через командную строку DeepSeek Harness:
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-cron
+```
+
+Перезапустите DSH и обновите вкладку в браузере.
+
+---
+
+## ⚙️ Конфигурация (`settings.yaml`)
+
+Настройка доступна через файл конфигурации или панель настроек DSH:
+
+```yaml
+# settings.yaml
+dsh-cron:
+  storagePath: "data/cron-tasks.json"
+  maxHistoryEntries: 50
+  defaultTimezone: "Europe/Moscow"
+  defaultModel: ""
+  notifyOnFailure: true
+```
+
+### Таблица параметров конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|
+| `storagePath` | `string` | `"data/cron-tasks.json"` | Путь к файлу атомарного сохранения задач и истории |
+| `maxHistoryEntries` | `number` | `50` | Максимальное количество записей журнала запусков на задачу |
+| `defaultTimezone` | `string` | `"UTC"` | Часовой пояс IANA для расчёта cron-выражений |
+| `defaultModel` | `string` | `""` | Модель по умолчанию, если не выбрана вручную |
+| `notifyOnFailure` | `boolean` | `true` | Показывать уведомление в интерфейсе при сбое фоновой задачи |
+
+---
+
+## 🧪 Тестирование
+
+Запуск набора юнит-тестов:
+
+```bash
+npm test
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.zh.md

@@ -0,0 +1,172 @@
+# 📦 @goodandready/dsh-cron
+
+<div align="center">
+
+<h3>面向 DeepSeek Harness 的定时 Cron 调度、后台自动化与智能体任务执行引擎</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="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>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>
+</p>
+
+<p align="center">
+  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 核心定位与解决痛点
+
+在自主 AI 智能体日常研发与运维工作中，经常需要承担周期性的例行事务：每日早晨生成代码变更简报、定期巡检待处理 PR、监测外部 API 运行健康度，或者定时执行分支清理与自动化测试。在缺乏内置调度器的情况下，开发者通常只能借助外部系统 crontab 脚本、复杂的 Webhook 链路，或者每日人工手动输入指令。
+
+**`@goodandready/dsh-cron`** 是专为 DeepSeek Harness 打造的原生全栈定时调度与后台任务自动化插件。它无缝融合了标准 Cron 表达式、自然语言时间间隔与智能体自主会话执行：
+
+1. **可视化任务管理中心**：集成在 DSH 侧边导航栏的时钟按钮（紧邻看板与聊天），提供全功能任务列表抽屉、状态标签过滤、执行历史与快速动作。
+2. **“与 DSH 交互创建”模式**：直接与智能体自然对话，由模型自动梳理需求、配置执行模型并转化为精准的定时任务。
+3. **聊天斜杠指令（`/cron`）**：在对话输入框中即可实现全键盘调度管理（`/cron list`, `/cron add`, `/cron pause`, `/cron run`）。
+4. **智能体原生工具调用（AI Tool Calling）**：赋予智能体 `cron_schedule_task`、`cron_list_tasks` 等工具，支持模型在对话中自主为后续任务安排执行时间表。
+5. **高可靠调度引擎与原子持久化**：基于 `croner` 引擎构建，支持时区配置、友好间隔语法（`every 15m`, `daily`, `weekdays`）、原子写入式 JSON 存储及完整运行审计。
+
+---
+
+## 🏗️ 架构设计
+
+```mermaid
+graph TD
+    subgraph Client ["前端交互界面 (DSH Web UI)"]
+        SidebarBtn["侧边栏时钟按钮<br/>(DSH 客户端界面插槽)"]
+        Overlay["可视化任务管理抽屉<br/>(标签页: 全部, 运行中, 已暂停, 已完成)"]
+        CreateWithDSH["'与 DSH 交互创建' 弹窗<br/>(模型选择与任务自然语言描述)"]
+        ManualForm["手动配置任务弹窗<br/>(Cron 表达式, 时区, 执行模型)"]
+        SlashCmd["斜杠指令解析器<br/>(/cron add, list, pause, run)"]
+    end
+
+    subgraph Server ["服务端运行时 (Cordis 插件与服务)"]
+        HttpRoutes["HTTP REST API 端点<br/>(/dsh-cron/tasks, /models, /chat-start)"]
+        AgentTools["AI 工具网关<br/>(cron_schedule_task, cron_list_tasks)"]
+        Scheduler["TaskScheduler 调度引擎<br/>(Croner 实例生命周期管理)"]
+        Store["原子存储 TaskStore<br/>(安全重写 tasks.json)"]
+        AgentRunner["智能体会话派发器<br/>(在独立上下文执行 Prompt)"]
+    end
+
+    SidebarBtn --> Overlay
+    Overlay --> CreateWithDSH
+    Overlay --> ManualForm
+    CreateWithDSH -->|POST /chat-start| HttpRoutes
+    ManualForm -->|POST /tasks| HttpRoutes
+    SlashCmd -->|指令分发| HttpRoutes
+    HttpRoutes --> Scheduler
+    AgentTools --> Scheduler
+    Scheduler --> Store
+    Scheduler -->|周期触发| AgentRunner
+```
+
+---
+
+## ✨ 核心特性深度解析
+
+### 1. 可视化任务管理中心
+点击 DSH 侧边栏的时钟图标即可唤出定时任务全景抽屉：
+* **状态过滤标签页**：一键在 **全部 (All)**、**运行中 (Active)**、**已暂停 (Paused)** 和 **已完成 (Completed)** 之间快速切换。
+* **快捷操作菜单**：支持即刻手动测试执行（*“立即运行”*）、暂停/恢复调度，以及带有二次确认防误触的安全删除。
+* **一键推荐模板**：内置高频工作流预设（*“每日早晨研发简报”*、*“每周代码仓库复盘”*、*“API 探活心跳检测”*）。
+* **执行历史记录**：展开任意任务卡片即可查阅过往历次运行时间戳、执行耗时（秒）、完成状态以及智能体生成的完整执行日志。
+
+### 2. “与 DSH 交互创建” 智能配置模式
+告别晦涩的手动 Cron 表达式换算：
+1. 点击 **新建 ⌄** ➔ **与 DSH 交互创建**。
+2. 在下拉框中直观选取本次自动化任务使用的模型服务商与模型名称。
+3. 输入任务自然语言意图（例如：*“每个工作日上午 9 点自动扫描仓库中未关闭的 Issue 并汇总至看板”*）。
+4. 插件将自动创建专属智能体会话，注入调度器系统指令，协助生成结构化配置并写入持久化存储。
+
+### 3. 聊天斜杠指令 (`/cron`)
+极客与键盘流的高效快捷通道：
+
+| 指令 | 语法 | 功能说明 |
+|:---|:---|:---|
+| `/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>` | 从存储中永久注销并删除任务 |
+
+### 4. 智能体原生工具调用 (Tool Calling)
+智能体在处理长期复杂项目时，可自主调用调度器工具：
+
+* **`cron_schedule_task`**：注册定时任务，支持传入 `name`、`schedule`、`prompt` 及可选 `model` 覆盖。
+* **`cron_list_tasks`**：获取已注册任务列表及下一次预定触发时刻。
+* **`cron_toggle_task`**：通过 `id` 快速切换任务的启用/停用状态。
+
+### 5. 支持的时间表达式语法
+依托底层 `croner` 引擎，全面兼容标准 5 段/6 段 Cron 语法与易读时间间隔：
+
+* `0 9 * * 1-5` — 工作日早晨 09:00
+* `*/15 * * * *` — 每隔 15 分钟
+* `0 0 * * 0` — 每周日午夜 00:00
+* `every 10m` / `every 2h` / `every 30s` — 自然语言时间间隔
+* `daily` / `hourly` / `weekly` — 快捷预设别名
+
+---
+
+## 📦 快速安装
+
+通过 DeepSeek Harness CLI 安装：
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-cron
+```
+
+重启 DSH 并刷新浏览器工作区。
+
+---
+
+## ⚙️ 配置指南 (`settings.yaml`)
+
+可在 `settings.yaml` 中配置，或在 Web UI 设置面板中调整：
+
+```yaml
+# settings.yaml
+dsh-cron:
+  storagePath: "data/cron-tasks.json"
+  maxHistoryEntries: 50
+  defaultTimezone: "Asia/Shanghai"
+  defaultModel: ""
+  notifyOnFailure: true
+```
+
+### 配置参数参考表
+
+| 参数名 | 类型 | 默认值 | 功能说明 |
+|:---|:---|:---|:---|
+| `storagePath` | `string` | `"data/cron-tasks.json"` | 定时任务与运行历史原子持久化文件的存储路径 |
+| `maxHistoryEntries` | `number` | `50` | 每个任务卡片保留的最大历史运行记录条数 |
+| `defaultTimezone` | `string` | `"UTC"` | 计算 Cron 触发时刻所使用的默认 IANA 时区（如 `"Asia/Shanghai"`） |
+| `defaultModel` | `string` | `""` | 未显式指定模型时的全局后备模型标识 |
+| `notifyOnFailure` | `boolean` | `true` | 当后台定时任务执行失败时是否在 Web UI 弹出告警徽标 |
+
+---
+
+## 🧪 测试与校验
+
+运行全部自动化单元测试：
+
+```bash
+npm test
+```
+
+---
+
+## 📄 开源许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cron",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Scheduled cron tasks, background automation and agent execution for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",