@mzzsfy/dsh-cron-board 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @mzzsfy/dsh-cron-board
+
+轻量级青龙面板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时在指定时间段向 dsh 会话发起任务,支持「每次新建会话」或「固定同一会话」)。
+
+设计文档见仓库 `docs/progress/feat-cron-board.md`(架构 / 数据模型 / API 契约 / BDD 场景 / 里程碑)。
+
+## 功能
+
+- **看板**:任务卡片列表(状态色/下次触发相对时间/启停开关/立即运行/编辑/删除),新建编辑模态支持 shell 与会话两类任务、cron 预设与服务端实时预览(人话摘要 + 下三次触发)
+- **环境变量**:集中管理,值打码展示,多值(同名展开笛卡尔积,组合数超出 20 截断并告警),dotenv 文本导入(预览/追加/覆盖)与导出
+- **会话任务**:fresh 每次新建会话;pinned 固定会话(忙时跳过,会话丢失自动重建并回写);允许时段(支持跨零点)外按策略跳过或顺延
+- **调度**:croner 解析,停机期间错过不补跑(misfire 即跳过),孤儿运行恢复,全局与任务级并发闸门,超时收尾
+- **日志**:每任务每运行独立日志文件,面板查看与清空,按任务保留条数裁剪(按文件修改时间)
+
+## 路由
+
+前缀 `/api/cron-board`(envs / jobs / runs / status / cron/preview),REST 风格,中文业务错误透传。
+
+## 界面挂载
+
+三形态自适应,运行时自动切换:
+
+| 场景 | 形态 |
+|---|---|
+| 未安装 dsh-better-sidebar | 主界面:原生侧栏「定时任务」入口 + 中心列看板(激活时隐藏会话区,面板互斥) |
+| 已安装且当前会话打开了「定时任务」页签 | 扩展槽:better-sidebar tab 承载看板,主界面形态拆除 |
+| 已安装但页签未打开(未开过 / 被用户关闭 / 类型在 side card 设置中被禁用) | 主界面形态接管 |
+
+页签开关实时联动(subscribeState),无需刷新;扩展槽缺失时主界面形态即唯一入口。
+
+## 配置
+
+设置页「定时任务」分区(`cron-board` 命名空间),四项均即时生效:
+
+| 配置项 | 说明 | 默认值 |
+|---|---|---|
+| `tickSeconds` | 调度轮询周期(秒,最小 5),变更后自动按新周期重建定时器 | 30 |
+| `maxConcurrent` | 全局同时运行的执行单元上限 | 2 |
+| `logKeepPerJob` | 每任务保留的运行日志份数(超出按文件修改时间裁剪) | 200 |
+| `maskEnvInPrompt` | 会话任务投递文本中环境变量值打码 | 关 |
+
+## 依赖
+
+- `croner`:cron 表达式解析与触发点计算
+- 宿主服务:settings / timer(软依赖)、webServer、sessionController(硬依赖,cordis 门控——缺失时插件整体不激活,含脚本任务)
+
+## 开发
+
+```sh
+node scripts/dev-link.mjs dsh-cron-board   # 挂载工作副本到 profile
+cd packages/dsh-cron-board
+node --test "test/*.test.mjs"              # 测试
+```
+
+注意:插件新增进入 profile bundles(`dsh plugin add`)后需 dsh 重启一次完成首装载;此后工作副本改动经 dev-link HMR 热重载。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-cron-board 打包补丁:将定时任务面板插件以单条目注入 profile 根。由 `dsh plugin add @mzzsfy/dsh-cron-board` 应用;
+# 条目 id 指向本插件宿主半区,/api/cron-board/* 路由由此宿主条目 provide,client 半区随宿主条目进入客户端模块表。
+- insert:
+    - id: cron-board
+      name: '@mzzsfy/dsh-cron-board'

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mzzsfy/dsh-cron-board",
+  "description": "轻量级青龙面板:环境变量集中管理与定时任务调度,执行体支持本地脚本与 dsh 会话任务",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "npmPublish": "npm publish --access public --provenance=false --registry=https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mzzsfy/dsh-plugin.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "croner": "^10.0.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "files": [
+    "src",
+    "test",
+    "cordis.patch.yml",
+    "README.md"
+  ]
+}

