@mzzsfy/dsh-cron-board 0.3.1 → 0.4.0

package/README.md

@@ -18,12 +18,12 @@
 
 ## 界面挂载
 
-挂载权交给用户,运行期不自动切换:
+挂载走宿主官方契约(main 全局面板插槽 / sidebar.panellist 侧栏面板行 / better-sidebar 服务),不刮宿主 DOM,宿主 UI 变动由契约消化:
 
-- **默认:主界面**。无论是否安装 dsh-better-sidebar,看板始终在主界面(原生侧栏「定时任务」入口 + 中心列看板,激活时隐藏会话区,面板互斥)
-- **手动移入**:设置>插件 页「定时任务」卡片(官方 PluginCard 形制:折叠卡壳,cb-pc 镜像)提供「看板移入 better-sidebar 侧边栏」开关;开启即注册扩展槽 tab(显式 openTab 落入工作台)并拆除主界面形态
-- **不自动回退**:移入后页签关闭/类型禁用均不再自动返回主界面;把开关关掉即回到主界面形态(轮询感知,约一个 tick 周期内生效)
-- **开关可用性**:已安装 better-sidebar 时可切换;未安装时开关呈禁用态仅展示(保持主界面,无副作用)
+- **默认:全局面板**。看板以同 id 注册 main keyed 条目(中央面板)+ sidebar.panellist 条目(侧栏「新会话」下方面板行);点击面板行由宿主 `layout.selectPanel` 切换中央区,会话保持不动;点击会话行或新会话即切回会话(官方路径)
+- **手动移入**:设置>插件 页「定时任务」卡片(官方 PluginCard 形制:折叠卡壳,cb-pc 镜像)提供「看板移入 better-sidebar 侧边栏」开关;开启即注册扩展槽 tab 并卸载全局面板
+- **不自动回退**:移入后页签关闭/类型禁用均不再自动返回;把开关关掉即回到全局面板形态(轮询感知,约一个 tick 周期内生效)
+- **开关可用性**:已装载 better-sidebar 时可切换;未装载时开关呈禁用态仅展示(保持全局面板,无副作用)
 
 ## 配置
 
@@ -35,7 +35,7 @@
 | `maxConcurrent` | 全局同时运行的执行单元上限 | 2 |
 | `logKeepPerJob` | 每任务保留的运行日志份数(超出按文件修改时间裁剪) | 200 |
 | `maskEnvInPrompt` | 会话任务投递文本中环境变量值打码 | 关 |
-| `sidebarTab` | 看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面) | 关 |
+| `sidebarTab` | 看板移入 better-sidebar 侧边栏(需已装载;关闭时以侧栏面板行 + 全局面板呈现) | 关 |
 
 ## 依赖
 

package/package.json

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

package/src/client.js

@@ -167,7 +167,9 @@ body{
 --cb-font-xs:12px;--cb-font-sm:12px;--cb-font-md:13px;--cb-font-lg:15px;
 --cb-control-h:30px;
 }
-.cb-panel{display:flex;flex-direction:column;gap:var(--cb-space-5);min-width:0;max-width:880px;color:var(--cb-text);container-type:inline-size}
+.cb-panel{display:flex;flex-direction:column;gap:var(--cb-space-5);min-width:0;max-width:880px;margin:0 auto;width:100%;color:var(--cb-text);container-type:inline-size}
+/* 全局面板壳:占满宿主中央区,滚动自持(main keyed 条目根) */
+.cb-main{flex:1;min-height:0;display:flex;flex-direction:column;overflow:auto;padding:var(--cb-space-6);background:var(--dsw-alias-bg-base,var(--cb-bg))}
 .cb-toolbar{display:flex;align-items:center;gap:var(--cb-space-3);flex-wrap:wrap}
 .cb-tabs{display:flex;gap:var(--cb-space-1);background:var(--cb-bg-muted);border-radius:999px;padding:3px}
 .cb-pill{border:none;border-radius:999px;padding:5px 14px;font-size:var(--cb-font-md);background:transparent;color:var(--cb-text-sub);cursor:pointer;font-weight:560;transition:color .15s,background .15s}
