agentworkshop 0.5.3 → 0.5.5

package/server/data/dcw-runs.json

@@ -1,22 +1,4 @@
 [
-  {
-    "id": "rr-57bca111",
-    "recipeId": "rc-ee30a7a0",
-    "recipeName": "终审配方A",
-    "productId": "pd-99159b45",
-    "lineId": "ln-c6713e4d",
-    "startedAt": "2026-08-29T15:13:03.707Z",
-    "endedAt": "2026-08-29T15:14:14.609Z",
-    "results": [
-      {
-        "templateRef": "dcw-temp-sp",
-        "nodeId": "dw-c4da380a",
-        "ok": true,
-        "message": "写入并回读一致:182 → raw 1280,回读 182(标定后物理值 182)",
-        "value": 182
-      }
-    ]
-  },
   {
     "id": "rr-c8ccb1f5",
     "recipeId": "rc-3b094c50",
@@ -4731,5 +4713,32 @@
         "max": 188
       }
     ]
+  },
+  {
+    "id": "rr-09acb43b",
+    "recipeId": "rc-4d460065",
+    "recipeName": "全功能配方-41bdm2",
+    "productId": "pd-33f3607e",
+    "lineId": "ln-69eaecb9",
+    "startedAt": "2026-09-02T10:37:44.029Z",
+    "endedAt": "2026-09-02T10:43:20.233Z",
+    "results": [
+      {
+        "templateRef": "dcw-temp-sp",
+        "nodeId": "dw-eeedb292",
+        "ok": true,
+        "message": "Mock PLC 写入成功:180 → raw 180,回读一致(标定后物理值 180)",
+        "value": 180
+      }
+    ],
+    "paramsSnapshot": [
+      {
+        "nodeId": "dw-eeedb292",
+        "templateRef": "dcw-temp-sp",
+        "value": 180,
+        "min": 176,
+        "max": 188
+      }
+    ]
   }
 ]

package/server/data/dcw-writes.json

@@ -9862,5 +9862,53 @@
     "message": "Mock PLC 写入成功:182 → raw 182,回读一致(标定后物理值 182)",
     "recipeRunId": null,
     "at": "2026-09-02T08:46:51.079Z"
+  },
+  {
+    "id": "wh-4b83484b",
+    "nodeId": "dw-eeedb292",
+    "nodeName": "FFX-温度设定",
+    "param": "烘箱温度设定",
+    "eng": 180,
+    "raw": 180,
+    "ok": true,
+    "message": "Mock PLC 写入成功:180 → raw 180,回读一致(标定后物理值 180)",
+    "recipeRunId": "rr-09acb43b",
+    "at": "2026-09-02T10:37:44.035Z"
+  },
+  {
+    "id": "wh-515c6f27",
+    "nodeId": "dw-eeedb292",
+    "nodeName": "FFX-温度设定",
+    "param": "烘箱温度设定",
+    "eng": 182,
+    "raw": 182,
+    "ok": true,
+    "message": "Mock PLC 写入成功:182 → raw 182,回读一致(标定后物理值 182)",
+    "recipeRunId": null,
+    "at": "2026-09-02T10:37:51.026Z"
+  },
+  {
+    "id": "wh-f337d292",
+    "nodeId": "dw-eeedb292",
+    "nodeName": "FFX-温度设定",
+    "param": "烘箱温度设定",
+    "eng": 180,
+    "raw": 180,
+    "ok": true,
+    "message": "Mock PLC 写入成功:180 → raw 180,回读一致(标定后物理值 180)",
+    "recipeRunId": null,
+    "at": "2026-09-02T10:37:51.168Z"
+  },
+  {
+    "id": "wh-f7919063",
+    "nodeId": "dw-eeedb292",
+    "nodeName": "FFX-温度设定",
+    "param": "烘箱温度设定",
+    "eng": 182,
+    "raw": 182,
+    "ok": true,
+    "message": "Mock PLC 写入成功:182 → raw 182,回读一致(标定后物理值 182)",
+    "recipeRunId": null,
+    "at": "2026-09-02T10:39:20.083Z"
   }
 ]

package/server/data/dcws.json

