create-dwy 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # create-dwy
 
+## 0.16.0
+
+### Minor Changes
+
+- `dwy` 开头自动检测更新全局外部 skill：未装 / 清单变更（cli 加了 skill 或改了 tag）才联网重装，已装且清单一致零开销；失败不阻塞 sync。用户无需再另记 `dwy skills install`。
+- 新增 `dwy-commercial` 商业分析 skill（立项阶段 validate 之后、poc 之前）：商业模式 / 变现路径 / 定价 / 单位经济（CAC/LTV/毛利/回本）/ GTM 获客 + 商业可行性结论；startup 模式为硬闸门、builder 模式跳过。包装 pm-skills 的 `business-model` / `monetization-strategy` / `pricing-strategy` / `startup-canvas` / `porters-five-forces` + `gtm-strategy`。
+- `dwy skills install` 降级为隐藏的强制刷新兜底（向后兼容保留，日常无需手动）；`printHelp` 只露 `dwy` 主入口，`dwy sync` 为别名。
+
 ## 0.15.0
 
 ### Minor Changes

package/bin/index.js

@@ -15,14 +15,16 @@ function printHelp() {
     `dwy ${pkg.version}`,
     '',
     'Usage:',
-    '  dwy               运行交互式同步',
-    '  dwy sync          运行交互式同步',
-    '  dwy skills install  安装/更新全局外部 skill 到 ~/.dwy/skills/',
+    '  dwy               运行交互式同步（自动更新全局外部 skill）',
     '  dwy --help        显示本说明',
     '  dwy -h            显示本说明',
     '  dwy --version     显示当前版本',
     '  dwy -V            显示当前版本',
     '',
+    '以下为隐藏命令（向后兼容保留，日常无需手动调用）：',
+    '  dwy sync          同上的别名',
+    '  dwy skills install  强制刷新全局外部 skill',
+    '',
   ]
   console.log(lines.join('\n'))
 }

package/package.json

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

package/src/skills-install.js

@@ -1,6 +1,7 @@
 import fs from 'fs-extra'
 import path from 'path'
 import os from 'node:os'
+import { createHash } from 'node:crypto'
 import { getDwyHomeDir, runGit, chalk } from './utils.js'
 
 function logAction(label) {
@@ -29,6 +30,12 @@ const SKILL_SOURCES = {
       'test-scenarios': 'pm-execution/skills/test-scenarios',
       'release-notes': 'pm-execution/skills/release-notes',
       'gtm-strategy': 'pm-go-to-market/skills/gtm-strategy',
+      // 商业分析（dwy-commercial 依赖）：商业模式 / 变现 / 定价 / 创业画布 / 赛道五力
+      'business-model': 'pm-product-strategy/skills/business-model',
+      'monetization-strategy': 'pm-product-strategy/skills/monetization-strategy',
+      'pricing-strategy': 'pm-product-strategy/skills/pricing-strategy',
+      'startup-canvas': 'pm-product-strategy/skills/startup-canvas',
+      'porters-five-forces': 'pm-product-strategy/skills/porters-five-forces',
       'intended-vs-implemented': 'pm-ai-shipping/skills/intended-vs-implemented',
       'north-star-metric': 'pm-marketing-growth/skills/north-star-metric',
     },
@@ -47,6 +54,13 @@ const SKILL_SOURCES = {
   },
 }
 
+// 计算 SKILL_SOURCES 清单的内容指纹，用于检测「cli 加了 skill / 改了 tag」→ 需重装。
+// SKILL_SOURCES 是源码内固定字面量，JSON.stringify 稳定（插入顺序固定）。
+// 取 sha256 前 12 位，足以区分任意清单变更，无碰撞风险。
+function computeManifestHash() {
+  return createHash('sha256').update(JSON.stringify(SKILL_SOURCES)).digest('hex').slice(0, 12)
+}
+
 // 全局外部 skill 安装目录：~/.dwy/skills/
 function getGlobalSkillsDir() {
   return path.join(getDwyHomeDir(), 'skills')
@@ -92,22 +106,49 @@ export async function installSkills() {
       }
     }
 
