# WorkBuddy 安装指南 — ChatCut

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

Content index: [llms.txt](<https://pr-523-preview.chatcut.dev/zh/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-523-preview.chatcut.dev/zh/workbuddy#verify)中的刷新命令。