agentworkshop 0.7.3 → 0.7.4

package/server/data/line-runs.json

@@ -7,7 +7,7 @@
     "productId": "pd-6348a595",
     "productName": "0.8mm 光学膜",
     "startedAt": "2026-09-03T11:18:01.213Z",
-    "taggedSamples": 0
+    "taggedSamples": 5708
   },
   {
     "lineId": "ln-9a60a0cd",
@@ -48,5 +48,15 @@
     "productName": "闭环验证产品",
     "startedAt": "2026-09-03T17:12:52.205Z",
     "taggedSamples": 0
+  },
+  {
+    "lineId": "ln-1b318320",
+    "runId": "rr-9e70a9dc",
+    "recipeId": "rc-ccee1b1b",
+    "recipeName": "探针配方",
+    "productId": "pd-db432902",
+    "productName": "探针产品",
+    "startedAt": "2026-09-04T05:08:10.103Z",
+    "taggedSamples": 470
   }
 ]

package/server/plugins/workshop.ts

@@ -30,6 +30,7 @@ import { createUserRepo } from '../services/workshop/db/user.repo'
 import { createChannelEventRepo } from '../services/workshop/db/channel-event.repo'
 import { createApprovalHistoryRepo, createAlarmEventRepo, createAuditRepo, createApprovalRequestRepo } from '../services/workshop/db/ops.repo'
 import { bindOpsRepos } from '../services/workshop/ops/ops'
