貢獻指南

如何為 FlowPick 專案貢獻程式碼、文件或回報問題。

感謝你對 FlowPick 專案的關注。本文件將引導你如何參與專案貢獻，包括程式碼提交、文件改進和問題回報。

行為準則

參與本專案即表示你同意遵守以下基本原則：

使用友善和包容的語言
尊重不同的觀點和經驗
建設性地接受批評
關注對社群最有利的事情
對其他社群成員表現出同理心

貢獻方式

回報 Bug

如果你發現了 Bug，請透過 GitHub Issues 提交回報。一個好的 Bug 回報應包含：

標題：簡潔描述問題

描述：
- 預期行為是什麼？
- 實際發生了什麼？

重現步驟：
1. 開啟 '...'
2. 點擊 '...'
3. 捲動到 '...'
4. 觀察到錯誤

環境資訊：
- 作業系統：Windows 11 / macOS 14 / Ubuntu 24.04
- 瀏覽器：Chrome 125 / Edge 125
- FlowPick 版本：v1.0.0
- 擴充功能版本還是線上工具？

附加資訊：
- 主控台錯誤記錄
- 截圖或螢幕錄影
- 相關的串流媒體 URL（如果可公開存取）

提交 Bug 前，建議先在 Console 中執行診斷報告產生器，將輸出一併附上。同時請查閱已知問題確認是否為已記錄的已知限制。

功能請求

提交功能請求時，請說明：

你的使用場景是什麼？
這個功能解決什麼問題？
你期望的行為是什麼？
是否有替代方案？

在提交功能請求前，建議先了解 FlowPick 的技術架構和已知限制，確保你的需求在技術上是可行的。

改進文件

文件改進是最容易參與的貢獻方式：

找到需要改進的文件頁面
點擊頁面底部的「編輯此頁」連結（如果可用）
直接在 GitHub 上編輯並提交 Pull Request

或者：

Fork 儲存庫
在 content/ 目錄下找到對應的 Markdown 檔案
修改後提交 Pull Request

文件改進的常見方向：

方向	說明	參考
修正錯誤	技術描述不準確、設定範例有誤	對照專案架構驗證
補充細節	某個功能缺少使用說明或參數解釋	參考功能文件的風格
新增範例	缺少實際使用場景的程式碼或操作範例	參考使用場景的寫法
翻譯	將文件翻譯為其他語言	參考多語言章節
修復連結	交叉引用連結失效或指向錯誤	檢查 `::note` 區塊中的連結

貢獻程式碼

如果你想貢獻程式碼，請遵循以下流程。

開發環境建置

前置需求

工具	最低版本	說明
Node.js	18.x	建議使用 nvm 或 fnm 管理版本
pnpm	8.x	套件管理器
Git	2.x	版本控制

克隆與安裝

git clone https://github.com/ezwebtools/flowpick.git
cd flowpick-web
pnpm install

啟動開發伺服器

pnpm dev

開發伺服器預設執行在 http://localhost:3000。

如果你需要測試 FFmpeg WASM 多執行緒模式，請確保開發伺服器設定了正確的 COEP/COOP 回應標頭。詳見瀏覽器相容性 — 進階 API。

專案結構

flowpick-web/
├── app/                    # 應用程式原始碼
│   ├── assets/             # 靜態資源（CSS）
│   ├── components/         # Vue 元件
│   │   └── content/        # Nuxt Content 專用元件
│   ├── composables/        # 組合式函式
│   │   ├── useFFmpeg.ts    # FFmpeg WASM 整合
│   │   ├── useStreamMerge.ts # 串流合併與下載引擎
│   │   ├── useClarity.ts   # Microsoft Clarity 分析
│   │   └── useGA4.ts       # Google Analytics
│   ├── layouts/            # 版面配置元件
│   ├── pages/              # 頁面路由
│   │   ├── docs/           # 文件頁面
│   │   ├── changelog/      # 更新日誌頁面
│   │   ├── legal/          # 法律頁面
│   │   ├── m3u8-downloader.vue  # M3U8 下載器
│   │   ├── dash-downloader.vue  # DASH 下載器
│   │   └── index.vue       # 首頁
│   ├── types/              # TypeScript 型別宣告
│   ├── app.config.ts       # 應用程式設定
│   └── app.vue             # 根元件
├── content/                # Nuxt Content 文件
│   └── zh-Hans/            # 簡體中文文件
├── public/                 # 公共靜態資源
│   ├── ffmpeg/             # FFmpeg WASM 核心檔案
│   └── ffmpeg-mt/          # FFmpeg WASM 多執行緒核心檔案
├── nuxt.config.ts          # Nuxt 設定
├── package.json            # 專案依賴
└── tsconfig.json           # TypeScript 設定

關於各模組的詳細職責、資料流和設計決策，請參閱專案架構。關於下載引擎的完整技術實作，請參閱下載引擎架構。

技術棧

