@mzzsfy/dsh-cron-board 0.4.2 → 0.5.0

package/README.md

@@ -10,6 +10,7 @@
 - **环境变量**:集中管理,值打码展示,多值(同名展开笛卡尔积,组合数超出 20 截断并告警),dotenv 文本导入(预览/追加/覆盖)与导出
 - **会话任务**:投递即终态(crontab 语义,执行状态归会话本身);fresh 每次新建会话;pinned 固定会话(忙时跳过,会话被删除或归档自动重建并回写,首跑自动绑定);按 workdir 自动挂载宿主分组,界面分组内可见;执行预设可选(Agent Preset,缺省跟随宿主默认,dsh-im 同构)
 - **调度**:croner 解析,停机期间错过不补跑(misfire 即跳过),孤儿运行恢复,全局与任务级并发闸门;shell 任务超时收尾(会话任务无超时语义);单次运行开关(runOnce,任意一次真实运行入队后自动停用任务)
+- **时区**:cron 表达式支持内联时区后缀 `T±N`(整数小时,如 `0 9 * * *T+8` 表示东八区 9 点,范围 -12 至 +14,`T+0` 即 UTC);构建器提供时区行写入后缀,新建任务默认固化设备时区偏移;无后缀表达式按宿主进程系统时区调度(crontab 惯例),摘要与运行记录按任务所用时区展示;固定偏移不随夏令时变化,半时区设备的设备偏移就近取整
 - **日志**:每任务每运行独立日志文件,面板查看与清空,按任务保留条数裁剪(按文件修改时间)
 
 ## 路由
