@goodandready/dsh-cron 0.1.24 → 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
  1. package/README.md +117 -82
  2. package/docs/README.ru.md +133 -85
  3. package/docs/README.zh.md +140 -82
  4. package/docs/design/DESIGN.md +44 -36
  5. package/lib/chat-start.js +2 -2
  6. package/lib/client.js +647 -409
  7. package/lib/http-utils.js +81 -0
  8. package/lib/index.js +342 -384
  9. package/lib/integrations.js +0 -1
  10. package/lib/prompt.js +42 -40
  11. package/lib/runner.js +48 -34
  12. package/lib/scheduler.js +33 -32
  13. package/lib/store.js +1 -1
  14. package/lib/telegram.js +27 -13
  15. package/package.json +1 -1
package/docs/README.zh.md CHANGED
@@ -6,13 +6,13 @@
6
6
 
7
7
  <p align="center">
8
8
  <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>
9
- <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>
9
+ <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>
10
10
  <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>
11
11
  <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>
12
12
  </p>
13
13
 
14
14
  <p align="center">
15
- <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>
15
+ <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>
16
16
  </p>
17
17
 
18
18
  <p align="center">
@@ -25,148 +25,206 @@
25
25
 
26
26
  ---
27
27
 
28
- ## ⚡ 核心定位与解决痛点
28
+ ## ⚡ 概述与问题
29
29
 
30
- 在自主 AI 智能体日常研发与运维工作中，经常需要承担周期性的例行事务：每日早晨生成代码变更简报、定期巡检待处理 PR、监测外部 API 运行健康度，或者定时执行分支清理与自动化测试。在缺乏内置调度器的情况下，开发者通常只能借助外部系统 crontab 脚本、复杂的 Webhook 链路，或者每日人工手动输入指令。
30
+ 自主 AI 智能体经常需要执行周期性任务：生成每日晨报、整理缺陷跟踪、检查 API 健康状态、同步数据库或定期执行 Git 清理。如果 Harness 内没有专用调度器，用户只能依赖外部 crontab 封装、复杂的 webhook 方案或手动干预。
31
31
 
32
- **`@goodandready/dsh-cron`** 是专为 DeepSeek Harness 打造的原生全栈定时调度与后台任务自动化插件。它无缝融合了标准 Cron 表达式、自然语言时间间隔与智能体自主会话执行：
32
+ **`@goodandready/dsh-cron`** 是 DeepSeek Harness 的原生全栈调度与后台自动化插件。它将标准 cron 表达式、自然语言间隔语法与自主智能体执行连接起来：
33
33
 
34
- 1. **可视化任务管理中心**：集成在 DSH 侧边导航栏的时钟按钮（紧邻看板与聊天），提供全功能任务列表抽屉、状态标签过滤、执行历史与快速动作。
35
- 2. **“与 DSH 交互创建”模式**：直接与智能体自然对话，由模型自动梳理需求、配置执行模型并转化为精准的定时任务。
36
- 3. **聊天斜杠指令（`/cron`）**：在对话输入框中即可实现全键盘调度管理（`/cron list`, `/cron add`, `/cron pause`, `/cron run`）。
37
- 4. **智能体原生工具调用（AI Tool Calling）**：赋予智能体 `cron_schedule_task`、`cron_list_tasks` 等工具，支持模型在对话中自主为后续任务安排执行时间表。
38
- 5. **高可靠调度引擎与原子持久化**：基于 `croner` 引擎构建，支持时区配置、友好间隔语法（`every 15m`, `daily`, `weekdays`）、原子写入式 JSON 存储及完整运行审计。
34
+ 1. **完善的可视化任务管理器** —— 侧边栏按钮与功能齐全的面板：查看、筛选、暂停、立即运行和创建任务。
35
+ 2. **交互式“由 DSH 创建”流程** —— 与智能体对话，把高层需求转化为规范的定时任务。
36
+ 3. **自主工具调用** —— 原生 `cron_*` 工具让智能体在会话中自行安排后续执行。
37
+ 4. **健壮的调度器与原子存储** —— 基于 `croner`：间隔别名、一次性延时任务、原子写入、运行历史与成本追踪。
39
38
 
40
39
  ---
41
40
 
42
- ## 🏗️ 架构设计
41
+ ## 🏗️ 架构
43
42
 
