agentworkshop 0.2.1

package/cli/commands/config.mjs

@@ -0,0 +1,157 @@
+// ============================================================
+// 指令:config — 读取 / 写入 / 校验运行配置（配置系统的心脏）
+// ------------------------------------------------------------
+// 用法:
+//   aw config                      # 列出全部设置项（有效值 + 来源 + 生效方式）
+//   aw config list [--json]
+//   aw config get <key> [--json]   # 如 aw config get server.prod.port
+//   aw config set <key> <value>    # 写入 data/runtime-settings.json（schema 校验）
+//   aw config unset <key>          # 移除覆盖，回落到 config.yml
+//   aw config reset [--yes]        # 清空全部运行时覆盖
+//   aw config validate             # 校验 config.yml + 运行时覆盖
+// 写入即持久化；生效时机见 list 输出的 applies 列（restart=重启对应模式）。
+// ============================================================
+import { color } from '../core/logger.mjs'
+import { CliError } from '../core/errors.mjs'
+
+export const meta = {
+  name: 'config',
+  aliases: ['cfg', 'c'],
+  group: '配置',
+  summary: '读取 / 写入 / 校验运行配置',
+  usage: 'aw config [list|get|set|unset|reset|validate] [key] [value] [--json]',
+  description: [
+    '以 config.yml 为默认、runtime-settings.json 为运行时覆盖、环境变量为最高优先级。',
+    '双模式:项目检出内写 <项目>/data/runtime-settings.json;全局安装(任意目录)写 ~/.AgentWorkShop/runtime-settings.json。',
+    'set 走 schema 校验并原子写入;重启对应模式后生效(端口键重启 dev/prod,其余键重启服务重新构建配置)。',
+  ],
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  const { flags, positionals } = argv
+  const sub = positionals[0] ?? 'list'
+  const key = positionals[1]
+  const value = positionals[2]
+
+  switch (sub) {
+    case 'list':
+    case 'ls':
+      return list(ctx)
+    case 'get':
+      return get(ctx, key)
+    case 'set':
+      return set(ctx, key, value)
+    case 'unset':
+      return unset(ctx, key)
+    case 'reset':
+      return reset(ctx, flags)
+    case 'validate':
+    case 'check':
+      return validate(ctx)
+    default:
+      throw new CliError('USAGE', `未知子命令 "${sub}"（list|get|set|unset|reset|validate）`)
+  }
+}
+
+function emit(ctx, obj) {
+  if (ctx.json) console.log(JSON.stringify(obj))
+  return obj
+}
+
+function list(ctx) {
+  const { effective, sources, descriptors } = ctx.config.load()
+  if (ctx.json) {
+    return emit(ctx, {
+      ok: true,
+      effective,
+      sources,
+      settings: descriptors.map(d => ({ ...d, value: effective[d.key], source: sources[d.key] })),
+    })
+  }
+  const rows = []
+  let lastGroup = null
+  for (const d of descriptors) {
+    const group = d.group
+    if (lastGroup !== group) {
+      rows.push([`${color.bold(`[${group}]`)}`, '', ''])
+      lastGroup = group
+    }
+    const value = String(effective[d.key])
+    const source = sources[d.key] === 'env'
+      ? color.yellow('env')
+      : sources[d.key] === 'runtime'
+        ? color.green('runtime')
+        : color.dim('config.yml')
+    const applies = d.applies === 'live' ? color.green('live') : color.yellow('restart')
+    rows.push([`  ${d.key}`, `= ${value}`, `${source} ${applies}`])
+  }
+  for (const row of rows) console.log(`  ${row[0].padEnd(38)} ${row[1].padEnd(18)} ${row[2]}`)
+  console.log('')
+  console.log(color.dim('来源优先级: config.yml < runtime(运行时覆盖) < env。live=保存即生效，restart=重启对应模式后生效。'))
+  return 0
+}
+
+function get(ctx, key) {
+  if (!key) throw new CliError('USAGE', '用法: aw config get <key>')
+  const eff = ctx.config.load()
+  if (!(key in eff.effective)) throw new CliError('USAGE', `未知设置项 "${key}"（aw config list 查看全部）`)
+  if (ctx.json) return emit(ctx, { ok: true, key, value: eff.effective[key], source: eff.sources[key] })
+  console.log(`${color.cyan(key)} = ${color.bold(eff.effective[key])}  ${color.dim(`(来源: ${eff.sources[key]})`)}`)
+  return 0
+}
+
+async function set(ctx, key, value) {
+  if (!key || value === undefined) throw new CliError('USAGE', '用法: aw config set <key> <value>，如 aw config set theme.primaryColor #35e0a0')
+  const result = ctx.config.set(key, value)
+  if (ctx.json) return emit(ctx, { ok: true, ...result })
+  console.log(`${color.green('✔')} ${result.key} = ${color.green(String(result.value))}  ${color.dim(`(原值: ${result.effectiveBefore}, 原 ${result.previousSource === 'env' ? '被环境变量遮蔽' : `来源: ${result.previousSource}`})`)}`)
+  console.log(`  › 写入 ${ctx.settingsPath}  ·  ${color.yellow(result.applies === 'live' ? '实时生效' : '重启对应模式后生效')}`)
+  if (result.previousSource === 'env')
+    console.log(`  ${color.yellow('⚠')} 当前有同名环境变量(AW_${key.toUpperCase().replace(/\./g, '_')})在起作用,运行时优先级高于本写入`)
+  return 0
+}
+
+async function unset(ctx, key) {
+  if (!key) throw new CliError('USAGE', '用法: aw config unset <key>')
+  const result = ctx.config.unset(key)
+  if (ctx.json) return emit(ctx, { ok: true, ...result })
+  if (result.removed) {
+    console.log(`${color.green('✔')} ${key} 已清除覆盖，回落 config.yml 默认（重启对应模式后生效）`)
+  }
+  else {
+    console.log(`${color.dim('›')} ${key} 没有运行时覆盖（当前为 config.yml/env 值），无需清除`)
+  }
+  return 0
+}
+
+async function reset(ctx, flags) {
+  const confirmed = flags.force || flags.yes || flags.y
+  if (!confirmed && !ctx.json) {
+    const { createInterface } = await import('node:readline')
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const answer = await new Promise(resolve2 => rl.question('确定清空全部运行时覆盖？(y/N) ', resolve2))
+    rl.close()
+    if (!/^y(es)?$/i.test(answer.trim())) {
+      console.log('已取消')
+      return 0
+    }
+  }
+  ctx.config.reset()
+  if (ctx.json) return emit(ctx, { ok: true, action: 'reset' })
+  console.log(`${color.green('✔')} 全部运行时覆盖已清空（恢复 config.yml 默认 + 环境变量）`)
+  return 0
+}
+
+function validate(ctx) {
+  const result = ctx.config.validate()
+  if (ctx.json) return emit(ctx, { ok: result.ok, keys: result.keys, overridesChecked: result.overridesChecked })
+  if (result.ok) {
+    const count = ctx.config.load().descriptors.length
+    console.log(`${color.green('✔')} 配置校验通过（${count} 个设置项 + ${result.overridesChecked} 个运行时覆盖）`)
+    return 0
+  }
+  console.log(`${color.red('✖')} 配置校验失败:`)
+  for (const [k, errs] of Object.entries(result.keys)) console.log(`  ${color.bold(k)}: ${errs.join('; ')}`)
+  return 1
+}