-    // 写版本清单，供查看与后续更新比对
-    await fs.writeJson(path.join(targetDir, 'VERSIONS.json'), versions, { spaces: 2 })
+    // 写版本清单 + 清单指纹，供查看与后续更新比对。
+    // manifest_hash 变化（cli 加了 skill / 改了 tag）→ 下次 ensureSkillsInstalled 触发重装。
+    await fs.writeJson(
+      path.join(targetDir, 'VERSIONS.json'),
+      { manifest_hash: computeManifestHash(), versions },
+      { spaces: 2 },
+    )
     console.log(chalk.green(`\n✓ 外部 skill 已安装到 ${targetDir}`))
   } finally {
     await fs.remove(tmpRoot)
   }
 }
 
-// 全局 skill 是否已就绪（供 sync 自检：缺则自动装）。
+// 全局 skill 是否已就绪（VERSIONS.json 存在）。
 export async function skillsInstalled() {
   return fs.pathExists(path.join(getGlobalSkillsDir(), 'VERSIONS.json'))
 }
 
+// 确保 ~/.dwy/skills/ 与 cli 当前 SKILL_SOURCES 清单一致：未装 / 清单变更 → 自动重装。
+// hash 一致 → 零开销跳过；失败 → warn 一行不阻塞主流程（离线/网络故障不挡 sync）。
+// 返回 true = 本次执行了安装，false = 跳过。
 export async function ensureSkillsInstalled() {
-  if (await skillsInstalled()) return false
-  console.log(chalk.gray('未检测到全局外部 skill，自动安装...'))
-  await installSkills()
-  return true
+  const versionsFile = path.join(getGlobalSkillsDir(), 'VERSIONS.json')
+  // 已装：读 manifest_hash 比对，一致即跳过，不联网
+  if (await fs.pathExists(versionsFile)) {
+    let stored
+    try {
+      stored = await fs.readJson(versionsFile)
+    } catch {
+      stored = {}
+    }
+    // 兼容老格式（无 manifest_hash）→ 视为不一致，触发一次重装补上指纹
+    if (stored.manifest_hash === computeManifestHash()) return false
+    console.log(chalk.gray('全局外部 skill 清单已更新，重新拉取...'))
+  } else {
+    console.log(chalk.gray('未检测到全局外部 skill，自动安装...'))
+  }
+  try {
+    await installSkills()
+    return true
+  } catch (error) {
+    // 离线/网络故障：不阻塞主流程，下次再来
+    console.log(chalk.yellow(`外部 skill 自动更新失败：${error.message}`))
+    return false
+  }
 }

package/src/sync-all.js

@@ -26,13 +26,6 @@ import { scanExistingCursorRules, syncCursor } from './sync-cursor.js'
 import { syncOpenCode } from './sync-opencode.js'
 import { ensureSkillsInstalled } from './skills-install.js'
 
