GeezerVison

核心架構 (System Architecture)

🎯 Gateway-Client 模式 (Gateway-Client Pattern)

┌─ Gateway Layer ─────────────────┐
│  Service Worker                 │
│  - 調用 Gemini API              │
│  - AI 推理與決策                 │
│  - 解析 JSON 指令                │
│  - 路由到 Client                 │
└─────────────────────────────────┘
              ↓
┌─ Client Layer ──────────────────┐
│  SidePanel                      │
│  - 動態加載技能模組              │
│  - 執行業務邏輯                  │
│  - 調用 Chrome APIs              │
│  - 與用戶界面交互                │
└─────────────────────────────────┘

🎯 設計哲學：大腦-手腳分離模式

用戶指令 (SidePanel UI)
        ↓
  Service Worker (消息路由層)
  - 接收訊息
  - 呼叫 Gemini 2.0 Flash API
  - 解析 AI 回應
  - 轉發到 SidePanel
        ↓
   SidePanel (執行引擎)
  - 動態載入技能模組
  - 執行技能邏輯
  - 返回結果
        ↓
  Chrome APIs / DOM 操作

完整操作流程 (Operational Flow)

階段 A：初始化 (Startup)

階段 B：指令接收、AI 推理與路由 (Input, Reasoning & Routing)

SidePanel (用戶說話)
    ↓
Service Worker 收到訊息
    ↓
[Gateway Phase - 大腦思考和決策]
- 提取用戶的自然語言輸入
- 組合 System Prompt + User Prompt
- 發送到 Gemini 2.0 Flash API
    ↓
Gemini 回應 (JSON)
{
  "skill": "open_tab",
  "url": "https://www.google.com"
}
    ↓
Service Worker 解析 JSON，查詢技能清單
    ↓
檢索 runInPageContext 標誌
{
  skill: "open_tab",
  runInPageContext: false
}
    ↓
轉發給 SidePanel（包含執行環境指示）
{
  skill: "open_tab",
  runInPageContext: false,
  args: { url: "https://www.google.com" }
}

階段 C：動態加載與執行 (Execution)

// service-worker.js
chrome.runtime.sendMessage({
    target: 'SIDE_PANEL',
    type: 'EXECUTE_SKILL',
    skill: 'open_tab',
    skillFolder: 'open_tab',
    args: { url: 'https://www.google.com' }
});

// sidepanel.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    if (message.target === 'SIDE_PANEL' && message.type === 'EXECUTE_SKILL') {
        (async () => {
            try {
                // ✨ 核心：動態 import（只有在 SidePanel 才被允許）
                const module = await import(
                    `./skills/${message.skillFolder}/${message.skill}.js`
                );
                
                // 執行技能函數
                const skillFunc = module[message.skill];
                const result = await skillFunc(message.args);
                
                sendResponse({ status: "success", result });
            } catch (error) {
                sendResponse({ status: "error", error: error.message });
            }
        })();
        
        return true; // ✨ 保持消息通道開啟
    }
});

// skills/open_tab/open_tab.js
export async function open_tab(args) {
    const url = args.url.startsWith('http') 
        ? args.url 
        : `https://${args.url}.com`;
    
    const tab = await chrome.tabs.create({ url });
    return `✅ 成功開啟分頁：${url}`;
}

技能系統規範 (Skill System Spec)

檔案結構

skills/
├── open_tab/
│   ├── open_tab.md          # AI 用的介面定義
│   └── open_tab.js          # 實作檔（標準 ES Module）
├── summarize/
│   ├── summarize_page.md
│   └── summarize_page.js
└── ...

1. 介面定義 (.md 檔案)

# open_tab

打開新分頁的技能。

## 參數
- url: (string) 要開啟的網址

## 返回
成功訊息字串

2. 實作檔 (.js 檔案)

// skills/opentab/open_tab.js
export async function open_tab(args) {
    // args 包含所有 AI 決定的參數
    // 例如: { url: "https://www.google.com" }
    
    try {
        // 執行邏輯
        const tab = await chrome.tabs.create({ url: args.url });
        
        // 返回執行結果訊息
        return `✅ 成功開啟分頁：${args.url}`;
    } catch (error) {
        throw new Error(`開啟分頁失敗：${error.message}`);
    }
}

3. 技能清單 (skills-manifest.json)

