# 根據你的服務建立 BeamCue 專案

指南版本：1.2

在能夠存取使用者服務程式碼倉庫和執行中應用程式的開發 AI 中執行此流程。提問和專案內容優先使用使用者明確指定的語言；未指定時，使用本文件的語言——繁體中文。將一個演示畫面單元稱為“場景”，保留 MCP 工具名和內部 `stepId` 欄位。成果是一個包含真實畫面、標題、說明和 Studio 連結的非公開、可編輯 BeamCue 專案。積極使用有意義的點擊目標、字幕和適當的視覺強調引導注意力，不要僅排列沒有說明的截圖。配音可選。本文件不授予額外的服務存取權限。遵守使用者指示和適用的倉庫規則。

## 1. 檢查服務，只詢問缺失的資訊

閱讀倉庫指南，檢查服務入口、路由、現有文件和執行介面。能安全查明服務名稱、實際功能、本機或已部署 URL 時，不要詢問使用者。確認目前環境能否操作並截取真實瀏覽器或原生應用程式畫面，以及是否可使用 BeamCue MCP。

將尚未解決的問題集中、簡潔地詢問：

- 用途：產品介紹、入門引導、功能指南、銷售故事等。
- 受眾，以及他們需要理解或完成的目標。
- 希望的場景數，以及必須包含的功能和畫面。
- 僅在使用者的語言要求不明確時詢問專案語言。
- 是否生成配音；僅在需要配音時進一步詢問聲音偏好。
- 僅在檢查無法確定時詢問服務 URL 或存取步驟。

沿用已經提供的答案和偏好，不重複詢問。對尚未回答的必要問題等待答覆；時間經過不等於答覆。使用者委託你選擇時，採用 5 個場景、明確指定的語言（未指定則為繁體中文）、無配音，並告知這些預設值。除非使用者要求，不額外增加分鏡核准步驟。

## 2. 連接 BeamCue MCP

在開發 AI 的 MCP 設定中新增以下遠端 Streamable HTTP 伺服器：

https://beamcue.com/mcp

使用 MCP 宿主支援的連接介面，檢查已安裝的能力，不要猜測各用戶端的設定命令。僅把 URL 放入提示詞並不會安裝或授權 MCP。無法自行設定時，請使用者在 AI 工具中新增該地址，然後繼續目前對話。OAuth 由宿主和使用者瀏覽器處理：

- 授權伺服器：https://beamcue.com/o
- 受保護資源中繼資料：https://beamcue.com/.well-known/oauth-protected-resource/mcp
- 授權伺服器中繼資料：https://beamcue.com/.well-known/oauth-authorization-server/o
- 權限範圍：`projects:read projects:write`
- 使用 S256 PKCE 的 Authorization Code 流程；回呼和 PKCE 值由宿主提供。

呼叫前查詢目前工具及其模式。宿主可能給工具名新增前綴。呼叫 `get_connection_status`，在修改專案前確認 `mcpConnectionStatus=connected`。缺少連接或連接過期時，使用 `begin_oauth` 或 `get_reconnect_url` 讓宿主重新啟動 OAuth。網站登入和 MCP OAuth 是不同工作階段；登入網站不能修復宿主過期的授權。不要在聊天中索要密碼、權杖或 PKCE 秘密，也不要把它們放入提示詞、截圖或紀錄。

## 3. 規劃場景並採集真實畫面

按用途和指定數量安排場景。每個場景明確觀眾應理解的要點、路徑或導航操作、所需介面狀態、目標元素（如有）、標題、簡短說明和注意力引導計劃：指向什麼、解釋什麼、展示什麼結果，以及哪些效果由 MCP 設定、哪些需要 Studio 編輯。受託製作 5 場景介紹時，涵蓋入口、主要工作區、核心操作、結果，以及另一項有用功能或下一步行動。以實際功能為準，不為湊數捏造功能。

盡量使用獲授權的測試帳號操作真實服務。使用可用的瀏覽器或原生截圖能力，或使用者提供的真實截圖，並遵守倉庫採集規則。在 BeamCue 倉庫中，Playwright 截圖僅供對照，不能用作專案源素材。不要用生成圖片、HTML 模型、樣例資料或程式碼片段證明服務正在工作。MCP 導入的是 `producer=mcp.client` 靜態圖片，不要稱為擴展錄制，也不要標成 `chrome.tabs.captureVisibleTab`。

