@moon791017/neo-skills 1.0.33 → 1.0.34

package/GEMINI.md

@@ -113,3 +113,5 @@ When interacting with this codebase or using the extension, the agent follows th
 *   **JavaScript 現代語法專家:** 跨版本 JavaScript 專家 (ES6-ES2025+)，專注於現代化語法、模組系統與高效能開發模式。
 
 *   **Vue 現代開發專家:** 專注於 Vue 3 Composition API (`<script setup>`)、Pinia 狀態管理與 Vue Router 4，嚴格遵循官方 Style Guide 與最佳實踐。
+
+*   **Rust 專家 (`skills/neo-rust`)**: 用於開發、重構或審查 Rust 應用程式的專家技能，涵蓋 ownership、borrowing、Result/Option 與現代 Rust 設計模式。

package/README.md

@@ -60,13 +60,16 @@
 ### 9. Vue 開發專家
 *   **Vue 3 現代開發專家 (`skills/neo-vue`)**：專注於 Vue 3 Composition API (`<script setup>`)、Pinia 狀態管理與 Vue Router 4。嚴格遵循官方 Style Guide 與最佳實踐，並提供反模式 (Anti-Patterns) 的避坑指引。
 
-### 10. 需求釐清助手
+### 10. Rust 開發專家
+*   **Rust 專家 (`skills/neo-rust`)**：用於開發、重構或審查 Rust 應用程式的專家技能，涵蓋 ownership、borrowing、Result/Option 與現代 Rust 設計模式。
+
+### 11. 需求釐清助手
 *   **需求釐清**：系統化引導用戶釐清模糊需求，並將其轉化為結構化的規格文件（背景、功能、約束、驗收標準）。
 
-### 11. AI 開發流程健檢
+### 12. AI 開發流程健檢
 *   **AI 助手開發治理 (`skills/neo-agent-harness`)**：檢查專案規則、測試、CI、審查流程與安全防護是否足夠清楚，協助 AI 助手更穩定、更安全地參與開發。
 
-### 12. 安全守衛 (Security Guard)
+### 13. 安全守衛 (Security Guard)
 *   **主動防護 (`secret-guard.ts`)**：作為 CLI 的中介軟體 (Hook)，自動攔截並掃描所有工具執行的參數。若偵測到敏感資訊（如環境設定檔、私鑰、雲端憑證等）將強制阻擋執行，防止機密外洩。
 
 ## 📂 系統架構

package/gemini-extension.json

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

package/package.json

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

package/skills/neo-rust/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: neo-rust
+description: 用於開發、重構或審查 Rust 應用程式的專家技能。涵蓋 ownership、borrowing、Result/Option 與現代 Rust 設計模式。當使用者要求撰寫 Rust 程式碼、進行 Code Review 或討論 Rust 架構時使用。
+metadata:
+  pattern: tool-wrapper, reviewer
+  domain: rust
+---
+
+# Neo Rust Expert
+
+You are an expert Rust developer. Your goal is to write safe, maintainable, and idiomatic Rust code by strictly following the official design patterns and avoiding anti-patterns.
+
+## Core Directives
+
+Before writing or reviewing any Rust code, you MUST follow the "Perceive-Reason-Act" loop:
+
+1. **Perceive**: Understand the user's intent. Is it a new feature, a refactor, or a code review?
+2. **Reason**: Load the appropriate reference files based on the task:
+   - For writing new code or architecture design, load `reference/patterns.md` and `reference/coding-style.md`.
+   - For code review or debugging, load `reference/anti-patterns.md` to spot common mistakes.
+3. **Act**: Execute the task adhering strictly to the loaded guidelines.
+
+## When Writing Code
+- Prioritize Borrowing over Ownership where applicable (`&str` instead of `String`).
+- Handle errors gracefully using `Result<T, E>`. Never use `.unwrap()` or `panic!()` in library or production code.
+- Represent "no value" with `Option<T>`, never with magic values like empty strings or `-1`.
+- Use the Type System to prevent invalid states (e.g., Typestate, Newtype, Smart Constructors).
+- Ensure resource cleanup using RAII/Drop.
+- Prefer explicit composition over shared mutable state. Default to single ownership.
+
+## When Reviewing Code
+1. Load `reference/anti-patterns.md`.
+2. Check for unnecessary `.clone()`, excessive use of `String`, and improper error handling.
+3. Verify that `Arc<Mutex<T>>` is not overused where message passing or simple ownership would suffice.
+4. Check naming conventions against `reference/coding-style.md`.
+5. Provide actionable feedback with code examples demonstrating the "Good" approach.
+
+## Tools & Formatting
+Always recommend standard Rust tooling: `cargo fmt`, `cargo clippy`, and `cargo check`.
+
+## 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/

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

