@mzzsfy/dsh-cron-board 0.4.2 → 0.6.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 版本兼容
+
+三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)兼容通过:cron 看板渲染与编辑器、侧栏入口、激活 live。0.1.6 新侧栏标签页系统下联动开关双态均验证通过;0.1.7-rc.1 修复 ui-settings 写失败打崩宿主(await 化 + 路由级 catch 降级),内置插件页改版后设置开关卡锚缺失(宿主演进),看板面实测正常。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-cron-board",
   "description": "轻量级定时任务看板:环境变量集中管理与定时任务调度,执行体支持本地脚本与 dsh 会话任务",
-  "version": "0.4.2",
+  "version": "0.6.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 },
         })
       },
@@ -295,8 +297,8 @@ export function createApi({ store, logger, executor, scheduler, periodic, sessio
         if (typeof body.sidebarTab === 'boolean') patch.sidebarTab = body.sidebarTab
         if (!Object.keys(patch).length) return sendJson(res, 400, { error: '无有效字段' })
         if (typeof updateUiSettings !== 'function') return sendJson(res, 200, { ok: false, error: '设置服务不可用' })
-        updateUiSettings(patch)
-        sendJson(res, 200, { ok: true, ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false } })
+        const persisted = await updateUiSettings(patch)
+        sendJson(res, 200, { ok: persisted, 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 侧栏入口)——
@@ -983,6 +1069,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     const TAB_ID = 'cron-board:board'
     const PANEL_ID = 'cron-board'
     const PANEL_LABEL = '定时任务'
+    const PKG_ID = '@mzzsfy/dsh-cron-board'
 
     // 设置>插件页卡片:官方 PluginCard 形制(名称/描述头部 + chevron 折叠 + 行内开关);better-sidebar 在场可切换,否则仅展示禁用态
     const CARD_TITLE = '定时任务'
@@ -1133,6 +1220,15 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             () => h(CronBoardPluginCard, { ctx }),
           )
         }), 'cron-board settings card')
