Postar 開發指南

📦 專案概述

Postar 是一個基於 WXT 框架建構的瀏覽器擴展專案，使用現代前端技術棧（Vue 3 + TypeScript）。支援宣告式開發和即時熱重載。Postar 專注於國際媒體平臺的內容同步和分發，採用外掛化架構實現平臺可擴展性。

🛠️ 開發環境要求

前提條件

• Node.js
• 套件管理器：pnpm（推薦）

可選工具

• Git 版本控制
• Chrome 瀏覽器（最新版本）

🔧 開發流程

1. 安裝依賴

   pnpm i

2. 啟動開發伺服器

   pnpm dev  # WXT 開發模式，支援即時重載和 HMR

3. 載入擴展
   • 導航到 chrome://extensions
   • 啟用開發者模式
   • 點擊載入已解壓的擴展程式
   • 選擇 .output/chrome-mv3-dev 目錄

🚀 建置與發布

• 生產建置：

  pnpm build

• 生成發布包（ZIP 格式）：

  pnpm zip

🛠️ 開發指南

Background Script

• 管理擴展生命週期（安裝/更新/解除安裝）
• 監聽瀏覽器事件（分頁更新、歷史記錄變更等）
• 無 DOM 存取（無法直接存取網頁 DOM；必須使用 content scripts 作為代理）
• 非持久化執行（在 Manifest V3 中，按需喚醒並在事件處理後休眠）
• 透過 chrome.runtime.sendMessage 接收來自 content scripts/popups 的訊息
• 透過 chrome.tabs.sendMessage 向特定分頁發送命令

Content Script

• 可以直接存取頁面 DOM，但無法呼叫大多數 Chrome API
• 透過 chrome.runtime.sendMessage 與背景通訊
• 支援智慧網頁內容擷取（Readability 解析）
• 支援文字選擇同步和圖片偵測

Sidepanel

• 支援 Vue.js 元件開發，擁有完整的 Chrome API 存取權限
• 使用 chrome.storage 進行資料持久化

外掛系統

• 基於外掛引擎（@gitcoffee/postbot-plugin-engine）實現平臺可擴展性
• 預設包含國際平臺發布外掛（@gitcoffee/postbot-publisher-en）
• 支援自訂平臺註冊和元資料管理

📁 專案結構

src/
├── api/              # API 介面和設定
├── assets/           # 靜態資源（圖示等）
├── background/       # 背景指令碼
├── config/           # 設定檔案
├── content/          # 內容指令碼（浮動按鈕、彈窗）
├── entrypoints/      # WXT 入口點
│   ├── background.ts
│   ├── content.ts
│   └── sidepanel/    # 側邊欄
├── events/           # 事件處理（右鍵選單等）
├── locales/          # 國際化（en/zh）
├── media/            # 媒體處理
│   ├── adapter/      # 媒體適配器
│   ├── handler/      # 媒體處理器
│   ├── meta/         # 平臺元資料
│   ├── parser/       # 內容解析器
│   ├── processor/    # 媒體處理器
│   └── publisher/    # 發布器
├── message/          # 訊息通訊
├── plugins/          # 外掛系統
├── stores/           # 狀態管理（Pinia）
└── styles/           # 全域樣式

❓ 常見問題

• 熱重載不工作：嘗試重新整理擴展頁面或重啟開發伺服器。
• 類型錯誤：檢查 tsconfig.json 設定並確保所有依賴已安裝。

🙌 參與貢獻

歡迎透過 Pull Request 貢獻程式碼。請確保：

• 程式碼風格與專案一致
• 現有測試案例透過
• 相關文件已更新

貢獻指南