@goodandready/dsh-cron 0.2.27 → 0.2.29

package/README.md

@@ -43,7 +43,7 @@ Autonomous AI agents often need to perform recurring duties: generating daily mo
 
 1. **Rich Visual Task Manager** — a sidebar button with a collapsible list of active jobs (next run or live state, capped and persisted), plus a full panel to inspect, filter by type/model/channel, pause, trigger, duplicate, export/import and create tasks.
 2. **Interactive "Create with DSH" Workflow** — chat with your agent to translate high-level requirements into a well-formed scheduled task.
-3. **Autonomous AI Tool Calling** — native `cron_*` tools let agents schedule their own follow-up executions during conversations.
+3. **Autonomous AI Tool Calling** — single unified `cron` tool (`action: 'create' | 'list' | 'get' | 'update' | 'pause' | 'resume' | 'run' | 'delete'`) lets agents inspect, trigger, and manage background automation without schema bloat.
 4. **Robust Scheduler & Atomic Storage** — built on `croner` with interval aliases, one-shot delays, atomic file persistence, run histories, and cost tracking.
 5. **Six Execution Runtimes** — shell, Node.js, Python, HTTP/webhook, remote SSH and Docker, plus per-task environment variables, workspace binding and isolated git worktrees for code-modifying agent tasks.
 6. **Multi-Channel Delivery With Templates** — one run fans out to Telegram, dsh-kanban, Discord, Slack, ntfy, Bark, PushPlus, voice (`dsh-tts`) and Gitea, with `{variable}` message templates and secrets referenced by DSH credential name.
@@ -64,7 +64,7 @@ graph TD
 
     subgraph Server ["Server Runtime (Cordis & DSH Services)"]
         HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
-        AgentTools["AI Tool Calling Gateway<br/>(cron_create_task, cron_list_tasks, ...)"]
+        AgentTools["AI Tool Calling Gateway<br/>(cron)"]
         Scheduler["TaskScheduler Engine<br/>(Croner instances + one-shot timers)"]
         Store["Atomic TaskStore<br/>(tasks.json with atomic write)"]
         AgentRunner["Agent Session Dispatcher<br/>(Executes prompt with chosen model)"]
