create-dwy 0.16.0 → 0.16.1

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

@@ -0,0 +1,139 @@
+---
+description: HarmonyOS ArkUI UI 设计与交互规范（弹层/顶栏/加载态/图标语义，事前约束，避免 bindSheet 重叠等坑）
+paths:
+  - "**/*.ets"
+---
+
+# ArkUI UI 设计规范
+
+与 `dwy-arkts-ui-build.md`（怎么编译/踩过哪些 API 坑）配套：本文件管 **长什么样、交互怎么关、加载怎么显**。
+写页面 / sheet **先按本规范搭骨架**，再写业务。踩到新 UI 坑：先记 `dwy-harmony-pitfalls.md`，再回写本文件。
+
+## 1. 分层约定
+
+| 层 | 职责 | 典型 API |
+|---|---|---|
+| 系统 chrome | 系统提供的关闭/拖拽指示 | `bindSheet` 的 `showClose`、下拉关闭 |
+| 内容顶栏 | 标题 + 业务操作 +（可选）自绘关闭 | `SheetHeader` / 自绘 `Row` |
+| 内容区 | 表单、列表、图 | 业务组件 |
+
+**硬规则：系统关闭钮与内容自绘「关弹层」× 禁止同时出现。**
+
+## 2. bindSheet 关闭策略（二选一）
+
+### 2.1 模式 A：自绘关闭（工具页 / 表单 / 顶栏有右侧操作）
+
+适用：Shell、进程、性能、调试、代理、录屏、快捷指令、设备编辑、**配对弹层**、设备信息（有「复制全部」等）。
+
+```ets
+.bindSheet(this.open, this.content(), {
+  detents: [SheetSize.LARGE],
+  backgroundColor: Palette.device,
+  showClose: false, // 必须关系统 ×
+  onDisappear: () => { this.open = false; },
+})
+
+@Builder
+content(): void {
+  FooPage({ onClose: () => { this.open = false; } })
+}
+```
+
+内容顶栏结构（从左到右）：
+
+```
+[ 标题（layoutWeight 1，单行省略） ] [ 可选业务按钮 ] [ 关闭 × ]
+```
+
+- 关闭用 `sys.symbol.xmark`，固定触控约 `36×36`，勿与分段按钮同一 `Row` 抢宽。
+- 分段 / Tab 切换放在 **顶栏下一行**，整行 `width('100%')`，不得伸进系统 chrome 区域。
+
+### 2.2 模式 B：仅系统关闭（纯浏览 / 轻列表）
+
+适用：语言选择、截图预览、无业务顶栏操作的列表。
+
+```ets
+.bindSheet(this.open, this.content(), {
+  showClose: true,
+  onDisappear: () => { this.open = false; },
+})
+```
+
+- 内容 **禁止** 再画关闭 ×。
+- 顶栏右侧 **禁止** 放会与系统 × 重叠的控件（可放在内容区下方或用「完成」文字按钮在底部）。
+
+### 2.3 禁止
+
+| 禁止 | 原因 |
+|---|---|
+| `showClose: true` + `SheetHeader` / 自绘 × | 双 × 重叠 |
+| `showClose` 省略 + 自绘 × | 默认常带系统 ×，仍重叠 |
+| 系统 × 与「新增 / 复制全部 / 分段 Tab」同一视觉行 | 贴边、难点 |
+| 关闭回调空实现（`onClose` 未注入） | × 点了无反应 |
+
+## 3. 图标语义（禁止混用）
+
+| 语义 | 推荐符号 | 禁止 |
+|---|---|---|
+| 关弹层 | `xmark`（顶栏） | 与「清空」共用同一位置无说明 |
+| 清空输入 | `xmark_circle_fill`（输入框旁） | 当成关 sheet |
+| 返回上一页 | `chevron_left`（`PageHeaderBar`） | 用 × 表示返回 |
+| 删除 | `trash` | 用 × 表示删除条目 |
+
+输入弹层（键盘）：**关 sheet 用模式 B（系统 ×）**；清空用输入框旁圆形 ×，注释写明「清空非关闭」。
+
+## 4. 加载与空态（禁止永久 spinner）
+
+异步出图 / 出列表必须三态：
+
+| 状态 | UI |
+|---|---|
+| 加载中 | `LoadingProgress`（限在固定占位区域内） |
+| 成功 | 内容（图 / 列表） |
+| 失败 | 文案说明 + 可选重试；**禁止**继续转圈 |
+
+二维码 / 图片：
+
+1. 优先系统能力（如 ScanKit）。
+2. 失败必须有 **可见兜底**（纯逻辑绘制 / 占位文案），不能空白。
+3. 占位区 **固定宽高**，避免生成前后布局跳动。
+
+## 5. 顶栏与安全区
+
+- **Push 页**：`PageHeaderBar`（返回 + 标题 + trailing），前景在安全区内。
+- **Sheet**：见 §2；全屏背景可用，主交互勿进系统手势死角。
+- 标题：`maxLines(1)` + `TextOverflow.Ellipsis`，避免长文案挤掉按钮。
+- 触控目标：主要按钮高度建议 ≥ 40；图标按钮约 36×36。
+
+## 6. 布局与间距（基线）
+
+- 页面水平 padding 统一 **16 / 20**（工具页内容区常用 16–20）。
+- 卡片圆角与描边走 **设计 token**（如 `Palette.surface2` + `hairline`），禁止业务页散落硬编码色。
+- 列表/宫格：用 `List` / `Grid` + 间距系统，不用绝对 `offset` 拼主布局。
+- 固定视觉比例控件（二维码、D-pad）可用固定边长，**外层容器仍自适应宽度**。
+
+## 7. 颜色与动效
+
+- 颜色只从 `Palette`（或项目 token）取，禁止裸 `0xFF...` 散落业务页（生成图 RGBA 缓冲区除外）。
+- 动效优先项目统一 spring / 系统默认；新增动画参数与现有 `Motion` 一致。
+- 强调色用于主按钮；关闭/次要操作用 `Palette.sub`，删除用 `Palette.red`。
+
+## 8. 文案与国际化
+
+- 所有用户可见文案走 `loc('key')` + 资源表，禁止硬编码中文/英文（调试日志除外）。
+- 新 key 至少补齐 **开发语言 + en**；其它语言可后续补。
+
+## 9. 自检清单（PR / 提交前）
+
+- [ ] 每个 `bindSheet` 已显式 `showClose: true` 或 `false`（不省略）。
+- [ ] 自绘 × 的 sheet 已 `showClose: false` 且 `onClose` 接通。
+- [ ] 系统 × 的 sheet 内容无第二颗关闭钮、右侧无抢位控件。
+- [ ] 异步区有失败态，无永久 spinner。
+- [ ] 出码/出图有 ScanKit 失败兜底（若依赖）。
+- [ ] 图标名在 `id_defined.json` 存在（见 ui-build §1）。
+- [ ] 文案全部 `loc`。
+
+## 10. 与 iOS 对照时注意
+
+- iOS `sheet` + 导航栏 toolbar 关闭 ≠ 鸿蒙默认 `showClose`；移植时 **重新选 §2 模式**，不要两端各画一套再叠系统。
+- SF Symbols 名不能直接当 `sys.symbol`（见 ui-build §1）。

