create-dwy 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # create-dwy
 
+## 0.19.1
+
+### Patch Changes
+
+- 上下移动时当前条目用指针 + 反底标出。原先只靠 dim，已勾选或 JetBrains 终端里看不出光标。
+
+---
+
 ## 0.19.0
 
 ### Minor Changes

package/package.json

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

package/src/prompt-style.js

@@ -0,0 +1,82 @@
+/**
+ * CLI 列表行聚焦样式。
+ * 只靠 dim 在 JetBrains / 部分终端看不出光标；已勾选时勾选框又全是绿块。
+ * 指针字符不依赖颜色，反底在支持 ANSI 的终端再加强。
+ */
+
+import { styleText } from 'node:util'
+import process from 'node:process'
+
+/** 是否支持 unicode 符号（与 clack prompts 判定一致） */
+function isUnicodeSupported() {
+  if (process.platform !== 'win32') {
+    return process.env.TERM !== 'linux'
+  }
+  return Boolean(process.env.CI)
+    || Boolean(process.env.WT_SESSION)
+    || Boolean(process.env.TERMINUS_SUBLIME)
+    || process.env.ConEmuTask === '{cmd::Cmder}'
+    || process.env.TERM_PROGRAM === 'Terminus-Sublime'
+    || process.env.TERM_PROGRAM === 'vscode'
+    || process.env.TERM === 'xterm-256color'
+    || process.env.TERM === 'alacritty'
+    || process.env.TERMINAL_EMULATOR === 'JetBrains-JediTerm'
+}
+
+const unicode = isUnicodeSupported()
+const unicodeOr = (c, fallback) => (unicode ? c : fallback)
+
+/** 光标指针。无 unicode 时用 ASCII，保证去 ANSI 后仍能看出聚焦行。 */
+const S_POINTER = unicodeOr('›', '>')
+const S_RADIO_ACTIVE = unicodeOr('●', '>')
+const S_RADIO_INACTIVE = unicodeOr('○', ' ')
+const S_CHECKBOX_ACTIVE = unicodeOr('◻', '[•]')
+const S_CHECKBOX_SELECTED = unicodeOr('◼', '[+]')
+const S_CHECKBOX_INACTIVE = unicodeOr('◻', '[ ]')
+
+/**
+ * 聚焦文案：反底芯片。无色终端退回原文字，靠指针区分。
+ *
+ * @param {string} label
+ * @param {boolean} active
+ */
+function formatLabel(label, active) {
+  if (active) return styleText(['bgCyan', 'black'], ` ${label} `)
+  return styleText('dim', label)
+}
+
+/**
+ * 多选一行。
+ * selected=已勾；active=当前光标。disabled 时不响应聚焦样式。
+ *
+ * @param {{ label: string, selected?: boolean, active?: boolean, prefix?: string, disabled?: boolean }} opts
+ */
+export function formatCheckboxRow({ label, selected = false, active = false, prefix = '', disabled = false }) {
+  const prefixPart = prefix ? `${prefix} ` : ''
+  if (disabled) {
+    return `  ${styleText('dim', S_CHECKBOX_INACTIVE)} ${prefixPart}${styleText(['strikethrough', 'dim'], label)}`
+  }
+  const pointer = active ? styleText('cyan', S_POINTER) : ' '
+  const box = selected
+    ? styleText('green', S_CHECKBOX_SELECTED)
+    : active
+      ? styleText('cyan', S_CHECKBOX_ACTIVE)
+      : styleText('dim', S_CHECKBOX_INACTIVE)
+  return `${pointer} ${box} ${prefixPart}${formatLabel(label, active)}`
+}
+
+/**
+ * 单选一行。disabled 画删除线，不画指针。
+ *
+ * @param {{ label: string, active?: boolean, disabled?: boolean }} opts
+ */
+export function formatRadioRow({ label, active = false, disabled = false }) {
+  if (disabled) {
+    return `  ${styleText('gray', S_RADIO_INACTIVE)} ${styleText(['strikethrough', 'gray'], label)}`
+  }
+  const pointer = active ? styleText('cyan', S_POINTER) : ' '
+  const radio = active
+    ? styleText('green', S_RADIO_ACTIVE)
+    : styleText('dim', S_RADIO_INACTIVE)
+  return `${pointer} ${radio} ${formatLabel(label, active)}`
+}