package/cli/commands/dev.mjs

@@ -0,0 +1,74 @@
+// ============================================================
+// 指令:dev — 以配置驱动的方式启动开发服务器
+// ------------------------------------------------------------
+// 实际执行 scripts/dev-guard.mjs（与 `pnpm dev` 完全同链路）：
+//   · --unhandled-rejections=warn 重入守卫（陈旧 socket ECONNRESET 免疫,
+//     且 nitro fork 的 worker 经 execArgv 继承同享保护）
+//   · .env 预载（NUXT_SESSION_PASSWORD 等密钥只经环境注入）
+//   · 端口/主机取自有效配置（config.yml < runtime-settings < env < CLI 参数）
+// 子进程统一注入 NO_PROXY（本机代理不再劫持 localhost 回环）。
+// ============================================================
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { color } from '../core/logger.mjs'
+import { localBypassEnv } from '../core/context.mjs'
+
+export const meta = {
+  name: 'dev',
+  aliases: ['d'],
+  group: '运行',
+  summary: '启动开发服务器（配置驱动端口，含断连守卫）',
+  usage: 'aw dev [--port <n>] [--host <h>]',
+  needsProject: true,
+}
+
+export async function run(argv, ctx) {
+  const { flags } = argv
+  const { root, config } = ctx
+
+  const eff = config.load()
+  const port = flags.port !== undefined ? Number(flags.port) : Number(eff.effective['server.dev.port'])
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.log(`${color.red('✖')} 无效端口: ${flags.port ?? eff.effective['server.dev.port']}`)
+    return 1
+  }
+  const host = flags.host !== undefined ? String(flags.host) : String(eff.effective['server.host'] ?? '0.0.0.0')
+  const portSource = flags.port !== undefined ? 'CLI' : eff.sources['server.dev.port']
+
+  // 走 dev-guard 启动链(与 pnpm dev 等效);脚本缺失时退回直连 nuxt(仍带守卫标志)
+  const guard = join(root, 'scripts', 'dev-guard.mjs')
+  const nuxtBin = ctx.resolveNuxtBin()
+  let cmd = process.execPath
+  let args
+  if (existsSync(guard)) {
+    args = [guard, 'dev', '--port', String(port), '--host', host]
+  }
+  else if (nuxtBin) {
+    args = ['--unhandled-rejections=warn', nuxtBin, 'dev', '--port', String(port), '--host', host]
+  }
+  else {
+    console.log(`${color.red('✖')} 未找到 scripts/dev-guard.mjs 且解析不到 nuxt CLI —— 请在项目根安装依赖(pnpm install)`)
+    return 1
+  }
+
+  console.log(`${color.cyan('›')} 开发服务器 -> http://${host}:${port}  ${color.dim(`(端口来源: ${portSource})`)}`)
+  console.log(`${color.cyan('›')} 停止: Ctrl+C`)
+
+  const child = spawn(cmd, args, {
+    cwd: root,
+    stdio: 'inherit',
+    env: localBypassEnv(),
+  })
+  const shutdown = () => child.kill('SIGTERM')
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+
+  return await new Promise((resolve2) => {
+    child.on('close', code => resolve2(code ?? 0))
+    child.on('error', (err) => {
+      console.log(`${color.red('✖')} dev 进程启动失败: ${err.message}`)
+      resolve2(1)
+    })
+  })
+}

