create-dwy 0.6.0 → 0.6.2

package/bin/index.js

@@ -5,33 +5,29 @@ import { fileURLToPath } from 'url'
 import { dirname, resolve } from 'path'
 import { program } from 'commander'
 import { createProject } from '../src/create.js'
-import { syncClaude, syncProjectClaude } from '../src/sync.js'
+import { syncClaude, syncProjectClaudeMd } from '../src/sync.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'))
 
 program
   .name('dwy')
-  .description('Project scaffolding and Claude Code config sync')
+  .description('项目脚手架与 Claude Code 配置同步工具')
   .version(pkg.version)
 
 program
   .command('create [name]')
-  .description('Create a new project from template')
+  .description('从模板创建新项目')
   .action(createProject)
 
 program
-  .command('sync <target>')
-  .description('Sync Claude configuration (claude | project-claude)')
-  .action(async (target) => {
-    if (target === 'claude') {
-      await syncClaude()
-    } else if (target === 'project-claude') {
-      await syncProjectClaude()
-    } else {
-      console.error(`Unknown sync target: ${target}. Use "claude" or "project-claude".`)
-      process.exit(1)
-    }
-  })
+  .command('sync')
+  .description('交互式选择并同步 Claude Code 配置（skills/rules/commands/settings.json → 项目 .claude/；CLAUDE.md → 全局 ~/.claude/）')
+  .action(syncClaude)
+
+program
+  .command('sync-claude-md')
+  .description('单独同步 CLAUDE.md 到当前目录的 .claude/')
+  .action(syncProjectClaudeMd)
 
 program.parse()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-dwy",
-  "version": "0.6.0",
-  "description": "Project scaffolding and Claude Code config sync CLI",
+  "version": "0.6.2",
+  "description": "项目脚手架与 Claude Code 配置同步工具",
   "type": "module",
   "bin": {
     "dwy": "./bin/index.js"
@@ -11,7 +11,12 @@
     "src",
     "templates"
   ],
