create-dwy 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # create-dwy
 
+## [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
+
+- 通用基线默认写入所选 AI CLI 的全局入口：Claude Code 使用 `~/.claude/CLAUDE.md`，Codex 使用 `$CODEX_HOME/AGENTS.md`（默认 `~/.codex/AGENTS.md`），OpenCode 使用 `~/.config/opencode/AGENTS.md`。
+- Claude Code、Codex、OpenCode 的所选 Rules 共用项目根 `AGENTS.md` 的托管规则块，项目不再重复注入通用基线。位置选择仅控制 Skills / Hooks；Cursor Rules 始终写入项目。
+- 基线源文件及项目脚手架模板统一使用 `AGENTS.md`，新增新功能开发前的官方／成熟社区工具发现与风险评估规则。
+- 迁移可识别的旧托管基线和 Rules，保留个人内容；全局历史 Rules 不再成为新项目的默认选择，切换 CLI 后取消的共享规则不会重新勾选。
+- 更新确认预览、命令行帮助和接入说明，覆盖全局基线、项目 Rules、旧配置迁移及取消无写入的验证。
+
+---
+
 ## 0.20.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.20.0",
+  "version": "0.22.0",
   "description": "项目脚手架与多平台 AI 配置同步工具",
   "type": "module",
   "bin": {

package/src/cli-help.js

@@ -14,16 +14,19 @@ export function buildHelpText(version) {
     `dwy ${version}`,
     '',
     '用法：',
-    '  dwy            选择 Skills / Rules，再同步到全局或项目',
+    '  dwy            全局更新通用基线，项目注入所选 Rules；Skills / Hooks 可选位置',
     '  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. 选择当前项目或全局，再选择要同步的平台。',
+    '  2. 选择 Skills / Hooks 写入当前项目或全局，再选择平台。',
     '  3. 查看更新、删除项，确认后才写入；取消不写文件。',
+    '  通用基线默认写入所选 CLI 的全局入口；所选 Rules 写入项目根 AGENTS.md。',
     '  Hooks 按平台自动同步，无需选择；Commands 不参与同步。',
     '',
     '交互按键：',
@@ -33,18 +36,25 @@ export function buildHelpText(version) {
     '',
     '常见用法：',
     '  同步当前项目：cd your-project 后执行 dwy，在位置步骤选择「当前项目」。',
-    '  同步全局配置：任意目录执行 dwy，在位置步骤选择「全局」。',
+    '  同步全局 Skills / Hooks：在项目目录执行 dwy，在位置步骤选择「全局」。',
     '  更新或调整配置：再次执行 dwy sync，检查勾选项，再确认同步。',
     '  更新 CLI：dwy upgrade（全局安装时可用；更新后执行 dwy --version 查看版本）。',
+    '  迁移老项目：cd your-project 后执行 dwy migrate，无需重新勾选。',
+    '  手动升级包后：执行一次 dwy refresh，所有已迁移的链接同时生效。',
     '  首次安装：npm install -g create-dwy@latest',
     '',
     '平台支持：',
-    '  Claude Code / Codex：项目或全局的 Skills、Rules、Hooks。',
-    '  OpenCode：项目或全局的 Skills、Rules；当前不支持 Hooks。',
+    '  Claude Code：全局 ~/.claude/CLAUDE.md；项目 Rules 使用根 AGENTS.md。',
+    '  Codex：全局 $CODEX_HOME/AGENTS.md（默认 ~/.codex/AGENTS.md）；项目根 AGENTS.md。',
+    '  OpenCode：全局 ~/.config/opencode/AGENTS.md；项目根 AGENTS.md；当前不支持 Hooks。',
     '  Cursor：仅项目 Rules；全局规则在 Cursor 设置中管理。',
     '',
-    '同步仅处理所选位置和平台；取消已勾选的托管项会在确认后删除。',
-    '更新 CLI 只升级工具；本地配置需再执行 dwy sync 更新。',
+    '同步仅处理所选平台；基线固定全局、Rules 固定项目，位置选择只影响 Skills / Hooks。',
+    '取消已勾选的托管项会在确认后删除，保留手写内容。',
+    'Skills 副本集中在 ~/.dwy/skills；项目和全局使用目录链接，同平台全局入口优先。',
+    '旧真实目录备份到同步根的 .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,182 @@
+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
+}
+
+/**
+ * 将包内 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 }
+}