feat: 大幅扩充代码审查指南内容

主要更新：
- typescript.md: 新增泛型、条件类型、映射类型、strict 模式、ESLint 规则 (~540 行)
- python.md: 新增类型注解、async/await、pytest、性能优化 (~1070 行)
- vue.md: 新增 Vue 3.5 特性 (defineModel, useTemplateRef, useId) (~920 行)
- rust.md: 新增取消安全性、spawn vs await 决策指南 (~840 行)
- react.md: 新增 useSuspenseQuery 限制说明和场景指南 (~870 行)
- README.md: 更新行数统计 (总计 6000+ 行)

新增内容约 2861 行代码审查指南和示例

README.md

@@ -37,13 +37,13 @@ This is a Claude Code skill designed to help developers conduct effective code r
 | File | Lines | Description |
 |------|-------|-------------|
 | **SKILL.md** | ~180 | Core principles + index (loads on skill activation) |
-| **reference/react.md** | ~650 | React/Next.js patterns (on-demand) |
-| **reference/vue.md** | ~200 | Vue 3 patterns (on-demand) |
-| **reference/rust.md** | ~200 | Rust patterns (on-demand) |
-| **reference/typescript.md** | ~100 | TypeScript/JS patterns (on-demand) |
-| **reference/python.md** | ~60 | Python patterns (on-demand) |
+| **reference/react.md** | ~870 | React 19/Next.js/TanStack Query v5 patterns (on-demand) |
+| **reference/vue.md** | ~920 | Vue 3.5 patterns + Composition API (on-demand) |
+| **reference/rust.md** | ~840 | Rust async/ownership/cancellation safety (on-demand) |
+| **reference/typescript.md** | ~540 | TypeScript generics/strict mode/ESLint (on-demand) |
+| **reference/python.md** | ~1070 | Python async/typing/pytest (on-demand) |
 
-**Total: ~2,000+ lines** of review guidelines and code examples, loaded on-demand per language.
+**Total: ~6,000+ lines** of review guidelines and code examples, loaded on-demand per language.
 
 ### Installation
 
@@ -197,13 +197,13 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 | 文件 | 行数 | 描述 |
 |------|------|------|
 | **SKILL.md** | ~180 | 核心原则 + 索引（技能激活时加载）|
-| **reference/react.md** | ~650 | React/Next.js 模式（按需加载）|
-| **reference/vue.md** | ~200 | Vue 3 模式（按需加载）|
-| **reference/rust.md** | ~200 | Rust 模式（按需加载）|
-| **reference/typescript.md** | ~100 | TypeScript/JS 模式（按需加载）|
-| **reference/python.md** | ~60 | Python 模式（按需加载）|
+| **reference/react.md** | ~870 | React 19/Next.js/TanStack Query v5（按需加载）|
+| **reference/vue.md** | ~920 | Vue 3.5 + Composition API（按需加载）|
+| **reference/rust.md** | ~840 | Rust async/所有权/取消安全性（按需加载）|
+| **reference/typescript.md** | ~540 | TypeScript 泛型/strict 模式/ESLint（按需加载）|
+| **reference/python.md** | ~1070 | Python async/类型注解/pytest（按需加载）|
 
-**总计：2,000+ 行**审查指南和代码示例，按语言按需加载。
+**总计：6,000+ 行**审查指南和代码示例，按语言按需加载。
 
 ### 安装
 

reference/react.md