{
  "skills": [
    {
      "name": "open_tab",
      "folder": "open_tab",
      "description": "打開新標籤頁",
      "runInPageContext": false
    },
    {
      "name": "summarize_this_page",
      "folder": "summarize_this_page",
      "description": "分析並總結當前頁面",
      "runInPageContext": false
    },
    {
      "name": "close_this_page",
      "folder": "close_this_page",
      "description": "關閉當前標籤頁",
      "runInPageContext": false
    },
    {
      "name": "who_are_you",
      "folder": "who_are_you",
      "description": "介紹 Jarvis 助手功能",
      "runInPageContext": false
    }
  ]
}

📚 當前支持的技能 (Supported Skills)

1. open_tab - 打開新標籤頁

2. summarize_this_page - 分析並總結頁面

3. close_this_page - 關閉當前標籤頁

4. who_are_you - 介紹助手

關鍵技術細節 (Technical Deep Dive)

為什麼 SidePanel 是完美的執行引擎？

非同步通訊的正確模式

// ❌ 錯誤（會導致消息通道關閉）
chrome.runtime.onMessage.addListener(async (message, sender, sendResponse) => {
    const result = await doSomethingAsync();
    sendResponse(result); // 通道已關閉！
});

// ✅ 正確（保持通道開啟）
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    (async () => {
        const result = await doSomethingAsync();
        sendResponse(result); // 通道仍然開啟
    })();
    return true; // 必須返回 true！
});

消息流協議 (Message Protocol)

Service Worker → SidePanel

{
    target: 'SIDE_PANEL',           // 目標模組
    type: 'EXECUTE_SKILL',          // 操作類型
    skill: 'open_tab',              // 技能名稱
    skillFolder: 'open_tab',        // 技能資料夾
    args: {                         // AI 決定的參數
        url: 'https://www.google.com'
    }
}

SidePanel → Service Worker (回應)

{
    status: 'success',
    result: '✅ 成功開啟分頁：https://www.google.com'
}

{
    status: 'error',
    error: '開啟分頁失敗：Invalid URL'
}

⚙️ 配置說明 (Configuration)

模型選擇

語言設置

通知設置

🌐 國際化支持 (i18n)

📖 開發指南 (Development Guide)

🚀 快速建立新技能 (Quick Skill Creation)

📄 参考 SKILL_DEVELOPMENT.md
📁 创建 skills/skill_name/ 文件夹
📝 写 .md 定义和 .js 实现
✨ 完成！Pre-commit hook 自动注册

添加新技能的完整步驟

第 1 步：建立檔案結構

skills/
├── myskill/
│   ├── myskill.md          # AI 用的介面定義
│   └── myskill.js          # 技能實現代碼
└── ...

第 2 步：編寫 .md 介面文件

name: myskill

description: 技能的簡短描述

when_to_use:
  MUST HAVE BOTH:
  1. **ACTION VERB** (必須有動詞):
     English: "verb1", "verb2"
     Chinese: "動詞1", "動詞2"
  
  2. **CONTEXT/OBJECT** (必須有對象):
     "context1", "context2"

examples_CORRECT:
  - "example 1" ✓
  - "example 2" ✓

examples_INCORRECT:
  - "bad example 1" ✗

when_NOT_to_use:
  - 不應使用的情況

input: 輸入格式說明

output:
JSON 格式輸出說明和範例

IMPORTANT:
- 重要提示和限制

第 3 步：編寫 .js 實現文件

// skills/myskill/myskill.js
// ✅ 正確的模板

export async function myskill(args) {
    console.log("[MySkill] 啟動，接收到參數:", args);

    try {
        // 驗證必要參數
        if (!args.requiredParam) {
            throw new Error("未提供必要參數: requiredParam");
        }

        console.log("[MySkill] 執行業務邏輯...");
        
        // 業務邏輯
        const result = await someAsyncOperation(args.requiredParam);
        
        console.log("[MySkill] 執行成功");
        return `✅ 操作成功：${result}`;
        
    } catch (error) {
        console.error("[MySkill] 錯誤:", error);
        throw new Error(`操作失敗：${error.message}`);
    }
}

第 4 步：註冊技能到清單

{
  "skills": [
    {
      "name": "myskill",
      "folder": "myskill",
      "description": "技能的簡短描述",
      "runInPageContext": false
    }
  ]
}

第 5 步：測試

第 6 步：完成！

技能編寫最佳實踐

🐛 調試方法 (Debugging)

查看 Service Worker (Gateway) 日誌