技術	用途
Nuxt 4	全端框架
Vue 3	UI 框架
Nuxt UI v4	元件庫
Nuxt Content v3	文件系統
Tailwind CSS v4	樣式
TypeScript	型別安全
@ffmpeg/ffmpeg	瀏覽器端媒體處理
m3u8-parser	HLS 清單解析
mpd-parser	DASH 清單解析
streamsaver	串流式檔案儲存

開發規範

程式碼風格

專案使用 ESLint 進行程式碼檢查：

pnpm lint

型別檢查

pnpm typecheck

提交前請確保型別檢查通過。

提交訊息規範

使用約定式提交（Conventional Commits）格式：

<type>(<scope>): <description>

[optional body]

[optional footer]

類型（type）：

類型	說明
`feat`	新功能
`fix`	Bug 修復
`docs`	文件更新
`style`	程式碼格式（不影響功能）
`refactor`	程式碼重構
`perf`	效能最佳化
`test`	測試相關
`chore`	構建/工具變更

範例：

feat(downloader): add concurrent segment download with configurable threads

Implemented a worker pool pattern for parallel segment downloading.
The concurrency level can be configured between 1-8 threads.

Closes #42

分支策略

main：穩定版本，隨時可部署
develop：開發分支
feat/xxx：功能分支
fix/xxx：修復分支
docs/xxx：文件分支

Pull Request 流程

Fork 儲存庫並建立功能分支
進行開發，確保程式碼通過 lint 和 typecheck
提交 PR 到 develop 分支
PR 描述中說明改動內容和原因
等待程式碼審查

PR 審查關注點：

關注點	說明
功能正確性	改動是否實現了預期功能，邊界情況是否處理
程式碼品質	是否遵循現有程式碼風格，是否有重複程式碼
效能影響	是否引入不必要的開銷，大檔案場景是否考慮
相容性	是否影響現有功能，瀏覽器相容性是否考慮
安全性	是否引入安全風險，使用者資料是否得到保護

關於下載引擎的效能考量（並行控制、記憶體管理、重試策略），請參閱下載引擎架構。關於瀏覽器相容性的注意事項，請參閱瀏覽器相容性。

文件編寫指南

文件結構

文件使用 Nuxt Content v3，以 Markdown 檔案形式存放在 content/zh-Hans/ 目錄下。

Frontmatter

每個文件檔案需要包含以下 frontmatter：

---
title: 文件標題
description: 文件描述（用於 SEO 和列表展示）
navigation:
  icon: i-lucide-xxx  # Lucide 圖示名稱
---

內容格式

使用 Markdown 標準語法
程式碼區塊指定語言以獲得語法突顯
表格用於對比和參考資訊
使用 ::tip、::note、::warning 等 Nuxt Content 指令

導覽設定

每個文件目錄需要一個 .navigation.yml 檔案：

title: 分類名稱
icon: i-lucide-xxx

多語言

目前文件以簡體中文（zh-Hans）為主。如果需要新增其他語言：

在 content/ 下建立對應語言目錄（如 en/）
複製文件結構並翻譯內容
保持檔案路徑和命名一致

測試

手動測試清單

提交涉及下載功能的 PR 前，請驗證以下場景：

小檔案下載（<10MB）
大檔案下載（>500MB）
加密 HLS 串流下載
DASH 串流下載
格式轉換（TS → MP4）
並行執行緒數切換
下載取消與重試
Chrome 瀏覽器
Edge 瀏覽器

各測試場景的驗證要點：

測試場景	驗證要點	參考文件
小檔案下載	下載完整性、速度顯示、進度條	下載引擎架構
大檔案下載	記憶體佔用、串流式寫入、無崩潰	下載引擎架構 — 記憶體安全管理
加密 HLS	AES-128 解密、金鑰取得	影片嗅探 — 加密串流
DASH 串流	音影片分離、FMP4 重組	下載引擎架構 — DASH 串流的特殊處理
格式轉換	FFmpeg 載入、轉封裝正確性	格式轉換 — FFmpeg WASM 引擎
並行切換	執行緒數變化、速度對比	設定參考
取消與重試	AbortController、重試次數	下載引擎架構 — 重試機制
瀏覽器相容	Chrome/Edge 功能一致性	瀏覽器相容性

測試用串流媒體 URL

以下是一些可用於測試的公開串流：

# 基礎 HLS（無加密）
https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8

# 多畫質 HLS
https://test-streams.mux.dev/pts_shift/pts_shift.m3u8

# 基礎 DASH
https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd

關於 HLS 和 DASH 串流的偵測原理和清單結構，請參閱影片嗅探。關於線上工具中如何使用這些測試 URL，請參閱線上工具。

發布流程

在 develop 分支完成開發和測試
更新 content/zh-Hans/4.changelog/ 中的更新日誌
合併 develop 到 main
建立版本標籤（如 v1.1.0）
構建擴充功能套件並提交到 Chrome Web Store