@@ -630,6 +630,20 @@ function GoodQuery({ filters }) {
 
 ### useSuspenseQuery
 
+> **重要限制**：useSuspenseQuery 与 useQuery 有显著差异，选择前需了解其限制。
+
+#### useSuspenseQuery 的限制
+
+| 特性 | useQuery | useSuspenseQuery |
+|------|----------|------------------|
+| `enabled` 选项 | ✅ 支持 | ❌ 不支持 |
+| `placeholderData` | ✅ 支持 | ❌ 不支持 |
+| `data` 类型 | `T \| undefined` | `T`（保证有值）|
+| 错误处理 | `error` 属性 | 抛出到 Error Boundary |
+| 加载状态 | `isLoading` 属性 | 挂起到 Suspense |
+
+#### 不支持 enabled 的替代方案
+
 ```tsx
 // ❌ 使用 useQuery + enabled 实现条件查询
 function BadSuspenseQuery({ userId }) {
@@ -660,6 +674,64 @@ function Parent({ userId }) {
 }
 ```
 
+#### 错误处理差异
+
+```tsx
+// ❌ useSuspenseQuery 没有 error 属性
+function BadErrorHandling() {
+  const { data, error } = useSuspenseQuery({...});
+  if (error) return <Error />;  // error 总是 null！
+}
+
+// ✅ 使用 Error Boundary 处理错误
+function GoodErrorHandling() {
+  return (
+    <ErrorBoundary fallback={<ErrorMessage />}>
+      <Suspense fallback={<Loading />}>
+        <DataComponent />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+function DataComponent() {
+  // 错误会抛出到 Error Boundary
+  const { data } = useSuspenseQuery({
+    queryKey: ['data'],
+    queryFn: fetchData,
+  });
+  return <Display data={data} />;
+}
+```
+
+#### 何时选择 useSuspenseQuery
+
+```tsx
+// ✅ 适合场景：
+// 1. 数据总是需要的（无条件查询）
+// 2. 组件必须有数据才能渲染
+// 3. 使用 React 19 的 Suspense 模式
+// 4. 服务端组件 + 客户端 hydration
+
+// ❌ 不适合场景：
+// 1. 条件查询（根据用户操作触发）
+// 2. 需要 placeholderData 或初始数据
+// 3. 需要在组件内处理 loading/error 状态
+// 4. 多个查询有依赖关系
+
+// ✅ 多个独立查询用 useSuspenseQueries
+function MultipleQueries({ userId }) {
+  const [userQuery, postsQuery] = useSuspenseQueries({
+    queries: [
+      { queryKey: ['user', userId], queryFn: () => fetchUser(userId) },
+      { queryKey: ['posts', userId], queryFn: () => fetchPosts(userId) },
+    ],
+  });
+  // 两个查询并行执行，都完成后组件渲染
+  return <Profile user={userQuery.data} posts={postsQuery.data} />;
+}
+```
+
 ### 乐观更新 (v5 简化)
 
 ```tsx

reference/rust.md

@@ -1,6 +1,18 @@
 # Rust Code Review Guide
 
-> Rust 代码审查指南。编译器能捕获内存安全问题，但审查者需要关注编译器无法检测的问题——业务逻辑、API 设计、性能和可维护性。
+> Rust 代码审查指南。编译器能捕获内存安全问题，但审查者需要关注编译器无法检测的问题——业务逻辑、API 设计、性能、取消安全性和可维护性。
+
+## 目录
+
+- [所有权与借用](#所有权与借用)
+- [Unsafe 代码审查](#unsafe-代码审查最关键)
+- [异步代码](#异步代码)
+- [取消安全性](#取消安全性)
+- [spawn vs await](#spawn-vs-await)
+- [错误处理](#错误处理)
+- [性能](#性能)
+- [Trait 设计](#trait-设计)
+- [Review Checklist](#rust-review-checklist)
 
 ---
 
@@ -19,6 +31,16 @@ fn bad_process(data: &Data) -> Result<()> {
 fn good_process(data: &Data) -> Result<()> {
     expensive_operation(data)  // 传递引用
 }
+
+// ✅ 如果确实需要 clone，添加注释说明原因
+fn justified_clone(data: &Data) -> Result<()> {
+    // Clone needed: data will be moved to spawned task
+    let owned = data.clone();
+    tokio::spawn(async move {
+        process(owned).await
+    });
+    Ok(())
+}
 ```
 
 ### Arc<Mutex<T>> 的使用
@@ -33,12 +55,54 @@ struct BadService {
 struct GoodService {
     cache: HashMap<String, Data>,  // 单一所有者
 }
+
+// ✅ 如果确实需要并发访问，考虑更好的数据结构
+use dashmap::DashMap;
+
+struct ConcurrentService {
+    cache: DashMap<String, Data>,  // 更细粒度的锁
+}
+```
+
+### Cow (Copy-on-Write) 模式
+
+```rust
+use std::borrow::Cow;
+
+// ❌ 总是分配新字符串
+fn bad_process_name(name: &str) -> String {
+    if name.is_empty() {
+        "Unknown".to_string()  // 分配
+    } else {
+        name.to_string()  // 不必要的分配
+    }
+}
+
+// ✅ 使用 Cow 避免不必要的分配
+fn good_process_name(name: &str) -> Cow<'_, str> {
+    if name.is_empty() {
+        Cow::Borrowed("Unknown")  // 静态字符串，无分配
+    } else {
+        Cow::Borrowed(name)  // 借用原始数据
+    }
+}
+
+// ✅ 只在需要修改时才分配
+fn normalize_name(name: &str) -> Cow<'_, str> {
+    if name.chars().any(|c| c.is_uppercase()) {
+        Cow::Owned(name.to_lowercase())  // 需要修改，分配
+    } else {
+        Cow::Borrowed(name)  // 无需修改，借用
+    }
+}
 ```
 
 ---
 
 ## Unsafe 代码审查（最关键！）
 
+### 基本要求
+
 ```rust
 // ❌ unsafe 没有安全文档——这是红旗
 unsafe fn bad_transmute<T, U>(t: T) -> U {
@@ -59,6 +123,69 @@ unsafe fn documented_transmute<T, U>(t: T) -> U {
 }
 ```
 
+### Unsafe 块注释
+
+```rust
+// ❌ 没有解释的 unsafe 块
+fn bad_get_unchecked(slice: &[u8], index: usize) -> u8 {
+    unsafe { *slice.get_unchecked(index) }
+}
+
+// ✅ 每个 unsafe 块必须有 SAFETY 注释
+fn good_get_unchecked(slice: &[u8], index: usize) -> u8 {
+    debug_assert!(index < slice.len(), "index out of bounds");
+    // SAFETY: We verified index < slice.len() via debug_assert.
+    // In release builds, callers must ensure valid index.
+    unsafe { *slice.get_unchecked(index) }
+}
+
+// ✅ 封装 unsafe 提供安全 API
+pub fn checked_get(slice: &[u8], index: usize) -> Option<u8> {
+    if index < slice.len() {
+        // SAFETY: bounds check performed above
+        Some(unsafe { *slice.get_unchecked(index) })
+    } else {
+        None
+    }
+}
+```
+
+### 常见 unsafe 模式
+
+```rust
+// ✅ FFI 边界
+extern "C" {
+    fn external_function(ptr: *const u8, len: usize) -> i32;
+}
+
+pub fn safe_wrapper(data: &[u8]) -> Result<i32, Error> {
+    // SAFETY: data.as_ptr() is valid for data.len() bytes,
+    // and external_function only reads from the buffer.
+    let result = unsafe {
+        external_function(data.as_ptr(), data.len())
+    };
+    if result < 0 {
+        Err(Error::from_code(result))
+    } else {
+        Ok(result)
+    }
+}
+
+// ✅ 性能关键路径的 unsafe
+pub fn fast_copy(src: &[u8], dst: &mut [u8]) {
+    assert_eq!(src.len(), dst.len(), "slices must be equal length");
+    // SAFETY: src and dst are valid slices of equal length,
+    // and dst is mutable so no aliasing.
+    unsafe {
+        std::ptr::copy_nonoverlapping(
+            src.as_ptr(),
+            dst.as_mut_ptr(),
+            src.len()
+        );
+    }
+}
+```
+
 ---
 
 ## 异步代码
@@ -73,9 +200,19 @@ async fn bad_async() {
 }
 
 // ✅ 使用异步 API
-async fn good_async() {
+async fn good_async() -> Result<String> {
     let data = tokio::fs::read_to_string("file.txt").await?;
     tokio::time::sleep(Duration::from_secs(1)).await;
+    Ok(data)
+}
+
+// ✅ 如果必须使用阻塞操作，用 spawn_blocking
+async fn with_blocking() -> Result<Data> {
+    let result = tokio::task::spawn_blocking(|| {
+        // 这里可以安全地进行阻塞操作
+        expensive_cpu_computation()
+    }).await?;
+    Ok(result)
 }
 ```
 
@@ -89,12 +226,323 @@ async fn bad_lock(mutex: &std::sync::Mutex<Data>) {
     process(&guard);
 }
 
-// ✅ 最小化锁范围，或使用 tokio::sync::Mutex
-async fn good_lock(mutex: &std::sync::Mutex<Data>) {
-    let data = mutex.lock().unwrap().clone();  // 立即释放
+// ✅ 方案1：最小化锁范围
+async fn good_lock_scoped(mutex: &std::sync::Mutex<Data>) {
+    let data = {
+        let guard = mutex.lock().unwrap();
+        guard.clone()  // 立即释放锁
+    };
     async_operation().await;
     process(&data);
 }
+
+// ✅ 方案2：使用 tokio::sync::Mutex（可跨 await）
+async fn good_lock_tokio(mutex: &tokio::sync::Mutex<Data>) {
+    let guard = mutex.lock().await;
+    async_operation().await;  // OK: tokio Mutex 设计为可跨 await
+    process(&guard);
+}
+
+// 💡 选择指南：
+// - std::sync::Mutex：低竞争、短临界区、不跨 await
+// - tokio::sync::Mutex：需要跨 await、高竞争场景
+```
+
+### 异步 trait 方法
+
+```rust
+// ❌ async trait 方法的陷阱（旧版本）
+#[async_trait]
+trait BadRepository {
+    async fn find(&self, id: i64) -> Option<Entity>;  // 隐式 Box
+}
+
+// ✅ Rust 1.75+：原生 async trait 方法
+trait Repository {
+    async fn find(&self, id: i64) -> Option<Entity>;
+
+    // 返回具体 Future 类型以避免 allocation
+    fn find_many(&self, ids: &[i64]) -> impl Future<Output = Vec<Entity>> + Send;
+}
+
+// ✅ 对于需要 dyn 的场景
+trait DynRepository: Send + Sync {
+    fn find(&self, id: i64) -> Pin<Box<dyn Future<Output = Option<Entity>> + Send + '_>>;
+}
+```
+
+---
+
+## 取消安全性
+
+### 什么是取消安全
+
+```rust
+// 当一个 Future 在 .await 点被 drop 时，它处于什么状态？
+// 取消安全的 Future：可以在任何 await 点安全取消
+// 取消不安全的 Future：取消可能导致数据丢失或不一致状态
+
+// ❌ 取消不安全的例子
+async fn cancel_unsafe(conn: &mut Connection) -> Result<()> {
+    let data = receive_data().await;  // 如果这里被取消...
+    conn.send_ack().await;  // ...确认永远不会发送，数据可能丢失
+    Ok(())
+}
+
+// ✅ 取消安全的版本
+async fn cancel_safe(conn: &mut Connection) -> Result<()> {
+    // 使用事务或原子操作确保一致性
+    let transaction = conn.begin_transaction().await?;
+    let data = receive_data().await;
+    transaction.commit_with_ack(data).await?;  // 原子操作
+    Ok(())
+}
+```
+
+### select! 中的取消安全
+
+```rust
+use tokio::select;
+
+// ❌ 在 select! 中使用取消不安全的 Future
+async fn bad_select(stream: &mut TcpStream) {
+    let mut buffer = vec![0u8; 1024];
+    loop {
+        select! {
+            // 如果 timeout 先完成，read 被取消
+            // 部分读取的数据可能丢失！
+            result = stream.read(&mut buffer) => {
+                handle_data(&buffer[..result?]);
+            }
+            _ = tokio::time::sleep(Duration::from_secs(5)) => {
+                println!("Timeout");
+            }
+        }
+    }
+}
+
+// ✅ 使用取消安全的 API
+async fn good_select(stream: &mut TcpStream) {
+    let mut buffer = vec![0u8; 1024];
+    loop {
+        select! {
+            // tokio::io::AsyncReadExt::read 是取消安全的
+            // 取消时，未读取的数据留在流中
+            result = stream.read(&mut buffer) => {
+                match result {
+                    Ok(0) => break,  // EOF
+                    Ok(n) => handle_data(&buffer[..n]),
+                    Err(e) => return Err(e),
+                }
+            }
+            _ = tokio::time::sleep(Duration::from_secs(5)) => {
+                println!("Timeout, retrying...");
+            }
+        }
+    }
+}
+
+// ✅ 使用 tokio::pin! 确保 Future 可以安全重用
+async fn pinned_select() {
+    let sleep = tokio::time::sleep(Duration::from_secs(10));
+    tokio::pin!(sleep);
+
+    loop {
+        select! {
+            _ = &mut sleep => {
+                println!("Timer elapsed");
+                break;
+            }
+            data = receive_data() => {
+                process(data).await;
+                // sleep 继续倒计时，不会重置
+            }
+        }
+    }
+}
+```
+
+### 文档化取消安全性
+
+```rust
+/// Reads a complete message from the stream.
+///
+/// # Cancel Safety
+///
+/// This method is **not** cancel safe. If cancelled while reading,
+/// partial data may be lost and the stream state becomes undefined.
+/// Use `read_message_cancel_safe` if cancellation is expected.
+async fn read_message(stream: &mut TcpStream) -> Result<Message> {
+    let len = stream.read_u32().await?;
+    let mut buffer = vec![0u8; len as usize];
+    stream.read_exact(&mut buffer).await?;
+    Ok(Message::from_bytes(&buffer))
+}
+
+/// Reads a message with cancel safety.
+///
+/// # Cancel Safety
+///
+/// This method is cancel safe. If cancelled, any partial data
+/// is preserved in the internal buffer for the next call.
+async fn read_message_cancel_safe(reader: &mut BufferedReader) -> Result<Message> {
+    reader.read_message_buffered().await
+}
+```
+
+---
+
+## spawn vs await
+
+### 何时使用 spawn
+
+```rust
+// ❌ 不必要的 spawn——增加开销，失去结构化并发
+async fn bad_unnecessary_spawn() {
+    let handle = tokio::spawn(async {
+        simple_operation().await
+    });
+    handle.await.unwrap();  // 为什么不直接 await？
+}
+
+// ✅ 直接 await 简单操作
+async fn good_direct_await() {
+    simple_operation().await;
+}
+
+// ✅ spawn 用于真正的并行执行
+async fn good_parallel_spawn() {
+    let task1 = tokio::spawn(fetch_from_service_a());
+    let task2 = tokio::spawn(fetch_from_service_b());
+
+    // 两个请求并行执行
+    let (result1, result2) = tokio::try_join!(task1, task2)?;
+}
+
+// ✅ spawn 用于后台任务（fire-and-forget）
+async fn good_background_spawn() {
+    // 启动后台任务，不等待完成
+    tokio::spawn(async {
+        cleanup_old_sessions().await;
+        log_metrics().await;
+    });
+
+    // 继续执行其他工作
+    handle_request().await;
+}
+```
+
+### spawn 的 'static 要求
+
+```rust
+// ❌ spawn 的 Future 必须是 'static
+async fn bad_spawn_borrow(data: &Data) {
+    tokio::spawn(async {
+        process(data).await;  // Error: `data` 不是 'static
+    });
+}
+
+// ✅ 方案1：克隆数据
+async fn good_spawn_clone(data: &Data) {
+    let owned = data.clone();
+    tokio::spawn(async move {
+        process(&owned).await;
+    });
+}
+
+// ✅ 方案2：使用 Arc 共享
+async fn good_spawn_arc(data: Arc<Data>) {
+    let data = Arc::clone(&data);
+    tokio::spawn(async move {
+        process(&data).await;
+    });
+}
+
+// ✅ 方案3：使用作用域任务（tokio-scoped 或 async-scoped）
+async fn good_scoped_spawn(data: &Data) {
+    // 假设使用 async-scoped crate
+    async_scoped::scope(|s| async {
+        s.spawn(async {
+            process(data).await;  // 可以借用
+        });
+    }).await;
+}
+```
+
+### JoinHandle 错误处理
+
+```rust
+// ❌ 忽略 spawn 的错误
+async fn bad_ignore_spawn_error() {
+    let handle = tokio::spawn(async {
+        risky_operation().await
+    });
+    let _ = handle.await;  // 忽略了 panic 和错误
+}
+
+// ✅ 正确处理 JoinHandle 结果
+async fn good_handle_spawn_error() -> Result<()> {
+    let handle = tokio::spawn(async {
+        risky_operation().await
+    });
+
+    match handle.await {
+        Ok(Ok(result)) => {
+            // 任务成功完成
+            process_result(result);
+            Ok(())
+        }
+        Ok(Err(e)) => {
+            // 任务内部错误
+            Err(e.into())
+        }
+        Err(join_err) => {
+            // 任务 panic 或被取消
+            if join_err.is_panic() {
+                error!("Task panicked: {:?}", join_err);
+            }
+            Err(anyhow!("Task failed: {}", join_err))
+        }
+    }
+}
+```
+
+### 结构化并发 vs spawn
+
+```rust
+// ✅ 优先使用 join!（结构化并发）
+async fn structured_concurrency() -> Result<(A, B, C)> {
+    // 所有任务在同一个作用域内
+    // 如果任何一个失败，其他的会被取消
+    tokio::try_join!(
+        fetch_a(),
+        fetch_b(),
+        fetch_c()
+    )
+}
+
+// ✅ 使用 spawn 时考虑任务生命周期
+struct TaskManager {
+    handles: Vec<JoinHandle<()>>,
+}
+
+impl TaskManager {
+    async fn shutdown(self) {
+        // 优雅关闭：等待所有任务完成
+        for handle in self.handles {
+            if let Err(e) = handle.await {
+                error!("Task failed during shutdown: {}", e);
+            }
+        }
+    }
+
+    async fn abort_all(self) {
+        // 强制关闭：取消所有任务
+        for handle in self.handles {
+            handle.abort();
+        }
+    }
+}
 ```
 
 ---
@@ -135,6 +583,41 @@ fn good_error() -> Result<()> {
     operation().context("failed to perform operation")?;
     Ok(())
 }
+
+// ✅ 使用 with_context 进行懒计算
+fn good_error_lazy() -> Result<()> {
+    operation()
+        .with_context(|| format!("failed to process file: {}", filename))?;
+    Ok(())
+}
+```
+
+### 错误类型设计
+
+```rust
+// ✅ 使用 #[source] 保留错误链
+#[derive(Debug, thiserror::Error)]
+pub enum ServiceError {
+    #[error("database error")]
+    Database(#[source] sqlx::Error),
+
+    #[error("network error: {message}")]
+    Network {
+        message: String,
+        #[source]
+        source: reqwest::Error,
+    },
+
+    #[error("validation failed: {0}")]
+    Validation(String),
+}
+
+// ✅ 为常见转换实现 From
+impl From<sqlx::Error> for ServiceError {
+    fn from(err: sqlx::Error) -> Self {
+        ServiceError::Database(err)
+    }
+}
 ```
 
 ---
@@ -155,7 +638,7 @@ fn bad_sum(items: &[i32]) -> i32 {
 
 // ✅ 惰性迭代
 fn good_sum(items: &[i32]) -> i32 {
-    items.iter().filter(|x| **x > 0).sum()
+    items.iter().filter(|x| **x > 0).copied().sum()
 }
 ```
 
@@ -173,7 +656,55 @@ fn bad_concat(items: &[&str]) -> String {
 
 // ✅ 预分配或用 join
 fn good_concat(items: &[&str]) -> String {
-    items.join("")  // 或用 with_capacity
+    items.join("")
+}
+
+// ✅ 使用 with_capacity 预分配
+fn good_concat_capacity(items: &[&str]) -> String {
+    let total_len: usize = items.iter().map(|s| s.len()).sum();
+    let mut result = String::with_capacity(total_len);
+    for item in items {
+        result.push_str(item);
+    }
+    result
+}
+
+// ✅ 使用 write! 宏
+use std::fmt::Write;
+
+fn good_concat_write(items: &[&str]) -> String {
+    let mut result = String::new();
+    for item in items {
+        write!(result, "{}", item).unwrap();
+    }
+    result
+}
+```
+
+### 避免不必要的分配
+
+```rust
+// ❌ 不必要的 Vec 分配
+fn bad_check_any(items: &[Item]) -> bool {
+    let filtered: Vec<_> = items.iter()
+        .filter(|i| i.is_valid())
+        .collect();
+    !filtered.is_empty()
+}
+
+// ✅ 使用迭代器方法
+fn good_check_any(items: &[Item]) -> bool {
+    items.iter().any(|i| i.is_valid())
+}
+
+// ❌ String::from 用于静态字符串
+fn bad_static() -> String {
+    String::from("error message")  // 运行时分配
+}
+
+// ✅ 返回 &'static str
+fn good_static() -> &'static str {
+    "error message"  // 无分配
 }
 ```
 
@@ -181,6 +712,8 @@ fn good_concat(items: &[&str]) -> String {
 
 ## Trait 设计
 
+### 避免过度抽象
+
 ```rust
 // ❌ 过度抽象——不是 Java，不需要 Interface 一切
 trait Processor { fn process(&self); }
@@ -189,6 +722,39 @@ trait Manager { fn manage(&self); }  // Trait 过多
 
 // ✅ 只在需要多态时创建 trait
 // 具体类型通常更简单、更快
+struct DataProcessor {
+    config: Config,
+}
+
+impl DataProcessor {
+    fn process(&self, data: &Data) -> Result<Output> {
+        // 直接实现
+    }
+}
+```
+
+### Trait 对象 vs 泛型
+
+```rust
+// ❌ 不必要的 trait 对象（动态分发）
+fn bad_process(handler: &dyn Handler) {
+    handler.handle();  // 虚表调用
+}
+
+// ✅ 使用泛型（静态分发，可内联）
+fn good_process<H: Handler>(handler: &H) {
+    handler.handle();  // 可能被内联
+}
+
+// ✅ trait 对象适用场景：异构集合
+fn store_handlers(handlers: Vec<Box<dyn Handler>>) {
+    // 需要存储不同类型的 handlers
+}
+
+// ✅ 使用 impl Trait 返回类型
+fn create_handler() -> impl Handler {
+    ConcreteHandler::new()
+}
 ```
 
 ---
@@ -213,6 +779,7 @@ trait Manager { fn manage(&self); }  // Trait 过多
 - [ ] Arc<Mutex<T>> 真的需要共享状态吗？
 - [ ] RefCell 的使用有正当理由
 - [ ] 生命周期不过度复杂
+- [ ] 考虑使用 Cow 避免不必要的分配
 
 ### Unsafe 代码（最重要）
 
@@ -231,6 +798,21 @@ trait Manager { fn manage(&self); }  // Trait 过多
 - [ ] 锁的获取顺序一致
 - [ ] Channel 缓冲区大小合理
 
+### 取消安全性
+
+- [ ] select! 中的 Future 是取消安全的
+- [ ] 文档化了 async 函数的取消安全性
+- [ ] 取消不会导致数据丢失或不一致状态
+- [ ] 使用 tokio::pin! 正确处理需要重用的 Future
+
+### spawn vs await
+
+- [ ] spawn 只用于真正需要并行的场景
+- [ ] 简单操作直接 await，不要 spawn
+- [ ] spawn 的 JoinHandle 结果被正确处理
+- [ ] 考虑任务的生命周期和关闭策略
+- [ ] 优先使用 join!/try_join! 进行结构化并发
+
 ### 错误处理
 
 - [ ] 库：thiserror 定义结构化错误
@@ -238,6 +820,7 @@ trait Manager { fn manage(&self); }  // Trait 过多
 - [ ] 没有生产代码 unwrap/expect
 - [ ] 错误消息对调试有帮助
 - [ ] must_use 返回值被处理
+- [ ] 使用 #[source] 保留错误链
 
 ### 性能
 
@@ -246,6 +829,7 @@ trait Manager { fn manage(&self); }  // Trait 过多
 - [ ] 字符串用 with_capacity 或 write!
 - [ ] impl Trait vs Box<dyn Trait> 选择合理
 - [ ] 热路径避免分配
+- [ ] 考虑使用 Cow 减少克隆
 
 ### 代码质量
 

reference/typescript.md

@@ -1,53 +1,405 @@
 # TypeScript/JavaScript Code Review Guide
 
-> TypeScript/JavaScript 通用代码审查指南，覆盖类型安全、异步处理、常见陷阱。
+> TypeScript 代码审查指南，覆盖类型系统、泛型、条件类型、strict 模式、async/await 模式等核心主题。
+
+## 目录
+
+- [类型安全基础](#类型安全基础)
+- [泛型模式](#泛型模式)
+- [高级类型](#高级类型)
+- [Strict 模式配置](#strict-模式配置)
+- [异步处理](#异步处理)
+- [不可变性](#不可变性)
+- [ESLint 规则](#eslint-规则)
+- [Review Checklist](#review-checklist)
 
 ---
 
-## 类型安全
+## 类型安全基础
 
 ### 避免使用 any
 
 ```typescript
 // ❌ Using any defeats type safety
-function processData(data: any) {  // Avoid any
-    return data.value;
+function processData(data: any) {
+  return data.value;  // 无类型检查，运行时可能崩溃
 }
 
 // ✅ Use proper types
 interface DataPayload {
-    value: string;
+  value: string;
 }
 function processData(data: DataPayload) {
-    return data.value;
+  return data.value;
 }
+
+// ✅ 未知类型用 unknown + 类型守卫
+function processUnknown(data: unknown) {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return (data as { value: string }).value;
+  }
+  throw new Error('Invalid data');
+}
+```
+
+### 类型收窄
+
+```typescript
+// ❌ 不安全的类型断言
+function getLength(value: string | string[]) {
+  return (value as string[]).length;  // 如果是 string 会出错
+}
+
+// ✅ 使用类型守卫
+function getLength(value: string | string[]): number {
+  if (Array.isArray(value)) {
+    return value.length;
+  }
+  return value.length;
+}
+
+// ✅ 使用 in 操作符
+interface Dog { bark(): void }
+interface Cat { meow(): void }
+
+function speak(animal: Dog | Cat) {
+  if ('bark' in animal) {
+    animal.bark();
+  } else {
+    animal.meow();
+  }
+}
+```
+
+### 字面量类型与 as const
+
+```typescript
+// ❌ 类型过于宽泛
+const config = {
+  endpoint: '/api',
+  method: 'GET'  // 类型是 string
+};
+
+// ✅ 使用 as const 获得字面量类型
+const config = {
+  endpoint: '/api',
+  method: 'GET'
+} as const;  // method 类型是 'GET'
+
+// ✅ 用于函数参数
+function request(method: 'GET' | 'POST', url: string) { ... }
+request(config.method, config.endpoint);  // 正确！
+```
+
+---
+
+## 泛型模式
+
+### 基础泛型
+
+```typescript
+// ❌ 重复代码
+function getFirstString(arr: string[]): string | undefined {
+  return arr[0];
+}
+function getFirstNumber(arr: number[]): number | undefined {
+  return arr[0];
+}
+
+// ✅ 使用泛型
+function getFirst<T>(arr: T[]): T | undefined {
+  return arr[0];
+}
+```
+
+### 泛型约束
+
+```typescript
+// ❌ 泛型没有约束，无法访问属性
+function getProperty<T>(obj: T, key: string) {
+  return obj[key];  // Error: 无法索引
+}
+
+// ✅ 使用 keyof 约束
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+const user = { name: 'Alice', age: 30 };
+getProperty(user, 'name');  // 返回类型是 string
+getProperty(user, 'age');   // 返回类型是 number
+getProperty(user, 'foo');   // Error: 'foo' 不在 keyof User
+```
+
+### 泛型默认值
+
+```typescript
+// ✅ 提供合理的默认类型
+interface ApiResponse<T = unknown> {
+  data: T;
+  status: number;
+  message: string;
+}
+
+// 可以不指定泛型参数
+const response: ApiResponse = { data: null, status: 200, message: 'OK' };
+// 也可以指定
+const userResponse: ApiResponse<User> = { ... };
+```
+
+### 常见泛型工具类型
+
+```typescript
+// ✅ 善用内置工具类型
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+type PartialUser = Partial<User>;         // 所有属性可选
+type RequiredUser = Required<User>;       // 所有属性必需
+type ReadonlyUser = Readonly<User>;       // 所有属性只读
+type UserKeys = keyof User;               // 'id' | 'name' | 'email'
+type NameOnly = Pick<User, 'name'>;       // { name: string }
+type WithoutId = Omit<User, 'id'>;        // { name: string; email: string }
+type UserRecord = Record<string, User>;   // { [key: string]: User }
+```
+
+---
+
+## 高级类型
+
+### 条件类型
+
+```typescript
+// ✅ 根据输入类型返回不同类型
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<string>;  // true
+type B = IsString<number>;  // false
+
+// ✅ 提取数组元素类型
+type ElementType<T> = T extends (infer U)[] ? U : never;
+
+type Elem = ElementType<string[]>;  // string
+
+// ✅ 提取函数返回类型（内置 ReturnType）
+type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+```
+
+### 映射类型
+
+```typescript
+// ✅ 转换对象类型的所有属性
+type Nullable<T> = {
+  [K in keyof T]: T[K] | null;
+};
+
+interface User {
+  name: string;
+  age: number;
+}
+
+type NullableUser = Nullable<User>;
+// { name: string | null; age: number | null }
+
+// ✅ 添加前缀
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+type UserGetters = Getters<User>;
+// { getName: () => string; getAge: () => number }
+```
+
+### 模板字面量类型
+
+```typescript
+// ✅ 类型安全的事件名称
+type EventName = 'click' | 'focus' | 'blur';
+type HandlerName = `on${Capitalize<EventName>}`;
+// 'onClick' | 'onFocus' | 'onBlur'
+
+// ✅ API 路由类型
+type ApiRoute = `/api/${string}`;
+const route: ApiRoute = '/api/users';  // OK
+const badRoute: ApiRoute = '/users';   // Error
+```
+
+### Discriminated Unions
+
+```typescript
+// ✅ 使用判别属性实现类型安全
+type Result<T, E> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+function handleResult(result: Result<User, Error>) {
+  if (result.success) {
+    console.log(result.data.name);  // TypeScript 知道 data 存在
+  } else {
+    console.log(result.error.message);  // TypeScript 知道 error 存在
+  }
+}
+
+// ✅ Redux Action 模式
+type Action =
+  | { type: 'INCREMENT'; payload: number }
+  | { type: 'DECREMENT'; payload: number }
+  | { type: 'RESET' };
+
+function reducer(state: number, action: Action): number {
+  switch (action.type) {
+    case 'INCREMENT':
+      return state + action.payload;  // payload 类型已知
+    case 'DECREMENT':
+      return state - action.payload;
+    case 'RESET':
+      return 0;  // 这里没有 payload
+  }
+}
+```
+
+---
+
+## Strict 模式配置
+
+### 推荐的 tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    // ✅ 必须开启的 strict 选项
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "useUnknownInCatchVariables": true,
+
+    // ✅ 额外推荐选项
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true
+  }
+}
+```
+
+### noUncheckedIndexedAccess 的影响
+
+```typescript
+// tsconfig: "noUncheckedIndexedAccess": true
+
+const arr = [1, 2, 3];
+const first = arr[0];  // 类型是 number | undefined
+
+// ❌ 直接使用可能出错
+console.log(first.toFixed(2));  // Error: 可能是 undefined
+
+// ✅ 先检查
+if (first !== undefined) {
+  console.log(first.toFixed(2));
+}
+
+// ✅ 或使用非空断言（确定时）
+console.log(arr[0]!.toFixed(2));
 ```
 
 ---
 
 ## 异步处理
 
-### 错误处理
+### Promise 错误处理
 
 ```typescript
 // ❌ Not handling async errors
 async function fetchUser(id: string) {
-    const response = await fetch(`/api/users/${id}`);
-    return response.json();  // What if network fails?
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();  // 网络错误未处理
 }
 
 // ✅ Handle errors properly
 async function fetchUser(id: string): Promise<User> {
-    try {
-        const response = await fetch(`/api/users/${id}`);
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}`);
-        }
-        return await response.json();
-    } catch (error) {
-        console.error('Failed to fetch user:', error);
-        throw error;
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
     }
+    return await response.json();
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to fetch user: ${error.message}`);
+    }
+    throw error;
+  }
+}
+```
+
+### Promise.all vs Promise.allSettled
+
+```typescript
+// ❌ Promise.all 一个失败全部失败
+async function fetchAllUsers(ids: string[]) {
+  const users = await Promise.all(ids.map(fetchUser));
+  return users;  // 一个失败就全部失败
+}
+
+// ✅ Promise.allSettled 获取所有结果
+async function fetchAllUsers(ids: string[]) {
+  const results = await Promise.allSettled(ids.map(fetchUser));
+
+  const users: User[] = [];
+  const errors: Error[] = [];
+
+  for (const result of results) {
+    if (result.status === 'fulfilled') {
+      users.push(result.value);
+    } else {
+      errors.push(result.reason);
+    }
+  }
+
+  return { users, errors };
+}
+```
+
+### 竞态条件处理
+
+```typescript
+// ❌ 竞态条件：旧请求可能覆盖新请求
+function useSearch() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+
+  useEffect(() => {
+    fetch(`/api/search?q=${query}`)
+      .then(r => r.json())
+      .then(setResults);  // 旧请求可能后返回！
+  }, [query]);
+}
+
+// ✅ 使用 AbortController
+function useSearch() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    fetch(`/api/search?q=${query}`, { signal: controller.signal })
+      .then(r => r.json())
+      .then(setResults)
+      .catch(e => {
+        if (e.name !== 'AbortError') throw e;
+      });
+
+    return () => controller.abort();
+  }, [query]);
 }
 ```
 
@@ -55,47 +407,137 @@ async function fetchUser(id: string): Promise<User> {
 
 ## 不可变性
 
-### 避免直接修改 Props/参数
+### Readonly 与 ReadonlyArray
 
 ```typescript
-// ❌ Mutation of props
-function UserProfile({ user }: Props) {
-    user.lastViewed = new Date();  // Mutating prop!
-    return <div>{user.name}</div>;
+// ❌ 可变参数可能被意外修改
+function processUsers(users: User[]) {
+  users.sort((a, b) => a.name.localeCompare(b.name));  // 修改了原数组！
+  return users;
 }
 
-// ✅ Don't mutate props
-function UserProfile({ user, onView }: Props) {
-    useEffect(() => {
-        onView(user.id);  // Notify parent to update
-    }, [user.id]);
-    return <div>{user.name}</div>;
+// ✅ 使用 readonly 防止修改
+function processUsers(users: readonly User[]): User[] {
+  return [...users].sort((a, b) => a.name.localeCompare(b.name));
 }
+
+// ✅ 深度只读
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};
+```
+
+### 不变式函数参数
+
+```typescript
+// ✅ 使用 as const 和 readonly 保护数据
+function createConfig<T extends readonly string[]>(routes: T) {
+  return routes;
+}
+
+const routes = createConfig(['home', 'about', 'contact'] as const);
+// 类型是 readonly ['home', 'about', 'contact']
 ```
 
 ---
 
-## TypeScript Review Checklist
+## ESLint 规则
+
+### 推荐的 @typescript-eslint 规则
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    'plugin:@typescript-eslint/strict'
+  ],
+  rules: {
+    // ✅ 类型安全
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unsafe-assignment': 'error',
+    '@typescript-eslint/no-unsafe-member-access': 'error',
+    '@typescript-eslint/no-unsafe-call': 'error',
+    '@typescript-eslint/no-unsafe-return': 'error',
+
+    // ✅ 最佳实践
+    '@typescript-eslint/explicit-function-return-type': 'warn',
+    '@typescript-eslint/no-floating-promises': 'error',
+    '@typescript-eslint/await-thenable': 'error',
+    '@typescript-eslint/no-misused-promises': 'error',
+
+    // ✅ 代码风格
+    '@typescript-eslint/consistent-type-imports': 'error',
+    '@typescript-eslint/prefer-nullish-coalescing': 'error',
+    '@typescript-eslint/prefer-optional-chain': 'error'
+  }
+};
+```
+
+### 常见 ESLint 错误修复
+
+```typescript
+// ❌ no-floating-promises: Promise 必须被处理
+async function save() { ... }
+save();  // Error: 未处理的 Promise
+
+// ✅ 显式处理
+await save();
+// 或
+save().catch(console.error);
+// 或明确忽略
+void save();
+
+// ❌ no-misused-promises: 不能在非 async 位置使用 Promise
+const items = [1, 2, 3];
+items.forEach(async (item) => {  // Error!
+  await processItem(item);
+});
+
+// ✅ 使用 for...of
+for (const item of items) {
+  await processItem(item);
+}
+// 或 Promise.all
+await Promise.all(items.map(processItem));
+```
+
+---
+
+## Review Checklist
 
 ### 类型系统
-- [ ] 没有使用 `any`（使用 `unknown` 代替未知类型）
-- [ ] 接口和类型定义完整
+- [ ] 没有使用 `any`（使用 `unknown` + 类型守卫代替）
+- [ ] 接口和类型定义完整且有意义的命名
 - [ ] 使用泛型提高代码复用性
 - [ ] 联合类型有正确的类型收窄
+- [ ] 善用工具类型（Partial、Pick、Omit 等）
+
+### 泛型
+- [ ] 泛型有适当的约束（extends）
+- [ ] 泛型参数有合理的默认值
+- [ ] 避免过度泛型化（KISS 原则）
+
+### Strict 模式
+- [ ] tsconfig.json 启用了 strict: true
+- [ ] 启用了 noUncheckedIndexedAccess
+- [ ] 没有使用 @ts-ignore（改用 @ts-expect-error）
 
 ### 异步代码
 - [ ] async 函数有错误处理
 - [ ] Promise rejection 被正确处理
-- [ ] 避免 callback hell，使用 async/await
-- [ ] 并发请求使用 `Promise.all` 或 `Promise.allSettled`
+- [ ] 没有 floating promises（未处理的 Promise）
+- [ ] 并发请求使用 Promise.all 或 Promise.allSettled
+- [ ] 竞态条件使用 AbortController 处理
 
 ### 不可变性
 - [ ] 不直接修改函数参数
 - [ ] 使用 spread 操作符创建新对象/数组
-- [ ] 考虑使用 `readonly` 修饰符
+- [ ] 考虑使用 readonly 修饰符
 
-### 代码质量
-- [ ] 启用 strict 模式
-- [ ] ESLint/TSLint 无警告
-- [ ] 函数有返回类型注解
-- [ ] 避免类型断言（`as`），除非确实必要
+### ESLint
+- [ ] 使用 @typescript-eslint/recommended
+- [ ] 没有 ESLint 警告或错误
+- [ ] 使用 consistent-type-imports

reference/vue.md

@@ -1,11 +1,54 @@
 # Vue 3 Code Review Guide
 
-> Vue 3 Composition API 代码审查指南，覆盖响应性系统、Props/Emits、Watchers、Composables 等核心主题。
+> Vue 3 Composition API 代码审查指南，覆盖响应性系统、Props/Emits、Watchers、Composables、Vue 3.5 新特性等核心主题。
+
+## 目录
+
+- [响应性系统](#响应性系统)
+- [Props & Emits](#props--emits)
+- [Vue 3.5 新特性](#vue-35-新特性)
+- [Watchers](#watchers)
+- [模板最佳实践](#模板最佳实践)
+- [Composables](#composables)
+- [性能优化](#性能优化)
+- [Review Checklist](#review-checklist)
 
 ---
 
 ## 响应性系统
 
+### ref vs reactive 选择
+
+```vue
+<!-- ✅ 基本类型用 ref -->
+<script setup lang="ts">
+const count = ref(0)
+const name = ref('Vue')
+
+// ref 需要 .value 访问
+count.value++
+</script>
+
+<!-- ✅ 对象/数组用 reactive（可选）-->
+<script setup lang="ts">
+const state = reactive({
+  user: null,
+  loading: false,
+  error: null
+})
+
+// reactive 直接访问
+state.loading = true
+</script>
+
+<!-- 💡 现代最佳实践：全部使用 ref，保持一致性 -->
+<script setup lang="ts">
+const user = ref<User | null>(null)
+const loading = ref(false)
+const error = ref<Error | null>(null)
+</script>
+```
+
 ### 解构 reactive 对象
 
 ```vue
@@ -49,6 +92,33 @@ watch(fullName, (name) => {
 </script>
 ```
 
+### shallowRef 优化
+
+```vue
+<!-- ❌ 大型对象使用 ref 会深度转换 -->
+<script setup lang="ts">
+const largeData = ref(hugeNestedObject)  // 深度响应式，性能开销大
+</script>
+
+<!-- ✅ 使用 shallowRef 避免深度转换 -->
+<script setup lang="ts">
+const largeData = shallowRef(hugeNestedObject)
+
+// 整体替换才会触发更新
+function updateData(newData) {
+  largeData.value = newData  // ✅ 触发更新
+}
+
+// ❌ 修改嵌套属性不会触发更新
+// largeData.value.nested.prop = 'new'
+
+// 需要手动触发时使用 triggerRef
+import { triggerRef } from 'vue'
+largeData.value.nested.prop = 'new'
+triggerRef(largeData)
+</script>
+```
+
 ---
 
 ## Props & Emits
@@ -94,10 +164,274 @@ const props = withDefaults(defineProps<Props>(), {
 </script>
 ```
 
+### defineEmits 类型安全
+
+```vue
+<!-- ❌ defineEmits 缺少类型 -->
+<script setup lang="ts">
+const emit = defineEmits(['update', 'delete'])  // 无类型检查
+emit('update', someValue)  // 参数类型不安全
+</script>
+
+<!-- ✅ 完整的类型定义 -->
+<script setup lang="ts">
+const emit = defineEmits<{
+  update: [id: number, value: string]
+  delete: [id: number]
+  'custom-event': [payload: CustomPayload]
+}>()
+
+// 现在有完整的类型检查
+emit('update', 1, 'new value')  // ✅
+emit('update', 'wrong')  // ❌ TypeScript 报错
+</script>
+```
+
+---
+
+## Vue 3.5 新特性
+
+### Reactive Props Destructure (3.5+)
+
+```vue
+<!-- Vue 3.5 之前：解构会丢失响应性 -->
+<script setup lang="ts">
+const props = defineProps<{ count: number }>()
+// 需要使用 props.count 或 toRefs
+</script>
+
+<!-- ✅ Vue 3.5+：解构保持响应性 -->
+<script setup lang="ts">
+const { count, name = 'default' } = defineProps<{
+  count: number
+  name?: string
+}>()
+
+// count 和 name 自动保持响应性！
+// 可以直接在模板和 watch 中使用
+watch(() => count, (newCount) => {
+  console.log('Count changed:', newCount)
+})
+</script>
+
+<!-- ✅ 配合默认值使用 -->
+<script setup lang="ts">
+const {
+  title,
+  count = 0,
+  items = () => []  // 函数作为默认值（对象/数组）
+} = defineProps<{
+  title: string
+  count?: number
+  items?: () => string[]
+}>()
+</script>
+```
+
+### defineModel (3.4+)
+
+```vue
+<!-- ❌ 传统 v-model 实现：冗长 -->
+<script setup lang="ts">
+const props = defineProps<{ modelValue: string }>()
+const emit = defineEmits<{ 'update:modelValue': [value: string] }>()
+
+// 需要 computed 来双向绑定
+const value = computed({
+  get: () => props.modelValue,
+  set: (val) => emit('update:modelValue', val)
+})
+</script>
+
+<!-- ✅ defineModel：简洁的 v-model 实现 -->
+<script setup lang="ts">
+// 自动处理 props 和 emit
+const model = defineModel<string>()
+
+// 直接使用
+model.value = 'new value'  // 自动 emit
+</script>
+<template>
+  <input v-model="model" />
+</template>
+
+<!-- ✅ 命名 v-model -->
+<script setup lang="ts">
+// v-model:title 的实现
+const title = defineModel<string>('title')
+
+// 带默认值和选项
+const count = defineModel<number>('count', {
+  default: 0,
+  required: false
+})
+</script>
+
+<!-- ✅ 多个 v-model -->
+<script setup lang="ts">
+const firstName = defineModel<string>('firstName')
+const lastName = defineModel<string>('lastName')
+</script>
+<template>
+  <!-- 父组件使用：<MyInput v-model:first-name="first" v-model:last-name="last" /> -->
+</template>
+
+<!-- ✅ v-model 修饰符 -->
+<script setup lang="ts">
+const [model, modifiers] = defineModel<string>()
+
+// 检查修饰符
+if (modifiers.capitalize) {
+  // 处理 .capitalize 修饰符
+}
+</script>
+```
+
+### useTemplateRef (3.5+)
+
+```vue
+<!-- 传统方式：ref 属性与变量同名 -->
+<script setup lang="ts">
+const inputRef = ref<HTMLInputElement | null>(null)
+</script>
+<template>
+  <input ref="inputRef" />
+</template>
+
+<!-- ✅ useTemplateRef：更清晰的模板引用 -->
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+
+const input = useTemplateRef<HTMLInputElement>('my-input')
+
+onMounted(() => {
+  input.value?.focus()
+})
+</script>
+<template>
+  <input ref="my-input" />
+</template>
+
+<!-- ✅ 动态 ref -->
+<script setup lang="ts">
+const refKey = ref('input-a')
+const dynamicInput = useTemplateRef<HTMLInputElement>(refKey)
+</script>
+```
+
+### useId (3.5+)
+
+```vue
+<!-- ❌ 手动生成 ID 可能冲突 -->
+<script setup lang="ts">
+const id = `input-${Math.random()}`  // SSR 不一致！
+</script>
+
+<!-- ✅ useId：SSR 安全的唯一 ID -->
+<script setup lang="ts">
+import { useId } from 'vue'
+
+const id = useId()  // 例如：'v-0'
+</script>
+<template>
+  <label :for="id">Name</label>
+  <input :id="id" />
+</template>
+
+<!-- ✅ 表单组件中使用 -->
+<script setup lang="ts">
+const inputId = useId()
+const errorId = useId()
+</script>
+<template>
+  <label :for="inputId">Email</label>
+  <input
+    :id="inputId"
+    :aria-describedby="errorId"
+  />
+  <span :id="errorId" class="error">{{ error }}</span>
+</template>
+```
+
+### onWatcherCleanup (3.5+)
+
+```vue
+<!-- 传统方式：watch 第三个参数 -->
+<script setup lang="ts">
+watch(source, async (value, oldValue, onCleanup) => {
+  const controller = new AbortController()
+  onCleanup(() => controller.abort())
+  // ...
+})
+</script>
+
+<!-- ✅ onWatcherCleanup：更灵活的清理 -->
+<script setup lang="ts">
+import { onWatcherCleanup } from 'vue'
+
+watch(source, async (value) => {
+  const controller = new AbortController()
+  onWatcherCleanup(() => controller.abort())
+
+  // 可以在任意位置调用，不限于回调开头
+  if (someCondition) {
+    const anotherResource = createResource()
+    onWatcherCleanup(() => anotherResource.dispose())
+  }
+
+  await fetchData(value, controller.signal)
+})
+</script>
+```
+
+### Deferred Teleport (3.5+)
+
+```vue
+<!-- ❌ Teleport 目标必须在挂载时存在 -->
+<template>
+  <Teleport to="#modal-container">
+    <!-- 如果 #modal-container 不存在会报错 -->
+  </Teleport>
+</template>
+
+<!-- ✅ defer 属性延迟挂载 -->
+<template>
+  <Teleport to="#modal-container" defer>
+    <!-- 等待目标元素存在后再挂载 -->
+    <Modal />
+  </Teleport>
+</template>
+```
+
 ---
 
 ## Watchers
 
+### watch vs watchEffect
+
+```vue
+<script setup lang="ts">
+// ✅ watch：明确指定依赖，惰性执行
+watch(
+  () => props.userId,
+  async (userId) => {
+    user.value = await fetchUser(userId)
+  }
+)
+
+// ✅ watchEffect：自动收集依赖，立即执行
+watchEffect(async () => {
+  // 自动追踪 props.userId
+  user.value = await fetchUser(props.userId)
+})
+
+// 💡 选择指南：
+// - 需要旧值？用 watch
+// - 需要惰性执行？用 watch
+// - 依赖复杂？用 watchEffect
+</script>
+```
+
 ### watch 清理函数
 
 ```vue
@@ -131,6 +465,71 @@ watch(searchQuery, async (query, _, onCleanup) => {
 </script>
 ```
 
+### watch 选项
+
+```vue
+<script setup lang="ts">
+// ✅ immediate：立即执行一次
+watch(
+  userId,
+  async (id) => {
+    user.value = await fetchUser(id)
+  },
+  { immediate: true }
+)
+
+// ✅ deep：深度监听（性能开销大，谨慎使用）
+watch(
+  state,
+  (newState) => {
+    console.log('State changed deeply')
+  },
+  { deep: true }
+)
+
+// ✅ flush: 'post'：DOM 更新后执行
+watch(
+  source,
+  () => {
+    // 可以安全访问更新后的 DOM
+    nextTick 不再需要
+  },
+  { flush: 'post' }
+)
+
+// ✅ once: true (Vue 3.4+)：只执行一次
+watch(
+  source,
+  (value) => {
+    console.log('只会执行一次:', value)
+  },
+  { once: true }
+)
+</script>
+```
+
+### 监听多个源
+
+```vue
+<script setup lang="ts">
+// ✅ 监听多个 ref
+watch(
+  [firstName, lastName],
+  ([newFirst, newLast], [oldFirst, oldLast]) => {
+    console.log(`Name changed from ${oldFirst} ${oldLast} to ${newFirst} ${newLast}`)
+  }
+)
+
+// ✅ 监听 reactive 对象的特定属性
+watch(
+  () => [state.count, state.name],
+  ([count, name]) => {
+    console.log(`count: ${count}, name: ${name}`)
+  }
+)
+</script>
+```
+
 ---
 
 ## 模板最佳实践
@@ -151,6 +550,13 @@ watch(searchQuery, async (query, _, onCleanup) => {
     {{ item.name }}
   </li>
 </template>
+
+<!-- ✅ 复合 key（当没有唯一 ID 时）-->
+<template>
+  <li v-for="(item, index) in items" :key="`${item.name}-${item.type}-${index}`">
+    {{ item.name }}
+  </li>
+</template>
 ```
 
 ### v-if 和 v-for 优先级
@@ -174,12 +580,87 @@ const activeUsers = computed(() =>
     {{ user.name }}
   </li>
 </template>
+
+<!-- ✅ 或用 template 包裹 -->
+<template>
+  <template v-for="user in users" :key="user.id">
+    <li v-if="user.active">
+      {{ user.name }}
+    </li>
+  </template>
+</template>
+```
+
+### 事件处理
+
+```vue
+<!-- ❌ 内联复杂逻辑 -->
+<template>
+  <button @click="items = items.filter(i => i.id !== item.id); count--">
+    Delete
+  </button>
+</template>
+
+<!-- ✅ 使用方法 -->
+<script setup lang="ts">
+const deleteItem = (id: number) => {
+  items.value = items.value.filter(i => i.id !== id)
+  count.value--
+}
+</script>
+<template>
+  <button @click="deleteItem(item.id)">Delete</button>
+</template>
+
+<!-- ✅ 事件修饰符 -->
+<template>
+  <!-- 阻止默认行为 -->
+  <form @submit.prevent="handleSubmit">...</form>
+
+  <!-- 阻止冒泡 -->
+  <button @click.stop="handleClick">...</button>
+
+  <!-- 只执行一次 -->
+  <button @click.once="handleOnce">...</button>
+
+  <!-- 键盘修饰符 -->
+  <input @keyup.enter="submit" @keyup.esc="cancel" />
+</template>
 ```
 
 ---
 
 ## Composables
 
+### Composable 设计原则
+
+```typescript
+// ✅ 好的 composable 设计
+export function useCounter(initialValue = 0) {
+  const count = ref(initialValue)
+
+  const increment = () => count.value++
+  const decrement = () => count.value--
+  const reset = () => count.value = initialValue
+
+  // 返回响应式引用和方法
+  return {
+    count: readonly(count),  // 只读防止外部修改
+    increment,
+    decrement,
+    reset
+  }
+}
+
+// ❌ 不要返回 .value
+export function useBadCounter() {
+  const count = ref(0)
+  return {
+    count: count.value  // ❌ 丢失响应性！
+  }
+}
+```
+
 ### Props 传递给 composable
 
 ```vue
@@ -196,35 +677,236 @@ const userIdRef = toRef(props, 'userId')
 const { user } = useUser(userIdRef)  // 保持响应性
 // 或使用 computed
 const { user } = useUser(computed(() => props.userId))
+
+// ✅ Vue 3.5+：直接解构使用
+const { userId } = defineProps<{ userId: string }>()
+const { user } = useUser(() => userId)  // getter 函数
 </script>
 ```
 
+### 异步 Composable
+
+```typescript
+// ✅ 异步 composable 模式
+export function useFetch<T>(url: MaybeRefOrGetter<string>) {
+  const data = ref<T | null>(null)
+  const error = ref<Error | null>(null)
+  const loading = ref(false)
+
+  const execute = async () => {
+    loading.value = true
+    error.value = null
+
+    try {
+      const response = await fetch(toValue(url))
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`)
+      }
+      data.value = await response.json()
+    } catch (e) {
+      error.value = e as Error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  // 响应式 URL 时自动重新获取
+  watchEffect(() => {
+    toValue(url)  // 追踪依赖
+    execute()
+  })
+
+  return {
+    data: readonly(data),
+    error: readonly(error),
+    loading: readonly(loading),
+    refetch: execute
+  }
+}
+
+// 使用
+const { data, loading, error, refetch } = useFetch<User[]>('/api/users')
+```
+
+### 生命周期与清理
+
+```typescript
+// ✅ Composable 中正确处理生命周期
+export function useEventListener(
+  target: MaybeRefOrGetter<EventTarget>,
+  event: string,
+  handler: EventListener
+) {
+  // 组件挂载后添加
+  onMounted(() => {
+    toValue(target).addEventListener(event, handler)
+  })
+
+  // 组件卸载时移除
+  onUnmounted(() => {
+    toValue(target).removeEventListener(event, handler)
+  })
+}
+
+// ✅ 使用 effectScope 管理副作用
+export function useFeature() {
+  const scope = effectScope()
+
+  scope.run(() => {
+    // 所有响应式效果都在这个 scope 内
+    const state = ref(0)
+    watch(state, () => { /* ... */ })
+    watchEffect(() => { /* ... */ })
+  })
+
+  // 清理所有效果
+  onUnmounted(() => scope.stop())
+
+  return { /* ... */ }
+}
+```
+
 ---
 
-## Vue 3 Review Checklist
+## 性能优化
+
+### v-memo
+
+```vue
+<!-- ✅ v-memo：缓存子树，避免重复渲染 -->
+<template>
+  <div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
+    <!-- 只有当 item.id === selected 变化时才重新渲染 -->
+    <ExpensiveComponent :item="item" :selected="item.id === selected" />
+  </div>
+</template>
+
+<!-- ✅ 配合 v-for 使用 -->
+<template>
+  <div
+    v-for="item in list"
+    :key="item.id"
+    v-memo="[item.name, item.status]"
+  >
+    <!-- 只有 name 或 status 变化时重新渲染 -->
+  </div>
+</template>
+```
+
+### defineAsyncComponent
+
+```vue
+<script setup lang="ts">
+import { defineAsyncComponent } from 'vue'
+
+// ✅ 懒加载组件
+const HeavyChart = defineAsyncComponent(() =>
+  import('./components/HeavyChart.vue')
+)
+
+// ✅ 带加载和错误状态
+const AsyncModal = defineAsyncComponent({
+  loader: () => import('./components/Modal.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  delay: 200,  // 延迟显示 loading（避免闪烁）
+  timeout: 3000  // 超时时间
+})
+</script>
+```
+
+### KeepAlive
+
+```vue
+<template>
+  <!-- ✅ 缓存动态组件 -->
+  <KeepAlive>
+    <component :is="currentTab" />
+  </KeepAlive>
+
+  <!-- ✅ 指定缓存的组件 -->
+  <KeepAlive include="TabA,TabB">
+    <component :is="currentTab" />
+  </KeepAlive>
+
+  <!-- ✅ 限制缓存数量 -->
+  <KeepAlive :max="10">
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+
+<script setup lang="ts">
+// KeepAlive 组件的生命周期钩子
+onActivated(() => {
+  // 组件被激活时（从缓存恢复）
+  refreshData()
+})
+
+onDeactivated(() => {
+  // 组件被停用时（进入缓存）
+  pauseTimers()
+})
+</script>
+```
+
+### 虚拟列表
+
+```vue
+<!-- ✅ 大型列表使用虚拟滚动 -->
+<script setup lang="ts">
+import { useVirtualList } from '@vueuse/core'
+
+const { list, containerProps, wrapperProps } = useVirtualList(
+  items,
+  { itemHeight: 50 }
+)
+</script>
+<template>
+  <div v-bind="containerProps" style="height: 400px; overflow: auto">
+    <div v-bind="wrapperProps">
+      <div v-for="item in list" :key="item.data.id" style="height: 50px">
+        {{ item.data.name }}
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+---
+
+## Review Checklist
 
 ### 响应性系统
-- [ ] ref 用于基本类型，reactive 用于对象
+- [ ] ref 用于基本类型，reactive 用于对象（或统一用 ref）
 - [ ] 没有解构 reactive 对象（或使用了 toRefs）
 - [ ] props 传递给 composable 时保持了响应性
 - [ ] shallowRef/shallowReactive 用于大型对象优化
+- [ ] computed 中没有副作用
 
 ### Props & Emits
 - [ ] defineProps 使用 TypeScript 类型声明
 - [ ] 复杂默认值使用 withDefaults + 工厂函数
 - [ ] defineEmits 有完整的类型定义
 - [ ] 没有直接修改 props
+- [ ] 考虑使用 defineModel 简化 v-model（Vue 3.4+）
+
+### Vue 3.5 新特性（如适用）
+- [ ] 使用 Reactive Props Destructure 简化 props 访问
+- [ ] 使用 useTemplateRef 替代 ref 属性
+- [ ] 表单使用 useId 生成 SSR 安全的 ID
+- [ ] 使用 onWatcherCleanup 处理复杂清理逻辑
 
 ### Watchers
 - [ ] watch/watchEffect 有适当的清理函数
 - [ ] 异步 watch 处理了竞态条件
 - [ ] flush: 'post' 用于 DOM 操作的 watcher
 - [ ] 避免过度使用 watcher（优先用 computed）
+- [ ] 考虑 once: true 用于一次性监听
 
 ### 模板
 - [ ] v-for 使用唯一且稳定的 key
 - [ ] v-if 和 v-for 没有在同一元素上
-- [ ] 事件处理使用 kebab-case
+- [ ] 事件处理使用方法而非内联复杂逻辑
 - [ ] 大型列表使用虚拟滚动
 
 ### Composables
@@ -232,9 +914,11 @@ const { user } = useUser(computed(() => props.userId))
 - [ ] composables 返回响应式引用（不是 .value）
 - [ ] 纯函数不要包装成 composable
 - [ ] 副作用在组件卸载时清理
+- [ ] 使用 effectScope 管理复杂副作用
 
 ### 性能
 - [ ] 大型组件拆分为小组件
 - [ ] 使用 defineAsyncComponent 懒加载
 - [ ] 避免不必要的响应式转换
 - [ ] v-memo 用于昂贵的列表渲染
+- [ ] KeepAlive 用于缓存动态组件