+        // 插件管理页(0.1.7-rc.1+)包详情配置卡:key = 包名,管理页 ledger.bundles 判定 section
+        // 在场;卡片自包含(只调本插件 API,不触宿主 settings)。两代槽位并存注册:inject 是
+        // 声明生命周期效应,错误世代宿主永不声明该槽,回调挂起不执行,零成本
+        ctx.effect(() => ctx.slots.inject('plugins.bundle.config', function* () {
+          yield ctx.slots.register(
+            { name: 'plugins.bundle.config', key: PKG_ID },
+            () => h(CronBoardPluginCard, { ctx }),
+          )
+        }), 'cron-board plugin manager card')
         ctx.inject(['betterSidebar'], (bsCtx) => {
           currentSidebar = bsCtx.betterSidebar
           applyPref()

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/index.js

@@ -43,6 +43,21 @@ const SETTINGS_SCHEMA = schemastery.object({
   sidebarTab: schemastery.boolean().default(false).description('看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面)'),
 })
 
+// 0.1.7 宿主以静态 Config 导出生成设置节表单(maintain 同构);legacy 宿主经
+// settings.register 注册同名命名空间。根级 volatile 包装:0.1.7 下整节为 live
+// 表单,节写经 loader 原地热更;旧宿主 schemastery 无 volatile 方法,特性检测原样返回
+export const Config = volatileWrap(SETTINGS_SCHEMA)
+
+function volatileWrap(schema) {
+  return typeof schema.volatile === 'function' ? schema.volatile() : schema
+}
+
+// volatile ref 动态解包(get 协议):0.1.7 下 apply 入参 config 为整节单 ref;
+// legacy 宿主 config 为普通对象原样透传
+function unwrapVolatile(value) {
+  return typeof value?.get === 'function' ? value.get() : value
+}
+
 export function resolveDataDir(env = process.env) {
   const override = env[DATA_DIR_ENV]
   if (override && override.trim() !== '') return override.trim()
@@ -139,17 +154,42 @@ export function apply(ctx, config) {
     const value = readSettingValue(name)
     return typeof value === 'boolean' ? value : fallback
   }
-  // 客户端设置面板写入通道:settings 服务在场时按命名空间合并补丁
-  function updateUiSettings(patch) {
+  // 配置面双形态(maintain 同构,判定一律延迟到使用点,settings 挂载时序无保证):
+  // legacy(≤0.1.6)settings 服务 register/get/update 命名空间语义;
+  // 0.1.7+ 静态 Config 导出生成节表单,读经 volatile ref 解包,写经 configEditor
+  const legacySettingsFace = () => {
     const settings = ctx.get('settings')
-    if (!settings || typeof settings.update !== 'function') return false
-    settings.update(SETTINGS_NS, patch)
+    return typeof settings?.register === 'function' && typeof settings?.update === 'function'
+  }
+  // 0.1.7 写路径:configEditor.edit 定位本条目(fiber.entry,与命名空间解耦),
+  // change 回调合并落 profile patch;仅 volatile 字段变化时 loader 原地热更不重启
+  async function persistPatch(patch) {
+    if (legacySettingsFace()) {
+      await ctx.get('settings').update(SETTINGS_NS, patch)
+      return true
+    }
+    const editor = ctx.get('configEditor')
+    const entry = ctx.fiber?.entry
+    if (!editor || typeof editor.edit !== 'function' || !entry) return false
+    await editor.edit(entry, (current) => ({ ...current, ...patch }))
     return true
   }
+  // 客户端设置面板写入通道。必须 await:宿主写失败在异步段抛出(0.1.5 前
+  // settings 对未注册命名空间 "No configurable plugin entry" 实测打崩宿主),
+  // await 后异常传播到 api.handle 的路由级 catch,降级为 400 响应,宿主存活
+  async function updateUiSettings(patch) {
+    return persistPatch(patch)
+  }
   function readSettingValue(name) {
-    const settings = ctx.get('settings')
-    const scope = settings && settings.get ? settings.get(SETTINGS_NS) : undefined
-    return scope ? scope[name] : undefined
+    try {
+      const settings = ctx.get('settings')
+      // 双形读:legacy settings 命名空间;0.1.7+ apply 入参 config 整节解包
+      const scope = settings && settings.get ? settings.get(SETTINGS_NS) : unwrapVolatile(config)
+      return scope ? scope[name] : undefined
+    } catch {
+      // 与写入同防:宿主 settings 对未注册命名空间抛错时读面降级为缺省
+      return undefined
+    }
   }
   function readTickMs() {
     return Math.max(MIN_TICK_MS, readNumber('tickSeconds', DEFAULT_TICK_MS / 1000) * 1000)
@@ -183,7 +223,14 @@ export function apply(ctx, config) {
   })
 
   ctx.inject(['settings'], (sctx) => {
-    if (typeof sctx.settings.register !== 'function') return
+    // 方法面守卫:settings 服务缺 register 面(0.1.7 已移除)即走新形态分支
+    if (typeof sctx.settings.register !== 'function') {
+      // 0.1.7:原生自动设置页与本包插件卡重复,特性检测关闭(maintain 同构)
+      if (typeof sctx.settings?.configure === 'function') {
+        sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber))
+      }
+      return
+    }
     const scope = sctx.settings.register(SETTINGS_NS, SETTINGS_SCHEMA, { base: config })
     // tick 周期等设置变更即时对账(重建 interval)
     if (scope && typeof scope.watch === 'function') {

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

@@ -185,6 +185,36 @@ test('index:settings 注册 cron-board 命名空间且 timer 承载默认周期
   assert.deepEqual(intervals.map((entry) => entry.ms), [30 * 1000])
 })
 
+test('index:settings.update 异步拒绝(镜像 rc.1 无命名空间条目)被路由级 catch 接住降级 400,不打崩进程', async () => {
+  // Given settings.update 返回 rejected promise 的宿主形态(0.1.7-rc.1 L3 实测:
+  // "No configurable plugin entry 'cron-board'" 在异步段抛出,不 await 时逃逸成
+  // uncaughtException 打崩宿主;await 后由 api.handle 路由级 catch 接住)
+  const { ctx, settingsService } = makeFullCtx()
+  settingsService.update = () => Promise.reject(new Error("No configurable plugin entry 'cron-board'"))
+  delete settingsService.get
+  const captured = []
+  const ctx2 = {
+    ...ctx,
+    get(name) {
+      if (name === 'settings') return settingsService
+      return ctx.get(name)
+    },
+    webServer: { register(route) { captured.push(route); return () => {} } },
+  }
+  apply(ctx2)
+  const route = captured[0]
+  assert.ok(route)
+  const res = { status: null, payload: null }
+  res.writeHead = (status) => { res.status = status }
+  res.end = (text) => { res.payload = JSON.parse(text) }
+  const req = { method: 'POST', url: 'http://localhost/api/cron-board/ui-settings', headers: { 'content-type': 'application/json' } }
+  req.on = (event, fn) => { if (event === 'data') setImmediate(() => fn(Buffer.from(JSON.stringify({ sidebarTab: true })))); if (event === 'end') setImmediate(fn) }
+  await route.handler(req, res)
+  // Then 路由级 catch 接住,降级 400 系统级错误响应,进程存活(测试正常走完即证)
+  assert.equal(res.status, 400)
+  assert.ok(res.payload.error)
+})
+
 test('index:tickSeconds 设置变更经 watch 重建 interval', async () => {
   // Given 全服务桩,settings.register 的 watch 回调被捕获
   let watchFn = null
@@ -203,7 +233,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()
@@ -263,7 +294,188 @@ function waitForRecord(poll, timeoutMs = 10 * 1000) {
         }
         setTimeout(tick, 50)
       }).catch(reject)
+     }
+     tick()
+   })
+}
+
+// --- 0.1.7 settings 面双形适配(maintain a913c2c 同构) ---
+
+// 0.1.7 形态装配桩:settings 无 register/get(宿主已移除),config 为整节单 ref 桩,
+// configEditor 桩经 change 合并后原样写回(模拟 loader 仅 volatile 变化的原地热更)
+function makeRc17Ctx({ configStore = {}, configEditorAvailable = true, configureAvailable = true } = {}) {
+  const routes = new Map()
+  const calls = { editCalls: [], configureCalls: [], registerCalls: [] }
+  const config = { get: () => ({ ...configStore }) }
+  const settingsService = {}
+  if (configureAvailable) {
+    settingsService.configure = (presentation, owner) => {
+      calls.configureCalls.push({ presentation, owner })
+      return () => {}
     }
-    tick()
-  })
+  }
+  const configEditor = {
+    async edit(entry, change) {
+      calls.editCalls.push(entry)
+      const next = change({ ...configStore }, {})
+      for (const [key, value] of Object.entries(next)) configStore[key] = value
+    },
+  }
+  const effects = []
+  const ctx = {
+    calls,
+    fiber: { entry: { options: { id: 'cron-board', name: '@mzzsfy/dsh-cron-board' } } },
+    effect(fn, label) {
+      // 会话等待轮询为真实定时器形态:桩跳过(与 makeFullCtx 同款),其余同步执行
+      if (label === 'cron-board session wait') return
+      effects.push(fn)
+      fn()
+    },
+    get(name) {
+      if (name === 'settings') return settingsService
+      if (name === 'configEditor') return configEditorAvailable ? configEditor : undefined
+      if (name === 'agents') return { get: () => undefined }
+      if (name === 'sessionQuery') return { listSessions: async () => [] }
+      if (name === 'workspaceRegistry') return { archivedSessionIds: [] }
+      if (name === 'agentPresets') return { defaultId: '', list: async () => [] }
+      return undefined
+    },
+    inject(deps, fn) {
+      if (deps[0] === 'timer') {
+        fn({ interval(intervalFn) { return () => {} } })
+      }
+      if (deps[0] === 'settings') {
+        fn({
+          settings: settingsService,
+          effect(stubEffect) {
+            const disposer = stubEffect()
+            if (typeof disposer === 'function') effects.push(disposer)
+          },
+        })
+      }
+    },
+    webServer: {
+      register(route) {
+        routes.set(route.path, route.handler)
+        return () => {}
+      },
+    },
+  }
+  return { ctx, routes, config, configStore, calls, effects }
 }
