create-dwy 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# create-dwy
+
+## 0.13.2
+
+### Patch Changes
+
+- 新增顶层命令 `dwy sync`，一次选择后同时同步 Claude Code 与 Codex 配置。
+- `dwy sync -i` 支持重新交互式选择；`dwy sync --dry-run` 支持预演；`dwy sync md` 同步 `CLAUDE.md` 到 `~/.claude/CLAUDE.md` 和 `~/.codex/AGENTS.md`。
+- 复用现有 `dwy claude sync` / `dwy codex sync` 的扫描、缓存选择、删除未选模板项和写入逻辑；`commands` 仅同步到 `.claude/commands`，`skills` / `rules` / `hooks` 同步到两端。
+- 新增 CLI 聚合同步回归测试，覆盖一次缓存选择同时写入 `.claude`、`.agents`、`.codex` 和 `AGENTS.md`。

package/bin/index.js

@@ -7,6 +7,7 @@ import { program } from 'commander'
 import { createProject } from '../src/create.js'
 import { syncClaude } from '../src/sync.js'
 import { syncCodex } from '../src/sync-codex.js'
+import { syncAll } from '../src/sync-all.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'))
@@ -18,6 +19,9 @@ program
   .addHelpText('after', `
 Examples:
   $ dwy create my-app              创建新项目
+  $ dwy sync                       同步 Claude Code 与 Codex 配置（只选择一次）
+  $ dwy sync -i                    重新交互式选择后同步到 Claude Code 与 Codex
+  $ dwy sync md                    同步 CLAUDE.md 到 ~/.claude/ 与 ~/.codex/AGENTS.md
   $ dwy claude sync                同步 Claude 配置（基于已选覆盖）
   $ dwy claude sync -i             重新交互式选择
   $ dwy claude sync --dry-run      预演同步，不写入文件
@@ -37,6 +41,20 @@ Examples:
   $ dwy create my-app
 `)
 
+program
+  .command('sync [target]')
+  .description('同步 Claude Code 与 Codex 配置（target=md 时同步 CLAUDE.md 到两个全局目录）')
+  .option('-i, --reselect', '忽略已选缓存，重新交互式选择（已选项默认勾选）')
+  .option('--dry-run', '预演模式，不实际写入文件')
+  .action((target, opts) => syncAll({ target, ...opts }))
+  .addHelpText('after', `
+Examples:
+  $ dwy sync                       基于已选覆盖同步到 Claude Code 与 Codex
+  $ dwy sync -i                    重新交互式选择一次，同步到两端
+  $ dwy sync --dry-run             预演，不写入文件
+  $ dwy sync md                    同步 CLAUDE.md 到 ~/.claude/ 与 ~/.codex/AGENTS.md
+`)
+
 const claudeCmd = program
   .command('claude')
   .description('Claude Code 配置管理')

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "create-dwy",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "项目脚手架与 Claude Code 配置同步工具",
   "type": "module",
   "bin": {
     "dwy": "./bin/index.js"
   },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
   "files": [
+    "CHANGELOG.md",
     "bin",
     "src",
     "templates"
@@ -32,4 +36,4 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   }
-}
+}

package/src/sync-all.js