-  "keywords": ["cli", "scaffold", "fastapi", "vue"],
+  "keywords": [
+    "cli",
+    "scaffold",
+    "fastapi",
+    "vue"
+  ],
   "license": "MIT",
   "author": "dwydev",
   "dependencies": {

package/src/sync.js

@@ -1,5 +1,6 @@
 import fs from 'fs-extra'
 import path from 'path'
+import os from 'os'
 import inquirer from 'inquirer'
 import { ensureRepoCache, copyDir, chalk, PACKAGE_ROOT } from './utils.js'
 
@@ -59,7 +60,7 @@ async function scanRules(sourceDir) {
     const content = await fs.readFile(rulePath, 'utf-8')
     const description = extractDescription(content)
     rules.push({
-      name: entry.name.replace(/\.md$/, ''),
+      name: entry.name,
       description: description || '（无描述）',
       sourcePath: rulePath,
       type: 'rule',
@@ -189,13 +190,15 @@ async function resolveSourceDir() {
 }
 
 /**
- * 主同步函数：交互式选择 + 同步到当前目录 .claude/
+ * 主同步函数：交互式选择 + 同步到当前目录 .claude/（不含 CLAUDE.md）
+ * CLAUDE.md 同步到全局 ~/.claude/
  */
 export async function syncClaude() {
   console.log(chalk.blue('\nScanning available Claude configuration...\n'))
 
   const sourceDir = await resolveSourceDir()
-  const targetDir = path.join(process.cwd(), '.claude')
+  const projectTargetDir = path.join(process.cwd(), '.claude')
+  const globalTargetDir = path.join(os.homedir(), '.claude')
 
   if (!await fs.pathExists(sourceDir)) {
     console.error(chalk.red('Error: claude-global templates not found in repo'))
@@ -216,28 +219,50 @@ export async function syncClaude() {
 
   const totalSelected = selectedSkills.length + selectedRules.length + selectedCommands.length
   if (totalSelected === 0) {
-    console.log(chalk.yellow('\nNo items selected. Nothing to sync.'))
-    return
+    console.log(chalk.yellow('\nNo skills/rules/commands selected.'))
   }
 
-  console.log(chalk.blue(`\nSyncing ${totalSelected} items to ${targetDir}...\n`))
+  console.log(chalk.blue(`\nSyncing to ${projectTargetDir}...\n`))
 
-  await fs.ensureDir(targetDir)
+  await fs.ensureDir(projectTargetDir)
 
   let syncedCount = 0
-  syncedCount += await syncSelectedItems(selectedSkills, targetDir)
-  syncedCount += await syncSelectedItems(selectedRules, targetDir)
-  syncedCount += await syncSelectedItems(selectedCommands, targetDir)
-  syncedCount += await syncClaudeMd(sourceDir, targetDir)
-  syncedCount += await syncSettings(sourceDir, targetDir)
+  if (totalSelected > 0) {
+    syncedCount += await syncSelectedItems(selectedSkills, projectTargetDir)
+    syncedCount += await syncSelectedItems(selectedRules, projectTargetDir)
+    syncedCount += await syncSelectedItems(selectedCommands, projectTargetDir)
+  }
+  syncedCount += await syncSettings(sourceDir, projectTargetDir)
+
+  // CLAUDE.md 同步到全局
+  await fs.ensureDir(globalTargetDir)
+  syncedCount += await syncClaudeMd(sourceDir, globalTargetDir)
 
-  console.log(chalk.blue(`\nDone! Synced ${syncedCount} items to ${targetDir}`))
+  console.log(chalk.blue(`\nDone! Synced ${syncedCount} items.`))
+  console.log(chalk.gray(`  Project config → ${projectTargetDir}`))
+  console.log(chalk.gray(`  CLAUDE.md      → ${globalTargetDir}`))
 }
 
 /**
- * 保留旧的 project-claude 同步逻辑
+ * 单独同步 CLAUDE.md 到当前项目 .claude/
  */
-export async function syncProjectClaude() {
-  console.log(chalk.yellow('"dwy sync project-claude" is deprecated. Use "dwy sync claude" instead.'))
-  await syncClaude()
+export async function syncProjectClaudeMd() {
+  const sourceDir = await resolveSourceDir()
+  const targetDir = path.join(process.cwd(), '.claude')
+
+  if (!await fs.pathExists(sourceDir)) {
+    console.error(chalk.red('Error: claude-global templates not found in repo'))
+    process.exit(1)
+  }
+
+  await fs.ensureDir(targetDir)
+  const synced = await syncClaudeMd(sourceDir, targetDir)
+
+  if (synced) {
+    console.log(chalk.blue(`\nDone! CLAUDE.md synced to ${targetDir}`))
+  } else {
+    console.log(chalk.yellow('\nCLAUDE.md not found in templates, nothing to sync.'))
+  }
 }
+
+

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

@@ -1,6 +1,6 @@
 ---
 name: dwy-eapi
-description: "dwyeapi FastAPI 后端基础设施速查。触发条件：使用 FastAPI 构建后端、配置数据库/Redis/JWT/异常处理、耗时任务处理时。"
+description: "dwyeapi FastAPI 后端基础设施速查。当用户使用 FastAPI 构建后端、配置数据库/Redis/JWT/异常处理、写 API 响应/分页/日志/健康检查/数据脱敏、处理异步耗时任务、接入邮件验证码发送时，**必须**使用此 skill。即使用户没有明确说'dwyeapi'或'eapi'，只要涉及 FastAPI 项目的基础设施搭建、统一响应封装、异常处理、数据库会话管理、Redis 缓存、JWT 认证、后台任务队列、PII 脱敏、日志配置，也应触发。"
 ---
 
 # dwyeapi 后端基础设施速查
@@ -431,3 +431,65 @@ app.include_router(task_router)
 | POST | `/tasks/{task_id}/cancel` | 取消任务 |
 
 > **完整文档：** [tasks-integration-guide.md](references/tasks-integration-guide.md) — 包含 TaskContext API、数据模型、Worker 配置、取消机制等详细说明。
+
+---
+
+## 其他模块速查
+
+### logger — 基于 loguru 的全局日志
+
+```python
+from dwyeapi import logger
+
+logger.configure(level="INFO", log_dir="./logs", filename="app")
+log = logger.get_logger("users")
+log.info("用户 %s 登录", user_id)
+```
+
+| 函数 | 说明 |
+|------|------|
+| `logger.configure(...)` | 启动时调用一次；支持按天+按大小轮转、JSON 序列化、拦截 stdlib logging |
+| `logger.get_logger(name?)` | 返回 Logger 门面，支持 `%s` 占位符和 `exc_info=True` |
+| `logger.close()` | 关闭并恢复 stdlib logger（lifespan 结束时调用） |
+
+**详细配置参数**：读 `references/logger.md`
+
+### health — 健康检查路由工厂
+
+```python
+from dwyeapi.health import create_health_router
+
+router = create_health_router(service_name="my-api", version="1.0.0")
+app.include_router(router)
+# GET /health → {"service": "my-api", "version": "1.0.0", "status": "alive"}
+```
+
+只探活、不探依赖（防 DoS 放大）。业务如需 readiness 自行实现并限制内网访问。
+
+### providers.email — 邮件验证码发送（可插拔）
+
+内置仅 `resend`，业务可继承 `EmailProviderBase` 注入自定义通道（腾讯云 SES、AWS SES、SMTP 等）。验证码 + Redis + 品牌化模板由基类复用。
+
+```python
+from dwyeapi.providers.email import EmailSettings, make_email_provider, register_email_provider
+```
+
+| 导出项 | 说明 |
+|--------|------|
+| `EmailSettings` | 配置模型（code_ttl, brand_name, resend） |
+| `make_email_provider(settings)` | 工厂函数，按 `.env EMAIL__PROVIDER` 创建实例 |
+| `register_email_provider(name, factory)` | 注册自定义 provider |
+| `EmailProviderBase` | 抽象基类，继承后实现 `_send` 即可 |
+
+---
+
+## 查阅源码
+
+所有模块为单文件设计，直接阅读：
+
+```
+backend/src/dwyeapi/{module}.py
+backend/src/dwyeapi/providers/email/
+```
+
+模块清单：config、database、dependencies、security、exceptions、response、pagination、cache、dt、masking、logger、health、tasks、providers/email。

package/templates/claude-global/skills/dwy-eapi/references/health.md

@@ -0,0 +1,47 @@
+# health — 健康检查路由工厂
+
+> 何时读这份：当用户需要添加健康检查端点、配置 k8s livenessProbe、或讨论 readiness vs liveness 设计时读取。
+
+```python
+from dwyeapi.health import create_health_router
+
+router = create_health_router(
+    service_name="my-api",
+    version="1.0.0",
+    path="/health",
+    include_in_schema=True,
+)
+app.include_router(router)
+```
+
+## 设计取舍
+
+端点**只**报告进程是否存活（liveness），**不连接 PostgreSQL / Redis** 等依赖。
+
+原因：健康端点通常对公网开放，若内置 readiness / dependency check，攻击者可用低频高并发请求放大到数据库/缓存层，变成 DoS 放大器。
+
+需要 readiness 语义的业务（如 k8s readinessProbe）应在业务项目里自行实现，并把该端点限制在内网或挂鉴权。
+
+## create_health_router 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| service_name | str | **必填** | 服务名，通常取自 `Settings.service_name` |
+| version | str | **必填** | 版本号，通常取自 `__version__` |
+| path | str | `"/health"` | 端点路径 |
+| include_in_schema | bool | True | 是否在 OpenAPI 文档暴露 |
+
+## 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "service": "my-api",
+    "version": "1.0.0",
+    "status": "alive"
+  },
+  "timestamp": 1775625000
+}
+```

package/templates/claude-global/skills/dwy-eapi/references/logger.md

@@ -0,0 +1,60 @@
+# logger — 基于 loguru 的全局日志
+
+> 何时读这份：当用户需要配置日志输出、轮转策略、拦截 uvicorn/SQLAlchemy 日志、或使用 JSON Lines 格式对接日志聚合系统时读取。
+
+```python
+from dwyeapi import logger
+
+# 启动时调用一次（通常在 lifespan 中）
+logger.configure(
+    level="INFO",
+    log_dir="./logs",
+    filename="app",
+    max_bytes=100 * 1024 * 1024,   # 100 MB
+    retention="30 days",
+    console=True,
+    serialize=False,
+    enqueue=True,
+    intercept_stdlib=True,
+    intercept_loggers=["uvicorn", "sqlalchemy"],
+)
+
+# 获取命名 logger
+log = logger.get_logger("users")
+log.info("用户 %s 登录", user_id)
+log.error("操作失败", exc_info=True)
+log.exception("未捕获异常")  # 自动 exc_info=True
+
+# 关闭（lifespan 结束时）
+logger.close()
+```
+
+## configure 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| level | str | `"INFO"` | 最低级别：DEBUG/INFO/WARNING/ERROR/CRITICAL |
+| log_dir | str/Path/None | None | 日志文件目录，None 表示关闭文件输出 |
+| filename | str | `"app"` | 文件基础名，最终为 `{filename}_YYYY-MM-DD.log` |
+| max_bytes | int | `100*1024*1024` | 单文件大小上限（字节） |
+| retention | str/int | `"30 days"` | 保留策略（如 `"1 week"`、整数个数） |
+| console | bool | True | 是否输出彩色日志到 stderr |
+| console_format | str/None | None | 自定义控制台格式 |
+| file_format | str/None | None | 自定义文件格式 |
+| serialize | bool | False | 文件 sink 是否按 JSON Lines 序列化 |
+| enqueue | bool | True | 是否异步写入（非阻塞、多进程安全） |
+| intercept_stdlib | bool | True | 是否拦截 stdlib `logging` |
+| intercept_loggers | list[str]/None | None | 限定拦截的 logger 名前缀，None 表示拦截 root |
+
+## Logger 门面 API
+
+`get_logger()` 返回的 `Logger` 兼容 stdlib 语义：
+
+- `debug(msg, *args, exc_info=False)`
+- `info(msg, *args, exc_info=False)`
+- `warning(msg, *args, exc_info=False)`
+- `error(msg, *args, exc_info=False)`
+- `exception(msg, *args)` — 等价于 `error(msg, *args, exc_info=True)`
+- `critical(msg, *args, exc_info=False)`
+
+所有方法支持 `%s` / `%d` 等 stdlib 占位符，空 args 时保留 msg 原样。

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

@@ -1,6 +1,6 @@
 ---
 name: dwy-eui
-description: "@dwydev/eui Vue 3 组件库速查。触发条件：使用 Vue 3 构建页面、选择 UI 组件、查询 eui 组件 API 时。"
+description: "@dwydev/eui Vue 3 组件库速查。当用户在使用 Vue 3 构建页面、选择 UI 组件、查询组件 API、写表单/表格/弹层/导航、配置主题或国际化、使用中后台或落地页设计规范时，**必须**使用此 skill。即使用户没有明确说'eui'，只要涉及 Vue 3 组件选型、页面布局、表单设计、数据展示、弹层交互、主题切换，也应触发。"
 ---
 
 # @dwydev/eui 组件速查
@@ -150,15 +150,16 @@ EConfigProvider 内部做了两件事：
 - 样式合并工具：`cn()` = clsx + tailwind-merge
 - 尺寸统一类型：`Size = 'sm' | 'default' | 'lg'`
 
-## 查阅完整 API
+## 查阅完整 API（按需读取源码）
 
-每个组件的完整 props/slots/events 定义在源码中：
+当需要某个组件的精确 props/slots/events/类型定义时，**必须**读取对应源码文件：
 
 ```
 frontend/eui/src/components/{component-name}/types.ts
+frontend/eui/src/components/{component-name}/EName.vue   # 模板和逻辑
 ```
 
-需要具体某个组件的详细 API 时，直接读取对应的 `types.ts` 文件。
+组件目录清单（89 个组件）：`frontend/eui/src/components/` 下包含 button、input、table、dialog、date-picker、chart、admin-layout、ai-chat 等。不确定组件名时，先 `ls frontend/eui/src/components/` 查看。
 
 ---
 
@@ -307,9 +308,11 @@ frontend/eui/src/components/{component-name}/types.ts
 | useMessage() | 全局消息提示 | { success, warning, error, info } — 每个接收 string 或 MessageOptions |
 | useNotification() | 通知 | { success, warning, error, info } — 接收 NotificationOptions(title, message, position, duration, onClick, closable) |
 | useMessageBox() | 对话确认 | { alert, confirm, prompt } — 返回 Promise<'confirm' \| 'cancel'> |
+| useToast() | Toast 通知（与 EToast 组件配合使用） | { toast, dismiss, toasts } — toast 接收 ToastOptions(title, description, variant) |
 | useTheme() | 主题管理 | { isDark, theme, setTheme, toggleDark, colorTheme, setColorTheme } |
 | useConfigProvider() | 读取全局配置 | { size, zIndex, locale } |
 | useFormField() | 表单字段上下文 | { id, name, formItemId, valid, isDirty, isTouched, error }（需在 FormField 内使用） |
+| useSecureValue() | 敏感输入安全绑定 | { isComposing, recordCursor, setCursor, setNativeValue, onCompositionStart, onCompositionEnd } — 通过 DOM property 赋值避免密码泄露到 HTML attribute |
 
 ## 主题系统