agentworkshop 0.2.1

package/cli/commands/register.mjs

@@ -0,0 +1,123 @@
+// ============================================================
+// 指令:register — 注册一条新指令（指令系统可扩展性的入口）
+// ------------------------------------------------------------
+// 注册目标：
+//   - 项目级（默认）:        <projectRoot>/.agentworkshop/commands/
+//   - 用户级（--global/-g）: ~/.agentworkshop/commands/
+// 注册来源 spec：
+//   - 本地文件路径（.mjs）或目录（含多个 .mjs）
+//   - URL（https://.../xxx.mjs）
+//   - npm:包名（生成包装模块，动态引入包内导出的 { meta, run }）
+// 注册即复制文件到扫描目录 → 下次启动自动发现（无需任何登记清单）。
+// ============================================================
+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'
+
+export const meta = {
+  name: 'register',
+  aliases: ['reg', 'install-cmd'],
+  group: '指令',
+  summary: '注册一条新指令（项目级或用户级）',
+  usage: 'aw register <path|url|npm:pkg> [--name <n>] [--global|-g] [--force]',
+  description: [
+    '指令文件只需导出 { meta, run }：',
+    '  export const meta = { name, summary, usage, group, aliases?, needsProject? }',
+    '  export async function run(argv, ctx) { /* argv={flags,positionals}, ctx=运行上下文 */ }',
+    '生效：注册后重启任意 aw 进程即自动发现（无集中登记清单，约定优于配置）。',
+  ],
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  const { flags, positionals } = argv
+  const spec = positionals[0]
+  if (!spec) throw new CliError('USAGE', '用法: aw register <path|url|npm:pkg> [--name <n>] [--global|-g]')
+
+  const global = Boolean(flags.global ?? flags.g)
+  const force = Boolean(flags.force ?? flags.f)
+  const targetDir = global ? ctx.commandsDir.global : ctx.commandsDir.local
+  if (!targetDir) {
+    throw new CliError('NO_PROJECT', '未检测到项目上下文。请 cd 到项目目录注册项目级指令，或加 --global 注册到用户级（AW Home/commands,默认 ~/.AgentWorkShop/commands）。')
+  }
+  mkdirSync(targetDir, { recursive: true })
+  if (!existsSync(join(targetDir, 'README.md'))) {
+    writeFileSync(join(targetDir, 'README.md'), '# 自定义指令目录\n\n导出 { meta, run } 的 .mjs 文件放入本目录即自动注册。\n', 'utf8')
+  }
+
+  const nameOverride = flags.name ? String(flags.name).replace(/\.(mjs|js)$/, '') : undefined
+  const scope = global ? `用户级 (${ctx.commandsDir.global})` : `项目级 (${targetDir})`
+  let written = []
+
+  console.log(`${color.cyan('›')} 注册到${scope}`)
+
+  if (/^https?:\/\//.test(spec)) {
+    written = [await fromUrl(spec, nameOverride, targetDir, force)]
+  }
+  else if (spec.startsWith('npm:')) {
+    written = [await fromNpm(spec.slice(4), nameOverride, targetDir, force)]
+  }
+  else {
+    const srcPath = resolve(ctx.cwd, spec)
+    if (!existsSync(srcPath)) throw new CliError('NOT_FOUND', `路径不存在: ${srcPath}`)
+    const st = statSync(srcPath)
+    if (st.isDirectory()) {
+      const files = readdirSync(srcPath).filter(f => /\.(mjs|js|cjs)$/.test(f))
+      if (!files.length) throw new CliError('NOT_FOUND', `目录中没有 .mjs 指令文件: ${srcPath}`)
+      for (const f of files) written.push(fromFile(join(srcPath, f), nameOverride, targetDir, force))
+    }
+    else {
+      written.push(fromFile(srcPath, nameOverride, targetDir, force))
+    }
+  }
+
+  for (const w of written) {
+    if (w.skipped) console.log(`${color.yellow('⚠')} 跳过(已存在): ${basename(w.name)}  (加 --force 覆盖)`)
+    else if (w.name) console.log(`${color.green('✔')} 已注册: ${color.bold(w.name)}  →  ${w.dest}`)
+  }
+
+  console.log(`  › 立刻可用: ${color.cyan(`aw ${nameOf(written[0]?.name)} --help`)}`)
+  console.log(`  › 查看全部: ${color.cyan('aw help')}`)
+  return 0
+}
+
+function nameOf(file) {
+  return basename(file ?? '').replace(/\.(mjs|js|cjs)$/, '')
+}
+
+function fromFile(srcPath, nameOverride, targetDir, force) {
+  const base = nameOverride ?? basename(srcPath).replace(/\.(mjs|js|cjs)$/, '')
+  const dest = join(targetDir, `${base}.mjs`)
+  if (existsSync(dest) && !force) return { name: `${base}.mjs`, dest, skipped: true }
+  copyFileSync(srcPath, dest)
+  return { name: `${base}.mjs`, dest, skipped: false }
+}
+
+async function fromUrl(url, nameOverride, targetDir, force) {
+  const base = nameOverride ?? (basename(new URL(url).pathname).replace(/\.(mjs|js|cjs)$/, '') || 'command')
+  const dest = join(targetDir, `${base}.mjs`)
+  if (existsSync(dest) && !force) return { name: `${base}.mjs`, dest, skipped: true }
+  const res = await fetch(url)
+  if (!res.ok) throw new CliError('FETCH_FAILED', `下载失败: HTTP ${res.status} ${url}`)
+  const text = await res.text()
+  const bom = text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text
+  writeFileSync(dest, bom, 'utf8')
+  return { name: `${base}.mjs`, dest, skipped: false }
+}
+
+async function fromNpm(pkg, nameOverride, targetDir, force) {
+  const base = nameOverride ?? (pkg.replace(/^@[^/]+\//, '').replace(/[^a-z0-9-]/g, '-') || 'command')
+  const dest = join(targetDir, `${base}.mjs`)
+  if (existsSync(dest) && !force) return { name: `${base}.mjs`, dest, skipped: true }
+  // 包装模块：兼容 default export 与命名导出 { meta, run }
+  const wrapper = `// 由 \`aw register npm:${pkg}\` 生成 — 包装 npm 包为 aw 指令\n`
+    + `import mod from '${pkg}'\n`
+    + `import * as ns from '${pkg}'\n`
+    + `const m = (typeof mod === 'object' && mod !== null && mod.meta) ? mod : null\n`
+    + `export const meta = m?.meta ?? ns?.meta\n`
+    + `export const run = m?.run ?? ns?.run\n`
+    + `export default { meta, run }\n`
+  writeFileSync(dest, wrapper, 'utf8')
+  return { name: `${base}.mjs`, dest, skipped: false }
+}

package/cli/commands/start.mjs

@@ -0,0 +1,106 @@
+// ============================================================
+// 指令:start — 以配置驱动的方式启动生产服务
+// ------------------------------------------------------------
+// 两种模式（自动判定,见 shared/config/home.mjs）：
+//   repo 模式：在项目检出内 → 与 `pnpm start` 同链路,配置/数据在项目根
+//   home 模式：全局安装后任意目录 → 跑本包应用载荷,cwd=AW Home,
+//              配置/数据/日志全部落在 ~/.AgentWorkShop(路径无关)
+// home 模式首启若无构建产物会自动构建一次(需依赖已安装)。
+// 子进程统一注入 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, preloadDotEnv } from '../core/context.mjs'
+import { runBootstrap } from '../../scripts/home-bootstrap.mjs'
+
+export const meta = {
+  name: 'start',
+  aliases: ['s', 'prod', 'preview'],
+  group: '运行',
+  summary: '一键启动生产服务（配置驱动端口,项目检出内外皆可）',
+  usage: 'aw start [--port <n>] [--host <h>]',
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  const { flags } = argv
+  const isRepo = Boolean(ctx.root)
+  const appRoot = isRepo ? ctx.root : ctx.packageRoot
+  const cwd = isRepo ? ctx.root : ctx.home
+  const envExtra = {}
+
+  // home 模式:确保 AW Home 就绪(幂等;postinstall 被跳过时兜底)
+  if (!isRepo) runBootstrap({ quiet: true })
+
+  // ---- 构建产物检查（home 模式缺产物则先构建一次） ----
+  const outputEntry = join(appRoot, '.output', 'server', 'index.mjs')
+  if (!existsSync(outputEntry)) {
+    const nuxtBin = ctx.resolveNuxtBin()
+    if (!nuxtBin) {
+      console.log(`${color.red('✖')} 未找到生产构建且解析不到 nuxt CLI(依赖未安装?)`)
+      console.log(`  › 请先执行 ${color.cyan('aw build')} 或在应用目录执行 pnpm install`)
+      return 1
+    }
+    console.log(`${color.cyan('›')} 首次启动:正在构建生产产物(约 2-5 分钟,仅一次) ...`)
+    const buildCode = await new Promise((resolve2) => {
+      const c = spawn(process.execPath, [nuxtBin, 'build'], { cwd: appRoot, stdio: 'inherit', env: localBypassEnv() })
+      c.on('close', code => resolve2(code ?? 1))
+      c.on('error', () => resolve2(1))
+    })
+    if (buildCode !== 0 || !existsSync(outputEntry)) {
+      console.log(`${color.red('✖')} 构建失败(exit=${buildCode})`)
+      return 1
+    }
+  }
+
+  // ---- 端口/主机解析（配置引擎:config.yml < runtime-settings < env < CLI） ----
+  const eff = ctx.config.load()
+  const port = flags.port !== undefined ? Number(flags.port) : Number(eff.effective['server.prod.port'])
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.log(`${color.red('✖')} 无效端口: ${flags.port ?? eff.effective['server.prod.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.prod.port']
+
+  // ---- 密钥预载（repo: 项目 .env;home: AW Home/.env —— 引导时已生成随机密钥） ----
+  preloadDotEnv(cwd)
+
+  // home 模式:把 AW_HOME/AW_MODE 传给应用与构建子进程
+  // (cwd=home 数据自然落盘;AW_MODE=home 防止包目录被误判为项目检出)
+  // prompts 是应用资产(随包升级),注入 AW_PROMPTS_DIR 指向包内唯一事实源
+  if (!isRepo) {
+    envExtra.AW_HOME = ctx.home
+    envExtra.AW_MODE = 'home'
+    envExtra.AW_PROMPTS_DIR = join(appRoot, '.AgentWorkShop', 'prompts')
+  }
+  // HOST 环境变量被 scripts/start.mjs 以最高优先读取(CLI 显式 --host 等效)
+  if (flags.host !== undefined) envExtra.HOST = host
+
+  console.log(`${color.cyan('›')} 生产服务(${isRepo ? 'repo' : 'home'} 模式) -> http://${host}:${port}  ${color.dim(`(端口来源: ${portSource})`)}`)
+  console.log(`${color.cyan('›')} ${color.dim(`配置: ${ctx.configPath} · 数据: ${ctx.dataDir}`)}`)
+  console.log(`${color.cyan('›')} 停止: Ctrl+C`)
+
+  const launcher = join(appRoot, 'scripts', 'start.mjs')
+  const args = existsSync(launcher) ? [launcher] : [outputEntry]
+  if (flags.port !== undefined) args.push('--port', String(port))
+
+  const child = spawn(process.execPath, args, {
+    cwd,
+    stdio: 'inherit',
+    env: localBypassEnv(envExtra),
+  })
+  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('✖')} start 进程启动失败: ${err.message}`)
+      resolve2(1)
+    })
+  })
+}

package/cli/commands/status.mjs

@@ -0,0 +1,67 @@
+// ============================================================
+// 指令:status — 项目运行态总览（配置源 / 服务健康 / 指令表）
+// ============================================================
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { color } from '../core/logger.mjs'
+import { findRunningServer } from '../core/context.mjs'
+
+export const meta = {
+  name: 'status',
+  aliases: ['st', 'info'],
+  group: '诊断',
+  summary: '项目运行态总览（模式 / 配置源 / 服务健康 / 指令表）',
+  usage: 'aw status [--json]',
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  const { config } = ctx
+  const { effective, sources } = config.load()
+
+  const server = await findRunningServer(config, { timeoutMs: 600 })
+
+  const runtimeOverrides = Object.fromEntries(
+    Object.entries(ctx.config.load().overrides).map(([k, v]) => [k, v]),
+  )
+
+  const commands = ctx.registry.list().map(c => ({
+    name: c.meta.name,
+    group: c.meta.group,
+    aliases: c.meta.aliases ?? [],
+    source: typeof c.source === 'string' && c.source.includes(join('cli', 'commands')) ? 'builtin' : c.source,
+  }))
+
+  if (ctx.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      mode: ctx.mode,
+      root: ctx.root,
+      home: ctx.home,
+      package: { version: (await import('../aw.mjs')).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')) },
+      commands,
+    }, null, 2))
+    return 0
+  }
+
+  console.log('')
+  console.log(`${color.bold('运行状态')}  ${color.dim(`${ctx.mode} 模式 · ${ctx.root ?? ctx.home}`)}`)
+  console.log('')
+  console.log(`  ${color.cyan('运行中服务')}   ${server ? color.green(`在线 · ${server.port} 端口 /api/system/config 响应`) : color.yellow('离线（无 dev/prod 服务在跑）')}`)
+  console.log(`  ${color.cyan('配置中枢')}     ${ctx.configPath}`)
+  console.log(`  ${color.cyan('生产构建')}     ${(ctx.root ?? ctx.packageRoot) && existsSync(join(ctx.root ?? ctx.packageRoot, '.output', 'server', 'index.mjs')) ? color.green('存在 (.output/)') : color.yellow('缺失（aw build 后可用 aw start）')}`)
+  console.log(`  ${color.cyan('运行时覆盖')}   ${Object.keys(runtimeOverrides).length ? Object.keys(runtimeOverrides).join(', ') : color.dim('无（全部为 config.yml/env 决定）')}`)
+  console.log(`  ${color.cyan('指令')}         ${commands.length} 条（内建 + 用户 + 项目）`)
+  console.log('')
+  console.log(color.bold('有效配置（关键项）'))
+  for (const key of ['server.host', 'server.dev.port', 'server.prod.port', 'theme.primaryColor', 'theme.mode', 'api.timeout']) {
+    const src = sources[key] === 'env' ? color.yellow(sources[key]) : sources[key] === 'runtime' ? color.green(sources[key]) : color.dim(sources[key])
+    console.log(`  ${key.padEnd(24)} = ${String(effective[key]).padEnd(14)} ${src}`)
+  }
+  console.log('')
+  console.log(color.dim('查看全部设置: aw config list · 服务细分: aw doctor'))
+  return 0
+}

package/cli/commands/update.mjs

@@ -0,0 +1,116 @@
+// ============================================================
+// 指令:update — 检查 npm 远程最新版本并就地更新全局 aw
+// ------------------------------------------------------------
+// 流程:本地版本(packageVersion) → npm view <pkg> version(尊重用户
+// registry 配置,--registry 可覆盖) → semver 比较 → 有新版则
+// npm install -g <pkg>@latest → npm ls 复核安装版本。
+// 提示:npmmirror 等镜像同步官方源有分钟级延迟,查最新版可加
+//   --registry https://registry.npmjs.org
+// ============================================================
+import { spawnSync } from 'node:child_process'
+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'
+
+export const meta = {
+  name: 'update',
+  aliases: ['upgrade'],
+  group: '其他',
+  summary: '检查 npm 远程最新版本,有新版则就地更新',
+  usage: 'aw update [--check] [--registry <url>] [--yes]',
+  description: [
+    '对比当前版本与 npm registry 上的 latest;有新版则 npm install -g 全局更新并复核。',
+    '镜像同步延迟时可加 --registry https://registry.npmjs.org 直查官方源。',
+  ],
+  needsProject: false,
+}
+
+const npmBin = () => 'npm'
+
+/** spawnSync npm;Windows 上 .cmd 必须经 shell(CVE-2024-27980 后无 shell 直接 spawn .cmd 报 EINVAL) */
+function npmRun(args, { registry, inherit = false } = {}) {
+  return spawnSync(npmBin(), registry ? [...args, '--registry', registry] : args, {
+    encoding: 'utf8',
+    stdio: inherit ? 'inherit' : 'pipe',
+    shell: process.platform === 'win32',
+  })
+}
+
+/** 读取包名(全局安装副本/仓库检出都成立;读不到回退 agentworkshop) */
+function pkgName(ctx) {
+  try {
+    const p = join(ctx.packageRoot, 'package.json')
+    if (existsSync(p)) return JSON.parse(readFileSync(p, 'utf8')).name || 'agentworkshop'
+  }
+  catch { /* 回退 */ }
+  return 'agentworkshop'
+}
+
+/** semver 比较:1 = a 更新,-1 = b 更新,0 相同(忽略 prerelease 后缀) */
+function cmpVersions(a, b) {
+  const pa = String(a).split('-')[0].split('.').map(n => Number.parseInt(n, 10) || 0)
+  const pb = String(b).split('-')[0].split('.').map(n => Number.parseInt(n, 10) || 0)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return 1
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return -1
+  }
+  return 0
+}
+
+export async function run(argv, ctx) {
+  const { flags } = argv
+  const registry = flags.registry ? String(flags.registry) : undefined
+  const name = pkgName(ctx)
+  const current = packageVersion()
+
+  console.log(`${color.cyan('›')} 当前版本: ${color.bold(`v${current}`)}`)
+  console.log(`${color.cyan('›')} 查询 npm registry${registry ? ` (${registry})` : ''} ...`)
+
+  const view = npmRun(['view', name, 'version'], { registry })
+  if (view.error || view.status !== 0) {
+    const detail = (view.stderr ?? view.stdout ?? view.error?.message ?? '').trim().split(/\r?\n/).filter(Boolean).pop() ?? 'unknown error'
+    throw new CliError('REGISTRY', `无法从 npm 获取 ${name} 的最新版本:\n  ${detail}\n提示: 镜像同步有延迟,可加 --registry https://registry.npmjs.org 直查官方源`)
+  }
+  const latest = (view.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop()?.trim()
+  if (!latest) throw new CliError('REGISTRY', 'npm view 返回为空')
+
+  console.log(`${color.cyan('›')} 远端最新: ${color.bold(`v${latest}`)}`)
+
+  if (cmpVersions(latest, current) <= 0) {
+    console.log(`${color.green('✔')} 已是最新版本 (${current})`)
+    return 0
+  }
+  console.log(`${color.yellow('⚠')} 发现新版本: ${color.dim(current)} → ${color.bold(latest)}`)
+
+  if (flags.check) {
+    console.log(`${color.dim('›')} (--check 仅检查;去掉该参数运行 aw update 即可更新)`)
+    return 0
+  }
+
+  if (!flags.yes && !flags.y && process.stdin.isTTY) {
+    const { createInterface } = await import('node:readline')
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const answer = await new Promise(resolve => rl.question('立即更新? (Y/n) ', resolve))
+    rl.close()
+    if (/^n/i.test(answer.trim())) {
+      console.log('已取消')
+      return 0
+    }
+  }
+
+  console.log(`${color.cyan('›')} npm install -g ${name}@latest ...`)
+  const inst = npmRun(['install', '-g', `${name}@latest`], { registry, inherit: true })
+  if (inst.status !== 0) {
+    throw new CliError('UPDATE_FAILED', `更新失败 (npm exit ${inst.status ?? '?'})——可手动执行: npm install -g ${name}@latest`)
+  }
+
+  // 复核:从全局包清单读回实际安装版本
+  const ls = npmRun(['ls', '-g', '--depth=0', name], { registry })
+  const installed = new RegExp(`${name}@(\\S+)`).exec(ls.stdout ?? '')?.[1]
+  if (installed) console.log(`${color.green('✔')} 更新完成: ${color.dim(current)} → ${color.bold(installed)}`)
+  else console.log(`${color.green('✔')} 更新完成 → ${color.bold(latest)}`)
+  console.log(`${color.dim('›')} 新开 aw 进程即运行新版本(当前进程仍是旧代码)`)
+  return 0
+}

package/cli/commands/version.mjs

@@ -0,0 +1,32 @@
+// ============================================================
+// 指令:version — 版本信息
+// ============================================================
+import { color } from '../core/logger.mjs'
+import { packageVersion } from '../aw.mjs'
+
+export const meta = {
+  name: 'version',
+  aliases: ['v'],
+  group: '其他',
+  summary: '显示版本信息',
+  usage: 'aw version',
+  needsProject: false,
+}
+
+export async function run(argv, ctx) {
+  const version = packageVersion()
+  if (ctx.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      name: 'agentworkshop',
+      version,
+      node: process.version,
+      project: ctx.root ?? null,
+    }))
+    return 0
+  }
+  console.log(`${color.bold('agentworkshop')} ${version}`)
+  console.log(`  node ${process.version} · ${ctx.root ? `项目: ${ctx.root}` : '未在项目中'}`)
+  console.log(`  ${color.dim('配置: config.yml < data/runtime-settings.json < env')}`)
+  return 0
+}

