@mzzsfy/dsh-cron-board 0.2.0 → 0.3.0

package/README.md

@@ -1,27 +1,27 @@
 # @mzzsfy/dsh-cron-board
 
-轻量级定时任务看板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时在指定时间段向 dsh 会话发起任务,支持「每次新建会话」或「固定同一会话」)。
+轻量级定时任务看板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时向 dsh 会话投递任务,投递即终态,支持「每次新建会话」或「固定同一会话」)。
 
-设计文档见仓库 `docs/progress/feat-cron-board.md`(架构 / 数据模型 / API 契约 / BDD 场景 / 里程碑)。
+设计文档见仓库 `docs/progress/debug-fix-cron-board-delivery-semantics.md`(近期语义收敛决策记录)。
 
 ## 功能
 
-- **看板**:任务卡片列表(状态色/下次触发相对时间/启停开关/立即运行/编辑/删除),新建编辑模态支持 shell 与会话两类任务、cron 预设与服务端实时预览(人话摘要 + 下三次触发)
+- **看板**:任务卡片列表(状态色/下次触发相对时间/启停开关/立即运行/编辑/删除),新建编辑模态为调度构建器布局:类型/会话模式/调度频率统一分段组件,结构化频率(每天/每周/工作日/固定间隔)自动生成表达式(反解不出即自定义手输),即将执行时刻 chips 为服务端实时预览
 - **环境变量**:集中管理,值打码展示,多值(同名展开笛卡尔积,组合数超出 20 截断并告警),dotenv 文本导入(预览/追加/覆盖)与导出
-- **会话任务**:fresh 每次新建会话;pinned 固定会话(忙时跳过,会话丢失自动重建并回写);允许时段(支持跨零点)外按策略跳过或顺延
-- **调度**:croner 解析,停机期间错过不补跑(misfire 即跳过),孤儿运行恢复,全局与任务级并发闸门,超时收尾
+- **会话任务**:投递即终态(crontab 语义,执行状态归会话本身);fresh 每次新建会话;pinned 固定会话(忙时跳过,会话被删除或归档自动重建并回写,首跑自动绑定);按 workdir 自动挂载宿主分组,界面分组内可见;执行预设可选(Agent Preset,缺省跟随宿主默认,dsh-im 同构)
+- **调度**:croner 解析,停机期间错过不补跑(misfire 即跳过),孤儿运行恢复,全局与任务级并发闸门;shell 任务超时收尾(会话任务无超时语义);单次运行开关(runOnce,任意一次真实运行入队后自动停用任务)
 - **日志**:每任务每运行独立日志文件,面板查看与清空,按任务保留条数裁剪(按文件修改时间)
 
 ## 路由
 
-前缀 `/api/cron-board`(envs / jobs / runs / status / cron/preview),REST 风格,中文业务错误透传。
+前缀 `/api/cron-board`(envs / jobs / runs / status / cron/preview / agent-presets),REST 风格,中文业务错误透传。
 
 ## 界面挂载
 
 挂载权交给用户,运行期不自动切换:
 
 - **默认:主界面**。无论是否安装 dsh-better-sidebar,看板始终在主界面(原生侧栏「定时任务」入口 + 中心列看板,激活时隐藏会话区,面板互斥)
-- **手动移入**:设置>插件 页「定时任务」卡片提供「看板移入 better-sidebar 侧边栏」开关;开启即注册扩展槽 tab(显式 openTab 落入工作台)并拆除主界面形态
+- **手动移入**:设置>插件 页「定时任务」卡片(官方 PluginCard 形制:折叠卡壳,cb-pc 镜像)提供「看板移入 better-sidebar 侧边栏」开关;开启即注册扩展槽 tab(显式 openTab 落入工作台)并拆除主界面形态
 - **不自动回退**:移入后页签关闭/类型禁用均不再自动返回主界面;把开关关掉即回到主界面形态(轮询感知,约一个 tick 周期内生效)
 - **开关可用性**:已安装 better-sidebar 时可切换;未安装时开关呈禁用态仅展示(保持主界面,无副作用)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-cron-board",
   "description": "轻量级定时任务看板:环境变量集中管理与定时任务调度,执行体支持本地脚本与 dsh 会话任务",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/api.mjs