package/src/searchable-select.js

@@ -8,6 +8,7 @@ import { AutocompletePrompt, getColumns, settings } from '@clack/core'
 import { limitOptions } from '@clack/prompts'
 import { styleText } from 'node:util'
 import process from 'node:process'
+import { formatCheckboxRow, formatRadioRow } from './prompt-style.js'
 
 /** 是否支持 unicode 符号（与 clack prompts 判定一致） */
 function isUnicodeSupported() {
@@ -34,10 +35,6 @@ const S_STEP_ERROR = unicodeOr('▲', 'x')
 const S_STEP_SUBMIT = unicodeOr('◇', 'o')
 const S_BAR = unicodeOr('│', '|')
 const S_BAR_END = unicodeOr('└', '—')
-const S_RADIO_ACTIVE = unicodeOr('●', '>')
-const S_RADIO_INACTIVE = unicodeOr('○', ' ')
-const S_CHECKBOX_SELECTED = unicodeOr('◼', '[+]')
-const S_CHECKBOX_INACTIVE = unicodeOr('◻', '[ ]')
 
 /** 底部说明区固定行数，避免列表高度随描述长短跳动 */
 const DESC_PANEL_LINES = 3
@@ -256,21 +253,12 @@ export function searchableMultiselect(opts) {
           maxItems: opts.maxItems,
           output: opts.output,
           rowPadding: header.length + footer.length,
-          style: (opt, active) => {
-            const selected = this.selectedValues.includes(opt.value)
-            const label = optionLabel(opt)
-            const box = selected
-              ? styleText('green', S_CHECKBOX_SELECTED)
-              : styleText('dim', S_CHECKBOX_INACTIVE)
-            if (opt.disabled) {
-              return `${styleText('dim', S_CHECKBOX_INACTIVE)} ${styleText(['strikethrough', 'dim'], label)}`
-            }
-            // 聚焦也不拼 hint，描述只在底部公共区
-            if (active) {
-              return `${box} ${label}`
-            }
-            return `${box} ${styleText('dim', label)}`
-          },
+          style: (opt, active) => formatCheckboxRow({
+            label: optionLabel(opt),
+            selected: this.selectedValues.includes(opt.value),
+            active,
+            disabled: opt.disabled,
+          }),
         })
 
       return [
@@ -396,16 +384,11 @@ export function searchableSelect(opts) {
           output: opts.output,
           columnPadding: withGuide ? 3 : 0,
           rowPadding: header.length + footer.length,
-          style: (opt, active) => {
-            const label = optionLabel(opt)
-            if (opt.disabled) {
-              return `${styleText('gray', S_RADIO_INACTIVE)} ${styleText(['strikethrough', 'gray'], label)}`
-            }
-            if (active) {
-              return `${styleText('green', S_RADIO_ACTIVE)} ${label}`
-            }
-            return `${styleText('dim', S_RADIO_INACTIVE)} ${styleText('dim', label)}`
-          },
+          style: (opt, active) => formatRadioRow({
+            label: optionLabel(opt),
+            active,
+            disabled: opt.disabled,
+          }),
         })
 
       return [

package/src/tab-multiselect.js

@@ -8,6 +8,7 @@ import { Prompt, getColumns, settings } from '@clack/core'
 import { limitOptions } from '@clack/prompts'
 import { styleText } from 'node:util'
 import process from 'node:process'
+import { formatCheckboxRow } from './prompt-style.js'
 
 /** 是否支持 unicode 符号（与 clack / searchable-select 判定一致） */
 function isUnicodeSupported() {
@@ -35,8 +36,6 @@ const S_STEP_SUBMIT = unicodeOr('◇', 'o')
 const S_BAR = unicodeOr('│', '|')
 const S_BAR_END = unicodeOr('└', '—')
 const S_BAR_H = () => unicodeOr('─', '-')
-const S_CHECKBOX_SELECTED = unicodeOr('◼', '[+]')
-const S_CHECKBOX_INACTIVE = unicodeOr('◻', '[ ]')
 const S_TAB_MORE = unicodeOr('‹', '<')
 const S_TAB_MORE_RIGHT = unicodeOr('›', '>')
 
@@ -418,16 +417,12 @@ export function tabMultiselect(opts) {
           maxItems: opts.maxItems ?? 12,
           output: opts.output,
           rowPadding: header.length + footer.length,
-          style: (opt, active) => {
-            const on = selected.includes(opt.value)
-            const label = opt.label ?? String(opt.value ?? '')
-            const box = on
-              ? styleText('green', S_CHECKBOX_SELECTED)
-              : styleText('dim', S_CHECKBOX_INACTIVE)
-            const prefix = formatItemTypePrefix(opt.type)
-            if (active) return `${box} ${prefix} ${label}`
-            return `${box} ${prefix} ${styleText('dim', label)}`
-          },
+          style: (opt, active) => formatCheckboxRow({
+            label: opt.label ?? String(opt.value ?? ''),
+            selected: selected.includes(opt.value),
+            active,
+            prefix: formatItemTypePrefix(opt.type),
+          }),
         })
 
       return [

package/templates/ai-tools/rules/Python/dwy-python-base-lib.md

@@ -33,7 +33,7 @@ paths:
 
 ### 查阅方式（关键）
 
-**在编写任何后端代码前，以及调用任何 dwyeapi 提供的 API 之前，必须先用 `Skill` 工具加载 `dwy-eapi` skill 查阅当前最新接口。** 本文件**只规定约束与边界**，**不固化** dwyeapi 的具体模块路径、类名、函数签名、参数 —— 这些会随版本演进，固化在 rules 里会与实际包不同步。
+**在编写任何后端代码前，以及调用任何 dwyeapi 提供的 API 之前，必须先用 `Skill` 工具加载 `dwy-eapi`。** skill 会按消费方**实际安装版本**选 `v0`/`v1` 文档线；不确定时先 clone `dwyeapi@x.y.z`，拿不到再读虚拟环境里的安装包。本文件**只规定约束与边界**，**不固化**模块路径、类名、函数签名。
 
 ```
 Skill 工具调用：skill="dwy-eapi"

package/templates/ai-tools/skills/Python/dwy-eapi/SKILL.md

@@ -1,226 +1,85 @@
 ---
 name: dwy-eapi
-description: "dwyeapi FastAPI 后端基础设施使用指南。涉及以下任何主题，**必须**使用此 skill（即使用户没有明确说 'dwyeapi' / 'eapi'）：FastAPI 项目搭建 / Pydantic Settings 配置 / 异步 SQLAlchemy / Redis 缓存 / JWT 认证 / bcrypt 密码哈希 / 异常体系（AppError / NotFoundError / BusinessError）/ 统一响应信封（ApiResponse / PageData）/ 分页 / 日志（loguru）/ 健康检查 / PII 脱敏 / 时区敏感的时间处理 / 异步任务（ARQ）/ 邮件验证码发送。本 skill 是 @dwydev/eapi 的唯一权威导航来源。"
-eapi_baseline_version: "0.9.0"
+description: "Use when building or changing FastAPI backends that use dwyeapi: Pydantic Settings, async SQLAlchemy, Redis, JWT/bcrypt, AppError/NotFoundError/BusinessError, ApiResponse/PageData, pagination, loguru, health checks, PII masking, timezone-aware dt, ARQ tasks, email verification codes, Gmail alias canonicalization. The single navigation skill for dwyeapi."
 ---
 
-# dwyeapi 后端基础设施使用指南
+# dwyeapi
 
-Python 3.11+ FastAPI 基础设施包，全异步。单文件模块设计（每个能力一个 .py），便于直接读源码。
+FastAPI 基础设施包。本文件只做**路由**：探测安装版本 → 选文档线 → 不够再读源码（先 clone tag，拿不到再读虚拟环境）。
 
-本 skill 索引基于 dwyeapi **0.9.0**。消费方版本可能不同 — 见 [版本兼容规则](#版本兼容规则)。
+对外只有这一个 skill。`v0/` `v1/` 不是独立 skill，禁止当多个入口用。
 
-## 模块清单（13 个）
+## 每次写 dwyeapi 代码前（强制）
 
-| 模块 | 用途 |
-|------|------|
-| `config` | Pydantic BaseSettings + 运行环境识别 (is_dev / is_prod / get_environment) |
-| `exceptions` | AppError 异常体系 + FastAPI 全局 handler 注册 |
-| `database` | 异步 SQLAlchemy engine/session 工厂 + Base + TimestampMixin |
-| `dependencies` | FastAPI 依赖注入工厂（如 get_db） |
-| `security` | JWT 令牌 + bcrypt 密码哈希（无状态） |
-| `cache` | 异步 Redis 连接管理（懒单例） |
-| `response` | 统一 API 响应信封 `ApiResponse[T]` + `PageData[T]` |
-| `pagination` | 分页参数 PaginationParams + offset/limit 计算 |
-| `dt` | 中国时区敏感的全局时间工具（替代 datetime.now） |
-| `logger` | loguru 全局日志（按天 + 按大小轮转、stdlib 拦截） |
-| `masking` | PII 数据脱敏（手机/邮箱/身份证/银行卡/姓名/地址/IP/车牌） |
-| `health` | 健康检查路由工厂（只探活、不探依赖） |
-| `tasks` | 异步任务系统（基于 ARQ，需 `pip install dwyeapi[tasks]`） |
-| `providers.email` | 邮件验证码发送（可插拔，默认 Resend，可继承注入腾讯 SES / SMTP 等） |
-
----
-
-## 查 API 标准动作（核心：每次写 dwyeapi 代码前都做）
-
-dwyeapi 的源码 docstring 写得非常详尽（含设计意图、边界行为、Args/Returns/Raises、典型陷阱）。**本文档不再镜像签名表格** —— 因为表格信息密度低于源码 docstring，且会随版本漂移。需要某个 API 的精确签名/语义时，按下面顺序拿：
-
-### 第一步：定位 dwyeapi 真实版本和安装路径
-
-```bash
-# 拿版本
-pip show dwyeapi | grep -i version
-#  或：python -c "import dwyeapi; print(dwyeapi.__version__)"
-
-# 拿包安装目录
-python -c "import dwyeapi; print(dwyeapi.__file__)"
-# 输出形如 /path/to/.venv/lib/python3.12/site-packages/dwyeapi/__init__.py
-# dirname 后的目录就是 dwyeapi 包根，模块都在里面
-```
-
-### 第二步：读模块源码（按存在性回退）
-
-```
-a. 优先：<site-packages>/dwyeapi/{module}.py
-   —— 下游消费方默认场景。每个模块单文件，含模块级 docstring + 所有公开函数/类的 Args/Returns/Raises
-
-b. 次选：<dwy-shared-root>/backend/src/dwyeapi/{module}.py
-   —— 仅当在 dwy-shared monorepo 内或并列 clone 时可用，内容相同
-
-c. 都拿不到 → 退到本文档下方的 [模块清单](#模块清单13-个)（粗略，仅做导航）
-```
-
-### 第三步：tasks 模块查详细文档
-
-tasks 模块功能丰富（注册 / 提交 / 查询 / 取消 / 进度），单独维护一份完整集成指南：
-
-```
-references/tasks-integration-guide.md
-```
-
-只在用到 tasks 时读，平时不必加载。
-
-### 第四步：冲突时永远信源码
-
-本 SKILL.md 是导航 + 心智模型，**不是 API 真相**。当文档描述与 site-packages 中的 `.py` 不一致：无条件以源码为准。
-
----
+1. **探测安装版本**（按顺序，命中即停）
+   ```bash
+   python -c "import dwyeapi; print(dwyeapi.__version__)"
+   ```
+   失败则读项目 `pyproject.toml` / `uv.lock` 里 `dwyeapi` 约束。
+   仍失败：按 `v0` 给脚手架，并声明「未探测到安装版本」。
 
-## 版本兼容规则
+2. **选线**：读同目录 `versions.yml`。`0.y.z` → `v0/`，`1.y.z` → `v1/`，`2.y.z` → `v2/`。目录不存在（例如装了 1.x 但还没有 `v1/`）→ 不要用 `v0` 冒充；按下面「读源码」拿该版本代码，并说明文档线未建。
 
-- 本 skill `eapi_baseline_version: 0.9.0`，模块清单、踩坑提示都基于这个版本
-- 消费方装的是不同版本（更新或更旧）时，**必须**按"查 API 标准动作"流程读 .py，不要默认本文档准确
-- dwyeapi < 0.9.0 可能没有 dt / tasks / providers 模块：先 `ls <site-packages>/dwyeapi/` 确认存在再用
-- 主版本号变更（0.x → 1.x）时，本文档的索引可能完全失效：先 `ls <site-packages>/dwyeapi/` 重建认知
+3. **读文档**：先 `shared/`（跨大版本不变），再该线 `vN/`。能力标了版本下限（如 `canonicalize_email` ≥0.9.6）时，安装版本低于下限 → 当不存在。
 
----
-
-## 重要约束与已知陷阱
-
-源码读得出来但容易忽略的"踩坑经验"，写后端代码时遵守：
-
-### 业务层架构（service / router 分层）
-
-- **service 层**抛业务异常（`NotFoundError("用户")` / `BusinessError("余额不足", code="INSUFFICIENT_BALANCE")` 等），不感知 HTTP 概念
-- **router 层**不写 try/except，由 `register_exception_handlers(app)` 统一转成 `ApiResponse` 信封 JSON
-- **禁止**在 service 层抛 `HTTPException` —— 会绕过统一 handler，破坏响应结构一致性
-
-### 时间处理（避免时区 bug）
-
-- 业务时间统一中国时区，**禁止 `datetime.now()`**，统一走 `dwyeapi.dt`
-- `dt.now()` 返回 naive datetime（Asia/Shanghai，用于数据库存储）
-- `dt.utc_now()` 返回 aware UTC datetime（用于 JWT exp 等协议字段）
-- 这两个不能混用：数据库列存 naive 中国时间、JWT exp 存 UTC aware
-
-### 配置
-
-- **没有 `debug` 字段**，所有调试开关统一用 `is_dev()`：避免两个维度（debug + environment）冲突
-- `environment` 默认 `"prod"`（误配置时保守）：生产环境必须显式关闭 docs/redoc/openapi 三个端点（`docs_url="/docs" if is_dev() else None`），否则路由元信息会泄露给攻击者
-- `BaseSettings` 必填三个字段：`database_url` / `redis_url` / `secret_key`（继承时不能给默认值）
-
-### Redis 连接
-
-- `cache.configure(redis_url)` 启动时调用一次（lifespan）；`cache.get_redis()` 首次调用懒建立连接
-- `close_redis()` 可重复调用（安全幂等），lifespan 关闭阶段调用
-- 未 configure 直接 `get_redis()` 会抛 `RuntimeError`
-
-### tasks 模块
-
-- 需要 `pip install dwyeapi[tasks]` 单独装 extra（避免不用任务的项目背 ARQ 依赖）
-- 任务函数签名固定 `async def task(ctx: TaskContext, params: dict)`，第一个参数 ctx 由框架注入
-- 取消机制是协作式：任务函数内必须主动 `await ctx.is_cancelled()` 检查，否则取消信号无效
-- 完整细节读 `references/tasks-integration-guide.md`
+4. **文档不够 / 和记忆冲突 / 下限对不上** → 读代码，顺序如下（命中即停）：
+   1. clone 安装版本对应 tag（见下）
+   2. tag 不存在 / clone 失败 → 读**当前虚拟环境**里已安装的 `dwyeapi` 源码
+   3. 虚拟环境也没有 → **停下来问人**，禁止猜 API，禁止拿旁边 dwy-shared master 冒充
 
-### 邮件 Provider
+## 读源码
 
-- 内置仅 `resend`。业务用其他通道（腾讯 SES / SMTP / 自建）：继承 `EmailProviderBase` 实现 `_send` → `register_email_provider("name", factory)` → `.env` 设 `EMAIL__PROVIDER=name`
-- 验证码生成 + Redis 存储 + 品牌化模板 由基类全部复用，子类只管"发出去"
+### 1. clone tag（优先）
 
-### 日志
-
-- `logger.configure()` 启动时调用一次；`logger.close()` 在 lifespan 结束时调用
-- `intercept_stdlib=True`（默认）会把 stdlib logging（uvicorn / SQLAlchemy 等）也接管到统一 sink
-- 多进程部署时必须 `enqueue=True`（默认）——避免日志文件竞争写
-
-### 健康检查
-
-- `create_health_router()` **只**探活、**不**触达 PostgreSQL / Redis 等依赖
-- 理由：健康端点常对公网开放，内置 dependency check 会被攻击者用来 DoS 放大数据库/缓存
-- 需要 readiness 的业务自行实现并限制内网访问
-
----
-
-## 典型项目接入流程
-
-```python
-# config.py
-from dwyeapi.config import BaseSettings
-
-class Settings(BaseSettings):
-    app_name: str = "My API"
-    service_name: str = "my-api"
-
-settings = Settings()  # 从 .env / 环境变量读 database_url、redis_url、secret_key
-
-# database.py
-from dwyeapi.database import create_async_engine_factory, create_session_factory
-from dwyeapi.dependencies import create_get_db
-from dwyeapi import is_dev
-
-engine = create_async_engine_factory(settings.database_url, echo=is_dev())
-session_factory = create_session_factory(engine)
-get_db = create_get_db(session_factory)
-
-# main.py
-from contextlib import asynccontextmanager
-from fastapi import FastAPI
-from dwyeapi import cache, logger, is_dev
-from dwyeapi.exceptions import register_exception_handlers
-from dwyeapi.health import create_health_router
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    logger.configure(level="INFO", log_dir="./logs", filename="app")
-    cache.configure(settings.redis_url)
-    yield
-    await cache.close_redis()
-    logger.close()
-
-app = FastAPI(
-    lifespan=lifespan,
-    docs_url="/docs" if is_dev() else None,
-    redoc_url="/redoc" if is_dev() else None,
-    openapi_url="/openapi.json" if is_dev() else None,
-)
-register_exception_handlers(app)
-app.include_router(create_health_router(service_name=settings.service_name, version="1.0.0"))
+```bash
+VER=0.9.6                          # 换成第 1 步探测到的版本
+TAG="dwyeapi@${VER}"
+DEST=".dwy/eapi-src/${VER}"        # 项目内缓存，已 gitignore
+
+if [ ! -d "$DEST/backend/src/dwyeapi" ]; then
+  git clone --depth 1 --branch "$TAG" \
+    --filter=blob:none --sparse \
+    https://github.com/danweiyuancircle/dwy-ai-experience.git \
+    "$DEST"
+  git -C "$DEST" sparse-checkout set backend/src/dwyeapi
+fi
+# 只读 $DEST/backend/src/dwyeapi/ 的模块 docstring
 ```
 
----
-
-## 响应契约速查（前后端对齐用）
+- `--branch` 必须是 `dwyeapi@x.y.z`，禁止 clone 默认 branch。
+- 必须 sparse，只要 `backend/src/dwyeapi`。
 
-所有接口返回统一信封：
+### 2. 虚拟环境（clone 拿不到时）
 
-```json
-{
-  "code": "SUCCESS",
-  "message": "success",
-  "data": { ... },
-  "timestamp": 1775625000
-}
+```bash
+python -c "import dwyeapi, os; print(os.path.dirname(dwyeapi.__file__))"
+# 输出形如 .venv/lib/python3.11/site-packages/dwyeapi
+# 读该目录下模块 docstring
 ```
 
-- 成功：`code = "SUCCESS"`，`data` 是业务载荷（单体或 `PageData[T]`）
-- 失败：`code` 是业务错误码（如 `NOT_FOUND` / `BUSINESS_ERROR` / `VALIDATION_ERROR` 等），HTTP 状态保持语义（404 就是 404）
-- 校验错误 `VALIDATION_ERROR`：`data.errors: [{field, message}]`，field 含 `body.` / `query.` / `path.` 前缀
-
-构造响应：用 `ApiResponse.ok(data)` 或 `ApiResponse.page(items, total, page, page_size)`，不直接实例化 `ApiResponse`。
+editable 安装时这个路径就是消费方正在跑的代码，当作安装版本真相。
 
-错误响应**不要业务代码构造** —— 直接 `raise NotFoundError("用户")`，handler 自动转。
+文档与源码冲突：信源码。clone 与 venv 都读到且不一致：以 **venv** 为准（editable / 热修），回复里写明。
 
----
+## 文档地图
 
-## 防腐层硬性约束（写代码前必读）
+| 路径 | 何时读 |
+|------|--------|
+| `shared/layering.md` | 分层、禁 HTTPException |
+| `shared/timezone.md` | 禁 `datetime.now` |
+| `shared/response-envelope.md` | ApiResponse 信封 |
+| `shared/anticorruption.md` | 禁止直调 redis/jwt/logging |
+| `v0/index.md` | 0.x 模块清单、接入、陷阱 |
+| `v0/providers-email.md` | 邮件 Provider 注册表 |
+| `v0/email-canonical.md` | Gmail 规范化（≥0.9.6） |
+| `v0/breaking.md` | 0.x 内部 breaking |
+| `references/tasks-integration-guide.md` | 只用 tasks 时读 |
 
-dwyeapi 把基础设施细节封装在自有 API 后面。业务代码**禁止**直接调下面这些底层 API，违反会导致升级困难、行为不一致：
+## 禁止
 
-| 禁止 | 改用 |
+| 借口 | 实际 |
 |------|------|
-| `datetime.now()` / `datetime.utcnow()` | `dt.now()` / `dt.utc_now()` |
-| `import logging; logging.getLogger()` | `from dwyeapi import logger; logger.get_logger()` |
-| 手写 `from redis.asyncio import Redis` 全局变量 | `cache.configure()` + `cache.get_redis()` |
-| 手写 JWT encode/decode（含 `import jwt`） | `security.create_token()` / `security.decode_token()` |
-| 直接 `raise HTTPException(404, ...)` | `raise NotFoundError("资源名")` |
-| 自己写 `{"code": ..., "data": ...}` dict 当响应 | `ApiResponse.ok(data)` / `ApiResponse.page(...)` |
-| 自己写 `?page=&page_size=` Query 参数 | `params: PaginationParams = Depends()` |
+| 读旁边 dwy-shared master | 消费方版本可能不同。先 clone 安装版本的 tag，不行再读本项目 venv |
+| 文档是 0.9，装的 0.9.6，差不多 | 有下限的能力必须对照版本 |
+| tag 没有就猜 / 直接停 | clone 失败后读 venv；venv 也没有才停 |
+| 再开一个 `dwy-eapi-v0` skill | 对外只有 `dwy-eapi` |

package/templates/ai-tools/skills/Python/dwy-eapi/shared/anticorruption.md

@@ -0,0 +1,13 @@
+# 防腐层
+
+业务代码禁止直调底层 API：
+
+| 禁止 | 改用 |
+|------|------|
+| `datetime.now()` / `datetime.utcnow()` | `dt.now()` / `dt.utc_now()` |
+| `import logging; logging.getLogger()` | `from dwyeapi import logger; logger.get_logger()` |
+| 手写 `from redis.asyncio import Redis` 全局变量 | `cache.configure()` + `cache.get_redis()` |
+| 手写 JWT encode/decode（含 `import jwt`） | `security.create_token()` / `security.decode_token()` |
+| 直接 `raise HTTPException(404, ...)` | `raise NotFoundError("资源名")` |
+| 自己写 `{"code": ..., "data": ...}` dict | `ApiResponse.ok(data)` / `ApiResponse.page(...)` |
+| 自己写 `?page=&page_size=` Query | `params: PaginationParams = Depends()` |

package/templates/ai-tools/skills/Python/dwy-eapi/shared/layering.md

@@ -0,0 +1,5 @@
+# 分层
+
+- **service 层**抛业务异常（`NotFoundError("用户")` / `BusinessError("余额不足", code="INSUFFICIENT_BALANCE")`），不感知 HTTP。
+- **router 层**不写 try/except，由 `register_exception_handlers(app)` 统一转成 `ApiResponse` 信封。
+- **禁止**在 service 层抛 `HTTPException` —— 会绕过统一 handler。

package/templates/ai-tools/skills/Python/dwy-eapi/shared/response-envelope.md

@@ -0,0 +1,20 @@
+# 响应信封
+
+所有接口返回：
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "success",
+  "data": {},
+  "timestamp": 1775625000
+}
+```
+
+- 成功：`code = "SUCCESS"`，`data` 是业务载荷（单体或 `PageData[T]`）
+- 失败：`code` 是业务错误码（`NOT_FOUND` / `BUSINESS_ERROR` / `VALIDATION_ERROR`），HTTP 状态保持语义
+- 校验错误 `VALIDATION_ERROR`：`data.errors: [{field, message}]`，field 含 `body.` / `query.` / `path.` 前缀
+
+构造：`ApiResponse.ok(data)` 或 `ApiResponse.page(items, total, page, page_size)`，不直接实例化成功态。
+
+错误响应不要业务代码拼信封 —— `raise NotFoundError("用户")`，handler 自动转。

package/templates/ai-tools/skills/Python/dwy-eapi/shared/timezone.md

@@ -0,0 +1,7 @@
+# 时间
+
+业务时间统一中国时区。**禁止 `datetime.now()` / `datetime.utcnow()`**，走 `dwyeapi.dt`。
+
+- `dt.now()`：naive（Asia/Shanghai），数据库存储
+- `dt.utc_now()`：aware UTC，JWT exp 等协议字段
+- 两者不能混用

package/templates/ai-tools/skills/Python/dwy-eapi/v0/breaking.md

@@ -0,0 +1,12 @@
+# 0.x 内部 breaking
+
+0.x 的 minor 也可以不兼容。整条线仍用 `v0/`，破坏点记在这里。细节 clone `dwyeapi@x.y.z`，不要另开 `v0.10/` 目录。
+
+完整段落以该 tag 的 `backend/CHANGELOG.md` 为准。
+
+| 版本 | 破坏点 |
+|------|--------|
+| 0.6.0 | 信封改为 `ApiResponse[T]` / `PageData[T]`；删除 `success` / `fail` / `paginated`；`code` 成功态从 int `200` 改为 `"SUCCESS"` |
+| 0.9.0 | 删除 `MockEmailProvider`、`AliyunEmailProvider`、整个 `providers.sms`；`EMAIL__PROVIDER` 改为自由字符串；mock/阿里云改业务 `register_email_provider` |
+
+0.9.6 起新增 `dwyeapi.email` 与 Redis key 规范化，对旧调用方兼容（发码 key 折到同一收件箱）。能力下限见 `email-canonical.md`。

package/templates/ai-tools/skills/Python/dwy-eapi/v0/email-canonical.md

@@ -0,0 +1,18 @@
+# 邮箱规范化（≥0.9.6）
+
+安装版本 `< 0.9.6`：没有 `dwyeapi.email`，不要 import。
+
+```python
+from dwyeapi.email import canonicalize_email, is_folded_alias, GMAIL_DOMAINS
+
+canonicalize_email("Bai.Wen+1@Gmail.com")  # baiwen@gmail.com
+canonicalize_email("a.b@googlemail.com")   # ab@gmail.com
+canonicalize_email("a+x@icloud.com")       # a+x@icloud.com
+is_folded_alias("a+x@gmail.com")           # True
+is_folded_alias("A@gmail.com")             # False
+```
+
+- 注册查重、登录查找、用户表写入 **必须** 走 `canonicalize_email`
+- Gmail 把 plus / 点号 / `googlemail.com` 当成同一收件箱，不折会开多个号、绕过发码冷却
+- 其它域名只做 strip + lower，保留 `+` 与点
+- `send_code` / `verify_code` 的 Redis key 已自动规范化；业务存库仍要自己调