使用一致的視口，等待目標狀態加載完成，上傳前檢查每張圖片。避免在圖片、請求、紀錄和證據中留下秘密或敏感輸入值。登入、付款、權限變更等重要操作需要使用者已有授權。無法登入、截圖或存取必要畫面時，具體說明所需存取操作或請求真實截圖，並等待。不要默默跳過必需場景，也不要把部分完成的專案當作完整成果。

從實際上傳圖片的左上角，以真實圖片像素測量目標坐標，不用 CSS 像素。無操作目標的場景使用圖片中心和 `labelMode=caption_only`，省略 `clickLabel`，不要虛構點擊。標題簡短，說明提供不同資訊，避免多個標籤重複同一句話。

### 引導觀眾理解真實操作

根據用途和受眾自行選擇表現細節，不要求使用者逐一設定效果或再次批准分鏡。建立時直接應用程式支援的 MCP 設定。有獲授權的 Studio 存取權限時，也通過可見控制項完成適當的 Studio 專用調整，保存並預覽。否則按場景列出待辦，不要把計劃中的效果稱為已應用程式。不要修改專案 JSON 或呼叫未公開 API 來繞過 MCP 的能力限制。

| 元素 | 如何引導注意力 | 目前設定方式 |
| --- | --- | --- |
| 點擊目標與操作標籤 | 指向準確控制項。使用“選擇日期範圍”等動詞加對象，而不是“點擊這裡”。 | `add_screen` / `update_screen`：實測 `clickXPixel`、`clickYPixel`、`clickLabel`，以及 `labelMode=both` 或 `hotspot_only`。 |
| 字幕 | 用一句短句說明操作意義或變化，無聲時也有用。 | `description` 和 `labelMode=caption_only` 或 `both`；說明也用作可選配音文本。 |
| 指針強調 | 在密集介面中讓下一步操作易於發現，保持強調指針一致。 | `update_project` 的 `pointerMode=highlighted`；若遮擋小控制項或分散注意力則用 `standard`。 |
| 點擊效果與高亮外觀 | 用可見提示強化真實操作，避免在概覽或結果畫面無故閃動。 | `presentation.clickEffectVisible=false`, `hotspotRadius`, `hotspotAnchor`. |
| 字幕和標籤佈局 | 避開目標、結果、導航和其他標籤，使用易讀對比度、統一字體和短行。 | `presentation.captionLayout`: `placement`, `point` (`x`, `y`: 0–1). |
| 縮放 | 短暫聚焦小而重要的控制項或結果，同時保留周邊上下文。 | `presentation.zoomEnabled=true`, `presentation.zoomScale=1.16` (1.12–1.20). |
| 時長與轉場 | 留出尋找目標、閱讀結果的時間。明確狀態變化用切換，平靜銜接用交叉淡化，僅在說明連續性時使用滑動或變形。 | `presentation.durationMs`, `transition` (`cut`, `crossfade`, `slide`, `morph`), `slideDirection`, `transitionAnchor`. |
| 輸出邊框 | 建立瀏覽器或應用程式上下文，避免不必要地縮小內容。 | `update_project` 的 `windowFrame=browser`、`app` 或 `none`。截圖已有邊框時用 `none`。 |
| 可選配音與停頓 | 觀看時解釋結果，發聲結束後留一點理解時間。 | 僅在使用者要求時呼叫 `set_narration` / `generate_voiceover`。`endPaddingMs` 支援 0–10000，需要時從 400–800ms 開始。 |

`labelMode` 控制說明文字。`caption_only` 不會隱藏點擊效果；沒有操作的場景請設定 `presentation.clickEffectVisible=false`，並檢查預覽。

在要求的場景數量內遵循 **瞭解背景 → 操作 → 確認結果 → 繼續**。如果報告服務實際擁有以下功能，可這樣安排：

| 場景 | 採集與強調 | 文案示例 |
| --- | --- | --- |
| 1. 背景 | 真實工作區全貌；只用字幕，無操作閃動，保留上下文。 | “在一個地方管理團隊報告。” |
| 2. 操作 | 使用前截圖日期篩選器，測量位置，使用 `both` 和強調指針，必要時在 Studio 適度放大。 | 標籤：“選擇日期範圍”；字幕：“將報告限定到需要比較的時間段。” |
| 3. 確認結果 | 截取真實篩選結果；僅用字幕，關注變化，不再次點擊篩選器。 | “圖表現在只顯示所選時間段的資料。” |
| 4. 再次操作 | 獲授權的導出操作前，截取真實導出控制項，用短標籤指向它。 | 標籤：“導出報告”；字幕：“將目前視圖準備成團隊資料。” |
| 5. 繼續 | 截取真實完成狀態或有用的下一頁，明確後續行動。 | 描述觀察到的結果，不根據點擊按鈕推斷成功。 |