package/cli/core/args.mjs

@@ -0,0 +1,95 @@
+// ============================================================
+// AgentWorkShop CLI — 极简 argv 解析器
+// 支持：
+//   --flag            → 布尔 true
+//   --flag=value      → 值
+//   --flag value      → 值（下一 token 非选项时）
+//   -x value / -x     → 短选项（映射到长名）
+//   --                 → 之后全部为位置参数
+// ============================================================
+
+/** 解析 argv（不含 node/script 前两项）。返回 { flags, positionals } */
+export function parseArgs(argv, { shortMap = {} } = {}) {
+  const flags = {}
+  const positionals = []
+  const unknown = []
+
+  let i = 0
+  let afterDoubleDash = false
+  while (i < argv.length) {
+    const tok = argv[i]
+    if (afterDoubleDash) {
+      positionals.push(tok)
+      i++
+      continue
+    }
+    if (tok === '--') {
+      afterDoubleDash = true
+      i++
+      continue
+    }
+
+    if (tok.startsWith('--')) {
+      let name = tok.slice(2)
+      let value = undefined
+      const eq = name.indexOf('=')
+      if (eq >= 0) {
+        value = name.slice(eq + 1)
+        name = name.slice(0, eq)
+      }
+      if (value === undefined) {
+        const next = argv[i + 1]
+        if (next !== undefined && !next.startsWith('--') && !next.startsWith('-') && next !== '') {
+          value = next
+          i++
+        }
+        else {
+          value = true
+        }
+      }
+      flags[name] = value
+      i++
+      continue
+    }
+
+    if (tok.startsWith('-') && tok.length > 1) {
+      const short = tok.slice(1)
+      if (shortMap[short]) {
+        const name = shortMap[short]
+        let value
+        const next = argv[i + 1]
+        if (next !== undefined && !next.startsWith('-')) {
+          value = next
+          i++
+        }
+        else {
+          value = true
+        }
+        flags[name] = value
+        i++
+        continue
+      }
+      unknown.push(tok)
+      i++
+      continue
+    }
+
+    positionals.push(tok)
+    i++
+  }
+
+  return { flags, positionals, unknown }
+}
+
+/** 便捷：读取 flags 中的值或默认 */
+export function flagValue(flags, name, fallback) {
+  return flags[name] === undefined ? fallback : flags[name]
+}
+
+export function isTruthy(value) {
+  if (typeof value === 'boolean') return value
+  if (value === undefined || value === null) return false
+  return !/^(0|false|no|off|)$/i.test(String(value))
+}
+
+export default parseArgs