package/templates/ai-tools/rules/HarmonyOS/dwy-harmony-pitfalls.md

@@ -0,0 +1,72 @@
+---
+description: 鸿蒙踩坑四栏归档（现象/根因/正确做法/适用）。事前规范见 dwy-arkts-ui-design / dwy-arkts-ui-build / dwy-arkts-strict
+paths:
+  - "**/*.ets"
+  - "**/build-profile.json5"
+---
+
+# 鸿蒙开发坑清单（归档）
+
+> **事前约束**请先读：
+>
+> | 文件 | 用途 |
+> |---|---|
+> | `dwy-arkts-strict.md` | 语言禁用语法 |
+> | `dwy-arkts-ui-build.md` | 组件 API / 构建 / 设备与运行时 |
+> | `dwy-arkts-ui-design.md` | UI 弹层/顶栏/加载态规范 |
+>
+> 本文件只记 **已踩过的坑**（四栏）。新坑：先按格式追加 → 再把「正确做法」回写到对应规范文件，避免规范与归档脱节。
+
+## 分类索引
+
+- ArkUI 弹层 / 出码
+- 工程与设备网络
+
+---
+
+## ArkUI 弹层 / 出码
+
+### bindSheet 系统 × 与内容自绘 × / 顶栏按钮重叠
+
+- **现象**：右上两颗 ×，或系统 × 与「扫码/配对码」「新增」「复制全部」贴在一起。
+- **根因**：`showClose` 与内容自绘关闭/右侧操作同区叠放。
+- **正确做法**：见 `dwy-arkts-ui-design.md` §2（二选一）；禁止省略 `showClose`。
+- **适用**：所有 `bindSheet`。
+
+### 内容区 × 是清空不是关 sheet
+
+- **现象**：键盘输入框旁 × 被当成关弹层。
+- **根因**：语义是清空输入。
+- **正确做法**：见 `dwy-arkts-ui-design.md` §3。
+- **适用**：Keyboard / 搜索。
+
+### ScanKit 二维码模拟器空白 + 永久 spinner
+
+- **现象**：配对扫码页只转圈，无码图。
+- **根因**：HVD 上 `generateBarcode` 常失败；失败 UI 仍 loading。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §14 + `dwy-arkts-ui-design.md` §4（兜底出图 + 三态）。
+- **适用**：出码展示。
+
+---
+
+## 工程与设备网络
+
+### unsigned.hap 真机装不上
+
+- **现象**：CLI 打包成功，真机安装失败。
+- **根因**：未配置 `signingConfigs`。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §11。
+- **适用**：真机分发。
+
+### 模拟器代理设置无法让 ADB 连局域网电视
+
+- **现象**：在 HVD「代理设置」里配代理/DNS，仍连不上 `192.168.x.x:5555`。
+- **根因**：代理只走 HTTP 出网；app 用原始 TCP；HVD 为 NAT 非 LAN peer。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §13；真机同 Wi-Fi。
+- **适用**：局域网调试类产品。
+
+### HVD 命令行启停
+
+- **现象**：不会脱离 IDE 起模拟器。
+- **正确做法**：见 `dwy-arkts-ui-build.md` §12。
+- **适用**：脚本化调试。

