agentworkshop 0.7.39 → 0.7.41

package/app/pages/workshop/w/[wsId].vue

@@ -11,6 +11,7 @@ import { useEntitiesStore } from '../../../stores/workshop/entities'
 import { useWorkshopWs } from '../../../composables/workshop/useWorkshopWs'
 import { useUserStore } from '../../../stores/workshop/user'
 import { useStorage } from '@vueuse/core'
+import { useResponsive } from '../../../composables/useResponsive'
 
 const { t } = useI18n()
 
@@ -36,6 +37,10 @@ onMounted(() => {
 const entities = useEntitiesStore()
 const { subscribe, unsubscribe, conn } = useWorkshopWs()
 
+// 视口档位(唯一判据;SSR 期返回桌面档)——
+// 窄屏(≤1023)三栏仪表台只剩 ~460px 画布,必须换成「单通道示波器」形态
+const { isDesktop } = useResponsive()
+
 const workspace = computed(() => wsStore.workspaces.find(w => w.id === wsId.value))
 // 聚焦 channel:activeChannelId 须在挂载清单内(陈旧持久化/竞态下回退首频道),
 // 避免订阅死频道 → 快照永不到达 → 右栏/时间线长时间"空数据"假象
@@ -77,7 +82,8 @@ const lastSeq = computed(() => (channelId.value ? conn.cursors[channelId.value]
 
 // 视图切换(P1 三视图 + P2 多通道同屏 + P5 RPG 小镇)
 // 深链:?view=lanes/board/split/town 直达指定视图(可分享/收藏)
-type CenterView = 'timeline' | 'lanes' | 'board' | 'split' | 'town'
+// inspector 只在窄屏出现(桌面它是右侧常驻栏),故不进深链白名单
+type CenterView = 'timeline' | 'lanes' | 'board' | 'split' | 'town' | 'inspector'
 const VIEW_KEYS: Record<string, CenterView> = {
   1: 'timeline',
   2: 'lanes',
@@ -90,15 +96,24 @@ const initView = route.query.view
 const view = ref<CenterView>(
   typeof initView === 'string' && VIEW_VALUES.has(initView) ? initView as CenterView : 'timeline',
 )
-const viewOptions = [
-  { value: 'timeline', label: t('wsView.k3otu32010') },
-  { value: 'lanes', label: 'Agent lanes' },
-  { value: 'board', label: t('wsView.k3ko7a8011') },
-  { value: 'split', label: t('wsView.k3xbmo012') },
-  { value: 'town', label: t('wsView.k1cz0pbw013') },
-]
+const viewOptions = computed(() => {
+  const base = [
+    { value: 'timeline', label: t('wsView.k3otu32010') },
+    { value: 'lanes', label: 'Agent lanes' },
+    { value: 'board', label: t('wsView.k3ko7a8011') },
+    { value: 'split', label: t('wsView.k3xbmo012') },
+    { value: 'town', label: t('wsView.k1cz0pbw013') },
+  ]
+  // 窄屏「一次一区」:检查器不占侧栏,并入切换条(四区都由同一条承载)
+  return narrowUI.value ? [...base, { value: 'inspector', label: '检查器' }] : base
+})
 // 数字快捷键 1-5 直切视图(非输入焦点时;控制台型键盘操作与 ⌘K 面板同一取向)
 const onViewKey = (ev: KeyboardEvent): void => {
+  // 窄屏抽屉:Esc 收起(与全站侧栏抽屉一致)
+  if (ev.key === 'Escape' && narrowUI.value && leftOpen.value) {
+    leftOpen.value = false
+    return
+  }
   if (ev.metaKey || ev.ctrlKey || ev.altKey) return
   const t = ev.target as HTMLElement | null
   if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable)) return
@@ -111,8 +126,31 @@ onMounted(() => window.addEventListener('keydown', onViewKey))
 onBeforeUnmount(() => window.removeEventListener('keydown', onViewKey))
 
 // 侧栏折叠(现代 harness 布局:左会话栏 / 右检查器可按需收起)
+// 形态差异只在挂载后生效:SSR/首帧一律按桌面结构渲染,客户端接管后才翻档,
+// 否则服务端 5 项切换条 vs 客户端 6 项会触发水合告警
+const mounted = ref(false)
+onMounted(() => {
+  mounted.value = true
+})
+const narrowUI = computed(() => mounted.value && !isDesktop.value)
+
 const leftOpen = ref(true)
 const rightOpen = ref(true)
+/** 窄屏:左右侧栏都不再占位(收成覆盖式抽屉 / 并入切换条) */
+const applyTier = (desktop: boolean): void => {
+  leftOpen.value = desktop
+  rightOpen.value = desktop
+  // 检查器只是窄屏的第 4 区:回桌面后它回到右栏,中部得有自己的区(否则中部空白)
+  if (desktop && view.value === 'inspector') view.value = 'timeline'
+}
+onMounted(() => {
+  if (!isDesktop.value) applyTier(false)
+})
+watch(isDesktop, d => applyTier(d))
+// 抽屉里选中频道后自动收起(窄屏少一次手动关闭)
+watch(channelId, (next, prev) => {
+  if (prev !== undefined && next !== prev && narrowUI.value) leftOpen.value = false
+})
 
 // 侧栏宽度拖拽调节(PaneSplitter;localStorage 持久化,双击复位到默认值)
 const LEFT_W_DEFAULT = 248
@@ -192,8 +230,18 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
         />
       </div>
       <div class="right">
+        <!-- 窄屏:频道会话列表入口(覆盖式抽屉;该页一次只看一区) -->
         <button
-          class="pane-toggle im"
+          v-if="narrowUI"
+          class="pane-toggle im toggle-left-narrow"
+          :class="{ off: !leftOpen }"
+          title="频道会话列表"
+          @click="leftOpen = !leftOpen"
+        >
+          <span class="i-tabler-list-details im-pop" />
+        </button>
+        <button
+          class="pane-toggle im toggle-left-desk"
           :class="{ off: !leftOpen }"
           :title="$t('wsView.k1tsy2e4002')"
           @click="leftOpen = !leftOpen"
@@ -201,7 +249,7 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
           <span class="i-tabler-layout-sidebar-left-collapse im-pop" />
         </button>
         <button
-          class="pane-toggle im"
+          class="pane-toggle im toggle-right-desk"
           :class="{ off: !rightOpen }"
           :title="$t('wsView.k1tx0ppf003')"
           @click="rightOpen = !rightOpen"
@@ -236,10 +284,16 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
 
     <!-- 主体三栏(左/右侧栏可折叠 + 拖拽调宽;分隔条 hairline 即面板边界) -->
     <div class="main">
+      <!-- 窄屏抽屉遮罩:点空白收起(不盖住底部 Composer,输入不被"锁在"抽屉后) -->
+      <div
+        v-if="narrowUI && leftOpen"
+        class="drawer-scrim"
+        @click="leftOpen = false"
+      />
       <div
         v-if="leftOpen"
         class="left-pane"
-        :style="{ flexBasis: `${leftWidth}px` }"
+        :style="{ flexBasis: narrowUI ? 'auto' : `${leftWidth}px` }"
       >
         <div class="left-scroll">
           <workshop-channel-session-list :ws-id="wsId" />
@@ -250,7 +304,7 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
         />
       </div>
       <workshop-pane-splitter
-        v-if="leftOpen"
+        v-if="leftOpen && !narrowUI"
         :label="$t('wsView.k1fkfvra005')"
         @resize="resizeLeft"
         @reset="leftWidth = LEFT_W_DEFAULT"
@@ -279,6 +333,13 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
             v-else-if="view === 'town'"
             :channel-id="channelId"
           />
+          <!-- 窄屏第 4 区:检查器并入切换条(桌面仍是右侧常驻栏) -->
+          <workshop-inspector-panel
+            v-else-if="view === 'inspector' && narrowUI"
+            :channel-id="channelId"
+            @open-agent="openAgent"
+            @open-task="openTask"
+          />
         </template>
         <div
           v-else
@@ -294,13 +355,13 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
         </div>
       </div>
       <workshop-pane-splitter
-        v-if="rightOpen"
+        v-if="rightOpen && !narrowUI"
         :label="$t('wsView.kwqb0st006')"
         @resize="resizeRight"
         @reset="rightWidth = RIGHT_W_DEFAULT"
       />
       <div
-        v-if="rightOpen"
+        v-if="rightOpen && !narrowUI"
         class="right-pane"
         :class="{ empty: wsStore.loaded && !channelId }"
         :style="{ flexBasis: `${rightWidth}px` }"
@@ -513,4 +574,131 @@ useHead({ title: () => `${workspace.value?.name ?? 'Workspace'} · AgentWorkShop
   color: var(--ink-faint);
 }
 .composer-pane { flex: 0 0 auto; }
+
+/* ══════════════════════════════════════════════════════════════════════════
+   窄屏形态 · 单通道示波器(≤1023px) —— 一次只看一路信号
+   ──────────────────────────────────────────────────────────────────────────
+   桌面是「三栏仪表台」:会话栏 248 + 画布 + 检查器 300 + 两条分隔条。
+   到了 ≤1023,画布只剩 ~460px(900–1023 还要再让 64px 图标轨),
+   硬塞的结果是三栏互相压扁。所以窄屏换一台仪器,而不是把仪表台缩小:
+
+     · 中部视图(时间线 / lanes / 任务板 / 检查器)→ 由顶栏切换条承载,
+       一次只挂载一区,顶部切换条独占一行、可横扫;
+     · 频道会话列表 → 覆盖式抽屉(点遮罩/Esc/选中频道收起),不再占位;
+     · 拖拽分隔条在窄屏没有意义(没有第二栏可分配宽度)→ 隐藏;
+     · 触摸目标 ≥40px、标签 ≥11.5px(手持 30cm 距离下 10px 只剩 6px 有效字号)。
+
+   ⚠️ 断点数值与 main.css v5 / useResponsive.ts 一致(1024 = 三栏仪表台下限),
+      此处不再引入新魔数。桌面(≥1024)样式完全不受影响。
+   ══════════════════════════════════════════════════════════════════════════ */
+@media (max-width: 1023.98px) {
+  .harness {
+    /* 窄屏收掉壳体外留白,把纵向像素让给内容与底部 Composer */
+    height: calc(100dvh - var(--app-header-h, 56px) - var(--app-footer-h, 46px) - 8px);
+  }
+
+  .topbar {
+    flex-wrap: wrap;
+    gap: 6px 8px;
+    padding: 8px 10px;
+  }
+
+  .topbar .left {
+    row-gap: 8px;
+  }
+
+  .ws-name {
+    max-width: 40vw;
+    font-size: 15px;
+  }
+
+  .chan-chip {
+    max-width: 34vw;
+    font-size: 12px;
+  }
+
+  /* 切换条独占一行:五个视图名不再挤掉工作区名(channel 名仍可见) */
+  .view-switch {
+    flex: 1 1 100%;
+    margin-left: 0;
+  }
+
+  .ws-state,
+  .seq {
+    font-size: 11.5px;
+  }
+
+  /* 触摸目标:26px 的幽灵图标钮在手持设备上点不中 */
+  .pane-toggle {
+    width: 40px;
+    height: 40px;
+    font-size: 18px;
+  }
+
+  .toggle-left-desk,
+  .toggle-right-desk {
+    display: none;
+  }
+
+  .main {
+    position: relative;
+  }
+
+  .left-pane {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    z-index: 30;
+    width: min(86vw, 320px);
+    border-right: 1px solid var(--line);
+    box-shadow: var(--shadow-float);
+    animation: pane-in 0.18s cubic-bezier(0.22, 1, 0.36, 1);
+  }
+
+  .drawer-scrim {
+    position: absolute;
+    inset: 0;
+    z-index: 25;
+    background: color-mix(in srgb, var(--ink) 34%, transparent);
+  }
+
+  /* 窄屏没有第二栏可分宽度,拖拽条只会白占 9px */
+  .pane-splitter {
+    display: none;
+  }
+
+  .pane-loading {
+    font-size: 13px;
+  }
+}
+
+/* 窄屏专属入口在桌面不出现(响应式形态差异不用 JS 表达,避免水合抖动) */
+.toggle-left-narrow {
+  display: none;
+}
+
+@media (max-width: 1023.98px) {
+  .toggle-left-narrow {
+    display: inline-flex;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .left-pane {
+    animation: none;
+  }
+}
+
+@keyframes pane-in {
+  from {
+    opacity: 0.5;
+    transform: translateX(-16px);
+  }
+
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
 </style>

package/app/plugins/aw-plugins.client.ts

@@ -13,10 +13,12 @@
  */
 import { watch } from 'vue'
 import { createClientContext, type ClientContext } from '@/sdk/client.mjs'
-import { usePluginPanels } from '@/app/composables/workshop/usePluginPanels'
-import type { TownBus } from '~/composables/workshop/useTownBus'
+import { usePluginPanels, type PluginPanelEntry } from '@/app/composables/workshop/usePluginPanels'
+import { useTownBus, type TownBus } from '~/composables/workshop/useTownBus'
 
 interface ManifestEntry { name: string, enabled?: boolean, hasClient?: boolean }
+/** vue-i18n 实例在 NuxtApp 上的最小面(只用到 mergeLocaleMessage + locale,故按鸭子类型声明确切形状) */
+interface I18nLike { mergeLocaleMessage?: (locale: string, messages: Record<string, unknown>) => void, locale?: unknown }
 interface I18nBundle { i18n?: Record<string, Record<string, Record<string, string>>> }
 
 export default defineNuxtPlugin(async (nuxtApp) => {
@@ -26,8 +28,8 @@ export default defineNuxtPlugin(async (nuxtApp) => {
   const loaded = new Map<string, ClientContext>()
   const { unregisterPlugin } = usePluginPanels()
   const panels = usePluginPanels()
-  const i18n: { mergeLocaleMessage?: (locale: string, messages: Record<string, unknown>) => void, locale?: unknown } | null
-    = (nuxtApp.$i18n as never) ?? null
+  // NuxtApp.$i18n 的库类型与本文件用到的两个成员结构不同(mergeLocaleMessage 的参数更宽),故在边界处收敛成 I18nLike
+  const i18n = ((nuxtApp.$i18n ?? null) as unknown) as I18nLike | null
   let bus: TownBus | null = null
   try {
     bus = useTownBus()
@@ -102,10 +104,13 @@ export default defineNuxtPlugin(async (nuxtApp) => {
       }
       const ctx = createClientContext({
         name,
-        eventBridge: bridgeFactory(bus),
+        eventBridge: bridgeFactory,
         ui: {
           slots: ['plugins.page', 'settings.plugins', 'dashboard.widgets'],
-          registerPanel: entry => panels.registerPanel({ ...entry, plugin: name }),
+          // SDK 的 ClientPanelEntry.mount 声明为 void,宿主 PluginPanelEntry 则允许返回清理函数
+          // (宿主编排器按返回值回收面板)。这里只在边界处断言 mount 形状,entry 原样透传、不包一层:
+          // 插件真返回清理函数时仍会被回收,返回 void 时同样合法。
+          registerPanel: entry => panels.registerPanel({ ...entry, plugin: name, mount: entry.mount as PluginPanelEntry['mount'] }),
         },
         t: translatorFor(name),
         getLocale: () => {
@@ -168,7 +173,7 @@ export default defineNuxtPlugin(async (nuxtApp) => {
   const localeRef = i18n?.locale as { value?: string } | undefined
   if (localeRef && typeof localeRef === 'object') {
     watch(localeRef, (loc) => {
-      for (const { ctx } of loaded.values()) {
+      for (const ctx of loaded.values()) {
         try {
           ctx?.hooks?.emit('i18n:changed', { locale: loc })
         }
@@ -185,7 +190,7 @@ export default defineNuxtPlugin(async (nuxtApp) => {
         path = useRoute().path ?? ''
       }
       catch { /* 路由上下文不可用时静默 */ }
-      for (const { ctx } of loaded.values()) {
+      for (const ctx of loaded.values()) {
         try {
           ctx?.hooks?.emit('page:change', { path })
         }

package/app/stores/app.ts

@@ -5,6 +5,8 @@ export const useAppStore = defineStore('app', () => {
   // 默认暗色 = Digital Twin 控制室是产品首态(可切换亮色,选择被持久化)
   const isDark = ref(true)
   const sidebarCollapsed = ref(false)
+  /** 窄屏抽屉导航是否展开(不持久化:每次进入页面都应关闭) */
+  const mobileNavOpen = ref(false)
   /**
    * 用户是否在设置页/页头显式切换过明暗。
    * 只有"显式选择"才锁死主题,阻止服务端 theme.mode 的运行时跟随——
@@ -26,11 +28,41 @@ export const useAppStore = defineStore('app', () => {
     sidebarCollapsed.value = !sidebarCollapsed.value
   }
 
+  /**
+   * 抽屉式导航(窄屏,<900px)。与 sidebarCollapsed 分开的原因:
+   * 折叠是**桌面用户的持久偏好**(图标轨),抽屉是**窄屏的临时浮层**——
+   * 两者语义不同,共用一个状态会让"手机上开过一次抽屉"变成
+   * "桌面侧栏永久收起"(实测:antd Sider 的 breakpoint 就会这么干)。
+   */
+  function openMobileNav() {
+    mobileNavOpen.value = true
+  }
+
+  function closeMobileNav() {
+    mobileNavOpen.value = false
+  }
+
+  function toggleMobileNav() {
+    mobileNavOpen.value = !mobileNavOpen.value
+  }
+
   function setAccent(color: string | null) {
     accent.value = color
   }
 
-  return { isDark, sidebarCollapsed, accent, themeTouched, toggleDark, toggleSidebar, setAccent }
+  return {
+    isDark,
+    sidebarCollapsed,
+    mobileNavOpen,
+    accent,
+    themeTouched,
+    toggleDark,
+    toggleSidebar,
+    openMobileNav,
+    closeMobileNav,
+    toggleMobileNav,
+    setAccent,
+  }
 }, {
   persist: {
     pick: ['isDark', 'sidebarCollapsed', 'accent', 'themeTouched'],

package/app/stores/workshop/user.ts

@@ -176,7 +176,7 @@ export const useUserStore = defineStore('workshop.user', {
     // token 真源是 30 天 cookie;hydration 后从 cookie 回填,无 cookie 即回登出态
     pick: ['user'],
     afterHydrate: (ctx) => {
-      const store = ctx.store as { user?: { token?: string } | null, user?: CurrentUser | null, applyCookie?: () => void }
+      const store = ctx.store as { user?: CurrentUser | null, applyCookie?: () => void }
       if (!store.user) return
       try {
         const cookie = useCookie<string | null>('token')

package/app/stores/workshop/workspaces.ts

@@ -30,8 +30,21 @@ interface ServerWorkspace {
 }
 
 const ACTIVE_KEY = 'workshop.activeChannel'
+const ACTIVE_WS_KEY = 'workshop.activeWorkspace'
+
+/**
+ * localStorage 只在浏览器存在。这几个读写点都在 **store 的初始化路径**上
+ * (load() → saveActiveMap()),而 load() 完全可能被服务端调用 ——
+ * 少了守卫,一次 SSR 调用就会抛 "localStorage is not defined",
+ * 被 stability-guard 当成 fatal unhandledRejection **直接结束进程**
+ * (实测:生产实例在 /town 刷新后静默退出,日志只有一行 ReferenceError)。
+ *
+ * 约定与 app/stores/app.ts 一致:持久化层自己保证 SSR 安全,调用方不必先判断环境。
+ */
+const hasLocalStorage = (): boolean => typeof localStorage !== 'undefined'
 
 function loadActiveMap(): Record<string, string> {
+  if (!hasLocalStorage()) return {}
   try {
     return JSON.parse(localStorage.getItem(ACTIVE_KEY) ?? '{}') as Record<string, string>
   }
@@ -41,6 +54,7 @@ function loadActiveMap(): Record<string, string> {
 }
 
 function saveActiveMap(map: Record<string, string>): void {
+  if (!hasLocalStorage()) return
   localStorage.setItem(ACTIVE_KEY, JSON.stringify(map))
 }
 
@@ -51,12 +65,14 @@ export const useWorkspacesStore = defineStore('workshop.workspaces', {
   }),
   getters: {
     activeWorkspaceId(state): string | null {
-      return localStorage.getItem('workshop.activeWorkspace') ?? state.workspaces[0]?.id ?? null
+      if (!hasLocalStorage()) return state.workspaces[0]?.id ?? null
+      return localStorage.getItem(ACTIVE_WS_KEY) ?? state.workspaces[0]?.id ?? null
     },
   },
   actions: {
     setActiveWorkspaceId(id: string | null): void {
-      localStorage.setItem('workshop.activeWorkspace', id ?? '')
+      if (!hasLocalStorage()) return
+      localStorage.setItem(ACTIVE_WS_KEY, id ?? '')
     },
     /** 拉取服务端 workspace 列表(合并本地 activeChannelId) */
     async load(): Promise<void> {

package/app/utils/api-error.ts

@@ -20,7 +20,7 @@ interface ErrLike {
 }
 
 /** i18n 取不到时的内置回退(与 locales errors.* 保持一致,zh 优先项目) */
-const FALLBACK: Record<string, string> = {
+const FALLBACK = {
   http400: '请求参数有误,请检查后重试',
   http401: '登录已过期,请重新登录',
   http403: '权限不足:该操作需要管理员权限',

package/cli/commands/build.mjs

@@ -25,10 +25,17 @@ export async function run(argv, ctx) {
   console.log(`${color.cyan('›')} 构建生产产物 .output/ ...`)
   // 统一生命周期:转发 SIGINT/SIGTERM(子进程不再变孤儿) + 等待退出 + 超时强杀
   // + 退出码传播(被信号杀死 → 128+N,不再 code ?? 0 误报成功)
+  const env = localBypassEnv()
+  // Node ≥21 对 exports 里的"尾部斜杠映射"(\"./\": \"./x/\")发 DEP0155 弃用警告。
+  // 本项目依赖树里有两个这样的包(@babel/runtime → ./regenerator/、diff → ./lib/),
+  // 它们**不是我们的代码**,也改不动(除非 patch 上游);这条提示不影响产物正确性。
+  // 只关这一个 code,其它弃用/实验性警告照常显示 —— 不是把日志静音,是把
+  // "上游已弃用、我们无权修改"的确定噪音摘掉。
+  env.NODE_OPTIONS = [env.NODE_OPTIONS, '--disable-warning=DEP0155'].filter(Boolean).join(' ')
   const code = await runChild(process.execPath, [nuxtBin, 'build'], {
     cwd: root,
     stdio: 'inherit',
-    env: localBypassEnv(),
+    env,
     onSpawnError: err => console.log(`${color.red('✖')} 构建失败: ${err.message}`),
   })
   if (code !== 0) return code

package/docker-compose.yml

@@ -21,6 +21,12 @@ services:
   daq-timescale:
     image: timescale/timescaledb:latest-pg16
     container_name: awshop-daq-timescale
+    # ⚠️ 必须显式放大 /dev/shm:Docker 默认只给 64MB,而 PostgreSQL 的并行查询
+    # 会按需扩容共享内存段 —— 不够时报的错是
+    #   could not resize shared memory segment "...": No space left on device
+    # 这句话看起来像"磁盘满了",实际是 shm 满了,极难排查(实测在回退账本的
+    # 兜底评估查询上稳定复现,而宿主机还剩 230GB)。512MB 是 Postgres 官方镜像文档的建议值。
+    shm_size: 512mb
     environment:
       POSTGRES_USER: postgres        # config.yml daq.timescale.user
       POSTGRES_PASSWORD: awshop      # config.yml daq.timescale.password

package/docs/cli.en.md

@@ -62,7 +62,7 @@ pnpm tui             # the terminal workbench
 ### 3. Quick use via npx (no global install)
 
 ```bash
-npx agentworkshop start            # fetch and start (pin a version with: npx agentworkshop@0.7.38 start)
+npx agentworkshop start            # fetch and start (pin a version with: npx agentworkshop@0.7.41 start)
 npx agentworkshop doctor           # subcommands work as usual
 npx -p agentworkshop aw doctor     # use -p when you want the name aw
 ```
@@ -79,7 +79,7 @@ npx -p agentworkshop aw doctor     # use -p when you want the name aw
 | Package manager | `pnpm@11.9.0` (`packageManager`, needed only for source development) |
 | Module format | ESM (`type: module`) |
 | License | `PolyForm-Noncommercial-1.0.0` |
-| Current version | `0.7.38` (`package.json`) |
+| Current version | `0.7.41` (`package.json`) |
 
 ## 2. First start (the Claude Code experience)
 

package/docs/cli.md

@@ -60,7 +60,7 @@ pnpm tui             # 终端工作台
 ### 3. npx 快速使用（免全局安装）
 
 ```bash
-npx agentworkshop start            # 拉取并启动(可锁定版本: npx agentworkshop@0.7.38 start)
+npx agentworkshop start            # 拉取并启动(可锁定版本: npx agentworkshop@0.7.41 start)
 npx agentworkshop doctor           # 子命令照常可用
 npx -p agentworkshop aw doctor     # 需要 aw 这个名字时用 -p 指定包
 ```
@@ -76,7 +76,7 @@ npx -p agentworkshop aw doctor     # 需要 aw 这个名字时用 -p 指定包
 | 包管理器 | `pnpm@11.9.0`（`packageManager`，仅源码开发需要） |
 | 模块形态 | ESM（`type: module`） |
 | 许可证 | `PolyForm-Noncommercial-1.0.0` |
-| 当前版本 | `0.7.38`（`package.json`） |
+| 当前版本 | `0.7.41`（`package.json`） |
 
 ## 二、首次启动（Claude Code 式）
 

package/docs/plugins.en.md

@@ -9,7 +9,7 @@
 >
 > Applies to: plugin system v2 has been available since **v0.7.29** (frontend component
 > injection / plugin settings / plugin i18n / runtime services surface); this document
-> describes **v0.7.38**. `ctx.sdkVersion` is currently `0.3.0`.
+> describes **v0.7.41**. `ctx.sdkVersion` is currently `0.3.0`.
 
 ## 1. Folder layout & quick start
 
@@ -210,10 +210,41 @@ async setup(ctx) {
 | Events | `ctx.events.on(type, fn)` / `ctx.events.off(type, fn)` | scene-event sugar: subscribes to `event:<type>` internally (see §7) |
 | Paths | `ctx.paths.home / configRoot / dataDir`; `ctx.dataDir` | `ctx.dataDir` is this plugin's KV folder, `<configRoot>/data/plugins/<plugin>` |
 | DAQ | `ctx.daq.registerDriver / registerProcessor / registerTemplate / onFrame / onSample / query / nodes` | driver, sink-processor and node-template registration + time-series queries + node metadata snapshot |
+| Write control | `ctx.dcw.registerWriteDriver(driver)` | write-driver injection (symmetric to DAQ read drivers): contract `{ kind, available(), write(input), test(cfg), read?(input), meta? }`; disabled plugins lose their drivers on hot reload |
 | Tools | `ctx.omp.registerTool({ name, label?, description, parameters, roles?, handler })` | agent tool injection; `roles` accepts `'lead'` and `'worker'` only (see §10) |
 | Services | `ctx.services.names()` / `.get(name)` / `.provide(name, getter)` | runtime object surface: `get('daq' \| 'lines' \| 'channels' \| 'plugins')`; `provide` auto-prefixes `<plugin>.` |
 | Permissions | `ctx.permissions.lineMode / visibleLineIds / listGrants / setGrants` | line-grant queries and management |
 
+### Communication-protocol plugins (custom interface connections)
+
+`ctx.daq.registerDriver` / `ctx.dcw.registerWriteDriver` are the **protocol plug-in points**: serial
+links, other PLC protocols and private buses all inject here — the main pipelines (sampling loop /
+write gateway / frontend forms) need zero changes.
+
+```js
+ctx.daq.registerDriver({
+  kind: 'serial',                    // custom protocol kind (overriding a builtin logs a warning)
+  async available() { return true }, // protocol-stack probe (missing package → UI shows "not installed")
+  async sample({ driverConfig }) { return 25.3 },   // reading (scalar or v2 frame envelope)
+  async test(driverConfig) { return { ok: true, message: 'connected', sampleValue: 25.3 } },
+  meta: {                            // self-description (frontend "add node" dropdown + dynamic form)
+    label: 'Serial (RS-232/485)',
+    status: 'real',
+    configFields: [{ key: 'path', label: 'Port path', type: 'string', required: true, placeholder: 'COM3' }],
+  },
+})
+```
+
+Key points:
+- The driver catalog is served via the `drivers` field of `GET /api/workshop/daq` (read) and
+  `GET /api/workshop/dcw` (write); the DAQ/DCW pages render plugin protocols and their forms from it
+  (with a ⌁ badge). Drivers registered without `meta` only appear in availability;
+- Hot reload clears all plugin drivers first, then re-loads: **disabled/unloaded protocol drivers
+  take effect immediately upon removal** and never linger until restart;
+- Builtin example: `server/plugins-builtin/serial-bridge` (serial Modbus RTU + ASCII line protocol,
+  with read/write drivers, `health`/`ports`/`probe` APIs, a frontend panel and the `serial_ports`
+  agent tool) — use it as the template for new protocol plugins.
+
 ### Where KV lives
 
 `<configRoot>/data/plugins/<plugin>/kv.json` — **not** inside the plugin folder. Writes are authoritative in memory and flushed atomically (`tmp` + `rename`) after a 200 ms debounce; on shutdown and hot reload the pending debounce is cancelled and the state is flushed synchronously. `ctx.kv` has exactly four methods: `get / set / all / bump`.
@@ -524,6 +555,7 @@ export default {
 - **A newly enabled browser plugin injects within 15 s** (instantly when the WS channel is up).
 - **`server:close` / `onDispose` depend on graceful shutdown signals**; a forced kill on Windows does not trigger them.
 - **`aw plugin list` only scans directories** — it reflects neither load failures nor runtime health.
+- **Protocol plugins share the host process with their native stacks**: serial-bridge's RTU framing is a self-contained implementation (single serialport native stack; modbus-serial is deliberately NOT used — its wrapper reproducibly crashed under dev mode). Known boundary: **inside the `aw dev` process, a serial transaction that ends in write → timeout → close can trigger a native V8 crash in `bindings-cpp`** (HandleScope fatal — not catchable in JS, regardless of which port is used); **production mode (`aw start`) is unaffected — the exact same sequence was verified live to return an honest timeout with the server healthy**, and open-only probes are also fine under dev. Connect real hardware during development with this in mind; for hardened deployments, run the serial gateway in its own process (see the plc-node-simulator child-process pattern).
 
 ## 13. Pre-release checklist