# WorkBuddy 安裝指南 — ChatCut

Source: [WorkBuddy 安裝指南 — ChatCut](<https://pr-535-preview.chatcut.dev/zh-hant/workbuddy>)

Content index: [llms.txt](<https://pr-535-preview.chatcut.dev/zh-hant/llms.txt>)

## WorkBuddy 安裝指南

本指南協助你在 **WorkBuddy** 中安裝 ChatCut MCP 服務，並連線到 ChatCut 雲端進行影片剪輯。

本安裝方式使用遠端 MCP 的靜態 `Authorization: Bearer` 請求標頭。先依照下方的 OAuth 2.0 流程取得權杖，再將它填入 WorkBuddy 的 MCP 設定。

開始前，請確認終端機能找到 `curl` 和 `python3`。下方的多行 `curl` 範例採用 Bash 接續行語法；Windows 可在 WSL 中執行。如果使用 PowerShell，請使用 `curl.exe`，並依照目前終端機的語法調整接續行與引號，參見 [Windows curl 說明](https://learn.microsoft.com/windows/curl/)。

## 準備工作

先確認下列兩條命令可以正常執行：

```text
curl --version
python3 --version
```

`curl` 和 `python3` 必須位於 `PATH` 中。後面的用戶端註冊、權杖交換與 MCP 驗證步驟都會用到它們。

## 安裝

如果你是為使用者讀取本指南的 WorkBuddy Agent，請在使用者已要求安裝 ChatCut 時，依序執行安裝步驟，並驗證結果。

本安裝流程使用手動 OAuth 2.0 授權，WorkBuddy 的本機回呼連接埠為 **52961**。

### 1\. 註冊 OAuth 用戶端

透過動態用戶端註冊介面建立自己的 OAuth 用戶端。傳回的 `client_id` 對應 WorkBuddy 的回呼連接埠：

```bash
curl -s -X POST "https://api.chatcut.io/auth/mcp/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "workbuddy",
    "redirect_uris": ["http://127.0.0.1:52961/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email offline_access"
  }'
```

儲存回應中的 `client_id`，並在後續命令中用它取代 `<CLIENT_ID>`。

### 2\. 產生 PKCE 參數

```bash
python3 -c "
import secrets, hashlib, base64
verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode()
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b'=').decode()
print(f'VERIFIER={verifier}')
print(f'CHALLENGE={challenge}')
"
```

儲存 `VERIFIER` 和 `CHALLENGE`，後面會用到這兩個值。

### 3\. 完成授權

取代下方命令中的 `<CLIENT_ID>` 和 `<CHALLENGE>` 後執行。它會自動開啟瀏覽器中的授權頁面，並在本機連接埠 52961 接收授權碼：

```bash
python3 -c "
import http.server, socketserver, urllib.parse, webbrowser
URL = 'https://api.chatcut.io/auth/mcp/authorize?response_type=code&client_id=<CLIENT_ID>&code_challenge=<CHALLENGE>&code_challenge_method=S256&redirect_uri=http://127.0.0.1:52961/callback&scope=openid+profile+email+offline_access&state=chatcut'
captured = {}
class H(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
        if 'code' in q:
            captured['code'] = q['code'][0]
            self.send_response(200); self.end_headers()
            self.wfile.write(b'ChatCut authorized - you can close this tab.')
    def log_message(*a): pass
with socketserver.TCPServer(('127.0.0.1', 52961), H) as s:
    s.timeout = 1
    webbrowser.open(URL)
    print('Opened the authorization page. Log in and click Allow ChatCut...')
    for _ in range(180):
        s.handle_request()
        if 'code' in captured: break
print('CODE=' + captured.get('code', '(timed out - copy the URL above and open it manually)'))
"
```

在開啟的 ChatCut 頁面中登入並點擊 **Allow ChatCut**。授權成功後，終端機會輸出 `CODE=...`。如果瀏覽器未自動開啟，請複製命令中的 `URL` 並手動開啟。

### 4\. 換取存取權杖

```bash
curl -s -X POST "https://api.chatcut.io/auth/mcp/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "redirect_uri=http://127.0.0.1:52961/callback" \
  -d "client_id=<CLIENT_ID>" \
  -d "code_verifier=<VERIFIER>"
```

回應包含 `access_token`、`refresh_token` 和 `expires_in`。存取權杖通常約 1 小時後到期，實際時間以 `expires_in` 為準。

先完成下方的設定與驗證，再重新啟動 WorkBuddy。

## 設定

將 ChatCut MCP 服務加入 WorkBuddy 的設定檔：

```text
~/.workbuddy/mcp.json
```

> 檔案名稱必須是 **`mcp.json`，開頭沒有點**。不要寫成 `~/.workbuddy/.mcp.json`。WorkBuddy 讀取的是 `~/.workbuddy/mcp.json`；路徑錯誤會導致服務無法顯示。

新增類型為 **HTTP** 的 `chatcut` 服務，用取得的存取權杖取代 `<access_token>`。如果檔案已有 `mcpServers` 物件，請將這一項合併進去，保留既有服務：

```json
{
  "mcpServers": {
    "chatcut": {
      "type": "http",
      "url": "https://api.chatcut.io/api/external-mcp/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

儲存檔案，然後重新啟動 WorkBuddy 或開啟新會話，讓它載入新設定。

## 驗證連線

執行下列命令，檢查 MCP 服務是否正常回應：

```bash
curl -s -X POST "https://api.chatcut.io/api/external-mcp/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"workbuddy","version":"1.0.0"}}}'
```

初始化成功後，回應會包含伺服器的功能資訊。

再開啟一段新的 WorkBuddy 對話，確認工具清單中出現 ChatCut。目前會話無法載入剛設定的 MCP 工具。

如果服務已出現，但請求傳回 **Unauthorized**，存取權杖可能已到期。用下列命令更新權杖：

```bash
curl -s -X POST "https://api.chatcut.io/auth/mcp/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<REFRESH_TOKEN>" \
  -d "client_id=<CLIENT_ID>"
```

用新的 `access_token` 更新 WorkBuddy MCP 設定中的 `Authorization` 請求標頭。如果更新權杖也已到期，請從第 2 步重新完成授權流程。

## 開始剪輯

安裝、登入與驗證完成後，將下方的提示詞貼到一段新的 WorkBuddy 對話中：

```text
ChatCut 外掛已經安裝好了，請你用內建瀏覽器開啟一個 ChatCut 專案，把專案名稱命名為「我的第一個 ChatCut 影片」，然後先告訴我你整體可以做什麼，尤其是這三部分：影片剪輯（語音清理、字幕、轉場、補充素材等）、MG 動畫製作、素材生成（影片、旁白、音樂、音效等）。之後問我有什麼素材、想做什麼樣的影片，告訴我你可以根據我的具體需求一步步開始製作，並且我也可以隨時進入 ChatCut 編輯介面自行調整時間軸、字幕、MG 動畫等任何內容，就像使用傳統編輯器一樣。
```

如果使用者實際使用其他對話語言，請將啟動提示詞翻譯成該語言。依照實際對話語言判斷，不要根據作業系統語言判斷，也不需要再讓使用者選擇。

## ChatCut 剪輯工作流程

ChatCut 透過 MCP 連線提供口播剪輯、MG 動畫，以及圖片、影片、配音與音樂生成等工作流程。執行較複雜的剪輯或生成任務前，讓 Agent 呼叫 `list_skills` 查看目錄，再用 `load_skill({ name })` 載入並遵循對應工作流程。工作流程會隨 ChatCut 後端部署更新，無需額外安裝。

## 更新設定

以後需要更換 MCP 服務位址或權杖時，編輯 WorkBuddy MCP 設定中的 ChatCut 設定。權杖到期時，使用[驗證連線](https://pr-535-preview.chatcut.dev/zh-hant/workbuddy#verify)中的更新命令。