+
+// ui-settings 请求走 prefix 路由(api.handle 按 method+segments 分发);
+// 需真实数据目录(getRuntime 装配 store),env 注入临时目录
+async function callApi(routes, path, body) {
+  const handler = routes.get('/api/cron-board')
+  assert.ok(handler, 'prefix 路由未注册')
+  const res = { status: null, payload: null }
+  res.writeHead = (status) => { res.status = status }
+  res.end = (text) => { res.payload = text ? JSON.parse(text) : null }
+  const req = new EventEmitter()
+  req.method = body === undefined ? 'GET' : 'POST'
+  req.url = 'http://localhost' + path
+  req.headers = { 'content-type': 'application/json' }
+  // 装配层初始化后才挂读体监听:桩事件须延后发射(与既有 post 桩同款)
+  setTimeout(() => {
+    if (body !== undefined) req.emit('data', Buffer.from(JSON.stringify(body)))
+    req.emit('end')
+  }, 80)
+  await handler(req, res)
+  return res
+}
+
+test('Config 导出契约:根级 volatile 包装,validate 产整节单 ref,默认值对拍', () => {
+  // Given 静态 Config 导出(0.1.7 节表单事实源)
+  assert.ok(mod.Config, 'Config 导出必须在场')
+  // When 空配置校验
+  const resolved = mod.Config['~standard'].validate({})
+  // Then 产整节单 ref(get 协议),字段为 schema 默认值
+  assert.equal(resolved.issues, undefined)
+  const section = resolved.value.get()
+  assert.equal(section.tickSeconds, 30)
+  assert.equal(section.maxConcurrent, 2)
+  assert.equal(section.logKeepPerJob, 200)
+  assert.equal(section.maskEnvInPrompt, false)
+  assert.equal(section.sidebarTab, false)
+  // When 显式值校验
+  // Then 值透传
+  const provided = mod.Config['~standard'].validate({ sidebarTab: true }).value.get()
+  assert.equal(provided.sidebarTab, true)
+})
+
+test('0.1.7 形态:ui-settings GET 读 config 节值(ref 解包),非默认值', async (t) => {
+  // Given settings 无 register/get 的宿主 + config ref 携带用户值
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-rc17-'))
+  t.after(async () => {
+    delete process.env.DSH_CRON_BOARD_DATA_DIR
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
+  process.env.DSH_CRON_BOARD_DATA_DIR = dir
+  const { ctx, routes, config } = makeRc17Ctx({ configStore: { sidebarTab: true, tickSeconds: 60 } })
+  apply(ctx, config)
+  // When GET ui-settings
+  const res = await callApi(routes, '/api/cron-board/status')
+  // Then 返回 config 节值
+  assert.equal(res.status, 200)
+  assert.equal(res.payload.ui.sidebarTab, true)
+})
+
+test('0.1.7 形态:ui-settings POST 经 configEditor.edit 落 fiber.entry 且持久合并', async (t) => {
+  // Given configEditor 桩记录 edit 调用
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-rc17-'))
+  t.after(async () => {
+    delete process.env.DSH_CRON_BOARD_DATA_DIR
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
+  process.env.DSH_CRON_BOARD_DATA_DIR = dir
+  const { ctx, routes, config, configStore, calls } = makeRc17Ctx({ configStore: { tickSeconds: 60 } })
+  apply(ctx, config)
+  // When POST 写 sidebarTab
+  const res = await callApi(routes, '/api/cron-board/ui-settings', { sidebarTab: true })
+  // Then edit 定位本条目,合并写回,响应 200 携新值
+  assert.equal(res.status, 200)
+  assert.equal(calls.editCalls.length, 1)
+  assert.equal(calls.editCalls[0].options.id, 'cron-board')
+  assert.equal(configStore.sidebarTab, true)
+  assert.equal(configStore.tickSeconds, 60)
+  assert.equal(res.payload.ui.sidebarTab, true)
+})
+
+test('0.1.7 形态:configEditor 缺失即 200 ok:false 拒写,不崩溃', async (t) => {
+  // Given configEditor 服务缺席
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-rc17-'))
+  t.after(async () => {
+    delete process.env.DSH_CRON_BOARD_DATA_DIR
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
+  process.env.DSH_CRON_BOARD_DATA_DIR = dir
+  const { ctx, routes, config } = makeRc17Ctx({ configEditorAvailable: false })
+  apply(ctx, config)
+  // When POST 写设置
+  const res = await callApi(routes, '/api/cron-board/ui-settings', { sidebarTab: true })
+  // Then ok:false 拒写(api 层 persisted=false 语义),进程存活(测试走完即证)
+  assert.equal(res.status, 200)
+  assert.equal(res.payload.ok, false)
+})
+
+test('0.1.7 形态:settings.configure 在场即关闭原生自动页,缺席静默跳过', () => {
+  // Given configure 在场
+  const { ctx, calls, config } = makeRc17Ctx()
+  apply(ctx, config)
+  // Then 关闭自动页,owner 为本插件 fiber
+  assert.deepEqual(calls.configureCalls, [{ presentation: { auto: false }, owner: ctx.fiber }])
+  // Given configure 缺席
+  const bare = makeRc17Ctx({ configureAvailable: false })
+  // When apply
+  // Then 不抛错(测试走完即证)
+  apply(bare.ctx, bare.config)
+})
+
+test('0.1.7 形态:settings 注入回调不因 register 缺失抛错', () => {
+  // Given settings 桩全空方法面(比真实宿主更严)
+  const { ctx, config } = makeRc17Ctx({ configureAvailable: false })
+  // When apply
+  // Then 注入回调静默返回,无异常
+  apply(ctx, config)
+})

package/test/routes.test.mjs

@@ -324,10 +324,11 @@ test('status 路由:ui.sidebarTab 透出用户侧边栏移入偏好', async (t)
 })
 
 test('ui-settings 路由:布尔补丁经 updateUiSettings 写入并回读', async (t) => {
-  // Given 写入桩记录补丁,读取桩翻转返回(模拟 settings.update 后生效)
+  // Given 写入桩记录补丁,读取桩翻转返回(模拟 settings.update 后生效);
+  // 写入桩 async 返回 true 镜像持久化成功契约(宿主 update 为异步面)
   let stored = false
   const { api } = await makeApi(t, {
-    updateUiSettings: (patch) => { if (typeof patch.sidebarTab === 'boolean') stored = patch.sidebarTab },
+    updateUiSettings: async (patch) => { if (typeof patch.sidebarTab === 'boolean') { stored = patch.sidebarTab; return true } return false },
     readSidebarTab: () => stored,
   })
   // When POST 开关开
@@ -465,9 +466,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 +478,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)

package/test/switch-guard.test.mjs

@@ -109,6 +109,11 @@ test('client.js 主页面双形态挂载契约(默认宿主全局面板;设置
   assert.match(source, /function CronBoardPluginCard/)
   assert.match(source, /'ui-settings'/)
   assert.match(source, /sidebarReady/)
+  // 插件管理页包详情配置卡(0.1.7-rc.1+ plugins.bundle.config,key=包名);两代槽位并存注册,
+  // 各自宿主只消费其一(旧宿主无 plugins.bundle.config 消费方,rc.1 无 settings.plugin.item 消费方)
+  assert.match(source, /const PKG_ID = '@mzzsfy\/dsh-cron-board'/)
+  assert.match(source, /ctx\.slots\.inject\('plugins\.bundle\.config'/)
+  assert.match(source, /name: 'plugins\.bundle\.config', key: PKG_ID/)
   // 挂载仲裁:偏好(status.ui.sidebarTab)驱动全局面板/扩展槽互斥
   assert.match(source, /applyPref\(\)/)
   assert.match(source, /ui\.sidebarTab/)