brand-research-toolkit 完整安裝教學

一頁讀完 Mac 與 Windows 的安裝、設定、第一次使用

2026-05-15 · Tony Wang · 約 7 分鐘

先選你的系統 ↓

TL;DR

七個 section 走完就能開始用 brand-research-toolkit。

環境前置 → 裝 plugin → GitHub Pages → publish 設定 → 第一次跑 → 路徑對照 → 常見問題。整頁可用上方按鈕切換 Mac / Windows 版指令，其他內容（GitHub 設定、使用方式）兩個系統都一樣。

看 GitHub Repo → 開發故事 →

0前置：環境準備（一次性）

安裝 Claude Code

開 Terminal（內建，不用裝），用 Homebrew：

Terminal# 沒裝 Homebrew 的話，先裝 brew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 再裝 Claude Code：
brew install claude-code

或從官方下載 .dmg：claude.com/claude-code

開 PowerShell（不需要 Admin），用 winget：

PowerShellwinget install Anthropic.ClaudeCode

或從官方下載 .exe：claude.com/claude-code

安裝 Git

Mac 通常已內建（隨 Xcode CLI Tools），輸入 git --version 確認。沒有的話：

Terminalxcode-select --install

會跳一個視窗讓你裝 Command Line Tools，按確定等幾分鐘。

PowerShellwinget install Git.Git

裝完重開 PowerShell，輸入 git --version 確認。

設定 git 身份

Terminalgit config --global user.name "你的名字"
git config --global user.email "your@email.com"

PowerShellgit config --global user.name "你的名字"
git config --global user.email "your@email.com"

1安裝 brand-research-toolkit

方法 A：用 Claude Code 內建指令（最簡單）

在 Claude Code 內輸入：

/plugin install tonyace126/brand-research-toolkit

重啟 Claude Code session 讓 skill 生效。

方法 B：手動 clone（如果 A 不行）

Terminal# 切到 plugin 目錄
cd ~/.claude/plugins

# clone repo
git clone https://github.com/tonyace126/brand-research-toolkit.git

# 重啟 Claude Code

PowerShell# 切到 plugin 目錄
cd "$env:USERPROFILE\.claude\plugins"

# clone repo
git clone https://github.com/tonyace126/brand-research-toolkit.git

# 重啟 Claude Code

2GitHub Pages 第一次設定

Step 1：在 github.com 建 repo

登入 GitHub → New repository → 名稱 my-shares → Public → 勾「Add a README file」 → Create

Step 2：啟用 GitHub Pages

repo Settings → Pages → Source: Deploy from a branch → main / (root) → Save

Step 3：Clone 到本機

Terminal# 切到家目錄
cd ~

# clone
git clone https://github.com/<你的帳號>/my-shares.git

本機路徑會是 /Users/你/my-shares/

PowerShell# 切到家目錄
cd $env:USERPROFILE

# clone
git clone https://github.com/<你的帳號>/my-shares.git

本機路徑會是 C:\Users\你\my-shares\

Step 4：設定 Git 認證（推薦 PAT）

github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate new token，勾 repo 權限，複製 token

在 Terminal：

Terminalgit config --global credential.helper osxkeychain

第一次 push 會跳 Keychain 視窗叫你輸入帳號密碼，密碼貼 PAT，之後自動記住在 macOS Keychain。

第一次 push 會跳 Git Credential Manager 視窗，密碼貼 PAT，之後自動記住。

如果跳的不是視窗而是命令列要求：

PowerShellgit config --global credential.helper manager

3設定 publish-research-html

第一次觸發這個 skill 時，Claude 會問你 5 題：

題目	怎麼答
GitHub Pages repo 本機路徑	`/Users/你/my-shares` `C:\Users\你\my-shares`
對外網址	`https://<你的帳號>.github.io/my-shares`
作者署名	你的名字 / 公司名
用自訂主題嗎？	y / n（新手選 n）
主題 CSS 檔名（若上題 y）	任意檔名，例 `my-theme.css`

設定檔位置（Mac）：~/.config/research-publisher.json。如果該目錄不存在，Claude 會自動建立。用任何文字編輯器（VSCode、Sublime、TextEdit）都能改。

設定檔位置（Windows）：C:\Users\你\.config\research-publisher.json。如果該目錄不存在，Claude 會自動建立。用記事本或 VSCode 可以直接打開編輯。

4第一次跑 e2e

試研究功能

重啟 Claude Code 後對它說：