@@ -2026,5 +2026,26 @@
     "state": "ok",
     "lastError": null,
     "createdAt": "2026-09-02T08:44:01.557Z"
+  },
+  {
+    "id": "dw-eeedb292",
+    "templateRef": "dcw-temp-sp",
+    "name": "FFX-温度设定",
+    "driver": "mock",
+    "enabled": true,
+    "holdIntervalMs": null,
+    "unit": "℃",
+    "decimals": 1,
+    "min": 150,
+    "max": 200,
+    "deviceBindingId": null,
+    "driverConfig": {},
+    "lineId": "ln-69eaecb9",
+    "value": 182,
+    "lastAckAt": "2026-09-02T10:39:20.083Z",
+    "lastWriteAt": "2026-09-02T10:39:20.083Z",
+    "state": "ok",
+    "lastError": null,
+    "createdAt": "2026-09-02T10:37:43.697Z"
   }
 ]

package/server/data/line-runs.json

@@ -7,7 +7,7 @@
     "productId": "pd-3ad54846",
     "productName": "光学膜 BOPP",
     "startedAt": "2026-08-31T16:20:13.707Z",
-    "taggedSamples": 33288
+    "taggedSamples": 34566
   },
   {
     "lineId": "ln-c377a6bf",
@@ -17,7 +17,7 @@
     "productId": "pd-7e69e0ee",
     "productName": "警告验证产品-k2xh",
     "startedAt": "2026-09-01T03:23:18.233Z",
-    "taggedSamples": 13453
+    "taggedSamples": 14092
   },
   {
     "lineId": "ln-9224d3d7",
@@ -27,7 +27,7 @@
     "productId": "pd-910c0fa8",
     "productName": "新协议产品-9xhn",
     "startedAt": "2026-09-01T05:59:24.062Z",
-    "taggedSamples": 16433
+    "taggedSamples": 17074
   },
   {
     "lineId": "ln-386c53ed",
@@ -37,7 +37,7 @@
     "productId": "pd-2d4f9357",
     "productName": "新协议产品-6ofk",
     "startedAt": "2026-09-01T06:05:53.063Z",
-    "taggedSamples": 16722
+    "taggedSamples": 17363
   },
   {
     "lineId": "ln-5957f6db",
@@ -47,7 +47,7 @@
     "productId": "pd-a3ed5047",
     "productName": "新协议产品-x4hd",
     "startedAt": "2026-09-01T06:09:02.148Z",
-    "taggedSamples": 16308
+    "taggedSamples": 16949
   },
   {
     "lineId": "ln-9ec42f08",
@@ -57,7 +57,7 @@
     "productId": "pd-5de729c0",
     "productName": "新协议产品-teti",
     "startedAt": "2026-09-01T06:13:44.315Z",
-    "taggedSamples": 16287
+    "taggedSamples": 16928
   },
   {
     "lineId": "ln-69e37924",
@@ -67,7 +67,7 @@
     "productId": "pd-45eb8d43",
     "productName": "新协议产品-fg8t",
     "startedAt": "2026-09-01T06:16:47.469Z",
-    "taggedSamples": 16320
+    "taggedSamples": 16961
   },
   {
     "lineId": "ln-c269e692",
@@ -77,7 +77,7 @@
     "productId": "pd-b3bd0191",
     "productName": "新协议产品-w2sp",
     "startedAt": "2026-09-01T06:56:05.893Z",
-    "taggedSamples": 16371
+    "taggedSamples": 17012
   },
   {
     "lineId": "ln-229d1637",
@@ -87,7 +87,7 @@
     "productId": "pd-06b896f9",
     "productName": "新协议产品-lp4h",
     "startedAt": "2026-09-01T06:57:29.288Z",
-    "taggedSamples": 16243
+    "taggedSamples": 16884
   },
   {
     "lineId": "ln-9546f91f",
@@ -97,7 +97,7 @@
     "productId": "pd-53e55078",
     "productName": "新协议产品-jri6",
     "startedAt": "2026-09-01T07:00:25.059Z",
-    "taggedSamples": 15666
+    "taggedSamples": 16307
   },
   {
     "lineId": "ln-087aad5b",
@@ -107,7 +107,7 @@
     "productId": "pd-e7e969af",
     "productName": "新协议产品-4c2d",
     "startedAt": "2026-09-01T07:09:07.307Z",
-    "taggedSamples": 14657
+    "taggedSamples": 15299
   },
   {
     "lineId": "ln-97d44f8a",
@@ -117,7 +117,7 @@
     "productId": "pd-28a3ab2c",
     "productName": "新协议产品-b2ni",
     "startedAt": "2026-09-01T07:13:44.912Z",
-    "taggedSamples": 14506
+    "taggedSamples": 15148
   },
   {
     "lineId": "ln-a9551770",
@@ -127,7 +127,7 @@
     "productId": "pd-0c6a64c8",
     "productName": "新协议产品-uwkf",
     "startedAt": "2026-09-01T07:15:40.113Z",
-    "taggedSamples": 14151
+    "taggedSamples": 14793
   },
   {
     "lineId": "ln-844ad82f",
@@ -137,7 +137,7 @@
     "productId": "pd-6932b24f",
     "productName": "新协议产品-kk6l",
     "startedAt": "2026-09-01T09:06:55.728Z",
-    "taggedSamples": 12306
+    "taggedSamples": 12948
   },
   {
     "lineId": "ln-af002514",
@@ -147,7 +147,7 @@
     "productId": "pd-6348a595",
     "productName": "0.8mm 光学膜",
     "startedAt": "2026-09-01T14:06:28.766Z",
-    "taggedSamples": 4488
+    "taggedSamples": 5772
   },
   {
     "lineId": "ln-0eccf6ba",
@@ -157,7 +157,7 @@
     "productId": "pd-4b71be77",
     "productName": "哨兵产品-mtjku36w",
     "startedAt": "2026-09-02T04:09:11.482Z",
-    "taggedSamples": 891
+    "taggedSamples": 1213
   },
   {
     "lineId": "ln-e984246e",
@@ -167,7 +167,7 @@
     "productId": "pd-bb1e0bed",
     "productName": "产品C-mtjkwyhu",
     "startedAt": "2026-09-02T04:11:26.583Z",
-    "taggedSamples": 890
+    "taggedSamples": 1212
   },
   {
     "lineId": "ln-1fe0b5bc",
@@ -177,7 +177,7 @@
     "productId": "pd-9f2d9507",
     "productName": "产品D-mtjkzcfr",
     "startedAt": "2026-09-02T04:13:17.902Z",
-    "taggedSamples": 889
+    "taggedSamples": 1211
   },
   {
     "lineId": "ln-d826473e",
@@ -187,7 +187,7 @@
     "productId": "pd-d230255e",
     "productName": "产品E-mtjl43pv",
     "startedAt": "2026-09-02T04:16:59.891Z",
-    "taggedSamples": 888
+    "taggedSamples": 1210
   },
   {
     "lineId": "ln-156abb71",
@@ -197,7 +197,7 @@
     "productId": "pd-6065b4ba",
     "productName": "产品F-mtjl60qf",
     "startedAt": "2026-09-02T04:18:29.340Z",
-    "taggedSamples": 887
+    "taggedSamples": 1209
   },
   {
     "lineId": "ln-bac43927",
@@ -207,7 +207,7 @@
     "productId": "pd-52f54e33",
     "productName": "产品G-mtjl98nl",
     "startedAt": "2026-09-02T04:20:59.682Z",
-    "taggedSamples": 886
+    "taggedSamples": 1208
   },
   {
     "lineId": "ln-f223008a",
@@ -217,6 +217,6 @@
     "productId": "pd-d919d4bf",
     "productName": "产品-mtjo000v",
     "startedAt": "2026-09-02T05:37:50.743Z",
-    "taggedSamples": 885
+    "taggedSamples": 1207
   }
 ]