@@ -0,0 +1,358 @@
+# 3. Anti-pattern：不好作法
+
+---
+
+## Anti-pattern 1：到處 `.clone()` 逃避 borrow checker
+
+### 不好
+
+```rust
+fn process(name: String) {
+    println!("{name}");
+}
+
+fn main() {
+    let name = String::from("Alice");
+
+    process(name.clone());
+    process(name.clone());
+    process(name.clone());
+}
+```
+
+### 好
+
+```rust
+fn process(name: &str) {
+    println!("{name}");
+}
+
+fn main() {
+    let name = String::from("Alice");
+
+    process(&name);
+    process(&name);
+    process(&name);
+}
+```
+
+### 原則
+
+clone 不是不能用，但要知道為什麼 clone。  
+如果只是讀取，先改成 borrow。
+
+---
+
+## Anti-pattern 2：過度使用 `String`
+
+### 不好
+
+```rust
+fn is_admin(role: String) -> bool {
+    role == "admin"
+}
+```
+
+### 好
+
+```rust
+fn is_admin(role: &str) -> bool {
+    role == "admin"
+}
+```
+
+### 原則
+
+建立 ownership 才用 `String`，讀取文字優先 `&str`。
+
+---
+
+## Anti-pattern 3：用 `bool` 表達複雜狀態
+
+### 不好
+
+```rust
+struct User {
+    is_active: bool,
+    is_deleted: bool,
+    is_locked: bool,
+}
+```
+
+問題：可能出現矛盾狀態，例如 active 又 deleted。
+
+### 好
+
+```rust
+enum UserStatus {
+    Active,
+    Deleted,
+    Locked,
+}
+
+struct User {
+    status: UserStatus,
+}
+```
+
+---
+
+## Anti-pattern 4：用 `String` 表達錯誤
+
+### 不好
+
+```rust
+fn parse_age(input: &str) -> Result<u8, String> {
+    input.parse::<u8>().map_err(|_| "invalid age".to_string())
+}
+```
+
+短程式可以，但 library 或大型系統不建議只丟字串。
+
+### 好
+
+```rust
+#[derive(Debug)]
+enum ParseAgeError {
+    InvalidNumber,
+    TooLarge,
+}
+
+fn parse_age(input: &str) -> Result<u8, ParseAgeError> {
+    let age = input.parse::<u8>().map_err(|_| ParseAgeError::InvalidNumber)?;
+
+    if age > 120 {
+        return Err(ParseAgeError::TooLarge);
+    }
+
+    Ok(age)
+}
+```
+
+### 原則
+
+錯誤要可分類、可測試、可處理。
+
+---
+
+## Anti-pattern 5：library 內部亂 `panic!`
+
+### 不好
+
+```rust
+pub fn divide(a: i32, b: i32) -> i32 {
+    if b == 0 {
+        panic!("divide by zero");
+    }
+
+    a / b
+}
+```
+
+### 好
+
+```rust
+#[derive(Debug)]
+pub enum DivideError {
+    DivideByZero,
+}
+
+pub fn divide(a: i32, b: i32) -> Result<i32, DivideError> {
+    if b == 0 {
+        return Err(DivideError::DivideByZero);
+    }
+
+    Ok(a / b)
+}
+```
+
+### 原則
+
+除非是不可恢復的程式錯誤，否則回傳 `Result`。
+
+---
+
+## Anti-pattern 6：過度 Trait 化
+
+### 不好
+
+```rust
+trait UserNameProvider {
+    fn user_name(&self) -> &str;
+}
+
+struct User {
+    name: String,
+}
+
+impl UserNameProvider for User {
+    fn user_name(&self) -> &str {
+        &self.name
+    }
+}
+```
+
+問題：只有一個 struct、一個方法、沒有替換需求時，trait 只是噪音。
+
+### 好
+
+```rust
+struct User {
+    name: String,
+}
+
+impl User {
+    fn name(&self) -> &str {
+        &self.name
+    }
+}
+```
+
+### 原則
+
+先用 concrete type。真的需要抽象再抽 trait。
+
+---
+
+## Anti-pattern 7：公開欄位破壞 invariant
+
+### 不好
+
+```rust
+pub struct Account {
+    pub balance: i64,
+}
+
+fn main() {
+    let mut account = Account { balance: 100 };
+    account.balance = -999;
+}
+```
+
+### 好
+
+```rust
+pub struct Account {
+    balance: i64,
+}
+
+impl Account {
+    pub fn new(balance: i64) -> Result<Self, String> {
+        if balance < 0 {
+            return Err("balance cannot be negative".to_string());
+        }
+
+        Ok(Self { balance })
+    }
+
+    pub fn balance(&self) -> i64 {
+        self.balance
+    }
+
+    pub fn deposit(&mut self, amount: i64) -> Result<(), String> {
+        if amount <= 0 {
+            return Err("amount must be positive".to_string());
+        }
+
+        self.balance += amount;
+        Ok(())
+    }
+}
+```
+
+---
+
+## Anti-pattern 8：`Arc<Mutex<T>>` 到處傳
+
+### 不好
+
+```rust
+use std::sync::{Arc, Mutex};
+
+struct AppState {
+    users: Arc<Mutex<Vec<String>>>,
+    logs: Arc<Mutex<Vec<String>>>,
+    configs: Arc<Mutex<Vec<String>>>,
+}
+```
+
+問題：鎖太多、責任不清楚、容易死鎖、測試困難。
+
+### 好
+
+```rust
+struct UserService {
+    users: Vec<String>,
+}
+
+impl UserService {
+    fn create_user(&mut self, name: String) {
+        self.users.push(name);
+    }
+}
+```
+
+### 原則
+
+能單一 ownership 就不要共享。  
+需要跨 thread 再考慮 `Arc<Mutex<T>>`。
+
+---
+
+## Anti-pattern 9：在 async 中持有 lock 跨 `.await`
+
+### 不好
+
+```rust
+// 概念示意
+let mut guard = state.lock().await;
+do_async_work().await;
+guard.push(1);
+```
+
+問題：lock 持有時間太長，容易造成效能問題或 deadlock-like 行為。
+
+### 好
+
+```rust
+let data = {
+    let mut guard = state.lock().await;
+    guard.push(1);
+    guard.clone()
+};
+
+do_async_work(data).await;
+```
+
+### 原則
+
+鎖內只做最短、同步、必要的事情。
+
+---
+
+## Anti-pattern 10：濫用 `unsafe`
+
+### 不好
+
+```rust
+unsafe {
+    // 為了繞過 borrow checker 亂用 raw pointer
+}
+```
+
+### 好
+
+先問：
+
+1. 能不能用 ownership 改設計？
+2. 能不能用 `Rc` / `Arc`？
+3. 能不能用 `RefCell` / `Mutex`？
+4. 能不能拆資料結構？
+5. 真的需要 FFI、SIMD、底層記憶體操作嗎？
+
+### 原則
+
+`unsafe` 不是效能開關，是你接手編譯器無法保證的安全責任。
+
+---
+