@moon791017/neo-skills 1.0.33 → 1.0.35

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.59.0",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.33",
+  "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

@@ -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,354 @@
+# 3. Anti-patterns
+
+---
+
+## Anti-pattern 1: Using `.clone()` everywhere to avoid the borrow checker
+
+### Bad
+
+```rust
+fn process(name: String) {
+    println!("{name}");
+}
+
+fn main() {
+    let name = String::from("Alice");
+
+    process(name.clone());
+    process(name.clone());
+    process(name.clone());
+}
+```
+
+### Good
+
+```rust
+fn process(name: &str) {
+    println!("{name}");
+}
+
+fn main() {
+    let name = String::from("Alice");
+
+    process(&name);
+    process(&name);
+    process(&name);
+}
+```
+
+### Principle
+
+`.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: Excessive use of `String`
+
+### Bad
+
+```rust
+fn is_admin(role: String) -> bool {
+    role == "admin"
+}
+```
+
+### Good
+
+```rust
+fn is_admin(role: &str) -> bool {
+    role == "admin"
+}
+```
+
+### Principle
+
+Use `String` when you need ownership; prefer `&str` for reading text.
+
+---
+
+## Anti-pattern 3: Using `bool` to represent complex states
+
+### Bad
+
+```rust
+struct User {
+    is_active: bool,
+    is_deleted: bool,
+    is_locked: bool,
+}
+```
+
+Problem: Contradictory states can occur, such as being both `active` and `deleted`.
+
+### Good
+
+```rust
+enum UserStatus {
+    Active,
+    Deleted,
+    Locked,
+}
+
+struct User {
+    status: UserStatus,
+}
+```
+
+---
+
+## Anti-pattern 4: Using `String` for errors
+
+### Bad
+
+```rust
+fn parse_age(input: &str) -> Result<u8, String> {
+    input.parse::<u8>().map_err(|_| "invalid age".to_string())
+}
+```
+
+Acceptable for short scripts, but not recommended for libraries or large systems.
+
+### Good
+
+```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)
+}
+```
+
+### Principle
+
+Errors should be categorizable, testable, and handleable.
+
+---
+
+## Anti-pattern 5: Random `panic!` inside a library
+
+### Bad
+
+```rust
+pub fn divide(a: i32, b: i32) -> i32 {
+    if b == 0 {
+        panic!("divide by zero");
+    }
+
+    a / b
+}
+```
+
+### Good
+
+```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)
+}
+```
+
+### Principle
+
+Return `Result` unless it is an unrecoverable programming error.
+
+---
+
+## Anti-pattern 6: Over-abstraction with Traits
+
+### Bad
+
+```rust
+trait UserNameProvider {
+    fn user_name(&self) -> &str;
+}
+
+struct User {
+    name: String,
+}
+
+impl UserNameProvider for User {
+    fn user_name(&self) -> &str {
+        &self.name
+    }
+}
+```
+
+Problem: When there's only one struct, one method, and no need for substitution, a trait is just noise.
+
+### Good
+
+```rust
+struct User {
+    name: String,
+}
+
+impl User {
+    fn name(&self) -> &str {
+        &self.name
+    }
+}
+```
+
+### Principle
+
+Use concrete types first. Abstract into traits only when actually needed.
+
+---
+
+## Anti-pattern 7: Public fields breaking invariants
+
+### Bad
+
+```rust
+pub struct Account {
+    pub balance: i64,
+}
+
+fn main() {
+    let mut account = Account { balance: 100 };
+    account.balance = -999;
+}
+```
+
+### Good
+
+```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: Passing `Arc<Mutex<T>>` everywhere
+
+### Bad
+
+```rust
+use std::sync::{Arc, Mutex};
+
+struct AppState {
+    users: Arc<Mutex<Vec<String>>>,
+    logs: Arc<Mutex<Vec<String>>>,
+    configs: Arc<Mutex<Vec<String>>>,
+}
+```
+
+Problem: Too many locks, unclear responsibilities, prone to deadlocks, and difficult to test.
+
+### Good
+
+```rust
+struct UserService {
+    users: Vec<String>,
+}
+
+impl UserService {
+    fn create_user(&mut self, name: String) {
+        self.users.push(name);
+    }
+}
+```
+
+### Principle
+
+Prefer single ownership over shared state. Consider `Arc<Mutex<T>>` only when cross-thread access is required.
+
+---
+
+## 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);
+```
+
+Problem: Holding a lock for too long can cause performance issues or deadlock-like behavior.
+
+### Good
+
+```rust
+let data = {
+    let mut guard = state.lock().await;
+    guard.push(1);
+    guard.clone()
+};
+
+do_async_work(data).await;
+```
+
+### Principle
+
+Keep the code inside a lock as short, synchronous, and necessary as possible.
+
+---
+
+## Anti-pattern 10: Abuse of `unsafe`
+
+### Bad
+
+```rust
+unsafe {
+    // Using raw pointers haphazardly to bypass the borrow checker
+}
+```
+
+### Good
+
+Ask yourself first:
+
+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?
+
+### Principle
+
+`unsafe` is not a performance switch; it is taking over the safety responsibilities that the compiler can no longer guarantee.