package/src/api.mjs

@@ -0,0 +1,434 @@
+// api:REST 路由 /api/cron-board/*。宿主 webServer 仅支持 exact/prefix 注册,
+// 本插件注册一条 prefix,handler 内按 method + 路径段表驱动分发(:id 路径段捕获);
+// 错误语义对齐仓内惯例:业务错误中文透传,系统级错误收敛固定文案并落服务端日志。
+
+import { assertValidSchedule, nextRunAtOf, nextRunsOf, summarizeCron } from './cron.mjs'
+import { DEFAULT_MAX_EXPANSION, DEFAULT_TIMEOUT_MS } from './config.mjs'
+import { maskValue } from './env-text.mjs'
+
+const ROUTE_PREFIX = '/api/cron-board'
+const BODY_MAX_BYTES = 64 * 1024
+
+export const MESSAGES = {
+  notFound: '接口不存在',
+  methodNotAllowed: '请求方法不支持',
+  badJsonBody: '请求体不是合法 JSON',
+  bodyTooLarge: '请求体超过上限',
+  nameRequired: '变量名不能为空',
+  jobNameRequired: '任务名称不能为空',
+  commandRequired: '任务命令不能为空',
+  badKind: '任务类型不合法',
+  badSessionMode: '会话模式仅支持 fresh 或 pinned',
+  badOnMiss: '窗口外策略仅支持 skip 或 defer',
+  windowPairRequired: '窗口起止时间必须成对填写',
+  badWindowFormat: '窗口时间格式须为 HH:mm',
+  jobNotFound: '任务不存在',
+  runNotFound: '运行记录不存在',
+  systemError: '操作失败(系统级错误,详见服务端日志)',
+}
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(payload))
+}
+
+function respondError(res, error, logSystem) {
+  const isSystem = Boolean(error && typeof error.code === 'string' && error.code !== '')
+  if (isSystem && logSystem) logSystem('[cron-board] ' + String(error && error.stack || error))
+  const message = isSystem ? MESSAGES.systemError : (error && error.message ? error.message : String(error))
+  sendJson(res, 400, { error: message })
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > BODY_MAX_BYTES) {
+        reject(new Error(MESSAGES.bodyTooLarge))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+async function readJsonBody(req) {
+  let body
+  try {
+    body = JSON.parse(await readBody(req))
+  } catch (error) {
+    if (error && error.message === MESSAGES.bodyTooLarge) throw error
+    throw new Error(MESSAGES.badJsonBody)
+  }
+  return body && typeof body === 'object' ? body : {}
+}
+
+// 多值归一:values 数组(客户端契约)按行折叠进 value 存储形态(单行 + multi 标志,
+// 展开时拆行);数组缺失或非多值回退原 value 字符串语义
+function normalizeEnvValue(body, multi) {
+  if (multi && Array.isArray(body.values)) {
+    return body.values
+      .map((item) => String(item).trim())
+      .filter((line) => line !== '')
+      .join('\n')
+  }
+  return typeof body.value === 'string' ? body.value : ''
+}
+
+// 导入文本解析:每行 NAME=value 或 NAME=value #备注;空行跳过,无 = 记非法
+export function parseEnvText(text) {
+  const rows = []
+  let invalid = 0
+  for (const rawLine of String(text).split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (line === '') continue
+    const eq = line.indexOf('=')
+    if (eq <= 0) {
+      invalid++
+      continue
+    }
+    const name = line.slice(0, eq).trim()
+    if (name === '') {
+      invalid++
+      continue
+    }
+    let rest = line.slice(eq + 1)
+    let remarks = ''
+    const hash = rest.indexOf(' #')
+    if (hash >= 0) {
+      remarks = rest.slice(hash + 2).trim()
+      rest = rest.slice(0, hash)
+    }
+    rows.push({ name, value: rest, remarks })
+  }
+  return { rows, invalid }
+}
+
+// 任务字段校验与规范化:非法即业务错误;返回可落库字段集
+const WINDOW_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/
+
+// 会话任务专有字段(设计 §3.2 job.session 子对象);窗口 start/end 须成对且为 HH:mm
+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)
+  }
+  return {
+    mode: raw.mode === 'pinned' ? 'pinned' : 'fresh',
+    pinnedSessionId: typeof raw.pinnedSessionId === 'string' ? raw.pinnedSessionId.trim() : '',
+    windowStart,
+    windowEnd,
+    onMiss: raw.onMiss === 'defer' ? 'defer' : 'skip',
+  }
+}
+
+function normalizeJob(body) {
+  const name = typeof body.name === 'string' ? body.name.trim() : ''
+  if (name === '') throw new Error(MESSAGES.jobNameRequired)
+  const kind = body.kind === 'session' ? 'session' : 'shell'
+  if (body.kind !== 'shell' && body.kind !== 'session') throw new Error(MESSAGES.badKind)
+  const command = typeof body.command === 'string' ? body.command.trim() : ''
+  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,
+    command,
+    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
+  // 任务级并发上限:合法正整数才落库,缺省走全局闸门(executor min 规则)
+  if (Number.isInteger(body.concurrency) && body.concurrency > 0) normalized.concurrency = body.concurrency
+  // nextRunAt:调用方可显式指定(导入任务保留原状态 / 测试注入到期时刻),缺省按 schedule 计算
+  normalized.nextRunAt = typeof body.nextRunAt === 'number' && Number.isFinite(body.nextRunAt)
+    ? body.nextRunAt
+    : nextRunAtOf(schedule)
+  return normalized
+}
+
+export function createApi({ store, logger, executor, scheduler, periodic, logSystem }) {
+
+  const routes = [
+    {
+      method: 'GET',
+      segments: ['envs'],
+      handler: async ({ res }) => {
+        const items = store.envs.list().map((row) => ({ ...row, value: maskValue(row.value) }))
+        sendJson(res, 200, { items })
+      },
+    },
+    {
+      // 固定段 export 须先于 :id 捕获注册,否则被当作 id 吞掉
+      method: 'GET',
+      segments: ['envs', 'export'],
+      handler: async ({ res, url }) => {
+        const includeDisabled = url.searchParams.get('includeDisabled') === '1'
+        const rows = store.envs.list().filter((row) => includeDisabled || row.enabled)
+        const text = rows.map((row) => row.name + '=' + row.value + (row.remarks ? ' #' + row.remarks : '')).join('\n') + (rows.length > 0 ? '\n' : '')
+        sendJson(res, 200, { text })
+      },
+    },
+    {
+      method: 'GET',
+      segments: ['envs', ':id'],
+      handler: async ({ res, params }) => {
+        const row = store.envs.get(params.id)
+        if (!row) throw new Error('变量不存在:' + params.id)
+        sendJson(res, 200, row)
+      },
+    },
+    {
+      method: 'POST',
+      segments: ['envs'],
+      handler: async ({ req, res }) => {
+        const body = await readJsonBody(req)
+        const name = typeof body.name === 'string' ? body.name.trim() : ''
+        if (name === '') throw new Error(MESSAGES.nameRequired)
+        const multi = body.multi === true
+        const row = await store.envs.create({
+          name,
+          value: normalizeEnvValue(body, multi),
+          remarks: typeof body.remarks === 'string' ? body.remarks : '',
+          enabled: body.enabled !== false,
+          multi,
+        })
+        sendJson(res, 200, row)
+      },
+    },
+    {
+      method: 'PATCH',
+      segments: ['envs', ':id'],
+      handler: async ({ req, res, params }) => {
+        const body = await readJsonBody(req)
+        const patch = {}
+        if (body.name !== undefined) {
+          const name = String(body.name).trim()
+          if (name === '') throw new Error(MESSAGES.nameRequired)
+          patch.name = name
+        }
+        for (const field of ['value', 'remarks']) {
+          if (body[field] !== undefined) patch[field] = String(body[field])
+        }
+        if (body.enabled !== undefined) patch.enabled = Boolean(body.enabled)
+        if (body.multi !== undefined) patch.multi = body.multi === true
+        // values 数组折叠与 POST 同前提:仅 multi===true 时采纳(client 契约恒带 multi)
+        if (body.multi === true && Array.isArray(body.values)) patch.value = normalizeEnvValue(body, true)
+        const row = await store.envs.update(params.id, patch)
+        if (!row) throw new Error('变量不存在:' + params.id)
+        sendJson(res, 200, row)
+      },
+    },
+    {
+      method: 'DELETE',
+      segments: ['envs', ':id'],
+      handler: async ({ res, params }) => {
+        const removed = await store.envs.remove(params.id)
+        if (!removed) throw new Error('变量不存在:' + params.id)
+        sendJson(res, 200, { ok: true })
+      },
+    },
+    {
+      // 环境变量文本导入:apply!==true 即预览(返回解析行数组),apply=true 落库
+      // overwrite=true 先清空再导入,缺省追加;与 client ImportForm 契约一一对应
+      method: 'POST',
+      segments: ['envs', 'import'],
+      handler: async ({ req, res }) => {
+        const body = await readJsonBody(req)
+        const { rows, invalid } = parseEnvText(body.text)
+        if (body.apply !== true) {
+          sendJson(res, 200, { parsed: rows, invalid })
+          return
+        }
+        const mode = body.overwrite === true ? 'overwrite' : 'append'
+        if (mode === 'overwrite') {
+          for (const row of [...store.envs.list()]) {
+            await store.envs.remove(row.id)
+          }
+        }
+        for (const row of rows) {
+          await store.envs.create({ name: row.name, value: row.value, remarks: row.remarks, enabled: true })
+        }
+        sendJson(res, 200, { ok: true, imported: rows.length, mode })
+      },
+    },
+    {
+      method: 'GET',
+      segments: ['status'],
+      handler: async ({ res }) => {
+        sendJson(res, 200, {
+          timerRunning: Boolean(periodic && periodic.running),
+          timerReason: periodic && periodic.reason ? periodic.reason : null,
+          scheduler: scheduler ? scheduler.status() : { active: 0, queued: 0 },
+          nextAt: scheduler && scheduler.nextRunAt ? scheduler.nextRunAt() : null,
+        })
+      },
+    },
+    {
+      // 编辑表单实时预览:croner 服务端解析,前端不引解析依赖(定案 §6.2)
+      method: 'POST',
+      segments: ['cron', 'preview'],
+      handler: async ({ req, res }) => {
+        const body = await readJsonBody(req)
+        const schedule = typeof body.schedule === 'string' ? body.schedule.trim() : ''
+        assertValidSchedule(schedule)
+        sendJson(res, 200, { summary: summarizeCron(schedule), nextAt: nextRunsOf(schedule, 3) })
+      },
+    },
+    {
+      method: 'GET',
+      segments: ['jobs'],
+      handler: async ({ res }) => {
+        // summary 人话摘要随行返回,前端不引解析依赖
+        const items = store.jobs.list().map((job) => ({ ...job, summary: summarizeCron(job.schedule) }))
+        sendJson(res, 200, { items })
+      },
+    },
+    {
+      method: 'POST',
+      segments: ['jobs'],
+      handler: async ({ req, res }) => {
+        const body = await readJsonBody(req)
+        const fields = normalizeJob(body)
+        const row = await store.jobs.create(fields)
+        sendJson(res, 200, row)
+      },
+    },
+    {
+      method: 'PATCH',
+      segments: ['jobs', ':id'],
+      handler: async ({ req, res, params }) => {
+        const body = await readJsonBody(req)
+        const existing = store.jobs.get(params.id)
+        if (!existing) throw new Error(MESSAGES.jobNotFound)
+        const fields = normalizeJob({ ...existing, ...body })
+        const row = await store.jobs.update(params.id, fields)
+        sendJson(res, 200, row)
+      },
+    },
+    {
+      method: 'DELETE',
+      segments: ['jobs', ':id'],
+      handler: async ({ res, params }) => {
+        const removed = await store.jobs.remove(params.id)
+        if (!removed) throw new Error(MESSAGES.jobNotFound)
+        await logger.removeJob(params.id)
+        sendJson(res, 200, { ok: true })
+      },
+    },
+    {
+      method: 'POST',
+      segments: ['jobs', ':id', 'run'],
+      handler: async ({ res, params }) => {
+        const job = store.jobs.get(params.id)
+        if (!job) throw new Error(MESSAGES.jobNotFound)
+        // 预占记录同步返回 runIds,执行经执行链闸门后台推进(结果经运行记录与日志呈现)
+        const runIds = await executor.dispatch(job, 'manual')
+        sendJson(res, 200, { runIds })
+      },
+    },
+    {
+      method: 'POST',
+      segments: ['jobs', ':id', 'toggle'],
+      handler: async ({ res, params }) => {
+        const job = store.jobs.get(params.id)
+        if (!job) throw new Error(MESSAGES.jobNotFound)
+        const row = await store.jobs.update(params.id, { enabled: !job.enabled })
+        sendJson(res, 200, row)
+      },
+    },
+    {
+      method: 'GET',
+      segments: ['runs'],
+      handler: async ({ res, url }) => {
+        const jobId = url.searchParams.get('jobId')
+        const rows = store.runs.list(jobId).slice().reverse()
+        sendJson(res, 200, { items: rows })
+      },
+    },
+    {
+      method: 'GET',
+      segments: ['runs', ':runId', 'log'],
+      handler: async ({ res, params, url }) => {
+        const record = store.runs.get(params.runId)
+        if (!record) throw new Error(MESSAGES.runNotFound)
+        const tailParam = url.searchParams.get('tail')
+        const tailLines = tailParam === null ? undefined : Math.max(1, Number(tailParam) || 1)
+        const text = await logger.read(record.jobId, params.runId, { tailLines })
+        sendJson(res, 200, { text })
+      },
+    },
+    {
+      method: 'DELETE',
+      segments: ['runs', ':runId', 'log'],
+      handler: async ({ res, params }) => {
+        const record = store.runs.get(params.runId)
+        if (!record) throw new Error(MESSAGES.runNotFound)
+        await logger.clear(record.jobId, params.runId)
+        sendJson(res, 200, { ok: true })
+      },
+    },
+  ]
+
+  // 路径段匹配:逐段比对,: 开头段捕获参数;返回 null 不匹配
+  function matchRoute(method, segments) {
+    for (const route of routes) {
+      if (route.method !== method) continue
+      if (route.segments.length !== segments.length) continue
+      const params = {}
+      let matched = true
+      for (let i = 0; i < route.segments.length; i++) {
+        const pattern = route.segments[i]
+        if (pattern.startsWith(':')) {
+          params[pattern.slice(1)] = decodeURIComponent(segments[i])
+        } else if (pattern !== segments[i]) {
+          matched = false
+          break
+        }
+      }
+      if (matched) return { route, params }
+    }
+    return null
+  }
+
+  return {
+    async handle(req, res) {
+      const url = new URL(req.url, 'http://localhost')
+      const pathname = url.pathname.startsWith(ROUTE_PREFIX + '/')
+        ? url.pathname.slice(ROUTE_PREFIX.length)
+        : url.pathname === ROUTE_PREFIX ? '/' : null
+      if (pathname === null) {
+        sendJson(res, 404, { error: MESSAGES.notFound })
+        return
+      }
+      const segments = pathname.split('/').filter(Boolean)
+      try {
+        const matched = matchRoute(req.method, segments)
+        if (!matched) {
+          sendJson(res, 404, { error: MESSAGES.notFound })
+          return
+        }
+        await matched.route.handler({ req, res, url, params: matched.params })
+      } catch (error) {
+        respondError(res, error, logSystem)
+      }
+    },
+  }
+}