create-dwy 0.14.7 → 0.16.0

package/templates/ai-tools/rules/HarmonyOS/dwy-arkts-ui-build.md

@@ -0,0 +1,193 @@
+---
+description: HarmonyOS ArkUI 组件层 / V2 状态管理 / 图标资源 / 工程构建 / 运行时容错避坑（与 dwy-arkts-strict.md 语言层配套）
+paths:
+  - "**/*.ets"
+  - "**/build-profile.json5"
+  - "**/main_pages.json"
+---
+
+# ArkUI / 工程 / 运行时 避坑
+
+`dwy-arkts-strict.md` 管语言语法层；本文件管 **ArkUI 组件、V2 状态管理、资源（图标）、工程构建、运行时容错**。
+均为真机/DevEco 构建实测踩坑（编译期或运行期暴露，命令行 tsc 查不出）。
+
+## 1. sys.symbol 图标名 ≠ SF Symbols 名，必须查鸿蒙清单逐个映射
+
+iOS 用 SF Symbols（`tv.and.mediabox`），鸿蒙 `$r('sys.symbol.xxx')` 是**另一套命名体系**，
+大量 SF 名在鸿蒙不存在，写错报 `Unknown resource name 'xxx'`。
+
+- **权威清单**：`<DevEco-SDK>/openharmony/toolchains/id_defined.json`（约 4000+ 个，`type=symbol`），
+  python 提取后 grep 验证目标名是否存在。
+- **`$r('sys.symbol.x')` 的 x 必须是字面量**，不能用变量动态拼 → 只能逐处改，不能写映射函数。
+- **常见映射**（SF → 鸿蒙）：
+
+  | SF Symbols | 鸿蒙 sys.symbol |
+  |---|---|
+  | tv / tv.and.mediabox | `TV_tv` |
+  | iphone / ipad | `phone` / `pad` |
+  | command | `keyboard` |
+  | cpu / memorychip | `memory_module` |
+  | terminal | `code` |
+  | pencil | `doc_plaintext_and_pencil` |
+  | globe | `globe_and_keyboard` |
+  | tag | `label` |
+  | square.and.arrow.up | `share` |
+  | checkmark.seal.fill | `checkmark_circle_fill` |
+  | stop.fill | `stop_circle_fill` |
+  | shippingbox | `card_package` |
+  | square.stack.3d.up | `AI_square_stack` |
+  | gearshape.fill / house / chevron.left | 同名（`gearshape_fill` / `house` / `chevron_left`，少数直通） |
+
+  写前先 `grep -ix '<候选名>' id_defined.txt` 确认存在，别想当然。
+
+## 2. 自定义组件后不能直接链通用属性（margin/layoutWeight/width…）
+
+自定义 `@Component`/`@ComponentV2`（尤其带尾随 `@BuilderParam` 闭包的）**后面直接链通用属性
+会编译失败**：`Declaration or statement expected` + `Cannot find name 'margin'`。
+
+```typescript
+// 错：HoldRepeatButton 是自定义组件，后链 .margin 解析失败
+HoldRepeatButton({ action: f }) { this.icon() }
+  .margin({ bottom: 184 })
+
+// 对：外层包系统组件（Column/Row/Stack）再链
+Column() {
+  HoldRepeatButton({ action: f }) { this.icon() }
+}.margin({ bottom: 184 })
+```
+
+需要偏移/尺寸时，要么外层包系统容器，要么给自定义组件加 `@Param` 参数在其内部应用。
+
+## 3. 支持本地初始化的组件属性必须有默认值（mandatory-default-value-for-local-initialization）
+
+DevEco **预览器/linter（PreviewBuild）比 assembleHap 更严**，会查这条；assembleHap 不查。
+
+- **`@BuilderParam`** 必须给默认值（默认值是一个全局 `@Builder` 函数）：
+
+  ```typescript
+  @Builder function emptyContent(): void {}
+  @ComponentV2
+  struct Foo {
+    @BuilderParam content: () => void = emptyContent;   // 不能写 `: () => void;`
+  }
+  ```
+
+- **`@CustomDialog` 的 `controller`** 必须可选（否则同报无默认值）：
+
+  ```typescript
+  @CustomDialog
+  struct MyDialog {
+    controller?: CustomDialogController;   // 不能写 `controller: CustomDialogController;`
+  }
+  ```
+  改可选后调用处要用可选链：`this.controller?.close()`（否则 `Object is possibly undefined`）。
+
+- **例外**：`@Require @Param x: T;` 不受此规则约束（`@Require` 表必传，无需默认值）。
+
+## 4. @ComponentV2 外部传入的回调属性必须用 @Param
+
+父组件给子组件传属性（含回调）时，子组件该属性必须 `@Param` 装饰，否则报
+`The 'regular' property 'xxx' cannot be initialized here (forbidden to specify)`：
+
+```typescript
+// 错：onDone 是普通属性，父层 Foo({ onDone: ... }) 传不进
+struct Foo { onDone: () => void = () => {}; }
+// 对
+struct Foo { @Param onDone: () => void = () => {}; }
+```
+
+## 5. async 状态供 UI 同步读：用 @Trace 快照，别在 build 里 await
+
+`build()` 是同步的，UI 不能 `await` 一个 async 方法拿状态（`Property 'kind' does not exist on
+type 'Promise<T>'`）。把异步数据在装配/事件时算好，存进 `@Trace` 快照，UI 同步读快照：
+
+```typescript
+@ObservedV2 class Store {
+  @Trace snapshot: State = defaultState;          // UI 读这个
+  private cache = 0;
+  async start(ctx): Promise<void> {
+    this.cache = await this.loadFromAsset(ctx);    // 异步读一次缓存
+    this.refresh();                                // 用缓存同步算快照
+  }
+  private refresh(): void { this.snapshot = compute(this.cache, Date.now()); }
+}
+```
+
+## 6. 跨模块 import 必须从「声明源」取，不能经中转模块隐式重导出
+
+ArkTS 不支持 TS 的「A 从 B import 某类型，C 再从 A import 同名」隐式重导出：
+`Module '"../X"' declares 'Y' locally, but it is not exported`。**直接从声明 Y 的那个文件 import**。
+
+```typescript
+// 错：AdbTransport 只是 import 了 AdbLog（没 re-export），别处从 AdbTransport 取 AdbLog
+import { AdbLog } from '../adb/AdbTransport';
+// 对：从声明 AdbLog 的源文件取
+import { AdbLog } from '../adb/AdbConnection';
+```
+
+## 7. 工程/资源杂项
+
+- **`Stack` 居中用 `.alignContent(Alignment.X)`**，不是构造参数 `Stack({ alignment: X })`
+  （`'alignment' does not exist in type 'StackOptions'`）。
+- **`SymbolGlyph` 没有 `.textAlign`**：居中靠外层容器的 `justifyContent`/`alignItems`，别链 textAlign。
+- **`build-profile.json5`（entry 模块）顶层字段固定**：apiType/targets/buildOption/buildOptionSet/
+  buildModeBinder/entryModules/apiType 等。塞 `testOption` 之类非法字段报
+  `Schema validate failed`。hypium 测试靠 `src/ohosTest/` 目录约定，不需在 build-profile 配。
+- **退役/不编译的代码移出 `entry/src/main/ets`**（如 spike）：放在 ets 下仍会被编译。
+  移到工程根的 `_archive/` 之类，并从 `main_pages.json` 去掉。
+
+## 8. 运行时：全局状态装配（bootstrap）必须分步容错，不能全有或全无
+
+app 入口的「装配全局状态」若把多个步骤串成一个 `await` 链，**任一步抛异常（尤其模拟器/无账号
+环境下的 IAP、首次无持久化）会让后面全不执行**，导致全局 router/store 为 null，UI 一进就崩
+（`AppContext 未装配` / `Object is possibly undefined`）。
+
+```typescript
+// 错：IAP 在模拟器抛错（如华为 IAP 错误码 27656204）→ router 没装配 → 全崩
+async bootstrap(ctx) {
+  await store.load(ctx);
+  await iap.start(ctx);          // ← 模拟器抛错，下面不执行
+  this.router = new Router(...); // ← 永远到不了
+}
+
+// 对：每步独立容错，核心对象（router）一定装配成功
+async bootstrap(ctx) {
+  await this.safe('存档', () => store.load(ctx));
+  await this.safe('内购', () => iap.start(ctx));   // 失败只 log，降级
+  this.router = new Router(...);                    // 一定执行
+}
+private async safe(name, step) {
+  try { await step(); } catch (e) { console.error(`[${name}]降级: ${(e as Error).message}`); }
+}
+```
+
+模块内部同理：**核心数据（如试用锚点）与非关键外部依赖（如 IAP 查询）分开 try**，
+非关键失败不连累核心，给 UI 一个合理降级默认值。
+
+## 9. DevEco 命令行构建（绕开 IDE，拿带 File:行:列 的错误）
+
+```bash
+NODE=/Applications/DevEco-Studio.app/Contents/tools/node/bin/node
+HVIGOR=/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js
+export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk   # 停 daemon 后必设
+
+# 配置校验
+$NODE $HVIGOR --sync -p product=default --daemon
+# 编译 + 打 HAP（验 ArkTS 编译；产物 entry/build/.../entry-default-unsigned.hap）
+$NODE $HVIGOR assembleHap -p product=default --mode module -p module=entry@default --daemon \
+  2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep "Error Message:"
+# 预览器构建（linter 更严，查 @BuilderParam/controller 默认值等；用独立 .preview 缓存）
+$NODE $HVIGOR --mode module -p module=entry@default -p product=default -p pageType=page \
+  -p previewMode=true -p buildRoot=.preview PreviewBuild --daemon
+```
+
+- **必须 `--daemon`**：DevEco daemon 自动注入 SDK 路径；`--no-daemon` 报 `Invalid DEVECO_SDK_HOME`。
+- **`Error Message:` 才是阻断错误**；`WARN ... may throw exceptions` 是建议，不阻断。
+- **PreviewBuild 用独立 `.preview` 缓存**：改了源码仍报已修错误 → `rm -rf entry/.preview` 重跑。
+- 两种构建都要过：assembleHap（真机包）+ PreviewBuild（linter 严，预览器）。
+
+## 10. 仍需真机确认的（编译/预览过 ≠ 运行对）
+
+见 `dwy-arkts-strict.md` 第 9 条（cryptoFramework 签名规格 / 公钥 DER 格式 / TCPSocket 局域网）。
+补充：手撸 HTTP/2 的 HPACK 全字面量是否被对端（如 grpc-netty）接受、华为 IAP 需 AGC 后台
+配商品 + 真机华为账号、asset/Preferences 在不同设备的可用性，均真机才能定论。

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
+
+<!-- 待填 -->
+
+## 部署与运行时
+
+<!-- 待填 -->
+
+## 排查方法论
+
+<!-- 待填 -->

