create-dwy 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # create-dwy
 
+## [0.23.0] - 2026-11-02
+
+### Minor Changes
+
+- 同步改为「范围 → 平台 → 本次处理内容 → 逐项选择 → 清单确认」。默认只选 Skills；项目 Rules、全局通用规范和 Hooks 必须显式选择，未选择的类型及其记录保持原样。全局不提供 Cursor。
+- 默认勾选只读取当前范围及所选平台。项目 Skills 全部适用平台已有有效全局入口时显示“全局已启用”并禁用重复勾选；部分平台覆盖时只为缺少入口的平台安装。
+- 确认页和执行共用操作清单，列出共享副本、入口、旧项清理、配置和同步记录。项目去重只备份或移除项目入口，不改写全局提供者；用户主目录及其别名不能作为项目范围同步。
+- `sync` / `migrate` 只准备缺失或损坏的共享副本，已有内容由 `refresh` / `upgrade` 刷新。产品流程的外部依赖补装也纳入确认清单，只拉取缺失内容并保留已有副本。
+- 全局 Codex Hooks 遵循自定义 `CODEX_HOME`，命令路径正确引用空格和单引号；同步保留个人配置，补充平台兼容、取消无写入和真实终端交互回归。
+
+---
+
+## [0.22.0] - 2026-11-02
+
+### Minor Changes
+
+- Skills 改为用户目录 `.dwy/skills/<name>` 内的一份共享副本，项目和全局入口使用整个目录的软链接；同平台已有有效全局入口时清理项目重复入口。原真实目录先备份，自定义 Skills、Rules 和 Hooks 保留。
+- 新增 `dwy migrate`，在老项目根目录一键迁移已有托管 Skills，无需重新勾选；重复执行不重复备份，已移除的历史模板和已有整个 Skills 根目录链接保留并报告。
+- 新增 `dwy refresh`，使用当前 CLI 包内模板刷新所有已安装的共享副本；`dwy upgrade` 升级成功后自动调用新进程刷新，所有已迁移项目无需分别更新。
+- 共享副本刷新加入互斥及整批失败恢复；扫描和清理统一保护目录链接目标，防止自链和穿透根链接误删文件。全局默认选择覆盖自定义 `CODEX_HOME`。
+- CHANGELOG 规则明确要求每个版本条目包含版本号和日期，禁止 `Unreleased` 等占位标题，与是否发布无关；发布记录提取兼容带日期和方括号的版本标题。
+
+---
+
 ## 0.21.0
 
 ### Minor Changes

package/bin/index.js

@@ -3,7 +3,8 @@
 import { readFileSync } from 'fs'
 import { fileURLToPath } from 'url'
 import { dirname, resolve } from 'path'
-import { runDwy } from '../src/sync-all.js'
+import { runDwy, migrateSkills } from '../src/sync-all.js'
+import { refreshSharedSkills } from '../src/skill-store.js'
 import { selfUpgrade } from '../src/self-upgrade.js'
 import { buildHelpText } from '../src/cli-help.js'
 
