create-dwy 0.14.7 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # create-dwy
 
+## 0.15.0
+
+### Minor Changes
+
+- 新增「产品 0→1」三层 skill 体系（总控 `dwy-product-launcher` + 5 个可独立触发的阶段 skill + 13 个产出物级原子 skill）：从模糊想法渐进式推进到上线产品，立项阶段三道闸门（需求市场验证为总闸门 → 技术 POC → MVP≤7），廉价验证在前、昂贵投入在后。
+- 新增 `dwy skills install` 命令：把 pm-skills / superpowers 的外部 skill 安装到全局 `~/.dwy/skills/`（一台机一份、全项目共享），含完整 `scripts/` 与 LICENSE；再次运行即覆盖更新。`dwy claude sync` 选中相关 skill 时自动自检安装。
+- 外部 skill 进全局纯数据目录而非 `.claude/skills/`，避免被工具当 skill 加载、与 `dwy-*` 触发冲突。
+- 改造 `dwy-whiteboard-prototype`：配色按产品定位推荐（保留 `:root` 语义变量结构）、尺寸按目标端推荐、图标不再用 emoji。
+
 ## 0.14.7
 
 ### Patch Changes

package/bin/index.js

@@ -4,6 +4,7 @@ import { readFileSync } from 'fs'
 import { fileURLToPath } from 'url'
 import { dirname, resolve } from 'path'
 import { syncAll } from '../src/sync-all.js'