@@ -0,0 +1,154 @@
+import fs from 'fs-extra'
+import path from 'path'
+import inquirer from 'inquirer'
+import { chalk } from './utils.js'
+import {
+  interactiveSelect,
+  resolveSourceDir,
+  scanCommands,
+  scanExisting,
+  scanHooks,
+  scanRules,
+  scanSkills,
+  syncClaude,
+} from './sync.js'
+import {
+  parseManagedRuleNames,
+  scanExistingCodexHooks,
+  scanExistingCodexSkills,
+  syncCodex,
+} from './sync-codex.js'
+
+function unionSets(...sets) {
+  return new Set(sets.flatMap(set => [...set]))
+}
+
+function selectFromExisting(scans, existing) {
+  return {
+    skills: scans.skills.filter(item => existing.skills.has(item.name)),
+    rules: scans.rules.filter(item => existing.rules.has(item.name)),
+    commands: scans.commands.filter(item => existing.commands.has(item.name)),
+    hooks: existing.hooks.size > 0
+      ? scans.hooks.filter(item => existing.hooks.has(item.name))
+      : scans.hooks,
+  }
+}
+
+async function scanCombinedExisting(projectDir) {
+  const claudeDir = path.join(projectDir, '.claude')
+  const agentsMdPath = path.join(projectDir, 'AGENTS.md')
+  const agentsMdContent = await fs.pathExists(agentsMdPath) ? await fs.readFile(agentsMdPath, 'utf-8') : ''
+
+  return {
+    skills: unionSets(
+      await scanExisting(claudeDir, 'skills'),
+      await scanExistingCodexSkills(projectDir),
+    ),
+    rules: unionSets(
+      await scanExisting(claudeDir, 'rules'),
+      parseManagedRuleNames(agentsMdContent),
+    ),
+    commands: await scanExisting(claudeDir, 'commands'),
+    hooks: unionSets(
+      await scanExisting(claudeDir, 'hooks'),
+      await scanExistingCodexHooks(projectDir),
+    ),
+  }
+}
+
+async function shouldInitialize(projectDir, existing) {
+  const hasAnyExisting = existing.skills.size + existing.rules.size + existing.commands.size + existing.hooks.size > 0
+  if (hasAnyExisting) return true
+
+  const hasConfigDir = await fs.pathExists(path.join(projectDir, '.claude'))
+    || await fs.pathExists(path.join(projectDir, '.codex'))
+    || await fs.pathExists(path.join(projectDir, '.agents'))
+
+  if (hasConfigDir) return true
+
+  const { ok } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'ok',
+    message: `当前目录 ${chalk.yellow(projectDir)} 尚无 Claude Code/Codex 配置，是否在此初始化？`,
+    default: false,
+  }])
+  return ok
+}
+
+export async function syncAll({
+  target,
+  reselect = false,
+  dryRun = false,
+  sourceDir: sourceDirOverride,
+  projectDir: projectDirOverride,
+} = {}) {
+  const sourceDir = sourceDirOverride || await resolveSourceDir()
+  if (!await fs.pathExists(sourceDir)) {
+    console.error(chalk.red('Error: claude-global templates not found in repo'))
+    process.exit(1)
+  }
+
+  if (target === 'md') {
+    await syncClaude({ target, dryRun, sourceDir })
+    await syncCodex({ target, dryRun, sourceDir })
+    return
+  }
+
+  if (target !== undefined) {
+    console.error(chalk.red(`Error: unknown sync target "${target}". Supported: (none) | md`))
+    process.exit(2)
+  }
+
+  const projectDir = projectDirOverride || process.cwd()
+
+  console.log(chalk.blue('\nScanning available Claude Code/Codex configuration...\n'))
+  const scans = {
+    skills: await scanSkills(sourceDir),
+    rules: await scanRules(sourceDir),
+    commands: await scanCommands(sourceDir),
+    hooks: await scanHooks(sourceDir),
+  }
+  console.log(chalk.yellow(`Found ${scans.skills.length} skills, ${scans.rules.length} rules, ${scans.commands.length} commands, ${scans.hooks.length} hooks\n`))
+
+  const existing = await scanCombinedExisting(projectDir)
+  if (!await shouldInitialize(projectDir, existing)) {
+    console.log(chalk.yellow('\n已取消同步。'))
+    return
+  }
+
+  const hasAnyExisting = existing.skills.size + existing.rules.size + existing.commands.size + existing.hooks.size > 0
+  let selected
+  if (!reselect && hasAnyExisting) {
+    selected = selectFromExisting(scans, existing)
+    console.log(chalk.gray('使用已选覆盖同步（如需调整请加 -i / --reselect）：'))
+    console.log(chalk.gray(`  ${selected.skills.length} skills, ${selected.rules.length} rules, ${selected.commands.length} commands, ${selected.hooks.length} hooks\n`))
+  } else {
+    if (!reselect && !hasAnyExisting) console.log(chalk.gray('首次同步，进入交互式选择...\n'))
+    const result = await interactiveSelect(scans, existing)
+    if (result === null) {
+      console.log(chalk.yellow('\n已取消同步。'))
+      return
+    }
+    selected = result
+  }
+
+  console.log(chalk.blue('\nSyncing Claude Code configuration...\n'))
+  await syncClaude({
+    sourceDir,
+    projectDir,
+    selected,
+    reselect,
+    dryRun,
+    skipInitPrompt: true,
+  })
+
+  console.log(chalk.blue('\nSyncing Codex configuration...\n'))
+  await syncCodex({
+    sourceDir,
+    projectDir,
+    selected,
+    reselect,
+    dryRun,
+    skipInitPrompt: true,
+  })
+}