@@ -104,27 +104,49 @@ Click the clock icon in the DSH sidebar (positioned next to the new-session butt
 Transform natural language into a scheduled job without guessing cron syntax:
 1. Click **Create ⌄** ➔ **Create with DSH**.
 2. Describe what you want to automate (e.g. *"Check open PRs every weekday at 9:00 and draft review comments"*).
-3. The plugin spawns a dedicated agent session pre-injected with scheduler instructions. The agent clarifies the details with you — LLM vs no-LLM shell task, the exact cron expression, an economical model from those available in your DSH installation, and whether a "silent rule" (alert only on new events or failures) should apply — and registers the task through the `cron_create_task` tool only after your confirmation.
-
-### 3. Agent Tools (Tool Calling)
-Autonomous agents can manage schedules directly:
-
-| Tool | Description |
-|:---|:---|
-| `cron_create_task` | Creates a scheduled task: `title`, `schedule`, `prompt`, `fallbackModel` (one retry on a stronger model when a run fails), optional `type` (`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`), `delivery`, `provider`, `model`, `channels`, `template`, `notifyTelegram`, `onlyOnFailure`, `timeoutSeconds`, `overlapPolicy`, `kanbanMode` |
-| `cron_schedule_task` | Alias of `cron_create_task` kept for compatibility with existing agent prompts |
-| `cron_list_tasks` | Lists tasks with statuses, next run timestamps, token totals, and cost estimates |
-| `cron_pause_task` | Pauses a schedule without deleting its configuration |
-| `cron_resume_task` | Resumes a paused schedule |
-| `cron_delete_task` | Permanently removes a task and its history |
-| `cron_run_task` | Triggers an immediate out-of-band run |
-| `cron_get_task` | Reads the full configuration of one task, including fields the list does not show |
-| `cron_update_task` | Changes an existing task in place (whitelisted fields, same validation as the HTTP route); the model is told to confirm code-executing changes with the user first |
+3. The plugin spawns a dedicated agent session pre-injected with scheduler instructions. The agent clarifies the details with you — LLM vs no-LLM shell task, the exact cron expression, an economical model from those available in your DSH installation, and whether a "silent rule" (alert only on new events or failures) should apply — evaluates simple in-chat reminder (`schedule_create`) vs background automation (`cron`), and registers the task through the `cron` tool (`action: 'create'`) only after your confirmation.
+
+### 2. DSH Core schedule vs dsh-cron
+
+DeepSeek Harness includes a lightweight built-in `@deepseek-ai/dsh-schedule` extension for basic in-chat reminders. Use this guide to choose the right tool:
+
+| Capability | DSH Core `schedule` (`@deepseek-ai/dsh-schedule`) | `@goodandready/dsh-cron` |
+|:---|:---|:---|
+| **Primary Purpose** | In-chat reminders & timed prompts back into the active dialogue | Unattended background automation runner & orchestrator |
+| **Execution Context** | Active conversation session | Isolated dedicated agent sessions or background runner |
+| **Runtimes** | Chat session turn only (LLM prompt) | 9 runtimes: `llm`, `script` (bash/sh), `node`, `python`, `http` (REST/webhook), `ssh`, `docker`, `skill`, `workflow` |
+| **Model Tools** | `schedule_create`, `schedule_list`, `schedule_delete` | Unified `cron` tool (action: `create`, `list`, `get`, `update`, `pause`, `resume`, `run`, `delete`) |
+| **Tool Schema Footprint** | ~1.5k characters | ~1.5k characters (consolidated from 9 tools down to 1, saving ~12k characters of LLM context) |
+| **Delivery Channels** | Current chat only | Multi-channel: Telegram, Discord, Slack, Webhook, Kanban, ntfy, Bark, PushPlus, Voice (TTS), Gitea |
+| **Code Modifying Isolation** | None | Ephemeral or retained git worktrees (`worktree: true`) |
+| **Cost & Token Limits** | None | Guard rails: `costLimitUsd`, `dailyCostLimitUsd`, `tokenLimit` auto-pausing |
+| **Failure Handling & Health** | None | Automatic retries with exponential backoff, failure inspector, Dead Man's Snitch / Better Uptime heartbeats |
+| **Silent Rule** | None | Suppress delivery when no new events or changes occur (zero noise / zero spam) |
+| **Task Management** | Basic list / delete | Full UI manager, execution history, log viewer, run metrics, manual trigger, import/export, profile config sync |
+
+### 3. Agent Tool (`cron`)
+
+Autonomous agents manage schedules directly through a single unified `cron` tool, keeping LLM schema overhead minimal:
+
+| Action | Description | Key Parameters |
+|:---|:---|:---|
+| `create` | Creates a new background scheduled task or automation job | `title`, `schedule`, `prompt`, `type`, `model`, `channels`, `delivery`, etc. |
+| `list` | Lists tasks with status, next run timestamp, tokens, and cost | `status` (`'all'`, `'active'`, `'paused'`, `'completed'`) |
+| `get` | Reads the full detailed configuration of one task | `id` |
+| `update` | Modifies an existing task in place (requires `confirmCodeSwitch: true` when switching to code-executing runtimes) | `id`, patch fields |
+| `pause` | Pauses an active schedule without deleting its configuration | `id` |
+| `resume` | Resumes a paused schedule | `id` |
+| `run` | Triggers an immediate out-of-band execution | `id` |
+| `delete` | Permanently removes a task and its run history | `id` |
+
+> [!NOTE]
+> **Context Optimization & Migration**: Previously, 9 separate tool schemas consumed ~13.6k characters of context in every model turn. The consolidated `cron` tool cuts this footprint by ~88% down to ~1.5k characters. Legacy tool names (`cron_create_task`, `cron_schedule_task`, `cron_list_tasks`, etc.) are gracefully rejected with helpful guidance directing the model to `cron` with the matching `action`. For simple in-conversation reminders, models are instructed to recommend core `schedule_create`.
 
 Example invocation the model can make during a conversation:
 
-```
-cron_create_task({
+```json
+cron({
+  "action": "create",
   "title": "Morning digest",
   "schedule": "0 8 * * 1-5",
   "prompt": "Prepare a brief morning digest of active tasks and open tickets.",
@@ -517,7 +539,7 @@ Notes:
 
 ## 🔌 HTTP API Reference
 
-All endpoints are served by the DSH web server under `/dsh-cron/`. Read endpoints are open to the local UI; **mutating endpoints reject cross-origin requests** and accept bodies up to 1 MB. Creating `script`-type tasks over HTTP additionally requires the `x-dsh-cron-confirm: script` header, which forged cross-site posts cannot attach.
+All endpoints are served by the DSH web server under `/dsh-cron/`. Endpoints are protected by a hardened HTTP source guard (`isTrustedRequest`): non-loopback remote callers require token authentication (`Authorization: Bearer <token>` or `x-dsh-cron-token`), and browser requests enforce strict `Host` and `Origin` matching, reject `Origin: null`, and restrict `Sec-Fetch-Site` to `same-origin` or `none`. Heartbeat ping routes strictly require the `POST` method. Task `GET` responses automatically redact sensitive fields (`env`, `httpHeaders`, `httpBody`) as `'[REDACTED]'`, and update operations preserve existing secrets when `'[REDACTED]'` is passed. Creating `script`-type tasks over HTTP additionally requires the `x-dsh-cron-confirm: script` header, which forged cross-site posts cannot attach. Body size is capped at 1 MB.
 
 | Method | Path | Description |
 |:---|:---|:---|

package/README.ru.md

@@ -64,7 +64,7 @@ graph TD
 
     subgraph Server ["Серверная часть (Cordis и сервисы DSH)"]
         HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
-        AgentTools["Шлюз tool calling<br/>(cron_create_task, cron_list_tasks, ...)"]
+        AgentTools["Шлюз tool calling<br/>(cron)"]
         Scheduler["Движок TaskScheduler<br/>(экземпляры Croner + таймеры one-shot)"]
         Store["Атомарный TaskStore<br/>(tasks.json, атомарная запись)"]
         AgentRunner["Диспетчер агентских сессий<br/>(запуск промпта выбранной моделью)"]
@@ -104,26 +104,49 @@ graph TD
 Превратите естественный язык в задачу без подбора cron-синтаксиса:
 1. Нажмите **Создать ⌄** ➔ **Создать с DSH**.
 2. Опишите, что нужно автоматизировать (например: *«Проверяй открытые PR по будням в 9:00 и готовь черновики комментариев»*).
-3. Плагин создаст отдельную агентскую сессию с системными инструкциями планировщика. Агент уточнит детали — LLM или NO-LLM shell-задача, точное cron-выражение, экономичная модель из доступных в вашей установке DSH, нужно ли «правило тишины» (алерт только при новых событиях или сбоях) — и создаст задачу через инструмент `cron_create_task` только после вашего подтверждения.
-
-### 3. Инструменты агентов (tool calling)
-
-| Инструмент | Описание |
-|:---|:---|
-| `cron_create_task` | Создаёт задачу: `title`, `schedule`, `prompt`, `fallbackModel` (одна повторная попытка на сильной модели при сбое), опционально `type` (`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`), `delivery`, `provider`, `model`, `channels`, `template`, `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` | Немедленный внеплановый запуск |
-| `cron_get_task` | Полная конфигурация одной задачи, включая поля, которых нет в списке |
-| `cron_update_task` | Изменяет существующую задачу на месте (whitelisted-поля, та же валидация, что у HTTP-маршрута); модели предписано сперва подтверждать с пользователем изменения, исполняющие код |
+3. Плагин создаст отдельную агентскую сессию с системными инструкциями планировщика. Агент уточнит детали — LLM или NO-LLM shell-задача, точное cron-выражение, экономичная модель из доступных в вашей установке DSH, нужно ли «правило тишины» (алерт только при новых событиях или сбоях) — оценивает тип задачи (простое напоминание в текущем чате через `schedule_create` ядра vs фоновая автоматизация через `cron`) и создаёт задачу через инструмент `cron` (`action: 'create'`) только после вашего подтверждения.
+
+### 2. Встроенный schedule ядра DSH vs dsh-cron
+
+В состав DeepSeek Harness входит легковесное встроенное расширение `@deepseek-ai/dsh-schedule` для базовых напоминаний в чате. Сравнительная таблица помогает выбрать правильный инструмент:
+
+| Возможность | Встроенный `schedule` ядра (`@deepseek-ai/dsh-schedule`) | `@goodandready/dsh-cron` |
+|:---|:---|:---|
+| **Основное назначение** | Напоминания и таймеры, доставляемые обратно в текущий диалог пользователя | Автономный фоновый раннер и оркестратор запланированных задач |
+| **Контекст исполнения** | Текущая активная сессия чата | Изолированные выделенные агентские сессии или фоновые процессы |
+| **Рантаймы** | Только ход в диалоге (LLM-промпт) | 9 рантаймов: `llm`, `script` (bash/sh), `node`, `python`, `http` (REST/webhook), `ssh`, `docker`, `skill`, `workflow` |
+| **Инструменты модели** | `schedule_create`, `schedule_list`, `schedule_delete` | Единый инструмент `cron` (action: `create`, `list`, `get`, `update`, `pause`, `resume`, `run`, `delete`) |
+| **Размер схемы инструментов** | ~1.5k символов | ~1.5k символов (консолидация 9 инструментов в 1, экономия ~12k символов контекста) |
+| **Каналы доставки** | Только текущий чат | Мультиканальность: Telegram, Discord, Slack, Webhook, Kanban, ntfy, Bark, PushPlus, Голос (TTS), Gitea |
+| **Изоляция кода** | Отсутствует | Одноразовые или сохраняемые git worktree (`worktree: true`) |
+| **Лимиты расходов и токенов** | Отсутствуют | Защита от перерасхода: `costLimitUsd`, `dailyCostLimitUsd`, `tokenLimit` с автопаузой |
+| **Надёжность и мониторинг** | Отсутствуют | Повторы с экспоненциальным backoff, failure inspector, heartbeat-пинги (Dead Man's Snitch / Better Uptime) |
+| **Тихое правило (Silent Rule)** | Отсутствует | Полная тишина при отсутствии изменений (ноль шума и спама в каналы) |
+| **Управление задачами** | Базовый список / удаление | Полноценный UI-менеджер, история запусков, логи, метрики, ручной запуск, импорт/экспорт, синхронизация с конфигом |
+
+### 3. Инструмент агента (`cron`)
+
+Автономные агенты управляют расписаниями через единый компактный инструмент `cron`:
+
+| Действие (action) | Описание | Основные параметры |
+|:---|:---|:---|
+| `create` | Создаёт фоновую задачу или периодический процесс | `title`, `schedule`, `prompt`, `type`, `model`, `channels`, `delivery` и др. |
+| `list` | Список задач со статусами, временем следующего запуска, токенами и стоимостью | `status` (`'all'`, `'active'`, `'paused'`, `'completed'`) |
+| `get` | Полная конфигурация одной задачи по её идентификатору | `id` |
+| `update` | Изменяет существующую задачу на месте (переключение в код требует `confirmCodeSwitch: true`) | `id`, поля патча |
+| `pause` | Приостанавливает расписание без удаления конфигурации | `id` |
+| `resume` | Возобновляет приостановленное расписание | `id` |
+| `run` | Немедленный внеплановый запуск задачи | `id` |
+| `delete` | Полностью удаляет задачу и её историю | `id` |
+
+> [!NOTE]
+> **Оптимизация контекста и миграция**: Ранее 9 отдельных схем инструментов занимали ~13.6k символов в каждом ходе модели. Консолидация в один инструмент `cron` сократила этот объём на ~88% до ~1.5k символов. Легаси-имена инструментов (`cron_create_task`, `cron_schedule_task`, `cron_list_tasks` и т.д.) отклоняются с понятной подсказкой использовать `cron` с соответствующим `action`. Для простых напоминаний в диалоге модель ориентируется на встроенный `schedule_create`.
 
 Пример вызова модели в диалоге:
 
-```
-cron_create_task({
+```json
+cron({
+  "action": "create",
   "title": "Утренняя сводка",
   "schedule": "0 8 * * 1-5",
   "prompt": "Подготовь короткую утреннюю сводку активных задач и открытых тикетов.",
@@ -506,7 +529,7 @@ bash deploy.sh verify [exact-version]
 
 ## 🔌 HTTP API
 
-Все эндпоинты обслуживаются веб-сервером DSH под `/dsh-cron/`. Чтение открыто локальному интерфейсу; **мутирующие эндпоинты отклоняют cross-origin запросы** и принимают тела до 1 МБ. Для создания `script`-задач по HTTP дополнительно требуется заголовок `x-dsh-cron-confirm: script`, который подделанный межсайтовый запрос приложить не может.
+Все эндпоинты обслуживаются веб-сервером DSH под `/dsh-cron/`. Эндпоинты защищены строгой проверкой источника (`isTrustedRequest`): удалённые не-loopback клиенты требуют аутентификацию токеном (`Authorization: Bearer <token>` или `x-dsh-cron-token`), а браузерные запросы проходят строгую валидацию совпадения `Host` и `Origin` с блокировкой `Origin: null` и ограничением `Sec-Fetch-Site` (`same-origin` или `none`). Маршруты heartbeat-ping строго требуют метод `POST`. В ответах `GET` чувствительные данные задач (`env`, `httpHeaders`, `httpBody`) маскируются как `'[REDACTED]'`, а при обновлении задач переданные плейсхолдеры `'[REDACTED]'` сохраняют оригинальные сохранённые секреты. Для создания `script`-задач по HTTP дополнительно требуется заголовок `x-dsh-cron-confirm: script`. Максимальный размер тела запроса ограничен 1 МБ.
 
 | Метод | Путь | Описание |
 |:---|:---|:---|

package/README.zh.md

@@ -64,7 +64,7 @@ graph TD
 
     subgraph Server ["服务端 (Cordis 与 DSH 服务)"]
         HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
-        AgentTools["工具调用网关<br/>(cron_create_task, cron_list_tasks, ...)"]
+        AgentTools["工具调用网关<br/>(cron)"]
         Scheduler["TaskScheduler 引擎<br/>(Croner 实例 + one-shot 定时器)"]
         Store["原子 TaskStore<br/>(tasks.json 原子写入)"]
         AgentRunner["智能体会话调度器<br/>(以指定模型执行提示词)"]
@@ -104,26 +104,49 @@ graph TD
 无需猜测 cron 语法，用自然语言即可创建任务：
 1. 点击 **Create ⌄** ➔ **Create with DSH**。
 2. 描述要自动化的内容（例如：*“每个工作日早上 9 点检查未处理的 PR 并起草评论”*）。
-3. 插件会创建一个注入了调度器指令的专属智能体会话。智能体会与你确认细节 —— LLM 还是 NO-LLM shell 任务、准确的 cron 表达式、在你的 DSH 安装中可用的经济型模型，以及是否启用“静默规则”（仅在新事件或故障时告警）—— 并在你确认后才通过 `cron_create_task` 工具注册任务。
-
-### 3. 智能体工具（Tool Calling）
-
-| 工具 | 说明 |
-|:---|:---|
-| `cron_create_task` | 创建任务：`title`、`schedule`、`prompt`、`fallbackModel`（失败时改用更强模型重试一次），可选 `type`（`llm`/`script`/`node`/`python`/`http`/`ssh`/`docker`/`skill`/`workflow`）、`delivery`、`provider`、`model`、`channels`、`template`、`notifyTelegram`、`onlyOnFailure`、`timeoutSeconds`、`overlapPolicy`、`kanbanMode` |
-| `cron_schedule_task` | `cron_create_task` 的别名，保持与既有提示词兼容 |
-| `cron_list_tasks` | 列出任务的状态、下次运行时间、token 总量与成本估算 |
-| `cron_pause_task` | 暂停调度而不删除配置 |
-| `cron_resume_task` | 恢复已暂停的调度 |
-| `cron_delete_task` | 永久删除任务及其历史 |
-| `cron_run_task` | 触发一次立即的带外运行 |
-| `cron_get_task` | 读取单个任务的完整配置，包括列表中看不到的字段 |
-| `cron_update_task` | 就地修改现有任务（白名单字段，校验与 HTTP 路由一致）；提示模型先与用户确认会执行代码的改动 |
+3. 插件会创建一个注入了调度器指令的专属智能体会话。智能体会与你确认细节 —— LLM 还是 NO-LLM shell 任务、准确的 cron 表达式、在你的 DSH 安装中可用的经济型模型，以及是否启用“静默规则”（仅在新事件或故障时告警）—— 评估属于对话内定时提醒（`schedule_create`）还是后台自动化（`cron`），并在获得您的确认后通过 `cron` 工具（`action: 'create'`）注册任务。
+
+### 2. DSH 核心内置 schedule 与 dsh-cron 对比
+
+DeepSeek Harness 内置了轻量级扩展 `@deepseek-ai/dsh-schedule`，用于会话内的基础定时提醒。下表帮助您根据场景选择合适的工具：
+
+| 功能维度 | DSH 核心 `schedule` (`@deepseek-ai/dsh-schedule`) | `@goodandready/dsh-cron` |
+|:---|:---|:---|
+| **主要定位** | 当前会话内的定时提醒与催办消息 | 无人值守的后台自动化执行器与任务编排引擎 |
+| **执行上下文** | 当前活动会话内 | 独立的隔离智能体会话或外部后台进程 |
+| **执行运行时** | 仅当前会话提示词（LLM） | 9 种运行时：`llm`、`script` (bash/sh)、`node`、`python`、`http` (REST/webhook)、`ssh`、`docker`、`skill`、`workflow` |
+| **模型工具** | `schedule_create`、`schedule_list`、`schedule_delete` | 统一 `cron` 工具（action: `create`、`list`、`get`、`update`、`pause`、`resume`、`run`、`delete`） |
+| **工具模式体积** | 约 1.5k 字符 | 约 1.5k 字符（由 9 个工具合并为 1 个，节省约 12k 字符上下文） |
+| **推送渠道** | 仅限当前会话 | 多渠道：Telegram、Discord、Slack、Webhook、Kanban、ntfy、Bark、PushPlus、语音 (TTS)、Gitea |
+| **代码修改隔离** | 无 | 临时或保留的 git worktree 隔离环境（`worktree: true`） |
+| **成本与 Token 限制** | 无 | 成本熔断防护：`costLimitUsd`、`dailyCostLimitUsd`、`tokenLimit` 自动暂停 |
+| **容错与健康检查** | 无 | 指数退避自动重试、失败自动诊断、心跳监测 (Dead Man's Snitch / Better Uptime) |
+| **静默规则 (Silent Rule)** | 无 | 无新事件或变更时完全静默（杜绝通道垃圾消息） |
+| **任务管理** | 基础列表与删除 | 完整 UI 管理器、运行历史、日志查看器、指标统计、手动触发、导入导出、配置同步 |
+
+### 3. 智能体工具 (`cron`)
+
+自主智能体通过单个统一的 `cron` 工具直接管理定时任务，大幅降低模型模式开销：
+
+| 动作 (action) | 说明 | 核心参数 |
+|:---|:---|:---|
+| `create` | 创建新的后台定时任务或自动化作业 | `title`、`schedule`、`prompt`、`type`、`model`、`channels`、`delivery` 等 |
+| `list` | 列出任务的状态、下次运行时间、token 总量与成本估算 | `status` (`'all'`、`'active'`、`'paused'`、`'completed'`) |
+| `get` | 根据任务 ID 获取单项任务的完整配置 | `id` |
+| `update` | 就地修改现有任务（切换到代码执行运行时需 `confirmCodeSwitch: true`） | `id`、修改字段 |
+| `pause` | 暂停调度而不删除配置 | `id` |
+| `resume` | 恢复已暂停的调度 | `id` |
+| `run` | 触发一次立即的带外运行 | `id` |
+| `delete` | 永久删除任务及其历史 | `id` |
+
+> [!NOTE]
+> **上下文优化与平滑迁移**：此前 9 个单独的工具模式在每次模型轮次中消耗约 13.6k 字符。整合为单一 `cron` 工具后，模式开销减少约 88%（降至约 1.5k 字符）。旧工具名（`cron_create_task`、`cron_schedule_task`、`cron_list_tasks` 等）被优雅拦截，并返回清晰迁移提示，引导模型使用带对应 `action` 的 `cron` 工具。对于简单的会话内提醒，模型将建议使用核心内置的 `schedule_create`。
 
 会话中模型可进行的调用示例：
 
-```
-cron_create_task({
+```json
+cron({
+  "action": "create",
   "title": "Morning digest",
   "schedule": "0 8 * * 1-5",
   "prompt": "Prepare a brief morning digest of active tasks and open tickets.",
@@ -506,7 +529,7 @@ dsh-cron:
 
 ## 🔌 HTTP API 参考
 
-所有端点由 DSH Web 服务器在 `/dsh-cron/` 下提供。读端点对本地 UI 开放；**变更端点拒绝跨域请求**且请求体最大 1 MB。通过 HTTP 创建 `script` 类型任务还需要 `x-dsh-cron-confirm: script` 请求头 —— 伪造的跨站请求无法附加该头。
+所有端点由 DSH Web 服务器在 `/dsh-cron/` 下提供。所有端点均受到强化的 HTTP 来源防护（`isTrustedRequest`）：非回环远程客户端必须携带有效令牌（`Authorization: Bearer <token>` 或 `x-dsh-cron-token`），浏览器请求严格校验 `Host` 与 `Origin` 一致性并拒绝 `Origin: null`，同时限制 `Sec-Fetch-Site` 仅允许 `same-origin` 或 `none`。心跳 ping 端点严格要求 `POST` 方法。任务 `GET` 响应自动将敏感字段（`env`、`httpHeaders`、`httpBody`）掩码为 `'[REDACTED]'`，并在更新操作提交 `'[REDACTED]'` 时安全保留已有原密钥。通过 HTTP 创建 `script` 类型任务还需要 `x-dsh-cron-confirm: script` 请求头。请求体大小上限为 1 MB。
 
 | 方法 | 路径 | 说明 |
 |:---|:---|:---|

package/lib/api-helpers.js

@@ -4,6 +4,13 @@ import { sendJson, readBody, rejectCrossOrigin } from './http-utils.js';
 const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
 
 export function handleHeartbeatPing({ store, req, res, taskId }) {
+  if (req.method !== 'POST') {
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+  const apiToken = store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken })) return;
+
   const task = store.get(taskId);
   if (!task) {
     sendJson(res, 404, { ok: false, error: 'Task not found' });
@@ -17,7 +24,10 @@ export function handleHeartbeatPing({ store, req, res, taskId }) {
   sendJson(res, 200, result);
 }
 
-export async function handleSchedulePreview({ req, res, url }) {
+export async function handleSchedulePreview({ req, res, url, store }) {
+  const apiToken = store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken })) return;
+
   let schedule = '';
   let timezone = '';
   let count = 5;
@@ -51,7 +61,8 @@ export async function handleSchedulePreview({ req, res, url }) {
 }
 
 export async function handleDryRunTask({ store, scheduler, req, res, id }) {
-  if (rejectCrossOrigin(req, res)) return;
+  const apiToken = store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken })) return;
   const task = store.get(id);
   if (!task) {
     sendJson(res, 404, { ok: false, error: 'Task not found' });
@@ -65,4 +76,3 @@ export async function handleDryRunTask({ store, scheduler, req, res, id }) {
     sendJson(res, 500, { ok: false, error: err.message });
   }
 }
-

package/lib/api.js

@@ -11,7 +11,7 @@ import { normalizeTaskType, CODE_EXECUTING_TYPES } from './runtimes.js';
 import { CHANNEL_IDS, unknownChannelIds } from './channels.js';
 import { applyTaskPatch } from './task-patch.js';
 import { MANAGED_BY_CONFIG, configOwnedMessage } from './config-jobs.js';
-import { sendJson, rejectCrossOrigin, readBody, pickPatchableFields, SCRIPT_CONFIRM_HEADER } from './http-utils.js';
+import { sendJson, rejectCrossOrigin, readBody, pickPatchableFields, SCRIPT_CONFIRM_HEADER, redactTaskSecrets, restoreTaskSecrets } from './http-utils.js';
 import {
   validateTaskType,
   buildDuplicateTask,
@@ -64,9 +64,10 @@ function refuseConfigOwned(res, id) {
 export function createCronApiHandler(store, scheduler, collection) {
   return async function handleCronApi(req, res) {
     try {
+      const apiToken = store?.getSettings?.()?.apiToken;
       const url = new URL(req.url, 'http://127.0.0.1');
       const parts = url.pathname.split('/').filter(Boolean);
-      const scope = parts[1]; // 'tasks' | 'action'
+      const scope = parts[1]; // 'tasks' | 'action' | 'heartbeat-ping'
       const id = parts[2];
       const action = parts[3];
 
@@ -75,22 +76,22 @@ export function createCronApiHandler(store, scheduler, collection) {
         return;
       }
 
-      if (scope === 'heartbeat' && id) {
+      if ((scope === 'heartbeat' || scope === 'heartbeat-ping') && id) {
         handleHeartbeatPing({ store, req, res, taskId: id });
         return;
       }
 
       if (scope === 'schedule' && id === 'preview') {
-        await handleSchedulePreview({ req, res, url });
+        await handleSchedulePreview({ req, res, url, store });
         return;
       }
 
       if (!id) {
-        await handleTaskCollection({ store, scheduler, collection, req, res, url, scope });
+        await handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken });
         return;
       }
 
-      if (req.method !== 'GET' && rejectCrossOrigin(req, res)) return;
+      if (rejectCrossOrigin(req, res, { apiToken })) return;
 
       // Export/import are collection operations that live under /tasks/:id/…,
       // so they are matched before the generic id handling below.
@@ -103,7 +104,7 @@ export function createCronApiHandler(store, scheduler, collection) {
         return;
       }
 
-      await handleTaskItem({ store, scheduler, req, res, url, id, action });
+      await handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken });
     } catch (err) {
       sendJson(res, err.statusCode || 500, { ok: false, error: err.message });
     }
@@ -112,18 +113,19 @@ export function createCronApiHandler(store, scheduler, collection) {
 
 // ------------------------------------------------------------- collection
 
-async function handleTaskCollection({ store, scheduler, collection, req, res, url, scope }) {
+async function handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken }) {
   // The alias family only exists for individual tasks.
   if (scope === 'action' || !collection) {
     sendJson(res, 405, NOT_ALLOWED);
     return;
   }
   if (req.method === 'GET') {
+    if (rejectCrossOrigin(req, res, { apiToken })) return;
     listTasks({ store, scheduler, collection, req, res, url });
     return;
   }
   if (req.method === 'POST') {
-    await createOrUpdateTask({ store, scheduler, req, res });
+    await createOrUpdateTask({ store, scheduler, req, res, apiToken });
     return;
   }
   sendJson(res, 405, NOT_ALLOWED);
@@ -133,7 +135,7 @@ function listTasks({ store, scheduler, collection, req, res, url }) {
   const status = url.searchParams.get('status') || 'all';
   const query = url.searchParams.get('query') || '';
   const list = store.list({ status, query }).map((t) => ({
-    ...t,
+    ...redactTaskSecrets(t),
     running: scheduler.isRunning(t.id),
     runningSince: scheduler.runningSince(t.id),
   }));
@@ -160,10 +162,12 @@ function listTasks({ store, scheduler, collection, req, res, url }) {
   sendJson(res, 200, payload);
 }
 
-async function createOrUpdateTask({ store, scheduler, req, res }) {
-  if (rejectCrossOrigin(req, res)) return;
-  const { body, error } = await readBody(req, res);
+async function createOrUpdateTask({ store, scheduler, req, res, apiToken }) {
+  if (rejectCrossOrigin(req, res, { apiToken })) return;
+  const { body: rawBody, error } = await readBody(req, res);
   if (error) return;
+  const existing = rawBody.id ? store.get(rawBody.id) : null;
+  const body = existing ? restoreTaskSecrets(rawBody, existing) : rawBody;
   if (!body.title || !body.schedule || !body.prompt) {
     sendJson(res, 400, { ok: false, error: 'Fields title, schedule and prompt are required' });
     return;
@@ -211,7 +215,7 @@ async function createOrUpdateTask({ store, scheduler, req, res }) {
   } else {
     scheduler.pauseTask(task.id);
   }
-  sendJson(res, 200, { ok: true, task });
+  sendJson(res, 200, { ok: true, task: redactTaskSecrets(task) });
 }
 
 /** Merge a create/update payload onto the stored task, if any. */
@@ -249,8 +253,8 @@ function buildTaskRecord(store, body, taskType, parsed) {
 
 // ------------------------------------------------------------ single task
 
-async function handleTaskItem({ store, scheduler, req, res, url, id, action }) {
-  if ((req.method === 'GET' || req.method === 'POST') && action === 'heartbeat') {
+async function handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken }) {
+  if (action === 'heartbeat') {
     handleHeartbeatPing({ store, req, res, taskId: id });
     return;
   }
@@ -260,25 +264,44 @@ async function handleTaskItem({ store, scheduler, req, res, url, id, action }) {
     return;
   }
 
-  if (req.method === 'GET' && action === 'archive') {
-    const limit = parseInt(url.searchParams.get('limit') || '50', 10);
-    const offset = parseInt(url.searchParams.get('offset') || '0', 10);
-    const search = url.searchParams.get('search') || '';
-    const result = typeof store.getArchivedRuns === 'function'
-      ? store.getArchivedRuns(id, { limit, offset, search })
-      : { runs: [], total: 0 };
-    sendJson(res, 200, { ok: true, taskId: id, ...result });
-    return;
-  }
-  if (req.method === 'GET' && action === 'stats') {
-    const stats = typeof store.getTaskStats === 'function' ? store.getTaskStats(id) : null;
-    sendJson(res, 200, { ok: true, taskId: id, stats });
-    return;
-  }
-  if (req.method === 'GET' && (action === 'history' || !action)) {
-    const limit = parseInt(url.searchParams.get('limit') || '20', 10);
-    sendJson(res, 200, { ok: true, history: store.getHistory(id, limit) });
-    return;
+  if (req.method === 'GET') {
+    if (rejectCrossOrigin(req, res, { apiToken })) return;
+    if (action === 'archive') {
+      const limit = parseInt(url.searchParams.get('limit') || '50', 10);
+      const offset = parseInt(url.searchParams.get('offset') || '0', 10);
+      const search = url.searchParams.get('search') || '';
+      const result = typeof store.getArchivedRuns === 'function'
+        ? store.getArchivedRuns(id, { limit, offset, search })
+        : { runs: [], total: 0 };
+      sendJson(res, 200, { ok: true, taskId: id, ...result });
+      return;
+    }
+    if (action === 'stats') {
+      const stats = typeof store.getTaskStats === 'function' ? store.getTaskStats(id) : null;
+      sendJson(res, 200, { ok: true, taskId: id, stats });
+      return;
+    }
+    if (action === 'history') {
+      const limit = parseInt(url.searchParams.get('limit') || '20', 10);
+      sendJson(res, 200, { ok: true, history: store.getHistory(id, limit) });
+      return;
+    }
+    if (!action) {
+      const task = store.get(id);
+      if (!task) {
+        sendJson(res, 404, NOT_FOUND);
+        return;
+      }
+      sendJson(res, 200, {
+        ok: true,
+        task: {
+          ...redactTaskSecrets(task),
+          running: scheduler.isRunning(task.id),
+          runningSince: scheduler.runningSince(task.id),
+        },
+      });
+      return;
+    }
   }
   if (req.method === 'POST') {
     const handled = await handleItemPost({ store, scheduler, req, res, url, id, action });
@@ -303,7 +326,7 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
       return true;
     }
     await scheduler.triggerManualRun(id);
-    sendJson(res, 200, { ok: true, task: store.get(id) });
+    sendJson(res, 200, { ok: true, task: redactTaskSecrets(store.get(id)) });
     return true;
   }
   if (action === 'duplicate') {
@@ -317,7 +340,7 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
     // A copy starts paused: it must never fire on its own before the user
     // reviews the schedule (a duplicated one-shot may point at a past time).
     scheduler.pauseTask(copy.id);
-    sendJson(res, 200, { ok: true, task: copy });
+    sendJson(res, 200, { ok: true, task: redactTaskSecrets(copy) });
     return true;
   }
   if (action === 'pause' || action === 'resume') {
@@ -330,7 +353,7 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
       sendJson(res, 404, NOT_FOUND);
       return true;
     }
-    sendJson(res, 200, { ok: true, task });
+    sendJson(res, 200, { ok: true, task: redactTaskSecrets(task) });
     return true;
   }
   if (action === 'toggle' || (!action && url.searchParams.get('action') === 'toggle')) {
@@ -344,7 +367,7 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
       return true;
     }
     const task = scheduler.toggleTask(id);
-    sendJson(res, 200, { ok: true, task });
+    sendJson(res, 200, { ok: true, task: redactTaskSecrets(task) });
     return true;
   }
   return false;
@@ -381,7 +404,7 @@ async function patchTask({ store, scheduler, req, res, id }) {
     });
     return;
   }
-  sendJson(res, 200, { ok: true, task: result.task });
+  sendJson(res, 200, { ok: true, task: redactTaskSecrets(result.task) });
 }
 
 function deleteTask({ store, scheduler, res, id }) {
@@ -464,7 +487,7 @@ export async function handleExternalTaskRequest({ store, scheduler, req, res, ur
     if (req.method === 'GET') {
       const list = store
         .list({ status: url.searchParams.get('status') || 'all', query: url.searchParams.get('query') || '' })
-        .map((task) => ({ ...task, running: scheduler.isRunning(task.id) }));
+        .map((task) => ({ ...redactTaskSecrets(task), running: scheduler.isRunning(task.id) }));
       sendJson(res, 200, { ok: true, tasks: list });
       return;
     }
@@ -486,7 +509,7 @@ export async function handleExternalTaskRequest({ store, scheduler, req, res, ur
       sendJson(res, 404, NOT_FOUND);
       return;
     }
-    sendJson(res, 200, { ok: true, task: { ...task, running: scheduler.isRunning(id) } });
+    sendJson(res, 200, { ok: true, task: { ...redactTaskSecrets(task), running: scheduler.isRunning(id) } });
     return;
   }
   if (req.method === 'DELETE' && !action) {

package/lib/client.js

@@ -1636,7 +1636,7 @@ window.__ModuleLoader__.load({
           Array.isArray(task.channels) && task.channels.length ? `- channels: ${task.channels.join(', ')}` : null,
           `- prompt: ${String(task.prompt || '').slice(0, 400)}`,
           '',
-          'Ask what should change, then apply it with the cron_update_task tool (read the current state again with cron_get_task if you need the full configuration).',
+          'Ask what should change, then apply it with the cron tool (action: "update", or action: "get" if you need the full configuration).',
           'If the change makes the task execute code (script/node/python/ssh/docker), confirm it with me explicitly before applying it.',
         ].filter(Boolean);
         try {