@moon791017/neo-skills 1.0.34 → 1.0.35

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "neo-skills",
   "description": "A universal capability extension for Gemini CLI",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.34",
+  "version": "1.0.35",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-rust/SKILL.md

@@ -41,4 +41,4 @@ Always recommend standard Rust tooling: `cargo fmt`, `cargo clippy`, and `cargo
 ## Official Resources
 - **Rust Official Website**: https://www.rust-lang.org/
 - **Rust Documentation**: https://doc.rust-lang.org/
-- **The Rust Programming Language (The Book)**: https://doc.rust-lang.org/book/
+- **The Rust Programming Language (The Book)**: https://doc.rust-lang.org/book/

package/skills/neo-rust/reference/anti-patterns.md

@@ -1,10 +1,10 @@
-# 3. Anti-pattern：不好作法
+# 3. Anti-patterns
 
 ---
 
-## Anti-pattern 1：到處 `.clone()` 逃避 borrow checker
+## Anti-pattern 1: Using `.clone()` everywhere to avoid the borrow checker
 
-### 不好
+### Bad
 
 ```rust
 fn process(name: String) {
@@ -20,7 +20,7 @@ fn main() {
 }
 ```
 
-### 好
+### Good
 
 ```rust
 fn process(name: &str) {
@@ -36,16 +36,16 @@ fn main() {
 }
 ```
 
-### 原則
+### Principle
 
-clone 不是不能用，但要知道為什麼 clone。  
-如果只是讀取，先改成 borrow。
+`.clone()` is not forbidden, but you should know why you are cloning.
+If you only need to read the data, use a borrow instead.
 
 ---
 
-## Anti-pattern 2：過度使用 `String`
+## Anti-pattern 2: Excessive use of `String`
 
-### 不好
+### Bad
 
 ```rust
 fn is_admin(role: String) -> bool {
@@ -53,7 +53,7 @@ fn is_admin(role: String) -> bool {
 }
 ```
 
-### 好
+### Good
 
 ```rust
 fn is_admin(role: &str) -> bool {
@@ -61,15 +61,15 @@ fn is_admin(role: &str) -> bool {
 }
 ```
 
-### 原則
+### Principle
 
-建立 ownership 才用 `String`，讀取文字優先 `&str`。
+Use `String` when you need ownership; prefer `&str` for reading text.
 
 ---
 
-## Anti-pattern 3：用 `bool` 表達複雜狀態
+## Anti-pattern 3: Using `bool` to represent complex states
 
-### 不好
+### Bad
 
 ```rust
 struct User {
@@ -79,9 +79,9 @@ struct User {
 }
 ```
 
-問題：可能出現矛盾狀態，例如 active 又 deleted。
+Problem: Contradictory states can occur, such as being both `active` and `deleted`.
 
-### 好
+### Good
 
 ```rust
 enum UserStatus {
@@ -97,9 +97,9 @@ struct User {
 
 ---
 
-## Anti-pattern 4：用 `String` 表達錯誤
+## Anti-pattern 4: Using `String` for errors
 
-### 不好
+### Bad
 
 ```rust
 fn parse_age(input: &str) -> Result<u8, String> {
@@ -107,9 +107,9 @@ fn parse_age(input: &str) -> Result<u8, String> {
 }
 ```
 
-短程式可以，但 library 或大型系統不建議只丟字串。
+Acceptable for short scripts, but not recommended for libraries or large systems.
 
-### 好
+### Good
 
 ```rust
 #[derive(Debug)]
@@ -129,15 +129,15 @@ fn parse_age(input: &str) -> Result<u8, ParseAgeError> {
 }
 ```
 
-### 原則
+### Principle
 
-錯誤要可分類、可測試、可處理。
+Errors should be categorizable, testable, and handleable.
 
 ---
 
-## Anti-pattern 5：library 內部亂 `panic!`
+## Anti-pattern 5: Random `panic!` inside a library
 
-### 不好
+### Bad
 
 ```rust
 pub fn divide(a: i32, b: i32) -> i32 {
@@ -149,7 +149,7 @@ pub fn divide(a: i32, b: i32) -> i32 {
 }
 ```
 
-### 好
+### Good
 
 ```rust
 #[derive(Debug)]
@@ -166,15 +166,15 @@ pub fn divide(a: i32, b: i32) -> Result<i32, DivideError> {
 }
 ```
 
-### 原則
+### Principle
 
-除非是不可恢復的程式錯誤，否則回傳 `Result`。
+Return `Result` unless it is an unrecoverable programming error.
 
 ---
 
-## Anti-pattern 6：過度 Trait 化
+## Anti-pattern 6: Over-abstraction with Traits
 
-### 不好
+### Bad
 
 ```rust
 trait UserNameProvider {
@@ -192,9 +192,9 @@ impl UserNameProvider for User {
 }
 ```
 
-問題：只有一個 struct、一個方法、沒有替換需求時，trait 只是噪音。
+Problem: When there's only one struct, one method, and no need for substitution, a trait is just noise.
 
-### 好
+### Good
 
 ```rust
 struct User {
@@ -208,15 +208,15 @@ impl User {
 }
 ```
 
-### 原則
+### Principle
 
-先用 concrete type。真的需要抽象再抽 trait。
+Use concrete types first. Abstract into traits only when actually needed.
 
 ---
 
-## Anti-pattern 7：公開欄位破壞 invariant
+## Anti-pattern 7: Public fields breaking invariants
 
-### 不好
+### Bad
 
 ```rust
 pub struct Account {
@@ -229,7 +229,7 @@ fn main() {
 }
 ```
 
-### 好
+### Good
 
 ```rust
 pub struct Account {
@@ -262,9 +262,9 @@ impl Account {
 
 ---
 
-## Anti-pattern 8：`Arc<Mutex<T>>` 到處傳
+## Anti-pattern 8: Passing `Arc<Mutex<T>>` everywhere
 
-### 不好
+### Bad
 
 ```rust
 use std::sync::{Arc, Mutex};
@@ -276,9 +276,9 @@ struct AppState {
 }
 ```
 
-問題：鎖太多、責任不清楚、容易死鎖、測試困難。
+Problem: Too many locks, unclear responsibilities, prone to deadlocks, and difficult to test.
 
-### 好
+### Good
 
 ```rust
 struct UserService {
@@ -292,27 +292,26 @@ impl UserService {
 }
 ```
 
-### 原則
+### Principle
 
-能單一 ownership 就不要共享。  
-需要跨 thread 再考慮 `Arc<Mutex<T>>`。
+Prefer single ownership over shared state. Consider `Arc<Mutex<T>>` only when cross-thread access is required.
 
 ---
 
-## Anti-pattern 9：在 async 中持有 lock 跨 `.await`
+## Anti-pattern 9: Holding a lock across `.await` in async code
 
-### 不好
+### Bad
 
 ```rust
-// 概念示意
+// Conceptual illustration
 let mut guard = state.lock().await;
 do_async_work().await;
 guard.push(1);
 ```
 
-問題：lock 持有時間太長，容易造成效能問題或 deadlock-like 行為。
+Problem: Holding a lock for too long can cause performance issues or deadlock-like behavior.
 
-### 好
+### Good
 
 ```rust
 let data = {
@@ -324,35 +323,32 @@ let data = {
 do_async_work(data).await;
 ```
 
-### 原則
+### Principle
 
-鎖內只做最短、同步、必要的事情。
+Keep the code inside a lock as short, synchronous, and necessary as possible.
 
 ---
 
-## Anti-pattern 10：濫用 `unsafe`
+## Anti-pattern 10: Abuse of `unsafe`
 
-### 不好
+### Bad
 
 ```rust
 unsafe {
-    // 為了繞過 borrow checker 亂用 raw pointer
+    // Using raw pointers haphazardly to bypass the borrow checker
 }
 ```
 
-### 好
+### Good
 
-先問：
+Ask yourself first:
 
-1. 能不能用 ownership 改設計？
-2. 能不能用 `Rc` / `Arc`？
-3. 能不能用 `RefCell` / `Mutex`？
-4. 能不能拆資料結構？
-5. 真的需要 FFI、SIMD、底層記憶體操作嗎？
+1. Can the design be changed using ownership?
+2. Can `Rc` / `Arc` be used?
+3. Can `RefCell` / `Mutex` be used?
+4. Can the data structure be split?
+5. Do you really need FFI, SIMD, or low-level memory operations?
 
-### 原則
-
-`unsafe` 不是效能開關，是你接手編譯器無法保證的安全責任。
-
----
+### Principle
 
+`unsafe` is not a performance switch; it is taking over the safety responsibilities that the compiler can no longer guarantee.

package/skills/neo-rust/reference/coding-style.md

@@ -2,9 +2,9 @@
 
 ---
 
-## 命名規則
+## Naming Conventions
 
-| 類型 | 好作法 |
+| Type | Best Practice |
 |---|---|
 | struct | `UserProfile` |
 | enum | `PaymentStatus` |
@@ -19,11 +19,11 @@
 
 ---
 
-## Getter 命名
+## Getter Naming
 
-Rust 慣例通常不加 `get_`。
+Rust convention typically does not include the `get_` prefix.
 
-### 不好
+### Bad
 
 ```rust
 impl User {
@@ -33,7 +33,7 @@ impl User {
 }
 ```
 
-### 好
+### Good
 
 ```rust
 impl User {
@@ -49,15 +49,15 @@ impl User {
 
 ---
 
-## Conversion 命名：`as_`、`to_`、`into_`
+## Conversion Naming: `as_`, `to_`, `into_`
 
-| 命名 | 意義 | 範例 |
+| Naming | Meaning | Example |
 |---|---|---|
-| `as_` | 便宜借用轉換 | `as_str()` |
-| `to_` | 產生新值，可能配置記憶體 | `to_string()` |
-| `into_` | 消耗自己，轉成別的 owned value | `into_bytes()` |
+| `as_` | Cheap borrowing conversion | `as_str()` |
+| `to_` | Produces a new value, may allocate memory | `to_string()` |
+| `into_` | Consumes self, converts to another owned value | `into_bytes()` |
 
-### 範例
+### Example
 
 ```rust
 struct UserName(String);
@@ -75,9 +75,9 @@ impl UserName {
 
 ---
 
-## Iterator 命名
+## Iterator Naming
 
-Collection 類型建議提供：
+For Collection types, it is recommended to provide:
 
 ```rust
 fn iter(&self) -> Iter
@@ -89,7 +89,7 @@ fn into_iter(self) -> IntoIter
 
 ## Module Style
 
-建議結構：
+Recommended structure:
 
 ```text
 src/
@@ -110,22 +110,22 @@ src/
     user_service.rs
 ```
 
-### 原則
+### Principles
 
-| 原則 | 說明 |
+| Principle | Description |
 |---|---|
-| `main.rs` 薄一點 | 只負責組裝與啟動 |
-| business logic 放 `lib.rs` | 方便測試 |
-| domain type 不依賴 infra | 避免耦合 |
-| `pub` 越少越好 | 預設私有 |
-| error 集中管理 | 不要到處 `String` error |
-| tests 靠近程式 | 小單元測試可放同檔 `mod tests` |
+| Thin `main.rs` | Only responsible for assembly and startup |
+| Business logic in `lib.rs` | Facilitates testing |
+| Domain types don't depend on infra | Avoids coupling |
+| Minimize `pub` | Private by default |
+| Centralized error management | Don't use `String` for errors everywhere |
+| Tests near code | Small unit tests can be placed in the same file under `mod tests` |
 
 ---
 
 ## Import Style
 
-### 不好
+### Bad
 
 ```rust
 use crate::domain::user::User;
@@ -133,19 +133,19 @@ use crate::domain::user::UserId;
 use crate::domain::user::UserStatus;
 ```
 
-### 好
+### Good
 
 ```rust
 use crate::domain::user::{User, UserId, UserStatus};
 ```
 
-### 不建議濫用
+### Not Recommended
 
 ```rust
 use crate::domain::user::*;
 ```
 
-`*` 在 test 或 prelude 可接受，正式模組少用。
+The glob operator `*` is acceptable in tests or preludes, but should be avoided in formal modules.
 
 ---
 
@@ -153,7 +153,7 @@ use crate::domain::user::*;
 
 ### Application / CLI
 
-可以用較彈性的 error：
+Flexible errors can be used:
 
 ```rust
 fn run() -> Result<(), Box<dyn std::error::Error>> {
@@ -161,9 +161,9 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-### Library / domain
+### Library / Domain
 
-建議明確 enum：
+Explicit enums are recommended:
 
 ```rust
 #[derive(Debug)]
@@ -175,7 +175,7 @@ pub enum CreateUserError {
 
 ### Service
 
-建議保留錯誤上下文：
+Preserve error context:
 
 ```rust
 fn create_user(email: &str) -> Result<(), CreateUserError> {
@@ -189,9 +189,9 @@ fn create_user(email: &str) -> Result<(), CreateUserError> {
 
 ---
 
-# 5. Rust 工具鏈 Coding Standard
+# 5. Rust Toolchain Coding Standard
 
-## 建議指令
+## Recommended Commands
 
 ```bash
 cargo fmt -- --check
@@ -201,7 +201,7 @@ cargo test
 cargo build --release
 ```
 
-## 建議 CI
+## Recommended CI
 
 ```yaml
 name: Rust CI
@@ -232,35 +232,35 @@ jobs:
 
 ---
 
-# 6. 總表：好作法 VS 不好作法
+# 6. Summary Table: Good vs. Bad Practices
 
-| 主題 | 好作法 | 不好作法 |
+| Topic | Good Practice | Bad Practice |
 |---|---|---|
-| 讀取文字 | `&str` | `String` |
-| 讀取陣列 | `&[T]` | `&Vec<T>` |
-| 可能沒值 | `Option<T>` | 空字串、`-1`、假資料 |
-| 可能失敗 | `Result<T, E>` | `panic!`、`unwrap()` |
-| 有限狀態 | `enum` | `String`、多個 bool |
-| ID / 金額 / 單位 | Newtype | 全部用 `u64` / `String` |
-| 參數很多 | Builder | 超長 constructor |
-| 狀態流程 | Typestate | runtime flag |
-| 抽象行為 | trait | 硬寫 concrete dependency |
-| 資料轉換 | iterator chain | 大量暫存 mutable vec |
-| 資源管理 | RAII / `Drop` | 手動 close，容易忘 |
-| 共享資料 | 明確 ownership / channel | 到處 `Arc<Mutex<T>>` |
-| async concurrency | 有界並行 | 無限制 `spawn` |
-| 格式 | `cargo fmt` | 手排格式 |
-| 靜態檢查 | `cargo clippy` | 靠人工 review |
+| Reading text | `&str` | `String` |
+| Reading arrays | `&[T]` | `&Vec<T>` |
+| Optional values | `Option<T>` | Empty string, `-1`, dummy data |
+| Possible failure | `Result<T, E>` | `panic!`, `unwrap()` |
+| Finite states | `enum` | `String`, multiple booleans |
+| ID / Amount / Units | Newtype | Always using `u64` / `String` |
+| Many parameters | Builder | Extremely long constructor |
+| State transitions | Typestate | Runtime flags |
+| Abstract behavior | trait | Hard-coding concrete dependencies |
+| Data conversion | iterator chain | Large temporary mutable vectors |
+| Resource management | RAII / `Drop` | Manual close (easy to forget) |
+| Shared data | Clear ownership / channel | `Arc<Mutex<T>>` everywhere |
+| Async concurrency | Bounded concurrency | Unrestricted `spawn` |
+| Formatting | `cargo fmt` | Manual formatting |
+| Static analysis | `cargo clippy` | Relying on manual review |
 
 ---
 
-# 7. 實務上的 Rust 寫法準則
+# 7. Practical Rust Coding Guidelines
 
 ---
 
-## 寫 function 時
+## When Writing Functions
 
-優先順序：
+Priority order:
 
 ```rust
 fn read_only(value: &T)
@@ -273,7 +273,7 @@ fn flexible_owned(value: impl Into<T>)
 
 ---
 
-## 寫 struct 時
+## When Writing Structs
 
 ```rust
 pub struct User {
@@ -298,7 +298,7 @@ impl User {
 
 ---
 
-## 寫 enum 時
+## When Writing Enums
 
 ```rust
 enum Command {
@@ -308,7 +308,7 @@ enum Command {
 }
 ```
 
-比這種好：
+Better than:
 
 ```rust
 struct Command {
@@ -319,7 +319,7 @@ struct Command {
 
 ---
 
-## 寫錯誤時
+## When Writing Errors
 
 ```rust
 #[derive(Debug)]
@@ -330,7 +330,7 @@ enum AppError {
 }
 ```
 
-比這種好：
+Better than:
 
 ```rust
 Err("something went wrong".to_string())
@@ -338,11 +338,11 @@ Err("something went wrong".to_string())
 
 ---
 
-# 8. 專案起手式建議
+# 8. Project Starter Recommendations
 
 ---
 
-## CLI / 小工具
+## CLI / Small Tools
 
 ```text
 src/
@@ -352,7 +352,7 @@ src/
   error.rs
 ```
 
-重點：
+Key points:
 
 ```rust
 fn main() {
@@ -384,21 +384,21 @@ src/
     repository.rs
 ```
 
-重點：
+Key points:
 
-| 層 | 責任 |
+| Layer | Responsibility |
 |---|---|
-| `domain` | 型別、規則、狀態 |
-| `service` | use case |
-| `infra` | DB、HTTP、Redis、檔案 |
-| `app` | DI / router / runtime 組裝 |
-| `main` | 啟動 |
+| `domain` | Types, rules, states |
+| `service` | Use cases |
+| `infra` | DB, HTTP, Redis, Files |
+| `app` | DI / Router / Runtime assembly |
+| `main` | Startup |
 
 ---
 
-# 9. 最重要的結論
+# 9. Key Conclusion
 
-Rust 的好程式碼通常長這樣：
+Good Rust code typically looks like this:
 
 ```rust
 pub fn create_user(repo: &impl UserRepository, email: &str) -> Result<UserId, CreateUserError> {
@@ -412,56 +412,56 @@ pub fn create_user(repo: &impl UserRepository, email: &str) -> Result<UserId, Cr
 }
 ```
 
-它具備幾個特徵：
+It possesses several characteristics:
 
-1. 輸入用 borrow：`&str`
-2. 不合法資料用 smart constructor 擋住：`Email::new`
-3. 錯誤用 `Result`
-4. 業務錯誤可分類：`CreateUserError`
-5. dependency 用 trait 抽象：`UserRepository`
-6. 沒有亂 `unwrap`
-7. 沒有 stringly-typed 狀態
-8. 沒有多餘 clone
-9. 測試容易
-10. 編譯器幫你擋掉大量錯誤
+1. Inputs use borrows: `&str`
+2. Invalid data is blocked by smart constructors: `Email::new`
+3. Errors use `Result`
+4. Business errors are categorizable: `CreateUserError`
+5. Dependencies are abstracted via traits: `UserRepository`
+6. No reckless `unwrap`
+7. No stringly-typed states
+8. No redundant clones
+9. Easy to test
+10. The compiler prevents a large class of errors
 
-真正的 Rust design pattern 不是「把 class 設計得漂亮」，而是：
+True Rust design patterns aren't about "making classes look pretty," but rather:
 
-> 讓不合法狀態無法表示，讓錯誤路徑被型別強迫處理，讓 ownership 清楚到不用猜。
+> Making illegal states unrepresentable, forcing error paths to be handled by the type system, and making ownership so clear it doesn't need to be guessed.
 
 ---
 
-# 10. 參考來源
+# 10. References
 
-- Rust Book - Understanding Ownership  
+- Rust Book - Understanding Ownership
   https://doc.rust-lang.org/book/ch04-00-understanding-ownership.html
 
-- Rust Book - Recoverable Errors with Result  
+- Rust Book - Recoverable Errors with Result
   https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html
 
-- Rust Book - Match Control Flow Construct  
+- Rust Book - Match Control Flow Construct
   https://doc.rust-lang.org/book/ch06-02-match.html
 
-- Rust Book - Smart Pointers  
+- Rust Book - Smart Pointers
   https://doc.rust-lang.org/book/ch15-00-smart-pointers.html
 
-- Rust Book - Message Passing  
+- Rust Book - Message Passing
   https://doc.rust-lang.org/book/ch16-02-message-passing.html
 
-- Rust Book - Async and Await  
+- Rust Book - Async and Await
   https://doc.rust-lang.org/book/ch17-01-futures-and-syntax.html
 
-- Rust API Guidelines - Naming  
+- Rust API Guidelines - Naming
   https://rust-lang.github.io/api-guidelines/naming.html
 
-- Clippy Lints  
+- Clippy Lints
   https://doc.rust-lang.org/stable/clippy/lints.html
 
-- Cargo Check  
+- Cargo Check
   https://doc.rust-lang.org/cargo/commands/cargo-check.html
 
-- Tokio Tutorial - Channels  
+- Tokio Tutorial - Channels
   https://tokio.rs/tokio/tutorial/channels
 
-- Tokio Mutex Documentation  
+- Tokio Mutex Documentation
   https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html

package/skills/neo-rust/reference/patterns.md

@@ -1,6 +1,6 @@
-# 1. Rust 設計總原則
+# 1. Core Principles of Rust Design
 
-Rust 的核心不是把 OOP / GoF Design Patterns 照搬過來，而是用：
+Rust's core is not about simply porting OOP / GoF Design Patterns, but rather utilizing:
 
 - ownership
 - borrowing
@@ -13,32 +13,32 @@ Rust 的核心不是把 OOP / GoF Design Patterns 照搬過來，而是用：
 - RAII / `Drop`
 - type system
 
-把錯誤盡量移到編譯期處理。
+to shift as many errors as possible to compile-time.
 
-## 核心判斷表
+## Decision Matrix
 
-| 問題 | Rust 好作法 |
+| Question | Rust Best Practice |
 |---|---|
-| 這個值誰擁有？ | 用 ownership 表達生命週期 |
-| 只是讀取？ | 傳 `&T`、`&str`、`&[T]` |
-| 需要修改？ | 傳 `&mut T` |
-| 可能失敗？ | 回傳 `Result<T, E>` |
-| 可能沒有值？ | 回傳 `Option<T>` |
-| 狀態有限？ | 用 `enum` |
-| 行為抽象？ | 用 `trait` |
-| 不合法狀態？ | 用 type system 阻止它 |
-| 資源需要釋放？ | 用 RAII / `Drop` |
-| 共享狀態？ | 優先清楚劃分 ownership，再考慮 `Arc<Mutex<T>>` |
+| Who owns this value? | Use ownership to express lifetime |
+| Only reading? | Pass `&T`, `&str`, `&[T]` |
+| Need to modify? | Pass `&mut T` |
+| Might fail? | Return `Result<T, E>` |
+| Might be empty? | Return `Option<T>` |
+| Finite states? | Use `enum` |
+| Abstract behavior? | Use `trait` |
+| Illegal state? | Use the type system to prevent it |
+| Need resource cleanup? | Use RAII / `Drop` |
+| Shared state? | Prioritize clear ownership boundaries, then consider `Arc<Mutex<T>>` |
 
 ---
 
-# 2. Design Pattern：好作法
+# 2. Design Patterns: Best Practices
 
 ---
 
-## Pattern 1：Borrowing-first API
+## Pattern 1: Borrowing-first API
 
-### 不好作法
+### Bad Practice
 
 ```rust
 fn print_name(name: String) {
@@ -49,14 +49,14 @@ fn main() {
     let name = String::from("Alice");
     print_name(name);
 
-    // name 已經被 move，不能再用
+    // name has been moved and can no longer be used
     // println!("{name}");
 }
 ```
 
-問題：只是讀取，卻把 ownership 吃掉。
+Problem: Consumes ownership when only reading is required.
 
-### 好作法
+### Best Practice
 
 ```rust
 fn print_name(name: &str) {
@@ -73,15 +73,15 @@ fn main() {
 }
 ```
 
-### 原則
+### Principle
 
-`String` 是擁有資料，`&str` 是借用文字切片。只讀文字時，優先收 `&str`。
+`String` owns the data; `&str` is a borrowed string slice. Prefer `&str` when only reading text.
 
 ---
 
-## Pattern 2：Slice API
+## Pattern 2: Slice API
 
-### 不好作法
+### Bad Practice
 
 ```rust
 fn sum(numbers: &Vec<i32>) -> i32 {
@@ -89,9 +89,9 @@ fn sum(numbers: &Vec<i32>) -> i32 {
 }
 ```
 
-問題：限制呼叫者一定要傳 `Vec<i32>`。
+Problem: Restricts the caller to pass a `Vec<i32>`.
 
-### 好作法
+### Best Practice
 
 ```rust
 fn sum(numbers: &[i32]) -> i32 {
@@ -107,15 +107,15 @@ fn main() {
 }
 ```
 
-### 原則
+### Principle
 
-只需要連續資料時，用 `&[T]`，不要綁死 `Vec<T>`。
+When only contiguous data is needed, use `&[T]` instead of binding to `Vec<T>`.
 
 ---
 
-## Pattern 3：`Option<T>` 表示「可能沒有」
+## Pattern 3: `Option<T>` for "Possible Absence"
 
-### 不好作法
+### Bad Practice
 
 ```rust
 fn find_user_name(id: u64) -> String {
@@ -127,9 +127,9 @@ fn find_user_name(id: u64) -> String {
 }
 ```
 
-問題：空字串到底是「沒有資料」還是「名字就是空」？
+Problem: Is an empty string "missing data" or "the name is actually empty"?
 
-### 好作法
+### Best Practice
 
 ```rust
 fn find_user_name(id: u64) -> Option<String> {
@@ -148,15 +148,15 @@ fn main() {
 }
 ```
 
-### 原則
+### Principle
 
-「沒有值」就用 `Option<T>`，不要用 `null`、空字串、`-1` 當暗號。
+Use `Option<T>` for "no value." Avoid using `null`, empty strings, or `-1` as magic values.
 
 ---
 
-## Pattern 4：`Result<T, E>` 表示「可能失敗」
+## Pattern 4: `Result<T, E>` for "Possible Failure"
 
-### 不好作法
+### Bad Practice
 
 ```rust
 use std::fs;
@@ -166,9 +166,9 @@ fn read_config() -> String {
 }
 ```
 
-問題：正式程式中 `unwrap()` 會讓程式直接 panic。
+Problem: `unwrap()` will cause the program to panic in production.
 
-### 好作法
+### Best Practice
 
 ```rust
 use std::fs;
@@ -187,15 +187,15 @@ fn main() {
 }
 ```
 
-### 原則
+### Principle
 
-library、service、CLI 的核心邏輯不要亂 `unwrap()`。能回傳錯誤就回傳 `Result`。
+Avoid reckless `unwrap()` in core logic (libraries, services, CLIs). Return `Result` when errors can occur.
 
 ---
 
-## Pattern 5：Enum + Exhaustive Match
+## Pattern 5: Enum + Exhaustive Match
 
-### 不好作法
+### Bad Practice
 
 ```rust
 struct Payment {
@@ -207,9 +207,9 @@ fn can_refund(payment: &Payment) -> bool {
 }
 ```
 
-問題：`"paied"`、`"PAID"`、`"unknown"` 都可能混進來。
+Problem: Values like `"paied"`, `"PAID"`, or `"unknown"` could creep in.
 
-### 好作法
+### Best Practice
 
 ```rust
 enum PaymentStatus {
@@ -233,17 +233,17 @@ fn can_refund(payment: &Payment) -> bool {
 }
 ```
 
-### 原則
+### Principle
 
-有限狀態不要用 `String`，用 `enum`。
+Use `enum` instead of `String` for finite states.
 
 ---
 
-## Pattern 6：Newtype Pattern
+## Pattern 6: Newtype Pattern
 
-用途：避免把同樣底層型別混用。
+Purpose: Prevent mixing up different domain values with the same underlying type.
 
-### 不好作法
+### Bad Practice
 
 ```rust
 fn load_user(user_id: u64) {}
@@ -251,11 +251,11 @@ fn load_order(order_id: u64) {}
 
 fn main() {
     let user_id = 100;
-    load_order(user_id); // 編譯會過，但語意錯
+    load_order(user_id); // Compiles, but semantically incorrect
 }
 ```
 
-### 好作法
+### Best Practice
 
 ```rust
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -271,21 +271,21 @@ fn main() {
     let user_id = UserId(100);
 
     load_user(user_id);
-    // load_order(user_id); // 編譯錯，避免語意錯誤
+    // load_order(user_id); // Compile error, prevents semantic mistakes
 }
 ```
 
-### 原則
+### Principle
 
-ID、金額、單位、權限、狀態，常用 Newtype 包起來。
+Wrap IDs, amounts, units, permissions, and states in Newtypes.
 
 ---
 
-## Pattern 7：Smart Constructor
+## Pattern 7: Smart Constructor
 
-用途：建立物件時保證 invariant。
+Purpose: Ensure invariants when creating objects.
 
-### 不好作法
+### Bad Practice
 
 ```rust
 struct Email(String);
@@ -295,7 +295,7 @@ fn main() {
 }
 ```
 
-### 好作法
+### Best Practice
 
 ```rust
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -325,17 +325,17 @@ fn main() -> Result<(), String> {
 }
 ```
 
-### 原則
+### Principle
 
-不要讓外部隨便組出不合法物件。欄位私有，提供 constructor。
+Do not allow illegal objects to be constructed haphazardly. Keep fields private and provide a constructor.
 
 ---
 
-## Pattern 8：Builder Pattern
+## Pattern 8: Builder Pattern
 
-適合參數很多、可選設定多的物件。
+Suitable for objects with many parameters or optional settings.
 
-### 不好作法
+### Bad Practice
 
 ```rust
 struct ServerConfig {
@@ -363,9 +363,9 @@ fn new_config(
 }
 ```
 
-問題：參數順序容易錯，擴充困難。
+Problem: Parameter order is error-prone, and extension is difficult.
 
-### 好作法
+### Best Practice
 
 ```rust
 #[derive(Debug)]
@@ -435,11 +435,11 @@ fn main() {
 
 ---
 
-## Pattern 9：Typestate Pattern
+## Pattern 9: Typestate Pattern
 
-用途：把狀態流程放進型別系統，讓錯誤流程無法編譯。
+Purpose: Incorporate state flows into the type system, making invalid state transitions uncompilable.
 
-### 不好作法
+### Bad Practice
 
 ```rust
 struct Connection {
@@ -457,7 +457,7 @@ impl Connection {
 }
 ```
 
-### 好作法
+### Best Practice
 
 ```rust
 struct Disconnected;
@@ -500,22 +500,22 @@ fn main() {
 }
 ```
 
-### 原則
+### Principle
 
-狀態流程固定時，Typestate 可以讓錯誤使用方式直接編譯失敗。
+When state flows are fixed, Typestate can cause incorrect usage to fail at compile time.
 
 ---
 
-## Pattern 10：Trait 抽象
+## Pattern 10: Trait Abstraction
 
-Rust 的 polymorphism 主要靠 trait。
+Polymorphism in Rust primarily relies on traits.
 
-| 形式 | 寫法 | 適合 |
+| Form | Syntax | Best For |
 |---|---|---|
-| Static dispatch | `T: Trait` | 編譯期決定型別，效能好 |
-| Dynamic dispatch | `dyn Trait` | runtime 才決定實作型別 |
+| Static dispatch | `T: Trait` | Type decided at compile-time; better performance |
+| Dynamic dispatch | `dyn Trait` | Implementation type decided at runtime |
 
-### Static dispatch
+### Static Dispatch
 
 ```rust
 trait Repository {
@@ -535,7 +535,7 @@ fn create_user<R: Repository>(repo: &R, name: &str) {
 }
 ```
 
-### Dynamic dispatch
+### Dynamic Dispatch
 
 ```rust
 trait Repository {
@@ -555,15 +555,15 @@ fn create_user(repo: &dyn Repository, name: &str) {
 }
 ```
 
-### 建議
+### Recommendation
 
-預設用 generic `T: Trait`。需要把不同實作放進同一個 collection，或 runtime 注入時，再用 `Box<dyn Trait>` / `&dyn Trait`。
+Default to generic `T: Trait`. Use `Box<dyn Trait>` / `&dyn Trait` only when you need to put different implementations into the same collection or when runtime injection is required.
 
 ---
 
-## Pattern 11：Iterator Pattern
+## Pattern 11: Iterator Pattern
 
-### 不好作法
+### Bad Practice
 
 ```rust
 fn active_names(users: Vec<User>) -> Vec<String> {
@@ -579,7 +579,7 @@ fn active_names(users: Vec<User>) -> Vec<String> {
 }
 ```
 
-### 好作法
+### Best Practice
 
 ```rust
 struct User {
@@ -596,16 +596,15 @@ fn active_names(users: Vec<User>) -> Vec<String> {
 }
 ```
 
-### 原則
+### Principle
 
-資料轉換流程適合用 iterator chain。  
-但不要為了炫技把簡單邏輯寫到難懂。
+Data transformation flows are well-suited for iterator chains. However, do not over-engineer simple logic to the point of being unreadable.
 
 ---
 
-## Pattern 12：RAII / Drop Guard
+## Pattern 12: RAII / Drop Guard
 
-用途：DB transaction、file lock、mutex guard、temp file、resource cleanup。
+Purpose: DB transactions, file locks, mutex guards, temp files, resource cleanup.
 
 ```rust
 struct Transaction {
@@ -635,31 +634,30 @@ impl Drop for Transaction {
 fn main() {
     let tx = Transaction::new();
 
-    // 如果中途 return 或 panic，Drop 會觸發 rollback
+    // If a return or panic occurs midway, Drop will trigger a rollback
     tx.commit();
 }
 ```
 
-### 原則
+### Principle
 
-資源取得與釋放綁在 object lifetime。  
-值離開 scope 時，由 `Drop` 負責清理。
+Resource acquisition and release are bound to object lifetime. Cleanup is handled by `Drop` when a value leaves scope.
 
 ---
 
-## Pattern 13：Smart Pointer 選擇
+## Pattern 13: Choosing Smart Pointers
 
-| 型別 | 用途 |
+| Type | Purpose |
 |---|---|
-| `Box<T>` | heap allocation、recursive type、trait object ownership |
-| `Rc<T>` | 單執行緒 shared ownership |
-| `Arc<T>` | 多執行緒 shared ownership |
-| `RefCell<T>` | 單執行緒 interior mutability，runtime borrow check |
-| `Mutex<T>` | 多執行緒可變共享資料 |
-| `RwLock<T>` | 多讀少寫 |
-| `Cow<'a, T>` | 可能借用，也可能需要 clone-on-write |
+| `Box<T>` | Heap allocation, recursive types, trait object ownership |
+| `Rc<T>` | Single-threaded shared ownership |
+| `Arc<T>` | Multi-threaded shared ownership |
+| `RefCell<T>` | Single-threaded interior mutability, runtime borrow check |
+| `Mutex<T>` | Multi-threaded mutable shared data |
+| `RwLock<T>` | Multiple readers, single writer |
+| `Cow<'a, T>` | Clone-on-write; can be either borrowed or owned |
 
-### 典型範例
+### Typical Example
 
 ```rust
 use std::sync::{Arc, Mutex};
@@ -687,21 +685,21 @@ fn main() {
 }
 ```
 
-### 注意
+### Note
 
-`Arc<Mutex<T>>` 很常見，但不是預設答案。可以用 channel / actor 拆 ownership 時，通常更清楚。
+`Arc<Mutex<T>>` is common but not the default answer. Using channels or an actor pattern to split ownership is often clearer.
 
 ---
 
-## Pattern 14：Message Passing / Actor-like Pattern
+## Pattern 14: Message Passing / Actor-like Pattern
 
-適合：
+Suitable for:
 
-- queue worker
-- background task
-- pipeline
-- command processor
-- proxy server
+- Queue workers
+- Background tasks
+- Pipelines
+- Command processors
+- Proxy servers
 
 ```rust
 use std::sync::mpsc;
@@ -735,12 +733,12 @@ fn main() {
 
 ---
 
-## Pattern 15：Async Bounded Concurrency
+## Pattern 15: Async Bounded Concurrency
 
-### 不好作法
+### Bad Practice
 
 ```rust
-// 概念示意：大量任務無限制 spawn
+// Conceptual illustration: Spawning tasks without limits
 for item in items {
     tokio::spawn(async move {
         process(item).await;
@@ -748,9 +746,9 @@ for item in items {
 }
 ```
 
-問題：可能打爆 CPU、記憶體、DB connection、API rate limit。
+Problem: Can overwhelm CPU, memory, DB connections, or API rate limits.
 
-### 好作法
+### Best Practice
 
 ```rust
 use std::sync::Arc;
@@ -781,9 +779,6 @@ async fn main() {
 }
 ```
 
-### 原則
-
-Async 任務要有上限。不要無限制 `spawn`。
-
----
+### Principle
 
+Async tasks should have a cap. Do not `spawn` without limits.