dsh-erpbot 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-erpbot",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "erpBot (Harness Erp): a bilingual finance/ERP panel with four business bots, a merged base page and an Aurora-style dashboard.",
   "keywords": [
@@ -30,6 +30,7 @@
   "main": "./index.js",
   "exports": {
     ".": "./index.js",
+    "./bot-identity": "./bot-identity.js",
     "./client": "./client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
@@ -39,11 +40,14 @@
   },
   "files": [
     "index.js",
+    "bot-identity.js",
     "client.js",
     "src/",
-    "scripts/build.mjs",
+    "scripts/",
     "cordis.patch.yml",
     "locale/*.json",
+    "docs/",
+    "spec/",
     "icon.svg",
     "README.md",
     "LICENSE"

package/scripts/check-bot-identity.mjs

@@ -0,0 +1,71 @@
+/**
+ * Cross-check the two copies of the bot identity.
+ *
+ * The Host half owns bot-identity.js (used to scaffold bot.json / AGENTS.md /
+ * SKILLS.md at mount). The browser bundle owns src/bot-data.js (used to render).
+ * They must agree on everything that reaches a generated file, or a bot's
+ * on-disk identity would disagree with what its page shows.
+ *
+ * Usage: node scripts/check-bot-identity.mjs   (exit 0 = consistent)
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { pathToFileURL } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+const { BOT_IDENTITY } = await import(pathToFileURL(join(root, 'bot-identity.js')).href)
+
+/* src/bot-data.js is a fragment (top-level `const`, no exports), so evaluate it
+   in an isolated scope and read the two bindings it declares. */
+const fragment = readFileSync(join(root, 'src', 'bot-data.js'), 'utf8')
+const sandbox = {}
+new Function('out', fragment + '\n;out.BOTS = BOTS;out.BOT_IDS = BOT_IDS;')(sandbox)
+const clientBots = sandbox.BOTS
+const clientIds = sandbox.BOT_IDS
+
+const FIELDS = ['name', 'role', 'duties', 'tone', 'boundaries', 'notApplicable', 'scene']
+let failures = 0
+
+const hostIds = Object.keys(BOT_IDENTITY)
+
+if (hostIds.join(',') !== clientIds.join(',')) {
+  failures += 1
+  console.log(`FAIL ids: host=[${hostIds.join(',')}] client=[${clientIds.join(',')}]`)
+} else {
+  console.log(`ok   ids: ${hostIds.join(', ')}`)
+}
+
+for (const id of hostIds) {
+  const host = BOT_IDENTITY[id]
+  const client = clientBots[id]
+  if (client === undefined) {
+    failures += 1
+    console.log(`FAIL ${id}: missing in src/bot-data.js`)
+    continue
+  }
+  const drift = []
+  for (const field of FIELDS) {
+    const hostValue = host[field]
+    const clientValue = client[field]
+    if (hostValue === undefined || clientValue === undefined) {
+      drift.push(`${field} (missing on ${hostValue === undefined ? 'host' : 'client'})`)
+      continue
+    }
+    for (const lang of ['zh', 'en']) {
+      if (hostValue[lang] !== clientValue[lang]) drift.push(`${field}.${lang}`)
+    }
+  }
+  if (drift.length > 0) {
+    failures += 1
+    console.log(`FAIL ${id}: drifted fields → ${drift.join(', ')}`)
+  } else {
+    console.log(`ok   ${id}: ${FIELDS.length} fields agree`)
+  }
+}
+
+console.log('')
+console.log(failures === 0 ? 'bot identity consistent ✅' : `${failures} inconsistency group(s)`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/lint-factories.mjs

@@ -0,0 +1,315 @@
+/**
+ * 防回归静态检查：找出每个工厂（createXxx）函数体里「未注入、未在工厂任意
+ * 作用域声明、非平台全局」的自由标识符引用。
+ *
+ * 背景：0c41a01 工厂化重构把顶层符号（LANGS / SHORT_LOCALE / LANG_BADGE / readLang /
+ * setLang / drawTrend）挪进了 createI18n/createChart 的闭包，但其它工厂的函数体
+ * 仍按「顶层符号」引用它们。verify.mjs 只查加载期（直接子声明初始化表达式），
+ * 故意不递归函数体，所以这类调用期 ReferenceError 会漏网 —— 症状就是 HerpPanel
+ * 渲染时抛错、main slot 空白。
+ *
+ * 本检查器补齐这块：对每个 createXxx 工厂，收集其「整个函数体（含所有嵌套
+ * 函数）里出现的标识符」，减去三样东西后剩下的就是未注入自由引用：
+ *   1. deps 参数解构出来的注入符号；
+ *   2. 工厂任意层级作用域里声明的名字（含嵌套函数参数 / 局部变量 / 内部函数名 /
+ *      catch 参数 / 函数表达式名）；
+ *   3. 已知的平台 / 全局名字。
+ *
+ * 用法：node scripts/lint-factories.mjs   （退出码 0 = 无未注入自由引用）
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+const require = createRequire(join(here, 'noop.js'))
+
+let acorn
+try { acorn = require(join(root, 'node_modules', 'acorn')) }
+catch { throw new Error('scripts/lint-factories.mjs: acorn not installed — run `npm install` first') }
+
+const fileArg = process.argv.find((a) => a.startsWith('--file='))
+const clientPath = fileArg ? fileArg.slice('--file='.length) : join(root, 'client.js')
+const code = readFileSync(clientPath, 'utf8')
+const ast = acorn.parse(code, { ecmaVersion: 2022, sourceType: 'script' })
+
+// 平台/全局允许名单
+const GLOBALS = new Set([
+  'React', 'h', 'window', 'document', 'console', 'fetch',
+  'Math', 'Date', 'JSON', 'RegExp', 'Error', 'TypeError', 'String', 'Number', 'Array', 'Object',
+  'Promise', 'Intl', 'Set', 'Map', 'Symbol', 'isFinite', 'parseFloat', 'parseInt', 'NaN', 'Infinity',
+  'encodeURIComponent', 'decodeURIComponent', 'encodeURI',
+  'undefined', 'arguments',
+  'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval',
+  'requestAnimationFrame', 'cancelAnimationFrame', 'ResizeObserver',
+  'localStorage', 'SVG_NS', 'PANEL_ID', 'NS',
+])
+
+// 收集绑定标识符（声明/参数位置出现的名字）
+function collectBinding(pat, out) {
+  if (!pat) return
+  switch (pat.type) {
+    case 'Identifier': out.add(pat.name); return
+    case 'ObjectPattern': for (const p of pat.properties) collectBinding(p.type === 'RestElement' ? p.argument : p.value, out); return
+    case 'ArrayPattern': for (const e of pat.elements) collectBinding(e, out); return
+    case 'AssignmentPattern': collectBinding(pat.left, out); return
+    case 'RestElement': collectBinding(pat.argument, out); return
+    default: return
+  }
+}
+
+// 收集一个函数作用域内的全部局部声明名（含参数、内部函数名、catch 参数），
+// 并递归进嵌套函数。
+function collectScope(node, out) {
+  for (const param of node.params || []) collectBinding(param, out)
+  const body = node.body
+  const stmts = body.type === 'BlockStatement' ? body.body : [body]
+  for (const stmt of stmts) {
+    if (stmt.type === 'VariableDeclaration') {
+      for (const d of stmt.declarations) {
+        collectBinding(d.id, out)
+        // 初始化表达式里的函数表达式/箭头函数也要递归（它们有自己的作用域）
+        if (d.init) collectNestedFunctions(d.init, out)
+      }
+    } else if ((stmt.type === 'FunctionDeclaration' || stmt.type === 'ClassDeclaration') && stmt.id) {
+      out.add(stmt.id.name)
+      if (stmt.type === 'FunctionDeclaration') collectScope(stmt, out)
+    } else {
+      collectNestedFunctions(stmt, out)
+    }
+  }
+}
+
+// 递归遍历节点，收集其中所有嵌套函数的作用域声明 + 块级变量声明
+function collectNestedFunctions(node, out) {
+  if (!node || typeof node !== 'object') return
+  if (node.type === 'FunctionDeclaration') {
+    if (node.id) out.add(node.id.name)
+    collectScope(node, out)
+    return
+  }
+  if (node.type === 'FunctionExpression') {
+    if (node.id) out.add(node.id.name)
+    collectScope(node, out)
+    return
+  }
+  if (node.type === 'ArrowFunctionExpression') {
+    collectScope(node, out)
+    return
+  }
+  if (node.type === 'CatchClause') {
+    collectBinding(node.param, out)
+    collectNestedFunctions(node.body, out)
+    return
+  }
+  if (node.type === 'VariableDeclaration') {
+    for (const d of node.declarations) {
+      collectBinding(d.id, out)
+      if (d.init) collectNestedFunctions(d.init, out)
+    }
+    return
+  }
+  for (const key of Object.keys(node)) {
+    if (['type', 'start', 'end', 'loc', 'range'].includes(key)) continue
+    const v = node[key]
+    if (Array.isArray(v)) { for (const it of v) if (it && typeof it === 'object') collectNestedFunctions(it, out) }
+    else if (v && typeof v === 'object') collectNestedFunctions(v, out)
+  }
+}
+
+// 收集一个节点内出现的全部标识符（引用位置）
+function collectIdents(node, out) {
+  if (!node || typeof node !== 'object') return
+  if (node.type === 'Identifier') { out.add(node.name); return }
+  // 属性键 / 成员名不是引用
+  if (node.type === 'Property' && !node.computed && node.key === node.value) return // 简写 {a}
+  for (const key of Object.keys(node)) {
+    if (['type', 'start', 'end', 'loc', 'range'].includes(key)) continue
+    if (key === 'key' && node.type === 'Property' && !node.computed) continue
+    if (key === 'key' && node.type === 'MethodDefinition' && !node.computed) continue
+    if (key === 'property' && node.type === 'MemberExpression' && !node.computed) continue
+    const v = node[key]
+    if (Array.isArray(v)) { for (const it of v) if (it && typeof it === 'object') collectIdents(it, out) }
+    else if (v && typeof v === 'object') collectIdents(v, out)
+  }
+}
+
+const factoryNodes = []
+function findFactories(node) {
+  if (!node || typeof node !== 'object') return
+  if (node.type === 'FunctionDeclaration' && node.id && /^create[A-Z]/.test(node.id.name)) {
+    factoryNodes.push(node)
+    return // 不递归进工厂内部（避免误把内部函数当工厂）
+  }
+  for (const key of Object.keys(node)) {
+    if (['type', 'start', 'end', 'loc', 'range'].includes(key)) continue
+    const v = node[key]
+    if (Array.isArray(v)) { for (const it of v) if (it && it.type) findFactories(it) }
+    else if (v && typeof v === 'object' && v.type) findFactories(v)
+  }
+}
+findFactories(ast)
+
+let failures = 0
+
+for (const factory of factoryNodes) {
+  const name = factory.id.name
+  const params = factory.params.map((p) => p.name)
+
+  // 1) deps 解构注入符号
+  const injected = new Set()
+  for (const stmt of factory.body.body) {
+    if (stmt.type === 'VariableDeclaration') {
+      for (const d of stmt.declarations) {
+        if (d.init && d.init.type === 'Identifier' && params.includes(d.init.name)) {
+          collectBinding(d.id, injected)
+        }
+      }
+    }
+  }
+
+  // 2) 工厂全作用域局部声明（含参数、所有嵌套层）
+  const local = new Set(params)
+  for (const stmt of factory.body.body) {
+    if (stmt.type === 'VariableDeclaration') {
+      for (const d of stmt.declarations) {
+        collectBinding(d.id, local)
+        if (d.init) collectNestedFunctions(d.init, local)
+      }
+    } else if ((stmt.type === 'FunctionDeclaration' || stmt.type === 'ClassDeclaration') && stmt.id) {
+      local.add(stmt.id.name)
+      if (stmt.type === 'FunctionDeclaration') collectScope(stmt, local)
+    } else {
+      collectNestedFunctions(stmt, local)
+    }
+  }
+
+  // 3) 全函数体标识符
+  const used = new Set()
+  collectIdents(factory.body, used)
+
+  // 4) 自由引用
+  const free = [...used].filter((id) =>
+    !injected.has(id) && !local.has(id) && !GLOBALS.has(id))
+
+  if (free.length > 0) {
+    failures += 1
+    console.log(`FAIL ${name}: 未注入的自由引用 → ${free.sort().join(', ')}`)
+  } else {
+    console.log(`ok   ${name}: 无未注入自由引用`)
+  }
+}
+
+/* =====================================================================
+ * 第二部分：apply() 的顶层符号检查。
+ *
+ * 工厂化把符号关进了各自闭包，而 mount.js 的 apply() 是「模块作用域」函数，
+ * 它只能引用 entry.js 解构回顶层的符号。entry.js 漏解构一个（例如
+ * refreshTeamChat），verify.mjs 不查函数体、上面的工厂检查也只看工厂内部，
+ * 于是症状同样落在运行期：apply 抛 ReferenceError，整个面板空白。
+ *
+ * 判据：apply() 函数体里出现的自由标识符，必须落在
+ *   1. 它自己的参数 / 局部声明；
+ *   2. 平台全局；
+ *   3. 模块作用域（loader factory 的直接子声明，含 entry.js 的解构）之内。
+ * ===================================================================== */
+
+// 定位 __ModuleLoader__.load({ factory() { ... } }) 里的模块作用域函数
+let moduleFn = null
+function findModuleFn(node) {
+  if (moduleFn || !node || typeof node !== 'object') return
+  if (node.type === 'CallExpression' && node.arguments && node.arguments.length > 0) {
+    const first = node.arguments[0]
+    if (first && first.type === 'ObjectExpression') {
+      for (const prop of first.properties) {
+        const key = prop.key && (prop.key.name || prop.key.value)
+        const value = prop.value
+        if (key === 'factory' && value
+          && (value.type === 'FunctionExpression' || value.type === 'ArrowFunctionExpression')) {
+          moduleFn = value
+          return
+        }
+      }
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (['type', 'start', 'end', 'loc', 'range'].includes(key)) continue
+    const v = node[key]
+    if (Array.isArray(v)) { for (const it of v) if (it && it.type) findModuleFn(it) }
+    else if (v && typeof v === 'object' && v.type) findModuleFn(v)
+  }
+}
+findModuleFn(ast)
+
+// 模块作用域的「直接子声明」——只有这些是 apply 能看见的顶层符号
+const moduleScope = new Set()
+if (moduleFn !== null) {
+  const body = moduleFn.body
+  const stmts = body.type === 'BlockStatement' ? body.body : []
+  for (const stmt of stmts) {
+    if (stmt.type === 'VariableDeclaration') {
+      for (const d of stmt.declarations) collectBinding(d.id, moduleScope)
+    } else if ((stmt.type === 'FunctionDeclaration' || stmt.type === 'ClassDeclaration') && stmt.id) {
+      moduleScope.add(stmt.id.name)
+    }
+  }
+}
+
+// 收集所有名为 apply 的函数值
+const applyNodes = []
+function findApply(node) {
+  if (!node || typeof node !== 'object') return
+  const key = node.key && (node.key.name || node.key.value)
+  if (key === 'apply' && node.value
+    && (node.value.type === 'FunctionExpression' || node.value.type === 'ArrowFunctionExpression')) {
+    applyNodes.push(node.value)
+    return
+  }
+  for (const k of Object.keys(node)) {
+    if (['type', 'start', 'end', 'loc', 'range'].includes(k)) continue
+    const v = node[k]
+    if (Array.isArray(v)) { for (const it of v) if (it && it.type) findApply(it) }
+    else if (v && typeof v === 'object' && v.type) findApply(v)
+  }
+}
+if (moduleFn !== null) findApply(moduleFn)
+
+if (applyNodes.length === 0) {
+  console.log('FAIL apply(): 未找到模块作用域里的 apply()，检查器需要同步 DSH 插件形态')
+  failures += 1
+} else if (moduleScope.size === 0) {
+  console.log('FAIL apply(): 未解析出模块作用域的直接子声明')
+  failures += 1
+} else {
+  for (const applyFn of applyNodes) {
+    const local = new Set()
+    for (const param of applyFn.params || []) collectBinding(param, local)
+    const body = applyFn.body
+    const stmts = body.type === 'BlockStatement' ? body.body : [body]
+    for (const stmt of stmts) {
+      if (stmt.type === 'VariableDeclaration') {
+        for (const d of stmt.declarations) collectBinding(d.id, local)
+      } else if ((stmt.type === 'FunctionDeclaration' || stmt.type === 'ClassDeclaration') && stmt.id) {
+        local.add(stmt.id.name)
+      }
+      collectNestedFunctions(stmt, local)
+    }
+    const used = new Set()
+    collectIdents(applyFn.body, used)
+    const free = [...used].filter((id) =>
+      !local.has(id) && !GLOBALS.has(id) && !moduleScope.has(id))
+    if (free.length > 0) {
+      failures += 1
+      console.log(`FAIL apply(): 引用了未在模块作用域声明的符号 → ${free.sort().join(', ')}`)
+      console.log('     （多半是 entry.js 少解构了一个工厂导出；apply 只能看到顶层符号）')
+    } else {
+      console.log('ok   apply(): 引用的顶层符号均已解构')
+    }
+  }
+}
+
+console.log('')
+console.log(failures === 0 ? '全部工厂与 apply 均无未注入自由引用 ✅' : `${failures} 处存在未注入自由引用`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/lint-scopes.mjs

@@ -0,0 +1,179 @@
+/**
+ * lint-scopes — catch cross-component undeclared references.
+ *
+ * The gap this closes: a helper declared inside ONE component but called from
+ * ANOTHER. Syntax is valid, so acorn/verify/build-check all pass; and
+ * lint-factories treats any declaration anywhere inside a factory as
+ * "declared", so it passes too. At runtime it is a ReferenceError that blanks
+ * the panel — which is exactly how `drawerHead` broke TeamShell.
+ *
+ * Method: for every function declared at factory scope, walk its body with a
+ * real lexical scope chain (params + declarations visible in each block,
+ * stopping at nested function boundaries), and report identifiers that resolve
+ * to nothing.
+ *
+ * Usage: node scripts/lint-scopes.mjs [file]
+ */
+import { readFileSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(join(here, '..', 'package.json'))
+const acorn = require('acorn')
+
+const target = process.argv[2]
+  ? resolve(process.argv[2])
+  : join(here, '..', 'src', 'workbench', 'index.js')
+
+const src = readFileSync(target, 'utf8')
+const ast = acorn.parse(src, { ecmaVersion: 'latest', sourceType: 'script', locations: true })
+
+const GLOBALS = new Set([
+  'React', 'h', 'window', 'document', 'console', 'fetch',
+  'Math', 'Date', 'JSON', 'RegExp', 'Error', 'TypeError', 'String', 'Number', 'Array', 'Object',
+  'Promise', 'Intl', 'Set', 'Map', 'Symbol', 'isFinite', 'parseFloat', 'parseInt', 'NaN', 'Infinity',
+  'encodeURIComponent', 'decodeURIComponent', 'encodeURI', 'Boolean',
+  'undefined', 'arguments', 'this',
+  'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval',
+  'requestAnimationFrame', 'cancelAnimationFrame', 'ResizeObserver',
+  'localStorage', 'SVG_NS', 'PANEL_ID', 'NS',
+])
+
+function collectBinding(pat, out) {
+  if (!pat) return
+  switch (pat.type) {
+    case 'Identifier': out.add(pat.name); break
+    case 'ObjectPattern':
+      for (const p of pat.properties) collectBinding(p.type === 'RestElement' ? p.argument : p.value, out)
+      break
+    case 'ArrayPattern': for (const e of pat.elements) collectBinding(e, out); break
+    case 'RestElement': collectBinding(pat.argument, out); break
+    case 'AssignmentPattern': collectBinding(pat.left, out); break
+    default: break
+  }
+}
+
+/** Names visible in a scope: recurse through blocks, stop at function boundaries. */
+function collectVisible(node, out) {
+  if (!node || typeof node !== 'object') return
+  switch (node.type) {
+    case 'VariableDeclaration':
+      for (const d of node.declarations) collectBinding(d.id, out)
+      return
+    case 'FunctionDeclaration': if (node.id) out.add(node.id.name); return
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression':
+      return
+    case 'ClassDeclaration': if (node.id) out.add(node.id.name); return
+    case 'CatchClause': if (node.param) collectBinding(node.param, out); break
+    default: break
+  }
+  for (const k of Object.keys(node)) {
+    if (k === 'loc' || k === 'start' || k === 'end') continue
+    const v = node[k]
+    if (Array.isArray(v)) { for (const it of v) collectVisible(it, out) }
+    else if (v && typeof v === 'object') collectVisible(v, out)
+  }
+}
+
+const problems = []
+
+function analyze(fn, enclosing, label) {
+  const scope = new Set(enclosing)
+  for (const p of fn.params) collectBinding(p, scope)
+  const stmts = fn.body.type === 'BlockStatement' ? fn.body.body : []
+  for (const s of stmts) collectVisible(s, scope)
+
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') return
+    switch (node.type) {
+      case 'FunctionDeclaration': {
+        const inner = node.id ? node.id.name : '(anonymous)'
+        analyze(node, scope, label + ' > ' + inner)
+        return
+      }
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+        analyze(node, scope, label + ' > (anonymous)')
+        return
+      case 'Identifier':
+        if (!scope.has(node.name) && !GLOBALS.has(node.name)) {
+          problems.push({ label, name: node.name, line: node.loc.start.line })
+        }
+        return
+      case 'MemberExpression':
+        visit(node.object)
+        if (node.computed) visit(node.property)
+        return
+      case 'Property':
+        if (node.computed) visit(node.key)
+        visit(node.value)
+        return
+      case 'VariableDeclarator':
+        visit(node.init)
+        return
+      case 'LabeledStatement':
+        visit(node.body)
+        return
+      case 'BreakStatement':
+      case 'ContinueStatement':
+        return
+      default: break
+    }
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'start' || k === 'end') continue
+      const v = node[k]
+      if (Array.isArray(v)) { for (const it of v) visit(it) }
+      else if (v && typeof v === 'object') visit(v)
+    }
+  }
+
+  for (const s of stmts) visit(s)
+}
+
+let factory = null
+;(function find(node) {
+  if (!node || typeof node !== 'object' || factory) return
+  if (node.type === 'FunctionDeclaration' && node.id && node.id.name === 'createWorkbench') {
+    factory = node
+    return
+  }
+  for (const k of Object.keys(node)) {
+    const v = node[k]
+    if (Array.isArray(v)) { for (const it of v) find(it) }
+    else if (v && typeof v === 'object') find(v)
+  }
+})(ast)
+
+if (!factory) {
+  console.log('跳过：未找到 createWorkbench')
+  process.exit(0)
+}
+
+const factoryScope = new Set()
+for (const p of factory.params) collectBinding(p, factoryScope)
+for (const s of factory.body.body) collectVisible(s, factoryScope)
+
+for (const stmt of factory.body.body) {
+  if (stmt && stmt.type === 'FunctionDeclaration' && stmt.id) {
+    analyze(stmt, factoryScope, stmt.id.name)
+  }
+}
+
+const seen = new Set()
+const unique = problems.filter((p) => {
+  const k = p.label + '|' + p.name
+  if (seen.has(k)) return false
+  seen.add(k)
+  return true
+})
+
+if (unique.length) {
+  console.log(`FAIL 跨组件未声明引用 ${unique.length} 处：`)
+  for (const p of unique) console.log(`  ${p.label}  →  ${p.name}  (L${p.line})`)
+  process.exit(1)
+}
+
+console.log(`ok  作用域检查通过（${target.split(/[\\/]/).pop()}）`)

package/scripts/scaffold-bots.mjs

@@ -0,0 +1,76 @@
+/**
+ * One-shot run of the mount-time scaffolding, so the four bot workspaces can be
+ * verified without a DSH restart. Mirrors index.js scaffoldBotFiles exactly.
+ * Usage: node scripts/scaffold-bots.mjs [--root <dir>]
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { homedir } from 'node:os'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+const { AGENTS_SCHEMA, BOT_IDENTITY, buildAgentsDoc } =
+  await import(pathToFileURL(join(root, 'bot-identity.js')).href)
+
+const argRoot = process.argv.indexOf('--root')
+const D_ROOT = argRoot >= 0 ? process.argv[argRoot + 1] : 'D:\\erpBot'
+const FALLBACK_ROOT = join(homedir(), 'Documents', 'deepseek-harness')
+
+async function ensureDirectory(bot) {
+  for (const [index, directory] of [join(D_ROOT, bot), join(FALLBACK_ROOT, 'erpbot-' + bot)].entries()) {
+    try {
+      await mkdir(directory, { recursive: true })
+      return directory
+    } catch (error) {
+      if (index === 0 && !existsSync('D:\\')) continue
+      throw error
+    }
+  }
+  throw new Error('workspace directory unavailable')
+}
+
+async function scaffoldBotFiles(bot) {
+  const directory = await ensureDirectory(bot)
+  const configPath = join(directory, 'bot.json')
+  const agentsPath = join(directory, 'AGENTS.md')
+  const created = []
+
+  let skills = []
+  let configExists = false
+  if (existsSync(configPath)) {
+    configExists = true
+    try {
+      const parsed = JSON.parse(await readFile(configPath, 'utf8'))
+      if (parsed !== null && typeof parsed === 'object' && Array.isArray(parsed.skills)) {
+        skills = parsed.skills.filter((name) => typeof name === 'string')
+      }
+    } catch (error) { /* rewritten below */ }
+  }
+  if (!configExists) {
+    await writeFile(configPath, JSON.stringify({ bot, skills, updatedAt: new Date().toISOString() }, null, 2) + '\n', 'utf8')
+    created.push('bot.json')
+  }
+
+  let agents = null
+  if (existsSync(agentsPath)) {
+    try { agents = await readFile(agentsPath, 'utf8') } catch (error) { agents = null }
+  }
+  let migrated = false
+  if (agents === null) {
+    await writeFile(agentsPath, buildAgentsDoc(bot, skills, {}) + '\n', 'utf8')
+    created.push('AGENTS.md')
+  } else if (agents.indexOf(AGENTS_SCHEMA) < 0) {
+    await writeFile(agentsPath, buildAgentsDoc(bot, skills, {}) + '\n', 'utf8')
+    migrated = true
+  }
+
+  return { bot, directory, created, migrated }
+}
+
+for (const bot of Object.keys(BOT_IDENTITY)) {
+  const r = await scaffoldBotFiles(bot)
+  console.log(`${r.bot.padEnd(9)} ${r.directory}`)
+  console.log(`  created: ${r.created.length ? r.created.join(', ') : '(none)'}${r.migrated ? '  [AGENTS.md migrated]' : ''}`)
+}