按真實服務調整，不捏造控制項，不宣稱未觀察到的導出成功。`add_screen` 圖片是靜態狀態，不是交互前後錄制。需要展示變化時，將結果作為另一個計劃場景採集。保持指定場景數；數量少時優先主要操作及其結果。每一時刻只突出一個重點，不用字幕遮住目標，也不為增加動效而堆疊縮放、大點擊提示和移動文本。只讀服務應強調有意義的結果，不偽造點擊。

## 4. 建立專案並新增畫面

在對話中保留恢復記錄：專案 ID、Studio URL、已完成場景 ID 及順序、目前修訂版本和逐操作冪等鍵。不要記錄圖片 Base64、簽名 URL、憑據或敏感畫面內容。每個新的邏輯修改生成獨立鍵；重試同一修改時保持相同輸入和鍵。只有新請求才建立新專案。

以下 JSON 是工具參數示例，不是真實服務證據。將佔位內容替換為查證過的值。`canvas` 表示所選 CSS 視口，`output` 在指定時設定影片尺寸和 fps。網站的 `surface` 為 `browser`，原生應用程式為 `screen`。根據成果語言明確設定 `locale`。

```json
{"tool":"create_project","arguments":{"title":"服務介紹","surface":"browser","locale":"zh-TW","sourceUrl":"https://your-service.example/","canvas":{"width":1440,"height":900},"idempotencyKey":"<unique-create-key>"}}
```

保存返回的 `projectId` 和 `studioUrl`。沒有要求配音時關閉語音。

```json
{"tool":"set_narration","arguments":{"projectId":"<projectId>","enabled":false,"idempotencyKey":"<unique-narration-settings-key>"}}
```

為操作指南明確設定強調指針和符合截圖的邊框，不依賴預設值。

```json
{"tool":"update_project","arguments":{"projectId":"<projectId>","pointerMode":"highlighted","windowFrame":"none","idempotencyKey":"<unique-presentation-key>"}}
```

按順序新增真實圖片與同圖測得的像素坐標。`description` 提供字幕，啓用語音時也是配音文本。說明場景用 `labelMode=caption_only`，需要真實目標時用 `both`。根據回答設定 `narrationEnabled`。

```json
{"tool":"add_screen","arguments":{"projectId":"<projectId>","title":"主要工作區","description":"說明此畫面中實際可執行的工作流程。","clickXPixel":720,"clickYPixel":450,"labelMode":"caption_only","narrationEnabled":false,"imageFile":{"name":"workspace.png","mimeType":"image/png","dataBase64":"<actual-image-base64>"},"idempotencyKey":"<unique-scene-key>"}}
```

操作場景使用真實目標，並同時提供標籤和字幕。以下坐標僅是示例，要用已檢查圖片重新測量。標題可能出現在目標氣泡中，應保持簡短。令 `title` 與 `clickLabel` 一致可避免第二個重複標籤，字幕則補充操作的益處。

```json
{"tool":"add_screen","arguments":{"projectId":"<projectId>","title":"選擇日期範圍","clickLabel":"選擇日期範圍","description":"將報告限定到需要比較的時間段。","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","narrationEnabled":false,"imageFile":{"name":"date-filter.png","mimeType":"image/png","dataBase64":"<actual-image-base64>"},"idempotencyKey":"<unique-action-scene-key>"}}
```

目標或文字有誤時原地修改已有場景。

```json
{"tool":"update_screen","arguments":{"projectId":"<projectId>","stepId":"<stepId>","title":"選擇日期範圍","clickLabel":"選擇日期範圍","description":"比較所選時間段的結果。","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","idempotencyKey":"<unique-action-correction-key>","presentation":{"clickEffectVisible":true,"zoomEnabled":true,"zoomScale":1.16,"durationMs":4000,"transition":"crossfade","captionLayout":{"placement":"bottom-center","point":{"x":0.5,"y":0.9}}}}}
```

將設定放在 `add_screen`、`update_screen` 或 `add_screens_batch.screens[]` 的 `presentation` 中。更新會保留未指定的設定及既有字幕樣式。`captionLayout` 必須同時提供 `placement` 和 `point`。

### 圖片和請求限制