44
43
  ```mermaid
45
44
  graph TD
46
- subgraph Client ["前端交互界面 (DSH Web UI)"]
47
- SidebarBtn["侧边栏时钟按钮<br/>(DSH 客户端界面插槽)"]
48
- Overlay["可视化任务管理抽屉<br/>(标签页: 全部, 运行中, 已暂停, 已完成)"]
49
- CreateWithDSH["'与 DSH 交互创建' 弹窗<br/>(模型选择与任务自然语言描述)"]
50
- ManualForm["手动配置任务弹窗<br/>(Cron 表达式, 时区, 执行模型)"]
51
- SlashCmd["斜杠指令解析器<br/>(/cron add, list, pause, run)"]
45
+ subgraph Client ["Web 客户端 (DSH UI)"]
46
+ SidebarBtn["侧边栏时钟按钮<br/>(DSH 客户端插槽)"]
47
+ Overlay["任务管理面板<br/>(标签: 全部 / 活跃 / 暂停 / 已完成)"]
48
+ CreateWithDSH["“由 DSH 创建”对话框<br/>(自然语言任务)"]
49
+ ManualForm["手动任务表单<br/>(cron 表达式、超时、重叠策略、模型)"]
50
+ SettingsCard["设置卡片<br/>(Telegram / Kanban 集成)"]
52
51
  end
53
52
 
54
- subgraph Server ["服务端运行时 (Cordis 插件与服务)"]
55
- HttpRoutes["HTTP REST API 端点<br/>(/dsh-cron/tasks, /models, /chat-start)"]
56
- AgentTools["AI 工具网关<br/>(cron_schedule_task, cron_list_tasks)"]
57
- Scheduler["TaskScheduler 调度引擎<br/>(Croner 实例生命周期管理)"]
58
- Store["原子存储 TaskStore<br/>(安全重写 tasks.json)"]
59
- AgentRunner["智能体会话派发器<br/>(在独立上下文执行 Prompt)"]
53
+ subgraph Server ["服务端 (Cordis 与 DSH 服务)"]
54
+ HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
55
+ AgentTools["工具调用网关<br/>(cron_create_task, cron_list_tasks, ...)"]
56
+ Scheduler["TaskScheduler 引擎<br/>(Croner 实例 + one-shot 定时器)"]
57
+ Store["原子 TaskStore<br/>(tasks.json 原子写入)"]
58
+ AgentRunner["智能体会话调度器<br/>(以指定模型执行提示词)"]
59
+ Notify["通知投递<br/>(Telegram Bot API、dsh-kanban 卡片)"]
60
60
  end
61
61
 
62
62
  SidebarBtn --> Overlay
63
63
  Overlay --> CreateWithDSH
64
64
  Overlay --> ManualForm
65
- CreateWithDSH -->|POST /chat-start| HttpRoutes
65
+ SettingsCard --> HttpRoutes
66
+ CreateWithDSH -->|POST /chat/start| HttpRoutes
66
67
  ManualForm -->|POST /tasks| HttpRoutes
67
- SlashCmd -->|指令分发| HttpRoutes
68
68
  HttpRoutes --> Scheduler
69
69
  AgentTools --> Scheduler
70
70
  Scheduler --> Store
71
- Scheduler -->|周期触发| AgentRunner
71
+ Scheduler -->|按间隔/一次性触发| AgentRunner
72
+ Scheduler --> Notify
72
73
  ```
73
74
 
74
75
  ---
75
76
 
76
- ## ✨ 核心特性深度解析
77
+ ## ✨ 功能与能力
77
78
 
78
- ### 1. 可视化任务管理中心
79
- 点击 DSH 侧边栏的时钟图标即可唤出定时任务全景抽屉：
80
- * **状态过滤标签页**：一键在 **全部 (All)**、**运行中 (Active)**、**已暂停 (Paused)** 和 **已完成 (Completed)** 之间快速切换。
81
- * **快捷操作菜单**：支持即刻手动测试执行（*“立即运行”*）、暂停/恢复调度，以及带有二次确认防误触的安全删除。
82
- * **一键推荐模板**：内置高频工作流预设（*“每日早晨研发简报”*、*“每周代码仓库复盘”*、*“API 探活心跳检测”*）。
83
- * **执行历史记录**：展开任意任务卡片即可查阅过往历次运行时间戳、执行耗时（秒）、完成状态以及智能体生成的完整执行日志。
79
+ ### 1. 可视化任务管理器
80
+ 点击 DSH 侧边栏中的时钟图标（位于“新会话”按钮旁）打开管理面板：
81
+ * **状态过滤标签**：**全部**、**活跃**、**已暂停**、**已完成**。
82
+ * **即时操作**：立即运行（**Run Now**）、暂停/恢复调度、带确认的删除。
83
+ * **一键预设模板**：*每日摘要*、*每周回顾*、*待办监控*。
84
+ * **运行历史**：打开任务卡片查看历史运行 —— 时间、耗时、状态（成功 / 失败 / 超时 / 跳过 / 错过）、输出与错误。
85
+ * **汇总统计栏**：活跃任务数、总运行次数、总 token 消耗与估算美元成本。
84
86
 