@@ -19,9 +19,7 @@ export const MESSAGES = {
   commandRequired: '任务命令不能为空',
   badKind: '任务类型不合法',
   badSessionMode: '会话模式仅支持 fresh 或 pinned',
-  badOnMiss: '窗口外策略仅支持 skip 或 defer',
-  windowPairRequired: '窗口起止时间必须成对填写',
-  badWindowFormat: '窗口时间格式须为 HH:mm',
+  badAgentPreset: '执行预设 ID 仅限小写字母、数字与连字符',
   jobNotFound: '任务不存在',
   runNotFound: '运行记录不存在',
   sessionDisabled: '宿主会话服务不可用,会话任务通道已禁用',
@@ -111,26 +109,22 @@ export function parseEnvText(text) {
 }
 
 // 任务字段校验与规范化:非法即业务错误;返回可落库字段集
-const WINDOW_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/
 
-// 会话任务专有字段(设计 §3.2 job.session 子对象);窗口 start/end 须成对且为 HH:mm
+// 会话任务专有字段(设计 §3.2 job.session 子对象);agentPreset 形态对齐宿主预设目录 id(dsh-im 同款校验)
+const AGENT_PRESET_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+
+// 会话任务专有字段(设计 §3.2 job.session 子对象)
 function normalizeSession(body) {
   if (body.kind !== 'session') return undefined
   const raw = body.session && typeof body.session === 'object' ? body.session : {}
   if (raw.mode !== undefined && raw.mode !== 'fresh' && raw.mode !== 'pinned') throw new Error(MESSAGES.badSessionMode)
-  if (raw.onMiss !== undefined && raw.onMiss !== 'skip' && raw.onMiss !== 'defer') throw new Error(MESSAGES.badOnMiss)
-  const windowStart = raw.windowStart ? String(raw.windowStart).trim() : ''
-  const windowEnd = raw.windowEnd ? String(raw.windowEnd).trim() : ''
-  if (windowStart === '' !== (windowEnd === '')) throw new Error(MESSAGES.windowPairRequired)
-  for (const window of [windowStart, windowEnd]) {
-    if (window !== '' && !WINDOW_PATTERN.test(window)) throw new Error(MESSAGES.badWindowFormat)
-  }
+  const agentPreset = typeof raw.agentPreset === 'string' ? raw.agentPreset.trim() : ''
+  if (agentPreset !== '' && !AGENT_PRESET_PATTERN.test(agentPreset)) throw new Error(MESSAGES.badAgentPreset)
   return {
     mode: raw.mode === 'pinned' ? 'pinned' : 'fresh',
     pinnedSessionId: typeof raw.pinnedSessionId === 'string' ? raw.pinnedSessionId.trim() : '',
-    windowStart,
-    windowEnd,
-    onMiss: raw.onMiss === 'defer' ? 'defer' : 'skip',
+    // 空串 = 跟随宿主当前默认(driver 建会话时对空值省略字段)
+    agentPreset,
   }
 }
 
@@ -143,7 +137,6 @@ function normalizeJob(body) {
   if (kind === 'shell' && command === '') throw new Error(MESSAGES.commandRequired)
   const schedule = typeof body.schedule === 'string' ? body.schedule.trim() : ''
   assertValidSchedule(schedule)
-  const timeoutMs = Number.isInteger(body.timeoutMs) && body.timeoutMs > 0 ? body.timeoutMs : DEFAULT_TIMEOUT_MS
   const normalized = {
     name,
     kind,
@@ -151,11 +144,17 @@ function normalizeJob(body) {
     prompt: typeof body.prompt === 'string' ? body.prompt : '',
     workdir: typeof body.workdir === 'string' ? body.workdir.trim() : '',
     schedule,
-    timeoutMs,
     enabled: body.enabled !== false,
     session: normalizeSession(body),
   }
   if (normalized.session === undefined) delete normalized.session
+  // 会话任务投递即终态无超时语义,timeoutMs 仅为 shell 真实执行保留
+  if (kind === 'shell') {
+    normalized.timeoutMs = Number.isInteger(body.timeoutMs) && body.timeoutMs > 0 ? body.timeoutMs : DEFAULT_TIMEOUT_MS
+  }
+  if (normalized.session === undefined) delete normalized.session
+  // 单次运行:真实运行入队即禁用(executor dispatch 承担),缺省关闭
+  normalized.runOnce = body.runOnce === true
   // 任务级并发上限:合法正整数才落库,缺省走全局闸门(executor min 规则)
   if (Number.isInteger(body.concurrency) && body.concurrency > 0) normalized.concurrency = body.concurrency
   // nextRunAt:调用方可显式指定(导入任务保留原状态 / 测试注入到期时刻),缺省按 schedule 计算
@@ -165,7 +164,7 @@ function normalizeJob(body) {
   return normalized
 }
 
-export function createApi({ store, logger, executor, scheduler, periodic, sessionState, readSidebarTab, updateUiSettings, logSystem }) {
+export function createApi({ store, logger, executor, scheduler, periodic, sessionState, readSidebarTab, updateUiSettings, getAgentPresets, logSystem }) {
 
   const routes = [
     {
@@ -311,6 +310,33 @@ export function createApi({ store, logger, executor, scheduler, periodic, sessio
         sendJson(res, 200, { summary: summarizeCron(schedule), nextAt: nextRunsOf(schedule, 3) })
       },
     },
+    {
+      method: 'GET',
+      segments: ['agent-presets'],
+      handler: async ({ res }) => {
+        // 目录来自宿主 agentPresets 服务(dsh-im 同构);服务缺失或异常回空目录,前端仅展示「跟随宿主默认」
+        const catalog = { defaultId: '', items: [] }
+        try {
+          const service = getAgentPresets ? getAgentPresets() : undefined
+          if (service && typeof service.list === 'function') {
+            const listed = await service.list()
+            const seen = new Set()
+            for (const entry of Array.isArray(listed) ? listed : []) {
+              const row = typeof entry === 'string' ? { id: entry } : entry
+              const id = row && typeof row.id === 'string' ? row.id.trim() : ''
+              if (id === '' || !AGENT_PRESET_PATTERN.test(id) || seen.has(id) || row.broken !== undefined) continue
+              seen.add(id)
+              const label = typeof row.name === 'string' && row.name.trim() ? row.name.trim().slice(0, 128) : id
+              catalog.items.push({ id, label })
+            }
+            if (typeof service.defaultId === 'string' && AGENT_PRESET_PATTERN.test(service.defaultId.trim())) {
+              catalog.defaultId = service.defaultId.trim()
+            }
+          }
+        } catch { /* 目录降级为空,不阻断任务表单 */ }
+        sendJson(res, 200, catalog)
+      },
+    },
     {
       method: 'GET',
       segments: ['jobs'],