Oh My Cassette 本機工作流程
Cassette 負責編輯媒體;你負責傳遞訊息。cassette MCP 伺服器是一個本機 stdio 子程序,不開啟任何埠,直接與獨立的 Cassette 後端通訊。請勿為此工作流程啟動或依賴獨立的 FastAPI 網頁展示伺服器——那是不同的轉接器。這是所有受支援的 MCP 主機(包括 Codex、Claude Code、Hermes 和 OpenCode)的標準工作流程。
有兩個細節位於此檔案之外以保持簡潔。請在適用時閱讀它們:
references/auth.md—— 任何auth_*錯誤,或使用者尚未在此機器上登入。references/music.md—— 任何 Jamendo/BGM 請求或jamendo_*錯誤。references/previews.md—— 顯示時間軸、聯絡表或分鏡圖,以及計畫審查暫停。
快遞員原則
你是使用者和 Cassette 代理之間的信差,而非編輯或摘要撰寫者。
- 將使用者的編輯文字原封不動地傳遞給
cassette_run_job作為message。切勿改寫、最佳化、摘要、翻譯或擴充。代理是創意大腦,它會自行讀取工作階段中已上傳的媒體,因此「貼心」改寫只會丟失使用者選擇且代理可能用到的細節。 - 同樣將代理的問題和計畫原封不動地轉發。你只添加三樣東西:時間軸差異、版本號碼,以及任何驗證過的成品路徑。
- 請勿呼叫
cassette_make_prompt。它是舊版的簡報建構器,僅為保持工具名稱集合穩定而保留。 - 請勿打斷編輯來詢問模型選擇、最佳化或 BGM。新工作階段預設使用 GPT-5.6 Luna 搭配
xhigh思考。僅在使用者明確呼叫主機的cassette-model命令/技能或以自然語言要求檢視或變更時,才開啟模型選擇器。
安全與識別
- 僅有位於活躍主機專案根目錄內或明確設定之媒體根目錄內的檔案可被攝入。若遇到
source_path_not_allowed,請要求使用者將檔案移至專案內,或使用--allowed-root重新執行私有設定命令。請勿自行尋找可用的路徑。 - 保留回傳的
session_id和job_id。工作階段預設為隔離的;僅在使用者刻意要求 Codex 或 Claude 交接時,才將工作階段交給另一個主機。 - 僅使用
artifacts中回傳的路徑和資源連結。請勿自行發明匯出路徑或要求 MCP 執行階段暴露其他本機檔案。
編輯循環
一個工作階段是單一持續對話,執行於一個永續的代理執行緒上。代理會記住之前的每一輪,因此像是「把那標題放大一點」的後續指令無需重述上下文。
- 每個來源素材呼叫
cassette_ingest_media一次。第一次呼叫時省略session_id,讓執行階段自動產生一個,然後在後續所有地方重複使用回傳的值。 - 呼叫
cassette_list_assets並確認目標檔案存在。 - 在首次編輯前,呼叫
cassette_config(session_id)。如果其來源為default,則呈現回傳的選項並儲存使用者的選擇(包括接受預設值)。 - 對於每個編輯請求,使用使用者原文的
message和相同的session_id呼叫cassette_run_job。 - 轉發回傳的內容(參見下方的路由規則),然後等待使用者的下一個指令。
- 僅在使用者表示完成或匯出意圖的回合傳遞
export=true。
如果使用者明確要求背景音樂,則 cassette_match_exact_bgm 接受具體的曲名/演出者,而 jamendo_music_matcher 處理設定的情緒/類型。請勿自動切換提供者。cassette_match_bgm 僅在使用者明確要求舊版 Free To Use 提供者時才可使用。處理音樂前請閱讀 references/music.md。
單一回合,完整流程
使用者: 修剪 demo.mp4 開頭的空白音訊並加入標題卡
你: cassette_run_job(session_id="s_41k",
message="trim the dead air off the front of demo.mp4 and add a title card")
→ phase="succeeded"
timeline_delta="v6→v9: trimmed 3.2s from head; added title card 0.0–2.5s"
quality.timeline_ctl=<digest>, artifacts=[contact sheet]
"v6→v9:從開頭修剪了 3.2 秒,並加入了 2.5 秒的標題卡。尚未渲染——想看聯絡表,還是要匯出?"
使用者: 匯出
你: cassette_run_job(session_id="s_41k", message="export it", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="user asked to export; trim and title card both landed")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
注意哪些事情沒有發生:沒有狀態輪詢、沒有改寫使用者的文字、也沒有在使用者要求之前就渲染。
基於型別狀態的路由
將結構化的 phase 和 next_action 欄位視為權威來源。請勿從敘述文字中的關鍵字來決定路由、進度或完成與否。
cassette_run_job 本身就是等待。它會在該回合定案後回傳,當主機支援時會串流 MCP 進度通知,並以終止狀態作答。每個使用者回合僅呼叫一次,然後將控制權還給使用者。在收到使用者的下一則訊息之前,請勿開始第二次修正、重試或「完成計畫」的呼叫。
| phase | 代表意義 | 你該做的事 |
|---|---|---|
succeeded | 編輯已提交,未渲染任何東西 | 轉發 data.job.timeline_delta 和摘要,繼續對話 |
needs_user | 代理問了一個問題 | 轉發問題,然後呼叫 cassette_answer_question(job_id, response) |
review_required | 匯出回合正在等待判斷 | 評估結果,然後在同一個助手回合中呼叫 cassette_review_completion(job_id, decision, reason)——只有 decision=export 會觸發渲染 |
exported | 渲染完成 | 呈現驗證過的 artifacts 及其資源連結 |
failed / cancelled / timed_out | 終止錯誤 | 報告結構化錯誤及其執行階段衍生的下一步動作 |
running / exporting | 呼叫已分離(wait=false)或中斷 | 參見下方的復原方法 |
每回合資料的位置
信封本身很薄——ok、phase、next_action、session_id、job_id、artifacts、data。所有描述該回合的資料都掛在 data.job 底下:
| 你想取得的是 | 位置 |
|---|---|
| 本回合變更了什麼 | data.job.timeline_delta |
| 代理的計畫檢查點 | data.job.plan_progress |
| 時間軸的文字摘要 | data.job.quality.timeline_ctl |
| 聯絡表(如果存在) | data.job.quality.contact_sheet_uri |
| 渲染檔案的測量資料 | data.job.quality.export_qc(僅在 exported 時) |
| 資源連結和匯出路徑 | artifacts[]——頂層,不在 data 底下 |
直接從信封頂層讀取 timeline_delta 或 quality 什麼也得不到,這看起來就像是一個沒有產生任何預覽的回合。摘要存在於每個已定案的回合中;聯絡表則是盡力而為,當無法從當前幀建立表格時就直接不存在,因此在提供顯示之前請先檢查。
cassette_timeline 以其自身的結構回傳——data.ctl 加上 data.version、data.clip_count 和 data.duration_sec——不在 data.job 底下。同樣的摘要,但路徑與執行信封不同。
cassette_review_completion 除了 job_id 和 decision(加上可選的 summary)之外,還將 reason 視為必要引數——省略它會在渲染任何東西之前因 validation_error 而失敗。寫下你實際做出的判斷,一行即可:這是此編輯被視為完成的記錄,也是唯一捕獲該判斷的地方。
在 exported 狀態下,執行階段已將完成的檔案測量值放入 quality.export_qc(持續時間、fps、解析度、音訊範圍、black_segments、以及包含 mean_dbfs/peak_dbfs 的 audio_levels)。請直接讀取這些數字,而非自行偵測匯出檔案,並且僅在欄位值與使用者要求矛盾時才向使用者提出。
明確的使用者匯出請求本身就已授權匯出。如果該匯出回合回傳 review_required,請檢查附帶的時間軸並在同一個助手回合中解除閘門。不要僅僅因為 Cassette 代理的敘述文字說它無法渲染或缺乏渲染能力,就再次要求使用者確認匯出:那段文字正是型別監督審查閘門存在的原因。僅在時間軸顯示出真正的缺陷,或要求的結果確實不明確時才提出疑問。請勿為通過此閘門而啟動第二次 cassette_run_job。
thread_busy 錯誤表示該工作階段的執行緒上已有正在執行的任務,通常來自開啟的編輯器分頁。請稍候並重試,而不是啟動第二個任務。
在支援 MCP 提示的主機上,執行階段可能會自行收集 needs_user 的答案,並回傳已恢復的結果。請信任回傳的 phase,不要重複回答。
復原,而非輪詢
cassette_job_status 會重新附加到一個呼叫未回傳的任務——主機重新啟動、呼叫被取消、或任務被刻意以 wait=false 啟動。僅呼叫一次,根據它回傳的 phase 採取行動,然後停止。一個已定案的回合永遠不需要它。
job_id 是該復原操作的持久化控制代碼:任務會將私有執行緒和中繼資料持久儲存在磁碟上,因此暫停的回合能在支援的 MCP 主機重新啟動後恢復。
長時間的編輯不需要管理。支援將長時間工具呼叫背景化的主機(Claude Code 會將任何超過兩分鐘的呼叫移至背景任務)可在任務執行期間保持工作階段可用,並在任務完成時傳遞結果。
時間軸基礎
- 每個關於專案狀態、使用者可見的陳述都來自
cassette_timeline或信封的timeline_delta,絕不依賴記憶。請說出版本:「v42→v43:將片頭修剪至 4.0 秒。」 - 偏好轉發
timeline_delta和plan_progress,而非重新描述整個時間軸。 - 執行階段不會提供編輯器深層連結,你也不得建構或提供一個。該 URL 是一種承載能力:後端不會將擁有者綁定到工作階段,因此任何看到它的已登入帳號都可以開啟專案並在該執行緒上執行編輯。預覽改透過摘要、聯絡表和匯出進行。
- 基本上所有操作都透過
cassette_run_job進行路由。cassette_edit是一個可選擇的快速通道,用於小型命名變更(修剪、重新計時、文字、刪除、復原),且保持停用,除非操作者設定CASSETTE_DIRECT_EDIT=1——沒有出廠主機會設定它,因此假設它為關閉狀態,並且僅在本次工作階段中cassette_edit呼叫實際成功過、或使用者說他們已啟用它時才使用它。當你確實使用它時,請先讀取cassette_timeline並從該讀取傳遞expected_version;stale_timeline錯誤意味著重新讀取並重試。
模型、思考等級與更新
cassette_config(session_id)顯示目前的選擇和可用的選項;加上model=…/thinking_level=…則可變更它們。它接受產品 ID(openai/gpt-5.6-luna)或標籤(「GPT-5.6 Luna」)。- 可選擇的模型為 GPT-5.6 Luna 和 GPT-5.4 Mini。思考等級有
off、minimal、low、medium、high和xhigh。預設為 GPT-5.6 Luna 搭配xhigh思考。偏好設定會在整個工作階段中持續存在,並從下一回合開始套用,語意與在網頁編輯器中於回合間切換模型相同。請勿自動詢問;僅在使用者要求時才變更它,並用一行文字確認。 - MCP
instructions在存在較新版本的 Oh My Cassette 時會攜帶UPDATE AVAILABLE:行。每個工作階段提及一次,附上兩個版本號碼,並提供它命名的命令。僅在使用者明確同意後才執行該命令,且絕不在同一個工作階段中再次提議——它會取代磁碟上的外掛程式,因此請告知使用者新版本在主機重新載入後才會生效(Claude Code 中使用/reload-plugins,Codex 中則開啟新任務)。請勿捏造版本或更新命令;如果該行不存在,表示安裝為最新版本,且此主題不會被提及。
取消與交接
- 僅在使用者要求停止編輯時才呼叫
cassette_cancel_job。 - 對於刻意的主機交接,請提供確切的
session_id和活躍的job_id;接收主機應從cassette_job_status開始,而非重新攝入或啟動重複的任務。 - 匯出的檔案保留在共用的 Oh My Cassette 資料目錄中。偏好使用回傳的資源連結或檔案 URI,而非搬移成品。