+import { installSkills } from '../src/skills-install.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'))
@@ -16,6 +17,7 @@ function printHelp() {
     'Usage:',
     '  dwy               运行交互式同步',
     '  dwy sync          运行交互式同步',
+    '  dwy skills install  安装/更新全局外部 skill 到 ~/.dwy/skills/',
     '  dwy --help        显示本说明',
     '  dwy -h            显示本说明',
     '  dwy --version     显示当前版本',
@@ -29,6 +31,8 @@ if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
   printHelp()
 } else if (argv.includes('--version') || argv.includes('-V')) {
   console.log(pkg.version)
+} else if (argv[0] === 'skills' && argv[1] === 'install') {
+  await installSkills()
 } else if (argv.length === 0 || argv[0] === 'sync') {
   await syncAll()
 } else {

package/package.json

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

package/src/skills-install.js

@@ -0,0 +1,113 @@
+import fs from 'fs-extra'
+import path from 'path'
+import os from 'node:os'
+import { getDwyHomeDir, runGit, chalk } from './utils.js'
+
+function logAction(label) {
+  console.log(chalk.green(`  ✓ ${label}`))
+}
+
+// 产品 0→1 流程依赖的外部 skill 清单。
+// 每项：缓存目录名（= 原子 skill 引用的 ~/.dwy/skills/<name>）→ 来源 repo / stable tag / repo 内目录。
+// 只用正式 release tag，不用 main HEAD（定版可复现）。更新版本时改这里的 tag。
+const SKILL_SOURCES = {
+  'pm-skills': {
+    repo: 'https://github.com/phuryn/pm-skills.git',
+    tag: 'v2.0.0',
+    licenseFile: 'LICENSE',
+    licenseDest: 'LICENSE-pm-skills',
+    skills: {
+      'competitor-analysis': 'pm-market-research/skills/competitor-analysis',
+      'market-sizing': 'pm-market-research/skills/market-sizing',
+      'sentiment-analysis': 'pm-market-research/skills/sentiment-analysis',
+      'interview-script': 'pm-product-discovery/skills/interview-script',
+      'prioritize-features': 'pm-product-discovery/skills/prioritize-features',
+      'opportunity-solution-tree': 'pm-product-discovery/skills/opportunity-solution-tree',
+      'metrics-dashboard': 'pm-product-discovery/skills/metrics-dashboard',
+      'create-prd': 'pm-execution/skills/create-prd',
+      'outcome-roadmap': 'pm-execution/skills/outcome-roadmap',
+      'test-scenarios': 'pm-execution/skills/test-scenarios',
+      'release-notes': 'pm-execution/skills/release-notes',
+      'gtm-strategy': 'pm-go-to-market/skills/gtm-strategy',
+      'intended-vs-implemented': 'pm-ai-shipping/skills/intended-vs-implemented',
+      'north-star-metric': 'pm-marketing-growth/skills/north-star-metric',
+    },
+  },
+  superpowers: {
+    repo: 'https://github.com/obra/superpowers.git',
+    tag: 'v6.0.3',
+    licenseFile: 'LICENSE',
+    licenseDest: 'LICENSE-superpowers',
+    skills: {
+      brainstorming: 'skills/brainstorming',
+      'writing-plans': 'skills/writing-plans',
+      'test-driven-development': 'skills/test-driven-development',
+      'systematic-debugging': 'skills/systematic-debugging',
+    },
+  },
+}
+
+// 全局外部 skill 安装目录：~/.dwy/skills/
+function getGlobalSkillsDir() {
+  return path.join(getDwyHomeDir(), 'skills')
+}
+
+// 浅克隆指定 tag 到临时目录（--depth 1 + --branch <tag> 只取定版，省带宽）。
+async function shallowCloneTag(repoUrl, tag, destDir) {
+  await runGit(['clone', '--depth', '1', '--branch', tag, repoUrl, destDir])
+}
+
+// 安装/更新全部外部 skill 到 ~/.dwy/skills/。再次运行即覆盖式更新。
+export async function installSkills() {
+  const targetDir = getGlobalSkillsDir()
+  await fs.ensureDir(targetDir)
+
+  const tmpRoot = path.join(os.tmpdir(), `dwy-skills-${process.pid}`)
+  await fs.ensureDir(tmpRoot)
+
+  const versions = {}
+  try {
+    for (const [sourceName, src] of Object.entries(SKILL_SOURCES)) {
+      console.log(chalk.gray(`拉取 ${sourceName} @ ${src.tag} ...`))
+      const repoDir = path.join(tmpRoot, sourceName)
+      await shallowCloneTag(src.repo, src.tag, repoDir)
+
+      // 搬 LICENSE（MIT 要求保留原版权声明）
+      const licenseSrc = path.join(repoDir, src.licenseFile)
+      if (await fs.pathExists(licenseSrc)) {
+        await fs.copy(licenseSrc, path.join(targetDir, src.licenseDest), { overwrite: true })
+      }
+
+      // 搬每个 skill 整目录（含 scripts/、配套 .md）
+      for (const [skillName, repoPath] of Object.entries(src.skills)) {
+        const from = path.join(repoDir, repoPath)
+        const to = path.join(targetDir, skillName)
+        if (!await fs.pathExists(from)) {
+          throw new Error(`${sourceName} @ ${src.tag} 内未找到 ${repoPath}（仓库结构可能变了）`)
+        }
+        await fs.remove(to)
+        await fs.copy(from, to, { overwrite: true })
+        logAction(`skills/${skillName}`)
+        versions[skillName] = { repo: src.repo, tag: src.tag }
+      }
+    }
+
+    // 写版本清单，供查看与后续更新比对
+    await fs.writeJson(path.join(targetDir, 'VERSIONS.json'), versions, { spaces: 2 })
+    console.log(chalk.green(`\n✓ 外部 skill 已安装到 ${targetDir}`))
+  } finally {
+    await fs.remove(tmpRoot)
+  }
+}
+
+// 全局 skill 是否已就绪（供 sync 自检：缺则自动装）。
+export async function skillsInstalled() {
+  return fs.pathExists(path.join(getGlobalSkillsDir(), 'VERSIONS.json'))
+}
+
+export async function ensureSkillsInstalled() {
+  if (await skillsInstalled()) return false
+  console.log(chalk.gray('未检测到全局外部 skill，自动安装...'))
+  await installSkills()
+  return true
+}

package/src/sync-all.js

@@ -24,6 +24,14 @@ import {
 } from './sync-codex.js'
 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' },
@@ -690,6 +698,17 @@ 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

@@ -8,7 +8,7 @@
 
 ## 团队执行任务
 
-任务执行必须使用多 Agent 或 agent team 并行提高效率。
+任务执行前必须先分析 block；无 block 的任务使用多 Agent 并行执行以提高效率。
 
 ## 代码注释
 

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

@@ -37,8 +37,16 @@ PATTERNS=(
 # 拼接为正则
 REGEX=$(IFS='|'; echo "${PATTERNS[*]}")
 
-# 扫描暂存内容
-RESULT=$(git diff --cached -U0 2>/dev/null | grep -inE "$REGEX" 2>/dev/null)
+# 只扫「新增行」(+ 开头，排除 +++ 文件头)，删除的代码不可能是正在引入的凭证。
+# 跳过文档/规则类文件(.md/.mdc/规则/hook 本身)——它们写的是「如何检测凭证」的模式说明，非真凭证。
+SCAN_FILES=$(printf '%s\n' "$STAGED" | grep -viE '\.(md|mdc|txt)$|rules/|/hooks/|sensitive-check')
+RESULT=""
+for f in $SCAN_FILES; do
+    HIT=$(git diff --cached -U0 -- "$f" 2>/dev/null \
+        | grep -E '^\+' | grep -vE '^\+\+\+' \
+        | grep -inE "$REGEX" 2>/dev/null)
+    [ -n "$HIT" ] && RESULT="${RESULT}${f}:\n${HIT}\n"
+done
 
 if [ -n "$RESULT" ]; then
     echo "========================================"

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

@@ -0,0 +1,221 @@
+---
+description: HarmonyOS ArkTS 严格性避坑（相对 TS/JS 的禁用语法，编译期 arkts-no-* 报错）
+paths:
+  - "**/*.ets"
+  - "**/*.ts"
+---
+
+# ArkTS 严格性避坑
+
+ArkTS 是 TypeScript 的**受限子集**，禁掉大量 TS/JS 动态写法以换取性能与静态可分析性。
+从 TS/JS（尤其 iOS/前端转鸿蒙）照搬代码必触发 `arkts-no-*` 编译错误。
+**写 `.ets` 前先过一遍本清单**，别用下面列出的禁用写法。每条配真实报错码 + 错误/正确写法。
+
+## 1. 禁止解构声明与解构赋值（arkts-no-destruct-decls / arkts-no-destruct-assignment）
+
+```typescript
+// 错：解构声明
+let [oldR, r] = [a % m, m];
+// 错：解构赋值
+[oldR, r] = [r, oldR - q * r];
+const { value, next } = readVarint(bytes, i);
+
+// 对：拆成单变量 + 临时变量交换
+let oldR = a % m;
+let r = m;
+const tmpR = oldR - q * r;
+oldR = r;
+r = tmpR;
+const res = readVarint(bytes, i);
+const value = res.value;
+const next = res.next;
+```
+
+## 2. 对象字面量必须对应显式 class/interface（arkts-no-untyped-obj-literals / arkts-no-obj-literals-as-types）
+
+ArkTS 不允许「匿名对象字面量当类型」，也不允许「无类型标注的对象字面量」。
+**两种触发场景都要先声明 interface**：
+
+### 2.1 函数返回类型不能写匿名对象
+
+```typescript
+// 错：返回类型是匿名对象字面量
+private static readVarint(bytes: Uint8Array, i: number): { value: number; next: number } { ... }
+
+// 对：先声明 interface
+interface VarintResult {
+  value: number;
+  next: number;
+}
+private static readVarint(bytes: Uint8Array, i: number): VarintResult { ... }
+```
+
+### 2.2 返回 / 赋值的对象字面量必须有类型来源
+
+```typescript
+// 错：裸对象字面量（编译器无法对应到具体类型）
+return { command: c, arg0: a, arg1: b, dataLength: d };
+const out = { header, payload: payload.slice() };
+
+// 对：显式标注类型（interface 已声明）
+const header: AdbHeader = { command: c, arg0: a, arg1: b, dataLength: d };
+return header;
+const out: AdbMessageResult = { header, payload: payload.slice() };
+```
+
+### 2.3 给 SDK API 传对象参数也要带类型
+
+SDK（@ohos.net.socket / cryptoFramework 等）的参数即使是已声明类型，裸字面量仍报错，
+必须用「声明类型的变量」传入：
+
+```typescript
+// 错：裸字面量传参
+await tcp.connect({ address: { address: host, port: 5555, family: 1 }, timeout: 15000 });
+await tcp.send({ data: buf });
+const out = await signer.sign({ data: token });
+
+// 对：拆成带 SDK 类型标注的变量
+const netAddr: socket.NetAddress = { address: host, port: 5555, family: 1 };
+const opts: socket.TCPConnectOptions = { address: netAddr, timeout: 15000 };
+await tcp.connect(opts);
+
+const sendOpts: socket.TCPSendOptions = { data: buf };
+await tcp.send(sendOpts);
+
+const input: cryptoFramework.DataBlob = { data: token };
+const out = await signer.sign(input);
+```
+
+## 3. 禁止用下标访问 string 取字符（arkts-no-props-by-index）
+
+string 不能 `s[i]` 取字符（被判为「字段索引访问」）。用 `charAt`：
+
+```typescript
+// 错
+const table = 'ABCD...';
+out += table[(n >> 18) & 63];
+
+// 对
+out += table.charAt((n >> 18) & 63);
+```
+
+> 注意：`Uint8Array[i]` / `Array[i]` 下标访问是允许的，只有 **string 下标取字符** 被禁。
+
+## 4. 禁止 String() / Number() / Boolean() 当转换函数调用
+
+ArkTS 禁止把内置构造器当函数转换值。catch 错误转文案、数字转字符串都要换写法：
+
+```typescript
+// 错
+const msg = e instanceof Error ? e.message : String(e);
+const s = String(num);
+
+// 对：catch 变量在 ArkTS 里就是 Error（含 BusinessError extends Error），直接取 message
+function errMsg(e: Error): string {
+  return e.message;
+}
+// 数字转字符串用 .toString() 或模板串
+const s = num.toString();
+const s2 = `${num}`;
+```
+
+## 5. Promise executor / 回调形参类型：简单形参标，executor 的 resolve/reject 不标
+
+箭头函数当回调，形参不能省类型；executor 里别把函数直接当回调透传：
+
+```typescript
+// 错：resolve 无类型 + 直接把 resolve 透传给 setTimeout
+return new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// 对：形参标类型 + 包一层箭头
+return new Promise<void>((resolve: () => void) => {
+  setTimeout(() => {
+    resolve();
+  }, ms);
+});
+```
+
+**⚠️ 例外（实测踩坑）：给 `Promise` executor 的 resolve/reject 标注「函数类型」反而触发
+`arkts-no-structural-typing`**。executor 的两个形参类型由 `Promise<T>` 自身约束，显式标
+`(reject: (e: Error) => void)` 会与 SDK 内置的 reject 签名做结构比对而报错。这种情况**去掉
+executor 形参的类型注解，让 ArkTS 推断**（reject 内部传 `Error` 子类实例完全正常）：
+
+```typescript
+// 错：executor 形参标函数类型 → arkts-no-structural-typing
+return new Promise<Uint8Array>(
+  (resolve: (v: Uint8Array) => void, reject: (e: Error) => void) => { ... });
+
+// 对：executor 形参不标，推断
+return new Promise<Uint8Array>((resolve, reject) => {
+  reject(new MyError(...));   // MyError extends Error，正常
+});
+```
+
+判据：**普通回调（如自己定义的 `onError: (e: Error) => void`）形参要标；`new Promise(...)`
+的 executor 形参不标**。另：跨文件传回调时，形参类型用基类（`Error`）而非具体子类
+（`MyGrpcError`），避免「子类型 lambda 赋给基类形参」触发同一规则。
+
+## 6. 页面路由路径不带 `ets/` 前缀
+
+`main_pages.json` 的 `src` 与 `windowStage.loadContent(...)` 的路径都相对 `src/main/ets/` 根，
+**不要带 `ets/` 前缀**，否则编译报 `Page '.../ets/ets/xxx' does not exist`：
+
+```json
+// 错：resources/base/profile/main_pages.json
+{ "src": ["ets/spike/SpikePage"] }
+// 对
+{ "src": ["spike/SpikePage"] }
+```
+
+```typescript
+// 错
+windowStage.loadContent('ets/spike/SpikePage', cb);
+// 对
+windowStage.loadContent('spike/SpikePage', cb);
+```
+
+## 7. 大整数运算用原生 bigint（无需第三方库）
+
+ArkTS 原生支持 ES11 `bigint`（`10n` / `BigInt(x)` / `<< >> % & | ** /`）。
+但无 `.inverse(m)` / `.power(_,modulus:)` / `.serialize()` 这类方法（那是 Swift BigInt 库的），
+模逆/模幂/序列化要**手写**：
+
+```typescript
+// 模幂（快速幂）
+function modPow(base: bigint, exp: bigint, m: bigint): bigint {
+  let result = 1n;
+  let b = base % m;
+  let e = exp;
+  while (e > 0n) {
+    if ((e & 1n) === 1n) { result = (result * b) % m; }
+    e >>= 1n;
+    b = (b * b) % m;
+  }
+  return result;
+}
+// 模逆（扩展欧几里得，见本仓鸿蒙工程 AndroidPubkey.ets）
+```
+
+## 8. 自检清单（写完 .ets 提交前 grep 一遍）
+
+```bash
+grep -rn 'let \[\|const \[' .          # 解构声明
+grep -rn '): {'  .                      # 匿名对象当返回类型
+grep -rn 'return {' .                   # 裸对象字面量返回（确认有类型标注）
+grep -rn 'String(\|Number(\|Boolean(' . # 构造器当转换函数（排除 String.fromCharCode）
+grep -rn 'new Promise<.*>((.*:.*=>' .   # executor 形参标了函数类型（见 §5 例外，应去注解）
+# string 下标取字符需人工核对（table[i] 形式）
+```
+
+## 9. 仍需真机/真实 SDK 确认的（编译期过不代表运行对）
+
+ArkTS 编译通过只保证语法合规；以下 SDK 行为编译期无法验证，需真机/模拟器实测：
+- cryptoFramework 的 `createSign(规格串)` 是否支持目标算法组合（如 `RSA2048|PKCS1|NoHash`）
+- `getEncoded()` 返回的公钥 DER 是 PKCS#1 还是 X.509 SPKI（影响解析）
+- `@ohos.net.socket.TCPSocket` 局域网连通性（需 `ohos.permission.INTERNET`，normal 级安装即授予）
+
+---
+
+> 本文件只管**语言语法层**。ArkUI 组件、V2 状态管理、图标资源、工程构建、运行时容错的坑
+> 见同目录 **`dwy-arkts-ui-build.md`**（图标名映射 / 自定义组件链属性 / @BuilderParam 默认值 /
+> @Param 外部初始化 / async 状态快照 / bootstrap 分步容错 / DevEco 命令行构建）。

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 在不同设备的可用性，均真机才能定论。