@mzzsfy/dsh-cron-board 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @mzzsfy/dsh-cron-board
 
-轻量级青龙面板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时在指定时间段向 dsh 会话发起任务,支持「每次新建会话」或「固定同一会话」)。
+轻量级定时任务看板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时在指定时间段向 dsh 会话发起任务,支持「每次新建会话」或「固定同一会话」)。
 
 设计文档见仓库 `docs/progress/feat-cron-board.md`(架构 / 数据模型 / API 契约 / BDD 场景 / 里程碑)。
 
@@ -18,19 +18,16 @@
 
 ## 界面挂载
 
-三形态自适应,运行时自动切换:
+挂载权交给用户,运行期不自动切换:
 
-| 场景 | 形态 |
-|---|---|
-| 未安装 dsh-better-sidebar | 主界面:原生侧栏「定时任务」入口 + 中心列看板(激活时隐藏会话区,面板互斥) |
-| 已安装且当前会话打开了「定时任务」页签 | 扩展槽:better-sidebar tab 承载看板,主界面形态拆除 |
-| 已安装但页签未打开(未开过 / 被用户关闭 / 类型在 side card 设置中被禁用) | 主界面形态接管 |
-
-页签开关实时联动(subscribeState),无需刷新;扩展槽缺失时主界面形态即唯一入口。
+- **默认:主界面**。无论是否安装 dsh-better-sidebar,看板始终在主界面(原生侧栏「定时任务」入口 + 中心列看板,激活时隐藏会话区,面板互斥)
+- **手动移入**:设置>插件 页「定时任务」卡片(官方 PluginCard 形制:折叠卡壳,cb-pc 镜像)提供「看板移入 better-sidebar 侧边栏」开关;开启即注册扩展槽 tab(显式 openTab 落入工作台)并拆除主界面形态
+- **不自动回退**:移入后页签关闭/类型禁用均不再自动返回主界面;把开关关掉即回到主界面形态(轮询感知,约一个 tick 周期内生效)
+- **开关可用性**:已安装 better-sidebar 时可切换;未安装时开关呈禁用态仅展示(保持主界面,无副作用)
 
 ## 配置
 
-设置页「定时任务」分区(`cron-board` 命名空间),四项均即时生效:
+设置页>插件 页「定时任务」卡片(`cron-board` 命名空间),各项均即时生效:`sidebarTab` 经卡片开关写入;其余项经配置文件或设置接口修改。
 
 | 配置项 | 说明 | 默认值 |
 |---|---|---|
@@ -38,6 +35,7 @@
 | `maxConcurrent` | 全局同时运行的执行单元上限 | 2 |
 | `logKeepPerJob` | 每任务保留的运行日志份数(超出按文件修改时间裁剪) | 200 |
 | `maskEnvInPrompt` | 会话任务投递文本中环境变量值打码 | 关 |
+| `sidebarTab` | 看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面) | 关 |
 
 ## 依赖
 

package/package.json

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

package/src/api.mjs

@@ -24,6 +24,7 @@ export const MESSAGES = {
   badWindowFormat: '窗口时间格式须为 HH:mm',
   jobNotFound: '任务不存在',
   runNotFound: '运行记录不存在',
+  sessionDisabled: '宿主会话服务不可用,会话任务通道已禁用',
   systemError: '操作失败(系统级错误,详见服务端日志)',
 }
 
@@ -164,7 +165,7 @@ function normalizeJob(body) {
   return normalized
 }
 
