create-dwy 0.15.0 → 0.16.1

package/src/sync.js

@@ -1,6 +1,11 @@
 import fs from 'fs-extra'
 import path from 'path'
-import { groupMultiselect, isCancel, select } from '@clack/prompts'
+import { isCancel } from '@clack/prompts'
+import {
+  SEARCH_PLACEHOLDER,
+  searchableMultiselect,
+  searchableSelect,
+} from './searchable-select.js'
 import { chalk, DEFAULT_TEMPLATE_REPO_URL, getDwyHomeDir, runGit } from './utils.js'
 
 const CATEGORIES = [
@@ -208,44 +213,42 @@ export async function scanExisting(projectTargetDir, typePlural) {
   return new Set(entries.filter(name => name !== '.gitkeep' && name !== '.DS_Store'))
 }
 
-function buildGroupedOptions(items) {
-  const groups = new Map()
-  for (const item of items) {
-    const category = item.category || '其他'
-    const options = groups.get(category) || []
-    const hint = item.description
-      ? item.description.length > 72
-        ? `${item.description.slice(0, 72)}...`
-        : item.description
-      : undefined
-
-    options.push({
-      value: item.name,
-      label: hint ? `${item.name}（${hint}）` : item.name,
+/**
+ * 将扫描项转为可搜索扁平 options。
+ * label 带分类前缀便于筛选；完整 description 进底部公共说明区（不截断塞 hint）。
+ *
+ * @param {Array<{ name: string, category?: string, description?: string }>} items
+ * @returns {Array<{ value: string, label: string, description?: string }>}
+ */
+function buildSearchableOptions(items) {
+  return items
+    .slice()
+    .sort((a, b) => {
+      const catCmp = (a.category || '其他').localeCompare(b.category || '其他', 'zh')
+      if (catCmp !== 0) return catCmp
+      return a.name.localeCompare(b.name, 'zh')
+    })
+    .map(item => {
+      const category = item.category || '其他'
+      return {
+        value: item.name,
+        label: `${category} / ${item.name}`,
+        // 完整描述给底部公共区；搜索也匹配 description
+        description: item.description || undefined,
+      }
     })
-    groups.set(category, options)
-  }
-
-  return Object.fromEntries(
-    [...groups.entries()]
-      .sort(([a], [b]) => a.localeCompare(b, 'zh'))
-      .map(([category, options]) => [
-        category,
-        options.sort((a, b) => a.label.localeCompare(b.label, 'zh')),
-      ]),
-  )
 }
 
 async function promptSelection(items, label, defaultNames) {
   if (items.length === 0) return []
-  const selectedNames = await groupMultiselect({
+  // 可搜索多选 + 底部说明区（聚焦项描述不跟在行尾）
+  const selectedNames = await searchableMultiselect({
     message: `选择 ${label}`,
-    options: buildGroupedOptions(items),
+    options: buildSearchableOptions(items),
     initialValues: [...defaultNames],
     maxItems: 15,
     required: false,
-    groupSpacing: 1,
-    selectableGroups: true,
+    placeholder: SEARCH_PLACEHOLDER,
   })
   if (isCancel(selectedNames)) return null
   const selectedSet = new Set(selectedNames)
@@ -273,7 +276,8 @@ export async function interactiveSelect(scans, existing) {
 
     const nextLabel = CATEGORIES[i + 1].label
     const prevLabel = i > 0 ? CATEGORIES[i - 1].label : null
-    const nav = await select({
+    // 导航步可搜索单选（选项少，交互与多选一致）
+    const nav = await searchableSelect({
       message: `${label} 已选 ${sel[key].length} 项。下一步：`,
       options: [
         { label: `继续选 ${nextLabel}`, value: 'next' },
@@ -281,6 +285,7 @@ export async function interactiveSelect(scans, existing) {
         { label: '取消同步', value: 'cancel' },
       ],
       initialValue: 'next',
+      placeholder: SEARCH_PLACEHOLDER,
     })
     if (isCancel(nav) || nav === 'cancel') return null
     i = nav === 'back' ? i - 1 : i + 1
@@ -292,7 +297,7 @@ export async function interactiveSelect(scans, existing) {
     for (const { key, label } of CATEGORIES) {
       console.log(chalk.gray(`  ${label.padEnd(10)} ${sel[key].length} 项`))
     }
-    const final = await select({
+    const final = await searchableSelect({
       message: '确认提交还是重选？',
       options: [
         { label: '确认提交', value: 'confirm' },
@@ -300,6 +305,7 @@ export async function interactiveSelect(scans, existing) {
         { label: '取消同步', value: 'cancel' },
       ],
       initialValue: 'confirm',
+      placeholder: SEARCH_PLACEHOLDER,
     })
     if (isCancel(final) || final === 'cancel') return null
     if (final === 'confirm') return sel

package/templates/ai-tools/CHANGELOG.md

@@ -0,0 +1,76 @@
+# ai-tools 内部版本
+
+本目录（`dwy-cli/templates/ai-tools`）rules / skills / hooks / commands / CLAUDE.md 等模板资产的**内部版本**，与 `create-dwy` npm 版本**解耦**。
+
+- 当前版本：见同目录 `VERSION`（单一事实源）
+- 用途：模板变更可追溯；发 `create-dwy` 时可对照本 CHANGELOG 摘发布说明；本地/多仓对照「模板包」新旧
+
+## 维护约定（强制）
+
+**每次**修改本目录下任意内容（含新增 / 删除 / 重命名）时，同一变更必须：
+
+1. 按下方规则 bump `VERSION`
+2. 在本文件**顶部**（当前版本段之上）追加新版本段
+3. 条目写清路径与行为变化，不写空话
+
+禁止：改了模板却不 bump、不写 CHANGELOG。
+
+### 版本号（SemVer，0.x 阶段）
+
+| 级别 | 何时 |
+| ---- | ---- |
+| **MAJOR**（`x.0.0`） | 破坏性：同步目录结构变更、托管块语义不兼容、删除已被广泛依赖的 skill/rule 且无迁移说明 |
+| **MINOR**（`0.y.0`） | 新增 skill / rule / hook / command；既有规范**新增强制约束**或大段能力 |
+| **PATCH**（`0.y.z`） | 文案修正、正反例补充、链接修复、不改变强制语义的小改 |
+
+0.x 阶段允许不稳定；仍用 minor / patch 区分「新增能力」与「修正」。
+
+### 版本段格式
+
+```markdown
+## x.y.z — YYYY-MM-DD
+
+### Added
+- …
+
+### Changed
+- …
+
+### Fixed
+- …
+
+### Removed
+- …
+```
+
+无某类变更可省略对应小节。日期用实际合并/提交日（`YYYY-MM-DD`）。
+
+### 与 create-dwy 的关系
+
+- 改本目录 ≠ 自动发 npm；发布 `create-dwy` 时另走 CLI 发版流程，并在 `dwy-cli/CHANGELOG.md` 摘要用户可感变化
+- 本文件是模板侧明细；CLI CHANGELOG 可只写要点并指向 ai-tools 版本号（如 `ai-tools 0.1.0`）
+
+---
+
+## 0.2.0 — 2026-07-23
+
+### Added
+
+- `skills/运维发布/dwy-deploy-first/`：通用「首次部署」skill（分章）
+  - 第 1 章：镜像源强制配置 — apt → 阿里云；uv/pip → 阿里云 PyPI
+  - 禁止默认 `astral.sh/uv/install.sh`；与 `dwy-mirror-source`（本机工具源）、`dwy-docker`（工程规范）边界划清
+  - `references/chapter-01-mirrors.md`：通用 Dockerfile 片段（Debian/Ubuntu/Alpine + uv/pip）
+
+---
+
+## 0.1.0 — 2026-07-20
+
+### Added
+
+- 建立 ai-tools 内部版本：`VERSION` + 本 `CHANGELOG.md` 及维护约定
+- `skills/元工具/dwy-shared/SKILL.md`：入库流程增加步骤 6.5，改模板必须同批 bump `VERSION` + `CHANGELOG.md`
+- `rules/Android/dwy-android-core.md`：新增「数据实体类封装（强制）」
+  - **Java**：字段 `private`，提供 `getXxx`/`setXxx` 与 `toString`；禁止 public 实例字段
+  - **Kotlin**：优先 `data class` + `val`（自带 `toString`）；禁止 `@JvmField`；非 data class 必须手写 `toString`
+  - 不强制 `equals`/`hashCode`
+  - 联动 §2.6 注释、§八反模式、§九自检项 #22

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/VERSION

@@ -0,0 +1 @@
+0.2.0

package/templates/ai-tools/hook-manifests/hooks.json

@@ -12,5 +12,12 @@
     "matcher": "Bash",
     "platforms": ["claude", "codex"],
     "timeout": 30
+  },
+  {
+    "name": "pre-git-commit-ai-signature-check.sh",
+    "event": "PreToolUse",
+    "matcher": "Bash",
+    "platforms": ["claude", "codex"],
+    "timeout": 30
   }
 ]

package/templates/ai-tools/hooks/Git/pre-git-commit-ai-signature-check.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Claude Code PreToolUse Hook
+# 拦截 git commit message 中的 AI 署名 / 生成声明
+#
+# 背景：AI agent 常在 commit message 中附加 Co-Authored-By: Claude / Generated with Claude Code 等署名。
+# 本 hook 检出此类模式后硬拦截（exit 2），要求人工确认或清理后再提交。
+#
+# 覆盖模式（不区分大小写）：
+#   Co-Authored-By: <ai-name> <noreply@...>
+#   Generated with Claude Code
+#   Generated with ...
+#   noreply@anthropic.com / noreply@openai.com
+#   Claude / ChatGPT / GPT / Copilot / Cursor / AI / LLM (在签名行上下文)
+
+# 从 stdin 读 JSON 取待执行命令（Claude Code 与 Codex 同样通过 stdin 传 .tool_input.command）
+CMD=$(python3 -c 'import sys,json; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))')
+
+# 只在含 git commit 的命令上检查
+printf '%s' "$CMD" | grep -q 'git commit' || exit 0
+
+# AI 署名匹配模式
+AI_PATTERNS=(
+    # Co-Authored-By trailer（任意 AI 名称 + 含 < 的邮箱）
+    "Co-Authored-By:"
+    # 生成声明
+    "Generated with"
+    # 常见 AI 署名邮箱
+    "noreply@anthropic\.com"
+    "noreply@openai\.com"
+    # AI 产品名（在签名行上下文，前面有 Co-Authored-By 或单独出现在行尾）
+    "Co-Authored-By:.*[Cc]laude"
+    "Co-Authored-By:.*[Cc]hatGPT"
+    "Co-Authored-By:.*GPT"
+    "Co-Authored-By:.*[Cc]opilot"
+    "Co-Authored-By:.*[Cc]ursor"
+)
+
+REGEX=$(IFS='|'; echo "${AI_PATTERNS[*]}")
+
+HIT=$(printf '%s' "$CMD" | grep -inE "$REGEX" 2>/dev/null)
+
+if [ -n "$HIT" ]; then
+    echo "========================================"
+    echo "  WARNING: AI 署名 detected"
+    echo "========================================"
+    echo ""
+    echo "$HIT"
+    echo ""
+    echo "commit message 中禁止出现 Co-Authored-By / Generated with 等 AI 署名。"
+    echo "请清理 AI 署名后再提交。"
+    echo ""
+    echo "如果要强制提交，请手动执行 git commit（绕过 hook）。"
+    echo "========================================"
+    exit 2  # 暂停等待人工审批
+fi
+
+exit 0

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

@@ -336,7 +336,7 @@ fun computeDiscount(order: Order): BigDecimal {
 
 ### 2.6 字段 / 属性注释(强制)
 
-公开字段、`data class` 字段、配置常量必须逐个注释。
+公开属性、`data class` 构造参数、配置常量必须逐个注释。**数据实体**除注释外还须遵守 §四「数据实体类封装」:Java 注释写在 **private 字段**上,Kotlin 用 `@property`。
 
 ```kotlin
 /**
@@ -356,6 +356,26 @@ data class User(
 ```
 
 ```java
+/**
+ * 用户信息实体。字段私有,经 getter / setter 访问。
+ */
+public class User {
+    /** 用户 ID,服务端分配,> 0 */
+    private long id;
+    /** 昵称,1-32 字符 */
+    private String name;
+
+    public long getId() {
+        return id;
+    }
+
+    public void setId(long id) {
+        this.id = id;
+    }
+
+    // ... 其余 get/set、toString 见 §四「数据实体类封装」
+}
+
 public final class Constants {
     /** 登录态本地缓存的 SP key,迁移版本时不允许复用此 key,会读到旧数据。 */
     public static final String SP_KEY_LOGIN_TOKEN = "login_token_v2";
@@ -407,7 +427,7 @@ public final class Constants {
 | 有参数 / 返回值 / 异常            | 多行,含 `@param` / `@return` / `@throws`              | ✓   |
 | Activity / Fragment       | 必须注明入口、参数 key、返回结果                                 | ✓   |
 | 回调接口                      | 必须注明触发线程 + 每个参数语义                                  | ✓   |
-| `data class` 字段           | Kotlin `@property`,Java 字段上 `/** */`               | ✓   |
+| `data class` / Java 实体字段  | Kotlin `@property`;Java **private 字段**上 `/** */` + get/set | ✓   |
 | 复杂业务规则                    | 行内注释解释 why + 关联 PRD / 需求号                          | ✓   |
 | 重写方法                      | `@inheritDoc` 或重新写明覆写差异                            | ✓   |
 | Gradle 脚本(Groovy)         | 解释 why:锁版本/exclude 原因、变体用途、自定义 task/方法语义(详见 §2.10) | ✓   |
@@ -533,7 +553,7 @@ public List<Order> findOrders(long userId) {
 
 ### 强制规则
 
-- 公开方法 / 函数参数 ≤ **3 个**,超过则封装为 DTO / `data class`
+- 公开方法 / 函数参数 ≤ **3 个**,超过则封装为 DTO / `data class`(封装出的 DTO **必须**遵守下文「数据实体类封装」)
 - Kotlin 优先**命名参数 + 默认参数**代替方法重载
 - 函数体不超过 **50 行**,超过则拆分
 - 单文件不超过 **500 行**,超过则拆分模块
@@ -636,6 +656,146 @@ for (Order o : orders) {
 }
 ```
 
+### 数据实体类封装(强制)
+
+**动机**:Java 一旦暴露 `public` 字段,调用方直接依赖字段名与访问方式;后续改为 `private` + getter 会破坏源码 / 二进制兼容。实体从一开始就封装,避免后期改结构成本。Kotlin 编译属性本就是 private 字段 + 访问器,规则与 Java 分写,禁止用 `@JvmField` 退化成 public 字段。
+
+#### 适用范围
+
+| 覆盖 | 不覆盖 |
+| ---- | ------ |
+| Model / Entity / DTO / VO / Bean 及同类数据载体 | Activity / Fragment / Adapter / ViewHolder / Repository / ViewModel 等非数据载体 |
+| 含功能包内私有、`internal` 实体 | `enum`;仅含常量的 `object` / `Constants` 类 |
+| 网络响应体、跨层传递的数据对象 | 纯 UI 状态若仅为页面内部临时结构且不跨层,可豁免(跨层则按实体处理) |
+
+#### 共同要求
+
+1. 字段 / 属性**不得**以 public 字段形式对外暴露(禁止 Java `public` 实例字段、禁止 Kotlin `@JvmField`)
+2. 必须提供读取能力:Java `getXxx()`,Kotlin property 访问器
+3. 必须有有意义的 `toString()`(能区分关键业务字段);禁止依赖 `Object` 默认 `ClassName@hash`
+4. **不强制** `equals` / `hashCode`(集合去重 / Map key 场景由调用方按需补)
+
+---
+
+#### Java 规则
+
+| 项 | 要求 |
+| -- | ---- |
+| 字段 | 必须 `private`;禁止 `public` / 包可见实例字段当实体 API |
+| 访问器 | 提供 `getXxx()` / `setXxx()`;不可变实体可用构造注入 + 仅 getter |
+| toString | `@Override public String toString()`,包含关键业务字段 |
+| 注释 | 类级说明职责;每个 private 字段上 `/** */`(见 §2.6) |
+
+```java
+/**
+ * 用户信息实体。
+ *
+ * <p>字段私有 + getter/setter,避免 public 字段导致后续无法安全改结构。
+ */
+public class User {
+    /** 用户 ID,服务端分配,> 0 */
+    private long id;
+    /** 昵称,1-32 字符 */
+    private String name;
+
+    public long getId() {
+        return id;
+    }
+
+    public void setId(long id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public String toString() {
+        return "User{id=" + id + ", name='" + name + "'}";
+    }
+}
+```
+
+```java
+// ❌ public 字段 — 调用方直接 .id,后期改 private 会大面积破坏
+public class User {
+    public long id;
+    public String name;
+}
+
+// ❌ 有 private 字段但缺 toString / 缺访问器
+public class User {
+    private long id;
+    // 无 getId,外部无法读;无 toString,日志只能看到 @hash
+}
+```
+
+---
+
+#### Kotlin 规则
+
+| 项 | 要求 |
+| -- | ---- |
+| 优先写法 | **`data class` + `val`**(编译为 private 字段 + getter;`data class` 自带 `toString`) |
+| 可变字段 | 确需可变用 `var`;仅允许类内改写时用 `private set` |
+| 禁止 | `@JvmField`;Java 风格 public 字段;为 `data class` 再手写冗余 get/set(Java 互操作强制命名除外) |
+| 非 data class | property 或 private 字段 + 访问器,**必须** `override fun toString()` |
+| 注释 | 构造属性用 `@property`,与 §2.6 一致 |
+
+```kotlin
+/**
+ * 用户信息实体。
+ *
+ * @property id 用户 ID,服务端分配,> 0
+ * @property name 昵称,1-32 字符
+ */
+data class User(
+    val id: Long,
+    val name: String,
+)
+// data class 已生成 toString / componentN / copy;JVM 侧字段为 private + getter
+```
+
+```kotlin
+/**
+ * 可编辑的草稿实体。
+ *
+ * 非 data class 时必须手写 toString;title 仅允许类内改写。
+ */
+class Draft {
+    var title: String = ""
+        private set
+
+    /**
+     * 更新草稿标题。
+     *
+     * @param value 新标题,调用方已做长度校验
+     */
+    fun updateTitle(value: String) {
+        title = value
+    }
+
+    override fun toString(): String = "Draft(title=$title)"
+}
+```
+
+```kotlin
+// ❌ @JvmField 把属性暴露成 public 字段,与 Java public 字段同样难改
+class User {
+    @JvmField
+    var id: Long = 0
+}
+
+// ❌ 普通 class 实体无 toString — 日志只有类名@hash
+class User(val id: Long, val name: String)
+// ✅ 改为 data class User(...) 或 override fun toString()
+```
+
 ### 包组织(按功能聚合)
 
 **按功能聚合(package-by-feature),不按技术分层(package-by-layer)。**
@@ -743,6 +903,51 @@ val result = calculate(x)
 
 ## 八、常见反模式(禁止)
 
+### 字符串空判断(强制)
+
+判断字符串是否为空、是否有有效内容时,**禁止**用 `length()` 比较,必须用语义明确的 `isEmpty()` / `isNotEmpty()`(Kotlin 意图为「非空白」时优先 `isNotBlank()`)。
+
+**强制规则**:
+
+- **禁止** `s.length() > 0`、`s.length() == 0`、`s.length() != 0`、`s.trim().length() > 0` 等 `length` 判空写法
+- **必须**用 `isEmpty()` / `!isEmpty()`(Java) 或 `isEmpty()` / `isNotEmpty()`(Kotlin)
+- 需先去首尾空白再判是否有内容:Java `!s.trim().isEmpty()`;Kotlin `s.trim().isNotEmpty()` 或等价的 `s.isNotBlank()`
+- 可空字符串仍先做 null 判断,再判空:`s != null && !s.trim().isEmpty()`(与 §三可空性一致)
+
+```java
+// ❌ 用 length 判「是否有有效内容」——语义弱、易被误读成「长度阈值」
+public String resolveVideoType() {
+    if (videoType != null && videoType.trim().length() > 0) {
+        return videoType.trim();
+    }
+    if (type != null && type.trim().length() > 0) {
+        return type.trim();
+    }
+    return null;
+}
+
+// ✅ 用 isEmpty 表达「非空」
+public String resolveVideoType() {
+    if (videoType != null && !videoType.trim().isEmpty()) {
+        return videoType.trim();
+    }
+    if (type != null && !type.trim().isEmpty()) {
+        return type.trim();
+    }
+    return null;
+}
+```
+
+```kotlin
+// ❌
+if (videoType != null && videoType.trim().length > 0) { ... }
+
+// ✅
+if (!videoType.isNullOrBlank()) { ... }
+// 或需保留 trim 后的值时:
+val trimmed = videoType?.trim().orEmpty()
+if (trimmed.isNotEmpty()) { ... }
+```
 
 | 反模式                                                               | 正确做法                                        |
 | ----------------------------------------------------------------- | ------------------------------------------- |
@@ -761,6 +966,9 @@ val result = calculate(x)
 | 硬编码颜色值 `#FF0000`                                                  | `@color/color_primary`                      |
 | 用户可见文案硬编码                                                         | `@string/...`                               |
 | 单行 `if` / `for` / `while` / `do-while` 无 `{}`(Kotlin 表达式 `if` 除外) | 即使只一行也写 `{}`;详见 §四「控制流大括号」                  |
+| Java 实体 `public` 实例字段                                              | `private` 字段 + `getXxx`/`setXxx` + `toString`            |
+| Kotlin 实体 `@JvmField` / 无 `toString` 的普通 class 实体                 | 优先 `data class` + `val`;或手写访问器 + `toString`          |
+| `s.length() > 0` / `s.trim().length() > 0` 等用 length 判空 / 非空       | Java `!s.isEmpty()` / `!s.trim().isEmpty()`;Kotlin `s.isNotEmpty()` / `s.isNotBlank()`;详见本节「字符串空判断」 |
 
 
 ## 九、代码自检(写代码时强制执行)
@@ -774,7 +982,7 @@ val result = calculate(x)
 | 2   | 方法 / 函数(不分可见性)有 Javadoc / KDoc,含 `@param` / `@return` / `@throws`;一目了然的简单 getter / setter、测试方法可省                                                                                                                          | ✓        |
 | 3   | Activity / Fragment 类注释包含入口、参数 key、返回结果                                                                                                                                                                                   | ✓        |
 | 4   | 回调接口注明每个参数语义 + 触发线程                                                                                                                                                                                                       | ✓        |
-| 5   | `data class` / 公开字段 / 配置常量逐个 `@property` / 字段注释                                                                                                                                                                           | ✓        |
+| 5   | `data class` 属性 / Java 实体 private 字段 / 配置常量逐个 `@property` 或字段注释                                                                                                                                                         | ✓        |
 | 6   | 复杂业务逻辑有"why"行内注释,关联 PRD / 需求号                                                                                                                                                                                             | ✓        |
 | 7   | 注释全部中文,无中英混用,无敷衍式"获取 / 设置 / 处理"                                                                                                                                                                                           | ✓        |
 | 8   | 注释与代码同步更新,无过时注释                                                                                                                                                                                                           | ✓        |
@@ -791,6 +999,9 @@ val result = calculate(x)
 | 19  | `if` / `else` / `else if` / `for` / `while` / `do-while` 语句即使单行也带 `{}`(Kotlin 表达式 `if` 除外)                                                                                                                                | ✓        |
 | 20  | 新增类按**功能聚合**放对应功能包(`login/` / `order/`),不按 `activities/` / `models/` 分层横切;仅多功能共享才放 `common/`                                                                                                                              | ✓        |
 | 21  | Gradle 脚本(Groovy / kts):锁版本 / `exclude` / 自定义 task / 变体 / 关键魔法值有 why 注释,无复述式、无注释掉的配置块                                                                                                                                     | ✓        |
+| 22  | 数据实体(Model/DTO/VO/Bean 等):Java 字段 `private` + get/set + `toString`;Kotlin 优先 `data class`+`val`(自带 toString),禁止 `@JvmField`,非 data class 必须手写 `toString`                                                                              | ✓        |
+| 23  | 字符串空判断用 `isEmpty` / `isNotEmpty` / `isNotBlank`,禁止 `length() > 0` / `== 0` / `!= 0` 及 `trim().length() > 0` 判空;详见 §八「字符串空判断」                                                                                                      | ✓        |
 
 
 **不执行自检就提交代码 = 违规。**
+

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
+
+<!-- 待填 -->
+
+## 排查方法论
+
+<!-- 待填 -->