agentworkshop 0.7.5 → 0.7.7

package/server/services/workshop/scene/scene-layout.repo.ts

@@ -9,8 +9,8 @@
  * 应用级单例,写入 server/data/scene-layouts.json,进程内缓存,启动读盘。
  */
 
-import fs from 'node:fs'
 import path from 'node:path'
+import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
 
 export interface SceneLayout {
   channelId: string
@@ -44,18 +44,11 @@ const DB_PATH = process.cwd().endsWith('server')
   : path.join(process.cwd(), 'server', 'data', 'scene-layouts.json')
 
 function load(): SceneLayout[] {
-  try {
-    const raw = fs.readFileSync(DB_PATH, 'utf-8')
-    const parsed = JSON.parse(raw)
-    return Array.isArray(parsed) ? parsed : []
-  }
-  catch {
-    return []
-  }
+  const parsed = loadJsonFile(DB_PATH, [])
+  return Array.isArray(parsed) ? parsed as SceneLayout[] : []
 }
 function save(list: SceneLayout[]): void {
-  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true })
-  fs.writeFileSync(DB_PATH, JSON.stringify(list, null, 2), 'utf-8')
+  saveJsonFileAtomic(DB_PATH, list)
 }
 
 class SceneLayoutRepo {

package/server/services/workshop/settings.ts

@@ -69,6 +69,12 @@ export interface OmpSettings {
   compact_min_interval_ms: number
   compact_wait_ms: number
 }
+export interface HarnessSettings {
+  opencode_command: string
+  codex_command: string
+  dsh_command: string
+  hitl_timeout_ms: number
+}
 export interface DcwSettings {
   rollback_cooldown_ms: number
   rollback_min_window_ms: number
@@ -113,6 +119,7 @@ export interface DaqRuntimeSettings {
 
 export const memorySettings = (): MemorySettings => section<MemorySettings>('memory')
 export const ompSettings = (): OmpSettings => section<OmpSettings>('omp')
+export const harnessSettings = (): HarnessSettings => section<HarnessSettings>('harness')
 export const dcwSettings = (): DcwSettings => section<DcwSettings>('dcw')
 export const workshopSettings = (): WorkshopSettings => section<WorkshopSettings>('workshop')
 export const backupSettings = (): BackupSettings => section<BackupSettings>('backup')

package/shared/config/schema.json

@@ -59,6 +59,11 @@
     { "key": "omp.compact_min_interval_ms", "type": "number", "group": "omp", "label": "压缩最小间隔(ms)", "labelKey": "settings.runtime.omp.compactMinIntervalMs", "description": "两次自动压缩之间的最小间隔", "applies": "restart", "default": 300000, "min": 30000, "max": 3600000 },
     { "key": "omp.compact_wait_ms", "type": "number", "group": "omp", "label": "压缩等待超时(ms)", "labelKey": "settings.runtime.omp.compactWaitMs", "description": "等待 compaction_end 完成事件的超时", "applies": "restart", "default": 120000, "min": 10000, "max": 600000 },
 
+    { "key": "harness.opencode_command", "type": "string", "group": "harness", "label": "opencode 命令", "labelKey": "settings.runtime.harness.opencodeCommand", "description": "OpenCode 引擎可执行文件(PATH 解析)", "applies": "restart", "default": "opencode" },
+    { "key": "harness.codex_command", "type": "string", "group": "harness", "label": "codex 命令", "labelKey": "settings.runtime.harness.codexCommand", "description": "OpenAI Codex CLI 可执行文件(app-server 模式)", "applies": "restart", "default": "codex" },
+    { "key": "harness.dsh_command", "type": "string", "group": "harness", "label": "dsh 命令", "labelKey": "settings.runtime.harness.dshCommand", "description": "DeepSeek Harness 可执行文件(ACP 模式)", "applies": "restart", "default": "dsh" },
+    { "key": "harness.hitl_timeout_ms", "type": "number", "group": "harness", "label": "引擎审批超时(ms)", "labelKey": "settings.runtime.harness.hitlTimeoutMs", "description": "codex/opencode/dsh 权限审批无人应答的自动拒绝时限(0=无限等待)", "applies": "restart", "default": 300000, "min": 0, "max": 3600000 },
+
     { "key": "dcw.rollback_cooldown_ms", "type": "number", "group": "dcw", "label": "回退冷却(ms)", "labelKey": "settings.runtime.dcw.rollbackCooldownMs", "description": "回退执行后的同向冷却窗", "applies": "restart", "default": 300000, "min": 0, "max": 3600000 },
     { "key": "dcw.rollback_min_window_ms", "type": "number", "group": "dcw", "label": "回退最小观察窗(ms)", "labelKey": "settings.runtime.dcw.rollbackMinWindowMs", "description": "开记录后允许判定的最小观察窗", "applies": "restart", "default": 120000, "min": 0, "max": 3600000 },
     { "key": "dcw.rollback_baseline_ms", "type": "number", "group": "dcw", "label": "基线稳定窗(ms)", "labelKey": "settings.runtime.dcw.rollbackBaselineMs", "description": "上一稳定锚的稳定时间要求", "applies": "restart", "default": 600000, "min": 0, "max": 7200000 },

package/shared/config/single-instance.mjs

@@ -1,86 +1,133 @@
-// ============================================================
-// 单实例互斥(hardening ST-1)—— 零依赖,CLI / 启动脚本通用。
-// 锁文件 <configRoot>/.runtime/aw.lock 原子创建(wx):
-//   { pid, startedAt, mode, port }
-// 已存在且 PID 存活 → 视为已有实例(返回冲突信息,调用方以退出码 2 退出);
-// PID 已死(崩溃/强杀残留) → 自动接管重写。进程退出时 releaseLock 兜底清理。
-// ============================================================
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-function pidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false
-  try {
-    // signal 0 探活:进程存在但不发信号;ESRCH=不存在,EPERM=存在(他人进程)
-    process.kill(pid, 0)
-    return true
-  }
-  catch (err) {
-    return err?.code === 'EPERM'
-  }
-}
-
-/**
- * 尝试获取单实例锁。
- * @returns {{ ok: true, lockPath: string, release: () => void }
- *   | { ok: false, lockPath: string, holder: { pid: number, startedAt: string, mode: string, port: number | null } }}
- */
-export function acquireLock(configRoot, { mode = 'prod', port = null } = {}) {
-  const runtimeDir = join(configRoot, '.runtime')
-  const lockPath = join(runtimeDir, 'aw.lock')
-  mkdirSync(runtimeDir, { recursive: true })
-  if (existsSync(lockPath)) {
-    let holder = null
-    try {
-      holder = JSON.parse(readFileSync(lockPath, 'utf8'))
-    }
-    catch { /* 损坏锁文件按残留处理 */ }
-    if (holder && pidAlive(holder.pid)) {
-      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
-    }
-    try { rmSync(lockPath) } catch { /* 抢不掉则下方 wx 再失败 */ }
-  }
-  const me = { pid: process.pid, startedAt: new Date().toISOString(), mode, port }
-  try {
-    writeFileSync(lockPath, JSON.stringify(me, null, 2), { flag: 'wx' })
-  }
-  catch (err) {
-    // 与并发启动者竞态:按冲突处理
-    let holder = null
-    try { holder = JSON.parse(readFileSync(lockPath, 'utf8')) } catch { /* ignore */ }
-    if (holder && pidAlive(holder.pid)) {
-      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
-    }
-    throw err
-  }
-  let released = false
-  const release = () => {
-    if (released) return
-    released = true
-    try {
-      const cur = JSON.parse(readFileSync(lockPath, 'utf8'))
-      if (cur?.pid !== process.pid) return // 锁已被他人接管,不误删
-      rmSync(lockPath)
-    }
-    catch { /* 已不存在/损坏,忽略 */ }
-  }
-  process.once('exit', release)
-  process.once('SIGINT', () => { release(); process.exit(130) })
-  process.once('SIGTERM', () => { release(); process.exit(143) })
-  return { ok: true, lockPath, release }
-}
-
-/** 端口占用探测:返回占用进程 PID(未占用返回 null)。TCP try-listen 后立刻释放。 */
-export async function checkPort(host, port) {
-  const net = await import('node:net')
-  return new Promise((resolveProbe) => {
-    const srv = net.createServer()
-    srv.once('error', (err) => {
-      resolveProbe(err?.code === 'EADDRINUSE' ? port : null)
-      srv.close()
-    })
-    srv.listen(port, host, () => {
-      srv.close(() => resolveProbe(null))
-    })
-  })
-}
+// ============================================================
+// 单实例互斥(hardening ST-1)—— 零依赖,CLI / 启动脚本通用。
+// 锁文件 <configRoot>/.runtime/aw.lock 原子创建(wx):
+//   { pid, startedAt, mode, port }
+// 已存在且 PID 存活 → 视为已有实例(返回冲突信息,调用方以退出码 2 退出);
+// PID 已死(崩溃/强杀残留) → 自动接管重写。进程退出时 releaseLock 兜底清理。
+// ============================================================
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    // signal 0 探活:进程存在但不发信号;ESRCH=不存在,EPERM=存在(他人进程)
+    process.kill(pid, 0)
+    return true
+  }
+  catch (err) {
+    return err?.code === 'EPERM'
+  }
+}
+
+const waitSync = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+
+/**
+ * 终止进程树并等待其死亡(供 `aw stop` 与 start 的"顶掉旧实例"共用)。
+ * Windows:taskkill /T /F;POSIX:SIGTERM 宽限 5s → SIGKILL。
+ * @returns {Promise<boolean>} 是否已确认死亡
+ */
+export async function terminatePid(pid) {
+  if (!pidAlive(pid)) return true
+  if (process.platform === 'win32') {
+    const { spawnSync } = await import('node:child_process')
+    const r = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf8' })
+    if (r.status !== 0) return !pidAlive(pid)
+  }
+  else {
+    try {
+      process.kill(pid, 'SIGTERM')
+    }
+    catch { /* 已死 */ }
+    const deadline = Date.now() + 5000
+    while (Date.now() < deadline && pidAlive(pid)) waitSync(200)
+    if (pidAlive(pid)) {
+      try {
+        process.kill(pid, 'SIGKILL')
+      }
+      catch { /* 已死 */ }
+    }
+  }
+  const deadline = Date.now() + 5000
+  while (Date.now() < deadline && pidAlive(pid)) waitSync(200)
+  return !pidAlive(pid)
+}
+
+/**
+ * 尝试获取单实例锁。
+ * @returns {{ ok: true, lockPath: string, release: () => void }
+ *   | { ok: false, lockPath: string, holder: { pid: number, startedAt: string, mode: string, port: number | null } }}
+ */
+export function acquireLock(configRoot, { mode = 'prod', port = null } = {}) {
+  const runtimeDir = join(configRoot, '.runtime')
+  const lockPath = join(runtimeDir, 'aw.lock')
+  mkdirSync(runtimeDir, { recursive: true })
+  if (existsSync(lockPath)) {
+    let holder = null
+    try {
+      holder = JSON.parse(readFileSync(lockPath, 'utf8'))
+    }
+    catch { /* 损坏锁文件按残留处理 */ }
+    if (holder && pidAlive(holder.pid)) {
+      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
+    }
+    try {
+      rmSync(lockPath)
+    }
+    catch { /* 抢不掉则下方 wx 再失败 */ }
+  }
+  const me = { pid: process.pid, startedAt: new Date().toISOString(), mode, port }
+  try {
+    writeFileSync(lockPath, JSON.stringify(me, null, 2), { flag: 'wx' })
+  }
+  catch (err) {
+    // 与并发启动者竞态:按冲突处理
+    let holder = null
+    try {
+      holder = JSON.parse(readFileSync(lockPath, 'utf8'))
+    }
+    catch { /* ignore */ }
+    if (holder && pidAlive(holder.pid)) {
+      return { ok: false, lockPath, holder: { ...holder, port: holder.port ?? null } }
+    }
+    throw err
+  }
+  let released = false
+  const release = () => {
+    if (released) return
+    released = true
+    try {
+      const cur = JSON.parse(readFileSync(lockPath, 'utf8'))
+      if (cur?.pid !== process.pid) return // 锁已被他人接管,不误删
+      rmSync(lockPath)
+    }
+    catch { /* 已不存在/损坏,忽略 */ }
+  }
+  const releaseAndExit = (code) => {
+    release()
+    process.exit(code)
+  }
+  process.once('exit', release)
+  process.once('SIGINT', () => releaseAndExit(130))
+  process.once('SIGTERM', () => releaseAndExit(143))
+  return { ok: true, lockPath, release }
+}
+
+/** 端口占用探测:TCP try-listen 后立刻释放。EADDRINUSE → 端口号;其余 error code →
+ *  绑定状态未知(Windows 保留段 EACCES 等),按"未占用"放行但显式告警,不静默。 */
+export async function checkPort(host, port) {
+  const net = await import('node:net')
+  return new Promise((resolveProbe) => {
+    const srv = net.createServer()
+    srv.once('error', (err) => {
+      if (err?.code !== 'EADDRINUSE') {
+        console.warn(`[checkPort] 端口 ${port} 探测异常(${err?.code ?? err}),绑定状态未知,按未占用继续`)
+      }
+      resolveProbe(err?.code === 'EADDRINUSE' ? port : null)
+      srv.close()
+    })
+    srv.listen(port, host, () => {
+      srv.close(() => resolveProbe(null))
+    })
+  })
+}

