create-dwy 0.6.2 → 0.6.4

package/bin/index.js

@@ -27,7 +27,7 @@ program
 
 program
   .command('sync-claude-md')
-  .description('单独同步 CLAUDE.md 到当前目录的 .claude/')
+  .description('单独同步 CLAUDE.md 到全局 ~/.claude/')
   .action(syncProjectClaudeMd)
 
 program.parse()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dwy",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "项目脚手架与 Claude Code 配置同步工具",
   "type": "module",
   "bin": {

package/src/sync.js

@@ -205,6 +205,22 @@ export async function syncClaude() {
     process.exit(1)
   }
 
+  // 如果当前目录没有 .claude，先确认是否在此创建
+  if (!await fs.pathExists(projectTargetDir)) {
+    const { shouldCreate } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'shouldCreate',
+        message: `当前目录 ${chalk.yellow(process.cwd())} 未找到 .claude 目录，是否在此创建？`,
+        default: false,
+      },
+    ])
+    if (!shouldCreate) {
+      console.log(chalk.yellow('\n已取消同步。'))
+      return
+    }
+  }
+
   // 扫描可用资源
   const skills = await scanSkills(sourceDir)
   const rules = await scanRules(sourceDir)
@@ -244,11 +260,11 @@ export async function syncClaude() {
 }
 
 /**
- * 单独同步 CLAUDE.md 到当前项目 .claude/
+ * 单独同步 CLAUDE.md 到全局 ~/.claude/
  */
 export async function syncProjectClaudeMd() {
   const sourceDir = await resolveSourceDir()
-  const targetDir = path.join(process.cwd(), '.claude')
+  const targetDir = path.join(os.homedir(), '.claude')
 
   if (!await fs.pathExists(sourceDir)) {
     console.error(chalk.red('Error: claude-global templates not found in repo'))

package/templates/claude-global/CLAUDE.md

@@ -6,11 +6,11 @@
 - **服务地址**：必须输出完整的 URL（如 `http://localhost:8000/api/users`），禁止省略协议、端口或路径
 - **数据库连接串**：必须输出完整连接字符串（如 `postgresql+asyncpg://user:pass@localhost:5432/mydb`），禁止只写主机名或库名
 
-## Agent 团队执行
+## 团队执行任务
 
-所有任务默认启用 agent team 模式执行：任务可拆分时优先并行派遣 Agent，具体派遣策略、并行度、worktree 隔离、review 闭环等由 Claude 自行判断，不在此处硬编码规则。
+任务执行优先使用 agent team 模式执行。
 
-## Behavioral Guidelines — 减少常见 LLM 编码错误的行为指南
+## 减少常见 LLM 编码错误的行为指南 (Behavioral Guidelines)
 
 与项目特定指令合并使用。
 

package/templates/claude-global/skills/dwy-ekit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dwy-ekit
-description: "@dwydev/ekit 前端工具库速查（v0.7.0）。触发条件：HTTP 请求、dwyeapi 响应契约对接、localStorage/Cookie、表单校验、日期/时区、剪贴板、查询字符串、文件下载、PII 脱敏、Vue composable 工具。"
+description: "【强制速查】只要涉及以下任何主题，必须调用本 skill，无论用户是否说ekit：HTTP 请求 / axios 封装 / token 刷新 / dwyeapi 响应契约对接 / localStorage / Cookie / useStorage / useCookie / 日期格式化 / 时区处理 / dayjs / 表单校验 / zod schema / vee-validate / PII 脱敏 / 剪贴板 / useClipboard / 文件下载 / Blob / 查询字符串 / qs / Vue composables（debounce / throttle / click-outside / event-listener / window-size / media-query / intersection-observer / resize-observer / useFormPersist）。本 skill 是 @dwydev/ekit（v0.7.0）的唯一权威来源，禁止绕过 ekit 直接手写底层 API。"
 ---
 
 # @dwydev/ekit 工具库速查（v0.7.0）
@@ -29,11 +29,11 @@ import {
 ekit 对外类型 **不允许** 出现底层库类名。下面这些导入 **会失败** —— 因为 ekit 不再 re-export：
 
 ```ts
-// ❌ 错误：ekit 不导出底层类型
+// 错误：ekit 不导出底层类型
 import type { AxiosInstance, IStringifyOptions, CookieAttributes } from '@dwydev/ekit'
 import { dayjs } from '@dwydev/ekit'
 
-// ✅ 正确：用 ekit 自有契约
+// 正确：用 ekit 自有契约
 import type { HttpClient, StringifyOptions, CookieOptions } from '@dwydev/ekit'
 import { now, formatTimestamp } from '@dwydev/ekit'  // 不需要 dayjs 实例
 ```
@@ -49,26 +49,295 @@ import { now, formatTimestamp } from '@dwydev/ekit'  // 不需要 dayjs 实例
 | `document.addEventListener('click', ...)` | `useEventListener()` |
 | 手写 axios 实例 | `createRequest()` |
 
-## 查阅源码
+## 模块速查
 
-每个模块源码在 `/Users/chances/WebstormProjects/dwy-shared/frontend/ekit/src/{module}/`，函数都很短可以直接读。
+### request — HTTP 客户端 + 4 内置插件 + dwyeapi 契约
 
-## 模块索引
+```ts
+import {
+  createRequest, tokenPlugin, headerPlugin, unwrapPlugin, refreshTokenPlugin,
+  SUCCESS_CODE, isApiBusinessError, extractValidationErrors,
+} from '@dwydev/ekit'
+import type {
+  HttpClient, HttpConfig, HttpResponse, HttpError, HttpPlugin,
+  CreateRequestOptions, ApiResponse, PageData,
+} from '@dwydev/ekit'
+```
+
+**createRequest**
+
+```ts
+const http: HttpClient = createRequest({
+  baseURL: '/api',
+  timeout: 30000,
+  headers: { 'X-Client': 'web' },
+  plugins: [tokenPlugin({ getToken: () => localStorage.getItem('token') }), unwrapPlugin()],
+})
+
+const res = await http.get<User>('/users/1')        // res: HttpResponse<User>
+const list = await http.get<PageData<User>>('/users')
+list.data.items       // User[]
+list.data.total       // number
+list.data.page        // number
+list.data.page_size   // number
+```
+
+**内置插件**
+
+| 插件 | 参数 | 说明 |
+|------|------|------|
+| `tokenPlugin` | `{ getToken: () => string | null }` | 注入 `Authorization: Bearer <token>` |
+| `headerPlugin` | `{ name, getValue }` | 动态自定义 header |
+| `unwrapPlugin` | 无 | 解包 dwyeapi `{ code, message, data, timestamp }`，业务失败时 reject |
+| `refreshTokenPlugin` | `{ getRefreshToken, refreshFn, onRefreshFail, retry, isLoginUrl? }` | 401 自动刷新并重放；`retry: (cfg) => http.request(cfg)` 必填 |
+
+**响应契约 & 错误捕获**
+
+```ts
+// unwrap 后 data 是纯业务数据（单体）或 PageData<T>（分页）
+const res = await http.get<User>('/users/1')   // res.data: User
+
+// 捕获业务错误
+try {
+  await http.post('/orders', body)
+} catch (err) {
+  if (!isApiBusinessError(err)) { message.error('网络异常'); return }
+  switch (err.businessCode) {
+    case 'INSUFFICIENT_BALANCE': showRecharge(); break
+    case 'VALIDATION_ERROR': form.setErrors(extractValidationErrors(err)); break
+    default: message.error(err.message)
+  }
+}
+```
+
+`extractValidationErrors` 剥离 `body. / query. / path.` 前缀，返回 `{ field: message }` 扁平对象，与 vee-validate 的 `form.setErrors` 直接兼容。
+
+### storage — localStorage
+
+```ts
+import { useStorage, storage } from '@dwydev/ekit'
+```
+
+| API | 签名 / 说明 |
+|-----|------------|
+| `useStorage(key, defaultValue, storage?, opts?)` | 再导出 @vueuse/core；跨标签页同步、SSR-safe、自动 JSON 序列化 |
+| `storage.get<T>(key, defaultValue?)` | 返回 `T | undefined`；JSON 解析失败按字符串返回 |
+| `storage.set(key, value)` | 自动 `JSON.stringify` |
+| `storage.remove(key)` | 删除 |
+| `storage.clear()` | 清空全部（慎用） |
+
+```ts
+const token = useStorage<string>('token', '')
+const config = useStorage('config', { theme: 'light' }, localStorage, { mergeDefaults: true })
+```
+
+### cookie — Cookie 读写
+
+```ts
+import { useCookie, cookie } from '@dwydev/ekit'
+import type { CookieOptions } from '@dwydev/ekit'
+```
+
+```ts
+interface CookieOptions {
+  expires?: number | Date   // 天数或 Date；不传 = 会话级
+  path?: string             // 默认 '/'
+  domain?: string
+  secure?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+}
+
+cookie.get<User>('user')
+cookie.set('user', { id: 1 }, { expires: 7, secure: true })
+cookie.remove('user', { path: '/' })
+
+const lang = useCookie('lang', 'zh-CN')
+lang.value = 'en-US'       // 自动写入
+lang.value = undefined     // 自动删除
+```
+
+### date — 日期 / 时间 / 时区
+
+```ts
+import {
+  now, formatTimestamp, formatInTimezone,
+  formatDate, formatDateTime, formatTime, formatRelativeTime, formatBy,
+} from '@dwydev/ekit'
+```
+
+| 函数 | 签名 | 输出示例 |
+|------|------|---------|
+| `now()` | `(): number` | `1745318445000`（UTC 毫秒戳） |
+| `formatTimestamp(ts, fmt?)` | `(number, string?) => string` | `'2026-04-22 18:40:45'`（默认） |
+| `formatInTimezone(tz, ts?, fmt?)` | `(string, number?, string?) => string` | `formatInTimezone('America/New_York', ts)` |
+| `formatDate(input)` | `(string | number | Date) => string` | `'2026-04-22'` |
+| `formatDateTime(input)` | 同上 | `'2026-04-22 18:40:45'` |
+| `formatTime(input)` | 同上 | `'18:40'` |
+| `formatRelativeTime(input)` | 同上 | `'刚刚' / '5 分钟前' / '3 小时前' / '2 天前'`；> 30 天退化为 `YYYY-MM-DD` |
+| `formatBy(input, template)` | 同上 | `formatBy(ts, 'YYYY年MM月DD日')` -> `'2026年04月22日'` |
+
+### qs — 查询字符串
+
+```ts
+import { stringify, parse } from '@dwydev/ekit'
+import type { StringifyOptions, ParseOptions } from '@dwydev/ekit'
+```
+
+```ts
+stringify({ ids: [1, 2], name: 'a' })                          // 'ids=1&ids=2&name=a'
+stringify({ ids: [1, 2] }, { arrayFormat: 'brackets' })        // 'ids[]=1&ids[]=2'
+stringify({ a: 1 }, { addQueryPrefix: true })                  // '?a=1'
+
+parse('?a=1&b=2')                                              // { a: '1', b: '2' }（默认 ignoreQueryPrefix: true）
+parse('a.b=1', { allowDots: true })                            // { a: { b: '1' } }
+```
+
+### validators — 表单校验
+
+```ts
+import {
+  isPhone, isEmail, isIdCard, isUrl, isRequired, minLength, maxLength,
+  phoneSchema, emailSchema, idCardSchema, urlSchema,
+  requiredSchema, minLengthSchema, maxLengthSchema,
+} from '@dwydev/ekit'
+```
+
+**布尔函数**
+
+| 函数 | 规则 |
+|------|------|
+| `isPhone(value)` | 中国手机号 1[3-9] 开头 11 位 |
+| `isEmail(value)` | 基础邮箱格式 |
+| `isIdCard(value)` | 18 位身份证（末位允许 X/x） |
+| `isUrl(value)` | 合法 URL |
+| `isRequired(value)` | 非空（0 / false 视为有效） |
+| `minLength(value, n)` / `maxLength(value, n)` | 长度校验 |
+
+**zod schema（配合 vee-validate）**
 
-按需读取对应 references 文件，避免一次性加载全部 API 文档。
+```ts
+import { useForm } from 'vee-validate'
+import { toTypedSchema } from '@vee-validate/zod'
+import { phoneSchema, emailSchema } from '@dwydev/ekit'
+
+const schema = toTypedSchema(z.object({ phone: phoneSchema, email: emailSchema }))
+const { defineField, errors } = useForm({ validationSchema: schema })
+```
+
+> `minLengthSchema(n)` / `maxLengthSchema(n)` 是工厂函数，调用后返回 schema。
+
+### masking — PII 脱敏
+
+```ts
+import {
+  maskPhone, maskEmail, maskIdCard, maskBankCard,
+  maskName, maskAddress, maskIp, maskLicensePlate, maskText,
+} from '@dwydev/ekit'
+```
+
+纯函数，无外部依赖。**输入不符合格式时原样返回，不抛异常**。
+
+| 函数 | 示例输出 |
+|------|---------|
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  /  |  /  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+
+### copy — 剪贴板
+
+```ts
+import { copyText, useClipboard } from '@dwydev/ekit'
+```
+
+```ts
+await copyText('hello')
+
+const { text, copy, copied, isSupported } = useClipboard({ source: '', copiedDuring: 1500 })
+copy('hello')
+// copied: ComputedRef<boolean>，1500ms 后自动复位
+// isSupported: ComputedRef<boolean>
+```
 
-| 模块 | 用途 | 详见 |
-|---|---|---|
-| `request` | HTTP 客户端（防腐层 + 4 个内置插件 + dwyeapi 响应契约 + 业务错误捕获） | `references/request.md` |
-| `storage` | localStorage 封装（@vueuse/core 的 useStorage + 静态 storage 对象） | `references/data.md` § storage |
-| `cookie` | Cookie 读写（js-cookie 薄封装 + useCookie） | `references/data.md` § cookie |
-| `date` | 日期 / 时间 / 时区格式化（基于 dayjs，不暴露实例） | `references/data.md` § date |
-| `qs` | 查询字符串序列化 / 解析（基于 qs） | `references/data.md` § qs |
-| `validators` | 表单校验（布尔函数 + zod schema 配合 vee-validate） | `references/form.md` § validators |
-| `masking` | PII 数据脱敏（手机/邮箱/身份证/银行卡/姓名/地址等） | `references/form.md` § masking |
-| `copy` | 剪贴板（copyText + @vueuse/core 的 useClipboard） | `references/ui.md` § copy |
-| `file` | 文件下载 / Blob / 文件大小格式化 | `references/ui.md` § file |
-| `hooks` | Vue Composables（全部再导出 @vueuse/core） | `references/ui.md` § hooks |
+### file — 文件下载 / Blob / 文件大小
+
+```ts
+import { downloadFile, saveBlob, formatFileSize } from '@dwydev/ekit'
+import type { DownloadOptions, FileRequester } from '@dwydev/ekit'
+```
+
+```ts
+await downloadFile('/api/export.xlsx')                      // GET，自动解析文件名
+await downloadFile('/api/export', {
+  filename: '报表.xlsx', method: 'POST', data: { dateRange },
+})
+
+// 自定义 requester（axios 实例天然满足 FileRequester）
+await downloadFile('/api/export', { requester: myHttpClient })
+
+saveBlob(blob, 'data.json')
+formatFileSize(1234567)        // '1.18 MB'
+formatFileSize(1234567, 0)     // '1 MB'
+```
+
+### hooks — Vue Composables
+
+```ts
+import {
+  useDebounce, useClickOutside, useEventListener, useThrottle,
+  useWindowSize, useMediaQuery, useIntersectionObserver, useResizeObserver,
+  useFormPersist, DEFAULT_SENSITIVE_FIELDS,
+} from '@dwydev/ekit'
+```
+
+| Composable | 说明 |
+|-----------|------|
+| `useDebounce(value, delay=300)` | 防抖 ref；返回 `Readonly<Ref<T>>` |
+| `useClickOutside(target, handler)` | 点击元素外部触发 |
+| `useEventListener(target, event, handler, options?)` | 自动绑/解绑 |
+| `useThrottle(fn, ms)` | 节流函数 |
+| `useWindowSize()` | `{ width, height }` |
+| `useMediaQuery(query)` | `useMediaQuery('(max-width: 768px)')` |
+| `useIntersectionObserver(target, cb)` | 监听元素出现/消失 |
+| `useResizeObserver(target, cb)` | 监听元素尺寸变化 |
+| `useFormPersist(key, initialValue, options?)` | 表单刷新自动回填；默认排除敏感字段 |
+
+**useFormPersist**
+
+```ts
+const { form, reset, clear } = useFormPersist('register-form', {
+  email: '', code: '', remark: '',
+})
+
+// 选项
+interface UseFormPersistOptions<T> {
+  exclude?: (keyof T)[]           // 追加敏感字段
+  storage?: 'session' | 'local'   // 默认 'session'
+  disableDefaultExclude?: boolean // 默认 false（开启内置排除）
+}
+
+// 提交成功后清空残留
+await api.register(form.value)
+reset()
+```
+
+内置 `DEFAULT_SENSITIVE_FIELDS` 包含 password / confirmPassword / oldPassword / newPassword / pwd / code / captcha / verifyCode / verificationCode / smsCode / emailCode / phoneCode / otp / token / accessToken / refreshToken / signSecret / secret / apiKey 共 19 项，不区分大小写。
+
+## 何时读取 references
+
+本 SKILL.md 正文已包含 10 个模块的核心 API、签名和典型用法，满足 90% 编码场景。`references/` 目录保存边缘细节，仅在需要时读取：
+
+| 文件 | 内容 |
+|------|------|
+| `references/request.md` | `HttpPlugin` 完整接口、`HttpError` 字段详情、refreshTokenPlugin 完整参数、`CommonBusinessCode` 枚举、非标准响应兜底行为 |
+| `references/data.md` | `StringifyOptions` / `ParseOptions` 完整字段、`CookieOptions` 完整字段、useStorage 全部选项 |
+| `references/form.md` | validators 底层正则规则、masking 边界处理说明 |
+| `references/ui.md` | `FileRequester` 完整契约、`DownloadOptions` 全部字段、旧版迁移陷阱 |
 
 ## v0.6.0 迁移要点