+import { configureHitlResolver } from '../services/workshop/agents/hitl-registry'
 import { ensureAllEventRecorders } from '../api/workshop/ws'
 import { createAgentImpl } from '../services/workshop/agents/factory'
 import {
@@ -123,6 +124,12 @@ export default function workshopPlugin(nitroApp: {
   const manager = createAgentChannelManager(deps)
   globalThis.__workshopManager = manager
 
+  // HITL 全局待办:agentId → channelId/agentName 解析器(避免 registry 反向依赖 manager)
+  configureHitlResolver((agentId) => {
+    const row = repos.channelAgents.findById(agentId)
+    return row ? { channelId: row.channelId, agentName: row.name } : null
+  })
+
   // 懒加载恢复:仅激活有待办任务的 channel(装配 lead + 调度循环);其余纯持久化
   manager.restore()
 

package/server/services/workshop/agents/harness-terminal.ts

@@ -9,13 +9,18 @@
  *
  * HITL 语义:extension_ui_request(select/confirm/input/editor)到达时
  *  - 有 WS 订阅者(有人在看终端)→ 等待人类应答,无超时(真 HITL);
- *  - 无订阅者 → 自动 cancelled(等价 TUI 按 Esc;agent 的 ask 回合中止),
- *    并落一条 notice 帧让事后接入的观众可见。
+ *  - 无订阅者 → park 至 hitl-registry 并启动倒计时(security.hitl_timeout_ms,
+ *    默认 180s;倒计时仅在零订阅期间进行,任一客户端接入终端即暂停)——
+ *    到期自动 cancelled(等价 TUI 按 Esc;agent 的 ask 回合中止),并落一条
+ *    notice 帧让事后接入的观众可见。TTL 配 0 恢复旧的"无人即秒取消"行为。
+ *    待办全局可见性/应答路由由 hitl-registry + /api/workshop/hitl/* 承接。
  *
  * 定位:模块级单例(globalThis 跨 HMR 存活,与 workshop ws hub 同风格);
  * omp-agent 装配时 attach,manager 监控层读取 hasTerminalSession 标记进程行。
  */
-import { createLogger } from '../logger'
+import { createLogger } from '../logger'
+import { securityHitlTimeoutMs } from '../settings'
+import { getHitlRegistry } from './hitl-registry'
 import type { OmpRpcClient } from './adapters/omp-rpc-client'
 import {
   TERM_FRAME_TEXT_PREVIEW_MAX,
@@ -43,6 +48,8 @@ interface TerminalSession {
   alive: boolean
   exitCode: number | null
   pendingHitl: TerminalHitlDialog | null
+  /** 零订阅 park 倒计时(有人接入即清除;到期自动取消待答对话框) */
+  parkTimer: NodeJS.Timeout | null
   unsubRaw: (() => void) | null
   /** 微批缓冲 + 定时器(50ms 合并 delta 帧,防 WS 洪泛) */
   batch: TermFrame[]
@@ -234,29 +241,83 @@ function hitlViewOf(frame: Record<string, unknown> | null): TerminalHitlDialog |
   }
 }
 
-/** HITL 对话框到达:登记 pending;无订阅者 → 自动 cancelled */
+/** HITL 对话框到达:登记 pending + hitl-registry;零订阅时进入 park 倒计时 */
 function handleUiRequest(session: TerminalSession, frame: Record<string, unknown>): void {
   const method = frame.method as string
   if (method === 'cancel') {
-    // omp 主动撤销对话框(如回合中止):清 pending
+    // omp 主动撤销对话框(如回合中止):清 pending + 落定全局待办
     const targetId = String(frame.targetId ?? '')
-    if (session.pendingHitl && session.pendingHitl.id === targetId) session.pendingHitl = null
+    if (session.pendingHitl && session.pendingHitl.id === targetId) {
+      session.pendingHitl = null
+      clearParkTimer(session)
+      getHitlRegistry().resolve('omp-dialog', targetId, 'cancelled')
+    }
     return
   }
   const view = hitlViewOf(frame)
   if (!view) return
   session.pendingHitl = view
-  if (session.listeners.size === 0) {
-    // 无人观看:自动取消(Esc 语义),事后观众通过 notice 帧可见
-    respondUi(session, { id: view.id, cancelled: true })
-    pushFrame(session, {
-      type: '__terminal_notice',
-      level: 'warning',
-      message: `HITL 对话框(${view.method} "${view.title.slice(0, 40)}")无人接入,已自动取消`,
-    })
+  getHitlRegistry().register({
+    kind: 'omp-dialog',
+    id: view.id,
+    agentId: session.meta.agentId,
+    agentName: session.meta.name,
+    channelId: session.meta.channelId,
+    pid: session.meta.pid,
+    method: view.method,
+    title: view.title,
+    options: view.options,
+    message: view.message,
+  })
+  if (session.listeners.size === 0) armParkTimer(session)
+}
+
+// ===== park 倒计时(无人观看时挂起等待;有人接入暂停) =====
+
+/** 零订阅 park 窗口(security.hitl_timeout_ms;0 = 恢复旧的"无人即秒取消") */
+const HITL_PARK_MS = (): number => securityHitlTimeoutMs()
+
+function clearParkTimer(session: TerminalSession): void {
+  if (session.parkTimer) {
+    clearTimeout(session.parkTimer)
+    session.parkTimer = null
   }
 }
 
+/** 进入 park(仅零订阅且有待答对话框时生效;TTL<=0 立即取消 = 旧行为) */
+function armParkTimer(session: TerminalSession): void {
+  clearParkTimer(session)
+  if (!session.pendingHitl || session.listeners.size > 0) return
+  const ttl = HITL_PARK_MS()
+  if (ttl <= 0) {
+    expirePendingHitl(session, true)
+    return
+  }
+  getHitlRegistry().setParkDeadline('omp-dialog', session.pendingHitl.id, new Date(Date.now() + ttl).toISOString())
+  session.parkTimer = setTimeout(() => {
+    session.parkTimer = null
+    if (session.pendingHitl && session.listeners.size === 0) expirePendingHitl(session)
+  }, ttl)
+  session.parkTimer.unref?.()
+}
+
+/** park 到期(或 TTL=0 立即):超时收敛 —— 先落定 expired,再走 cancelled 应答写 omp stdin */
+function expirePendingHitl(session: TerminalSession, immediate = false): void {
+  const hitl = session.pendingHitl
+  if (!hitl) return
+  session.pendingHitl = null
+  clearParkTimer(session)
+  getHitlRegistry().resolve('omp-dialog', hitl.id, 'expired')
+  respondUi(session, { id: hitl.id, cancelled: true })
+  pushFrame(session, {
+    type: '__terminal_notice',
+    level: 'warning',
+    message: immediate
+      ? `HITL 对话框(${hitl.method} "${hitl.title.slice(0, 40)}")无人接入,已自动取消`
+      : `HITL 对话框(${hitl.method} "${hitl.title.slice(0, 40)}")park 超时无人处理,已自动取消`,
+  })
+}
+
 // ===== 对外 API =====
 
 /**
@@ -287,6 +348,7 @@ export function attachTerminalTap(
     alive: true,
     exitCode: null,
     pendingHitl: null,
+    parkTimer: null,
     unsubRaw: null,
     batch: [],
     batchTimer: null,
@@ -337,7 +399,11 @@ export function markTerminalSessionExit(pid: number, exitCode: number | null): v
   detachTerminalTap(pid)
   session.alive = false
   session.exitCode = exitCode
-  session.pendingHitl = null
+  if (session.pendingHitl) {
+    getHitlRegistry().resolve('omp-dialog', session.pendingHitl.id, 'cancelled')
+    session.pendingHitl = null
+  }
+  clearParkTimer(session)
   session.running = false
   session.streaming = false
   flushNow(session)
@@ -442,19 +508,17 @@ export function subscribeTerminal(
 ): (() => void) | null {
   const session = sessions.get(pid)
   if (!session) return null
+  const wasEmpty = session.listeners.size === 0
   session.listeners.add(listener)
+  if (wasEmpty && session.pendingHitl) {
+    // 有人观看:暂停 park 倒计时(真 HITL 等待无上限;观看者离开后重新计时)
+    clearParkTimer(session)
+    getHitlRegistry().setParkDeadline('omp-dialog', session.pendingHitl.id, null)
+  }
   return () => {
     session.listeners.delete(listener)
-    // 订阅者归零时若还有待应答对话框 → 自动取消(观看者离开 = 放弃应答权)
-    if (session.listeners.size === 0 && session.pendingHitl) {
-      const hitl = session.pendingHitl
-      respondUi(session, { id: hitl.id, cancelled: true })
-      pushFrame(session, {
-        type: '__terminal_notice',
-        level: 'warning',
-        message: `观看者已全部离开,HITL 对话框(${hitl.method} "${hitl.title.slice(0, 40)}")自动取消`,
-      })
-    }
+    // 订阅者归零时若还有待应答对话框:park 倒计时(超时自动取消;不再是秒取消)
+    if (session.listeners.size === 0 && session.pendingHitl) armParkTimer(session)
   }
 }
 
@@ -526,6 +590,7 @@ function respondUi(
   response: { id: string, value?: string, confirmed?: boolean, cancelled?: boolean },
 ): void {
   if (session.pendingHitl && session.pendingHitl.id === response.id) session.pendingHitl = null
+  clearParkTimer(session)
   const frame: Record<string, unknown> = { type: 'extension_ui_response', id: response.id }
   if (response.cancelled) {
     frame.cancelled = true
@@ -542,4 +607,6 @@ function respondUi(
   catch (err) {
     log.error(`[harness-terminal] extension_ui_response 写入失败(pid=${session.meta.pid}):`, err)
   }
+  // 全局待办落定(expired 收敛路径已先行 resolve,此处幂等 no-op)
+  getHitlRegistry().resolve('omp-dialog', response.id, response.cancelled ? 'cancelled' : 'answered')
 }

package/server/services/workshop/agents/hitl-registry.ts

@@ -0,0 +1,181 @@
+/**
+ * HitlRegistry —— 全局"待人工处理"登记处(进程内,globalThis 单例)。
+ *
+ * 把两条互相独立的 HITL 链路统一成一个可发现的视图:
+ *  - omp-dialog   omp `rpc-ui` 的 extension_ui_request 对话框(harness-terminal 登记;
+ *                 park/暂停计时语义由 terminal 订阅者状态驱动,本模块只存状态与广播)
+ *  - dcw-approval 手动确认模式的工具执行审批(tool-approvals 登记/裁决)
+ *
+ * 职责:登记(hitl.request)/ 落定(hitl.resolved)事件经 per-channel 订阅扇出,
+ * 由 workshop ws hub 转接进 AEP 频道流(seq/落库);统一 REST 快照与应答路由
+ * (/api/workshop/hitl/pending、/respond)也读本模块。裁决留痕仍在各链路
+ * (approval_history / audit),这里不做持久化 —— omp 对话框本就随子进程消亡。
+ *
+ * 定位:模块级单例(globalThis 跨 HMR 存活,与 tool-approvals 同风格);
+ * 不 import runtime/manager(避免循环初始化),channelId 由插件注入 resolver 解析。
+ */
+import type { AepHitlItem, AepHitlResolved } from '../../../../shared/workshop-protocol'
+
+export type HitlKind = AepHitlItem['kind']
+export type HitlOutcome = AepHitlResolved['outcome']
+
+/** hitl 帧事件(ws hub 按 channelId 转接进频道流) */
+export interface HitlEvent {
+  type: 'hitl.request' | 'hitl.resolved'
+  payload: AepHitlItem | AepHitlResolved
+  agentId?: string
+}
+
+type HitlListener = (e: HitlEvent) => void
+
+/** 登记入参(channelId/agentName 可由 resolver 补全;缺 channelId 的条目仅入全局快照) */
+export interface HitlRegisterInput {
+  kind: HitlKind
+  id: string
+  agentId: string
+  agentName?: string
+  channelId?: string
+  pid?: number
+  method?: AepHitlItem['method']
+  title: string
+  detail?: string
+  options?: string[]
+  message?: string
+  createdAt?: string
+  expiresAt?: string | null
+}
+
+class HitlRegistryService {
+  /** key = `${kind}:${id}`;value 为 AepHitlItem(parkDeadline 单独存,避免污染协议对象) */
+  private items = new Map<string, AepHitlItem>()
+  private parkDeadline = new Map<string, string | null>()
+  private listeners = new Map<string, Set<HitlListener>>()
+  /** agentId → { channelId, agentName }(插件装配 repos 后注入;避免反向依赖 manager) */
+  private resolver: ((agentId: string) => { channelId: string, agentName: string } | null) | null = null
+
+  configureResolver(fn: (agentId: string) => { channelId: string, agentName: string } | null): void {
+    this.resolver = fn
+  }
+
+  private key(kind: HitlKind, id: string): string {
+    return `${kind}:${id}`
+  }
+
+  /** 登记(幂等:同 kind+id 重复登记只更新 parkDeadline,不重发事件) */
+  register(input: HitlRegisterInput): void {
+    const key = this.key(input.kind, input.id)
+    const existing = this.items.get(key)
+    if (existing) return
+    let channelId = input.channelId ?? ''
+    let agentName = input.agentName ?? ''
+    if ((!channelId || !agentName) && this.resolver) {
+      try {
+        const resolved = this.resolver(input.agentId)
+        channelId = channelId || resolved?.channelId || ''
+        agentName = agentName || resolved?.agentName || ''
+      }
+      catch { /* resolver 异常不阻断登记 */ }
+    }
+    const item: AepHitlItem = {
+      kind: input.kind,
+      id: input.id,
+      channelId,
+      agentId: input.agentId,
+      agentName: agentName || input.agentId.slice(0, 8),
+      pid: input.pid,
+      method: input.method,
+      title: input.title,
+      detail: input.detail,
+      options: input.options,
+      message: input.message,
+      createdAt: input.createdAt ?? new Date().toISOString(),
+      expiresAt: input.expiresAt ?? null,
+    }
+    this.items.set(key, item)
+    this.parkDeadline.set(key, item.expiresAt ?? null)
+    this.emit({ type: 'hitl.request', payload: item, agentId: item.agentId })
+  }
+
+  /**
+   * 落定(幂等:未登记的 key 返回 false —— 上层据此实现 409 ALREADY_RESOLVED)。
+   * outcome:answered(人类已答复/批准/拒绝)/ cancelled(人工放弃或 omp 撤销)/ expired(超时)。
+   */
+  resolve(kind: HitlKind, id: string, outcome: HitlOutcome, by?: string): boolean {
+    const key = this.key(kind, id)
+    const item = this.items.get(key)
+    if (!item) return false
+    this.items.delete(key)
+    this.parkDeadline.delete(key)
+    const payload: AepHitlResolved = {
+      kind,
+      id,
+      channelId: item.channelId,
+      agentId: item.agentId,
+      outcome,
+      by,
+    }
+    this.emit({ type: 'hitl.resolved', payload, agentId: item.agentId })
+    return true
+  }
+
+  /** 查询单条(应答路由用:取 pid / channelId / method) */
+  find(kind: HitlKind, id: string): AepHitlItem | null {
+    return this.items.get(this.key(kind, id)) ?? null
+  }
+
+  /** park 截止更新(harness-terminal 订阅者增减时静默修正;null = 计时暂停) */
+  setParkDeadline(kind: HitlKind, id: string, expiresAt: string | null): void {
+    const key = this.key(kind, id)
+    if (!this.items.has(key)) return
+    this.parkDeadline.set(key, expiresAt)
+    const item = this.items.get(key)!
+    item.expiresAt = expiresAt
+  }
+
+  /** 全局(或指定 channel)待处理快照 */
+  snapshot(channelId?: string): AepHitlItem[] {
+    return [...this.items.values()].filter(i => !channelId || i.channelId === channelId)
+  }
+
+  /** per-channel 事件订阅(ws hub ensureStream 时接线;返回退订函数) */
+  subscribe(channelId: string, fn: HitlListener): () => void {
+    let set = this.listeners.get(channelId)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(channelId, set)
+    }
+    set.add(fn)
+    return () => {
+      set.delete(fn)
+      if (set.size === 0) this.listeners.delete(channelId)
+    }
+  }
+
+  private emit(e: HitlEvent): void {
+    const channelId = (e.payload as AepHitlItem).channelId
+    const set = channelId ? this.listeners.get(channelId) : undefined
+    if (!set) return
+    for (const fn of set) {
+      try {
+        fn(e)
+      }
+      catch { /* 单个订阅者异常不影响扇出 */ }
+    }
+  }
+}
+
+const g = globalThis as typeof globalThis & { __hitlRegistry?: HitlRegistryService }
+
+export function getHitlRegistry(): HitlRegistryService {
+  g.__hitlRegistry ??= new HitlRegistryService()
+  return g.__hitlRegistry
+}
+
+/** 插件接线用别名(语义直白) */
+export const configureHitlResolver = (fn: (agentId: string) => { channelId: string, agentName: string } | null): void =>
+  getHitlRegistry().configureResolver(fn)
+
+/** per-channel 事件订阅(ws hub 建流时挂接;hitl.request/hitl.resolved 扇出) */
+export function subscribeHitlEvents(channelId: string, fn: HitlListener): () => void {
+  return getHitlRegistry().subscribe(channelId, fn)
+}

package/server/services/workshop/agents/tool-approvals.ts

@@ -9,6 +9,7 @@
 import { randomUUID } from 'node:crypto'
 import { getOps } from '../ops/ops'
 import { securityHitlTimeoutMs } from '../settings'
+import { getHitlRegistry } from './hitl-registry'
 
 export interface ToolApproval {
   id: string
@@ -57,6 +58,17 @@ class ToolApprovalService {
       decidedBy: '',
       decidedName: '',
     }
+    // 全局 HITL 待办登记(channelId/agentName 由插件注入的 resolver 补全;
+    // expiresAt 与审批超时窗同源,前端可显示倒计时)
+    getHitlRegistry().register({
+      kind: 'dcw-approval',
+      id: approval.id,
+      agentId: approval.agentId,
+      title: `${approval.kind.toUpperCase()} 下发审批`,
+      detail: approval.detail,
+      createdAt: approval.createdAt,
+      expiresAt: approval.expiresAt,
+    })
     return new Promise((resolve) => {
       const timer = setTimeout(() => {
         if (!this.pending.has(approval.id)) return
@@ -65,6 +77,7 @@ class ToolApprovalService {
         approval.decidedAt = new Date().toISOString()
         approval.comment = '审批超时未处理,默认拒绝,指令未执行'
         this.remember(approval)
+        getHitlRegistry().resolve('dcw-approval', approval.id, 'expired')
         resolve({ approved: false, comment: approval.comment, id: approval.id })
       }, TIMEOUT_MS())
       timer.unref?.()
@@ -83,6 +96,7 @@ class ToolApprovalService {
     entry.approval.decidedBy = decidedBy
     entry.approval.decidedName = decidedName
     this.remember(entry.approval)
+    getHitlRegistry().resolve('dcw-approval', id, 'answered', decidedBy || undefined)
     entry.resolve({ approved, comment: entry.approval.comment, id })
     return entry.approval
   }
@@ -105,6 +119,7 @@ class ToolApprovalService {
       entry.approval.comment = '绑定已解除,审批失效'
       entry.approval.decidedAt = new Date().toISOString()
       this.remember(entry.approval)
+      getHitlRegistry().resolve('dcw-approval', id, 'cancelled')
       entry.resolve({ approved: false, comment: entry.approval.comment, id })
       n++
     }

package/server/services/workshop/scene-events.ts

@@ -7,7 +7,6 @@
  * 路由改为从本模块导入广播函数 —— 避免"路由文件被当库静态导入"引发
  * nitro 打包的循环初始化(TDZ)问题。
  */
-import type { AepEnvelope } from '../../../shared/workshop-protocol'
 import { emitPluginEvent } from './plugins/host.mjs'
 
 const AEP_VERSION = 1
@@ -46,15 +45,26 @@ export function broadcastSceneEvent(type: string, payload: unknown): void {
   // 插件宿主事件桥(event:<type> 钩子;宿主未装载时 no-op)——先于 peers 短路,插件不依赖在线页面
   emitPluginEvent(type, payload)
   if (peers().size === 0) return
-  const e: AepEnvelope = {
-    v: AEP_VERSION,
-    type,
-    seq: 0,
-    at: new Date().toISOString(),
-    channelId: '',
-    payload: payload as AepEnvelope['payload'],
+  const frame = JSON.stringify({ v: AEP_VERSION, type, seq: 0, at: new Date().toISOString(), channelId: '', payload })
+  for (const peer of peers()) {
+    try {
+      peer.send(frame)
+    }
+    catch {
+      peers().delete(peer)
+    }
   }
-  const frame = JSON.stringify(e)
+}
+
+/**
+ * 全员直推(不触发插件宿主事件桥):给已有频道归属、但需要"全局主动提醒"
+ * 语义的低频事件用(hitl.request/hitl.resolved —— WebUI 徽标/TUI 状态条不依赖
+ * channel 订阅即达)。与 broadcastSceneEvent 的差别仅在不二次 emitPluginEvent
+ * (频道流 publish 路径已各发一次,避免插件钩子重复触发)。
+ */
+export function broadcastPeerEvent(type: string, payload: unknown): void {
+  if (peers().size === 0) return
+  const frame = JSON.stringify({ v: AEP_VERSION, type, seq: 0, at: new Date().toISOString(), channelId: '', payload })
   for (const peer of peers()) {
     try {
       peer.send(frame)

package/shared/workshop-protocol.ts

@@ -118,6 +118,40 @@ export interface AepSceneLayout {
   rotationY: number
 }
 
+/** hitl.request payload:待人工处理条目(omp ask 对话框与 dcw 工具审批的统一视图) */
+export interface AepHitlItem {
+  kind: 'omp-dialog' | 'dcw-approval'
+  /** omp:对话框 id;dcw:审批 id(ap-*) */
+  id: string
+  channelId: string
+  agentId: string
+  agentName: string
+  /** omp 子进程 pid(应答路由 respondTerminalUi 用) */
+  pid?: number
+  /** omp-dialog 专属:对话框形态 */
+  method?: 'select' | 'confirm' | 'input' | 'editor'
+  title: string
+  /** dcw-approval 专属:人读摘要(节点/物理量/目标值) */
+  detail?: string
+  /** select 的选项列表 */
+  options?: string[]
+  message?: string
+  createdAt: string
+  /** park 截止时刻(omp 对话框零订阅倒计时;null = 有订阅者,计时暂停) */
+  expiresAt?: string | null
+}
+
+/** hitl.resolved payload:待办落定(answered=已答复/cancelled=放弃或撤销/expired=超时) */
+export interface AepHitlResolved {
+  kind: AepHitlItem['kind']
+  id: string
+  channelId: string
+  agentId: string
+  outcome: 'answered' | 'cancelled' | 'expired'
+  /** 落定方(user id / system) */
+  by?: string
+}
+
 export type AepEvent
   = | { type: 'channel.snapshot', payload: AepSnapshot }
     | { type: 'agent.status', payload: { agentId: string, state: 'idle' | 'busy' | 'stopped', currentTaskId?: string | null, queued?: number, completed?: number } }
@@ -135,6 +169,8 @@ export type AepEvent
     | { type: 'device.deleted', payload: { id: string, name: string } }
     | { type: 'scene.layout.saved', payload: AepSceneLayout }
     | { type: 'scene.layout.removed', payload: { channelId: string } }
+    | { type: 'hitl.request', payload: AepHitlItem }
+    | { type: 'hitl.resolved', payload: AepHitlResolved }
     | { type: 'daq.reading', payload: AepDaqReading }
     | { type: 'daq.node.changed', payload: AepDaqNodeChange }
     | { type: 'daq.controller', payload: AepDaqControllerState }
@@ -192,6 +228,7 @@ export const AEP_GROUPS: Record<string, string[]> = {
   team: ['agent.member'],
   devices: ['device.created', 'device.updated', 'device.deleted'],
   scene: ['scene.layout.saved', 'scene.layout.removed'],
+  hitl: ['hitl.request', 'hitl.resolved'],
   daq: ['daq.reading', 'daq.node.changed', 'daq.controller', 'daq.template.changed', 'daq.alarm', 'daq.alarm.changed'],
   dcw: ['dcw.node.changed', 'dcw.written', 'dcw.controller', 'dcw.optimization.changed'],
   ops: ['ops.log'],

package/tui/README.md

@@ -0,0 +1,65 @@
+# AgentWorkShop TUI —— 终端工作台
+
+与 AgentTeam 交互作业的终端客户端(pi-tui 组件化渲染,与 WebUI 平级的瘦客户端):
+创建/切换 Channel、放置 Agent、发送任务、实时查看执行过程,以及 **HITL 待办
+(omp ask 对话框 / dcw 下发审批)的统一提醒与作答**。
+
+## 启动
+
+```bash
+aw tui                          # 或:pnpm tui / node tui/aw-tui.mjs
+aw tui --url http://127.0.0.1:3000 --token ut-xxxx --channel <名>
+```
+
+- 首次使用交互式登录(邮箱+密码);凭据落 `<配置根>/tui-auth.json`(0600,
+  已 gitignore)。也可用环境变量 `AW_TUI_EMAIL` / `AW_TUI_PASSWORD` 免交互。
+- 需要服务端已运行(`pnpm dev` 或 `aw start`)。
+
+## 界面
+
+```
+┌ 会话时间线(左)                          ┌ 监控面板(右,/monitor 开启)
+│ ◆ 你 消息 · ◆ Agent 回复 · 任务状态行    │ ┌─ 监控 <agent> · 流式中
+├ HITL 作答卡(/hitl <n> 进入作答时出现)
+├ 状态条:频道 · 成员(忙 n) · HITL 待处理 n · 连接态
+└ 输入框(/ 命令补全 · ↑↓ 历史)
+```
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `/help` | 命令列表 |
+| `/channels` | 列出我的频道 |
+| `/channel new <名> [--desc …] [--lead <名>]` | 创建频道(可选内联建 lead) |
+| `/channel use <名\|序号>` | 切换频道(WS 断点续传) |
+| `/channel add <模板\|名> [--role lead\|worker] [--harness omp] [--config JSON]` | 放置 Agent 实例 |
+| `/agents` | 当前频道成员与实时状态 |
+| `/send <agent\|序号> <文本…>` | 向指定 Agent 直发(忙碌时 steer 注入) |
+| `/task <标题…> [--mode goal\|loop\|pipeline] [--assignee <agent>]` | 提交正式任务 |
+| `/tasks` | 任务列表与七态/进度 |
+| `/monitor <agent\|序号\|off>` | 开/关右侧终端镜像(实时执行过程) |
+| `/hitl [序号\|off]` | 待人工处理列表/进入作答/放弃作答 |
+| `/quit` | 退出 |
+
+普通文本 = 向当前频道 lead 发送任务(`priority=task`)。
+
+## HITL 流程(与 WebUI 同一套服务端)
+
+1. Agent 需要人类确认/ask 时,服务端 hitl-registry 登记待办,所有已连接
+   客户端(WebUI 徽标 / TUI 状态条)收到 `hitl.request` 帧 → 提醒亮起。
+2. TUI:`/hitl` 看列表 → `/hitl <序号>` 进入作答卡(自动可配合 `/monitor`
+   观察现场);confirm 输 `y/n`,select 输序号,input/editor 直接输入。
+3. 回车提交 → `POST /api/workshop/hitl/respond` → extension_ui_response
+   直写 omp stdin(或 dcw 审批落定)→ `hitl.resolved` 帧 → 双端提醒消隐。
+4. 无人观看时对话框 park `security.hitl_timeout_ms`(默认 180s,仅零订阅
+   期间倒计时,有人接入终端即暂停;配 0 恢复旧的立即取消行为)。
+
+## 测试
+
+```bash
+node scripts/test-hitl-registry.ts     # 服务端 registry + park 语义(需 tsx)
+node scripts/test-tui-reducers.mjs     # AEP 帧归约
+node scripts/test-tui-commands.mjs     # 命令解析/分发
+node scripts/tui-smoke.mjs             # 无头 e2e(需 dev server 运行)
+```