package/shared/local-time.mjs

@@ -0,0 +1,36 @@
+/**
+ * 本地时间呈现(单点收口):全项目 ISO 时间输出统一为本地系统时区(如北京时间 +08:00)。
+ *
+ * 背景:Node `Date.toISOString()` 恒输出 UTC(`Z` 后缀)。本项目所有时间字段
+ * (日志 t / DB createdAt / WS 帧 at / Agent 记录)此前均为 UTC 字符串,用户要求
+ * 全部以本地系统时间呈现。
+ *
+ * 机制:installLocalIso() 把 Date.prototype.toISOString 改写为输出
+ * `YYYY-MM-DDTHH:mm:ss.sss±HH:MM`(本地偏移)。性质:
+ *  - 同一绝对时刻(仅表示形式变化),Date.parse/new Date(str) 完全兼容;
+ *  - 偏移后缀恒定(无 DST 时区如 +08:00),字符串字典序排序与时间序一致;
+ *  - 覆盖显式调用与 JSON.stringify(Date)(toJSON 默认走 toISOString)。
+ *  - 时区动态取自系统(getTimezoneOffset),跟随宿主,不硬编码。
+ *
+ * 幂等:重复安装跳过;原始实现保留在 __origToISOString 供诊断。
+ */
+export function installLocalIso() {
+  const proto = Date.prototype
+  if (proto.__origToISOString) return
+  const orig = proto.toISOString
+  proto.__origToISOString = orig
+  const pad = (n, w) => String(n).padStart(w, '0')
+  proto.toISOString = function () {
+    const t = this.getTime()
+    if (Number.isNaN(t)) throw new RangeError('Invalid time value')
+    // getTimezoneOffset:UTC 比本地慢的分钟数(UTC+8 → -480);取负得本地相对 UTC 偏移
+    const offMin = -this.getTimezoneOffset()
+    const sign = offMin >= 0 ? '+' : '-'
+    const abs = Math.abs(offMin)
+    // 平移后用 UTC getter 读出本地分量(整分偏移,毫秒不变)
+    const shifted = new Date(t + offMin * 60_000)
+    return `${pad(shifted.getUTCFullYear(), 4)}-${pad(shifted.getUTCMonth() + 1, 2)}-${pad(shifted.getUTCDate(), 2)}`
+      + `T${pad(shifted.getUTCHours(), 2)}:${pad(shifted.getUTCMinutes(), 2)}:${pad(shifted.getUTCSeconds(), 2)}`
+      + `.${pad(this.getMilliseconds(), 3)}${sign}${pad(Math.floor(abs / 60), 2)}:${pad(abs % 60, 2)}`
+  }
+}