package/templates/ai-tools/rules/Vue/dwy-vue-base-lib.md

@@ -0,0 +1,127 @@
+---
+description: 团队内部基础库强制复用规范（eui UI 组件 + ekit 工具：禁重复造轮子、HTTP/存储/日期/校验/脱敏走 ekit、UI 走 eui）
+paths:
+  - "**/*.vue"
+  - "**/*.ts"
+---
+
+# Vue 团队基础库强制复用规范
+
+`dwy-vue-core` rule 的团队内补充。通用 Vue 工程规范见 `dwy-vue-core`；本文件只管「凡 eui / ekit 已提供的能力，禁止自行实现，也禁止引入其他库重复造轮子」。
+
+`@dwydev/eui` 与 `@dwydev/ekit` 是团队内部 npm 基础库，分别覆盖 UI 组件层与通用工具层。
+
+---
+
+## 一、必须复用的能力域
+
+| 能力域 | 归属 |
+|--------|------|
+| 通用 UI 组件（Button / Input / Select / Dialog / Drawer / Form / Table 等） | eui |
+| 主题 / 设计 tokens / 暗色模式 | eui |
+| 表单校验（vee-validate + zod 集成） | eui + ekit |
+| 中后台 / 落地页设计规范 | eui（references） |
+| HTTP 客户端（拦截器 / token / 刷新 / 解包） | ekit |
+| 本地存储 / Cookie | ekit（storage / cookie） |
+| 日期 / 时间格式化 | ekit（date） |
+| 数据校验 schema | ekit（validators） |
+| PII 数据脱敏 | ekit（masking） |
+| 剪贴板 / 文件下载 / qs 序列化 | ekit |
+| VueUse 再导出（debounce / throttle / clickOutside / mediaQuery 等） | ekit（hooks） |
+
+### 查阅方式（关键）
+
+**在编写任何 Vue 代码前，以及调用任何 eui / ekit 提供的 API 之前，必须先用 `Skill` 工具加载对应 skill 查阅当前最新接口。** 本文件只规定约束与边界，**不固化**组件 props、函数签名 —— 这些会随版本演进，固化在 rule 里会与实际包不同步。
+
+```
+Skill 工具调用：
+  - skill="dwy-eui"   组件库 API 与设计规范
+  - skill="dwy-ekit"  工具库 API 与契约
+```
+
+---
+
+## 二、强制规则
+
+- **禁止**业务代码出现 `axios` / `fetch` / `new XMLHttpRequest`，HTTP 走 ekit `createRequest`
+- **禁止**直接 `localStorage.getItem` / `setItem` / `removeItem`，走 ekit storage / `useStorage`
+- **禁止**直接 `document.cookie` 或单独引入 `js-cookie`，走 ekit cookie
+- **禁止**业务代码 `new Date()` / `toLocaleString` / 直接 `import dayjs`，走 ekit date
+- **禁止**手写 `navigator.clipboard` / `document.addEventListener('click', ...)` 监听，走 ekit copy / hooks
+- **禁止**自定义已有 UI 组件（Button / Input / Select / Dialog / Form / Table 等），走 eui
+- **禁止**自定义已有日期 / 时间 / 验证 / 脱敏 / 下载 工具函数，走 ekit
+- 涉及任一能力域，**先查 skill 拿到当前 API，再写代码**
+
+---
+
+## 三、API 请求
+
+### 强制规则
+
+- HTTP 客户端**必须**用 ekit `createRequest` 创建，全局唯一实例放 `core/http.ts`（具体参数与插件查 `dwy-ekit` skill）
+- **禁止**业务代码 `axios.create()` / `fetch()` / `new XMLHttpRequest()`
+- 响应解包契约与 dwyeapi 对齐（`{ code, message, data }`），具体类型与守卫查 `dwy-ekit` skill
+- 401 / 422 / 业务错误的统一处理由 ekit request 插件完成（具体 API 查 `dwy-ekit` skill）
+- 业务侧 catch 用 ekit 提供的 `isApiBusinessError` 类型守卫做分支（`NOT_FOUND` / `VALIDATION_ERROR` / `PERMISSION_DENIED` 等）
+
+> API 函数的目录归属、独立导出、类型标注等结构约定见 `dwy-vue-core` 第六节。
+
+### 示例
+
+```typescript
+// core/http.ts —— 全局唯一 HTTP 客户端（具体 plugins 查 dwy-ekit skill）
+import { createRequest } from '@dwydev/ekit'
+
+export const request = createRequest({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  plugins: [
+    /* tokenPlugin / refreshTokenPlugin / unwrapPlugin —— 具体用法查 dwy-ekit skill */
+  ],
+})
+
+// modules/users/api.ts —— 该业务的 API
+import { request } from '@/core/http'
+import type { UserInfo, UserCreate } from './types'
+
+export function getUsers(params: { page: number; page_size: number }) {
+  return request.get<{ items: UserInfo[]; total: number }>('/users', { params })
+}
+
+export function createUser(data: UserCreate) {
+  return request.post<UserInfo>('/users', data)
+}
+```
+
+---
+
+## 四、通用 hooks 走 ekit
+
+通用 hooks（debounce / throttle / clickOutside / mediaQuery 等）**禁止**自己造，走 ekit hooks（具体 API 查 `dwy-ekit` skill）。
+
+---
+
+## 五、样式覆盖 eui
+
+覆盖 eui 内部样式用 scoped CSS + `:deep(...)`（其余样式规范见 `dwy-vue-core` 第八节，优先 Tailwind）。
+
+---
+
+## 六、错误拦截走 ekit
+
+401 / 422 / 业务错误的拦截走 ekit request 插件（查 `dwy-ekit` skill），**禁止**每个 API 都包 try-catch。业务侧统一在页面级或 store 级处理，用 `isApiBusinessError` 守卫分支。
+
+---
+
+## 七、违规检测清单（基础库相关）
+
+AI 编写或审查 Vue 代码时，涉及 eui / ekit 必须检查以下违规模式（通用框架违规清单见 `dwy-vue-core` 第十四节）：
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| 未查 skill | 使用 eui / ekit API 前未先查 `dwy-eui` / `dwy-ekit` skill | 高 |
+| ekit 重复造轮子 | 自造 HTTP / storage / cookie / date / 校验 / 脱敏 等 ekit 已提供能力 | 高 |
+| eui 重复造轮子 | 自造已有 UI 组件（Button / Input / Dialog 等） | 高 |
+| 组件直调 axios | 组件内 `axios.get` / `fetch` / `new XMLHttpRequest` | **致命 → STOP** |
+| 直接 localStorage | `localStorage.getItem` / `setItem` 出现在业务代码 | 高 |
+| 直接 new Date | `new Date()` / `toLocaleString` / 直接 `import dayjs` | 高 |
+| 旧 axios 例子 | 业务里出现 `axios.create()` / `interceptors.request.use(...)` | **致命 → STOP** |