- 解碼後支援 PNG、WebP、JPEG。每邊最多 8192px，總像素最多 6400 萬。
- 內嵌圖片 Base64 解碼後最多 4MiB。Base64 增加約三分之一大小；整個 MCP HTTP 請求必須在 8MiB 內。
- `add_screens_batch` 以不可分割的方式接受 1–20 個內嵌畫面，但同樣受整個請求大小限制。優先順序呼叫 `add_screen`，便於預測大小和恢復；不要在一次請求中放入 20 張大圖。
- 較大圖片使用 `prepare_image_upload`，上限 15MiB。提供 `name`、`mimeType`、`byteLength`、`sha256`、`width`、`height`、`projectId` 和新 `idempotencyKey`。按返回的請求頭向 `uploadUrl` PUT 完全相同的圖片位元組。簽名 URL 十分鐘後失效且只能使用一次。隨後呼叫 `add_screen` 時用 `uploadId` 替代 `imageFile`。
- MIME、位元組數、SHA-256 和尺寸必須與實際圖片一致。根據解碼位元組判斷 MIME，不靠檔名：保存為 `.png` 的截圖也可能是 JPEG。不要記錄 Base64、簽名 URL 憑據或圖片位元組。超限時重新截取合適視口或一致縮放，並重新計算尺寸、哈希和目標坐標。

用 `update_screen` 修正、`reorder_screens` 調整順序，不建立重複畫面。查閱目前工具結構描述的必填欄位。如果響應有 `displayPreview.display`，檢查標題、點擊標籤和字幕是否重複顯示。

## 5. 可選配音

僅在使用者要求時通過 `set_narration` 啓用，設定請求的語言和支援的聲音，並開啓目標場景的配音。沒有聲音偏好時使用已有支援的預設聲音，不編造聲音 ID。說明最終確定後，以 `operation=generate-stale` 呼叫 `generate_voiceover`，再用 `get_narration_status` 檢查完成情況。單獨報告配音失敗或排隊任務，保留專案供 Studio 修正。

## 6. 恢復並繼續

- 連接失敗或響應不確定後，必要時重連，用 `get_project` 檢查已有專案。以原輸入和冪等鍵重試同一修改，不盲目建立另一個專案。
- `expectedRevision` 可選，簡單順序流程可省略。使用時若修訂衝突，閱讀結構化錯誤、刷新專案狀態，使用返回的重試修訂版本並保持相同邏輯輸入和鍵。保留使用者編輯；若與請求衝突，先詢問而非覆蓋。
- 簽名上傳過期時，用新上傳操作鍵重新準備。將失敗的新增畫面請求換成新 `uploadId` 時，先確認舊操作沒有建立場景，再用新的新增操作鍵。
- 必要存取或截圖不可用時，簡潔指出缺少的場景與所需操作。保留已完成內容和 Studio 連結，便於在此對話繼續，不必重來。

## 7. 驗證並交付

用 `get_project` 將實際場景數、順序、標題、說明和所選配音狀態與請求比較並修正差異。同時逐場景核對注意力計劃：準確的操作目標、不同的操作和結果文案、合適的標籤模式以及已應用程式的指針和邊框。然後驗證規範化專案：

```json
{"tool":"get_project","arguments":{"projectId":"<projectId>"}}
```

```json
{"tool":"validate_project","arguments":{"projectId":"<projectId>","idempotencyKey":"<unique-validation-key>"}}
```

使用返回的 `studioUrl` 或 `open_studio` 動作中的 `nextAction.url`，不猜測專案 URL。有獲授權的瀏覽器存取時，在真實 Studio 場景列表和預覽中檢查導入圖片與字幕。跨場景播放，確認點擊提示落在正確控制項、結果呈現真實變化、字幕清晰且不遮擋目標、縮放不裁掉必要 UI。桌面和小尺寸預覽都要檢查。確認閱讀時間（包括無聲時）、轉場警告和 Studio 專用編輯在保存、重新加載後仍存在。宣佈準備完成前，縮短擁擠文案或簡化效果。無法登入 Studio 時，單獨報告 MCP 驗證並請使用者檢查連結中的專案，不聲稱已做視覺驗證。

最後給出專案標題、完成/請求場景數、簡短場景列表、已應用程式視覺提示、配音狀態、Studio 連結和待辦。區分已應用程式 MCP 設定、已目視檢查的 Studio 調整和逐場景待完成調整。所有必需畫面與說明存在時才稱專案完成。

`validate_project` 只驗證並準備 Studio 編輯，不發佈、不生成配音、不渲染 MP4。MCP 沒有影片渲染工具。保持專案非公開，讓使用者在 Studio 預覽、編輯、渲染 MP4 並選擇共享。不能僅因專案驗證成功就稱公開連結或影片檔案已經存在。