@@ -24,14 +25,16 @@ if (wantsHelp(argv)) {
   printHelp()
 } else if (argv.includes('--version') || argv.includes('-V')) {
   console.log(pkg.version)
-} else if (argv[0] === 'upgrade') {
+} else if (['upgrade', 'refresh', 'migrate'].includes(argv[0])) {
   if (argv.length > 1) {
     console.error(`未知命令: dwy ${argv.join(' ')}`)
     printHelp()
     process.exitCode = 1
   } else {
     try {
-      await selfUpgrade()
+      if (argv[0] === 'upgrade') await selfUpgrade()
+      if (argv[0] === 'refresh') await refreshSharedSkills()
+      if (argv[0] === 'migrate') await migrateSkills()
     } catch (error) {
       console.error(error.message)
       process.exitCode = 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dwy",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "项目脚手架与多平台 AI 配置同步工具",
   "type": "module",
   "bin": {

package/src/cli-help.js

@@ -14,29 +14,36 @@ export function buildHelpText(version) {
     `dwy ${version}`,
     '',
     '用法：',
-    '  dwy            全局更新通用基线，项目注入所选 Rules；Skills / Hooks 可选位置',
+    '  dwy            选择范围、平台和处理内容，预览清单后同步',
     '  dwy sync       同上',
-    '  dwy upgrade    把 dwy 升级到 npm 最新正式版',
+    '  dwy upgrade    升级到 npm 最新正式版，并刷新共享 Skills',
+    '  dwy refresh    用当前 CLI 模板刷新已安装的共享 Skills',
+    '  dwy migrate    一键迁移老项目已有的托管 Skills，原目录先备份',
     '  dwy --help     显示本说明',
     '  dwy --version  显示版本',
     '',
     '同步步骤：',
-    '  1. 选择 Skills，再选择 Rules；按分类逐项勾选。',
-    '  2. 选择 Skills / Hooks 写入当前项目或全局，再选择平台。',
-    '  3. 查看更新、删除项，确认后才写入；取消不写文件。',
-    '  通用基线默认写入所选 CLI 的全局入口；所选 Rules 写入项目根 AGENTS.md。',
-    '  Hooks 按平台自动同步，无需选择；Commands 不参与同步。',
+    '  1. 选择同步范围：当前项目或全局。',
+    '  2. 选择该范围支持的平台；全局不提供 Cursor。',
+    '  3. 选择本次处理内容，默认只选 Skills；未选择的类型保持原样。',
+    '     项目：Skills、项目 Rules、Hooks；全局：Skills、全局通用规范、Hooks。',
+    '     内容选项按平台能力过滤。Hooks 选中类型后按平台自动处理。',
+    '  4. 逐项选择 Skills / 项目 Rules；全局通用规范显示摘要。',
+    '  5. 查看写入、备份和清理清单，确认后执行；取消不写文件。',
+    '  Commands 不参与同步。',
     '',
     '交互按键：',
     '  Skills / Rules：←/→ 切分类，↑/↓ 移动，Space 勾选，a 全选／清空当前分类。',
-    '  位置 / 平台：↑/↓ 移动；平台用 Space 勾选，可输入关键字筛选。',
+    '  范围 / 平台 / 内容：↑/↓ 移动；多选用 Space 勾选，可输入关键字筛选。',
     '  Enter 确认当前步骤，Esc 或 Ctrl+C 取消。',
     '',
     '常见用法：',
-    '  同步当前项目：cd your-project 后执行 dwy，在位置步骤选择「当前项目」。',
-    '  同步全局 Skills / Hooks：在项目目录执行 dwy，在位置步骤选择「全局」。',
+    '  同步当前项目：cd your-project 后执行 dwy，选择「当前项目」及本次处理内容。',
+    '  同步全局：执行 dwy，选择「全局」及 Skills、全局通用规范或 Hooks。',
     '  更新或调整配置：再次执行 dwy sync，检查勾选项，再确认同步。',
     '  更新 CLI：dwy upgrade（全局安装时可用；更新后执行 dwy --version 查看版本）。',
+    '  迁移老项目：cd your-project 后执行 dwy migrate，无需重新勾选。',
+    '  手动升级包后：执行一次 dwy refresh，所有已迁移的链接同时生效。',
     '  首次安装：npm install -g create-dwy@latest',
     '',
     '平台支持：',
@@ -45,9 +52,18 @@ export function buildHelpText(version) {
     '  OpenCode：全局 ~/.config/opencode/AGENTS.md；项目根 AGENTS.md；当前不支持 Hooks。',
     '  Cursor：仅项目 Rules；全局规则在 Cursor 设置中管理。',
     '',
-    '同步仅处理所选平台；基线固定全局、Rules 固定项目，位置选择只影响 Skills / Hooks。',
-    '取消已勾选的托管项会在确认后删除，保留手写内容。',
-    '更新 CLI 只升级工具；本地配置需再执行 dwy sync 更新。',
+    '同步仅处理当前范围、所选平台和内容；未选择的类型及其记录保持原样。',
+    '用户主目录不能作为项目范围同步，请选择全局或进入项目目录。',
+    '取消已有勾选会在确认后移除当前范围的托管入口；不勾选整个类型则不处理。',
+    'Skills 副本集中在 ~/.dwy/skills；项目和全局使用目录链接，同平台全局入口优先。',
+    '项目 Skills 全部适用平台均有全局入口时显示「全局已启用」，不能重复勾选。',
+    '部分平台已有全局入口时仍可选，只为缺少全局入口的平台安装项目链接。',
+    '项目同步只清理项目重复入口，不改全局提供者；真实目录先备份。',
+    'sync / migrate 仅准备缺失或损坏副本，不刷新已有共享内容；refresh / upgrade 才刷新。',
+    '产品流程缺失的外部依赖也列入清单，确认后联网补齐，已有内容保留。',
+    '旧真实目录备份到同步根的 .dwy/skill-backups；个人 Skills、Rules、Hooks 不参与 migrate。',
+    '旧项目首次需执行 dwy migrate；迁移后无需逐项目刷新 Skills。',
+    'Rules / Hooks 的模板更新仍需执行 dwy sync；已有会话缓存的 Skill 可能需要重新加载。',
     '',
   ].join('\n')
 }

package/src/self-upgrade.js

@@ -141,6 +141,7 @@ export async function selfUpgrade({
   const latest = await fetchLatest()
   const cmp = compareVersions(current, latest)
   if (cmp === 0) {
+    await runCommand('dwy', ['refresh'])
     console.log(chalk.green(`已是最新正式版 ${current}`))
     return { status: 'up-to-date', current, latest, installer }
   }
@@ -153,6 +154,12 @@ export async function selfUpgrade({
   console.log(chalk.blue(`升级 ${PACKAGE_NAME} ${current} → ${latest}`))
   console.log(chalk.gray(`  ${cmd} ${args.join(' ')}`))
   await runCommand(cmd, args)
+  try {
+    // 必须启动新安装的 CLI；pnpm 升级后旧进程的模块路径仍可能指向旧版本。
+    await runCommand('dwy', ['refresh'])
+  } catch (error) {
+    throw new Error(`CLI 已安装新版本，但共享 Skills 刷新失败：${error.message}`, { cause: error })
+  }
   console.log(chalk.green(`已升级到 ${latest}`))
   return { status: 'upgraded', current, latest, installer }
 }

package/src/skill-store.js

@@ -0,0 +1,197 @@
+import fs from 'fs-extra'
+import os from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { copyFilter, resolveSourceDir, scanSkills } from './sync.js'
+import { chalk } from './utils.js'
+
+function validateName(name) {
+  if (!/^[\p{L}\p{N}_-]+$/u.test(name)) throw new Error(`无效 Skill 名称：${name}`)
+}
+
+async function readInstalledNames(homeDir) {
+  const file = path.join(homeDir, '.dwy', 'skill-store.json')
+  if (!await fs.pathExists(file)) return []
+  const names = await fs.readJson(file)
+  if (!Array.isArray(names) || names.some(name => typeof name !== 'string')) {
+    throw new Error(`共享 Skills 清单格式无效：${file}`)
+  }
+  names.forEach(validateName)
+  return names
+}
+
+/** 仅为缺失或损坏的 Skill 准备共享副本；已有有效内容只登记，不随入口同步刷新。 */
+export async function ensureSharedSkills({ skills, homeDir = os.homedir() }) {
+  const sources = []
+  for (const skill of skills) {
+    validateName(skill.name)
+    const cached = path.join(homeDir, '.dwy', 'skills', skill.name)
+    const stat = await fs.stat(path.join(cached, 'SKILL.md')).catch(error => {
+      if (['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) return null
+      throw error
+    })
+    sources.push(stat?.isFile() ? { ...skill, sourcePath: cached } : skill)
+  }
+  return prepareSharedSkills({ skills: sources, homeDir })
+}
+
+/**
+ * 将包内 Skills 准备到稳定用户目录，返回指向共享副本的条目。
+ * 同一用户的刷新互斥；完整副本准备失败时不替换旧内容。外部 Skills 缓存不纳入本模块清单。
+ */
+export async function prepareSharedSkills({ skills, homeDir = os.homedir() }) {
+  if (skills.length === 0) return []
+  for (const skill of skills) {
+    validateName(skill.name)
+    if (!(await fs.stat(path.join(skill.sourcePath, 'SKILL.md'))).isFile()) {
+      throw new Error(`Skill 缺少有效 SKILL.md：${skill.sourcePath}`)
+    }
+  }
+  const root = path.join(homeDir, '.dwy')
+  const store = path.join(root, 'skills')
+  await fs.ensureDir(store)
+  const lockPath = path.join(root, 'skill-store.lock')
+  let lock
+  try {
+    lock = await fs.open(lockPath, 'wx')
+  } catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`另一个进程正在刷新 Skills；若前次异常退出，请移除 ${lockPath} 后重试`)
+    throw error
+  }
+  let staging
+  let preserveStaging = false
+  try {
+    staging = await fs.mkdtemp(path.join(root, '.skills-'))
+    const installed = new Set(await readInstalledNames(homeDir))
+    const prepared = []
+    const replacements = []
+    for (const skill of skills) {
+      const dest = path.join(store, skill.name)
+      const next = path.join(staging, skill.name)
+      if (path.resolve(skill.sourcePath) !== path.resolve(dest)) {
+        await fs.copy(skill.sourcePath, next, { dereference: true, filter: copyFilter(skill.sourcePath) })
+        replacements.push({ dest, next, old: path.join(staging, `${skill.name}.old`), saved: false, replaced: false })
+      }
+      installed.add(skill.name)
+      prepared.push({ ...skill, sourcePath: dest })
+    }
+    const manifest = path.join(staging, 'skill-store.json')
+    await fs.writeJson(manifest, [...installed].sort(), { spaces: 2 })
+    try {
+      for (const entry of replacements) {
+        const existing = await fs.lstat(entry.dest).catch(error => {
+          if (error.code === 'ENOENT') return null
+          throw error
+        })
+        if (existing) {
+          await fs.rename(entry.dest, entry.old)
+          entry.saved = true
+        }
+        await fs.rename(entry.next, entry.dest)
+        entry.replaced = true
+      }
+      await fs.rename(manifest, path.join(root, 'skill-store.json'))
+    } catch (error) {
+      const errors = [error]
+      for (const entry of [...replacements].reverse()) {
+        try {
+          if (entry.replaced) await fs.remove(entry.dest)
+          if (entry.saved) await fs.rename(entry.old, entry.dest)
+        } catch (restoreError) {
+          errors.push(restoreError)
+        }
+      }
+      if (errors.length > 1) {
+        preserveStaging = true
+        throw new AggregateError(errors, `刷新失败且自动恢复未完成，旧副本保留在 ${staging}`)
+      }
+      throw error
+    }
+    return prepared
+  } finally {
+    try {
+      if (staging && !preserveStaging) await fs.remove(staging)
+    } finally {
+      await fs.close(lock)
+      await fs.remove(lockPath)
+    }
+  }
+}
+
+async function entryParent(dest, backupRoot) {
+  const parent = await fs.realpath(path.dirname(dest))
+  const boundary = path.resolve(backupRoot, '..', '..')
+  const realBoundary = await fs.realpath(boundary)
+  const expected = path.join(realBoundary, path.relative(boundary, path.dirname(dest)))
+  if (parent !== expected) throw new Error(`Skills 根目录链接指向外部位置，保留原入口，不修改目标：${path.dirname(dest)}`)
+  return parent
+}
+
+/**
+ * 清理托管入口：真实目录移到备份根，软链接仅移除入口，不遍历其目标。
+ * 返回真实目录的备份路径；入口不存在或原为链接时返回 null。
+ */
+export async function removeSkillEntry({ dest, backupRoot }) {
+  const stat = await fs.lstat(dest).catch(error => {
+    if (error.code === 'ENOENT') return null
+    throw error
+  })
+  if (!stat) return null
+  await entryParent(dest, backupRoot)
+  if (stat.isSymbolicLink()) {
+    await fs.unlink(dest)
+    return null
+  }
+  await fs.ensureDir(backupRoot)
+  const backup = path.join(backupRoot, `${path.basename(dest)}-${randomUUID()}`)
+  await fs.rename(dest, backup)
+  console.log(chalk.gray(`已备份 ${dest} → ${backup}`))
+  return backup
+}
+
+/** 将整个 Skill 目录链接到共享副本；原真实目录先备份，链接失败时恢复原入口。 */
+export async function linkSkill({ skill, dest, backupRoot }) {
+  if (!(await fs.stat(path.join(skill.sourcePath, 'SKILL.md'))).isFile()) {
+    throw new Error(`Skill 缺少有效 SKILL.md：${skill.sourcePath}`)
+  }
+  await fs.ensureDir(path.dirname(dest))
+  const actualParent = await fs.realpath(path.dirname(dest))
+  // 整个全局 skills 根可能已链接到共享目录；此时入口就是源目录，不能把它再改为自链。
+  if (path.join(actualParent, path.basename(dest)) === await fs.realpath(skill.sourcePath)) return null
+  await entryParent(dest, backupRoot)
+  const stat = await fs.lstat(dest).catch(error => {
+    if (error.code === 'ENOENT') return null
+    throw error
+  })
+  const previousLink = stat?.isSymbolicLink() ? await fs.readlink(dest) : null
+  if (previousLink && path.resolve(path.dirname(dest), previousLink) === path.resolve(skill.sourcePath)) return null
+  const temporary = path.join(path.dirname(dest), `.${path.basename(dest)}.link-${randomUUID()}`)
+  await fs.symlink(path.resolve(skill.sourcePath), temporary, process.platform === 'win32' ? 'junction' : 'dir')
+  let backup
+  try {
+    backup = await removeSkillEntry({ dest, backupRoot })
+    try {
+      await fs.rename(temporary, dest)
+    } catch (error) {
+      if (backup) await fs.rename(backup, dest)
+      else if (previousLink) await fs.symlink(previousLink, dest, process.platform === 'win32' ? 'junction' : 'dir')
+      throw error
+    }
+    return backup
+  } finally {
+    await fs.remove(temporary)
+  }
+}
+
+/** 使用当前 CLI 包内模板刷新已有共享副本；新包移除的条目保留，避免其他项目坏链。 */
+export async function refreshSharedSkills({ sourceDir, homeDir = os.homedir() } = {}) {
+  const names = await readInstalledNames(homeDir)
+  const scans = await scanSkills(sourceDir || await resolveSourceDir())
+  const available = new Map(scans.map(skill => [skill.name, skill]))
+  const updated = names.filter(name => available.has(name))
+  const retained = names.filter(name => !available.has(name))
+  await prepareSharedSkills({ skills: updated.map(name => available.get(name)), homeDir })
+  for (const name of retained) console.log(chalk.yellow(`当前 CLI 已移除 ${name}，保留共享旧副本以免其他项目链接失效。`))
+  console.log(chalk.green(`已刷新 ${updated.length} 个共享 Skills，保留 ${retained.length} 个旧副本。`))
+  return { updated, retained }
+}

package/src/skills-install.js

@@ -71,24 +71,54 @@ async function shallowCloneTag(repoUrl, tag, destDir) {
   await runGit(['clone', '--depth', '1', '--branch', tag, repoUrl, destDir])
 }
 
-// 安装/更新全部外部 skill 到 ~/.dwy/skills/。再次运行即覆盖式更新。
-export async function installSkills() {
-  const targetDir = getGlobalSkillsDir()
-  await fs.ensureDir(targetDir)
+async function validExternalSkill(dest) {
+  const stat = await fs.stat(path.join(dest, 'SKILL.md')).catch(error => {
+    if (['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) return null
+    throw error
+  })
+  return Boolean(stat?.isFile())
+}
 
-  const tmpRoot = path.join(os.tmpdir(), `dwy-skills-${process.pid}`)
-  await fs.ensureDir(tmpRoot)
+async function missingExternalSources(targetDir) {
+  const sources = []
+  for (const [name, source] of Object.entries(SKILL_SOURCES)) {
+    const skills = {}
+    for (const [skill, repoPath] of Object.entries(source.skills)) {
+      if (!await validExternalSkill(path.join(targetDir, skill))) skills[skill] = repoPath
+    }
+    if (Object.keys(skills).length) sources.push([name, { ...source, skills }])
+  }
+  return sources
+}
 
-  const versions = {}
+/** 只读列出产品流程缺失的外部依赖；确认后再联网补齐，已有副本不刷新。 */
+export async function planMissingExternalSkills(targetDir) {
+  const sources = await missingExternalSources(targetDir)
+  const paths = sources.flatMap(([, source]) => Object.keys(source.skills).map(name => path.join(targetDir, name)))
+  for (const [, source] of sources) {
+    const license = path.join(targetDir, source.licenseDest)
+    if (!await fs.pathExists(license)) paths.push(license)
+  }
+  if (sources.length) paths.push(path.join(targetDir, 'VERSIONS.json'))
+  return { paths, run: () => installSkillSources(sources, targetDir, true) }
+}
+
+async function installSkillSources(sources, targetDir, missingOnly) {
+  if (sources.length === 0) return
+  const versionsFile = path.join(targetDir, 'VERSIONS.json')
+  const previous = missingOnly && await fs.pathExists(versionsFile) ? await fs.readJson(versionsFile) : {}
+  const versions = { ...previous.versions }
+  await fs.ensureDir(targetDir)
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'dwy-skills-'))
   try {
-    for (const [sourceName, src] of Object.entries(SKILL_SOURCES)) {
+    for (const [sourceName, src] of sources) {
       console.log(chalk.gray(`拉取 ${sourceName} @ ${src.tag} ...`))
       const repoDir = path.join(tmpRoot, sourceName)
       await shallowCloneTag(src.repo, src.tag, repoDir)
 
       // 搬 LICENSE（MIT 要求保留原版权声明）
       const licenseSrc = path.join(repoDir, src.licenseFile)
-      if (await fs.pathExists(licenseSrc)) {
+      if (await fs.pathExists(licenseSrc) && (!missingOnly || !await fs.pathExists(path.join(targetDir, src.licenseDest)))) {
         await fs.copy(licenseSrc, path.join(targetDir, src.licenseDest), { overwrite: true })
       }
 
@@ -96,6 +126,7 @@ export async function installSkills() {
       for (const [skillName, repoPath] of Object.entries(src.skills)) {
         const from = path.join(repoDir, repoPath)
         const to = path.join(targetDir, skillName)
+        if (missingOnly && await validExternalSkill(to)) continue
         if (!await fs.pathExists(from)) {
           throw new Error(`${sourceName} @ ${src.tag} 内未找到 ${repoPath}（仓库结构可能变了）`)
         }
@@ -109,8 +140,8 @@ export async function installSkills() {
     // 写版本清单 + 清单指纹，供查看与后续更新比对。
     // manifest_hash 变化（cli 加了 skill / 改了 tag）→ 下次 ensureSkillsInstalled 触发重装。
     await fs.writeJson(
-      path.join(targetDir, 'VERSIONS.json'),
-      { manifest_hash: computeManifestHash(), versions },
+      versionsFile,
+      { manifest_hash: missingOnly ? previous.manifest_hash : computeManifestHash(), versions },
       { spaces: 2 },
     )
     console.log(chalk.green(`\n✓ 外部 skill 已安装到 ${targetDir}`))
@@ -119,6 +150,11 @@ export async function installSkills() {
   }
 }
 
+/** 兼容显式安装调用：更新固定清单中的全部外部 Skills。 */
+export async function installSkills() {
+  return installSkillSources(Object.entries(SKILL_SOURCES), getGlobalSkillsDir(), false)
+}
+
 // 全局 skill 是否已就绪（VERSIONS.json 存在）。
 export async function skillsInstalled() {
   return fs.pathExists(path.join(getGlobalSkillsDir(), 'VERSIONS.json'))