create-dwy 0.14.7 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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
+
+- 新增「产品 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'))
@@ -14,13 +15,16 @@ function printHelp() {
     `dwy ${pkg.version}`,
     '',
     'Usage:',
-    '  dwy               运行交互式同步',
-    '  dwy sync          运行交互式同步',
+    '  dwy               运行交互式同步（自动更新全局外部 skill）',
     '  dwy --help        显示本说明',
     '  dwy -h            显示本说明',
     '  dwy --version     显示当前版本',
     '  dwy -V            显示当前版本',
     '',
+    '以下为隐藏命令（向后兼容保留，日常无需手动调用）：',
+    '  dwy sync          同上的别名',
+    '  dwy skills install  强制刷新全局外部 skill',
+    '',
   ]
   console.log(lines.join('\n'))
 }
@@ -29,6 +33,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.16.0",
   "description": "项目脚手架与多平台 AI 配置同步工具",
   "type": "module",
   "bin": {

package/src/skills-install.js

@@ -0,0 +1,154 @@
+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) {
+  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',
+      // 商业分析（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',
+    },
+  },
+  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_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')
+}
+
+// 浅克隆指定 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 }
+      }
+    }
+
+    // 写版本清单 + 清单指纹，供查看与后续更新比对。
+    // 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 是否已就绪（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() {
+  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

@@ -24,6 +24,7 @@ import {
 } from './sync-codex.js'
 import { scanExistingCursorRules, syncCursor } from './sync-cursor.js'
 import { syncOpenCode } from './sync-opencode.js'
+import { ensureSkillsInstalled } from './skills-install.js'
 
 const PLATFORM_OPTIONS = [
   { value: 'claude', label: 'Claude Code', hint: '支持 rules / skills / commands / hooks' },
@@ -559,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),

package/templates/ai-tools/CLAUDE.md

@@ -8,7 +8,7 @@
 
 ## 团队执行任务
 
-任务执行必须使用多 Agent 或 agent team 并行提高效率。
+任务执行前必须先分析 block；无 block 的任务使用多 Agent 并行执行以提高效率。
 
 ## 代码注释
 
@@ -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/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/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/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 命令行构建）。