agentworkshop 0.7.34 → 0.7.38

package/app/stores/workshop/events.ts

@@ -18,8 +18,8 @@ const HISTORY_EXCLUDE_TYPES = ['agent.delta']
 
 export type EventFilter = 'all' | 'messages' | 'tasks' | 'team' | 'errors' | 'key'
 
-/** 过滤器 → 允许的事件类型集合(key = 档位过滤:只看注意级+终局级,open-tag deliveryTier) */
-const FILTER_TYPES: Record<EventFilter, string[] | null> = {
+/** 过滤器 → 允许的事件类型集合(key = 档位过滤:只看注意级+终局级,open-tag deliveryTier)。导出供回归测试复用。 */
+export const FILTER_TYPES: Record<EventFilter, string[] | null> = {
   all: null,
   messages: ['agent.message', 'agent.delta', 'agent.status.message', 'a2a.message'],
   tasks: ['task.status', 'task.progress', 'a2a.artifact'],
@@ -28,36 +28,98 @@ const FILTER_TYPES: Record<EventFilter, string[] | null> = {
   key: null,
 }
 
-/** 时间线过滤纯函数(记忆化缓存的真实计算体) */
+/**
+ * 单帧是否命中时间线过滤 —— **唯一事实源**。
+ * 全量重算(computeTimeline)与增量追加(timeline getter)必须共用本函数,
+ * 否则两条路径的语义会悄悄分叉(表现为"刷新后少了/多了几条")。
+ *
+ * 导出供回归测试使用:测试要验证的是「增量维护 ⊆ 与全量重算等价」,
+ * 参照实现必须调用同一个谓词,否则测的是参照写得对不对,而不是实现是否等价。
+ *
+ * 注意 `filter === 'key'` 是**提前返回**:该档位只看注意级/终局级,
+ * 刻意不受 focus 影响(聚焦是"看某人的流",key 是"只看需要我介入的",两者正交)。
+ */
+export function matchesTimeline(
+  e: AepEnvelope,
+  filter: EventFilter,
+  allow: string[] | null,
+  focus: string | null,
+): boolean {
+  if (e.type === 'channel.snapshot') return false
+  // key 过滤:只看注意级 + 终局级(open-tag deliveryTier —— agent 噪声让路)
+  if (filter === 'key') {
+    const t = envelopeTier(e)
+    return t === 'attention' || t === 'terminal'
+  }
+  if (allow && !allow.includes(e.type)) return false
+  if (focus && e.type !== 'task.status' && e.type !== 'task.progress') {
+    if (e.agentId === focus) return true
+    // 消息归属发送方,但发给聚焦 Agent 的消息(a2a.message target)仍属其流
+    if (e.type === 'a2a.message') {
+      const target = (e.payload as { metadata?: { 'x-aw-target-agent'?: string } }).metadata?.['x-aw-target-agent']
+      return target === focus
+    }
+    return false
+  }
+  return true
+}
+
+/** 时间线过滤纯函数(全量重算路径;增量路径见 matchesTimeline) */
 function computeTimeline(
   items: AepEnvelope[],
   filter: EventFilter,
   allow: string[] | null,
   focus: string | null,
 ): AepEnvelope[] {
-  return items.filter((e) => {
-    if (e.type === 'channel.snapshot') return false
-    // key 过滤:只看注意级 + 终局级(open-tag deliveryTier —— agent 噪声让路)
-    if (filter === 'key') {
-      const t = envelopeTier(e)
-      return t === 'attention' || t === 'terminal'
-    }
-    if (allow && !allow.includes(e.type)) return false
-    if (focus && e.type !== 'task.status' && e.type !== 'task.progress') {
-      if (e.agentId === focus) return true
-      // 消息归属发送方,但发给聚焦 Agent 的消息(a2a.message target)仍属其流
-      if (e.type === 'a2a.message') {
-        const target = (e.payload as { metadata?: { 'x-aw-target-agent'?: string } }).metadata?.['x-aw-target-agent']
-        return target === focus
-      }
-      return false
-    }
-    return true
-  })
+  return items.filter(e => matchesTimeline(e, filter, allow, focus))
 }
 
-/** per-channel 时间线记忆化(key 含 lastSeq/条数/过滤态;原 getter 每访问全量过滤 5000 帧) */
-const timelineCache = new Map<string, { key: string, result: AepEnvelope[] }>()
+interface ChannelRing {
+  lastSeq: number
+  items: AepEnvelope[]
+  /**
+   * 已消费过的全部 seq(含被 delta 合并吃掉的中间 seq)——loadHistory 的
+   * 去重依据:按 item.seq 精确匹配会漏掉合并帧,导致同段 delta 重复插入。
+   */
+  consumed: Set<number>
+}
+
+/** 稳定空数组:让"无数据"返回同一引用,避免下游 computed 每帧产出新数组触发重渲染 */
+const EMPTY_ITEMS: AepEnvelope[] = Object.freeze([]) as unknown as AepEnvelope[]
+
+/**
+ * 时间线增量缓存。
+ *
+ * 为什么不再用「key 含 lastSeq 的全量记忆化」:lastSeq 每帧递增 → 每帧必然 miss →
+ * 每帧对整条 ring(≤5000)全量过滤一次。改为增量:filter/focus 未变时只并入**新增尾巴**,
+ * 已淘汰的头部条目从结果前部摘除。
+ *
+ * ⚠️ 游标必须用 **seq** 而不是数组下标。ring 满之后是「push 一条 + 头部淘汰一条」,
+ * `items.length` 恒等于 RING_CAP 不变,而所有元素整体左移一位 ——
+ * 用下标做游标的实现会认为"没有新元素",**静默漏掉每一个新帧**
+ * (本仓库的等价性测试正是先在 messages+a1 上抓到这个 off-by-one 才改成 seq 的)。
+ */
+interface TimelineMemo {
+  filter: EventFilter
+  focus: string | null
+  /** 已并入结果的最大 seq;ring 被重建(快照)时回退为 -1 */
+  lastSeq: number
+  result: AepEnvelope[]
+}
+
+const timelineCache = new Map<string, TimelineMemo>()
+
+/** 在按 seq 升序的数组里找第一个 seq > 目标值 的下标(二分,O(log n)) */
+function firstIndexAfterSeq(items: AepEnvelope[], seq: number): number {
+  let lo = 0
+  let hi = items.length
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1
+    if ((items[mid]?.seq ?? 0) > seq) hi = mid
+    else lo = mid + 1
+  }
+  return lo
+}
 
 interface ChannelRing {
   lastSeq: number
@@ -67,9 +129,45 @@ interface ChannelRing {
    * 去重依据:按 item.seq 精确匹配会漏掉合并帧,导致同段 delta 重复插入。
    */
   consumed: Set<number>
+  /**
+   * agentId → 该 agent 的事件子序列(与 items 同生命周期,增量维护)。
+   *
+   * 为什么需要:lane 视图对**每个成员**各跑一遍 `items.filter(e => e.agentId === id)`,
+   * 即每帧 O(L×R) 次谓词调用并分配 L 个新数组(L=成员数、R=ring 长度≤5000)。
+   * 取 L=8、R=2000、30 帧/s ≈ 4.8×10⁵ 次谓词/秒,且随会话时长线性劣化(越看越卡)。
+   * 有了索引,lane 每帧只读一个已备好的数组 → O(1)。
+   * 桶内元素与 items 中**同一个对象引用**(delta 合并是原地改 payload,索引自动可见)。
+   */
+  byAgent: Map<string, AepEnvelope[]>
+}
+
+const EMPTY_RING = (): ChannelRing => ({ lastSeq: 0, items: [], consumed: new Set(), byAgent: new Map() })
+
+/** 尾部追加建档(与 items.push 配对) */
+function indexAppend(ring: ChannelRing, e: AepEnvelope): void {
+  const key = e.agentId
+  if (!key) return
+  const bucket = ring.byAgent.get(key)
+  if (bucket) bucket.push(e)
+  else ring.byAgent.set(key, [e])
+}
+
+/** 头部淘汰出档(与 items.splice(0, n) 配对);按引用查找,防同 seq 重放误删 */
+function indexEvict(ring: ChannelRing, dropped: AepEnvelope[]): void {
+  for (const e of dropped) {
+    const bucket = ring.byAgent.get(e.agentId ?? '')
+    if (!bucket) continue
+    const idx = bucket.indexOf(e)
+    if (idx >= 0) bucket.splice(idx, 1)
+    if (bucket.length === 0) ring.byAgent.delete(e.agentId ?? '')
+  }
 }
 
-const EMPTY_RING = (): ChannelRing => ({ lastSeq: 0, items: [], consumed: new Set() })
+/** 全量重建索引(排序/批量合并后调用;这类路径每次频道/成员只走一次,成本可接受) */
+function reindex(ring: ChannelRing): void {
+  ring.byAgent.clear()
+  for (const e of ring.items) indexAppend(ring, e)
+}
 
 /** 历史接口响应壳(全局/lane 同构) */
 interface EventsHistoryRes {
@@ -92,7 +190,10 @@ function mergeHistory(ring: ChannelRing, items: AepEnvelope[], ceiling: number):
   }
   if (added > 0) {
     ring.items.sort((a, b) => a.seq - b.seq)
-    if (ring.items.length > RING_CAP) ring.items.splice(0, ring.items.length - RING_CAP)
+    const overflow = ring.items.length - RING_CAP
+    if (overflow > 0) ring.items.splice(0, overflow)
+    // 排序打乱了插入序 → 索引必须整体重建(批量历史路径,非热路径)
+    reindex(ring)
   }
   return added
 }
@@ -111,19 +212,64 @@ export const useEventsStore = defineStore('workshop.events', {
       return (channelId: string): ChannelRing =>
         state.rings[channelId] ?? EMPTY_RING()
     },
-    /** 应用过滤 + agent 聚焦后的时间线(虚拟滚动/自动吸底消费;per-channel 记忆化) */
+    /** 应用过滤 + agent 聚焦后的时间线(虚拟滚动/自动吸底消费;per-channel 增量缓存) */
     timeline(state) {
       return (channelId: string): AepEnvelope[] => {
         const ring = state.rings[channelId]
-        if (!ring) return []
+        if (!ring) return EMPTY_ITEMS
         const filter = state.filters[channelId] ?? 'all'
         const focus = state.focusAgents[channelId] ?? null
-        const memoKey = `${filter}:${focus ?? ''}:${ring.lastSeq}:${ring.items.length}`
-        const hit = timelineCache.get(channelId)
-        if (hit && hit.key === memoKey) return hit.result
-        const result = computeTimeline(ring.items, filter, FILTER_TYPES[filter], focus)
-        timelineCache.set(channelId, { key: memoKey, result })
-        return result
+        const items = ring.items
+        const allow = FILTER_TYPES[filter]
+        const maxSeq = items.length > 0 ? (items[items.length - 1]?.seq ?? 0) : -1
+        const prev = timelineCache.get(channelId)
+
+        // 需要全量重算的三种情况:
+        //  ① 首次 / 过滤态变化 —— 增量无从谈起
+        //  ② ring 被重建(channel.snapshot):maxSeq 反而变小(甚至为空)
+        //  ③ 缓存里的游标超过当前最大 seq(同上,防御性)
+        const needRebuild = !prev
+          || prev.filter !== filter
+          || prev.focus !== focus
+          || (items.length === 0 && prev.result.length > 0)
+          || prev.lastSeq > maxSeq
+        if (needRebuild) {
+          const result = computeTimeline(items, filter, allow, focus)
+          timelineCache.set(channelId, { filter, focus, lastSeq: maxSeq, result })
+          return result
+        }
+
+        // 摘除已淘汰的头部条目(结果与 items 同按 seq 升序 → 只可能从前往后连续失效)
+        const headSeq = items[0]?.seq ?? 0
+        const res = prev.result
+        if (res.length > 0 && (res[0]?.seq ?? 0) < headSeq) {
+          let drop = 0
+          while (drop < res.length && (res[drop]?.seq ?? 0) < headSeq) drop++
+          res.splice(0, drop)
+        }
+
+        // 并入新增尾巴:按 seq 定位起点(不能用下标 —— 见 TimelineMemo 的说明)
+        if (maxSeq > prev.lastSeq) {
+          const from = firstIndexAfterSeq(items, prev.lastSeq)
+          for (let i = from; i < items.length; i++) {
+            const e = items[i]!
+            if (matchesTimeline(e, filter, allow, focus)) res.push(e)
+          }
+          prev.lastSeq = maxSeq
+        }
+        return res
+      }
+    },
+    /**
+     * 某 agent 的事件子序列(增量索引,O(1) 取用)。
+     * lane 视图用它替代 `items.filter(e => e.agentId === id)` —— 后者每帧对每个成员
+     * 各扫一遍整条 ring(见 ChannelRing.byAgent 的说明)。
+     * 无数据时返回**同一个冻结空数组**,避免下游 computed 每帧产出新引用而触发重渲染。
+     */
+    agentEvents(state) {
+      return (channelId: string, agentId: string): AepEnvelope[] => {
+        if (!agentId) return EMPTY_ITEMS
+        return state.rings[channelId]?.byAgent.get(agentId) ?? EMPTY_ITEMS
       }
     },
     lastSeq(state) {
@@ -137,7 +283,7 @@ export const useEventsStore = defineStore('workshop.events', {
       const ring = this.rings[e.channelId] ?? EMPTY_RING()
       if (e.type === 'channel.snapshot') {
         // 全量对齐:清空 ring,游标对齐快照 seq
-        this.rings[e.channelId] = { lastSeq: e.seq, items: [], consumed: new Set([e.seq]) }
+        this.rings[e.channelId] = { lastSeq: e.seq, items: [], consumed: new Set([e.seq]), byAgent: new Map() }
         return
       }
       if (typeof e.seq === 'number' && e.seq > ring.lastSeq) {
@@ -158,7 +304,11 @@ export const useEventsStore = defineStore('workshop.events', {
           }
         }
         ring.items.push(e)
-        if (ring.items.length > RING_CAP) ring.items.splice(0, ring.items.length - RING_CAP)
+        indexAppend(ring, e)
+        if (ring.items.length > RING_CAP) {
+          // 淘汰与索引清理必须同拍,否则索引会持有已出窗条目(查询命中"已看不见"的事件)
+          indexEvict(ring, ring.items.splice(0, ring.items.length - RING_CAP))
+        }
         ring.lastSeq = e.seq
         // 防泄漏:超限后从现存 items 重建(合并掉的旧 seq 允许短暂失忆——远早于 ring 窗口)
         if (ring.consumed.size > 20_000) ring.consumed = new Set(ring.items.map(i => i.seq))

package/bin/aw.mjs

@@ -3,11 +3,16 @@
 // AgentWorkShop CLI — npm bin 入口
 // `npm i -g agentworkshop` 后，终端里 `aw` / `agentworkshop` 即指向本文件。
 // ============================================================
+// 必须 process.exit(code) 而不是 process.exitCode = await main():
+// stdout/stderr 是管道(重定向 / CI / 父进程 spawn 捕获)时,句柄会保活事件循环,
+// Node 在顶层 await 下会以 **退出码 13**(ERR_UNSETTLED_TOP_LEVEL_AWAIT)收场,
+// 把 `aw --help` 这类纯诊断指令的成功退出写成 13 且输出为空。
+// process.exit 会同步 flush 已排队的 stdio 写入(writev 直写 fd)。
 try {
   const { main } = await import('../cli/aw.mjs')
-  process.exitCode = await main()
+  process.exit(await main())
 }
 catch (err) {
   console.error('[aw] 启动失败:', err)
-  process.exitCode = 1
+  process.exit(1)
 }

package/cli/aw.mjs

@@ -9,16 +9,17 @@
 //   4. 组装运行上下文 ctx（含有效配置 API）并执行指令
 //   5. 统一错误处理与退出码（0 成功 / 1 错误 / 2 用法错误）
 // ============================================================
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import { join, resolve, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { CommandRegistry, commandDirs } from './core/registry.mjs'
 import { createContext, EXIT } from './core/context.mjs'
-import { parseArgs, stripGlobals } from './core/args.mjs'
+import { parseArgs, stripGlobals, extractCommandName, globalNames, globalValueNames } from './core/args.mjs'
 import { renderHelp, renderCommandHelp } from './core/help.mjs'
 import { logger, color } from './core/logger.mjs'
 import { CliError, isUsageError } from './core/errors.mjs'
+import { packageRoot, packageVersion } from './core/meta.mjs'
+import { awHome } from '../shared/config/home.mjs'
 import { installLocalIso } from '../shared/local-time.mjs'
 
 // 全 CLI 时间输出统一本地时区(先于任何命令逻辑)
@@ -26,22 +27,11 @@ installLocalIso()
 
 export { CliError }
 
-/** 本包版本（cli/aw.mjs → ../package.json） */
-export function packageVersion() {
-  try {
-    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0'
-  }
-  catch {
-    return '0.0.0'
-  }
-}
-
-/** 本包根目录（全局安装副本同样成立;必须走 fileURLToPath,Windows 下
- *  URL pathname 是 '/D:/...' 形态,直接 path.resolve 会得到 'D:\D:\...' 垃圾路径,
- *  导致内建指令目录扫描全部静默失败 —— 指令注册失效的根因） */
-export function packageRoot() {
-  return resolve(dirname(fileURLToPath(import.meta.url)), '..')
-}
+/** 本包版本/包根:实现下沉到叶子模块 cli/core/meta.mjs。
+ *  命令模块要复用它们,若继续定义在本文件会让 cli/commands/* → ../aw.mjs 形成
+ *  循环依赖,并在 **cli/aw.mjs 自任入口**时死锁(顶层 await main() 等 scanDirs,
+ *  scanDirs 等命令模块,命令模块等 aw.mjs 求值完成)→ 退出码 13 且无输出。 */
+export { packageRoot, packageVersion } from './core/meta.mjs'
 
 /** 向上查找文件（与 shared/config/engine.mjs 的 findUp 等价,避免顶层依赖引擎） */
 function findUp(startDir, filename) {
@@ -55,19 +45,10 @@ function findUp(startDir, filename) {
   }
 }
 
-/** 从命令行提取指令名（首个非选项 token） */
+/** 从命令行提取指令名（首个位置 token;跳过全局选项及其取值）
+ *  实现在 args.mjs —— 与 stripGlobals 共用同一张取值边界表,避免两处各自猜。 */
 function extractCommand(argv) {
-  let afterDash = false
-  for (const tok of argv) {
-    if (afterDash) return tok
-    if (tok === '--') {
-      afterDash = true
-      continue
-    }
-    if (tok.startsWith('-')) continue
-    return tok
-  }
-  return null
+  return extractCommandName(argv)
 }
 
 function toBool(v, fallback = false) {
@@ -97,7 +78,9 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
         return p ? dirname(p) : null
       })()
 
-  const homeDir = homedir()
+  // 用户级指令目录必须与 `aw register --global` / createContext 用同一个 AW Home 解析
+  // (awHome 认 $AW_HOME);用 OS 家目录会在 AW_HOME 生效时扫到错误的目录。
+  const homeDir = awHome(process.env)
   const pkgRoot = packageRoot()
 
   // 指令注册：内建(本包 cli/commands) → 用户级 → 项目级(同名单后者覆盖)
@@ -157,9 +140,11 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
   // 按字面量剔除,会把出现在「值」位置的同名 token 一并删掉:
   //   aw foo --name --json      → --json 是 --name 的值,却被删 → --name 变布尔 true(值丢失)
   //   aw foo --title=b --json   → 同理
-  // 传入 predicate 后由 parseArgs 在消费该 flag 时决定 skip 范围。
+  // 取值边界由 GLOBAL_OPTS 声明(--root 带值,--json/--debug 为布尔):
+  //   aw build --json x         → x 是位置参数,不得被 --json 吞掉
+  //   aw --root /p build        → --root 连 /p 一起剥离
   const idx = argv.indexOf(commandName)
-  const cmdArgv = stripGlobals(argv.slice(idx >= 0 ? idx + 1 : 0), ['--json', '--debug'])
+  const cmdArgv = stripGlobals(argv.slice(idx >= 0 ? idx + 1 : 0), globalNames(), { valueNames: globalValueNames() })
   const local = parseArgs(cmdArgv, { shortMap: { h: 'help', ...(cmd.meta.short ?? {}) } })
 
   if (local.flags.help) {

package/cli/commands/build.mjs

@@ -4,6 +4,7 @@
 import { color } from '../core/logger.mjs'
 import { localBypassEnv } from '../core/context.mjs'
 import { runChild } from '../core/child-lifecycle.mjs'
+import { postBuildArtifacts } from '../core/post-build.mjs'
 
 export const meta = {
   name: 'build',
@@ -24,10 +25,26 @@ export async function run(argv, ctx) {
   console.log(`${color.cyan('›')} 构建生产产物 .output/ ...`)
   // 统一生命周期:转发 SIGINT/SIGTERM(子进程不再变孤儿) + 等待退出 + 超时强杀
   // + 退出码传播(被信号杀死 → 128+N,不再 code ?? 0 误报成功)
-  return await runChild(process.execPath, [nuxtBin, 'build'], {
+  const code = await runChild(process.execPath, [nuxtBin, 'build'], {
     cwd: root,
     stdio: 'inherit',
     env: localBypassEnv(),
     onSpawnError: err => console.log(`${color.red('✖')} 构建失败: ${err.message}`),
   })
+  if (code !== 0) return code
+
+  // 构建产物后处理:import-meta 补丁 + 外置资产分发。
+  // 不能只靠 nuxt.config 的 compiled 钩子 —— 它与 chunk 落盘有竞态,静默失效会让
+  // 产物启动即抛 ERR_INVALID_FILE_URL_PATH。这里在构建**返回后**重做并校验。
+  try {
+    const r = postBuildArtifacts(root)
+    if (r.patched.length > 0) console.log(`${color.cyan('›')} import-meta 补丁:${r.patched.join(', ')}`)
+    if (r.assets.length > 0) console.log(`${color.cyan('›')} 外置资产随产物分发:${r.assets.join(', ')}`)
+    if (r.missing.length > 0) console.log(`${color.yellow('!')} 未生成(跳过):${r.missing.join(', ')}`)
+  }
+  catch (err) {
+    console.log(`${color.red('✖')} ${err?.message ?? err}`)
+    return 1
+  }
+  return 0
 }

package/cli/commands/config.mjs

@@ -20,6 +20,8 @@ export const meta = {
   group: '配置',
   summary: '读取 / 写入 / 校验运行配置',
   usage: 'aw config [list|get|set|unset|reset|validate] [key] [value] [--json]',
+  // reset 的确认短选项:未登记时 `-y` 会被静默丢弃,reset 变成无确认的破坏性操作
+  short: { y: 'yes' },
   description: [
     '以 config.yml 为默认、runtime-settings.json 为运行时覆盖、环境变量为最高优先级。',
     '双模式:项目检出内写 <项目>/data/runtime-settings.json;全局安装(任意目录)写 ~/.AgentWorkShop/runtime-settings.json。',

package/cli/commands/plugin.mjs

@@ -1,27 +1,39 @@
 // ============================================================
-// 指令:plugin — 插件管理(list / create 脚手架)
+// 指令:plugin — 插件管理(list / create / enable / disable)
 // ------------------------------------------------------------
-// 插件目录(与配置根一致):
-//   project: <repo>/.AgentWorkShop/plugins/<name>/
-//   user:    ~/.AgentWorkShop/plugins/<name>/
+// 插件目录(三作用域,与宿主 host.mjs discoverPluginDirs 一致):
+//   builtin: <packageRoot>/server/plugins-builtin/<name>/   ← 随包发布,永远存在
+//   project: <repo>/.AgentWorkShop/plugins/<name>/          ← aw plugin create 默认落点
+//   user:    ~/.AgentWorkShop/plugins/<name>/               ← aw plugin create --global
+//   ⚠️ 同名优先级 builtin > project > user(宿主先扫先占),与 scopes() 的返回顺序一致。
 // 插件契约:入口 index.mjs 导出 { name, version?, description?,
 //   setup(ctx)?, client?: './client.mjs', routes?: [...] } —— 零导入依赖。
 // ============================================================
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { color } from '../core/logger.mjs'
 import { CliError } from '../core/errors.mjs'
 
+/** 本文件位于 <packageRoot>/cli/commands/,故包根 = 上两级 */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
+
 export const meta = {
   name: 'plugin',
   aliases: ['plugins', 'plug'],
   group: '扩展',
   summary: '插件管理:查看/启停(热重载)/脚手架',
-  usage: 'aw plugin <list|create|enable|disable> [name] [--project|--global] [--force]',
+  usage: 'aw plugin <list|create|enable|disable> [name] [--global|-g] [--project] [--force|-f]',
+  // 短选项必须在这里登记:cli/aw.mjs 只把 meta.short 声明过的短名映射成长名,
+  // 未登记的 `-g` 会被 args.mjs 丢进 unknown 且**不报错** —— 插件会静默落到 project 级。
+  short: { g: 'global', f: 'force' },
   description: [
-    '插件 = 配置根 plugins/<name>/ 下的 node 项目:入口 index.mjs 导出',
-    '{ name, setup(ctx) } 即自动装载(服务端钩子/API 路由),client.mjs 可选(浏览器增强)。',
-    '服务端钩子:daq:sample / dcw:write / line:start|stop / event:*(scene 全事件)/ server:close。',
+    '插件 = plugins/<name>/ 下的自包含目录:入口 index.mjs 导出 { name, setup(ctx) }',
+    '即自动装载(服务端钩子/API 路由/Agent 工具/数采扩展),client.mjs 可选(浏览器增强)。',
+    '作用域:builtin(随包) > project(仓库 .AgentWorkShop/plugins) > user(~/.AgentWorkShop/plugins)。',
+    'create 默认落 project 级,--global/-g 落 user 级。',
+    '服务端钩子:daq:sample / daq:frame / dcw:write / line:start|stop / config:changed /',
+    'plugins:reloaded / event:*(scene 全事件) / server:close —— 通配写法是 \'*\'(裸星号)。',
   ],
   needsProject: false,
 }
@@ -70,7 +82,11 @@ export default {
 `
 
 const CLIENT_TEMPLATE = name => `// ${name} — 客户端增强(可选;自包含 ESM,无裸导入)
-// ctx: on(type,fn) 事件订阅 / el() DOM 助手 / root() 私有挂载点 / log
+// ctx: on(type,fn) scene 事件订阅 / el() DOM 助手 / root() 私有挂载点 / log
+// ⚠️ ctx.on 只装 **scene 事件**(type 传事件名本身,如 'daq.reading' / 'daq.alarm';
+//    收全部用字面量 'event:*')。服务端钩子(daq:sample / dcw:write / line:start…)
+//    不会过桥到浏览器;浏览器侧生命周期钩子(client:init / page:change / i18n:changed)
+//    要走 ctx.hooks.on(...)。
 export function setup(ctx) {
   const badge = ctx.el('div', {
     style: 'padding:6px 10px;border:1px solid #2de0a0;border-radius:8px;color:#2de0a0;background:rgba(0,0,0,.55)',
@@ -78,7 +94,7 @@ export function setup(ctx) {
   ctx.root().append(badge)
 
   let n = 0
-  ctx.on('daq:sample', () => {
+  ctx.on('daq.reading', () => {
     n++
     badge.textContent = \`\${ctx.name} · \${n} 样本\`
   })
@@ -89,11 +105,17 @@ export function setup(ctx) {
 
 const PLUGIN_README = name => `# ${name}
 
-AgentWorkShop 插件。重启 \`aw start\` / \`aw dev\` 自动装载。
+AgentWorkShop 插件。
 
 - \`index.mjs\` — 服务端入口(setup(ctx))
 - \`client.mjs\` — 浏览器增强(可选)
 - API:GET /api/plugins/${name}/stats
+
+装载无需重启:运行中的服务监听 <home>/plugins-state.json(fs.watch + 10s 轮询兜底),
+启用/停用会在 ~1s 内热重载。**改插件源码不会自动触发重载** —— 重载时宿主会用带
+时间戳的 dynamic import 破缓存重新加载模块,所以改完代码触碰一下 plugins-state.json
+(或 Web 端切一次开关)即生效,不必重启进程。
+完整契约见 docs/plugins.md。
 `
 
 export async function run(argv, ctx) {
@@ -157,15 +179,18 @@ function findPluginDir(ctx, name) {
 }
 
 function scopes(ctx) {
+  // 顺序 = 宿主 host.mjs 的发现顺序(builtin → project → user);
+  // findPluginDir 取首个命中,故顺序必须与宿主同名优先级一致,否则启停会打到另一个同名插件上。
   return [
-    { scope: 'project', dir: ctx.root ? join(ctx.root, '.AgentWorkShop', 'plugins') : null, label: '内置示例' },
-    { scope: 'user', dir: ctx.commandsDir?.global ? join(ctx.home, 'plugins') : join(ctx.home, 'plugins'), label: '用户级扩展' },
+    { scope: 'builtin', dir: join(PACKAGE_ROOT, 'server', 'plugins-builtin'), label: '内置插件(随包发布)' },
+    { scope: 'project', dir: ctx.root ? join(ctx.root, '.AgentWorkShop', 'plugins') : null, label: '项目级(仓库 .AgentWorkShop/plugins)' },
+    { scope: 'user', dir: join(ctx.home, 'plugins'), label: '用户级(~/.AgentWorkShop/plugins)' },
   ]
 }
 
 function list(ctx) {
   console.log('')
-  console.log(`${color.bold('AgentWorkShop 插件')}  ${color.dim('— 配置根 plugins/ 目录,自动装载;aw plugin enable/disable 启停')}`)
+  console.log(`${color.bold('AgentWorkShop 插件')}  ${color.dim('— 三作用域自动装载;aw plugin enable/disable 启停(热重载)')}`)
   let total = 0
   const disabled = readState(ctx)
   for (const { dir, label } of scopes(ctx)) {
@@ -196,8 +221,9 @@ function list(ctx) {
 
 function create(ctx, name, flags) {
   if (!name || !/^[a-z][a-z0-9-]{1,31}$/.test(name)) {
-    throw new CliError('USAGE', '用法: aw plugin create <name> [--project|--global](name: 小写字母开头,2-32 位 a-z0-9-)')
+    throw new CliError('USAGE', '用法: aw plugin create <name> [--global|-g] [--project] [--force|-f](name: 小写字母开头,2-32 位 a-z0-9-)')
   }
+  // 默认落 project 级;--global/-g 落 user 级。--project 是显式写法(与默认等价,保留以符合直觉)。
   const global = Boolean(flags.global ?? flags.g)
   const force = Boolean(flags.force ?? flags.f)
   const target = global
@@ -213,7 +239,8 @@ function create(ctx, name, flags) {
   writeFileSync(join(target, 'README.md'), PLUGIN_README(name), 'utf8')
 
   console.log(`${color.green('✔')} 插件已创建: ${color.bold(name)} → ${target}`)
-  console.log(`  › 重启服务自动装载;API 示例: ${color.cyan(`GET /api/plugins/${name}/stats`)}`)
-  console.log(`  › 查看列表: ${color.cyan('aw plugin list')}`)
+  console.log(`  › 作用域: ${global ? 'user(用户级,~/.AgentWorkShop/plugins)' : 'project(项目级,<repo>/.AgentWorkShop/plugins)'}`)
+  console.log(`  › 装载: 运行中的服务在 plugins-state.json 变化后 ~1s 内热重载;改代码后触碰该文件即生效(无需重启进程)`)
+  console.log(`  › 查看列表: ${color.cyan('aw plugin list')}    API 示例: ${color.cyan(`GET /api/plugins/${name}/stats`)}`)
   return 0
 }

package/cli/commands/register.mjs

@@ -13,14 +13,18 @@
 import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
 import { join, basename, resolve } from 'node:path'
 import { color } from '../core/logger.mjs'
-import { CliError } from '../aw.mjs'
+// 从叶子模块取 CliError(而非 '../aw.mjs'):命令模块反向依赖入口会形成循环依赖,
+// 在 cli/aw.mjs 自任入口时死锁(详见 cli/core/meta.mjs 文件头说明)
+import { CliError } from '../core/errors.mjs'
 
 export const meta = {
   name: 'register',
   aliases: ['reg', 'install-cmd'],
   group: '指令',
   summary: '注册一条新指令（项目级或用户级）',
-  usage: 'aw register <path|url|npm:pkg> [--name <n>] [--global|-g] [--force]',
+  usage: 'aw register <path|url|npm:pkg> [--name <n>] [--global|-g] [--force|-f]',
+  // 短选项需显式登记(cli/aw.mjs 只认 meta.short);否则 `-g` 被静默丢弃 → 注册到错误的层级
+  short: { g: 'global', f: 'force' },
   description: [
     '指令文件只需导出 { meta, run }：',
     '  export const meta = { name, summary, usage, group, aliases?, needsProject? }',

package/cli/commands/status.mjs

@@ -5,6 +5,7 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { color } from '../core/logger.mjs'
 import { findRunningServer } from '../core/context.mjs'
+import { packageVersion } from '../core/meta.mjs'
 
 export const meta = {
   name: 'status',
@@ -38,7 +39,7 @@ export async function run(argv, ctx) {
       mode: ctx.mode,
       root: ctx.root,
       home: ctx.home,
-      package: { version: (await import('../aw.mjs')).packageVersion() },
+      package: { version: packageVersion() },
       config: { path: ctx.configPath, effective, sources, runtimeOverrides },
       server: server ? { running: true, port: server.port } : { running: false },
       build: { outputExists: ctx.root ? existsSync(join(ctx.root, '.output', 'server', 'index.mjs')) : existsSync(join(ctx.packageRoot, '.output', 'server', 'index.mjs')) },

package/cli/commands/update.mjs

@@ -12,7 +12,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { color } from '../core/logger.mjs'
 import { CliError } from '../core/errors.mjs'
-import { packageVersion } from '../aw.mjs'
+import { packageVersion } from '../core/meta.mjs'
 
 export const meta = {
   name: 'update',

package/cli/commands/version.mjs

@@ -2,7 +2,7 @@
 // 指令:version — 版本信息
 // ============================================================
 import { color } from '../core/logger.mjs'
-import { packageVersion } from '../aw.mjs'
+import { packageVersion } from '../core/meta.mjs'
 
 export const meta = {
   name: 'version',