@@ -183,7 +185,7 @@ body{
 .cb-button--danger{color:var(--cb-danger)}
 .cb-button--danger:hover:not(:disabled){border-color:var(--cb-danger);background:var(--cb-danger);color:#fff}
 .cb-button--sm{min-height:28px;padding:0 10px;font-size:var(--cb-font-sm)}
-.cb-button:focus-visible,.cb-icon:focus-visible,.cb-pill:focus-visible,.cb-select:focus-visible,.cb-entry:focus-visible{outline:2px solid color-mix(in srgb, var(--cb-accent) 70%, white);outline-offset:2px}
+.cb-button:focus-visible,.cb-icon:focus-visible,.cb-pill:focus-visible,.cb-select:focus-visible{outline:2px solid color-mix(in srgb, var(--cb-accent) 70%, white);outline-offset:2px}
 .cb-button:active:not(:disabled){transform:translateY(1px)}
 .cb-cards{display:flex;flex-direction:column;gap:var(--cb-space-3)}
 .cb-card{position:relative;display:flex;flex-direction:column;gap:var(--cb-space-2);border:1px solid var(--cb-border);border-radius:var(--cb-radius-lg);padding:var(--cb-space-4) var(--cb-space-5);cursor:pointer;overflow:hidden;background:var(--cb-bg);box-shadow:var(--cb-shadow);transition:border-color .15s,box-shadow .15s}
@@ -290,27 +292,17 @@ body{
 .cb-log::-webkit-scrollbar-thumb,.cb-modal::-webkit-scrollbar-thumb{background:var(--cb-border-strong);border-radius:999px}
 .cb-log::-webkit-scrollbar-track,.cb-modal::-webkit-scrollbar-track{background:transparent}
 .cb-error{font-size:var(--cb-font-sm);color:var(--cb-danger);background:var(--cb-bg-sub);border-left:3px solid var(--cb-danger);border-radius:var(--cb-radius-sm);padding:var(--cb-space-2) var(--cb-space-3)}
-/* 容器查询:better-sidebar tab 与主视图宽度差异大,跟随面板自身宽度而非视口。
+/* 容器查询:会话视图区与 better-sidebar tab 宽度差异大,跟随面板自身宽度而非视口。
    模态不受面板容器宽度连累:mask 固定定位于视口,断点用视口媒体查询独立判定 */
 @container (max-width: 560px){
 .cb-card-row .cb-actions{margin-left:0;width:100%;justify-content:flex-end;flex-wrap:wrap}
-.cb-view{padding:var(--cb-space-4)}
 .cb-panel{gap:var(--cb-space-4)}
 }
 @media (max-width: 560px){
 .cb-grid{grid-template-columns:1fr}
 .cb-modal{max-height:92vh}
+.cb-main{padding:var(--cb-space-4)}
 }
-.cb-entry{display:flex;align-items:center;gap:var(--cb-space-3);width:100%;border:none;background:transparent;color:inherit;cursor:pointer;padding:var(--cb-space-2) var(--cb-space-4);border-radius:var(--cb-radius-md);font-size:var(--cb-font-md);text-align:left}
-.cb-entry:hover{background:var(--cb-hover)}
-.cb-entry[data-active="true"]{background:var(--cb-accent);color:#fff}
-.cb-entry-icon{display:inline-flex;flex:none}
-.cb-view{display:none;flex:1;min-height:0;flex-direction:column;padding:var(--cb-space-6);overflow:auto;background:var(--dsw-alias-bg-base,var(--cb-bg))}
-.cb-view > .cb-panel{margin:0 auto;width:100%}
-html[data-cb-board-active] [data-cb-view]{display:flex}
-html[data-cb-board-active] [data-pane="conversation"] > :not([data-cb-view]){display:none !important}
-html[data-cb-board-active] [class*="centerCol"] > :not([data-cb-view]){display:none !important}
-html[data-cb-board-active] .dshDesktopConversationSurface > :not([data-cb-view]){display:none !important}
 `
 
 // 空模块兜底:react 缺席即整面板禁用(宿主必有 react,防御性)
@@ -321,6 +313,13 @@ function noopFactory() {
 if (typeof window !== 'undefined' && window.__ModuleLoader__) {
   window.__ModuleLoader__.load({ id: '@mzzsfy/dsh-cron-board', factory })
 
+  // 导航图标声明:交给 dsh-settings-nav-icons 统一渲染;键 = 市场短名(发现页
+  // 收录显示形态);该插件未就绪时入队,由其启动时排空
+  const NAV_ICON = { 'dsh-cron-board': 'plan' }
+  if (window.__navicIcons !== undefined) window.__navicIcons.register(NAV_ICON)
+  else if (Array.isArray(window.__navicIconQueue)) window.__navicIconQueue.push(NAV_ICON)
+  else window.__navicIconQueue = [NAV_ICON]
+
   function factory(require) {
     let React = null
     let ReactDOMClient = null
@@ -679,7 +678,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           h('button', { className: 'cb-button cb-button--danger', onClick: onConfirm }, '删除')))
     }
 
-    function JobsTab({ jobs, status, now, reload, wsModel }) {
+    function JobsTab({ jobs, status, now, reload, applyJobPatch, wsModel }) {
       const [formJob, setFormJob] = useState(null)
       const [notice, setNotice] = useState(null)
       const [kindFilter, setKindFilter] = useState('all')
@@ -691,7 +690,13 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
         setTimeout(reload, 300)
       }
       const toggleJob = async (job) => {
-        await request('PATCH', 'jobs/' + job.id, { enabled: !job.enabled })
+        // 乐观翻转:受控开关即时到位;失败回滚并提示,不静默
+        applyJobPatch(job.id, { enabled: !job.enabled })
+        const outcome = await request('PATCH', 'jobs/' + job.id, { enabled: !job.enabled })
+        if (!outcome.ok) {
+          applyJobPatch(job.id, { enabled: job.enabled })
+          setNotice('切换失败:' + outcome.error)
+        }
         reload()
       }
       const deleteJob = async (job) => {
@@ -811,14 +816,20 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           h('button', { className: 'cb-button cb-button--danger', onClick: () => doApply(true) }, '覆盖导入')))
     }
 
-    function EnvsTab({ envs, reload }) {
+    function EnvsTab({ envs, reload, applyEnvPatch }) {
       const [formRow, setFormRow] = useState(null)
       const [importing, setImporting] = useState(false)
       const [exportText, setExportText] = useState(null)
       const [notice, setNotice] = useState(null)
 
       const toggleEnv = async (row) => {
-        await request('PATCH', 'envs/' + row.id, { enabled: !row.enabled })
+        // 乐观翻转:受控开关即时到位;失败回滚并提示,不静默
+        applyEnvPatch(row.id, { enabled: !row.enabled })
+        const outcome = await request('PATCH', 'envs/' + row.id, { enabled: !row.enabled })
+        if (!outcome.ok) {
+          applyEnvPatch(row.id, { enabled: row.enabled })
+          setNotice('切换失败:' + outcome.error)
+        }
         reload()
       }
       const deleteEnv = async (row) => {
@@ -921,6 +932,13 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       const [now, setNow] = useState(Date.now())
       const [reloadFlag, setReloadFlag] = useState(0)
       const reload = useCallback(() => setReloadFlag((value) => value + 1), [])
+      // 乐观更新:受控开关点击即时到位,PATCH 失败由调用方回滚;reload 拉权威态对账
+      const applyJobPatch = useCallback((id, patch) => {
+        setJobs((prev) => prev.map((job) => (job.id === id ? { ...job, ...patch } : job)))
+      }, [])
+      const applyEnvPatch = useCallback((id, patch) => {
+        setEnvs((prev) => prev.map((row) => (row.id === id ? { ...row, ...patch } : row)))
+      }, [])
 
       useEffect(() => {
         if (!active) return undefined
@@ -949,28 +967,19 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           status ? h('span', { className: 'cb-meta' },
             '运行中 ' + status.scheduler.active + ' · 队列 ' + status.scheduler.queued +
             (status.nextAt ? ' · 下次 ' + relativeTime(status.nextAt, now) : '')) : null),
-        tab === 'jobs' ? h(JobsTab, { key: 'jobs', jobs, status, now, reload, wsModel }) : null,
-        tab === 'envs' ? h(EnvsTab, { key: 'envs', envs, reload }) : 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)
     }
 
-    // —— 主页面挂载(形态对齐 dsh-taskboard,cb- 属性命名空间)——
-    // 优先 better-sidebar 扩展槽(单实例 tab);未装回退主界面:侧栏入口行 + 中心列看板容器。
+    // —— 主页面挂载:宿主官方全局面板契约(main keyed 插槽 + sidebar.panellist 侧栏入口)——
+    // 侧栏行与中央面板均由宿主渲染:点击入口行宿主调 layout.selectPanel 切换,会话保持不动;
+    // 切回会话走官方路径(会话行/新会话 openSession → selectPanel(null))。禁 DOM 刮取。
+    // better-sidebar 偏好开启时改注册其扩展槽 tab(服务契约,同样非 DOM 刮取),两形态互斥。
 
     const TAB_ID = 'cron-board:board'
-    const ENTRY_ATTR = 'data-cb-entry'
-    const VIEW_ATTR = 'data-cb-view'
-    const BOARD_ACTIVE_ATTR = 'data-cb-board-active'
-    const PANEL_ACTIVATE_EVENT = 'dsh-panel-activate'
-    const PANEL_NAME = 'dsh-cron-board'
-    const ENTRY_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="2" width="12" height="12" rx="2"/><path d="M6 2v12M10 2v12"/></svg>'
-    // 三代布局壳兼容:dev data-pane / 官方 CSS-Module centerCol / DSH Desktop 扩展面
-    const CONVERSATION_COLUMN_SELECTOR = '[data-pane="conversation"], [class*="centerCol"], .dshDesktopConversationSurface'
-    const SIDEBAR_ROOT_SELECTOR = '[data-pane="sidebar"], [class*="sidebarCol"], .dshDesktopUpstreamSidebar, .dshDesktopSidebarSurface'
-    // 家族面板入口条目(taskboard 系),插入时排其前,避免重渲染后顺序漂移
-    const FAMILY_ENTRY_SELECTOR = '[data-dsh-atb-entry], [data-dsh-taskboard-entry], [data-dsh-ssh-entry], [' + ENTRY_ATTR + ']'
-    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"]'
+    const PANEL_ID = 'cron-board'
+    const PANEL_LABEL = '定时任务'
 
     // 设置>插件页卡片:官方 PluginCard 形制(名称/描述头部 + chevron 折叠 + 行内开关);better-sidebar 在场可切换,否则仅展示禁用态
     const CARD_TITLE = '定时任务'
@@ -981,12 +990,12 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       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() {
+    function CronBoardPluginCard({ ctx }) {
       const [enabled, setEnabled] = useState(null)
       const [busy, setBusy] = useState(false)
       const [open, setOpen] = useState(false)
-      // 渲染时重探:侧栏面晚于设置页挂载时,enabled 到达的重渲染会自动纠正禁用态
-      const sidebarReady = Boolean(document.querySelector(SIDEBAR_ROOT_SELECTOR))
+      // 渲染时重探服务在场:better-sidebar 晚于设置页装载时,重渲染自动纠正禁用态
+      const sidebarReady = ctx.get('betterSidebar') !== undefined
       useEffect(() => {
         let alive = true
         request('GET', 'status').then((outcome) => {
@@ -1019,7 +1028,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
                 ariaLabel: CARD_TOGGLE_LABEL,
               })),
             h('p', { className: 'cb-pc__hint' },
-              sidebarReady ? '开启后看板以侧边栏页签呈现,关闭时始终使用主界面。' : '需安装 better-sidebar 后方可切换;未安装时看板始终使用主界面。'))) : null)
+              sidebarReady ? '开启后看板以侧边栏页签呈现,关闭时使用全局面板。' : '需已装载 better-sidebar 后方可切换;未装载时看板始终使用全局面板。'))) : null)
     }
 
     // better-sidebar tab:注册即单实例(single);只注册不主动打开,
@@ -1028,7 +1037,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       return ctx.effect(() => {
         const disposeTab = service.registerTab({
           id: TAB_ID,
-          title: '定时任务',
+          title: PANEL_LABEL,
           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 }),
@@ -1041,123 +1050,30 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       }, 'cron-board sidebar tab')
     }
 
-    function sidebarRoot() {
-      const column = document.querySelector(SIDEBAR_ROOT_SELECTOR)
-      if (!column) return undefined
-      const logoOwner = column.querySelector('[class*="logoRow"]')
-      return (logoOwner && logoOwner.parentElement) || column.firstElementChild || undefined
-    }
-
-    function newSessionButton(root) {
-      const nested = root.querySelector('button[class*="newSession"]')
-      if (nested) return nested
-      for (const child of root.children) {
-        if (child instanceof HTMLButtonElement && !child.matches('[' + ENTRY_ATTR + ']')) return child
-      }
-      return root.querySelector('button[aria-label="新建会话"], button[aria-label*="新会话"], button[aria-label*="new session" i]') || undefined
+    // 面板图标:panellist 渲染契约组件,宿主传 { size, active }
+    function PanelIcon({ size }) {
+      return 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' }))
     }
 
-    function placeEntry(root, entry) {
-      const button = newSessionButton(root)
-      if (!button) return false
-      if (entry.parentElement !== root) {
-        const row = button.closest('[class*="logoRow"]')
-        const base = (row && row.parentElement === root) ? row : button
-        const family = Array.from(root.children).filter((el) => el.matches(FAMILY_ENTRY_SELECTOR))
-        const anchor = family.length > 0 ? family[0] : (base.nextElementSibling || null)
-        root.insertBefore(entry, anchor)
-      }
-      return true
-    }
-
-    // 主界面形态:入口行 + 中心列容器 + html 属性显隐 + 面板互斥;返回幂等 disposer
-    function mountStandaloneBoard(wsModel) {
-      let disposed = false
-      let entry = null
-      let rootEl = undefined
-      let placed = false
-      let rootObserver = null
-      let viewRoot = null
-      let viewEl = null
-
-      const setOpen = (open) => {
-        if (open) {
-          for (const attr of OTHER_PANEL_ACTIVE_ATTRS) document.documentElement.removeAttribute(attr)
-          document.documentElement.setAttribute(BOARD_ACTIVE_ATTR, '')
-          document.dispatchEvent(new CustomEvent(PANEL_ACTIVATE_EVENT, { detail: PANEL_NAME }))
-          entry.dataset.active = 'true'
-        } else {
-          document.documentElement.removeAttribute(BOARD_ACTIVE_ATTR)
-          entry.dataset.active = 'false'
-        }
-      }
-      const isOpen = () => document.documentElement.hasAttribute(BOARD_ACTIVE_ATTR)
-
-      const ensureEntry = () => {
-        if (rootEl !== undefined && !rootEl.isConnected) { placed = false; rootEl = undefined }
-        if (placed && document.body.contains(entry)) return true
-        placed = false
-        rootEl = sidebarRoot()
-        if (!rootEl) return false
-        placed = placeEntry(rootEl, entry)
-        if (placed && rootObserver) rootObserver.observe(rootEl, { childList: true, subtree: true })
-        return placed
-      }
-
-      const ensureView = () => {
-        if (viewEl && viewEl.isConnected) return true
-        const column = document.querySelector(CONVERSATION_COLUMN_SELECTOR)
-        if (!column) return false
-        viewEl = document.createElement('div')
-        viewEl.setAttribute(VIEW_ATTR, '')
-        viewEl.className = 'cb-view'
-        column.appendChild(viewEl)
-        viewRoot = ReactDOMClient.createRoot(viewEl)
-        viewRoot.render(React.createElement(CronBoardPanel, { visible: true, wsModel }))
-        return true
-      }
-
-      const onClickDocument = (event) => {
-        if (!isOpen()) return
-        const target = event.target
-        if (target && target.closest && target.closest('[' + ENTRY_ATTR + ']')) return
-        if (target && target.closest && target.closest(SIDEBAR_ROW_SELECTOR)) setOpen(false)
-      }
-      const onOtherActivate = (event) => {
-        if (event.detail !== PANEL_NAME && isOpen()) setOpen(false)
-      }
-      entry = document.createElement('button')
-      entry.type = 'button'
-      entry.setAttribute(ENTRY_ATTR, '')
-      entry.className = 'cb-entry'
-      entry.setAttribute('aria-label', '定时任务')
-      entry.innerHTML = '<span class="cb-entry-icon">' + ENTRY_ICON + '</span><span>定时任务</span>'
-      entry.addEventListener('click', () => setOpen(!isOpen()))
-      document.addEventListener('click', onClickDocument, true)
-      document.addEventListener(PANEL_ACTIVATE_EVENT, onOtherActivate)
-      const waitObserver = new MutationObserver(() => { ensureEntry(); ensureView() })
-      waitObserver.observe(document.body, { childList: true, subtree: true })
-      rootObserver = new MutationObserver(() => {
-        if (rootEl === undefined || !rootEl.isConnected) { ensureEntry(); return }
-        if (!rootEl.contains(entry)) placeEntry(rootEl, entry)
-      })
-      const retry = setInterval(() => { ensureEntry(); ensureView() }, 2000)
-      ensureEntry()
-      ensureView()
-
-      return () => {
-        if (disposed) return
-        disposed = true
-        clearInterval(retry)
-        waitObserver.disconnect()
-        if (rootObserver) rootObserver.disconnect()
-        document.removeEventListener('click', onClickDocument, true)
-        document.removeEventListener(PANEL_ACTIVATE_EVENT, onOtherActivate)
-        document.documentElement.removeAttribute(BOARD_ACTIVE_ATTR)
-        entry.remove()
-        if (viewRoot) viewRoot.unmount()
-        if (viewEl) viewEl.remove()
-      }
+    // 全局面板形态:main keyed 条目(中央面板)+ sidebar.panellist 条目(侧栏入口行),同 id 配对;
+    // 页签点击切换、激活高亮均由宿主管;effect 工厂必须交付组合清理,否则互斥仲裁拆不掉条目
+    function registerMainPanel(ctx, wsModel) {
+      return ctx.effect(() => {
+        const injectDisposers = []
+        injectDisposers.push(ctx.slots.inject('main', () => ctx.slots.register({
+          name: 'main',
+          key: PANEL_ID,
+        }, () => h('div', { className: 'cb-main' }, h(CronBoardPanel, { wsModel })))))
+        injectDisposers.push(ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
+          name: 'sidebar.panellist',
+          id: PANEL_ID,
+          label: PANEL_LABEL,
+        }, (iconProps) => h(PanelIcon, iconProps))))
+        return () => { for (const dispose of injectDisposers) dispose() }
+      }, 'cron-board main panel')
     }
 
     return {
@@ -1168,45 +1084,50 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
         // 工作区 model(list 即 getSnapshot/subscribe 契约的响应式模型;形态不符传 null,表单仅保留手输)
         const wsService = ctx.get('workspaces')
         const wsModel = wsService && wsService.list && typeof wsService.list.getSnapshot === 'function' ? wsService.list : null
-        // 挂载权交给用户:默认永远主界面;设置 sidebarTab 开启且侧边栏服务在场才移入扩展槽,注册后不再自动回退
-        const attachBoardTab = (sidebar) => registerBoardTab(ctx, sidebar, wsModel)
-        let standalone = mountStandaloneBoard(wsModel)
-        let tabDisposer = null
-        let sidebarTabOn = false
-        // betterSidebar 服务软探测 + 晚注册追踪:出现/变化时按当前偏好重新决策
+        // 挂载权交给用户:默认注册全局面板;设置 sidebarTab 开启且侧边栏服务在场才移入扩展槽,注册后不再自动回退
         let currentSidebar = ctx.get('betterSidebar')
+        let sidebarTabOn = false
+        let tabDisposer = null
+        let panelDisposer = null
+        const attachBoardTab = (sidebar) => registerBoardTab(ctx, sidebar, wsModel)
         const applyPref = () => {
           const wantTab = sidebarTabOn && currentSidebar !== undefined
           if (wantTab && tabDisposer === null) {
-            standalone()
-            standalone = null
+            if (panelDisposer) { panelDisposer(); panelDisposer = null }
             tabDisposer = attachBoardTab(currentSidebar)
           } else if (!wantTab && tabDisposer !== null) {
             tabDisposer()
             tabDisposer = null
           }
-          if (!wantTab && standalone === null) standalone = mountStandaloneBoard(wsModel)
+          if (!wantTab && panelDisposer === null) panelDisposer = registerMainPanel(ctx, wsModel)
         }
         const prefWatch = setInterval(async () => {
           try {
             const outcome = await request('GET', 'status')
             const next = readSidebarTabPref(outcome)
             if (next !== sidebarTabOn) {
+              const previous = sidebarTabOn
               sidebarTabOn = next
-              applyPref()
+              try {
+                applyPref()
+              } catch (error) {
+                // 形态切换失败回滚偏好,下轮轮询重试,避免入口消失后卡死
+                sidebarTabOn = previous
+                console.warn('[cron-board] 看板形态切换失败:', error)
+              }
             }
           } catch { /* 轮询失败保形态不变,下轮重试 */ }
         }, 5 * 1000)
         ctx.effect(() => () => {
           clearInterval(prefWatch)
-          if (standalone) standalone()
           if (tabDisposer) tabDisposer()
+          if (panelDisposer) panelDisposer()
         }, '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,
+            { name: 'settings.plugin.item', key: PANEL_ID, label: PANEL_LABEL },
+            () => h(CronBoardPluginCard, { ctx }),
           )
         }), 'cron-board settings card')
         ctx.inject(['betterSidebar'], (bsCtx) => {

package/test/switch-guard.test.mjs

@@ -60,28 +60,67 @@ test('client.js 无顶层词法声明(经典 script 书挡内安全)', () => {
   assert.ok(trimmed.endsWith('})()'), '必须以 IIFE 书挡结尾')
 })
 
-test('client.js 主页面双形态挂载契约(默认主界面;设置开关手动移入侧边栏;无自动回退)', () => {
-  // Given 用户要求:默认永远主界面;检测到 better-sidebar 提供设置项,由用户手动移入;
-  //        移入后页签关闭/禁用不再自动返回主界面(挂载权完全交给用户与侧边栏)
-  // Then 静态锁定:模块注册形态、服务软探测、tab 单实例、主界面容器与互斥事件、偏好驱动仲裁
+test('启停开关乐观更新契约:即时翻转 + 失败回滚提示,禁止等待往返才反馈', () => {
+  // Given 受控 switch(checked 锁定 props)点击后无本地 state 变化不产生视觉反馈
+  // When toggleJob/toggleEnv 发起 PATCH
+  // Then 先乐观翻转,失败回滚并 notice,最后 reload 对账权威态(顺序锁定)
+  for (const fn of ['toggleJob', 'toggleEnv']) {
+    const start = source.indexOf('const ' + fn + ' = async')
+    assert.ok(start > 0, `缺少 ${fn}`)
+    const body = source.slice(start, source.indexOf('reload()', start))
+    assert.match(body, /apply(Job|Env)Patch\([^)]*, \{ enabled: !/m, `${fn} 必须先乐观翻转`)
+    assert.match(body, /if \(!outcome\.ok\)/m, `${fn} 必须检查 PATCH 结果`)
+    assert.match(body, /apply(Job|Env)Patch\([^)]*, \{ enabled: (job|row)\.enabled \}\)/m, `${fn} 失败必须回滚`)
+    assert.match(body, /切换失败:/m, `${fn} 失败必须提示,禁止静默`)
+  }
+  // 两个 Tab 均接收乐观更新通道(Board 下传)
+  assert.match(source, /applyJobPatch, wsModel/)
+  assert.match(source, /envs, reload, applyEnvPatch/)
+})
+
+test('client.js 主页面双形态挂载契约(默认宿主全局面板;设置开关手动移入侧边栏;无自动回退)', () => {
+  // Given 定时任务是全局工具,入口必须不依赖会话:main 为 keyed 全局中央面板插槽,
+  //        sidebar.panellist 为侧栏面板行,点击切换由宿主 layout.selectPanel 承载
+  // When 插件以同 id 注册 main 条目 + panellist 条目;sidebarTab 偏好开启且服务在场时改注册 better-sidebar 扩展槽 tab
+  // Then 静态锁定:双条目注册形态、服务软探测、tab 单实例、偏好驱动仲裁、设置卡片;
+  //        DOM 刮取挂载与会话内页签形态(conversation.view)禁止回流
   assert.match(source, /window\.__ModuleLoader__\.load\(\{ id: '@mzzsfy\/dsh-cron-board', factory \}\)/)
+  assert.match(source, /ctx\.slots\.inject\('main'/)
+  assert.match(source, /name: 'main'/)
+  assert.match(source, /key: PANEL_ID/)
+  assert.match(source, /const PANEL_ID = 'cron-board'/)
+  assert.match(source, /const PANEL_LABEL = '定时任务'/)
+  assert.match(source, /ctx\.slots\.inject\('sidebar\.panellist'/)
+  assert.match(source, /name: 'sidebar\.panellist'/)
+  assert.match(source, /id: PANEL_ID/)
+  assert.match(source, /function registerMainPanel/)
+  assert.match(source, /cb-main/)
+  // 面板贡献必须可拆除:effect 工厂收集 inject disposer 并交付组合清理,
+  // 否则互斥仲裁拆不掉 main/panellist 条目,开关往返累积注册(审查阻断项)
+  assert.match(source, /injectDisposers\.push\(ctx\.slots\.inject\('main'/)
+  assert.match(source, /injectDisposers\.push\(ctx\.slots\.inject\('sidebar\.panellist'/)
+  assert.match(source, /return \(\) => \{ for \(const dispose of injectDisposers\) dispose\(\) \}/)
   assert.match(source, /ctx\.get\('betterSidebar'\)/)
   assert.match(source, /single: true/)
   assert.match(source, /ctx\.inject\(\['betterSidebar'\]/)
-  assert.match(source, /data-cb-board-active/)
-  assert.match(source, /dsh-panel-activate/)
-  assert.match(source, /function mountStandaloneBoard/)
-  // 设置>插件页卡片(settings.plugin.item,key 配对 ns);better-sidebar 在场可切换,否则禁用仅展示
+  // 设置>插件页卡片(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, /key: PANEL_ID, label: PANEL_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\)/)
+  // 挂载仲裁:偏好(status.ui.sidebarTab)驱动全局面板/扩展槽互斥
   assert.match(source, /applyPref\(\)/)
   assert.match(source, /ui\.sidebarTab/)
   // 不再自动回退:attach 后不订阅页签状态,无 openTabs/subscribeState 联动
   assert.doesNotMatch(source, /subscribeState/)
   assert.doesNotMatch(source, /openTabs/)
+  assert.doesNotMatch(source, /mountStandaloneBoard/)
+  assert.doesNotMatch(source, /data-cb-board-active/)
+  assert.doesNotMatch(source, /dsh-panel-activate/)
+  assert.doesNotMatch(source, /data-pane="conversation"/)
+  assert.doesNotMatch(source, /centerCol/)
+  assert.doesNotMatch(source, /dshDesktop/)
+  assert.doesNotMatch(source, /MutationObserver/)
+  assert.doesNotMatch(source, /conversation\.view/)
 })