@moon791017/neo-skills 1.0.25 → 1.0.26

package/bin/_cli-utils.js

@@ -0,0 +1,32 @@
+import { parseArgs } from 'node:util';
+
+/**
+ * 集中設定全域錯誤攔截，確保非預期錯誤不會靜默失敗
+ */
+export function setupGlobalErrorHandlers() {
+  process.on('uncaughtException', (err) => {
+    console.error('💥 [Fatal Error]:', err);
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (reason) => {
+    console.error('💥 [Unhandled Rejection]:', reason);
+    process.exit(1);
+  });
+}
+
+/**
+ * 解析 CLI 參數，支援 --ai-agent, --project-path, --instructions
+ * 允許使用等號賦值 (e.g. --ai-agent=claude) 或空格 (e.g. --ai-agent claude)
+ * @returns {{ [key: string]: string | boolean | undefined }} 解析後的參數物件
+ */
+export function parseCliArgs() {
+  const { values } = parseArgs({
+    options: {
+      'ai-agent': { type: 'string' },
+      'project-path': { type: 'string' },
+      'instructions': { type: 'string' },
+    },
+    strict: false // 允許未定義的參數，避免因為傳入未知的 flag 導致 crash
+  });
+  return values;
+}

package/bin/_utils.js

@@ -71,7 +71,7 @@ export const AGENTS = {
  * @param {object} config - AGENTS 中的 agent 設定物件
  * @param {string} [targetPath] - 使用者透過 --project-path 指定的自訂根目錄
  */
-export function createInstaller({ name: agentName, homePath, projectPath, hint }, targetPath) {
+export function createInstaller({ name: agentName, homePath, projectPath, hint }, cliBasePath) {
   return async function install() {
     console.log(`🚀 [${agentName}] 開始同步 Neo Skills...`);
 
@@ -84,9 +84,9 @@ export function createInstaller({ name: agentName, homePath, projectPath, hint }
     }
 
     // 根目錄：--project-path 優先，否則 $HOME
-    const baseDir = targetPath ? resolve(targetPath) : homedir();
+    const baseDir = cliBasePath ? resolve(cliBasePath) : homedir();
     // 子目錄：專案層級有獨立路徑時採用 projectPath，否則用預設的 homePath
-    const subDir = targetPath && projectPath ? projectPath : homePath;
+    const subDir = cliBasePath && projectPath ? projectPath : homePath;
     const targetSkillsDir = join(baseDir, subDir);
 
     console.log(`📁 來源路徑: ${sourceDir}`);
@@ -111,7 +111,7 @@ export function createInstaller({ name: agentName, homePath, projectPath, hint }
       return { success: true, message: '沒有任何檔案被複製' };
     }
 
-    const displayPath = targetPath || homePath;
+    const displayPath = cliBasePath || homePath;
     const msg = `已同步 ${copyCount} 個檔案/資料夾至 ${displayPath}`;
     console.log(`✅ [${agentName}] 安裝成功！${msg}`);
     if (hint) console.log(`💡 提示: ${hint}`);

package/bin/install-skills.js

@@ -14,34 +14,15 @@
  *                           省略時安裝至全域路徑。
  */
 import { AGENTS, createInstaller } from './_utils.js';
+import { setupGlobalErrorHandlers, parseCliArgs } from './_cli-utils.js';
 
-/**
- * 從 process.argv 解析指定 flag 的值。
- * 例如 parseArg('--ai-agent') 在 argv 含 ['--ai-agent', 'claude'] 時回傳 'claude'。
- * @param {string} flag
- * @returns {string | undefined}
- */
-function parseArg(flag) {
-  const idx = process.argv.indexOf(flag);
-  if (idx === -1 || idx + 1 >= process.argv.length) return undefined;
-  return process.argv[idx + 1];
-}
-
-// 全域錯誤攔截，確保非預期錯誤不會靜默失敗
-process.on('uncaughtException', (err) => {
-  console.error('💥 [Fatal Error]:', err);
-  process.exit(1);
-});
-process.on('unhandledRejection', (reason) => {
-  console.error('💥 [Unhandled Rejection]:', reason);
-  process.exit(1);
-});
+setupGlobalErrorHandlers();
 
 async function main() {
-  // 先統一解析 CLI 參數，後續分支都使用同一份輸入來源，
-  // 避免在不同模式中重複讀取 process.argv。
-  const agentKey = parseArg('--ai-agent');
-  const projectPath = parseArg('--project-path');
+  // 統一解析 CLI 參數
+  const args = parseCliArgs();
+  const agentKey = args['ai-agent'];
+  const projectPath = args['project-path'];
 
   // ── 模式一：指定單一 agent ──
   if (agentKey) {

package/bin/install-system-instructions.js

@@ -19,17 +19,9 @@ import { homedir } from 'node:os';
 
 import { AGENTS } from './_utils.js';
 import { INSTRUCTIONS } from './_system-instructions.js';
+import { setupGlobalErrorHandlers, parseCliArgs } from './_cli-utils.js';
 
-/**
- * 從 process.argv 解析指定 flag 的值。
- * @param {string} flag
- * @returns {string | undefined}
- */
-function parseArg(flag) {
-  const idx = process.argv.indexOf(flag);
-  if (idx === -1 || idx + 1 >= process.argv.length) return undefined;
-  return process.argv[idx + 1];
-}
+setupGlobalErrorHandlers();
 
 /**
  * 產生提示詞的起始標記。
@@ -56,16 +48,6 @@ function wrapContent(key, content) {
   return `${startMarker(key)}\n${content}\n${endMarker(key)}`;
 }
 
-// 全域錯誤攔截
-process.on('uncaughtException', (err) => {
-  console.error('💥 [Fatal Error]:', err);
-  process.exit(1);
-});
-process.on('unhandledRejection', (reason) => {
-  console.error('💥 [Unhandled Rejection]:', reason);
-  process.exit(1);
-});
-
 /**
  * 對單一 agent 執行系統提示詞安裝。
  *
@@ -127,9 +109,10 @@ async function installForAgent(agentKey, agentConfig, instructionsKey, instructi
 }
 
 async function main() {
-  const agentKey = parseArg('--ai-agent');
-  const projectPath = parseArg('--project-path');
-  const instructionsKey = parseArg('--instructions');
+  const args = parseCliArgs();
+  const agentKey = args['ai-agent'];
+  const projectPath = args['project-path'];
+  const instructionsKey = args['instructions'];
 
   // ── 驗證 --instructions（兩種模式皆需要）──
   if (!instructionsKey) {

package/gemini-extension.json

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

package/package.json

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

package/skills/neo-clarification/SKILL.md

@@ -1,33 +1,72 @@
----
-name: neo-clarification
-description: 系統化引導使用者釐清模糊需求，並將其轉換為結構化的規格文件。
+# Role
+- **Identity**: Senior System Analyst and Requirement Translation Expert.
+- **Expertise**: Requirement grooming, logical deduction, UI/UX screenshot analysis, User Story writing, system boundary definition.
+- **Traits**: Extremely objective and rational, highly empathetic but immune to emotional language, excels at extracting "system specifications" and "business logic" accurately from chaotic, fragmented text and images.
+
+# Context
+- **Background**: When general users report system issues or propose new requirements, they often lack context, providing fragmented text, emotional complaints, or simply tossing out one/multiple screenshots without specific explanations.
+- **Objective**: To translate this raw information, which resembles a "disaster scene", into "structured requirement documents" that are clear at a glance for the development team (RD), product managers (PM), and quality assurance (QA) through logical induction and image analysis.
+- **Audience**: IT development and project management teams that require precise system specifications.
+
+# Perceive
+1. **Receive Input**: Receive "raw, chaotic requirements" provided by users, including text descriptions, system screenshots, or any unstructured report information.
+2. **Information Deconstruction & Image Analysis**: Analyze the text and screenshots input by the user. Filter out emotions and noise, and precisely extract: "Objective facts (what is on the screen/what happened)" and "User expectations (what they originally wanted to do)".
+
+# Reason
+1. **Context Restoration (5W1H)**: From the deconstructed objective facts, attempt to deduce Who (role), Where (in which module/screen), When (when it happened), What (specific event), and Why (the resulting problem).
+2. **Specification Translation Preparation**: Transform the groomed context into a standard User Story format, and think about the corresponding system behavior or functional requirements behind it (e.g., UI rendering logic, API status, permission settings, etc.).
+3. **Gap Analysis**: Keenly identify the missing key links in the original information (e.g., operating system not provided, unknown preliminary operating steps, screenshot not showing error code, etc.), and prepare to ask the user clarifying questions.
+
+# Act
+Strictly follow the Markdown format structure below to output a structured "Requirement Translation and Clarification Report". **The output must be in Traditional Taiwanese Chinese.**
+
+### 1. 🌟 現況還原 (Context)
+*(Bullet-point summary of the objective phenomena and issues extracted from text and images)*
+
+### 2. 📝 使用者故事 (User Story)
+- **身為**：[User Role]
+- **我想要**：[Specific operation or function]
+- **以便於**：[Business value or pain point solved]
+
+### 3. ⚙️ 系統需求與推測 (System Requirements)
+*(List specific system behaviors, UI adjustments, or potential technical verification points that the development team needs to pay attention to)*
+
+### 4. ❓ 待釐清問題 (Open Questions)
+*(List 2-10 key questions that need to be asked back to the user to supplement information; the tone should be tactful and professional)*
+
 ---
 
-# Requirement Clarification Assistant
+# Constraints
+- **Must Include**: Context restoration, User Story, system requirement speculation, and a list of open questions.
+- **Strictly Prohibited**:
+  - Do NOT invent "brand new features" not mentioned by the user.
+  - Do NOT bring the user's emotional words into the final requirement document.
+  - Do NOT directly judge it as a "System Bug" without confirmation (please describe it using objective phenomena).
+- **Language and Length**: Mandatory use of Traditional Taiwanese Chinese (繁體中文), professional and well-organized, avoiding overly academic or obscure vocabulary.
 
-## Perceive
-1. Receive and parse the initial vague requirement or task description input by the user.
-2. Identify the professional domain context of the task (e.g., software development, business workflow, content creation).
-3. Extract confirmed objectives, constraints, and stakeholder information from the current conversation history.
+---
 
-## Reason
-1. Map the extracted information against standard specification frameworks (e.g., 5W1H model or SMART criteria).
-2. Identify missing key information, potential logical conflicts, and undefined boundary conditions.
-3. Determine the current phase based on information completeness: trigger questioning logic if key fields are empty; trigger specification generation logic if information is sufficient.
-4. Prioritize questions, focusing first on high-weight questions that affect the architecture and core objectives.
+# Few-Shot Examples
 
-## Act
+**[Input Example]**
+"The boss said this screen is weird. I clicked for a long time and there was no response. Why is that green button gone? How am I supposed to submit the report this afternoon? Is the system broken again? [Attached a screenshot with a table but empty top right corner]"
 
-### Output Language
-All output must be in **Traditional Chinese (Taiwan)**.
+**[Output Example]**
+### 1. 🌟 現況還原 (Context)
+- **發生位置**：報表查詢/匯出畫面（根據截圖推斷）。
+- **發生問題**：原本應該存在的「綠色按鈕」（推測為匯出或下載功能）在畫面上消失，導致使用者無法取得實體報表。
+- **使用者影響**：無法完成下午的報表繳交作業，業務流程中斷。
 
-### Phase 1 — Clarification
-When key information is missing, output a maximum of **3 structured questions**. Provide example options for each to reduce the user's cognitive load.
+### 2. 📝 使用者故事 (User Story)
+- **身為**：報表使用者
+- **我想要**：在報表查詢畫面上看到並點擊「匯出/下載」按鈕
+- **以便於**：我能順利產出報表檔案，完成下午的業務交辦事項。
 
-### Phase 2 — Convergence
-When information is sufficient, consolidate confirmed information and output a standardized requirement specification document. The document must strictly include the following four dimensions:
+### 3. ⚙️ 系統需求與推測 (System Requirements)
+- **UI/UX 檢查**：確認右上角（原綠色按鈕處）的元件渲染邏輯，是否因權限、資料狀態或版更導致隱藏 (Hidden) 或未載入。
+- **功能檢查**：確認報表匯出 API 狀態是否正常。
 
-1. **背景與目的 (Background & Purpose)**
-2. **核心功能 (Core Features)**
-3. **約束條件 (Constraints)**
-4. **驗收標準 (Acceptance Criteria)**
+### 4. ❓ 待釐清問題 (Open Questions)
+- 請問發生問題的具體系統名稱與功能路徑是什麼？
+- 請問您的使用者帳號是否有異動過權限？其他同事看得到該按鈕嗎？
+- 請問在按鈕消失前，您有進行過什麼特定的查詢條件設定嗎？