@@ -51,3 +52,7 @@ node --test "test/*.test.mjs"              # 测试
 ```
 
 注意:插件新增进入 profile bundles(`dsh plugin add`)后需 dsh 重启一次完成首装载;此后工作副本改动经 dev-link HMR 热重载。
+
+## dsh 版本兼容
+
+三版本全部通过:cron 看板渲染与启停、与侧边栏联动(侧栏标签页形态)、激活 live。0.1.6 新侧栏标签页系统下联动开关双态均验证通过。

package/package.json

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

package/src/api.mjs

@@ -281,6 +281,8 @@ export function createApi({ store, logger, executor, scheduler, periodic, sessio
           session: sessionState
             ? { ready: Boolean(sessionState.ready), disabled: Boolean(sessionState.disabled) }
             : { ready: false, disabled: false },
+          // 宿主进程时区偏移小时数:无后缀任务的展示时区(调度与展示同源,与浏览器无关)
+          serverTzOffset: -new Date().getTimezoneOffset() / 60,
           ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false },
         })
       },

package/src/client.js

@@ -34,10 +34,18 @@ function relativeTime(timestamp, now) {
   return Math.round(abs / DAY_MS) + ' 天' + suffix
 }
 
-function formatDateTime(timestamp) {
+function formatDateTime(timestamp, timezoneOffset) {
   if (typeof timestamp !== 'number' || !(timestamp > 0)) return '-'
-  const date = new Date(timestamp)
-  return date.getFullYear() + '-' + PAD2(date.getMonth() + 1) + '-' + PAD2(date.getDate()) + ' ' + PAD2(date.getHours()) + ':' + PAD2(date.getMinutes())
+  // 按调度所用时区(任务显式后缀或宿主默认)平移后取 UTC 分量,与浏览器时区无关;
+  // 偏移缺失(状态未加载)瞬态回退浏览器时区
+  const offset = typeof timezoneOffset === 'number' ? timezoneOffset : -new Date().getTimezoneOffset() / 60
+  const shifted = new Date(timestamp + offset * HOUR_MS)
+  return shifted.getUTCFullYear() + '-' + PAD2(shifted.getUTCMonth() + 1) + '-' + PAD2(shifted.getUTCDate()) + ' ' + PAD2(shifted.getUTCHours()) + ':' + PAD2(shifted.getUTCMinutes())
+}
+
+// 浏览器所在设备的时区偏移(整小时就近取整):仅用于新建任务时固化初始时区后缀
+function deviceTzOffset() {
+  return Math.round(-new Date().getTimezoneOffset() / 60)
 }
 
 function formatDuration(ms) {
@@ -61,6 +69,9 @@ const SB_WEEKDAY_LABELS = { '0': '日', '1': '一', '2': '二', '3': '三', '4':
 const SB_MINUTE_MAX = 59
 const SB_HOUR_MAX = 23
 const SB_INTERVAL_MIN_MINUTES = 1
+const SB_TZ_SUFFIX_MIN = -12
+const SB_TZ_SUFFIX_MAX = 14
+const SB_TZ_SUFFIX_PATTERN = /\s*T([+-])(\d{1,2})$/i
 
 function createScheduleState(expression) {
   return {
@@ -70,6 +81,7 @@ function createScheduleState(expression) {
     weekdays: ['1'],
     intervalMinutes: 30,
     expression,
+    timezone: null,
   }
 }
 
@@ -79,11 +91,21 @@ const sbClampInt = (raw, min, max, fallback) => {
   return value
 }
 
-// cron(5 段)→ 构建器状态:匹配失败即 custom;非法数值一律归 custom,不猜
+// cron(5 段)→ 构建器状态:匹配失败即 custom;非法数值一律归 custom,不猜;
+// 非法时区后缀同样 custom 兜底(原样保留,合法性由校验通道业务报错)
 function parseSchedule(expression) {
   const raw = String(expression).trim()
-  const parts = raw.split(/\s+/)
-  const state = createScheduleState(raw)
+  let split
+  try {
+    split = sbSplitScheduleTz(raw)
+  } catch {
+    const state = createScheduleState(raw)
+    state.freq = 'custom'
+    return state
+  }
+  const state = createScheduleState(split.base)
+  state.timezone = split.timezoneOffset
+  const parts = split.base.split(/\s+/)
   if (parts.length !== 5) { state.freq = 'custom'; return state }
   const [minute, hour, day, month, weekday] = parts
   if (day !== '*' || month !== '*') { state.freq = 'custom'; return state }
@@ -111,8 +133,19 @@ function parseSchedule(expression) {
   return state
 }
 
-// 构建器状态 → cron;custom 直接返回手工表达式
+// 偏移小时数 → 后缀符号值:+8 / -5 / +0
+function sbFormatTzOffset(offset) {
+  return (offset >= 0 ? '+' : '') + offset
+}
+
+// 构建器状态 → cron;custom 透传剥离后手工表达式;显式时区统一附加 T±N 后缀
 function buildSchedule(state) {
+  const base = sbBuildBase(state)
+  if (state.timezone == null) return base
+  return base + 'T' + sbFormatTzOffset(state.timezone)
+}
+
+function sbBuildBase(state) {
   if (state.freq === 'custom') return String(state.expression).trim()
   const minute = String(state.minute)
   const hour = String(state.hour)
@@ -122,8 +155,30 @@ function buildSchedule(state) {
   if (state.freq === 'interval') return '*/' + state.intervalMinutes + ' * * * *'
   return String(state.expression).trim()
 }
+
+// 剥离时区后缀:返回 { base, timezoneOffset },无后缀时 timezoneOffset 为 null;
+// 后缀超出支持范围抛业务错误(校验与桥接共用,脏数据须暴露)
+function sbSplitScheduleTz(schedule) {
+  const text = String(schedule).trim()
+  const match = text.match(SB_TZ_SUFFIX_PATTERN)
+  if (!match) return { base: text, timezoneOffset: null }
+  const offset = Number(match[1] + match[2])
+  if (offset < SB_TZ_SUFFIX_MIN || offset > SB_TZ_SUFFIX_MAX) {
+    throw new Error('时区后缀不合法: T' + match[1] + match[2] + '(支持 T±N 整数小时 ' + SB_TZ_SUFFIX_MIN + ' 至 ' + SB_TZ_SUFFIX_MAX + ')')
+  }
+  return { base: text.slice(0, match.index).trim(), timezoneOffset: offset }
+}
 /* SBUILD-END */
 
+// 任务表达式的时区偏移(小时);无后缀返回 null;脏表达式(后缀非法)兜底 null 不炸渲染
+function scheduleTzOffset(schedule) {
+  try {
+    return sbSplitScheduleTz(schedule).timezoneOffset
+  } catch {
+    return null
+  }
+}
+
 const API_PREFIX = '/api/cron-board/'
 const REFRESH_INTERVAL_MS = 30 * SECOND_MS
 const TABS = [
@@ -435,8 +490,8 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       { value: 'custom', label: '自定义' },
     ]
 
-    // 调度构建器面板:频率分段 + 上下文选择器 + 表达式芯片 + 即将执行 chips
-    function ScheduleBuilder({ scheduleState, onStateChange, preview }) {
+    // 调度构建器面板:频率分段 + 上下文选择器 + 时区行 + 表达式芯片 + 即将执行 chips
+    function ScheduleBuilder({ scheduleState, onStateChange, preview, previewError, serverTzOffset }) {
       const state = scheduleState
       const setFreq = (freq) => onStateChange({ ...state, freq })
       const patchClock = (field, raw) => {
@@ -450,6 +505,8 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
         if (days.length === 0) return
         onStateChange({ ...state, weekdays: days })
       }
+      const setTz = (raw) => onStateChange({ ...state, timezone: raw === 'host' ? null : Number(raw) })
+      const displayTzOffset = state.timezone == null ? serverTzOffset : state.timezone
       const clockRow = (h('div', { className: 'cb-bline' },
         h('span', { className: 'cb-blabel' }, '执行时间'),
         h('input', { type: 'number', className: 'cb-time', min: 0, max: SB_HOUR_MAX, value: state.hour, onChange: (e) => patchClock('hour', e.target.value) }),
@@ -486,14 +543,20 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             ? null
             : h('button', { type: 'button', className: 'cb-linkbtn', onClick: () => setFreq('custom') }, '自定义'),
           state.freq === 'custom' ? null : h('span', { className: 'cb-hint' }, '由上方选择自动生成')),
+        h('div', { className: 'cb-bline' },
+          h('span', { className: 'cb-blabel' }, '时区'),
+          h('select', { className: 'cb-select', value: state.timezone == null ? 'host' : String(state.timezone), onChange: (e) => setTz(e.target.value) },
+            h('option', { value: 'host' }, '宿主默认' + (typeof serverTzOffset === 'number' ? '(UTC' + sbFormatTzOffset(serverTzOffset) + ')' : '')),
+            Array.from({ length: SB_TZ_SUFFIX_MAX - SB_TZ_SUFFIX_MIN + 1 }, (_, i) => SB_TZ_SUFFIX_MIN + i).map((offset) => h('option', { key: offset, value: String(offset) }, 'UTC' + sbFormatTzOffset(offset)))),
+          h('span', { className: 'cb-hint' }, '固定偏移不随夏令时变化;写入表达式后缀 T±N')),
         h('div', { className: 'cb-bline' },
           h('span', { className: 'cb-blabel' }, '即将执行'),
           preview
-            ? h('span', { className: 'cb-runs' }, preview.nextAt.map((at) => h('span', { key: at, className: 'cb-run' }, formatDateTime(at))))
-            : h('span', { className: 'cb-hint' }, '表达式非法或计算中')))
+            ? h('span', { className: 'cb-runs' }, preview.nextAt.map((at) => h('span', { key: at, className: 'cb-run' }, formatDateTime(at, displayTzOffset))))
+            : h('span', { className: 'cb-hint' }, previewError || '表达式非法或计算中')))
     }
 
-    function JobForm({ job, onDone, wsModel }) {
+    function JobForm({ job, onDone, wsModel, serverTzOffset }) {
       // 工作区清单:订阅 model 快照(服务缺失或形态不符即空表,仅保留手输)
       const [wsItems, setWsItems] = useState(() => (wsModel ? wsModel.getSnapshot().items || [] : []))
       useEffect(() => {
@@ -503,7 +566,14 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
         return wsModel.subscribe(update)
       }, [wsModel])
       const editing = Boolean(job && job.id)
-      const initialSchedule = job ? job.schedule : '0 9 * * *'
+      // 构建器初始状态:新建任务把设备时区偏移固化为显式后缀,
+      // 宿主环境时区异常(如 UTC)时任务仍按设备预期时刻触发;编辑存量保持原表达式语义
+      const [scheduleState, setScheduleState] = useState(() => {
+        const parsed = parseSchedule(job ? job.schedule : '0 9 * * *')
+        if (!editing) parsed.timezone = deviceTzOffset()
+        return parsed
+      })
+      const initialSchedule = editing ? job.schedule : buildSchedule(scheduleState)
       const [form, setForm] = useState(() => ({
         name: job ? job.name : '',
         kind: job ? job.kind : 'shell',
@@ -521,15 +591,24 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           agentPreset: job && job.session ? job.session.agentPreset : '',
         },
       }))
-      // 构建器状态:由既有表达式反解初始化;结构化变更写回 form.schedule
-      const [scheduleState, setScheduleState] = useState(() => parseSchedule(initialSchedule))
       const [preview, setPreview] = useState(null)
+      const [previewError, setPreviewError] = useState(null)
       const [error, setError] = useState(null)
       const [saving, setSaving] = useState(false)
       const [presetCatalog, setPresetCatalog] = useState({ defaultId: '', items: [] })
       const set = (patch) => setForm((prev) => ({ ...prev, ...patch }))
       const setSession = (patch) => setForm((prev) => ({ ...prev, session: { ...prev.session, ...patch } }))
       const applyScheduleState = (next) => {
+        // custom 频率下表达式携带合法后缀时以表达式为准(剥离归一并回填时区);
+        // 无后缀保留调用方传入的时区(select 与频率切换不丢配置);非法后缀原文保留且时区置空
+        if (next.freq === 'custom') {
+          try {
+            const split = sbSplitScheduleTz(next.expression)
+            if (split.timezoneOffset != null) next = { ...next, expression: split.base, timezone: split.timezoneOffset }
+          } catch {
+            next = { ...next, timezone: null }
+          }
+        }
         setScheduleState(next)
         set({ schedule: buildSchedule(next) })
       }
@@ -545,9 +624,13 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
 
       useEffect(() => {
         let alive = true
+        // 表达式变更即清空旧错误:防抖窗口内不残留上一次失败文案
+        setPreviewError(null)
         const timer = setTimeout(async () => {
           const outcome = await request('POST', 'cron/preview', { schedule: form.schedule })
-          if (alive) setPreview(outcome.ok ? outcome.data : null)
+          if (!alive) return
+          setPreview(outcome.ok ? outcome.data : null)
+          setPreviewError(outcome.ok ? null : outcome.error)
         }, 300)
         return () => { alive = false; clearTimeout(timer) }
       }, [form.schedule])
@@ -575,7 +658,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             ariaLabel: '类型',
           }))),
         h(Section, { title: '调度计划' },
-          h(ScheduleBuilder, { scheduleState, onStateChange: applyScheduleState, preview })),
+          h(ScheduleBuilder, { scheduleState, onStateChange: applyScheduleState, preview, previewError, serverTzOffset })),
         form.kind === 'shell'
           ? h(Section, { title: '运行配置(shell)' },
               h(Field, { label: '命令', hint: '经由宿主 shell 执行,支持环境变量插值 $NAME' },
@@ -739,7 +822,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           onConfirm: () => deleteJob(pendingDelete),
           onCancel: () => setPendingDelete(null),
         }) : null,
-        formJob ? h(JobForm, { job: formJob.id ? formJob : null, wsModel, onDone: () => { setFormJob(null); reload() } }) : null)
+        formJob ? h(JobForm, { job: formJob.id ? formJob : null, wsModel, serverTzOffset: status ? status.serverTzOffset : undefined, onDone: () => { setFormJob(null); reload() } }) : null)
     }
 
     // —— 环境变量 Tab ——
@@ -874,11 +957,14 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     }
 
     // —— 日志 Tab ——
-    function LogsTab({ jobs, reload, reloadFlag }) {
+    function LogsTab({ jobs, reload, reloadFlag, serverTzOffset }) {
       const [jobId, setJobId] = useState(jobs.length > 0 ? jobs[0].id : null)
       const [runs, setRuns] = useState([])
       const [logText, setLogText] = useState(null)
       const [logRunId, setLogRunId] = useState(null)
+      // 展示时区随所选任务:显式后缀用其偏移,无后缀用宿主默认(调度与展示同源)
+      const selectedJob = jobs.find((job) => job.id === jobId)
+      const displayTzOffset = scheduleTzOffset(selectedJob ? selectedJob.schedule : null) ?? (typeof serverTzOffset === 'number' ? serverTzOffset : undefined)
 
       useEffect(() => {
         let alive = true
@@ -912,7 +998,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
                 h('span', { className: 'cb-dot', style: { '--cb-status': STATUS_TONE_COLOR[meta.tone] } }),
                 h('span', { className: 'cb-meta' }, meta.label),
                 h('span', { className: 'cb-badge' }, TRIGGER_META[run.trigger] ? TRIGGER_META[run.trigger].label : run.trigger),
-                h('span', { className: 'cb-meta' }, formatDateTime(run.createdAt)),
+                h('span', { className: 'cb-meta' }, formatDateTime(run.createdAt, displayTzOffset)),
                 typeof run.durationMs === 'number' ? h('span', { className: 'cb-meta' }, formatDuration(run.durationMs)) : null,
                 run.message ? h('span', { className: 'cb-meta' }, run.message) : null,
                 h('div', { className: 'cb-actions' },
@@ -972,7 +1058,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             (status.nextAt ? ' · 下次 ' + relativeTime(status.nextAt, now) : '')) : null),
         tab === 'jobs' ? h(JobsTab, { key: 'jobs', jobs, status, now, reload, applyJobPatch, wsModel }) : null,
         tab === 'envs' ? h(EnvsTab, { key: 'envs', envs, reload, applyEnvPatch }) : null,
-        tab === 'logs' ? h(LogsTab, { key: 'logs', jobs, reload, reloadFlag }) : null)
+        tab === 'logs' ? h(LogsTab, { key: 'logs', jobs, reload, reloadFlag, serverTzOffset: status ? status.serverTzOffset : undefined }) : null)
     }
 
     // —— 主页面挂载:宿主官方全局面板契约(main keyed 插槽 + sidebar.panellist 侧栏入口)——

package/src/cron.mjs

@@ -1,25 +1,42 @@
 // cron 解析薄封装:croner 承担表达式解析与触发点计算(5/6 段通吃、时区、DST)。
-// 非法表达式以业务错误抛出,文案中文原样透传给路由层。
+// 表达式支持内联时区后缀 T±N(语法归 schedule-builder):显式后缀按固定偏移,
+// 无后缀按宿主系统时区(crontab 惯例,与 croner 原生行为一致)。
 
 import { Cron } from 'croner'
 
+import { splitScheduleTz, formatTzOffset } from './schedule-builder.mjs'
+
+// 固定偏移 → croner 时区名(Etc/GMT 为 POSIX 反转:UTC+8 即 Etc/GMT-8)
+function etcGmtName(timezoneOffset) {
+  if (timezoneOffset === 0) return 'UTC'
+  return timezoneOffset > 0 ? 'Etc/GMT-' + timezoneOffset : 'Etc/GMT+' + (-timezoneOffset)
+}
+
+// croner 构造选项:无后缀不指定时区(宿主系统时区)
+function cronOptions(timezoneOffset) {
+  return timezoneOffset === null ? {} : { timezone: etcGmtName(timezoneOffset) }
+}
+
 // 求自 from 起下一次触发点(ms epoch);表达式无未来触发点时返回 null
 export function nextRunAtOf(schedule, from = new Date()) {
-  const job = new Cron(schedule)
+  const { base, timezoneOffset } = splitScheduleTz(schedule)
+  const job = new Cron(base, cronOptions(timezoneOffset))
   const next = job.nextRun(from)
   return next ? next.getTime() : null
 }
 
 // 求自 from 起下 N 次触发点(编辑表单实时预览用)
 export function nextRunsOf(schedule, count, from = new Date()) {
-  const job = new Cron(schedule)
+  const { base, timezoneOffset } = splitScheduleTz(schedule)
+  const job = new Cron(base, cronOptions(timezoneOffset))
   return job.nextRuns(count, from).map((date) => date.getTime())
 }
 
-// 表达式合法性校验:合法返回 null,非法抛业务错误
+// 表达式合法性校验:合法返回 null,非法抛业务错误(后缀与表达式分别报因)
 export function assertValidSchedule(schedule) {
+  const { base } = splitScheduleTz(schedule)
   try {
-    new Cron(schedule)
+    new Cron(base)
   } catch (error) {
     throw new Error('cron 表达式不合法: ' + schedule)
   }
@@ -28,23 +45,32 @@ export function assertValidSchedule(schedule) {
 const WEEKDAY_LABELS = ['日', '一', '二', '三', '四', '五', '六']
 const PAD2 = (value) => String(value).padStart(2, '0')
 
-// 人话摘要(轻量规则覆盖常用形态,兜底回原表达式)
-export function summarizeCron(schedule) {
-  const parts = String(schedule).trim().split(/\s+/)
-  if (parts.length !== 5) return schedule
+// 时区尾注:显式后缀标注自身,无后缀标注宿主默认(hostOffset 可显式传入以便测试)
+function tzNote(timezoneOffset, hostOffset) {
+  return timezoneOffset === null
+    ? '(宿主 UTC' + formatTzOffset(hostOffset) + ')'
+    : '(UTC' + formatTzOffset(timezoneOffset) + ')'
+}
+
+// 人话摘要(轻量规则覆盖常用形态,兜底回原表达式),一律携带时区尾注
+export function summarizeCron(schedule, hostOffset = -new Date().getTimezoneOffset() / 60) {
+  const { base, timezoneOffset } = splitScheduleTz(schedule)
+  const note = tzNote(timezoneOffset, hostOffset)
+  const parts = base.trim().split(/\s+/)
+  if (parts.length !== 5) return base + note
   const [minute, hour, day, month, weekday] = parts
   const clock = (h, m) => PAD2(h) + ':' + PAD2(m)
   const dayFree = day === '*' && month === '*' && weekday === '*'
-  if (dayFree && /^\*\/\d+$/.test(hour) && minute === '0') return '每 ' + hour.slice(2) + ' 小时'
-  if (dayFree && hour.startsWith('*/')) return '每 ' + hour.slice(2) + ' 小时(第 ' + minute + ' 分)'
-  if (dayFree && /^\*\/\d+$/.test(minute) && hour === '*') return '每 ' + minute.slice(2) + ' 分钟'
-  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return schedule
+  if (dayFree && /^\*\/\d+$/.test(hour) && minute === '0') return '每 ' + hour.slice(2) + ' 小时' + note
+  if (dayFree && hour.startsWith('*/')) return '每 ' + hour.slice(2) + ' 小时(第 ' + minute + ' 分)' + note
+  if (dayFree && /^\*\/\d+$/.test(minute) && hour === '*') return '每 ' + minute.slice(2) + ' 分钟' + note
+  if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour)) return base + note
   if (month !== '*' || day !== '*') {
-    if (/^\d+$/.test(day) && month === '*') return '每月 ' + day + ' 日 ' + clock(hour, minute)
-    return schedule
+    if (/^\d+$/.test(day) && month === '*') return '每月 ' + day + ' 日 ' + clock(hour, minute) + note
+    return base + note
   }
-  if (weekday === '1-5') return '工作日 ' + clock(hour, minute)
-  if (/^\d$/.test(weekday)) return '每周' + (WEEKDAY_LABELS[Number(weekday)] || weekday) + ' ' + clock(hour, minute)
-  if (day === '*' && weekday === '*') return '每天 ' + clock(hour, minute)
-  return schedule
+  if (weekday === '1-5') return '工作日 ' + clock(hour, minute) + note
+  if (/^\d$/.test(weekday)) return '每周' + (WEEKDAY_LABELS[Number(weekday)] || weekday) + ' ' + clock(hour, minute) + note
+  if (day === '*' && weekday === '*') return '每天 ' + clock(hour, minute) + note
+  return base + note
 }

package/src/schedule-builder.mjs

@@ -10,7 +10,8 @@ export const MINUTE_MAX = 59
 export const HOUR_MAX = 23
 export const INTERVAL_MIN_MINUTES = 1
 
-// 结构化调度状态:custom 时 expression 为唯一有效字段,其余字段仍保留(切回结构化频率不丢配置)
+// 结构化调度状态:custom 时 expression 为唯一有效字段,其余字段仍保留(切回结构化频率不丢配置);
+// timezone 为内联时区后缀的偏移小时数,null 表示无后缀(按宿主系统时区)
 export function createScheduleState(expression) {
   return {
     freq: 'daily',
@@ -19,6 +20,7 @@ export function createScheduleState(expression) {
     weekdays: ['1'],
     intervalMinutes: 30,
     expression,
+    timezone: null,
   }
 }
 
@@ -28,11 +30,21 @@ const clampInt = (raw, min, max, fallback) => {
   return value
 }
 
-// cron(5 段)→ 构建器状态:匹配失败即 custom;非法数值一律归 custom,不猜
+// cron(5 段)→ 构建器状态:匹配失败即 custom;非法数值一律归 custom,不猜;
+// 非法时区后缀同样 custom 兜底(原样保留,合法性由校验通道业务报错)
 export function parseSchedule(expression) {
   const raw = String(expression).trim()
-  const parts = raw.split(/\s+/)
-  const state = createScheduleState(raw)
+  let split
+  try {
+    split = splitScheduleTz(raw)
+  } catch {
+    const state = createScheduleState(raw)
+    state.freq = 'custom'
+    return state
+  }
+  const state = createScheduleState(split.base)
+  state.timezone = split.timezoneOffset
+  const parts = split.base.split(/\s+/)
   if (parts.length !== 5) { state.freq = 'custom'; return state }
   const [minute, hour, day, month, weekday] = parts
   if (day !== '*' || month !== '*') { state.freq = 'custom'; return state }
@@ -60,8 +72,19 @@ export function parseSchedule(expression) {
   return state
 }
 
-// 构建器状态 → cron;custom 直接返回手工表达式
+// 偏移小时数 → 后缀符号值:+8 / -5 / +0
+export function formatTzOffset(offset) {
+  return (offset >= 0 ? '+' : '') + offset
+}
+
+// 构建器状态 → cron;custom 透传剥离后手工表达式;显式时区统一附加 T±N 后缀
 export function buildSchedule(state) {
+  const base = buildBase(state)
+  if (state.timezone == null) return base
+  return base + 'T' + formatTzOffset(state.timezone)
+}
+
+function buildBase(state) {
   if (state.freq === 'custom') return String(state.expression).trim()
   const minute = String(state.minute)
   const hour = String(state.hour)
@@ -71,3 +94,23 @@ export function buildSchedule(state) {
   if (state.freq === 'interval') return '*/' + state.intervalMinutes + ' * * * *'
   return String(state.expression).trim()
 }
+
+// —— 内联时区后缀:表达式形态的一部分,构建器读写,cron.mjs 桥接 croner 时复用 ——
+
+export const TZ_SUFFIX_MIN = -12
+export const TZ_SUFFIX_MAX = 14
+// T±N 整数小时,允许与表达式空格分隔,大小写均可
+const TZ_SUFFIX_PATTERN = /\s*T([+-])(\d{1,2})$/i
+
+// 剥离时区后缀:返回 { base, timezoneOffset },无后缀时 timezoneOffset 为 null;
+// 后缀超出支持范围抛业务错误(校验与桥接共用,脏数据须暴露)
+export function splitScheduleTz(schedule) {
+  const text = String(schedule).trim()
+  const match = text.match(TZ_SUFFIX_PATTERN)
+  if (!match) return { base: text, timezoneOffset: null }
+  const offset = Number(match[1] + match[2])
+  if (offset < TZ_SUFFIX_MIN || offset > TZ_SUFFIX_MAX) {
+    throw new Error('时区后缀不合法: T' + match[1] + match[2] + '(支持 T±N 整数小时 ' + TZ_SUFFIX_MIN + ' 至 ' + TZ_SUFFIX_MAX + ')')
+  }
+  return { base: text.slice(0, match.index).trim(), timezoneOffset: offset }
+}

package/test/cron.test.mjs

@@ -0,0 +1,98 @@
+// cron 解析封装测试:内联时区后缀 T±N 的触发点计算、校验与人话摘要(BDD feat-timezone S1)。
+// 后缀语义:显式后缀按固定偏移;无后缀按宿主系统时区(与 croner 原生行为一致)。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { Cron } from 'croner'
+
+import { nextRunAtOf, nextRunsOf, assertValidSchedule, summarizeCron } from '../src/cron.mjs'
+import { buildSchedule } from '../src/schedule-builder.mjs'
+
+// 固定起点:2026-09-17T12:00:00Z(北京 20:00),之后的 9:00 触发点跨日,断言无歧义
+const FROM = new Date('2026-09-17T12:00:00Z')
+
+test('cron:后缀 T+8 按东八区计算触发点', () => {
+  // Given 表达式 0 9 * * *T+8
+  // When 求自固定起点起的下一次触发
+  const at = nextRunAtOf('0 9 * * *T+8', FROM)
+  // Then 触发点为北京 09-18 09:00,即 01:00Z
+  assert.equal(at, Date.UTC(2026, 8, 18, 1, 0, 0))
+})
+
+test('cron:后缀 T+0 与 T-5 按固定偏移计算,允许后缀前空格', () => {
+  // Then T+0 即 UTC 触发点 09:00Z
+  assert.equal(nextRunAtOf('0 9 * * *T+0', FROM), Date.UTC(2026, 8, 18, 9, 0, 0))
+  // Then 空格分隔等价紧贴
+  assert.equal(nextRunAtOf('0 9 * * * T+0', FROM), Date.UTC(2026, 8, 18, 9, 0, 0))
+  // Then T-5 即 UTC-5 的 9:00,起点(12:00Z)之后的下一次为当日 14:00Z
+  assert.equal(nextRunAtOf('0 9 * * *T-5', FROM), Date.UTC(2026, 8, 17, 14, 0, 0))
+})
+
+test('cron:后缀 T+8 下三次触发连续推进', () => {
+  // Given 显式东八区,取 3 个触发点
+  const runs = nextRunsOf('0 9 * * *T+8', 3, FROM)
+  // Then 为连续三天北京 09:00(01:00Z)
+  assert.deepEqual(runs, [
+    Date.UTC(2026, 8, 18, 1, 0, 0),
+    Date.UTC(2026, 8, 19, 1, 0, 0),
+    Date.UTC(2026, 8, 20, 1, 0, 0),
+  ])
+})
+
+test('cron:无后缀与 croner 原生系统时区行为一致', () => {
+  // Given 无后缀表达式
+  // When 求下一次触发
+  const at = nextRunAtOf('30 8 * * *', FROM)
+  // Then 与 croner 原生(不传 timezone)一致,零回归
+  const native = new Cron('30 8 * * *').nextRun(FROM).getTime()
+  assert.equal(at, native)
+})
+
+test('cron:后缀解析边界——负零、前导零、小写、空格归一', () => {
+  // Then 负零等价 +0(UTC)
+  assert.equal(nextRunAtOf('0 9 * * *T-0', FROM), Date.UTC(2026, 8, 18, 9, 0, 0))
+  // Then 前导零等价单位数
+  assert.equal(nextRunAtOf('0 9 * * *T+08', FROM), Date.UTC(2026, 8, 18, 1, 0, 0))
+  // Then 小写 t 同样识别
+  assert.equal(nextRunAtOf('0 9 * * *t+8', FROM), Date.UTC(2026, 8, 18, 1, 0, 0))
+  // Then 空格分隔反解后回写归一为紧贴形态
+  const state = { freq: 'daily', hour: 9, minute: 0, weekdays: ['1'], intervalMinutes: 30, expression: '0 9 * * *', timezone: 8 }
+  assert.equal(buildSchedule(state), '0 9 * * *T+8')
+  // Then 负零写侧归一为 +0(不输出 T-0)
+  assert.equal(buildSchedule({ ...state, timezone: -0 }), '0 9 * * *T+0')
+})
+
+test('cron:nextRunAtOf 对非法后缀直接抛业务错误', () => {
+  assert.throws(() => nextRunAtOf('0 9 * * *T+15', FROM), /时区后缀不合法/)
+})
+
+test('cron:非法后缀抛业务错误,坏表达式抛表达式错误', () => {
+  // Then 后缀超界(-12..14 之外)报后缀不合法
+  assert.throws(() => assertValidSchedule('0 9 * * *T+15'), /时区后缀不合法: T\+15/)
+  assert.throws(() => assertValidSchedule('0 9 * * *T-13'), /时区后缀不合法/)
+  // Then 表达式本身坏报表达式不合法(文案含原文)
+  assert.throws(() => assertValidSchedule('not-a-cronT+8'), /cron 表达式不合法: not-a-cronT\+8/)
+  // Then 合法表达式不抛
+  assert.doesNotThrow(() => assertValidSchedule('0 9 * * *T+8'))
+  assert.doesNotThrow(() => assertValidSchedule('0 9 * * *'))
+})
+
+test('cron:摘要显式后缀尾注 (UTC+N)', () => {
+  assert.equal(summarizeCron('0 9 * * *T+8'), '每天 09:00(UTC+8)')
+  assert.equal(summarizeCron('30 8 * * 1-5 T+0'), '工作日 08:30(UTC+0)')
+  assert.equal(summarizeCron('0 22 * * 6T-5'), '每周六 22:00(UTC-5)')
+})
+
+test('cron:摘要无后缀尾注显示宿主偏移,显式传参可测', () => {
+  // Given 宿主偏移显式传 0
+  assert.equal(summarizeCron('0 9 * * *', 0), '每天 09:00(宿主 UTC+0)')
+  // Given 宿主偏移显式传 5.5(半时区宿主)
+  assert.equal(summarizeCron('0 9 * * *', 5.5), '每天 09:00(宿主 UTC+5.5)')
+})
+
+test('cron:摘要 custom 与非 5 段兜底同样携带时区尾注', () => {
+  // Given 指定日月(非构建器形态)带后缀
+  assert.equal(summarizeCron('0 0 1 1 *T+8'), '0 0 1 1 *(UTC+8)')
+  // Given 非法表达式(不构成摘要)带宿主偏移传参
+  assert.equal(summarizeCron('not-a-cron', 0), 'not-a-cron(宿主 UTC+0)')
+})

package/test/executor.test.mjs

@@ -36,14 +36,21 @@ async function makeExecutor(t, { jobsBroken = false, logLines = [] } = {}) {
 
 const JOB_BASE = { name: 't', kind: 'shell', command: 'echo hi', schedule: '* * * * *', enabled: true, timeoutMs: 60 * 1000 }
 
-async function dispatchAndSettle(executor, store, jobId) {
-  const [runId] = await executor.dispatch({ ...JOB_BASE, id: jobId }, 'manual')
-  // 等执行链收尾:pump 后单元在后台,轮询至终态或超时
-  for (let i = 0; i < 200; i++) {
-    const row = store.runs.get(runId)
-    if (row && row.status !== 'queued' && row.status !== 'running') return runId
+// 轮询至断言目标状态可见:执行链在 runs 终态后仍有任务卡回填/留痕等后台落定动作,单次读取存在竞态窗口
+async function waitFor(predicate, timeoutMs = 2 * 1000) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    if (predicate()) return
+    if (Date.now() > deadline) throw new Error('waitFor 超时')
     await new Promise((resolve) => setTimeout(resolve, 10))
   }
+}
+
+async function dispatchAndSettle(executor, store, jobId) {
+  const [runId] = await executor.dispatch({ ...JOB_BASE, id: jobId }, 'manual')
+  // 等执行链完整落定:runs 终态内存生效早于写链持久化,任务卡回填在其后才可见,以回填为收尾信号
+  // 信号为任务级(同名任务任一单元回填即满足),非特定 run 级;当前调用点无依赖特定 run 落定的断言
+  await waitFor(() => store.jobs.get(jobId)?.lastStatus !== undefined)
   return runId
 }
 
@@ -87,12 +94,8 @@ test('executor:pinned 自愈回写 session.pinnedSessionId 且清除顶层孤立
     readMaxConcurrent: () => 2,
   })
   const [runId] = await executorWithPinned.dispatch({ ...JOB_BASE, kind: 'session', session: { mode: 'pinned', pinnedSessionId: '' }, id: 'j-pin' }, 'manual')
-  for (let i = 0; i < 200; i++) {
-    const row = store.runs.get(runId)
-    if (row && row.status !== 'queued' && row.status !== 'running') break
-    await new Promise((resolve) => setTimeout(resolve, 10))
-  }
-  // Then 绑定写入 session 子对象,顶层无孤立残留
+  // Then 绑定写入 session 子对象,顶层无孤立残留;回填晚于 runs 终态,以回填可见为落定信号
+  await waitFor(() => store.jobs.get('j-pin')?.session?.pinnedSessionId === 's-new')
   const job = store.jobs.get('j-pin')
   assert.equal(job.session.pinnedSessionId, 's-new')
   assert.equal(job.pinnedSessionId, undefined)
@@ -114,11 +117,8 @@ test('executor:runner 拒绝时补写 fail 终态', async (t) => {
   })
   await store.jobs.create({ ...JOB_BASE, id: 'j2' })
   const [runId] = await executor.dispatch({ ...JOB_BASE, id: 'j2' }, 'manual')
-  for (let i = 0; i < 200; i++) {
-    const row = store.runs.get(runId)
-    if (row && row.status === 'fail') break
-    await new Promise((resolve) => setTimeout(resolve, 10))
-  }
+  // catch 路径先补 runs 终态再回填任务卡,以回填可见为收尾信号
+  await waitFor(() => store.jobs.get('j2')?.lastStatus === 'fail')
   const row = store.runs.get(runId)
   assert.equal(row.status, 'fail')
   assert.match(row.message, /会话服务爆炸/)
@@ -129,7 +129,9 @@ test('executor:runner 拒绝时补写 fail 终态', async (t) => {
 test('executor:运行终态已落库而任务卡回填失败,历史不被覆写', async (t) => {
   const { store, executor, logLines } = await makeExecutor(t, { jobsBroken: true })
   await store.jobs.create({ ...JOB_BASE, id: 'j3' })
-  const runId = await dispatchAndSettle(executor, store, 'j3')
+  const [runId] = await executor.dispatch({ ...JOB_BASE, id: 'j3' }, 'manual')
+  // 任务卡回填被拒必留痕:留痕集合即 catch 路径收尾信号(此场景 lastStatus 永不可见)
+  await waitFor(() => logLines.length === 1)
   // Then 事实成功保留,不被 catch 覆写为 fail;回填缺口留痕可观测
   assert.equal(store.runs.get(runId).status, 'success')
   assert.equal(logLines.length, 1)
@@ -143,7 +145,8 @@ test('executor:运行终态补写失败经 logSystem 留痕', async (t) => {
   const [runId] = await executor.dispatch({ ...JOB_BASE, id: 'j4' }, 'manual')
   // dispatch 完成(记录已落库、runUnit 已入队)后再让 runs 集合损坏:终态写入必失败
   store.runs.update = async () => { throw new Error('数据文件已损坏已备份,已暂停写入以防数据丢失') }
-  await new Promise((resolve) => setTimeout(resolve, 200))
+  // 补写失败必留痕:以留痕可见替代固定等待,消除时序脆弱
+  await waitFor(() => logLines.length === 1)
   // Then 补写失败恰留痕一次,含 runId 与原始错误
   assert.equal(logLines.length, 1)
   assert.ok(logLines[0].includes(runId))

package/test/index.test.mjs

@@ -203,7 +203,8 @@ test('index:tick 到期任务被调度执行(端到端装配)', async (t) => {
   const dir = await mkdtemp(join(tmpdir(), 'cron-board-idx-'))
   t.after(async () => {
     delete process.env.DSH_CRON_BOARD_DATA_DIR
-    await rm(dir, { recursive: true, force: true })
+    // 运行终态可见后执行链仍有后台落盘(任务卡回填/日志写),与目录删除竞态,有界重试消解
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
   })
   process.env.DSH_CRON_BOARD_DATA_DIR = dir
   const { ctx, routes, intervals } = makeFullCtx()

package/test/routes.test.mjs

@@ -465,9 +465,9 @@ test('cron preview 路由:人话摘要与下三次触发', async (t) => {
   const { api } = await makeApi(t)
   // When 预览「每天 08:30」
   const ok = await call(api, 'POST', '/api/cron-board/cron/preview', { schedule: '30 8 * * *' })
-  // Then 摘要含每天与时刻,三次触发时间戳齐备
+  // Then 摘要含每天与时刻并带宿主时区尾注,三次触发时间戳齐备
   assert.equal(ok.status, 200)
-  assert.equal(ok.payload.summary, '每天 08:30')
+  assert.match(ok.payload.summary, /^每天 08:30\(宿主 UTC[+-]\d/)
   assert.equal(ok.payload.nextAt.length, 3)
   assert.ok(ok.payload.nextAt.every((value) => typeof value === 'number' && value > Date.now()))
   // When 非法表达式
@@ -477,6 +477,33 @@ test('cron preview 路由:人话摘要与下三次触发', async (t) => {
   assert.match(bad.payload.error, /cron/i)
 })
 
+test('jobs 与 preview 路由:时区后缀表达式的调度与校验', async (t) => {
+  const { api } = await makeApi(t)
+  // Given 带 T+8 后缀的任务
+  const created = await call(api, 'POST', '/api/cron-board/jobs', { name: 'tz', kind: 'shell', command: 'x', schedule: '0 9 * * *T+8' })
+  assert.equal(created.status, 200)
+  // Then 默认触发点按东八区 9:00(01:00Z),与宿主自身时区无关
+  assert.equal(new Date(created.payload.nextRunAt).toISOString().slice(11, 16), '01:00')
+  // When 非法后缀创建任务
+  const bad = await call(api, 'POST', '/api/cron-board/jobs', { name: 'tz2', kind: 'shell', command: 'x', schedule: '0 9 * * *T+15' })
+  // Then 400 且报后缀不合法
+  assert.equal(bad.status, 400)
+  assert.match(bad.payload.error, /时区后缀不合法/)
+  // When 带后缀预览
+  const preview = await call(api, 'POST', '/api/cron-board/cron/preview', { schedule: '30 8 * * *T+8' })
+  // Then 摘要尾注与触发点均为东八区语义
+  assert.equal(preview.status, 200)
+  assert.equal(preview.payload.summary, '每天 08:30(UTC+8)')
+  assert.equal(new Date(preview.payload.nextAt[0]).toISOString().slice(11, 16), '00:30')
+})
+
+test('status 路由:暴露宿主时区偏移 serverTzOffset', async (t) => {
+  const { api } = await makeApi(t)
+  const res = await call(api, 'GET', '/api/cron-board/status')
+  assert.equal(res.status, 200)
+  assert.equal(typeof res.payload.serverTzOffset, 'number')
+})
+
 test('runs 路由:无参数查全量,带 jobId 查单任务', async (t) => {
   // Given 两个任务各有一条运行记录
   const { store, api } = await makeApi(t)

package/test/schedule-builder.test.mjs

@@ -102,6 +102,54 @@ test('字段越界数值反解归 custom,不猜修正', () => {
   assert.equal(parseSchedule('* 9 * * *').freq, 'custom')
 })
 
+test('时区后缀:反解与回写 T+N', () => {
+  const state = parseSchedule('0 9 * * *T+8')
+  assert.equal(state.freq, 'daily')
+  assert.equal(state.hour, 9)
+  assert.equal(state.timezone, 8)
+  assert.equal(buildSchedule(state), '0 9 * * *T+8')
+})
+
+test('时区后缀:无后缀反解 timezone 为 null,回写不附加', () => {
+  const state = parseSchedule('30 8 * * *')
+  assert.equal(state.timezone, null)
+  assert.equal(buildSchedule(state), '30 8 * * *')
+})
+
+test('时区后缀:interval 与工作日形态同样携带', () => {
+  const interval = parseSchedule('*/30 * * * *T+0')
+  assert.equal(interval.freq, 'interval')
+  assert.equal(interval.timezone, 0)
+  assert.equal(buildSchedule(interval), '*/30 * * * *T+0')
+  const weekdays = parseSchedule('0 9 * * 1-5T-5')
+  assert.equal(weekdays.freq, 'weekdays')
+  assert.equal(weekdays.timezone, -5)
+  assert.equal(buildSchedule(weekdays), '0 9 * * 1-5T-5')
+})
+
+test('时区后缀:非法后缀反解 custom 且原文保留,不抛', () => {
+  const state = parseSchedule('0 9 * * *T+15')
+  assert.equal(state.freq, 'custom')
+  assert.equal(state.expression, '0 9 * * *T+15')
+  assert.equal(state.timezone, null)
+})
+
+test('时区后缀:custom 合法后缀剥离存储,回写统一附加', () => {
+  const state = parseSchedule('0 9 * * * 2026T+8')
+  assert.equal(state.freq, 'custom')
+  assert.equal(state.expression, '0 9 * * * 2026')
+  assert.equal(state.timezone, 8)
+  assert.equal(buildSchedule(state), '0 9 * * * 2026T+8')
+})
+
+test('时区后缀:createScheduleState 默认无后缀,置空回写不带后缀', () => {
+  const state = createScheduleState('')
+  assert.equal(state.timezone, null)
+  state.freq = 'daily'
+  state.hour = 2
+  assert.equal(buildSchedule(state), '0 2 * * *')
+})
+
 test('parity:client.js SBUILD 段与核心实现逐字镜像', () => {
   // Given client 半区无模块系统,构建器逻辑必须内联(经典 script)
   // When 从两侧源码提取函数体文本(SBUILD 标记段 vs schedule-builder.mjs 导出体)
@@ -115,7 +163,7 @@ test('parity:client.js SBUILD 段与核心实现逐字镜像', () => {
   const core = readFileSync(join(pkgRoot, 'src', 'schedule-builder.mjs'), 'utf8')
   // 逐函数对比:剥离 export 关键词后,核心源码的每个可执行行都应出现在 client 镜像段
   const coreLines = core.split('\n')
-    .map((line) => line.replace(/^export /, '').replace(/\bFREQS\b/g, 'SB_FREQS').replace(/\bWEEKDAY_ORDER\b/g, 'SB_WEEKDAY_ORDER').replace(/\bWEEKDAY_LABELS\b/g, 'SB_WEEKDAY_LABELS').replace(/\bMINUTE_MAX\b/g, 'SB_MINUTE_MAX').replace(/\bHOUR_MAX\b/g, 'SB_HOUR_MAX').replace(/\bINTERVAL_MIN_MINUTES\b/g, 'SB_INTERVAL_MIN_MINUTES').replace(/\bclampInt\b/g, 'sbClampInt').trim())
+    .map((line) => line.replace(/^export /, '').replace(/\bFREQS\b/g, 'SB_FREQS').replace(/\bWEEKDAY_ORDER\b/g, 'SB_WEEKDAY_ORDER').replace(/\bWEEKDAY_LABELS\b/g, 'SB_WEEKDAY_LABELS').replace(/\bMINUTE_MAX\b/g, 'SB_MINUTE_MAX').replace(/\bHOUR_MAX\b/g, 'SB_HOUR_MAX').replace(/\bINTERVAL_MIN_MINUTES\b/g, 'SB_INTERVAL_MIN_MINUTES').replace(/\bTZ_SUFFIX_MIN\b/g, 'SB_TZ_SUFFIX_MIN').replace(/\bTZ_SUFFIX_MAX\b/g, 'SB_TZ_SUFFIX_MAX').replace(/\bTZ_SUFFIX_PATTERN\b/g, 'SB_TZ_SUFFIX_PATTERN').replace(/\bsplitScheduleTz\b/g, 'sbSplitScheduleTz').replace(/\bformatTzOffset\b/g, 'sbFormatTzOffset').replace(/\bbuildBase\b/g, 'sbBuildBase').replace(/\bclampInt\b/g, 'sbClampInt').trim())
     .filter((line) => line !== '' && !line.startsWith('//'))
   for (const line of coreLines) {
     assert.ok(block.includes(line), 'client 镜像段缺少核心行: ' + line)