package/templates/ai-tools/rules/iOS/dwy-ios-pitfalls.md

@@ -157,3 +157,10 @@ paths:
 - **根因**：`switch` 在视图树里每次只保留当前 case 的子树，切 tab 时 SwiftUI **销毁**旧 tab 视图、**重建**新 tab 视图，`@State` 随之重置。它不是缓存容器。
 - **正确做法**：用系统 `TabView(selection:)` + 每页 `.tag(...)`。TabView 保活所有 tab 页，切换只是显隐，状态天然保留。隐藏系统 tab bar（`.toolbar(.hidden, for: .tabBar)`）后用自绘底栏，`selection` 与自绘栏共用同一 `@State`。注意别用 `.tabViewStyle(.page)`（会引入左右滑动切页，与边缘返回手势冲突）。
 - **适用**：iOS 16+ SwiftUI 多 tab 且需保留各 tab 页内状态时。
+
+### Mac（Designed for iPhone/iPad）上 sheet 不继承 Observable environment，弹层即崩
+
+- **现象**：iPhone 真机正常；把 iOS app 装到 macOS（「在 Mac 上使用 iPhone/iPad App」）后，一点「解锁」/付费墙/编辑设备/键盘 sheet 就崩。崩溃报告 `EXC_BREAKPOINT` / `SIGTRAP`，栈顶 `libswiftCore _assertionFailure` → `SwiftUICore EnvironmentValues.subscript.getter` → `SheetBridge.present` / `PresentationHostingController`。应用日志只到 `app 启动`。
+- **根因**：`@Environment(Store.self)` / `@Environment(AppRouter.self)` 在未注入时会 fatal。iPhone 上 sheet 内容通常继承父树的 `.environment(...)`；Mac 上 UIKitMacHelper 走 `PresentationHostingController`，**不把父视图的 Observable environment 传进 sheet**，于是 `PaywallView` 等一 present 就 assertionFailure。
+- **正确做法**：凡 sheet / fullScreenCover 内容里读了 `@Environment(SomeObservable.self)`，在 content 上**显式** `.environment(store)` / `.environment(router)` 重注入，不要依赖继承。嵌套 sheet 同样要再注一次。例：`PaywallView().environment(store)`、`DeviceEditSheet(...).environment(router)`、`KeyboardSheet().environment(router)`。
+- **适用**：iOS 17+ `@Observable` + `.environment(instance)`，且 app 会在 Mac 上以 Designed for iPhone/iPad 运行时。iPhone 上不重注入多数也能跑，但为跨平台一致应一律重注入。

package/templates/ai-tools/rules//345/274/200/345/217/221/346/265/201/347/250/213/dwy-git-commit.md

@@ -135,16 +135,19 @@ Scope 由 AI 根据变更模块与项目语义自行决定，保持与现有提
 
 ## 8. AI 署名与生成声明治理
 
-commit 的 subject、body、footer、trailer 中禁止出现：
+commit 的 subject、body、footer、trailer 中禁止出现任何形式的 AI 署名或生成声明。AI 应自行判断：凡由 AI 工具（Claude、ChatGPT、GPT、Copilot、Cursor、Gemini、Llama、LLM 等）生成或参与撰写的署名、尾随声明、自动生成标记，均不得写入 commit message。
 
-- `Co-Authored-By: Claude ...`
-- `Generated with Claude Code`
-- `Generated with ...`
-- `Claude`、`ChatGPT`、`GPT`、`Copilot`、`Cursor`、`AI`、`LLM`
-- `noreply@anthropic.com`、`noreply@openai.com`
+包括但不限于：
+
+- `Co-Authored-By: <AI 名称> <noreply@...>`（任何 AI 产品 + 邮箱组合）
+- `Generated with Claude Code` / `Generated with ...`（任何"由 XX 生成"声明）
+- 含 AI 产品名的署名行（Claude、ChatGPT、GPT、Copilot、Cursor、Gemini、LLM 等）
+- AI 平台noreply 邮箱（noreply@anthropic.com、noreply@openai.com 等）
 
 `git commit -m "..."` 不得附带 AI 署名 trailer。
 
+> PreToolUse hook `pre-git-commit-ai-signature-check.sh` 会在 commit message 中检出 Co-Authored-By / Generated with 等 AI 署名模式时硬拦截（exit 2），规则约束 + 工程兜底双保险。
+
 ## 9. 参考示例
 
 - `feat(eui): 添加 Image 组件懒加载支持`