[Gateway] 🚀 Service Worker 已加載
[Gateway] 啟動動態技能加載器...
[Gateway] 讀取技能清單: chrome-extension://...
[Gateway] 發現技能: open_tab, summarize_this_page, who_are_you, close_this_page
[Gateway] ✅ 技能 [open_tab] 已加載
[Gateway] 可用技能:(4) ['open_tab', 'summarize_this_page', 'who_are_you', 'close_this_page']

查看 SidePanel 日誌

[SidePanel] 收到訊息: ask_ai
[SidePanel] 用戶輸入: open Google
[SidePanel] 發送的訊息: {action: "ask_ai", prompt: "open Google", config: {...}}
[SidePanel] 收到回應: {status: "success", text: "..."}
[SidePanel] 執行技能: open_tab
[SidePanel] 技能執行成功: ✅ 成功開啟分頁：https://google.com

查看特定技能的日誌

[Gateway] - Service Worker 層
[SidePanel] - SidePanel 主線程
[Open Tab Skill] - open_tab 技能
[Summary Page Skill] - summarize_this_page 技能
[Close Page Skill] - close_this_page 技能
[Who Are You Skill] - who_are_you 技能

常見問題排查

問題：技能未被註冊

問題：技能執行失敗

問題：AI 沒有調用正確的技能

📊 項目狀態 (Project Status)

核心功能 ✅

已實現的技能 ✅

國際化 (i18n) ✅

用戶設置 ✅

開發工具 ✅

文檔 ✅

🚀 快速開始 (Quick Start)

1. 安裝擴展

2. 配置 API

3. 開始使用

💻 開發環境設置 (Development Environment)

必要工具

第 1 步：克隆並設置項目

# 克隆項目
git clone https://github.com/jaylooloomi/chrome-jarvis.git
cd chrome-jarvis

# 安裝依賴並設置 Git hooks
npm install

第 2 步：了解項目結構

chrome-jarvis/
├── package.json              # npm 配置和腳本
├── scripts/
│   └── generate-manifest.js  # 自動生成技能清單
├── .husky/
│   └── pre-commit            # Git 提交前自動運行
├── skills/
│   ├── skills-manifest.json  # 自動生成（勿手動編輯）
│   ├── open_tab/
│   ├── summarize_this_page/
│   ├── close_this_page/
│   └── who_are_you/
├── service-worker.js
├── sidepanel.js
└── README.md

第 3 步：在 Chrome 中加載項目

📦 npm 腳本 (npm Scripts)

生成技能清單

# 手動生成 skills-manifest.json
npm run generate-manifest

查看所有可用腳本

npm run

🔄 開發工作流程 (Development Workflow)

自動清單生成 (Auto-Manifest Generation)

常見場景

添加新技能

修改現有技能

# 編輯文件
vim skills/open_tab/open_tab.md
vim skills/open_tab/open_tab.js

# 測試（在 Chrome 中）
# 1. 打開 chrome://extensions/
# 2. 點擊 OmniAssistant 旁的"刷新"

# 提交（manifest 自動更新）
git add skills/open_tab/
git commit -m "fix: improve open_tab skill"
git push

調試技能

Git 工作流程

# 創建功能分支
git checkout -b feat/new-feature

# 進行開發
# ...編輯文件...

# 提交（manifest 自動更新）
git add .
git commit -m "feat: add new feature"
# Pre-commit hook 自動運行：
# - npm run generate-manifest
# - 更新 skills-manifest.json
# - 添加到提交

# 推送
git push origin feat/new-feature

# 創建 Pull Request
# ...在 GitHub 上操作...

🛠️ npm 與 Husky 故障排除

問題：manifest 沒有自動更新

# 手動運行生成腳本
npm run generate-manifest

# 查看輸出確認技能是否被正確發現

問題：Git hook 未運行

# 確保 husky 已正確安裝
npm install

# 檢查 git hook 是否存在
ls -la .git/hooks/pre-commit

# 如果不存在，手動安裝
npx husky install

問題：npm install 失敗

npm ERR! Cannot find module 'husky'

# 清除 npm 緩存
npm cache clean --force

# 重新安裝
rm -rf node_modules package-lock.json
npm install

問題：Windows 上 pre-commit hook 不工作

# 設置 Git 忽略行終止符差異
git config core.safecrlf false

# 重新安裝 husky
npx husky install

📚 進階主題 (Advanced Topics)

如何貢獻新技能

如何自定義 AI 模型

如何添加新語言

更多關於 Husky

📜 許可證 (License)

✅ 你可以：

❌ 你不能：

💼 商業使用或其他許可需求