85
- ### 2. “与 DSH 交互创建” 智能配置模式
86
- 告别晦涩的手动 Cron 表达式换算：
87
- 1. 点击 **新建 ⌄** ➔ **与 DSH 交互创建**。
88
- 2. 在下拉框中直观选取本次自动化任务使用的模型服务商与模型名称。
89
- 3. 输入任务自然语言意图（例如：*“每个工作日上午 9 点自动扫描仓库中未关闭的 Issue 并汇总至看板”*）。
90
- 4. 插件将自动创建专属智能体会话，注入调度器系统指令，协助生成结构化配置并写入持久化存储。
87
+ ### 2. “由 DSH 创建”对话框
88
+ 无需猜测 cron 语法，用自然语言即可创建任务：
89
+ 1. 点击 **Create ⌄** ➔ **Create with DSH**。
90
+ 2. 描述要自动化的内容（例如：*“每个工作日早上 9 点检查未处理的 PR 并起草评论”*）。
91
+ 3. 插件会创建一个注入了调度器指令的专属智能体会话。智能体会与你确认细节 —— LLM 还是 NO-LLM shell 任务、准确的 cron 表达式、在你的 DSH 安装中可用的经济型模型，以及是否启用“静默规则”（仅在新事件或故障时告警）—— 并在你确认后才通过 `cron_create_task` 工具注册任务。
91
92
 
92
- ### 3. 聊天斜杠指令 (`/cron`)
93
- 极客与键盘流的高效快捷通道：
93
+ ### 3. 智能体工具（Tool Calling）
94
94
 
95
- | 指令 | 语法 | 功能说明 |
96
- |:---|:---|:---|
97
- | `/cron list` | `/cron list` | 列出所有已注册任务的 ID、表达式与当前运行状态 |
98
- | `/cron add` | `/cron add "<时间表>" <提示词>` | 新建任务。示例：`/cron add "every 2h" 检查最新提交并整理日志` |
99
- | `/cron pause` | `/cron pause <id>` | 暂停指定任务的自动触发（保留配置） |
100
- | `/cron resume` | `/cron resume <id>` | 恢复已暂停的任务调度 |
101
- | `/cron run` | `/cron run <id>` | 脱离计划立即触发一次执行 |
102
- | `/cron delete` | `/cron delete <id>` | 从存储中永久注销并删除任务 |
95
+ | 工具 | 说明 |
96
+ |:---|:---|
97
+ | `cron_create_task` | 创建任务：`title`、`schedule`、`prompt`，可选 `type`（`llm`/`script`）、`delivery`、`provider`、`model`、`notifyTelegram`、`onlyOnFailure`、`timeoutSeconds`、`overlapPolicy`、`kanbanMode` |
98
+ | `cron_schedule_task` | `cron_create_task` 的别名，保持与既有提示词兼容 |
99
+ | `cron_list_tasks` | 列出任务的状态、下次运行时间、token 总量与成本估算 |
100
+ | `cron_pause_task` | 暂停调度而不删除配置 |
101
+ | `cron_resume_task` | 恢复已暂停的调度 |
102
+ | `cron_delete_task` | 永久删除任务及其历史 |
103
+ | `cron_run_task` | 触发一次立即的带外运行 |
103
104
 
104
- ### 4. 智能体原生工具调用 (Tool Calling)
105
- 智能体在处理长期复杂项目时，可自主调用调度器工具：
105
+ 会话中模型可进行的调用示例：
106
106
 
107
- * **`cron_schedule_task`**：注册定时任务，支持传入 `name`、`schedule`、`prompt` 及可选 `model` 覆盖。
108
- * **`cron_list_tasks`**：获取已注册任务列表及下一次预定触发时刻。
109
- * **`cron_toggle_task`**：通过 `id` 快速切换任务的启用/停用状态。
107
+ ```
108
+ cron_create_task({
109
+ "title": "Morning digest",
110
+ "schedule": "0 8 * * 1-5",
111
+ "prompt": "Prepare a brief morning digest of active tasks and open tickets.",
112
+ "type": "llm",
113
+ "delivery": "isolated"
114
+ })
115
+ ```
110
116
 
111
- ### 5. 支持的时间表达式语法
112
- 依托底层 `croner` 引擎，全面兼容标准 5 段/6 段 Cron 语法与易读时间间隔：
117
+ ### 4. 调度表达式语法
118
+ 基于 `croner`，支持标准 5 段 cron 表达式与友好的别名：
113
119
 