package/server/plugins/backup.ts

@@ -1,13 +1,13 @@
 /**
  * 备份定时插件(S6,production-readiness-plan)。
  *
- * 对 data/ 下三库(workshop/users/daq-timeseries)每日 VACUUM INTO 快照到
+ * 对 data/ 下三库(workshop/users/daq-timeseries)每日 serialize 镜像快照到
  * data/backups/,按 BACKUP_KEEP(默认 7)轮转;调度模式复用 ws.ts 保留期清理的
  * setInterval + globalThis key 防 HMR 重复 + unref()。dev 与生产均生效
  * (备份无副作用,始终开启;BACKUP_DISABLED=1 可关)。
  */
 import { DatabaseSync } from 'node:sqlite'
-import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { ensureDataDir } from '@/shared/config/home.mjs'
 
@@ -15,7 +15,23 @@ const g = globalThis as typeof globalThis & { __awBackupTimer?: NodeJS.Timeout,
 
 const DB_FILES = ['workshop.sqlite', 'users.sqlite', 'daq-timeseries.sqlite'] as const
 
-function backupOnce(dataDir: string): void {
+/**
+ * 单库在线快照(hardening ST-2):node:sqlite serialize() 一致性数据库镜像 → 落盘。
+ * 纯读操作,不与主写者抢锁(VACUUM INTO 会与写事务竞争 SQLITE_BUSY,已实测);
+ * 产物为标准 SQLite 文件,与历史 .bak 结构兼容。失败只记录不抛出。
+ */
+async function backupOne(src: string, target: string): Promise<void> {
+  const db = new DatabaseSync(src)
+  try {
+    const image = db.serialize()
+    writeFileSync(target, image)
+  }
+  finally {
+    db.close()
+  }
+}
+
+async function backupOnce(dataDir: string): Promise<void> {
   const backupDir = resolve(dataDir, 'backups')
   mkdirSync(backupDir, { recursive: true })
   const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
@@ -24,14 +40,8 @@ function backupOnce(dataDir: string): void {
     if (!existsSync(src)) continue
     const target = resolve(backupDir, `${file}.${stamp}.bak`)
     try {
-      const db = new DatabaseSync(src)
-      try {
-        // VACUUM INTO:在线一致性快照(WAL 下安全),不阻塞长事务
-        db.exec(`VACUUM INTO '${target.replace(/\\/g, '/')}'`)
-      }
-      finally {
-        db.close()
-      }
+      await backupOne(src, target)
+      console.log('[backup]', file, '快照完成(serialize)')
     }
     catch (err) {
       console.error(`[backup] ${file} 快照失败:`, err instanceof Error ? err.message : err)

package/server/plugins/dev-stability-guard.ts

@@ -7,6 +7,9 @@
  * 依赖异常中止进程,绝不能被护栏吞掉。
  */
 const SOCKET_NOISE = /ECONNRESET|EPIPE|ECONNABORTED|ETIMEDOUT|ERR_STREAM_PREMATURE_CLOSE/
+// SQLite 忙/锁(hardening ST-1):多写竞争的瞬态错误,记录并继续;
+// 真正的库损坏/磁盘错误不经此路径,仍走致命语义。
+const SQLITE_BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i
 
 function isSocketNoise(reason: unknown): boolean {
   if (reason == null) return false
@@ -22,11 +25,16 @@ function describe(reason: unknown): string {
 }
 
 export default defineNitroPlugin(() => {
+  const isTransientDbBusy = (reason: unknown): boolean => SQLITE_BUSY.test(describe(reason))
   process.on('unhandledRejection', (reason) => {
     if (isSocketNoise(reason)) {
       console.warn(`[stability-guard] socket noise suppressed: ${describe(reason).slice(0, 120)}`)
       return
     }
+    if (isTransientDbBusy(reason)) {
+      console.warn(`[stability-guard] sqlite busy(瞬态,不退出): ${describe(reason).slice(0, 120)}`)
+      return
+    }
     console.error(`[stability-guard] fatal unhandledRejection, exiting:\n${describe(reason)}`)
     process.exit(1)
   })
@@ -35,8 +43,12 @@ export default defineNitroPlugin(() => {
       console.warn(`[stability-guard] socket noise suppressed: ${describe(err).slice(0, 120)}`)
       return
     }
+    if (isTransientDbBusy(err)) {
+      console.warn(`[stability-guard] sqlite busy(瞬态,不退出): ${describe(err).slice(0, 120)}`)
+      return
+    }
     console.error(`[stability-guard] fatal uncaughtException, exiting:\n${describe(err)}`)
     process.exit(1)
   })
-  console.warn('[stability-guard] armed (socket disconnects → log & continue; real errors → exit 1)')
+  console.warn('[stability-guard] armed (socket 断连与 sqlite 瞬态忙 → 记录继续;真实错误 → exit 1)')
 })

package/server/plugins/retention.ts

@@ -0,0 +1,57 @@
+/**
+ * 保留期定时插件(hardening GROW-1)。
+ *
+ * 每 24h 对 workshop.sqlite 的 messages/audit_log/approval_history 做分批保留
+ * 清理(策略见 db/retention.ts;RETENTION_DISABLED=1 可整体关闭)。
+ * 调度模式同 backup.ts:setInterval + globalThis key 防 HMR 重复 + unref()。
+ * 启动 90s 后首跑(避开启动风暴,且错峰于 backup 的 30s 首备)。
+ */
+import { DatabaseSync } from 'node:sqlite'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { runRetentionSweep } from '@/server/services/workshop/db/retention'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+
+const g = globalThis as typeof globalThis & { __awRetentionTimer?: NodeJS.Timeout }
+
+function sweepOnce(dataDir: string): void {
+  const dbPath = resolve(dataDir, 'workshop.sqlite')
+  if (!existsSync(dbPath)) return
+  const db = new DatabaseSync(dbPath)
+  try {
+    const results = runRetentionSweep(db)
+    for (const r of results) {
+      if (r.removed > 0) console.log(`[retention] ${r.table} 清理 ${r.removed} 行(>${r.days}d)`)
+    }
+  }
+  finally {
+    db.close()
+  }
+}
+
+export default function retentionPlugin() {
+  if (process.env.RETENTION_DISABLED === '1' || process.env.AW_RETENTION_DISABLED === '1') return
+  if (g.__awRetentionTimer) return
+  const dataDir = ensureDataDir()
+
+  const first = setTimeout(() => {
+    try {
+      sweepOnce(dataDir)
+    }
+    catch (err) {
+      console.error('[retention] 首轮清理失败:', err instanceof Error ? err.message : err)
+    }
+  }, 90_000)
+  first.unref?.()
+
+  const timer = setInterval(() => {
+    try {
+      sweepOnce(dataDir)
+    }
+    catch (err) {
+      console.error('[retention] 定时清理失败:', err instanceof Error ? err.message : err)
+    }
+  }, 24 * 3_600_000)
+  timer.unref?.()
+  g.__awRetentionTimer = timer
+}

package/server/services/workshop/daq/daq-controller.ts

@@ -476,12 +476,14 @@ class DaqController {
   controllerState(): AepDaqControllerState & { produced?: number, consumed?: number, dropped?: number, samplesStored?: number, tsdbDropped?: number } {
     // 丢弃 = 队列层真实丢弃(inproc 拥塞/mqtt 断连)+ 消费侧乱序迟到帧(诚实可见)
     const queueLost = g_queueLost()
+    // 单次遍历(hardening PERF-1):status 高频路径不再对全表多次 all()
+    const nodes = this.repo.all()
     return {
       running: this.running,
       defaultIntervalMs: this.defaultIntervalMs,
       defaultPublishIntervalMs: this.defaultPublishIntervalMs,
-      nodesTotal: this.repo.all().length,
-      nodesOnline: this.onlineCount(),
+      nodesTotal: nodes.length,
+      nodesOnline: this.running ? nodes.filter(n => n.enabled).length : 0,
       produced: this.producedCount,
       consumed: this.consumedCount,
       dropped: Math.max(0, this.producedCount - this.consumedCount) + queueLost + this.lateDropped,

package/server/services/workshop/db/retention.ts

@@ -0,0 +1,50 @@
+/**
+ * 增长治理保留策略(hardening GROW-1)。
+ *
+ * 为无保留机制的只增表做分批清理(每批 ≤5000,循环到 0,避免长事务持锁):
+ *   messages          默认 30d   (AW_MESSAGES_RETENTION_D)
+ *   audit_log         默认 90d   (AW_AUDIT_RETENTION_D;合规观察期,从严保留)
+ *   approval_history  默认 180d  (AW_APPROVAL_RETENTION_D;历史裁决主张不可变,放宽)
+ * AW_RETENTION_DISABLED=1 整体逃生门。时间列均为 TEXT ISO,可字典序比较。
+ * channel_events 与 daq_samples 已有各自保留机制,此处不重复覆盖。
+ */
+type DatabaseSyncLike = {
+  prepare: (sql: string) => { run: (...args: unknown[]) => { changes: number | bigint } }
+}
+
+const DAY_MS = 86_400_000
+const BATCH = 5000
+
+const TARGETS = [
+  { table: 'messages', column: 'created_at', days: 30, envKey: 'AW_MESSAGES_RETENTION_D' },
+  { table: 'audit_log', column: 'at', days: 90, envKey: 'AW_AUDIT_RETENTION_D' },
+  { table: 'approval_history', column: 'created_at', days: 180, envKey: 'AW_APPROVAL_RETENTION_D' },
+] as const
+
+function retentionDays(envKey: string, fallback: number): number {
+  const n = Number(process.env[envKey])
+  return Number.isFinite(n) && n > 0 ? n : fallback
+}
+
+export interface RetentionResult { table: string, removed: number, days: number }
+
+/** 对单库执行一轮保留清理;返回各表删除行数(调用方负责 try/catch 与日志)。 */
+export function runRetentionSweep(db: DatabaseSyncLike): RetentionResult[] {
+  if (process.env.AW_RETENTION_DISABLED === '1') return []
+  const out: RetentionResult[] = []
+  for (const t of TARGETS) {
+    const days = retentionDays(t.envKey, t.days)
+    const before = new Date(Date.now() - days * DAY_MS).toISOString()
+    let removed = 0
+    for (;;) {
+      const res = db.prepare(
+        `DELETE FROM ${t.table} WHERE rowid IN (SELECT rowid FROM ${t.table} WHERE ${t.column} < ? LIMIT ${BATCH})`,
+      ).run(before)
+      const n = Number(res.changes)
+      removed += n
+      if (n < BATCH) break
+    }
+    out.push({ table: t.table, removed, days })
+  }
+  return out
+}

package/server/services/workshop/dcw/dcw-controller.ts

@@ -218,10 +218,12 @@ class DcwController {
   }
 
   controllerState() {
+    // 单次遍历(hardening PERF-1):status 高频路径不再对全表多次 all()
+    const nodes = this.repo.all()
     return {
       running: this.running,
-      nodesTotal: this.repo.all().length,
-      nodesOnline: this.running ? this.repo.all().filter(n => n.enabled).length : 0,
+      nodesTotal: nodes.length,
+      nodesOnline: this.running ? nodes.filter(n => n.enabled).length : 0,
       writesTotal: this.writesTotal,
       writesFailed: this.writesFailed,
     }

package/server/services/workshop/prompts/loader.ts

@@ -7,11 +7,18 @@
  *  - 缓存:mtime 感知(文件修改即刻生效,dev/HMR 友好;stat 开销可忽略)
  *  - host-tools.json:结构化工具定义(name/label/description/parameters),
  *    JSON 承载 schema,与叙事型 md 并置同一目录统一管理
- *  - 目录解析:AW_PROMPTS_DIR 环境变量 → process.cwd()/.AgentWorkShop/prompts;
+ *  - 目录解析(hardening 后的规约,与配置根优先级同族):
+ *      ① AW_PROMPTS_DIR 环境变量(显式覆盖,兼容旧约定)
+ *      ② 项目内 <cwd 向上>/.AgentWorkShop/prompts 真实存在 → 项目内优先
+ *      ③ 否则 ~/.AgentWorkShop/prompts —— 首次解析时从包内资产播种初始文件
+ *        (只补缺失文件,绝不覆盖已有内容 → 用户在 Home 的定制即权威版本);
+ *        播种源 = AW_PACKAGE_ROOT(启动器注入的包根)/.AgentWorkShop/prompts
  *    启动即校验(缺文件 fail-fast,防静默降级为无 prompt 裸跑)
  */
-import { readFileSync, statSync, existsSync, readdirSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { copyFileSync, existsSync, readdirSync, readFileSync, statSync, mkdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { awHome, findLocalConfigRoot } from '../../../../shared/config/home.mjs'
 import { AppError } from '../../../utils/errors'
 
 /** 模板变量值(字符串化注入) */
@@ -24,15 +31,61 @@ interface CacheEntry {
 
 const cache = new Map<string, CacheEntry>()
 
-/** prompts 目录(AW_PROMPTS_DIR 覆盖 → cwd 相对) */
+/** 包内资产 prompts 目录(播种源;不存在返回 null) */
+function packagedPromptsDir(): string | null {
+  const packageRoot = process.env.AW_PACKAGE_ROOT
+    ? resolve(process.env.AW_PACKAGE_ROOT)
+    : resolve(dirname(fileURLToPath(import.meta.url)), '../../../..')
+  const candidate = join(packageRoot, '.AgentWorkShop', 'prompts')
+  return existsSync(candidate) ? candidate : null
+}
+
+/** 首次解析时把包内初始 prompts 播种到 ~/.AgentWorkShop/prompts(只补缺,不覆盖) */
+function seedHomePrompts(homePrompts: string): void {
+  const src = packagedPromptsDir()
+  if (!src || resolve(src) === resolve(homePrompts)) return
+  mkdirSync(homePrompts, { recursive: true })
+  let seeded = 0
+  for (const f of readdirSync(src)) {
+    const dst = join(homePrompts, f)
+    if (existsSync(dst)) continue
+    try {
+      copyFileSync(join(src, f), dst)
+      seeded++
+    }
+    catch { /* 单文件失败不阻断播种 */ }
+  }
+  if (seeded > 0) console.log(`[prompts] 已向 ${homePrompts} 播种 ${seeded} 个初始提示词文件`)
+}
+
+/**
+ * prompts 目录解析:显式覆盖 > 项目内(存在即用) > ~/.AgentWorkShop/prompts(自动播种)。
+ * 失败 fail-fast —— 外置 prompt 为必需,防静默降级为无 prompt 裸跑。
+ */
 export function promptsDir(): string {
-  const base = process.env.AW_PROMPTS_DIR
-    ? resolve(process.env.AW_PROMPTS_DIR)
-    : resolve(process.cwd(), '.AgentWorkShop', 'prompts')
-  if (!existsSync(base)) {
-    throw new AppError(500, 'PROMPTS_DIR_MISSING', `prompts 目录不存在: ${base}(外置 prompt 为必需;可用 AW_PROMPTS_DIR 指定)`)
+  // ① 显式覆盖(兼容既有部署约定)
+  if (process.env.AW_PROMPTS_DIR) {
+    const base = resolve(process.env.AW_PROMPTS_DIR)
+    if (!existsSync(base)) {
+      throw new AppError(500, 'PROMPTS_DIR_MISSING', `prompts 目录不存在: ${base}(AW_PROMPTS_DIR 指定)`)
+    }
+    return base
+  }
+
+  // ~/.AgentWorkShop/prompts:默认兜底目录,首次解析自动播种初始文件(只补缺,不覆盖用户定制)
+  const homePrompts = join(awHome(process.env), 'prompts')
+  if (!existsSync(homePrompts)) seedHomePrompts(homePrompts)
+
+  // ② 项目内 ./.AgentWorkShop/prompts 真实存在 → 项目内优先
+  const localConfigRoot = findLocalConfigRoot(process.cwd())
+  if (localConfigRoot) {
+    const candidate = join(localConfigRoot, 'prompts')
+    if (existsSync(candidate)) return candidate
   }
-  return base
+
+  // ③ ~/.AgentWorkShop/prompts
+  if (existsSync(homePrompts)) return homePrompts
+  throw new AppError(500, 'PROMPTS_DIR_MISSING', `prompts 目录不存在(已尝试自动播种): ${homePrompts};可用 AW_PROMPTS_DIR 指定`)
 }
 
 /** 读取 md 原文(mtime 缓存;文件缺失 fail-fast) */