研究永豐銀行近 7 天的 PTT + Dcard + 新聞輿情

預期看到：

Claude 自動觸發 brand-issue-research skill
並行 dispatch 多個 agent（速度比序列快 3-4 倍）
回傳整合表格 + 觀察小結
最後問你「要做成 HTML 電子報嗎？」

試發布功能

回答「好」，Claude 會：

第一次 → 跑 setup（5 題，見上一節）
之後 → 直接套範本、寫到你 my-shares 資料夾、問你要不要 push

5路徑對照表（Mac vs Windows）

不論你選哪個系統，這張表都可以收藏：

概念	Mac / Linux	Windows
家目錄	`~/` 或 `/Users/你/`	`C:\Users\你\` 或 `$env:USERPROFILE`
Claude plugins	`~/.claude/plugins/`	`C:\Users\你\.claude\plugins\`
設定檔	`~/.config/research-publisher.json`	`C:\Users\你\.config\research-publisher.json`
my-shares repo	`~/my-shares/`	`C:\Users\你\my-shares\`
Git 認證儲存	macOS Keychain	Windows Credential Manager
Shell	zsh（預設）/ bash	PowerShell
路徑分隔符	`/`	`\`（PowerShell 也接受 `/`）

6常見問題

共通問題（兩種系統都適用）：

Q：/plugin install 找不到

你的 Claude Code 版本可能還沒支援這個 slash 指令。改用方法 B（手動 clone）。

Q：路徑含中文 Claude 抓不到

強烈建議所有 git repo 路徑都用英文資料夾名。中文路徑在 git 環境很容易出問題。

Q：Claude Code 沒有自動讀到 plugin

確認你的 plugin 在這個位置：

~/.claude/plugins/brand-research-toolkit/
├── plugin.json
├── README.md
└── skills/
    ├── brand-issue-research/
    └── publish-research-html/

C:\Users\你\.claude\plugins\brand-research-toolkit\
├── plugin.json
├── README.md
└── skills\
    ├── brand-issue-research\
    └── publish-research-html\

完全重啟 Claude Code（不是 reload，是關掉重開）。

Q：HTML 開啟亂碼

範本已含 <meta charset="utf-8">，亂碼通常是檔案儲存編碼問題。用 VSCode 確認檔案是 UTF-8 編碼（不是 BIG5 / GB / UTF-8 BOM）。

🍎 Mac 專屬問題： 🪟 Windows 專屬問題：

Q：brew 指令找不到

Apple Silicon Mac 第一次裝完 brew 要把它加到 PATH。Terminal 跑：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Q：跳「無法驗證的開發者」警告

系統設定 → 隱私權與安全性 → 拉到下方「仍要打開」。或在 Terminal：

sudo xattr -dr com.apple.quarantine /Applications/Claude\ Code.app

Q：Terminal 找不到 git 但其實有裝

通常是新機沒跑過 xcode-select --install。或者你裝了 Apple Silicon 的 brew 但 PATH 沒設好（見第一題）。

Q：~/.config 目錄不存在

Mac 預設不會幫你建。手動建：

mkdir -p ~/.config

Q：PowerShell 跳「執行原則」錯誤

用 Admin 開 PowerShell 跑一次：

PowerShell AdminSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q：git push 跳 SSL 錯誤

PowerShellgit config --global http.sslBackend schannel

Q：找不到 .config\ 資料夾

Windows 預設不會幫你建 . 開頭的資料夾。手動建：

PowerShellmkdir "$env:USERPROFILE\.config"

Q：想用 Linux 環境？WSL2 替代方案

如果你不抗拒在 Windows 上用 Linux：

PowerShell Adminwsl --install

裝完後 Windows 裡會多一個 Ubuntu，所有 Mac 教學的 bash 指令都能直接用。但我會推薦 marketing 圈的人直接用 PowerShell 不要 WSL ── 學習曲線太抖、出問題不好 Google。

下一步

如果照著走還是卡關，到 GitHub repo 開 issue 給我：

github.com/tonyace126/brand-research-toolkit/issues

把以下資訊一併附上，比較好排除：

macOS 版本（Apple → 關於這台 Mac）、Terminal 預設 shell（zsh? bash?）
Windows 版本（11 / 10）、PowerShell 版本（$PSVersionTable）
Claude Code 版本
具體錯誤訊息截圖

跑通之後，記得回來看開發故事了解這個 toolkit 為什麼這樣設計。