package/src/sync-codex.js

@@ -54,7 +54,7 @@ async function ruleToSection(ruleItem) {
   return [marker, title, scopeLine, body].filter(Boolean).join('\n\n')
 }
 
-function parseManagedRuleNames(content) {
+export function parseManagedRuleNames(content) {
   const block = content.match(BLOCK_RE)
   if (!block) return new Set()
   const names = new Set()
@@ -94,7 +94,7 @@ async function syncRulesToAgentsMd(selectedRules, proj, dryRun) {
 
 // ---------- skills → .agents/skills/ ----------
 
-async function scanExistingCodexSkills(proj) {
+export async function scanExistingCodexSkills(proj) {
   const dir = path.join(proj, '.agents', 'skills')
   if (!await fs.pathExists(dir)) return new Set()
   const entries = await fs.readdir(dir, { withFileTypes: true })
@@ -129,7 +129,7 @@ async function removeUnselectedFlat(subdir, existingNames, selectedNames, templa
 
 // ---------- hooks → .codex/ ----------
 
-async function scanExistingCodexHooks(proj) {
+export async function scanExistingCodexHooks(proj) {
   const dir = path.join(proj, '.codex', 'hooks')
   if (!await fs.pathExists(dir)) return new Set()
   const entries = await fs.readdir(dir)
@@ -258,8 +258,16 @@ async function interactiveSelect(scans, existing) {
  *   target=undefined  同步到项目：rules→AGENTS.md / skills→.agents/skills / hooks→.codex
  *   target='md'       仅同步 CLAUDE.md → 全局 ~/.codex/AGENTS.md
  */
-export async function syncCodex({ target, reselect = false, dryRun = false } = {}) {
-  const claudeGlobal = await resolveSourceDir()
+export async function syncCodex({
+  target,
+  reselect = false,
+  dryRun = false,
+  sourceDir: sourceDirOverride,
+  projectDir,
+  selected: selectedOverride,
+  skipInitPrompt = false,
+} = {}) {
+  const claudeGlobal = sourceDirOverride || await resolveSourceDir()
   if (!await fs.pathExists(claudeGlobal)) {
     console.error(chalk.red('Error: claude-global templates not found in repo'))
     process.exit(1)
@@ -289,7 +297,7 @@ export async function syncCodex({ target, reselect = false, dryRun = false } = {
 
   const codexGlobal = path.join(claudeGlobal, '..', 'codex-global')
   const hooksJsonSrc = path.join(codexGlobal, 'hooks.json')
-  const proj = process.cwd()
+  const proj = projectDir || process.cwd()
 
   console.log(chalk.blue('\nScanning available config for Codex...\n'))
 
@@ -309,7 +317,11 @@ export async function syncCodex({ target, reselect = false, dryRun = false } = {
   }
   const hasAnyExisting = existing.skills.size + existing.rules.size + existing.hooks.size > 0
 
-  if (!hasAnyExisting && !await fs.pathExists(path.join(proj, '.codex')) && !await fs.pathExists(path.join(proj, '.agents'))) {
+  if (!selectedOverride
+      && !skipInitPrompt
+      && !hasAnyExisting
+      && !await fs.pathExists(path.join(proj, '.codex'))
+      && !await fs.pathExists(path.join(proj, '.agents'))) {
     const { ok } = await inquirer.prompt([{
       type: 'confirm',
       name: 'ok',
@@ -323,7 +335,14 @@ export async function syncCodex({ target, reselect = false, dryRun = false } = {
   }
 
   let selected
-  if (!reselect && hasAnyExisting) {
+  if (selectedOverride) {
+    const selectedNames = key => new Set((selectedOverride[key] || []).map(item => item.name))
+    selected = {
+      skills: scans.skills.filter(item => selectedNames('skills').has(item.name)),
+      rules: scans.rules.filter(item => selectedNames('rules').has(item.name)),
+      hooks: scans.hooks.filter(item => selectedNames('hooks').has(item.name)),
+    }
+  } else if (!reselect && hasAnyExisting) {
     selected = {
       skills: scans.skills.filter(s => existing.skills.has(s.name)),
       rules: scans.rules.filter(r => existing.rules.has(r.name)),

package/src/sync.js

@@ -103,7 +103,7 @@ export async function scanRules(sourceDir) {
   return rules.sort((a, b) => a.name.localeCompare(b.name))
 }
 
-async function scanCommands(sourceDir) {
+export async function scanCommands(sourceDir) {
   const commandsDir = path.join(sourceDir, 'commands')
   if (!await fs.pathExists(commandsDir)) return []
 
@@ -163,7 +163,7 @@ async function promptSelection(items, label, defaultNames) {
  * 交互式选择：每步可回退到上一步，最后总览支持任意类别重选。
  * 返回 { skills, rules, commands, hooks } 或 null（取消）。
  */
-async function interactiveSelect(scans, existing) {
+export async function interactiveSelect(scans, existing) {
   const sel = {}
 
   // 第一轮：顺序遍历，每步给导航
@@ -350,8 +350,16 @@ export async function resolveSourceDir() {
  *   target=undefined  同步项目 .claude/（不动全局 CLAUDE.md）
  *   target='md'       仅同步 CLAUDE.md → 全局 ~/.claude/
  */
-export async function syncClaude({ target, reselect = false, dryRun = false } = {}) {
-  const sourceDir = await resolveSourceDir()
+export async function syncClaude({
+  target,
+  reselect = false,
+  dryRun = false,
+  sourceDir: sourceDirOverride,
+  projectDir,
+  selected: selectedOverride,
+  skipInitPrompt = false,
+} = {}) {
+  const sourceDir = sourceDirOverride || await resolveSourceDir()
   if (!await fs.pathExists(sourceDir)) {
     console.error(chalk.red('Error: claude-global templates not found in repo'))
     process.exit(1)
@@ -373,13 +381,14 @@ export async function syncClaude({ target, reselect = false, dryRun = false } =
   }
 
   console.log(chalk.blue('\nScanning available Claude configuration...\n'))
-  const projectTargetDir = path.join(process.cwd(), '.claude')
+  const projectRoot = projectDir || process.cwd()
+  const projectTargetDir = path.join(projectRoot, '.claude')
 
-  if (!await fs.pathExists(projectTargetDir)) {
+  if (!selectedOverride && !skipInitPrompt && !await fs.pathExists(projectTargetDir)) {
     const { shouldCreate } = await inquirer.prompt([{
       type: 'confirm',
       name: 'shouldCreate',
-      message: `当前目录 ${chalk.yellow(process.cwd())} 未找到 .claude 目录，是否在此创建？`,
+      message: `当前目录 ${chalk.yellow(projectRoot)} 未找到 .claude 目录，是否在此创建？`,
       default: false,
     }])
     if (!shouldCreate) {
@@ -406,7 +415,15 @@ export async function syncClaude({ target, reselect = false, dryRun = false } =
 
   let selected
 
-  if (!reselect && hasAnyExisting) {
+  if (selectedOverride) {
+    const selectedNames = key => new Set((selectedOverride[key] || []).map(item => item.name))
+    selected = {
+      skills: scans.skills.filter(item => selectedNames('skills').has(item.name)),
+      rules: scans.rules.filter(item => selectedNames('rules').has(item.name)),
+      commands: scans.commands.filter(item => selectedNames('commands').has(item.name)),
+      hooks: scans.hooks.filter(item => selectedNames('hooks').has(item.name)),
+    }
+  } else if (!reselect && hasAnyExisting) {
     // 缓存模式：模板 ∩ 已选
     selected = {
       skills: scans.skills.filter(s => existing.skills.has(s.name)),

package/templates/claude-global/hooks/Git/pre-git-commit-backtick-check.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# Claude Code PreToolUse Hook
+# 拦截 git commit message 中会被 shell 命令替换的反引号 / $(...)
+#
+# 背景：AI 生成的 commit message 爱用 Markdown 风格反引号包代码标识符，
+#   git commit -m "fix: support `bun install` on windows"
+# 经 shell 执行时，双引号内的 `bun install` 会被当成命令替换 $(bun install) 实际执行，
+# 输出塞进 message，甚至误执行破坏性命令导致丢代码。
+# 单引号内 '...`...`...' 不展开，安全。
+# 安全写法：git commit -F <file> / --file=- / 单引号。
+
+# 从 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
+
+# 逐字符做轻量 shell 词法扫描：跟踪引号状态，
+# 只在「非单引号上下文」里出现裸反引号或 $( 时判危险（这些会被 shell 求值）。
+# 命令经环境变量传入（stdin 已被 heredoc 脚本占用，不能再走管道）。
+DANGER=$(CMD="$CMD" python3 <<'PY'
+import os
+
+s = os.environ.get("CMD", "")
+in_single = False   # 单引号内：所有字符字面，反引号安全
+in_double = False   # 双引号内：反引号 / $() 仍会命令替换
+i, n = 0, len(s)
+danger = False
+
+while i < n:
+    c = s[i]
+    if c == '\\' and not in_single:
+        # 反斜杠转义下一个字符（单引号内反斜杠不转义）
+        i += 2
+        continue
+    if c == "'" and not in_double:
+        in_single = not in_single
+        i += 1
+        continue
+    if c == '"' and not in_single:
+        in_double = not in_double
+        i += 1
+        continue
+    if not in_single:
+        # 非单引号上下文（裸或双引号内）：反引号 / $( 会被求值
+        if c == '`':
+            danger = True
+            break
+        if c == '$' and i + 1 < n and s[i + 1] == '(':
+            danger = True
+            break
+    i += 1
+
+print("DANGER" if danger else "OK")
+PY
+)
+
+[ "$DANGER" = "DANGER" ] || exit 0
+
+echo "========================================"
+echo "  WARNING: 危险的 commit message 写法"
+echo "========================================"
+echo ""
+echo "检测到 git commit message 中含会被 shell 命令替换的反引号 \` 或 \$(...)。"
+echo "双引号内的 \`...\` 会被当成命令替换实际执行，可能误执行命令甚至丢代码。"
+echo ""
+echo "改用以下任一安全写法："
+echo "  1. 文件提交（推荐多行 / 含特殊字符）："
+echo "       git commit -F <msg-file>"
+echo "       printf '%s\\n' \"\$MSG\" | git commit --file=-"
+echo "  2. 单引号包裹（单引号内反引号不展开）："
+echo "       git commit -m 'fix: support \`bun install\` on windows'"
+echo "  3. 转义反引号："
+echo "       git commit -m \"fix: support \\\`bun install\\\` on windows\""
+echo "========================================"
+exit 2  # 暂停等待人工审批

package/templates/claude-global/hooks/Git/pre-git-commit-sensitive-check.sh

@@ -2,40 +2,36 @@
 # Claude Code PreToolUse Hook
 # 在 git commit 前检查暂存文件中是否包含敏感数据
 
+# 从 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 命令
-echo "$TOOL_INPUT" | grep -q 'git commit' || exit 0
+printf '%s' "$CMD" | grep -q 'git commit' || exit 0
 
 # 获取暂存文件列表
 STAGED=$(git diff --cached --diff-filter=ACMR --name-only 2>/dev/null)
 [ -z "$STAGED" ] && exit 0
 
-# 敏感数据匹配模式
+# 敏感数据匹配模式（赋值/上下文形式，避免类名/变量名裸词误报）
 PATTERNS=(
-    # 密码/密钥
-    'password'
-    'passwd'
-    'secret'
-    'api[_-]?key'
-    'access[_-]?token'
-    'private[_-]?key'
-    'auth[_-]?token'
-    'client[_-]?secret'
-    'bearer'
-
-    # 数据库连接串
-    'jdbc:'
-    'mysql://'
-    'postgres://'
-    'mongodb://'
-    'redis://'
-
-    # 私钥文件
-    '-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY'
-
-    # 平台 Token
-    'sk-[a-zA-Z0-9]{20,}'        # OpenAI
-    'ghp_[a-zA-Z0-9]{36}'        # GitHub
-    'AKIA[0-9A-Z]{16}'           # AWS
+    # 口令/密钥/令牌赋值（词 + :或= + 引号值；PairingSecret / clientSecret 等标识符不命中）
+    "(password|passwd)[[:space:]]*[:=][[:space:]]*[\"'][^\"']{4,}"
+    "secret[[:space:]]*[:=][[:space:]]*[\"'][^\"']{8,}"
+    "api[_-]?key[[:space:]]*[:=][[:space:]]*[\"'][^\"']{8,}"
+    "(access|auth)[_-]?token[[:space:]]*[:=][[:space:]]*[\"'][^\"']{8,}"
+    "client[_-]?secret[[:space:]]*[:=][[:space:]]*[\"'][^\"']{8,}"
+    "[Bb]earer[[:space:]]+[a-zA-Z0-9._-]{20,}"
+
+    # 含凭证的连接串（scheme://user:pass@host）
+    "://[a-zA-Z0-9_.-]+:[^@[:space:]/]{3,}@"
+
+    # 私钥文件块
+    "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY"
+
+    # 平台 Token（格式高特异，裸匹配）
+    "sk-[a-zA-Z0-9]{20,}"        # OpenAI
+    "ghp_[a-zA-Z0-9]{36}"        # GitHub
+    "AKIA[0-9A-Z]{16}"           # AWS
 )
 
 # 拼接为正则

package/templates/claude-global/rules/iOS/dwy-swift-style.md

@@ -0,0 +1,96 @@
+---
+paths:
+  - "**/*.swift"
+---
+
+# Swift 代码规范
+
+编辑任何 `.swift` 时遵守。本规则仅覆盖代码写法层（缩进、命名、注释、控制流、UI token 化），是与具体业务无关的通用约定。
+
+## 1. 缩进与格式
+
+- **4 空格缩进**，不用 Tab。
+- 类型 / 函数声明参数过长时换行，每参数一行，右括号与返回类型 `) -> X` 单起一行。
+- 一行只做一件事，避免把多个 `if` 挤进一行。
+
+## 2. 命名
+
+- 类型 `UpperCamelCase`，属性 / 方法 / 局部变量 `lowerCamelCase`。
+- **局部短生命周期变量可用短名**（`i` = index、`f` = formatter、`cal` = calendar），同一文件内保持一致。
+- 名字表达意图，避免无信息量的 `data` / `info` / `tmp` 当主力变量名。
+
+## 3. 类型声明（iOS 17）
+
+状态对象统一 iOS 17 写法，不要 `ObservableObject / @Published / @StateObject`：
+
+```swift
+@MainActor                  // 所有触碰 UI / 主线程隔离状态的类型都标
+@Observable                 // 替代 ObservableObject
+final class ListViewModel { // 非继承类一律 final
+    private let store: DataStore  // 依赖私有 + 构造注入
+}
+```
+
+## 4. 注释（中文，强制全量）
+
+**所有代码都要加注释，包括每个类型和每个方法**。注释说明**意图**（为什么这么做、约束是什么），而非复述代码字面。
+
+- **类型顶部必加** `///` 文档注释：说明该类型的职责、它在数据流里的位置或关键约束。`class` / `struct` / `enum` / `protocol` / 有逻辑的 `extension` 都算。
+- **每个方法 / 函数必加** `///` 文档注释（公开和私有都要），说明它做什么、入参出参的语义、可能抛出的错误。
+- 关键属性、反直觉分支、易踩坑处用行内 `//` 标注触发条件。
+- 注释里**禁止 emoji**。
+- 不写废话注释（`// 设置 name` 这种复述赋值的删掉），注释要补充代码没说出口的信息。
+
+```swift
+/// 列表数据源。负责从持久层读取并按时间分组，供视图直接渲染。
+@MainActor
+@Observable
+final class ListViewModel {
+
+    /// 重新加载全部数据并写回 `grouped`。
+    /// 失败时透传持久层错误，由调用方决定提示策略。
+    func reload() throws {
+        let items = try store.all()        // 持久层已保证非 nil，无需兜底
+        grouped = group(items)
+    }
+}
+```
+
+## 5. 控制流：信任上游，不过度防御
+
+只在系统外边界（用户输入、文件 / 网络读入、外部 API）校验；内部调用信任类型签名。
+
+```swift
+// 好：early return，无多余 else
+guard !isBusy else { return }
+withAnimation(.spring(response: 0.5, dampingFraction: 0.75)) { isBusy = true }
+```
+
+- 不写 `value ?? default` 兜已有明确来源的值。
+- 不写 `try? { ... }` 吞异常掩盖 bug；只 catch 预期的具体错误，其余让它抛。
+- 持久 / IO 层方法用 `throws` 透传错误，由调用方决定处理，不在底层吞。
+
+## 6. 图标：矢量图，禁止 emoji
+
+UI 图标**一律 SF Symbols 矢量图**（`Image(systemName:)`），任何视图、文案、注释都**禁止 emoji**：
+
+```swift
+// 好：SF Symbols 矢量图标
+Image(systemName: "checkmark")
+    .font(.system(size: 11, weight: .bold))
+    .foregroundStyle(.white)
+
+// 禁止：emoji 当图标
+Text("✅")   // 不允许
+```
+
+## 7. 颜色 / 字体 / 动效 token 化
+
+- 颜色集中到设计 token（如 `ColorTokens.*` / `theme.*`），**禁止在视图里散落硬编码颜色字面量**。
+- 字体用 `.font(.system(size:weight:))` 或集中的字体 token。
+- 动效统一用一组 `.spring(response:dampingFraction:)` 参数，不用 `.easeInOut`，保持全局手感一致。
+
+## 8. 文案与时间
+
+- 所有 UI 文案走 `String(localized: "some_key")`，**禁止硬编码字面量**；key 命名风格全项目统一。
+- 业务逻辑里「现在」作为依赖注入（`now: @escaping () -> Date = { Date() }`），方便单测固定时间，禁止在逻辑里直接散用 `Date()`。