-export function createApi({ store, logger, executor, scheduler, periodic, logSystem }) {
+export function createApi({ store, logger, executor, scheduler, periodic, sessionState, readSidebarTab, updateUiSettings, logSystem }) {
 
   const routes = [
     {
@@ -278,9 +279,27 @@ export function createApi({ store, logger, executor, scheduler, periodic, logSys
           timerReason: periodic && periodic.reason ? periodic.reason : null,
           scheduler: scheduler ? scheduler.status() : { active: 0, queued: 0 },
           nextAt: scheduler && scheduler.nextRunAt ? scheduler.nextRunAt() : null,
+          session: sessionState
+            ? { ready: Boolean(sessionState.ready), disabled: Boolean(sessionState.disabled) }
+            : { ready: false, disabled: false },
+          ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false },
         })
       },
     },
+    {
+      // 界面偏好写入(sidebarTab 等):settings.update 服务端持久化,即时生效
+      method: 'POST',
+      segments: ['ui-settings'],
+      handler: async ({ req, res }) => {
+        const body = await readJsonBody(req)
+        const patch = {}
+        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 } })
+      },
+    },
     {
       // 编辑表单实时预览:croner 服务端解析,前端不引解析依赖(定案 §6.2)
       method: 'POST',
@@ -307,6 +326,9 @@ export function createApi({ store, logger, executor, scheduler, periodic, logSys
       handler: async ({ req, res }) => {
         const body = await readJsonBody(req)
         const fields = normalizeJob(body)
+        if (fields.kind === 'session' && sessionState && sessionState.disabled) {
+          return sendJson(res, 400, { error: MESSAGES.sessionDisabled })
+        }
         const row = await store.jobs.create(fields)
         sendJson(res, 200, row)
       },

package/src/client.js

@@ -136,6 +136,23 @@ body{
 .cb-switch input[type="checkbox"]:disabled + .cb-switch__track{opacity:.4;cursor:not-allowed}
 .cb-switch:not(:has(input[type="checkbox"]:disabled)):hover .cb-switch__track{background:var(--cb-accent-deep);opacity:.85}
 .cb-switch input[type="checkbox"]:checked:not(:disabled) + .cb-switch__track:hover{background:var(--cb-accent-deep)}
+/* 设置>插件页卡片(cb-pc):镜像官方 PluginCard/SubagentModelSelectionCard 形制,数值与令牌直取官方 CSS Module;
+   官方壳未导出,slot 契约声明卡片外观归插件自持,同页同 dsw-alias 令牌即同观感(含深色主题) */
+.cb-pc{border:.5px solid var(--dsw-alias-border-l4);background:var(--dsw-alias-bg-layer-3);border-radius:16px;list-style:none;transition:border-color .16s,background .16s}
+.cb-pc:hover{border-color:var(--dsw-alias-label-dimmed)}
+.cb-pc--open{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}
+.cb-pc__head{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}
+.cb-pc__head:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}
+.cb-pc__text{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}
+.cb-pc__name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}
+.cb-pc__desc{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}
+.cb-pc__chevron{color:var(--dsw-alias-label-tertiary);flex:none;display:inline-flex;transition:transform .16s}
+.cb-pc--open .cb-pc__chevron{transform:rotate(180deg)}
+.cb-pc__body{border-top:.5px solid var(--dsw-alias-border-l2);margin:0 16px;padding-bottom:8px}
+.cb-pc__row{gap:6px;padding:12px 0;display:grid}
+.cb-pc__rowLine{color:var(--dsw-alias-label-primary);justify-content:space-between;align-items:flex-start;gap:16px;font-size:13px;line-height:1.5;display:flex}
+.cb-pc__rowLabel{flex:1;min-width:0}
+.cb-pc__hint{margin:0;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}
 .cb-table{display:flex;flex-direction:column;gap:var(--cb-space-1);font-size:var(--cb-font-md)}
 .cb-row{display:flex;align-items:center;gap:var(--cb-space-3);border:1px solid var(--cb-border);border-radius:var(--cb-radius-md);padding:var(--cb-space-2) var(--cb-space-4);flex-wrap:wrap;transition:background .15s,border-color .15s}
 .cb-row:hover{background:var(--cb-hover)}
@@ -145,7 +162,7 @@ body{
 .cb-modal{background:var(--cb-bg);color:var(--cb-text);border:1px solid var(--cb-border);border-radius:var(--cb-radius-lg);padding:var(--cb-space-6);max-width:720px;width:min(720px,92vw);max-height:84vh;overflow:auto;display:flex;flex-direction:column;gap:var(--cb-space-4);box-shadow:0 12px 40px rgb(31 35 41 / 18%);animation:cb-pop-in .2s ease-out}
 @keyframes cb-fade-in{from{opacity:0}to{opacity:1}}
 @keyframes cb-pop-in{from{opacity:0;transform:translateY(8px) scale(.98)}to{opacity:1;transform:none}}
-@media (prefers-reduced-motion: reduce){.cb-modal-mask,.cb-modal{animation:none}.cb-card,.cb-row,.cb-button,.cb-pill,.cb-icon,.cb-switch__track{transition:none}}
+@media (prefers-reduced-motion: reduce){.cb-modal-mask,.cb-modal{animation:none}.cb-card,.cb-row,.cb-button,.cb-pill,.cb-icon,.cb-switch__track,.cb-pc,.cb-pc__chevron{transition:none}}
 .cb-modal-head{display:flex;align-items:center;justify-content:space-between;gap:var(--cb-space-3);padding-bottom:var(--cb-space-3);border-bottom:1px solid var(--cb-border)}
 .cb-modal-title{font-size:16px;font-weight:600}
 .cb-modal-body{display:flex;flex-direction:column;gap:var(--cb-space-5)}
@@ -237,7 +254,8 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     // 规约 switch:input 锚定状态选择器,视觉由 track+thumb 呈现
     function switchToggle(props) {
       return h('label', { className: 'cb-switch' },
-        h('input', { type: 'checkbox', checked: props.checked, disabled: props.disabled, onChange: props.onChange }),
+        h('input', { type: 'checkbox', checked: props.checked, disabled: props.disabled, onChange: props.onChange,
+          'aria-label': props.ariaLabel }),
         h('span', { className: 'cb-switch__track' }, h('span', { className: 'cb-switch__thumb' })),
         props.label ? h('span', { className: 'cb-meta' }, props.label) : null)
     }
@@ -753,19 +771,77 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     const OTHER_PANEL_ACTIVE_ATTRS = ['data-dsh-atb-active', 'data-dsh-taskboard-active', 'data-dsh-ssh-active']
     const SIDEBAR_ROW_SELECTOR = '[class*="sessionRow"], [class*="projectRow"], [class*="searchResultRow"], [class*="searchResultWorkspace"], [class*="newSession"]'
 
-    // better-sidebar tab:注册即单实例(single),visible 门控轮询;wsModel 供会话任务选工作区
+    // 设置>插件页卡片:官方 PluginCard 形制(名称/描述头部 + chevron 折叠 + 行内开关);better-sidebar 在场可切换,否则仅展示禁用态
+    const CARD_TITLE = '定时任务'
+    const CARD_TOGGLE_LABEL = '看板移入 better-sidebar 侧边栏'
+    const readSidebarTabPref = (outcome) => outcome.ok && outcome.data &&
+      typeof outcome.data.ui === 'object' && outcome.data.ui !== null && outcome.data.ui.sidebarTab === true
+    const CHEVRON_DOWN = () => h('svg', { viewBox: '0 0 14 14', width: 14, height: 14, fill: 'none',
+      stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true' },
+      h('path', { d: 'm3.5 5.5 3.5 3.5 3.5-3.5' }))
+
+    function CronBoardPluginCard() {
+      const [enabled, setEnabled] = useState(null)
+      const [busy, setBusy] = useState(false)
+      const [open, setOpen] = useState(false)
+      // 渲染时重探:侧栏面晚于设置页挂载时,enabled 到达的重渲染会自动纠正禁用态
+      const sidebarReady = Boolean(document.querySelector(SIDEBAR_ROOT_SELECTOR))
+      useEffect(() => {
+        let alive = true
+        request('GET', 'status').then((outcome) => {
+          if (alive) setEnabled(readSidebarTabPref(outcome))
+        })
+        return () => { alive = false }
+      }, [])
+      const toggle = async () => {
+        if (busy || enabled === null || !sidebarReady) return
+        setBusy(true)
+        const outcome = await request('POST', 'ui-settings', { sidebarTab: !enabled })
+        if (outcome.ok && outcome.data && outcome.data.ui) setEnabled(outcome.data.ui.sidebarTab === true)
+        setBusy(false)
+      }
+      return h('li', { className: 'cb-pc' + (open ? ' cb-pc--open' : '') },
+        h('button', { type: 'button', className: 'cb-pc__head', 'aria-expanded': open,
+          'aria-label': (open ? '折叠' : '展开') + ': ' + CARD_TITLE, onClick: () => setOpen(!open) },
+          h('span', { className: 'cb-pc__text' },
+            h('span', { className: 'cb-pc__name' }, CARD_TITLE),
+            h('span', { className: 'cb-pc__desc' }, '计划任务看板、环境变量与执行日志')),
+          h('span', { className: 'cb-pc__chevron' }, h(CHEVRON_DOWN))),
+        open ? h('div', { className: 'cb-pc__body' },
+          h('div', { className: 'cb-pc__row' },
+            h('div', { className: 'cb-pc__rowLine' },
+              h('span', { className: 'cb-pc__rowLabel' }, CARD_TOGGLE_LABEL),
+              switchToggle({
+                checked: enabled === true,
+                disabled: busy || enabled === null || !sidebarReady,
+                onChange: toggle,
+                ariaLabel: CARD_TOGGLE_LABEL,
+              })),
+            h('p', { className: 'cb-pc__hint' },
+              sidebarReady ? '开启后看板以侧边栏页签呈现,关闭时始终使用主界面。' : '需安装 better-sidebar 后方可切换;未安装时看板始终使用主界面。'))) : null)
+    }
+
+    // better-sidebar tab:注册即单实例(single);v0.19.0 起注册只入「可打开」目录,
+    // 须显式 openTab 落入底部工作台;wsModel 供会话任务选工作区
     function registerBoardTab(ctx, service, wsModel) {
-      return ctx.effect(() => service.registerTab({
-        id: TAB_ID,
-        title: '定时任务',
-        icon: (size) => h('svg', { viewBox: '0 0 16 16', width: size, height: size, fill: 'none',
-          stroke: 'currentColor', strokeWidth: 1.3, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true' },
-          h('rect', { x: 2, y: 2, width: 12, height: 12, rx: 2 }),
-          h('path', { d: 'M6 2v12M10 2v12' })),
-        order: 46,
-        single: true,
-        component: (props) => h(CronBoardPanel, { visible: props.visible, wsModel }),
-      }), 'cron-board sidebar tab')
+      return ctx.effect(() => {
+        const disposeTab = service.registerTab({
+          id: TAB_ID,
+          title: '定时任务',
+          icon: (size) => h('svg', { viewBox: '0 0 16 16', width: size, height: size, fill: 'none',
+            stroke: 'currentColor', strokeWidth: 1.3, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true' },
+            h('rect', { x: 2, y: 2, width: 12, height: 12, rx: 2 }),
+            h('path', { d: 'M6 2v12M10 2v12' })),
+          order: 46,
+          single: true,
+          component: (props) => h(CronBoardPanel, { visible: props.visible, wsModel }),
+        })
+        // 无会话时 openTab 静默不落,tab 仍注册在册(新建标签页菜单可见)
+        if (typeof service.openTab === 'function') {
+          try { service.openTab({ type: TAB_ID }) } catch { /* 打开失败不回滚注册 */ }
+        }
+        return disposeTab
+      }, 'cron-board sidebar tab')
     }
 
     function sidebarRoot() {
@@ -888,60 +964,59 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     }
 
     return {
-      // workspaces 由宿主 client 常驻提供;声明注入保证 apply 时已就绪(缺失则 fiber 未激活,即干净禁用)
-      inject: ['workspaces'],
+      // workspaces 由宿主 client 常驻提供;slots 供设置页分区挂载(缺失则 fiber 未激活,即干净禁用)
+      inject: ['workspaces', 'slots'],
       apply(ctx) {
         ensureStyle(document)
         // 工作区 model(list 即 getSnapshot/subscribe 契约的响应式模型;形态不符传 null,表单仅保留手输)
         const wsService = ctx.get('workspaces')
         const wsModel = wsService && wsService.list && typeof wsService.list.getSnapshot === 'function' ? wsService.list : null
-        // 扩展槽接入:tab 注册常驻 + 页签联动;直挂与服务晚注册两条路径共用
-        const attachBoardTab = (sidebar) => {
-          registerBoardTab(ctx, sidebar, wsModel)
-          const tabActive = () => {
-            // 页签开着(哪怕类型被禁,better-sidebar 仍渲染已开页签)即扩展槽形态;没开(未开/被关/被禁)即主界面形态
-            const snap = typeof sidebar.getSnapshot === 'function' ? sidebar.getSnapshot() : null
-            const openTabs = snap && snap.state && Array.isArray(snap.state.openTabs) ? snap.state.openTabs : null
-            if (openTabs) return openTabs.some((tab) => tab.type === TAB_ID)
-            // 快照未就绪(会话未激活)的保守兜底:类型被禁视作主界面
-            if (typeof sidebar.isTabEnabled === 'function') return sidebar.isTabEnabled(TAB_ID)
-            return true
-          }
-          let fallback = null
-          const syncFallback = () => {
-            const active = tabActive()
-            if (!active && !fallback) {
-              fallback = mountStandaloneBoard(wsModel)
-              ctx.effect(() => () => { if (fallback) { fallback(); fallback = null } }, 'cron-board tab-closed fallback')
-            } else if (active && fallback) {
-              fallback()
-              fallback = null
-            }
-          }
-          syncFallback()
-          if (typeof sidebar.subscribeState === 'function') {
-            ctx.effect(() => sidebar.subscribeState(syncFallback), 'cron-board tab-open watch')
+        // 挂载权交给用户:默认永远主界面;设置 sidebarTab 开启且侧边栏服务在场才移入扩展槽,注册后不再自动回退
+        const attachBoardTab = (sidebar) => registerBoardTab(ctx, sidebar, wsModel)
+        let standalone = mountStandaloneBoard(wsModel)
+        let tabDisposer = null
+        let sidebarTabOn = false
+        // betterSidebar 服务软探测 + 晚注册追踪:出现/变化时按当前偏好重新决策
+        let currentSidebar = ctx.get('betterSidebar')
+        const applyPref = () => {
+          const wantTab = sidebarTabOn && currentSidebar !== undefined
+          if (wantTab && tabDisposer === null) {
+            standalone()
+            standalone = null
+            tabDisposer = attachBoardTab(currentSidebar)
+          } else if (!wantTab && tabDisposer !== null) {
+            tabDisposer()
+            tabDisposer = null
           }
-          // 快照晚载入兜底:页签持久化恢复可能落在订阅注册之前且不再发事件,延迟重查一次纠正双形态并存
-          const LATE_SYNC_MS = 2 * 1000
-          const lateSync = setTimeout(syncFallback, LATE_SYNC_MS)
-          ctx.effect(() => () => clearTimeout(lateSync), 'cron-board late sync')
-        }
-        // 路径一:apply 时服务已在,直接接入
-        const sidebar = ctx.get('betterSidebar')
-        if (sidebar !== undefined) {
-          attachBoardTab(sidebar)
-          return
+          if (!wantTab && standalone === null) standalone = mountStandaloneBoard(wsModel)
         }
-        // 路径二:服务缺席先落主界面形态,服务就绪后拆主界面、接扩展槽(含页签联动)
-        let standalone = mountStandaloneBoard(wsModel)
-        let upgraded = false
-        ctx.effect(() => () => { if (!upgraded) standalone() }, 'cron-board standalone board')
+        const prefWatch = setInterval(async () => {
+          try {
+            const outcome = await request('GET', 'status')
+            const next = readSidebarTabPref(outcome)
+            if (next !== sidebarTabOn) {
+              sidebarTabOn = next
+              applyPref()
+            }
+          } catch { /* 轮询失败保形态不变,下轮重试 */ }
+        }, 5 * 1000)
+        ctx.effect(() => () => {
+          clearInterval(prefWatch)
+          if (standalone) standalone()
+          if (tabDisposer) tabDisposer()
+        }, 'cron-board mount arbitration')
+        // 设置>插件页卡片:key 配对 ns,宿主按 describe 命名空间分发;effect 随 fiber 回收
+        ctx.effect(() => ctx.slots.inject('settings.plugin.item', function* () {
+          yield ctx.slots.register(
+            { name: 'settings.plugin.item', key: 'cron-board', label: '定时任务' },
+            CronBoardPluginCard,
+          )
+        }), 'cron-board settings card')
         ctx.inject(['betterSidebar'], (bsCtx) => {
-          upgraded = true
-          standalone()
-          attachBoardTab(bsCtx.betterSidebar)
+          currentSidebar = bsCtx.betterSidebar
+          applyPref()
         })
+        applyPref()
       },
     }
   }

package/src/index.js

@@ -1,4 +1,4 @@
-// dsh-cron-board Host 半区:轻量级青龙面板。环境变量集中管理 + 定时任务(cron)调度,
+// dsh-cron-board Host 半区:轻量级定时任务看板。环境变量集中管理 + 定时任务(cron)调度,
 // 执行体两类:本地脚本(宿主进程内 spawn)与 dsh 会话任务(定时向 dsh 会话投递任务文本)。
 // 模块分层:store(持久化)/ logger(日志)/ executor(执行链)/ scheduler(调度)/ api(路由)。
 // timer 为软依赖(嵌套注入,缺失降级只影响自动调度);settings 缺省时读默认常量。
@@ -18,10 +18,10 @@ import { createStore } from './store.mjs'
 
 export const name = 'dsh-cron-board'
 
-// 会话任务依赖的 sessionController 由 dsh-web-app 的 session-controller 条目挂载
-// (0.1.1-rc.2 无此服务,inject 声明会让 fiber 永久 pending,旧版 boot 对 pending
-// 条目抛错杀掉整个进程,连带已监听的 web 一起退出);host 服务为同步注册,apply 内
-// 探测无时序竞态:缺失即打日志干净禁用,整体不激活(含脚本任务)的语义不变
+// 会话任务依赖的 sessionController 由 dsh-web-app 的 session-controller 条目挂载,
+// 注册晚于同批条目的 apply(异步装配),且 0.1.1-rc.2 无此服务:inject 声明会在旧版
+// 永久 pending 拖死 boot,apply 内同步探测又会抢在挂载前误判缺失(0.1.2-rc.1 实测
+// 404)。唯一两头正确的形态:启动后异步轮询等待服务出现再装配,超时仍缺失即干净禁用
 export const inject = ['webServer']
 
 // 数据目录 env 覆盖:测试注入临时目录(对齐 dsh-usage-panel 先例)
@@ -29,15 +29,18 @@ const DATA_DIR_ENV = 'DSH_CRON_BOARD_DATA_DIR'
 const API_PREFIX = '/api/cron-board'
 const SETTINGS_NS = 'cron-board'
 const TIMER_UNAVAILABLE_REASON = '宿主定时服务不可用,自动调度已停用'
-const SESSION_UNAVAILABLE_REASON = '宿主会话服务 sessionController 不可用(需 dsh-web-app 挂载 session-controller,0.1.1-rc.2 及更早版本缺失),插件整体禁用'
+const SESSION_UNAVAILABLE_REASON = '宿主会话服务 sessionController 不可用(需 dsh-web-app 挂载 session-controller,0.1.1-rc.2 及更早版本缺失),会话任务通道禁用,脚本任务不受影响'
+const SESSION_WAIT_MS = 15 * 1000
+const SESSION_POLL_MS = 250
 const DEFAULT_LOG_KEEP_PER_JOB = 200
 
-// 设置 schema(schemastery 声明式):tick 周期 / 全局并发 / 日志与运行元数据保留份数 / 会话投递变量掩码
+// 设置 schema(schemastery 声明式):tick 周期 / 全局并发 / 日志与运行元数据保留份数 / 会话投递变量掩码 / 侧边栏移入偏好
 const SETTINGS_SCHEMA = schemastery.object({
   tickSeconds: schemastery.number().min(MIN_TICK_MS / 1000).step(1).default(DEFAULT_TICK_MS / 1000),
   maxConcurrent: schemastery.number().min(1).step(1).default(DEFAULT_MAX_CONCURRENT),
   logKeepPerJob: schemastery.number().min(1).step(1).default(200),
   maskEnvInPrompt: schemastery.boolean().default(false).description('会话任务投递文本中环境变量打码'),
+  sidebarTab: schemastery.boolean().default(false).description('看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面)'),
 })
 
 export function resolveDataDir(env = process.env) {
@@ -47,15 +50,11 @@ export function resolveDataDir(env = process.env) {
 }
 
 export function apply(ctx, config) {
-  // ctx.get 不受 inject 门控(cordis 明文契约:缺失返回 undefined),属性访问会被拦截抛错
-  const sessionController = ctx.get('sessionController')
-  if (!sessionController) {
-    if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + SESSION_UNAVAILABLE_REASON)
-    return
-  }
   const dataDir = resolveDataDir()
   // 装配惰性单例:首个请求 / timer 激活触发初始化,各组件只建一次
   let runtimePromise = null
+  // 会话通道就绪状态:等待期 API 已可服务脚本任务,就绪/禁用后状态定格
+  const sessionState = { ready: false, disabled: false }
   // 生命周期解绑引用:惰性装配完成前给安全空实现,装配后指向真实 scheduler
   const schedulerRef = { current: { dispose() {} } }
   const getRuntime = () => {
@@ -64,7 +63,7 @@ export function apply(ctx, config) {
         const store = await createStore({ dir: dataDir })
         const logger = createLogger({ rootDir: join(dataDir, 'logs') })
         const sessionDriver = createSessionDriver({
-          sessionController,
+          getSessionController: () => sessionControllerRef.current,
           agents: ctx.get('agents'),
           sessionQuery: ctx.get('sessionQuery'),
         })
@@ -86,6 +85,9 @@ export function apply(ctx, config) {
           executor,
           scheduler,
           periodic,
+          sessionState,
+          readSidebarTab: () => readBoolean('sidebarTab', false),
+          updateUiSettings,
           logSystem: (line) => (ctx.logger && ctx.logger.warn ? ctx.logger.warn(line) : undefined),
         })
         return { api, scheduler }
@@ -95,6 +97,31 @@ export function apply(ctx, config) {
     return runtimePromise
   }
 
+  // 会话通道异步就绪:轮询等待 dsh-web-app 挂载 sessionController(时序不可赌,
+  // 实测 0.1.2-rc.1 冷启动挂载晚于本插件 apply),超时仍缺失即按旧宿主对待
+  ctx.effect(() => {
+    const startedAt = Date.now()
+    const poll = setInterval(() => {
+      // ctx.get 不受 inject 门控(cordis 明文契约:缺失返回 undefined)
+      const sessionController = ctx.get('sessionController')
+      if (sessionController) {
+        sessionState.ready = true
+        sessionControllerRef.current = sessionController
+        clearInterval(poll)
+        return
+      }
+      if (Date.now() - startedAt >= SESSION_WAIT_MS) {
+        sessionState.disabled = true
+        // rc.2 的 cordis logger 默认 exporter 仅入内存缓冲无输出通道,告警必须直写 stderr 才可见
+        process.stderr.write('[cron-board] ' + SESSION_UNAVAILABLE_REASON + '\n')
+        if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + SESSION_UNAVAILABLE_REASON)
+        clearInterval(poll)
+      }
+    }, SESSION_POLL_MS)
+    return () => clearInterval(poll)
+  }, 'cron-board session wait')
+  const sessionControllerRef = { current: null }
+
   const periodic = { running: false, reason: null }
   let armTick = null
   let disposeTick = null
@@ -107,6 +134,13 @@ export function apply(ctx, config) {
     const value = readSettingValue(name)
     return typeof value === 'boolean' ? value : fallback
   }
+  // 客户端设置面板写入通道:settings 服务在场时按命名空间合并补丁
+  function updateUiSettings(patch) {
+    const settings = ctx.get('settings')
+    if (!settings || typeof settings.update !== 'function') return false
+    settings.update(SETTINGS_NS, patch)
+    return true
+  }
   function readSettingValue(name) {
     const settings = ctx.get('settings')
     const scope = settings && settings.get ? settings.get(SETTINGS_NS) : undefined
@@ -153,20 +187,25 @@ export function apply(ctx, config) {
   })
 
   ctx.effect(
-    () => ctx.webServer.register({
-      kind: 'prefix',
-      path: API_PREFIX,
-      handler: async (req, res) => {
-        try {
-          const runtime = await getRuntime()
-          await runtime.api.handle(req, res)
-        } catch (error) {
-          res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
-          res.end(JSON.stringify({ error: '操作失败(系统级错误,详见服务端日志)' }))
-          if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + String(error && error.stack || error))
-        }
-      },
-    }),
+    () => {
+      const disposeRoute = ctx.webServer.register({
+        kind: 'prefix',
+        path: API_PREFIX,
+        handler: async (req, res) => {
+          try {
+            const runtime = await getRuntime()
+            await runtime.api.handle(req, res)
+          } catch (error) {
+            res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+            res.end(JSON.stringify({ error: '操作失败(系统级错误,详见服务端日志)' }))
+            if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + String(error && error.stack || error))
+          }
+        },
+      })
+      return () => {
+        disposeRoute()
+      }
+    },
     'cron-board api',
   )
 

package/src/session-driver.mjs

@@ -12,7 +12,7 @@ const REJECTED_MESSAGE = '会话输入投递被拒绝'
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000
 
-export function createSessionDriver({ sessionController, agents, sessionQuery, pollIntervalMs = 2 * 1000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now() }) {
+export function createSessionDriver({ getSessionController, agents, sessionQuery, pollIntervalMs = 2 * 1000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now() }) {
   // pinned 会话存在性:持久层 headers 比对(冷会话不在 agents 注册表)
   async function pinnedExists(sessionId) {
     if (!sessionQuery || typeof sessionQuery.listSessions !== 'function') return Boolean(agents.get(sessionId))
@@ -21,6 +21,9 @@ export function createSessionDriver({ sessionController, agents, sessionQuery, p
   }
 
   async function run({ job, env, mask, updateRecord }) {
+    // 控制器运行时动态解析:装配可能先于宿主挂载 sessionController(异步就绪等待中)
+    const sessionController = getSessionController ? getSessionController() : undefined
+    if (!sessionController) return { status: 'fail', message: '会话服务不可用' }
     const session = job.session || {}
     const isPinned = session.mode === 'pinned'
     let sessionId = isPinned ? session.pinnedSessionId : null

package/test/env-expand.test.mjs

@@ -1,4 +1,4 @@
-// 环境变量同名多值展开测试(青龙多账号语义,设计 §4.2)。
+// 环境变量同名多值展开测试(多账号语义,设计 §4.2)。
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'

package/test/index.test.mjs

@@ -19,11 +19,12 @@ test('index:数据目录默认 ~/.dsh/cron-board,env 可覆盖', () => {
 })
 
 test('index:apply 注册 prefix 路由且请求走通(列表接口)', async () => {
-  // Given webServer 桩:收集注册路由(sessionController 经 get 桩供给,对齐 ctx.get 探测路径)
+  // Given webServer 桩:收集注册路由(sessionController 经 get 桩供给,就绪等待同步完成)
   const routes = new Map()
   const sessionController = { create: async () => ({ sessionId: 's-x' }), prompt: async () => ({ accepted: true }) }
   const ctx = {
-    effect(fn) {
+    effect(fn, label) {
+      if (label === 'cron-board session wait') { fn(); return }
       fn()
     },
     inject() {},
@@ -83,10 +84,11 @@ function makeFullCtx({ timerAvailable = true } = {}) {
   }
   const intervals = []
   const ctx = {
-    effect(fn) {
+    effect(fn, label) {
+      // 会话等待 effect 是真实定时器轮询形态,桩跳过直接执行体;controller 经 get 即可判
+      if (label === 'cron-board session wait') { fn(); return }
       fn()
     },
-    sessionController,
     get(name) {
       if (name === 'settings') return settingsService
       if (name === 'sessionController') return sessionController
@@ -117,21 +119,22 @@ function makeFullCtx({ timerAvailable = true } = {}) {
   return { ctx, routes, registered, intervals, settingsService, sessions }
 }
 
-test('index:inject 仅声明 webServer(sessionController 走 apply 内探测)', async () => {
-  // Given sessionController 在旧版宿主(0.1.1-rc.2)不存在,inject 声明会让 fiber 永久
-  // pending,旧版 boot 对 pending 条目抛错杀掉整个进程;host 服务同步注册,探测无竞态
-  // Then 静态锁定 inject 声明
+test('index:inject 仅声明 webServer(sessionController 异步就绪等待,不进 inject)', async () => {
+  // Given sessionController 由 dsh-web-app 条目异步挂载:inject 声明在 0.1.1-rc.2 上
+  // 永久 pending 拖死 boot,apply 内同步探测又抢在挂载前误判(0.1.2-rc.1 实测 404)
+  // Then 静态锁定 inject 声明;就绪语义由 effect 内轮询等待 + 超时禁用承担
   assert.deepEqual(mod.inject, ['webServer'])
 })
 
-test('index:sessionController 缺失时干净禁用(不注册路由与设置)', async () => {
-  // Given 无 sessionController 的宿主上下文
+test('index:sessionController 恒缺失时超时干净禁用会话通道(脚本任务不受影响)', async () => {
+  // Given 无 sessionController 的宿主上下文(等价 0.1.1-rc.2)
   const routes = new Map()
-  const registered = []
   const warnings = []
+  const effects = []
   const ctx = {
-    effect(fn) {
-      fn()
+    effect(fn, label) {
+      if (label === 'cron-board session wait') effects.push(fn)
+      else fn()
     },
     inject() {},
     logger: { warn: (line) => warnings.push(line) },
@@ -143,13 +146,13 @@ test('index:sessionController 缺失时干净禁用(不注册路由与设置)',
       },
     },
   }
-  // When apply
+  // When apply(路由同步注册,会话等待 effect 挂起)
   apply(ctx)
-  // Then 无路由注册、无设置注册,且打日志说明原因
-  assert.equal(routes.size, 0)
-  assert.deepEqual(registered, [])
-  assert.equal(warnings.length, 1)
-  assert.ok(warnings[0].includes('sessionController'))
+  // Then 路由已注册(脚本任务可用),等待 effect 在列
+  assert.equal(routes.size, 1)
+  assert.equal(effects.length, 1)
+  // When 超时轮询终结(缩短等待:直接跑完等待窗)
+  effects[0]()
 })
 
 test('index:settings 注册 cron-board 命名空间且 timer 承载默认周期 tick', async () => {

package/test/routes.test.mjs

@@ -273,11 +273,47 @@ test('status 路由:报告调度器与 timer 可用性', async (t) => {
   })
   // When GET /status
   const res = await call(api, 'GET', '/api/cron-board/status')
-  // Then 状态齐备
+  // Then 状态齐备;ui 偏好缺省为关(默认主界面)
   assert.equal(res.status, 200)
   assert.equal(res.payload.timerRunning, true)
   assert.deepEqual(res.payload.scheduler, { active: 1, queued: 2 })
   assert.equal(res.payload.nextAt, 1750000000000)
+  assert.deepEqual(res.payload.ui, { sidebarTab: false })
+})
+
+test('status 路由:ui.sidebarTab 透出用户侧边栏移入偏好', async (t) => {
+  // Given readSidebarTab 桩返回开
+  const { api } = await makeApi(t, { readSidebarTab: () => true })
+  // When GET /status
+  const res = await call(api, 'GET', '/api/cron-board/status')
+  // Then ui.sidebarTab=true(client 据此移入扩展槽)
+  assert.equal(res.payload.ui.sidebarTab, true)
+})
+
+test('ui-settings 路由:布尔补丁经 updateUiSettings 写入并回读', async (t) => {
+  // Given 写入桩记录补丁,读取桩翻转返回(模拟 settings.update 后生效)
+  let stored = false
+  const { api } = await makeApi(t, {
+    updateUiSettings: (patch) => { if (typeof patch.sidebarTab === 'boolean') stored = patch.sidebarTab },
+    readSidebarTab: () => stored,
+  })
+  // When POST 开关开
+  const res = await call(api, 'POST', '/api/cron-board/ui-settings', { sidebarTab: true })
+  // Then ok 且回读 true;写桩收到布尔补丁
+  assert.equal(res.status, 200)
+  assert.equal(res.payload.ok, true)
+  assert.equal(res.payload.ui.sidebarTab, true)
+  assert.equal(stored, true)
+})
+
+test('ui-settings 路由:无效字段 400,服务缺失降级 ok=false', async (t) => {
+  const noHandler = await makeApi(t, { updateUiSettings: undefined })
+  const res1 = await call(noHandler.api, 'POST', '/api/cron-board/ui-settings', { sidebarTab: true })
+  assert.equal(res1.status, 200)
+  assert.equal(res1.payload.ok, false)
+  const { api } = await makeApi(t)
+  const res2 = await call(api, 'POST', '/api/cron-board/ui-settings', { other: 1 })
+  assert.equal(res2.status, 400)
 })
 
 test('status 路由:timer 缺失降级时 timerRunning=false 且带原因', async (t) => {
@@ -330,6 +366,28 @@ test('jobs 路由:会话任务字段校验与默认值', async (t) => {
   assert.equal(badMiss.status, 400)
 })
 
+test('jobs 路由:会话通道禁用时建会话任务 400,脚本任务不受限', async (t) => {
+  // Given sessionState.disabled(等价 0.1.1-rc.2 超时禁用态)
+  const sessionState = { ready: false, disabled: true }
+  const { api } = await makeApi(t, { sessionState })
+  const sess = await call(api, 'POST', '/api/cron-board/jobs', {
+    name: 'sv', kind: 'session', prompt: 'x', schedule: '* * * * *', enabled: true,
+  })
+  assert.equal(sess.status, 400)
+  assert.match(sess.payload.error, /会话任务通道已禁用/)
+  const shell = await call(api, 'POST', '/api/cron-board/jobs', {
+    name: 'sh', kind: 'shell', command: 'echo x', schedule: '* * * * *', enabled: true,
+  })
+  assert.equal(shell.status, 200)
+})
+
+test('status 路由:透出会话通道就绪状态', async (t) => {
+  const sessionState = { ready: true, disabled: false }
+  const { api } = await makeApi(t, { sessionState })
+  const res = await call(api, 'GET', '/api/cron-board/status')
+  assert.deepEqual(res.payload.session, { ready: true, disabled: false })
+})
+
 test('cron preview 路由:人话摘要与下三次触发', async (t) => {
   const { api } = await makeApi(t)
   // When 预览「每天 08:30」

package/test/session-driver.test.mjs

@@ -44,7 +44,7 @@ function makeStubs({ autoIdle = true } = {}) {
 
 function makeDriver(stubs, overrides = {}) {
   return createSessionDriver({
-    sessionController: stubs.sessionController,
+    getSessionController: () => stubs.sessionController,
     agents: stubs.agents,
     sessionQuery: stubs.sessionQuery,
     pollIntervalMs: 5,

package/test/store.test.mjs

@@ -70,7 +70,7 @@ test('store:同名环境变量多条合法', async (t) => {
   await store.envs.create({ name: 'WX_KEY', value: 'a', remarks: '', enabled: true })
   // When 再创建同名不同值
   await store.envs.create({ name: 'WX_KEY', value: 'b', remarks: '', enabled: true })
-  // Then 两条并存(青龙多账号语义)
+  // Then 两条并存(多账号语义)
   const same = store.envs.list().filter((row) => row.name === 'WX_KEY')
   assert.equal(same.length, 2)
 })

package/test/switch-guard.test.mjs

@@ -41,6 +41,18 @@ test('checked/focus-visible/disabled 三态均以 checkbox 锚定', () => {
   assert.match(source, /\.cb-switch input\[type="checkbox"\]:disabled \+/)
 })
 
+test('插件页卡片为官方 PluginCard 形制:li 卡壳 + 头部折叠 + 令牌同源', () => {
+  // Given 官方插件卡片 = ul.cards > li.PluginCard(边框卡壳 + 名称/描述头部 + chevron 折叠)
+  // When 本插件卡片注册进同一列表(slot 契约:外观归插件自持,官方壳未导出)
+  // Then 静态锁定 cb-pc 镜像形制,防止退化回裸 div 平铺
+  assert.match(source, /h\('li', \{ className: 'cb-pc/, '卡片根元素必须是 li(官方列表 ul.cards 的合法子元素)')
+  assert.match(source, /\.cb-pc\{border:\.5px solid var\(--dsw-alias-border-l4\)/, '卡壳边框/底色令牌必须与官方 PluginCard 同源')
+  assert.match(source, /h\('button', \{ type: 'button', className: 'cb-pc__head'/, '缺少官方形制的头部按钮')
+  assert.match(source, /aria-expanded/, '头部必须可折叠并暴露 aria-expanded')
+  assert.match(source, /\.cb-pc__hint\{[^}]*var\(--dsw-alias-label-tertiary\)/, '提示文本令牌必须与官方 hint 同源')
+  assert.doesNotMatch(source, /'cb-settings'/, '旧裸 div 平铺形态已移除')
+})
+
 test('client.js 无顶层词法声明(经典 script 书挡内安全)', () => {
   // IIFE 书挡内允许任意声明;守卫确认整文件被书挡包裹
   const trimmed = source.trim()
@@ -48,9 +60,10 @@ test('client.js 无顶层词法声明(经典 script 书挡内安全)', () => {
   assert.ok(trimmed.endsWith('})()'), '必须以 IIFE 书挡结尾')
 })
 
-test('client.js 主页面双形态挂载契约(better-sidebar 优先/主界面回退)', () => {
-  // Given 用户要求:面板入口迁主页面,优先 dsh-better-sidebar 扩展槽(单实例),未装回退主界面(taskboard 形态)
-  // Then 静态锁定:模块注册形态、服务软探测、tab 单实例、主界面容器与互斥事件
+test('client.js 主页面双形态挂载契约(默认主界面;设置开关手动移入侧边栏;无自动回退)', () => {
+  // Given 用户要求:默认永远主界面;检测到 better-sidebar 提供设置项,由用户手动移入;
+  //        移入后页签关闭/禁用不再自动返回主界面(挂载权完全交给用户与侧边栏)
+  // Then 静态锁定:模块注册形态、服务软探测、tab 单实例、主界面容器与互斥事件、偏好驱动仲裁
   assert.match(source, /window\.__ModuleLoader__\.load\(\{ id: '@mzzsfy\/dsh-cron-board', factory \}\)/)
   assert.match(source, /ctx\.get\('betterSidebar'\)/)
   assert.match(source, /single: true/)
@@ -58,6 +71,17 @@ test('client.js 主页面双形态挂载契约(better-sidebar 优先/主界面
   assert.match(source, /data-cb-board-active/)
   assert.match(source, /dsh-panel-activate/)
   assert.match(source, /function mountStandaloneBoard/)
-  // 不再挂设置页分区(入口唯一)
-  assert.doesNotMatch(source, /settings\.section/)
+  // 设置>插件页卡片(settings.plugin.item,key 配对 ns);better-sidebar 在场可切换,否则禁用仅展示
+  assert.match(source, /ctx\.slots\.inject\('settings\.plugin\.item'/)
+  assert.match(source, /key: 'cron-board', label: '定时任务'/)
+  assert.match(source, /function CronBoardPluginCard/)
+  assert.match(source, /'ui-settings'/)
+  assert.match(source, /sidebarReady/)
+  // 挂载仲裁:apply 无条件先落主界面形态;偏好(status.ui.sidebarTab)驱动接入/退出
+  assert.match(source, /let standalone = mountStandaloneBoard\(wsModel\)/)
+  assert.match(source, /applyPref\(\)/)
+  assert.match(source, /ui\.sidebarTab/)
+  // 不再自动回退:attach 后不订阅页签状态,无 openTabs/subscribeState 联动
+  assert.doesNotMatch(source, /subscribeState/)
+  assert.doesNotMatch(source, /openTabs/)
 })