package/cli/commands/doctor.mjs

@@ -0,0 +1,120 @@
+// ============================================================
+// 指令:doctor — 环境与项目健康检查
+// ============================================================
+import { existsSync, accessSync, constants } from 'node:fs'
+import { join } from 'node:path'
+import { color } from '../core/logger.mjs'
+import { findRunningServer } from '../core/context.mjs'
+
+export const meta = {
+  name: 'doctor',
+  aliases: ['dsk', 'check-env'],
+  group: '诊断',
+  summary: '环境 / 项目 / 配置健康检查',
+  usage: 'aw doctor [--json]',
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  const checks = []
+  const add = (name, pass, detail = '') => checks.push({ name, pass, detail })
+
+  // ── Node / 包管理器 ──
+  const nodeMajor = Number(process.versions.node.split('.')[0])
+  add('Node.js 版本', nodeMajor >= 20, `v${process.versions.node}${nodeMajor < 23.4 ? '（推荐 ≥23.4：node:sqlite）' : ''}`)
+  const { spawnSync } = await import('node:child_process')
+  // Windows 下需经 shell 才能spawn pnpm.cmd(Node ≥18.20 对无 shell 的 .cmd spawn 返回 EINVAL)
+  const pmBin = 'pnpm'
+  const pm = spawnSync(pmBin, ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' })
+  add('pnpm 可用', pm.status === 0, pm.status === 0 ? `v${(pm.stdout ?? '').trim()}` : '未找到 pnpm')
+
+  // ── AW Home（全局安装模式的配置中枢;两种模式都检查） ──
+  const home = ctx.home
+  add('AW Home 目录', existsSync(home), `${home}${existsSync(home) ? '' : '（aw home 可初始化）'}`)
+  add('AW Home config.yml', existsSync(join(home, 'config.yml')), join(home, 'config.yml'))
+  const homeEnv = join(home, '.env')
+  add('AW Home .env 密钥', existsSync(homeEnv), existsSync(homeEnv) ? '已生成(含随机 session 密钥)' : '未生成(aw home 可初始化)')
+
+  // ── 项目上下文 ──
+  if (ctx.root) {
+    add('项目检测', true, ctx.root)
+    const cfg = ctx.config.load()
+    add('config.yml 可解析', Boolean(cfg.descriptors.length), `${cfg.descriptors.length} 个设置项`)
+    const v = ctx.config.validate()
+    add('配置校验', v.ok, v.ok ? `runtime 覆盖 ${v.overridesChecked} 项` : Object.keys(v.keys).join(', '))
+
+    // 数据目录可写
+    const dataDir = join(ctx.root, 'data')
+    try {
+      accessSync(dataDir, constants.W_OK)
+      add('data/ 可写', true, dataDir)
+    }
+    catch {
+      add('data/ 可写', false, dataDir)
+    }
+
+    // 端口情形
+    const eff = cfg.effective
+    const devPort = eff['server.dev.port']
+    const prodPort = eff['server.prod.port']
+    const server = await findRunningServer(ctx.config, { timeoutMs: 600 })
+    add('运行中服务', Boolean(server), server ? `检测到 ${server.port} 端口 /api/system/config 响应` : '无（dev/prod 均未运行）')
+    const occupied = await checkPorts([devPort, prodPort].filter((p, i, a) => a.indexOf(p) === i))
+    for (const occ of occupied) {
+      add(`端口 ${occ.port}`, !occ.busy, occ.busy ? '已被占用' : '空闲')
+    }
+
+    // 生产密钥
+    const sess = eff.security?.sessionPassword ?? ctx.env.NUXT_SESSION_PASSWORD
+    const isDefault = /change-me|awshop-dev-secret/.test(String(sess))
+    add('生产 session 密钥', !isDefault, isDefault ? '仍是默认值（生产部署前必须更换）' : '已自定义（或由 env 提供）')
+
+    // 产物
+    add('生产构建存在', existsSync(join(ctx.root, '.output', 'server', 'index.mjs')), existsSync(join(ctx.root, '.output', 'server', 'index.mjs')) ? '.output/server/index.mjs' : '尚未 aw build')
+  }
+  else {
+    add('项目检测', false, '当前目录未找到 config.yml（可在项目目录运行，或 aw init 新建）')
+  }
+
+  // ── 指令注册表 ──
+  const cmds = ctx.registry.list()
+  const failed = ctx.registry.failures
+  add('指令注册', failed.length === 0, `${cmds.length} 条指令${failed.length ? `，${failed.length} 个加载失败` : ''}`)
+  for (const f of failed) checks.push({ name: `  加载失败: ${f.source}`, pass: false, detail: f.error })
+
+  // ── 输出 ──
+  if (ctx.json) {
+    console.log(JSON.stringify({ ok: checks.every(c => c.pass), checks }, null, 2))
+    return checks.every(c => c.pass) ? 0 : 1
+  }
+  console.log('')
+  console.log(`${color.bold('AgentWorkShop doctor')}  ${color.dim('— 环境与项目健康检查')}`)
+  console.log('')
+  let fail = 0
+  for (const c of checks) {
+    if (!c.pass) fail++
+    const icon = c.pass ? color.green('✔') : color.red('✖')
+    console.log(`  ${icon} ${c.name.padEnd(22)} ${color.dim(c.detail ?? '')}`)
+  }
+  console.log('')
+  console.log(fail === 0 ? `${color.green(`全部通过 (${checks.length} 项)`)}` : `${color.red(`发现 ${fail} 项异常`)}`)
+  return fail ? 1 : 0
+}
+
+async function checkPorts(ports) {
+  const { createConnection } = await import('node:net')
+  return Promise.all(ports.map(port => new Promise((resolve2) => {
+    const socket = createConnection({ port, host: '127.0.0.1' })
+    let done = false
+    const finish = (busy) => {
+      if (!done) {
+        done = true
+        socket.destroy()
+        resolve2({ port, busy })
+      }
+    }
+    socket.once('connect', () => finish(true))
+    socket.once('error', () => finish(false))
+    setTimeout(() => finish(false), 700)
+  })))
+}

package/cli/commands/home.mjs

@@ -0,0 +1,75 @@
+// ============================================================
+// 指令:home — 查看/初始化 .AgentWorkShop 配置根
+// ------------------------------------------------------------
+// .AgentWorkShop 是配置与数据中枢（类比 Claude Code 的 ~/.claude）：
+//   repo 模式：<检出>/.AgentWorkShop（运行时覆盖/数据/日志/项目级指令）
+//   home 模式：~/.AgentWorkShop（AW_HOME 可重定向;另种子 config.yml/.env/compose）
+// 本指令幂等：缺什么补什么，绝不覆盖已有文件。
+// ============================================================
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { color } from '../core/logger.mjs'
+import { runBootstrap } from '../../scripts/home-bootstrap.mjs'
+
+export const meta = {
+  name: 'home',
+  aliases: ['hw'],
+  group: '配置',
+  summary: '查看/初始化 .AgentWorkShop 配置根（双模式）',
+  usage: 'aw home [--json]',
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  // home 模式引导（幂等）：种子 config.yml/.env/docker-compose 到用户级根
+  const { home: bootHome } = runBootstrap({ quiet: ctx.json })
+  const userRoot = ctx.home
+  const configRoot = ctx.configRoot
+  const isRepo = ctx.mode === 'repo'
+
+  if (ctx.json) {
+    const files = ['runtime-settings.json', 'data']
+    const status = Object.fromEntries(files.map(f => [f, existsSync(join(configRoot, f))]))
+    console.log(JSON.stringify({
+      ok: true,
+      mode: ctx.mode,
+      userRoot,
+      configRoot,
+      files: status,
+      homeBootstrapped: bootHome,
+    }))
+    return 0
+  }
+
+  console.log('')
+  console.log(`${color.bold('.AgentWorkShop 配置根')}  ${color.dim('— 配置与数据中枢(与环境和路径无关)')}`)
+  console.log('')
+  console.log(`  ${color.cyan('运行模式')}   ${isRepo ? color.green('repo') + color.dim(' (项目检出内)') : color.cyan('home') + color.dim(' (全局安装)')}`)
+  console.log(`  ${color.cyan('配置根')}     ${configRoot}`)
+  console.log(`  ${color.cyan('用户级根')}   ${color.dim(userRoot)}${userRoot === configRoot ? color.dim(' (同配置根)') : ''}`)
+  console.log('')
+  console.log(color.bold('  当前生效配置根内容'))
+  const files = [
+    ['runtime-settings.json', '运行时覆盖(aw config set 写入)'],
+    ['data/', '运行数据(sqlite/JSON 仓库/备份)'],
+    ['commands/', isRepo ? '项目级自定义指令(覆盖内建)' : '用户级自定义指令'],
+  ]
+  for (const [f, desc] of files) {
+    const ok = existsSync(join(configRoot, f.replace(/\/$/, '')))
+    const mark = ok ? color.green('✓') : color.yellow('—')
+    console.log(`  ${mark} ${f.padEnd(24)}${color.dim(desc)}`)
+  }
+  if (isRepo) {
+    console.log(`  ${existsSync(join(ctx.root, '.AgentWorkShop', 'prompts')) ? color.green('✓') : color.yellow('—')} prompts/                ${color.dim('Agent 提示词(唯一事实源,随包分发)')}`)
+  }
+  else {
+    console.log(`  ${existsSync(join(userRoot, 'config.yml')) ? color.green('✓') : color.yellow('—')} config.yml              ${color.dim('主配置(工厂默认种子)')}`)
+    console.log(`  ${existsSync(join(userRoot, '.env')) ? color.green('✓') : color.yellow('—')} .env                    ${color.dim('密钥(随机 NUXT_SESSION_PASSWORD)')}`)
+    console.log(`  ${existsSync(join(userRoot, 'docker-compose.yml')) ? color.green('✓') : color.yellow('—')} docker-compose.yml      ${color.dim('数采基础设施自拉起')}`)
+  }
+  console.log('')
+  console.log(color.dim('重定向: 设置环境变量 AW_HOME 即可改变用户级根(默认 ~/.AgentWorkShop)'))
+  console.log(color.dim('层级:   项目级(检出内) > 用户级(~/.AgentWorkShop) > 内建;同名指令/覆盖前者生效'))
+  console.log('')
+  return 0
+}

package/cli/commands/init.mjs

@@ -0,0 +1,150 @@
+// ============================================================
+// 指令:init — 从本包脚手架一个可运行的新 AgentWorkShop 项目
+// ------------------------------------------------------------
+// 复制 app/server/shared/i18n/public/scripts/bin/cli 与全部配置文件，
+// 生成派生的 package.json（名称=目录名，含完整依赖）与 data/runtime-settings.json。
+// 之后: cd <dir> && pnpm install && aw dev
+// ============================================================
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join, resolve, basename } from 'node:path'
+import { color } from '../core/logger.mjs'
+import { CliError } from '../aw.mjs'
+
+export const meta = {
+  name: 'init',
+  aliases: ['create', 'new'],
+  group: '项目',
+  summary: '脚手架一个可运行的新项目（含完整配置系统与 CLI）',
+  usage: 'aw init [dir] [--force] [--no-install] [--silent]',
+  needsProject: false,
+}
+
+const COPY_DIRS = ['app', 'server', 'shared', 'i18n', 'public', 'scripts', 'bin', 'cli']
+const COPY_FILES = [
+  'config.yml',
+  'nuxt.config.ts',
+  'tsconfig.json',
+  'uno.config.ts',
+  'eslint.config.mjs',
+  'commitlint.config.mjs',
+  '.env.example',
+  '.gitignore',
+  '.npmrc',
+  '.editorconfig',
+  'pnpm-workspace.yaml',
+]
+
+/** 排除产物/依赖/缓存目录（不复制） */
+function skipEntry(name) {
+  return name.startsWith('.')
+    || name === 'node_modules'
+    || name === '.nuxt'
+    || name === '.output'
+    || name === '.data'
+    || name === 'dist'
+    || name.endsWith('.log')
+}
+
+function copyDir(src, dst, { depth = 0 } = {}) {
+  mkdirSync(dst, { recursive: true })
+  for (const entry of readdirSync(src)) {
+    if (skipEntry(entry) && depth === 0) continue
+    const s = join(src, entry)
+    const d = join(dst, entry)
+    const st = statSync(s)
+    if (st.isDirectory()) copyDir(s, d, { depth: depth + 1 })
+    else if (st.isFile()) cpSync(s, d)
+  }
+}
+
+/** 派生 package.json：保留依赖，替换项目标识与脚本 */
+function derivePackageJson(ownPkg, name) {
+  const { dependencies, devDependencies, engines, packageManager, type } = ownPkg
+  return {
+    name,
+    version: '0.1.0',
+    private: true,
+    type: type ?? 'module',
+    description: 'AgentWorkShop 项目实例（由 aw init 脚手架生成）',
+    packageManager,
+    engines,
+    scripts: {
+      dev: 'node scripts/dev-guard.mjs dev',
+      build: 'nuxt build',
+      start: 'node scripts/start.mjs',
+      preview: 'nuxt preview',
+      generate: 'nuxt generate',
+      postinstall: 'nuxt prepare',
+      lint: 'eslint .',
+      aw: 'node bin/aw.mjs',
+    },
+    dependencies,
+    devDependencies,
+  }
+}
+
+export async function run(argv, ctx) {
+  const { flags, positionals } = argv
+  const target = positionals[0] ? resolve(ctx.cwd, positionals[0]) : ctx.cwd
+  const force = Boolean(flags.force || flags.f)
+  const silent = Boolean(flags.silent)
+  const skipInstall = Boolean(flags['no-install'])
+
+  if (existsSync(join(target, 'config.yml')) && !force) {
+    throw new CliError('CONFLICT', `目标目录已是项目（存在 config.yml）: ${target}\n如需覆盖请加 --force`)
+  }
+  mkdirSync(target, { recursive: true })
+
+  const src = ctx.packageRoot
+  const log = (msg) => {
+    if (!silent) console.log(msg)
+  }
+
+  log(`${color.cyan('›')} 正在脚手架项目: ${color.bold(target)}`)
+
+  // 1. 源码目录
+  for (const dir of COPY_DIRS) {
+    if (existsSync(join(src, dir))) copyDir(join(src, dir), join(target, dir))
+  }
+  // 2. 配置文件
+  for (const file of COPY_FILES) {
+    if (existsSync(join(src, file))) cpSync(join(src, file), join(target, file))
+  }
+  // 3. 派生 package.json
+  const ownPkg = JSON.parse(readFileSync(join(src, 'package.json'), 'utf8'))
+  const projPkg = derivePackageJson(ownPkg, basename(target).toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'agentworkshop')
+  writeFileSync(join(target, 'package.json'), `${JSON.stringify(projPkg, null, 2)}\n`, 'utf8')
+
+  // 4. 运行时数据与用户指令目录
+  mkdirSync(join(target, 'data'), { recursive: true })
+  writeFileSync(join(target, 'data', 'runtime-settings.json'), `${JSON.stringify({ version: 1, updatedAt: new Date().toISOString(), overrides: {} }, null, 2)}\n`, 'utf8')
+  mkdirSync(join(target, '.AgentWorkShop', 'commands'), { recursive: true })
+  writeFileSync(join(target, '.AgentWorkShop', 'commands', 'README.md'),
+    '# 项目级自定义指令\n\n把导出 `{ meta, run }` 的 .mjs 文件放入本目录即自动注册。\n\n```js\n// 例如 my-tool.mjs\nexport const meta = { name: \'my-tool\', group: \'自定义\', summary: \'我的指令\', usage: \'aw my-tool [--opt]\' }\nexport async function run(argv, ctx) { console.log(\'hello from my-tool\', argv) }\n```\n\n`aw register <path>` 可自动把指令文件复制到此处。\n',
+    'utf8')
+
+  log(`${color.green('✔')} 项目脚手架完成: ${target}`)
+
+  if (skipInstall) {
+    log(`  › 跳过依赖安装，请自行执行: ${color.cyan('pnpm install')}`)
+  }
+  else {
+    log(`${color.cyan('›')} 安装依赖 (pnpm install) ...`)
+    const { spawnSync } = await import('node:child_process')
+    const r = spawnSync('pnpm', ['install', '--reporter=silent'], { cwd: target, stdio: silent ? 'ignore' : 'inherit' })
+    if (r.status !== 0) {
+      log(`${color.yellow('⚠')} 依赖安装未完成(status=${r.status})，可稍后手动在项目目录执行 pnpm install`)
+    }
+    else {
+      log(`${color.green('✔')} 依赖安装完成`)
+    }
+  }
+
+  log('')
+  log('下一步:')
+  log(`  ${color.cyan(`cd ${target}`)}`)
+  log(`  ${color.cyan('aw dev')}         # 启动开发服务器（端口来自 config.yml / 运行时设置）`)
+  log(`  ${color.cyan('aw config list')} # 查看全部可配置项`)
+  log(`  ${color.cyan('aw config set theme.primaryColor #35e0a0')}`)
+  return 0
+}