-// 产品 0→1 流程里依赖全局外部 skill 的包装型原子 skill。
-// 同步选中其中任一个时，触发全局外部 skill 自检安装。
-const WRAPPER_SKILL_NAMES = new Set([
-  'dwy-ideate', 'dwy-competitor', 'dwy-validate', 'dwy-mvp', 'dwy-prd',
-  'dwy-version', 'dwy-tasks', 'dwy-tdd-dev', 'dwy-acceptance', 'dwy-release',
-])
-
 const PLATFORM_OPTIONS = [
   { value: 'claude', label: 'Claude Code', hint: '支持 rules / skills / commands / hooks' },
   { value: 'codex', label: 'Codex', hint: '支持 rules / skills / hooks' },
@@ -567,6 +560,12 @@ export async function syncAll({
 
   const projectDir = projectDirOverride || process.cwd()
 
+  // 开头无条件自检全局外部 skill：未装 / 清单变更（cli 加了 skill 或改了 tag）则自动更新，
+  // 已装且清单一致则零开销跳过。失败不阻塞 sync（离线/网络故障，下次再来）。
+  // 这样用户跑一次 `dwy` 就把 skill 更新到位，无需另记 `dwy skills install`。
+  console.log(chalk.gray('检查全局外部 skill 更新...'))
+  await ensureSkillsInstalled()
+
   console.log(chalk.blue('\nScanning available Claude Code/Codex configuration...\n'))
   const scans = {
     skills: await scanSkills(sourceDir),
@@ -698,17 +697,6 @@ export async function syncAll({
   }
   await saveSyncState(projectDir, syncState)
 
-  // 产品 0→1 流程的包装型原子 skill 依赖全局外部 skill（~/.dwy/skills/）。
-  // 若本次同步选中了这些 skill 且全局未安装，自动装一次（缺则装、有则跳过）。
-  if (selected.skills?.some((s) => WRAPPER_SKILL_NAMES.has(s.name))) {
-    try {
-      await ensureSkillsInstalled()
-    } catch (error) {
-      console.log(chalk.yellow(`\n外部 skill 自动安装失败：${error.message}`))
-      console.log(chalk.gray('可稍后手动运行 `dwy skills install` 重试。'))
-    }
-  }
-
   if (!syncedAnySupportedPlatform) {
     console.log(chalk.yellow('未选择已接入平台，本次未执行同步。'))
   }

package/templates/ai-tools/CLAUDE.md

@@ -54,6 +54,21 @@
 - 如果你写了 200 行但可以写成 50 行，重写它。
 - 问自己："一个资深工程师会说这过于复杂吗？"如果是，简化。
 
+### 写代码前走决策阶梯
+
+写任何新代码前，从上往下逐级问，命中即停：
+
+1. 这任务真需要存在吗？（YAGNI——能不做就不做）
+2. 代码库里已有现成的吗？
+3. 标准库覆盖吗？
+4. 平台 / 框架原生特性有吗？
+5. 已安装的依赖能做吗？
+6. 能一行解决吗？
+7. 以上都不行 → 才写最小代码。
+
+刻意的简化用注释标注：跳过了什么、何时该加回。
+红线——以下永不简化掉：输入校验、错误处理、安全、可访问性。先理解问题，再谈优化。
+
 ### 3. 精准改动
 
 只动必须动的代码。只清理自己造成的混乱。
@@ -181,3 +196,15 @@
 - 后端用 dict / map / any 接收 body
 - 分页 `page_size` 无上限
 - 图片只校验文件大小不校验像素
+
+## 自成长项目规则（project-rules）
+
+写项目要自成长：同一类问题反复踩坑，主动沉淀成可复用规则，下次自动生效，不靠人事后总结。
+
+- **触发**：写代码 / 排查问题时，同一类问题踩坑 **≥2 次**（重复的报错根因、踩同一个坑、被反复纠正同一处写法）。
+- **动作**：把教训沉淀成一条可复用规则（写清「现象 / 根因 / 怎么避免」），追加到 `project-rules.md`；已有同类规则补充进去，不重复立条。
+- **落盘位置**（按当前工具自动选）：
+  - **Claude Code** → 项目 `.claude/rules/project-rules.md`（放进去即自动加载，无需注册）。
+  - **Codex** → 项目根 `AGENTS.md`，写在 `<!-- DWY-RULES:START/END -->` 托管块**之外**的 `## [自成长] 项目规则` 节下。托管块内会被 `dwy codex sync` 整块覆盖，自成长内容**必落块外**。
+- **方式**：自动沉淀，事后输出一行告知「已沉淀 <规则> 到 project-rules」，不打断当前任务、不逐条问用户。
+- **边界**：只沉淀**可复用、跨任务**的教训；一次性 / 本任务特有的问题不立规则，避免噪音堆积。

package/templates/ai-tools/rules/Android/dwy-android-pitfalls.md

@@ -0,0 +1,52 @@
+---
+description: Android 开发避坑清单（Gradle / 签名 / Compose / 生命周期 / 真机部署踩坑），按分类持续追加
+paths:
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.kts"
+  - "**/*.gradle"
+  - "**/AndroidManifest.xml"
+  - "**/res/**/*.xml"
+---
+
+# Android 开发坑清单
+
+> 动手前先对照本清单避开已知坑；踩到新坑随手按四栏格式（现象 / 根因 / 正确做法 / 适用）追加到对应分类，没有合适分类就新建一个。
+>
+> 通用开发规范见 `dwy-android-core` rule，本文件只记**非显而易见的实战坑**。
+
+## 分类索引
+
+- 工程与构建（Gradle / AGP / 依赖冲突）
+- 签名与真机部署
+- Compose / UI（重组、状态、生命周期）
+- 生命周期 / 并发（协程、ViewModel、内存泄漏）
+- 权限 / Manifest / Capability
+- 排查方法论
+- 其他分类遇到再加
+
+---
+
+## 工程与构建
+
+<!-- 待填：踩到坑按四栏格式追加 -->
+
+## 签名与真机部署
+
+<!-- 待填 -->
+
+## Compose / UI
+
+<!-- 待填 -->
+
+## 生命周期 / 并发
+
+<!-- 待填 -->
+
+## 权限 / Manifest / Capability
+
+<!-- 待填 -->
+
+## 排查方法论
+
+<!-- 待填 -->

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

@@ -10,52 +10,6 @@ paths:
 
 ---
 
-## 零、优先使用 `dwyeapi` 基础框架库（强制）
-
-`dwyeapi` 是团队内部 PyPI 基础设施包，已封装后端项目所需的通用能力。**凡是 dwyeapi 已提供的能力，禁止自行实现，也禁止引入其他库重复造轮子。**
-
-### 必须复用 dwyeapi 的能力域
-
-| 能力域 | 内容 |
-|--------|------|
-| 配置管理 | 应用 Settings 基类、运行环境识别（dev / prod） |
-| 异常体系 | 业务异常基类与全局异常处理器注册 |
-| 统一响应 | `{ code, message, data, timestamp }` 包装 |
-| 分页 | 分页查询参数模型与分页响应封装 |
-| 数据库 | ORM 声明式基类、时间戳 Mixin、异步引擎与会话工厂 |
-| 依赖注入 | FastAPI `get_db` 工厂 |
-| 安全 | 密码哈希、JWT 创建与解码 |
-| 缓存 | 共享异步 Redis 客户端 |
-| 时间 | 业务时间统一入口（Asia/Shanghai） |
-| 脱敏 | PII 数据脱敏函数 |
-| 日志 | 全局日志配置与门面 |
-| 健康检查 | 健康检查路由工厂 |
-| 异步任务 | 耗时任务队列与上下文 |
-| 邮件 | 邮件验证码可插拔通道 |
-
-### 查阅方式（关键）
-
-**在编写任何后端代码前，以及调用任何 dwyeapi 提供的 API 之前，必须先用 `Skill` 工具加载 `dwy-eapi` skill 查阅当前最新接口。** 本文件**只规定约束与边界**，**不固化** dwyeapi 的具体模块路径、类名、函数签名、参数 —— 这些会随版本演进，固化在 rules 里会与实际包不同步。
-
-```
-Skill 工具调用：skill="dwy-eapi"
-```
-
-### 强制规则
-
-- 涉及上表任一能力域，**先查 skill 拿到当前 API，再写代码**
-- **禁止**自造异常基类，必须复用 dwyeapi 异常体系
-- **禁止**手写 bcrypt / PyJWT 调用，必须走 dwyeapi 安全模块
-- **禁止**自定义统一响应包装函数，必须用 dwyeapi 响应模块
-- **禁止**自定义分页模型，必须用 dwyeapi 分页模块
-- **禁止**自定义 `DeclarativeBase`，模型必须继承 dwyeapi 提供的基类
-- **禁止**在路由函数中直接创建数据库会话，必须用 dwyeapi 依赖工厂
-- **禁止**自建 Redis 连接池，必须用 dwyeapi 共享客户端
-- **禁止**在业务代码中直接使用 `datetime.now()`，必须用 dwyeapi 时间模块
-- **禁止**自行 `logging.basicConfig`，必须用 dwyeapi 日志模块
-
----
-
 ## 一、项目结构与业务聚合（强制）
 
 ### 核心原则
@@ -103,7 +57,7 @@ app/
 - 测试镜像功能聚合结构：`tests/users/test_router.py` / `tests/users/test_service.py`（详见第九节）
 
 ### 例外
-- 通用基础设施代码（如 dwyeapi 内部）可保持技术层结构
+- 通用基础设施代码（如基础框架库内部）可保持技术层结构
 
 ---
 
@@ -167,11 +121,11 @@ async def create_user(
 
 ### 统一响应格式
 
-所有成功 / 分页 / 错误响应统一走 dwyeapi 响应与异常模块（具体 API 与字段结构查 `dwy-eapi` skill），**禁止**自造响应包装函数，**禁止**在 router 中手动构造 `{"success": true, ...}` 等非标准格式。
+所有成功 / 分页 / 错误响应统一走项目级响应与异常模块，**禁止**自造响应包装函数，**禁止**在 router 中手动构造 `{"success": true, ...}` 等非标准格式。
 
 ### 分页
 
-分页参数模型与响应包装统一走 dwyeapi（具体 API 查 `dwy-eapi` skill），**禁止**自定义。
+分页参数模型与响应包装统一走项目级分页模块，**禁止**自定义。
 
 ---
 
@@ -234,7 +188,7 @@ class UserResponse(UserBase):
 
 - 数据库会话、当前用户、配置等**必须**通过 `Depends()` 注入
 - **禁止**在路由函数中直接创建数据库会话或实例化 service
-- `get_db` 依赖必须用 dwyeapi 提供的工厂生成（具体 API 查 `dwy-eapi` skill）
+- `get_db` 依赖必须用项目级工厂生成，**禁止**每个路由各自创建
 
 ```python
 # 反例：路由中直接创建会话
@@ -258,8 +212,8 @@ async def get_user(
 
 ### 强制规则
 
-- **必须**复用 dwyeapi 异常体系与全局处理器（具体异常类与注册方法查 `dwy-eapi` skill），**禁止**自造异常基类
-- 项目级扩展异常必须继承 dwyeapi 异常基类
+- **必须**复用项目级异常体系与全局处理器，**禁止**自造异常基类
+- 项目级扩展异常必须继承统一异常基类
 - **service 层**抛业务异常，**禁止**抛 `HTTPException`（service 不感知 HTTP）
 - **router 层**不写 `try / except`，由全局 handler 统一处理
 - **禁止**裸 `except:` 或 `except Exception: pass`
@@ -273,7 +227,7 @@ async def get_user(
 ### 强制规则
 
 - 必须使用 **SQLAlchemy 2.0** 声明式映射 + async
-- 模型继承 dwyeapi 提供的声明式基类与时间戳 Mixin（具体类名查 `dwy-eapi` skill），**禁止**自定义 `DeclarativeBase`
+- 模型继承项目级统一声明式基类与时间戳 Mixin，**禁止**每个模型各自定义 `DeclarativeBase`
 - 数据库迁移使用 **Alembic**，**禁止**手动执行 DDL
 - **禁止**在路由层直接写 SQL 查询
 - **禁止**使用 SQLAlchemy 1.x 风格的 `session.query(...)`
@@ -283,7 +237,7 @@ from sqlalchemy.orm import Mapped, mapped_column
 from sqlalchemy import String
 import uuid as uuid_lib
 
-class User(BaseFromDwyeapi, TimestampMixinFromDwyeapi):  # 实际基类名以 skill 为准
+class User(Base, TimestampMixin):  # 项目级统一基类与时间戳 Mixin
     __tablename__ = "users"
 
     id: Mapped[int] = mapped_column(primary_key=True)
@@ -328,10 +282,10 @@ user = result.scalar_one_or_none()
 
 | 规则 | 说明 |
 |------|------|
-| 存储算法 | **只允许 bcrypt**，必须走 dwyeapi 安全模块，**禁止**手写 bcrypt 调用或使用 MD5 / SHA / 明文 |
+| 存储算法 | **只允许 bcrypt**，必须走项目级统一安全模块，**禁止**散落手写 bcrypt 调用或使用 MD5 / SHA / 明文 |
 | 接口返回 | **永远不返回**密码字段，Response Schema 中不包含 |
 | 密码强度 | **长度 ≥ 8 字符**，且**必须**包含 **大写字母、小写字母、数字、特殊符号** 中的至少 **3 类** |
-| 密码长度上限 | Schema 必须 `max_length=72`（bcrypt 输入硬上限，超过会被静默截断），除非 dwyeapi 已做 SHA-256 预哈希 |
+| 密码长度上限 | Schema 必须 `max_length=72`（bcrypt 输入硬上限，超过会被静默截断），除非安全模块已做 SHA-256 预哈希 |
 | 登录错误 | 返回"用户名或密码错误"，**不区分**是用户名不存在还是密码错误 |
 | 强度校验位置 | Pydantic Schema 层用 `field_validator` 校验复杂度，**禁止**只校长度 |
 
@@ -361,12 +315,12 @@ class UserCreate(BaseModel):
         return v
 ```
 
-> 该 validator 建议下沉到 dwyeapi 提供统一的 `PasswordStr` 类型，避免每个项目重复实现。
+> 该 validator 建议下沉为项目级统一的 `PasswordStr` 类型，避免每个模块重复实现。
 
 ### 7.3 接口认证与授权
 
 - 所有 API **必须** JWT 认证（白名单除外：`/health` / `/auth/login` / `/auth/register`）
-- JWT 创建与解码**必须**走 dwyeapi 安全模块，**禁止**直接调用 PyJWT
+- JWT 创建与解码**必须**走项目级统一安全模块，**禁止**散落直接调用 PyJWT
 - Token 黑名单存 Redis（登出后失效，TTL = 剩余有效期）
 - Secret Key 必须从环境变量读取，**禁止**硬编码
 - Secret Key 长度与生成方式（按字节算，不按字符算）：
@@ -389,7 +343,7 @@ class UserCreate(BaseModel):
 
 - **禁止**直接返回 ORM 对象（可能暴露 password、内部 ID 等）
 - 列表接口**必须**分页，**禁止**返回全量数据
-- PII 字段（手机号 / 邮箱 / 身份证 / 银行卡 / 姓名 / 地址 / IP / 车牌）必须使用 dwyeapi 脱敏函数处理
+- PII 字段（手机号 / 邮箱 / 身份证 / 银行卡 / 姓名 / 地址 / IP / 车牌）必须使用项目级统一脱敏函数处理
 
 ### 7.5 错误处理安全
 
@@ -449,7 +403,7 @@ file_path = Path("/uploads") / safe_name
 
 ### 7.8 审计日志
 
-通过 dwyeapi 日志模块获取审计 logger，记录以下操作：
+通过项目级统一日志模块获取审计 logger，记录以下操作：
 
 | 操作 | 记录内容 |
 |------|---------|
@@ -510,8 +464,7 @@ AI 编写或审查后端代码时，**必须**检查以下违规模式，按严
 
 | 检查项 | 违规模式 | 严重程度 |
 |--------|---------|---------|
-| 重复造轮子 | 自造异常基类 / 自封装统一响应 / 手写 bcrypt 或 JWT 调用 / 自建 Redis 连接池 等 dwyeapi 已提供能力 | 高 |
-| 未查 skill | 调用 dwyeapi 能力域却未先查 `dwy-eapi` skill 拿当前 API | 高 |
+| 重复造轮子 | 自造异常基类 / 自封装统一响应 / 散落手写 bcrypt 或 JWT 调用 / 自建 Redis 连接池 等本应走项目级统一模块的能力 | 高 |
 | 技术层散落 | 顶级出现 `routers/` / `services/` / `models/` / `schemas/` 等技术层目录把不同功能文件混放，未按功能聚合 | 高 |
 | 测试与源码混放 | 测试文件放在源码目录中（如 `app/users/test_router.py`），未独立到测试目录 | 高 |
 | 密码明文 | `password` 字段出现在 Response Schema | **致命 → STOP** |
@@ -528,5 +481,5 @@ AI 编写或审查后端代码时，**必须**检查以下违规模式，按严
 | service 抛 HTTPException | service 层直接 `raise HTTPException` | 高 |
 | 路由中开会话 | 路由函数中 `async with session_factory()` | 高 |
 | 旧式查询 | `session.query(...)` 而非 `select(...)` | 高 |
-| `datetime.now()` 直用 | 业务代码直接 `datetime.now()` 而非走 dwyeapi 时间模块 | 高 |
+| `datetime.now()` 直用 | 业务代码直接 `datetime.now()` 而非走项目级统一时间模块 | 高 |
 | 物理删除业务数据 | 对业务数据执行物理删除 | 中 |

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

@@ -0,0 +1,89 @@
+---
+description: 团队内部 dwyeapi 基础框架库强制复用规范（配置 / 异常 / 响应 / 分页 / ORM / 安全 / 缓存 / 时间 / 脱敏 / 日志：禁重复造轮子）
+paths:
+  - "**/*.py"
+---
+
+# Python 后端 dwyeapi 基础库强制复用规范
+
+`dwy-python-backend` rule 的团队内补充。通用 FastAPI / SQLAlchemy / 安全编码规范见 `dwy-python-backend`；本文件只管「凡 dwyeapi 已提供的能力，禁止自行实现，也禁止引入其他库重复造轮子」。
+
+`dwyeapi` 是团队内部 PyPI 基础设施包，已封装后端项目所需的通用能力。
+
+---
+
+## 一、必须复用 dwyeapi 的能力域
+
+| 能力域 | 内容 |
+|--------|------|
+| 配置管理 | 应用 Settings 基类、运行环境识别（dev / prod） |
+| 异常体系 | 业务异常基类与全局异常处理器注册 |
+| 统一响应 | `{ code, message, data, timestamp }` 包装 |
+| 分页 | 分页查询参数模型与分页响应封装 |
+| 数据库 | ORM 声明式基类、时间戳 Mixin、异步引擎与会话工厂 |
+| 依赖注入 | FastAPI `get_db` 工厂 |
+| 安全 | 密码哈希、JWT 创建与解码 |
+| 缓存 | 共享异步 Redis 客户端 |
+| 时间 | 业务时间统一入口（Asia/Shanghai） |
+| 脱敏 | PII 数据脱敏函数 |
+| 日志 | 全局日志配置与门面 |
+| 健康检查 | 健康检查路由工厂 |
+| 异步任务 | 耗时任务队列与上下文 |
+| 邮件 | 邮件验证码可插拔通道 |
+
+### 查阅方式（关键）
+
+**在编写任何后端代码前，以及调用任何 dwyeapi 提供的 API 之前，必须先用 `Skill` 工具加载 `dwy-eapi` skill 查阅当前最新接口。** 本文件**只规定约束与边界**，**不固化** dwyeapi 的具体模块路径、类名、函数签名、参数 —— 这些会随版本演进，固化在 rules 里会与实际包不同步。
+
+```
+Skill 工具调用：skill="dwy-eapi"
+```
+
+---
+
+## 二、强制规则
+
+- 涉及上表任一能力域，**先查 skill 拿到当前 API，再写代码**
+- **禁止**自造异常基类，必须复用 dwyeapi 异常体系
+- **禁止**手写 bcrypt / PyJWT 调用，必须走 dwyeapi 安全模块
+- **禁止**自定义统一响应包装函数，必须用 dwyeapi 响应模块
+- **禁止**自定义分页模型，必须用 dwyeapi 分页模块
+- **禁止**自定义 `DeclarativeBase`，模型必须继承 dwyeapi 提供的基类
+- **禁止**在路由函数中直接创建数据库会话，必须用 dwyeapi 依赖工厂
+- **禁止**自建 Redis 连接池，必须用 dwyeapi 共享客户端
+- **禁止**在业务代码中直接使用 `datetime.now()`，必须用 dwyeapi 时间模块
+- **禁止**自行 `logging.basicConfig`，必须用 dwyeapi 日志模块
+
+---
+
+## 三、各能力域 dwyeapi 落点
+
+通用规范（路由 / Schema / ORM / 安全编码本身的要求）见 `dwy-python-backend` 对应章节；本节只说明这些规范在团队项目里**必须落到哪个 dwyeapi 模块**。
+
+| 能力 | 团队项目落点 | 对应通用规范 |
+|------|-------------|-------------|
+| 统一响应 / 异常 | dwyeapi 响应模块 + 异常体系（禁自造） | backend 二、五 |
+| 分页 | dwyeapi 分页模块（禁自定义） | backend 二 |
+| ORM 基类 / 时间戳 | 继承 dwyeapi 声明式基类与 Mixin | backend 六 |
+| `get_db` 依赖 | dwyeapi 依赖工厂 | backend 四 |
+| 密码哈希 | dwyeapi 安全模块（bcrypt，禁手写） | backend 7.2 |
+| JWT 创建 / 解码 | dwyeapi 安全模块（禁直接 PyJWT） | backend 7.3 |
+| PII 脱敏 | dwyeapi 脱敏函数 | backend 7.4 |
+| 审计日志 | dwyeapi 日志模块获取审计 logger | backend 7.8 |
+| 业务时间 | dwyeapi 时间模块（禁裸 `datetime.now()`） | backend 六 / 七 |
+| Redis 缓存 | dwyeapi 共享客户端（禁自建连接池） | backend 八 |
+
+> 密码复杂度校验建议下沉到 dwyeapi 提供统一的 `PasswordStr` 类型，避免每个项目重复实现。
+
+---
+
+## 四、违规检测清单（dwyeapi 相关）
+
+通用后端违规清单见 `dwy-python-backend` 第十节；涉及 dwyeapi 必须额外检查：
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| 重复造轮子 | 自造异常基类 / 自封装统一响应 / 手写 bcrypt 或 JWT 调用 / 自建 Redis 连接池 等 dwyeapi 已提供能力 | 高 |
+| 未查 skill | 调用 dwyeapi 能力域却未先查 `dwy-eapi` skill 拿当前 API | 高 |
+| 密码弱存储 | 使用 MD5 / SHA 而非 dwyeapi 安全模块的 bcrypt | **致命 → STOP** |
+| `datetime.now()` 直用 | 业务代码直接 `datetime.now()` 而非走 dwyeapi 时间模块 | 高 |

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

@@ -0,0 +1,49 @@
+---
+description: Python 后端开发避坑清单（FastAPI / SQLAlchemy / async / 依赖 / 部署踩坑），按分类持续追加
+paths:
+  - "**/*.py"
+  - "**/pyproject.toml"
+  - "**/uv.lock"
+---
+
+# Python 开发坑清单
+
+> 动手前先对照本清单避开已知坑；踩到新坑随手按四栏格式（现象 / 根因 / 正确做法 / 适用）追加到对应分类，没有合适分类就新建一个。
+>
+> 通用开发规范见 `dwy-python-core` / `dwy-python-backend` rule，本文件只记**非显而易见的实战坑**。
+
+## 分类索引
+
+- 依赖与环境（uv / venv / 版本）
+- async / 并发（事件循环、阻塞调用、连接池）
+- FastAPI / Pydantic（路由、Schema、校验、序列化）
+- SQLAlchemy / ORM（异步 session、懒加载、事务）
+- 部署与运行时（打包、环境变量、进程模型）
+- 排查方法论
+- 其他分类遇到再加
+
+---
+
+## 依赖与环境
+
+<!-- 待填：踩到坑按四栏格式追加 -->
+
+## async / 并发
+
+<!-- 待填 -->
+
+## FastAPI / Pydantic
+
+<!-- 待填 -->
+
+## SQLAlchemy / ORM
+
+<!-- 待填 -->
+
+## 部署与运行时
+
+<!-- 待填 -->
+
+## 排查方法论
+
+<!-- 待填 -->