114
- * `0 9 * * 1-5` — 工作日早晨 09:00
115
- * `*/15 * * * *` — 每隔 15 分钟
116
- * `0 0 * * 0` — 每周日午夜 00:00
117
- * `every 10m` / `every 2h` / `every 30s` — 自然语言时间间隔
118
- * `daily` / `hourly` / `weekly` — 快捷预设别名
120
+ * `0 9 * * 1-5` —— 工作日 09:00
121
+ * `*/15 * * * *` —— 每 15 分钟
122
+ * `0 0 * * 0` —— 每周日午夜
123
+ * `every 10m` / `every 2h` / `every 30s` —— 自然语言间隔
124
+ * `daily` / `hourly` / `weekdays` 快捷方式
125
+ * **一次性任务**：`at: 2026-09-05T15:00:00Z`（精确 ISO 时间戳）或相对延时 `in 20m` / `in 2h`（也接受 `через 15 минут` 之类的俄语输入）。一次性任务在单次运行后自动转为 `completed`，显示在 **已完成** 标签下。
119
126
 
120
- ---
127
+ ### 5. Telegram 通知与投递路由
128
+ 通过与 Telegram Bot API 的直接集成，将执行报告与错误跟踪推送到你的即时通讯工具：
129
+
130
+ * **自动获取或自定义凭据** —— 在设置对话框中输入自己的 `botToken` 与 `chatId`，或让插件从 DSH `settings.yaml` 的 `dsh-messenger-gateway` 段尽力继承默认值。
131
+ * **仅失败时通知** —— 全局或按任务启用 `onlyOnFailure`。成功运行保持静默；失败（`error` 或 `timeout` 状态）会发送带错误跟踪的告警。
132
+ * **Markdown 排版** —— 消息包含状态徽标（✅ / ❌）、耗时、调度描述与等宽输出块；动态值会被转义，特殊字符不会破坏消息。
133
+ * **测试发送按钮** —— 在安排关键任务前现场验证 Telegram 连通性。
134
+
135
+ ### 6. Kanban 集成与成本统计
136
+ * **自动创建 Kanban 卡片** —— 当 `kanbanMode` 为 `on_failure` 或 `always` 时，插件在 `dsh-kanban` 中创建卡片（`on_failure` → `error`/`timeout` 时进入 *Backlog*；`always` → 完成后进入 *Done*/*Backlog*）。
137
+ * **Token 与执行成本计量** —— 按运行与任务统计 token 消耗（输入、输出、缓存读取），基于内置价格表估算美元成本，并提供汇总分析栏。
138
+
139
+ ### 7. 重叠策略与执行超时
140
+
141
+ * **执行超时（`timeoutSeconds`）** —— 达到限制后，shell 子进程通过 abort 信号立即终止，智能体会话被释放以停止消耗 token。默认 `1800`（30 分钟）。
142
+ * **重叠策略（`overlapPolicy`）** —— 上一次运行尚未结束时再次触发调度时的行为：
143
+ * **`skip`**（默认）：丢弃重叠的运行，在历史中记录 `skipped`；
144
+ * **`queue`**：将下一次运行排队，当前任务完成后自动开始；
145
+ * **`replace`**：通过 `AbortController` 中止当前运行并启动新的执行。
146
+
147
+ 如果守护进程在计划时刻处于离线状态，启动时该次运行会被记录为 `missed`，历史空档始终可见。
121
148
 
122
- ## 📦 快速安装
149
+ ---
123
150
 
124
- 通过 DeepSeek Harness CLI 安装：
151
+ ## 📦 安装
125
152
 
126
153
  ```bash
127
154
  dsh plugin --profile web add @goodandready/dsh-cron
128
155
  ```
129
156
 
130
- 重启 DSH 并刷新浏览器工作区。
157
+ 重启 DeepSeek Harness 实例并刷新浏览器。
131
158
 
132
159
  ---
133
160
 
134
- ## ⚙️ 配置指南 (`settings.yaml`)
161
+ ## ⚙️ 配置（`settings.yaml`）
135
162
 
136
- 可在 `settings.yaml` 中配置，或在 Web UI 设置面板中调整：
163
+ 可以在 `settings.yaml` 中配置，也可以通过 DSH 中的插件设置卡片交互式管理：
137
164
 
138
165
  ```yaml
139
166
  # settings.yaml
140
167
  dsh-cron:
141
- storagePath: "data/cron-tasks.json"
142
- maxHistoryEntries: 50
143
- defaultTimezone: "Asia/Shanghai"
144
- defaultModel: ""
145
- notifyOnFailure: true
168
+ botToken: "" # Telegram Bot API 令牌（保密字段）
169
+ chatId: "" # 接收报告的 Telegram chat ID
170
+ notifyTelegram: false # 全局投递所有任务的报告
171
+ onlyOnFailure: false # 仅失败时投递报告
172
+ kanbanBaseUrl: "http://127.0.0.1:3000" # dsh-kanban HTTP API 基础地址
146
173
  ```
147
174
 
148
- ### 配置参数参考表
175
+ ### 配置参数
149
176
 
150
- | 参数名 | 类型 | 默认值 | 功能说明 |
177
+ | 参数 | 类型 | 默认值 | 说明 |
151
178
  |:---|:---|:---|:---|
152
- | `storagePath` | `string` | `"data/cron-tasks.json"` | 定时任务与运行历史原子持久化文件的存储路径 |
153
- | `maxHistoryEntries` | `number` | `50` | 每个任务卡片保留的最大历史运行记录条数 |
154
- | `defaultTimezone` | `string` | `"UTC"` | 计算 Cron 触发时刻所使用的默认 IANA 时区（如 `"Asia/Shanghai"`） |
155
- | `defaultModel` | `string` | `""` | 未显式指定模型时的全局后备模型标识 |
156
- | `notifyOnFailure` | `boolean` | `true` | 当后台定时任务执行失败时是否在 Web UI 弹出告警徽标 |
179
+ | `botToken` | `string` | `""` | Telegram Bot API 令牌。留空时插件会尽力继承 DSH 设置中 `dsh-messenger-gateway` 配置的机器人。保密字段：界面只显示掩码值 |
180
+ | `chatId` | `string` | `""` | 接收报告的 Telegram chat ID。留空时回退到 `dsh-messenger-gateway` 的第一个允许会话 |
181
+ | `notifyTelegram` | `boolean` | `false` | 全局开关：向 Telegram 投递运行报告 |
182
+ | `onlyOnFailure` | `boolean` | `false` | 全局开关：仅对 `error`/`timeout` 运行投递报告 |
183
+ | `kanbanBaseUrl` | `string` | `"http://127.0.0.1:3000"` | 用于自动卡片的 `dsh-kanban` HTTP API 基础地址 |
184
+
185
+ 说明：
186
+
187
+ * 运行历史上限为**每任务 50 条**（固定）；每条记录最多保留 4000 字符输出。
188
+ * 任务在**服务器本地时区**执行；cron 表达式由 `croner` 按主机时钟计算。
189
+ * 任务持久化在 DSH 数据目录（`cron/tasks.json`），重启后保留；启动时会检测错过的一次性任务。
157
190
 
158
191
  ---
159
192
 
160
- ## 🧪 测试与校验
193
+ ## 🔌 HTTP API 参考
161
194
 
162
- 运行全部自动化单元测试：
195
+ 所有端点由 DSH Web 服务器在 `/dsh-cron/` 下提供。读端点对本地 UI 开放；**变更端点拒绝跨域请求**且请求体最大 1 MB。通过 HTTP 创建 `script` 类型任务还需要 `x-dsh-cron-confirm: script` 请求头 —— 伪造的跨站请求无法附加该头。
196
+
197
+ | 方法 | 路径 | 说明 |
198
+ |:---|:---|:---|
199
+ | `GET` | `/dsh-cron/tasks` | 任务列表；查询参数 `status`（`all/active/paused/completed`）、`query`（子串搜索）。返回任务、推荐模板与汇总统计 |
200
+ | `POST` | `/dsh-cron/tasks` | 创建或更新任务（携带 `id` 时为更新）。需要 `title`、`schedule`、`prompt` |
201
+ | `GET` | `/dsh-cron/tasks/:id/history` | 运行历史，`?limit=20` |
202
+ | `POST` | `/dsh-cron/tasks/:id/run` | 立即手动运行 |
203
+ | `POST` | `/dsh-cron/tasks/:id/pause` | 暂停调度 |
204
+ | `POST` | `/dsh-cron/tasks/:id/resume` | 恢复调度 |
205
+ | `POST` | `/dsh-cron/tasks/:id/toggle` | 切换活跃/暂停 |
206
+ | `PATCH` | `/dsh-cron/tasks/:id` | 部分更新（仅白名单字段：`title`、`schedule`、`prompt`、`type`、`delivery`、`provider`、`model`、通知/超时/重叠/Kanban 设置、`status`、`oneShot`） |
207
+ | `DELETE` | `/dsh-cron/tasks/:id` | 删除任务 |
208
+ | `GET` | `/dsh-cron/models` | 列出 LLM 提供方；`?provider=<id>` 列出模型 |
209
+ | `POST` | `/dsh-cron/chat/start` | 启动带任务配置指令的“由 DSH 创建”智能体会话 |
210
+ | `GET` | `/dsh-cron/settings` | 客户端安全设置（令牌掩码显示） |
211
+ | `POST` | `/dsh-cron/settings` | 更新集成设置 |
212
+ | `POST` | `/dsh-cron/telegram/test` | 发送 Telegram 测试消息 |
213
+ | `POST` | `/dsh-cron/kanban/test` | 创建 Kanban 连通性测试卡片 |
214
+ | `*` | `/dsh-cron/action/:id/:action` | 任务操作路由的兼容别名（`run`、`toggle`、`delete`、`history`） |
215
+
216
+ ---
217
+
218
+ ## 🧪 测试
163
219
 
164
220
  ```bash
165
221
  npm test
166
222
  ```
167
223
 
224
+ 测试覆盖调度表达式解析、调度器引擎、原子存储、HTTP 辅助函数、通知与工具契约。
225
+
168
226
  ---
169
227
 
170
- ## 📄 开源许可证
228
+ ## 📄 许可证
171
229
 
172
230
  MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
package/docs/design/DESIGN.md CHANGED
@@ -3,60 +3,68 @@
3
3
  ## Product / Purpose
4
4
  - Назначение: Интегрированный планировщик cron-задач и фоновой автоматизации для DeepSeek Harness. Позволяет запускать агентские сессии по расписанию, выполнять автоматические проверки и предоставлять визуальный интерфейс управления задачами.
5
5
  - Аудитория: Пользователи и операторы DeepSeek Harness, автоматизирующие периодические процессы (утренние сводки, проверка тикетов, мониторинг серверов).
6
- - Статус: In Development, v0.1.0, публичный npm-пакет @goodandready/dsh-cron.
6
+ - Статус: Active, публичный npm-пакет @goodandready/dsh-cron (текущая линия 0.1.x → 0.2.0).
7
7
 
8
8
  ## User Surfaces
9
- - Web/UI:
10
- - Экран «Запланированные задачи» (полноэкранный оверлей в центральной колонке интерфейса DSH, аналогично dsh-kanban через mountOverlay/mountBoard).
11
- - Кнопка вызова в боковой панели (sidebar-entry) рядом с новой сессией и канбаном.
12
- - Кнопка «Создать ⌄» в правом верхнем углу с дропдауном:
9
+ - Web/UI:
10
+ - Экран «Запланированные задачи» (полноэкранный оверлей в центральной колонке интерфейса DSH, аналогично dsh-kanban).
11
+ - Кнопка вызова в боковой панели (sidebar-entry) рядом с новой сессией + иконка в шапке сессии (utilities slot).
12
+ - Кнопка «Создать ⌄» с дропдауном:
13
13
  - 💬 «Создать с DSH» (запуск интерактивного диалога постановки задачи агенту).
14
- - ✏️ «Настроить вручную» (модальное окно с формой параметров расписания, промпта, типа запуска).
15
- - Табы фильтрации: «Все», «Активные», «Приостановленные», «Завершено».
16
- - Поисковая строка: «Поиск запланированных задач».
17
- - Карточки задач: статус-иконка (play/pause/done), название, расписание (человекочитаемое + raw cron), контекстные действия (пауза/старт, запуск сейчас, редактировать, удалить, логи).
18
- - Блок «Рекомендации»: готовые шаблоны (Ежедневная сводка, Еженедельный обзор, Мониторинг) в один клик.
19
- - Карточка настроек в слоте settings.plugin.item (namespace dsh-cron).
20
- - Chat / Slash Commands:
21
- - Команда /cron для быстрого создания или просмотра статуса запланированных задач прямо в чате.
22
- - LLM Tools: cron_schedule_task, cron_list_tasks, cron_toggle_task, cron_get_history.
23
- - API: HTTP эндпоинты /dsh-cron/* (tasks, toggle, run-now, history, templates).
14
+ - ✏️ «Настроить вручную» (модальная форма: тип, расписание, таймаут, overlap, промпт, модель, уведомления).
15
+ - Табы фильтрации: «Все», «Активные», «На паузе», «Завершённые».
16
+ - Поисковая строка; сводная статистика (активные задачи, запуски, токены, стоимость).
17
+ - Карточки задач: статус-переключатель, название, расписание (человекочитаемое + raw cron), действия (запуск, редактирование, удаление).
18
+ - Блок «Рекомендуемые задачи»: готовые шаблоны (Daily digest, Weekly review, Follow-up monitor) в один клик.
19
+ - Карточка настроек в слоте settings.plugin.item, key = namespace `dsh-cron`; запасной путь — settings.section.
20
+ - LLM Tools: cron_create_task (+ alias cron_schedule_task), cron_list_tasks, cron_pause_task, cron_resume_task, cron_delete_task, cron_run_task.
21
+ - API: HTTP эндпоинты /dsh-cron/* (tasks, models, chat/start, settings, telegram/test, kanban/test, tasks/:id/actions, legacy action/:id/:action). Мутирующие эндпоинты отклоняют cross-origin запросы; script-задачи по HTTP требуют заголовок x-dsh-cron-confirm.
22
+ - Chat / Slash Commands: отсутствуют (ранее заявленные /cron-команды не были реализованы и удалены из документации; решение 2026-09-09).
24
23
 
25
24
  ## Visual Direction
26
- - Атмосфера: Строгий утилитарный темный/светлый интерфейс в нативном стиле DeepSeek Harness (дизайн как на утвержденных скриншотах пользователя).
27
- - Использование нативных токенов темы DSH: --dsw-alias-bg-layer-*, --dsw-alias-border-l2, --dsw-alias-label-primary, --dsw-alias-label-secondary.
28
- - Иерархия: читаемые карточки с четким акцентом на статусе и времени следующего запуска.
25
+ - Атмосфера: Строгий утилитарный интерфейс в нативном стиле DeepSeek Harness.
26
+ - Использование нативных токенов темы DSH: --dsw-alias-bg-base, --dsw-alias-bg-layer-*, --dsw-alias-border-l1/l2, --dsw-alias-label-primary/secondary/tertiary, --dsw-alias-interactive-bg-hover.
27
+ - Семантические статусы объявляются один раз через plugin-переменные --dsh-cron-success/danger/info/accent/warning (токен ядра при наличии, иначе фолбэк); рассыпанных hex в инлайн-стилях нет.
28
+ - Иерархия: читаемые карточки с чётким акцентом на статусе и времени следующего запуска.
29
29
 
30
30
  ## Foundations
31
31
  - Семантические цвета статусов:
32
- - Зеленый/активный: рабочее расписание.
32
+ - Зелёный/активный: рабочее расписание, успех.
33
33
  - Серый/приостановленный: на паузе.
34
- - Синий/информационный: шаблоны и рекомендации.
35
- - Красный: ошибка выполнения последнего запуска.
36
- - Доступность: aria-label для всех иконок, управление клавиатурой в модальных окнах, семантические формы.
34
+ - Синий/информационный: шаблоны, Shell-тип, Telegram-акценты.
35
+ - Красный: ошибка/таймаут последнего запуска.
36
+ - Фиолетовый: разовая (one-shot) задача; жёлтый: skipped/missed.
37
+ - Доступность: aria-label у иконок и действий, роль button + управление с клавиатуры (Enter/Space) для строк списков, Escape закрывает модалки, autofocus первого поля формы.
38
+ - Язык: канонические строки — английские (словарь STRINGS.en, namespace dsh-cron, регистрация через ctx.locale.register); русский и другие языки предоставляет translation-плагин в рантайме.
37
39
 
38
40
  ## Components And States
39
41
  - Components:
40
42
  - CronSidebarButton: кнопка в левом сайдбаре DSH.
41
- - CronScreen: основной оверлей со списком, табами и рекомендациями.
43
+ - CronScreen: основной оверлей со списком, табами, статистикой и рекомендациями.
42
44
  - CreateDropdown: всплывающее меню выбора способа создания.
43
- - ManualTaskModal: модальная форма создания/редактирования.
44
- - TaskItem: строка задачи с переключателем состояния и меню действий.
45
+ - ManualTaskModal: модальная форма создания/редактирования (вкладки «Параметры» / «История запусков»).
46
+ - SettingsModal: настройки Telegram/Kanban с тестами доставки.
47
+ - TaskItem: строка задачи с переключателем состояния и действиями.
45
48
  - RecommendationCard: плашка с готовым шаблоном.
46
49
  - CronSettingsCard: карточка параметров плагина в настройках.
47
50
  - States:
48
- - Loading: скелетон списка при загрузке.
49
- - Empty: дружелюбный пустой экран с предложением создать первую задачу или выбрать из рекомендаций.
50
- - Error: баннер с ошибкой и кнопкой повтора.
51
+ - Loading: индикатор загрузки списка/истории.
52
+ - Empty: дружелюбный пустой экран со списком рекомендаций.
53
+ - Error: баннер с ошибкой и кнопкой повтора (в панели), статус-баннеры в модалках.
54
+ - Success: статус-баннеры тестов доставки, «✓ Сохранено».
55
+ - Опасные действия: удаление задачи — через confirm(); переключение типа на script по HTTP требует confirm-заголовок.
51
56
 
52
57
  ## User Flows
53
- 1. Создание через DSH-чат: пользователь пишет «напоминай каждый день в 9 утра...» -> агент вызывает тул cron_schedule_task -> задача сохраняется и появляется на экране.
54
- 2. Создание через команду: пользователь вводит /cron add 0 9 * * 1-5 <промпт>.
55
- 3. Создание вручную: клик по кнопке сайдбара -> клик «Создать ⌄» -> «Настроить вручную» -> заполнение формы -> сохранение.
56
- 4. Выполнение по крону: срабатывает таймер croner -> запуск сессии агента или команды -> запись в историю -> доставка результата.
58
+ 1. Создание через DSH-чат: «напоминай каждый день в 9 утра...» → «Создать с DSH» → агент уточняет тип (LLM/NO-LLM), расписание, модель, Silent Rule → после подтверждения вызывает cron_create_task → задача появляется на экране.
59
+ 2. Создание вручную: кнопка сайдбара → «Создать ⌄» → «Настроить вручную» → форма → сохранение.
60
+ 3. Выполнение по расписанию: croner/таймер one-shot → запуск shell-команды или изолированной агентской сессии → запись в историю → доставка отчёта (Telegram/Kanban по настройкам).
61
+ 4. Разбор инцидента: история запусков в карточке задачи → статус, длительность, вывод/ошибка.
57
62
 
58
63
  ## Locked Design Decisions
59
- - 2026-09-08 — Пакет надежности ядра (v0.1.24): буфер shell-задач 10МБ, bash/env, атомарное сохранение с PID, автоочистка сессий агента ephemeral/internal, аудит пропущенных запусков при рестарте (missed), фоновый поллинг UI (8с).
60
- - 2026-09-03 — Публичный скоуп @goodandready/dsh-cron.
61
- - 2026-09-03 — Оверлей открывается через mountSidebarEntry и mountScreen аналогично dsh-kanban.
62
- - 2026-09-03 — Двойная кнопка «Создать ⌄» («Создать с DSH» и «Настроить вручную»).
64
+ - 2026-09-09 — Пакет надёжности ядра (v0.1.24): буфер shell-задач 10МБ, атомарное сохранение с PID, аудит пропущенных запусков при рестарте (missed), фоновый поллинг UI (8с).
65
+ - 2026-09-03 — Публичный скоуп @goodandready/dsh-cron; оверлей через mountSidebarEntry/mountScreen аналогично dsh-kanban; двойная кнопка «Создать ⌄».
66
+ - 2026-09-09 — Слот карточки настроек: settings.plugin.item с key/namespace `dsh-cron` (совпадение с серверной регистрацией); settings.section — только запасной путь. Причина: контракт слота настроек (#85).
67
+ - 2026-09-09 — Английский — канонический язык строк; словарь STRINGS.en регистрируется в ctx.locale; русский — через translation-плагин. Причина: стандарт DSH-плагинов (#87).
68
+ - 2026-09-09 — Same-origin проверка мутирующих эндпоинтов, лимит тела 1 МБ, confirm-заголовок для script-задач. Причина: закрытие CSRF→RCE поверхности (#86).
69
+ - 2026-09-09 — Стилевая изоляция: динамические <style> с data-dsh-plugin="dsh-cron"; цвета только через токены темы + единый блок plugin-переменных. Причина: защита от очистки стилей соседями и поддержка светлой темы (#91).
70
+ - 2026-09-09 — /cron slash-команды удалены из документации (не были реализованы); при появлении продукта — отдельная feature-issue и согласование. Причина: документация = истина (#84).
package/lib/chat-start.js CHANGED
@@ -8,13 +8,13 @@ export async function chatStartHandler(ctx, req, res, parseJsonBody, sendJson, r
8
8
  const body = await parseJsonBody(req);
9
9
  const userPrompt = (body.prompt || '').trim();
10
10
  if (!userPrompt) {
11
- sendJson(res, 400, { ok: false, error: 'Текст задачи не может быть пустым' });
11
+ sendJson(res, 400, { ok: false, error: 'Prompt text must not be empty' });
12
12
  return;
13
13
  }
14
14
 
15
15
  const agents = ctx.agents;
16
16
  if (!agents || typeof agents.create !== 'function') {
17
- sendJson(res, 500, { ok: false, error: 'Служба agents недоступна в DSH' });
17
+ sendJson(res, 500, { ok: false, error: 'The agents service is unavailable in DSH' });
18
18
  return;
19
19
  }
20
20