package/shared/workshop-protocol.ts

@@ -118,20 +118,26 @@ export interface AepSceneLayout {
   rotationY: number
 }
 
-/** hitl.request payload:待人工处理条目(omp ask 对话框与 dcw 工具审批的统一视图) */
+/**
+ * hitl.request payload:待人工处理条目的统一视图。
+ * kind:omp 对话框(rpc-ui ask)/ dcw 工具审批 / codex 命令与文件审批 /
+ * opencode 权限与提问 / dsh 权限请求。
+ */
+export type AepHitlKind = 'omp-dialog' | 'dcw-approval' | 'codex-approval' | 'opencode-permission' | 'dsh-permission'
+
 export interface AepHitlItem {
-  kind: 'omp-dialog' | 'dcw-approval'
-  /** omp:对话框 id;dcw:审批 id(ap-*) */
+  kind: AepHitlKind
+  /** omp:对话框 id;dcw:审批 id(ap-*);其余:引擎请求 id(应答路由用) */
   id: string
   channelId: string
   agentId: string
   agentName: string
   /** omp 子进程 pid(应答路由 respondTerminalUi 用) */
   pid?: number
-  /** omp-dialog 专属:对话框形态 */
+  /** 对话框形态(codex requestUserInput/opencode question 为 input/select;权限类为 confirm) */
   method?: 'select' | 'confirm' | 'input' | 'editor'
   title: string
-  /** dcw-approval 专属:人读摘要(节点/物理量/目标值) */
+  /** dcw-approval 专属:人读摘要(节点/物理量/目标值);其余:命令/路径/权限详情 */
   detail?: string
   /** select 的选项列表 */
   options?: string[]

package/tui/aw-tui.mjs

@@ -9,7 +9,7 @@
 // 命令系统(/help)+ 监控面板(终端 WS)+ HITL 统一作答(/hitl)。
 // --headless:VirtualTerminal 驱动(无 TTY;scripts/tui-smoke.mjs 用)。
 // ============================================================
-import { TuiMainScreen, Editor, CombinedAutocompleteProvider, ProcessTerminal } from '@earendil-works/pi-tui'
+import { TuiMainScreen, Editor, CombinedAutocompleteProvider, ProcessTerminal, truncateToWidth } from '@earendil-works/pi-tui'
 import { theme } from './theme.mjs'
 import { loadAuth, saveAuth, configRoot } from './lib/config.mjs'
 import { createApi } from './lib/api.mjs'
@@ -221,10 +221,14 @@ export async function main(argv = process.argv.slice(2)) {
         }
       }
       else {
-        // dcw-approval:confirm 语义(y=批准/n=拒绝)+ 备注
+        // dcw-approval:显式 y/n。此前"非 y 开头一律落定为拒绝"对中文用户是逆向
+        // 陷阱(输入"同意/ok/批准"全部变成静默拒绝高危下发),必须重输。
         const norm = text.trim().toLowerCase()
+        if (!['y', 'n', 'yes', 'no'].includes(norm)) {
+          push('error', '下发审批请输入 y(批准)或 n(拒绝)')
+          return true
+        }
         body.confirmed = norm.startsWith('y')
-        if (norm.length > 1) body.comment = text
       }
       try {
         await api.hitlRespond(body)
@@ -234,7 +238,11 @@ export async function main(argv = process.argv.slice(2)) {
       }
       catch (err) {
         push('error', `应答失败:${err.message}`)
-        if (String(err.code) === 'ALREADY_RESOLVED') state.hitlAnswering = null
+        if (String(err.code) === 'ALREADY_RESOLVED') {
+          // 该待办已在别处(WebUI/另一端)解决:同步清除列表项,避免幽灵待办
+          state.hitl = state.hitl.filter(i => !(i.kind === item.kind && i.id === item.id))
+          state.hitlAnswering = null
+        }
       }
       store.notify()
       return true
@@ -262,21 +270,23 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const ctx = { state, store, api, echo, push, actions }
 
-  // ── 编辑器提交路由:HITL 作答 → 命令 → 普通文本按目标分流 ──
+  // ── 编辑器提交路由:命令 → HITL 作答 → 普通文本按目标分流 ──
   editor.onSubmit = async (text) => {
     const trimmed = text.trim()
     editor.setText('')
     editor.addToHistory?.(text)
     if (!trimmed) return
-    if (state.hitlAnswering) {
-      await actions.submitHitlAnswer(trimmed)
-      return
-    }
+    // 斜杠命令优先于作答分支:否则作答卡里输入 /hitl off(卡片提示的放弃方式)
+    // 会被当作答案文本提交给 Agent —— 与文档承诺行为相反。
     if (trimmed.startsWith('/')) {
       await dispatchCommand(ctx, trimmed)
       store.notify()
       return
     }
+    if (state.hitlAnswering) {
+      await actions.submitHitlAnswer(trimmed)
+      return
+    }
     if (!state.activeChannelId) {
       push('error', '未选择频道:Tab 或 /channel use 打开选择器')
       return
@@ -346,8 +356,16 @@ export async function main(argv = process.argv.slice(2)) {
 
   store.onChange(() => tui.requestRender())
 
+  // 兜底:未处理的 rejection 只记日志,不让 TUI 进程静默死亡(重连窗口内
+  // ws.send 之类的瞬态异常不应终止整个工作台)。
+  process.on('unhandledRejection', (err) => {
+    push('error', `未处理的异步错误:${err?.message ?? err}`)
+  })
+
   // ── 组装视图 ──
-  tui.addChild({ render: width => [...stack.render(width), '', ...editor.render(width)] })
+  // 出口统一按终端宽度夹断:pi-tui 对超宽行直接 stop()+throw(进程崩溃),
+  // 组合行(左栏+44 列监控右栏)在窄终端必然溢出,必须在进入渲染前截断。
+  tui.addChild({ render: width => [...stack.render(width), '', ...editor.render(width)].map(l => truncateToWidth(l, width)) })
   editor.setAutocompleteProvider?.(new CombinedAutocompleteProvider(slashCommandCompletions(), process.cwd()))
   tui.setFocus(editor)
 

package/tui/components/hitl-card.mjs

@@ -1,36 +1,47 @@
-// ============================================================
-// HitlCard —— 作答模式卡片(state.hitlAnswering 非空时渲染于输入框上方)。
-// 作答约定:confirm → y/n;select → 选项序号;input/editor → 自由文本;
-// /hitl off 放弃作答(等价 Esc)。提交经 POST /api/workshop/hitl/respond。
-// ============================================================
-import { theme } from '../theme.mjs'
-import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
-
-const HINT = {
-  confirm: '输入 y 批准 / n 拒绝',
-  select: '输入选项序号(如 1)',
-  input: '输入回答文本',
-  editor: '输入回答文本',
-}
-
-export class HitlCard {
-  constructor(state) {
-    this.state = state
-  }
-
-  render(width) {
-    const item = this.state.hitlAnswering
-    if (!item) return []
-    const w = Math.max(width - 4, 20)
-    const lines = []
-    lines.push(theme.warn(`⏸ HITL 作答 · ${item.agentName} · ${item.kind === 'omp-dialog' ? 'omp 对话框' : '下发审批'}`))
-    lines.push(truncateToWidth(theme.bold(String(item.title ?? '')), w))
-    if (item.detail) lines.push(...wrapTextWithAnsi(theme.faint(item.detail), w))
-    if (item.message) lines.push(...wrapTextWithAnsi(String(item.message), w))
-    if (item.method === 'select' && Array.isArray(item.options)) {
-      item.options.forEach((opt, i) => lines.push(`  ${theme.accent(`${i + 1}.`)} ${opt}`))
-    }
-    lines.push(theme.faint(`${HINT[item.method] ?? '输入回答'} · /hitl off 放弃`))
-    return lines.map(l => truncateToWidth(l, Math.max(width, 20)))
-  }
-}
+// ============================================================
+// HitlCard —— 作答模式卡片(state.hitlAnswering 非空时渲染于输入框上方)。
+// 作答约定:confirm → y/n;select → 选项序号;input/editor → 自由文本;
+// /hitl off 放弃作答(等价 Esc)。提交经 POST /api/workshop/hitl/respond。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const HINT = {
+  confirm: '输入 y 批准 / n 拒绝',
+  select: '输入选项序号(如 1)',
+  input: '输入回答文本',
+  editor: '输入回答文本',
+}
+
+const KIND_LABEL = {
+  'omp-dialog': 'omp 对话框',
+  'dcw-approval': '下发审批',
+  'codex-approval': 'codex 审批',
+  'opencode-permission': 'opencode 权限',
+  'dsh-permission': 'dsh 权限',
+}
+
+export class HitlCard {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const item = this.state.hitlAnswering
+    if (!item) return []
+    const w = Math.max(width - 4, 20)
+    const lines = []
+    lines.push(theme.warn(`⏸ HITL 作答 · ${item.agentName} · ${KIND_LABEL[item.kind] ?? '引擎待办'}`))
+    lines.push(truncateToWidth(theme.bold(String(item.title ?? '')), w))
+    if (item.detail) lines.push(...wrapTextWithAnsi(theme.faint(item.detail), w))
+    if (item.message) lines.push(...wrapTextWithAnsi(String(item.message), w))
+    if (item.method === 'select' && Array.isArray(item.options)) {
+      item.options.forEach((opt, i) => lines.push(`  ${theme.accent(`${i + 1}.`)} ${opt}`))
+    }
+    // 下发审批(dcw-approval)无 method 字段,必须显式告知 y/n 约定,
+    // 否则中文确认词会触发"非 y 即拒绝"的静默拒绝。
+    const hint = item.kind === 'omp-dialog' ? (HINT[item.method] ?? '输入回答') : '输入 y 批准 / n 拒绝'
+    lines.push(theme.faint(`${hint} · /hitl off 放弃`))
+    return lines.map(l => truncateToWidth(l, Math.max(width, 20)))
+  }
+}