Presenter — 在會議中簡報文件(或主題)
一個 AI 機器人加入會議並進行簡報:預設情況下,簡報會以螢幕分享的形式完整顯示在會議主畫面上,由機器人的聲音旁白並自動推進,而機器人的臉部會顯示在一個小的攝影機方塊中。(如果傳入 --avatar-mode 參數,或使用者說「以頭像模式加入」,則會改為將簡報顯示在攝影機方塊上,呈現原本的單一方塊外觀。)兩種模式都不需要點擊器。
顯示模式: 螢幕分享是預設模式(全螢幕投影片顯示,並有簡報者的臉部);頭像模式 (--avatar-mode) 則將簡報僅顯示在攝影機方塊上。其他所有功能 — 語音控制、配套遙控器、旁白、問答 — 在兩種模式下運作方式完全相同。
主要使用情境:使用者提供會議連結和一份文件(PDF、PowerPoint 或 Word),機器人即可進行簡報。 也可以僅從一個主題開始。
請依序執行(完整流程 — 每次固定,不繞路)
0 · 預檢(一次)。
- API 金鑰 — 依此順序檢查,如果已存在則不要詢問(一個設定檔,與 AgentCall 使用同一個;這是
load_api_key使用的確切順序):~/.agentcall/config.json存在且包含api_key?→ 準備就緒。- 已設定
AGENTCALL_API_KEY環境變數?→ 準備就緒。 - 以上皆無?→ 詢問使用者取得金鑰(在 agentcall.dev/api-keys 免費取得)並將其寫入
~/.agentcall/config.json(請參閱設定章節)— 以 AgentCall 的格式建立該檔案,然後繼續。
- 相依套件 —
pip install -r requirements.txt(快速;純 Python wheel,無需系統工具)。
1 · 將輸入內容轉換為簡報。你(代理)始終擁有旁白的控制權 — 切勿讓機器人直接朗讀投影片上的文字。 先執行 doc_to_deck.py,然後檢視其產生的結果:
.pptx/.ppt檔案,或投影片格式的 PDF → 顯示真實投影片,但旁白由你負責:- 如果檔案每張投影片都有備忘稿(僅限
.pptx— 舊版.ppt的備忘稿無法讀取;請要求.pptx格式),這些備忘稿就會成為旁白 — 你已經完成,可以直接簡報。只有部分投影片有備忘稿 → 該簡報會被標記,需要你為缺少備忘稿的投影片撰寫旁白。 - 如果完全沒有備忘稿,則該簡報會被標記為
needs_narration,且每張投影片的notes都是空的(並會產生decks/<name>/source.json)。在簡報前,你需要為每張投影片撰寫口語化的notes行(請閱讀source.json並瀏覽投影片圖片)—present.py拒絕執行一份尚未撰寫旁白的轉換後簡報,所以這沒有捷徑。撰寫旁白本身就是簡報的一部分。
- 如果檔案每張投影片都有備忘稿(僅限
.docx/.doc檔案、報告型 PDF,或一個主題 → 自行撰寫簡報:執行doc_to_deck.py --mode generate,閱讀decks/<name>/source.json(其中的文字 + 抽取的圖表),然後撰寫decks/<name>/deck.json。請勿嘗試自行開啟或渲染檔案(不需要pdftoppm、不需要圖片工具)—source.json就是你的輸入內容。撰寫時請保持精簡:一張投影片一個重點、簡短的條列敘述、自然的旁白 — 不要過度修飾。- 已撰寫的內容是受保護的 — 但僅限於預設的簡報資料夾。 如果重新執行轉換(或
present.py --deck <相同文件>),且來源文件未變更,則會重複使用已撰寫的deck.json(位於decks/<name>/中)— 立即完成,無需重新渲染,你的旁白得以保留。只有當文件本身變更時才會重新轉換(然後需要重新撰寫 — 標記會再次出現)。對於你將要撰寫並簡報的文件,請勿傳遞--out <不同的資料夾>— 一個新的資料夾沒有可重複使用的簡報,所以你會得到一份備忘稿為空的草稿(而真正撰寫好的簡報則會被閒置)。--out僅用於一次性/檢查性的轉換。請從預設的decks/<name>/deck.json路徑進行撰寫、簡報和重複簡報。 - 詳細說明與簡報結構:請參閱下方的 A 和 B 小節。
嚴格規則(以下每一條都曾經讓實際的簡報流程失敗 — 程式碼會強制執行其中大部分規則,請不要試圖規避):
- 切勿將原始文件直接傳遞給
present.py後就撒手不管。 轉換 → 檢查needs_narration標記 → 撰寫notes→ 再進行簡報。拒絕退出(錯誤碼 2)是通知你該撰寫旁白的信號,而不是一個可以跳過的錯誤。 - 切勿透過重新轉換來覆蓋已撰寫的
deck.json。 未變更的來源 → 會自動重複使用;只有在使用者明確要求重新轉換時,才刪除該簡報資料夾。 - 切勿編造一個佔位用的簡報或在鏡頭前道歉。 如果轉換失敗,
present.py會直接退出 — 修正輸入內容(或安裝 LibreOffice)後重新啟動。一個從未加入會議的機器人,比一個看起來有問題的機器人要好。 - 切勿讓會議持續運行。
present.py會在每次退出時自行停止計費 — 但如果是你啟動的,請確認該程序在簡報結束時確實已退出。
1b · 重視使用者的簡短指示 — 這些指示會影響簡報的內容 AND 你的操作方式。 當使用者說出任何超出「簡報這個」範圍的內容時,請記錄下來並加以應用。這些指示會落在以下兩個地方之一:
- 撰寫時(寫入
deck.json) — 任何關於內容或表達方式的指示:- 「保持簡潔 / 大約 5 分鐘 / 每張投影片一句話」 → 撰寫較短的
notes;投影片停留時間是根據長度計算的,所以較短的筆記 = 更快的演講。「深入探討」 → 撰寫更豐富的notes。 - 「在價格頁上說 ‹X›」、「用一個笑話開場」、「強調 ‹Y›」 → 將那句內容放入該張特定投影片的
notes中,以便在確切的位置說出。 - 「跳過路線圖那張」 → 在撰寫時刪除/合併該投影片。
- 「保持簡潔 / 大約 5 分鐘 / 每張投影片一句話」 → 撰寫較短的
- 即時驅動策略(由你執行) — 任何關於在會議中反應的指示:
- 「不要回答關於 ‹Z› / 價格 / 人數的問題」 → 當此類問題透過
heard.jsonl傳來時,請勿回答:改以簡短的迴避回覆({"cmd":"say","text":"好問題 — 我們會後再討論。"})代替真正的回答。「將所有問答延後到最後」 → 先確認並繼續簡報,而不是在簡報中途回答問題。 - 「在第三張投影片暫停討論」、「只有在我說可以時才前進」 → 調整你發送
next/present指令的頻率。 請在整個會議過程中記住這些規則 — 它們適用於整個通話,而不僅僅是第一張投影片。如果某個要求不明確,請在啟動前詢問使用者。
- 「不要回答關於 ‹Z› / 價格 / 人數的問題」 → 當此類問題透過
2 · (可選)預覽 — present.py --local --deck <deck> 會產生一個 localhost URL,讓你在上線前觀看簡報效果。
3 · 在背景啟動上線簡報 — python scripts/present.py "<url>" --deck <deck> &
(名稱/語音來自 ~/.agentcall/config.json;可使用 --name/--voice 參數覆蓋每次執行的設定)。
機器人需要 30–90 秒才會出現,然後會打招呼並等待。
4 · 驅動簡報 — 立即開始監聽。 監看 link/heard.jsonl 並回覆至 link/commands.jsonl(完整協定請參閱語音控制)。在收到你的 present 回覆之前,簡報不會開始進行。
5 · 結束 — 當所有人離開、達到時間上限、或收到 leave 指令時,機器人會自動離開並停止計費。如果你啟動了它,請確認該程序已退出。
兩種模式(這是核心概念)
| 模式 | 功能 | 預設用於 |
|---|---|---|
| show | 將文件的真實頁面/投影片渲染為圖片並原樣顯示 | .pptx/.ppt 檔案,以及投影片格式的 PDF |
| generate | 解析文件,然後由你自行撰寫一份有意義的簡報(包含標題、條列重點、口語旁白),並帶入來源文件中的圖表 | .docx/.doc 檔案、密集/報告型 PDF,以及主題 |
經驗法則:已經是投影片的檔案 → 直接顯示。文件(散文) → 從中生成簡報。 auto(預設值)會根據檔案類型來決定,對於 PDF 則會根據頁面形狀(橫向 + 稀疏文字 = 投影片 → 顯示;直向 + 密集文字 = 文件 → 生成)。可以使用 --mode show|generate 來覆蓋。使用者的意圖始終優先(「確切地簡報我的投影片」→ 顯示;「將此摘要成一份簡報」→ 生成)。
A) 直接顯示投影片(PowerPoint 或投影片風格的 PDF)
顯示模式會保留每張投影片的原始設計(以全版圖片的方式顯示實際投影片)。它會說出什麼內容,則取決於該檔案是否包含備忘稿:
python scripts/doc_to_deck.py "/path/deck.pptx" # 渲染投影片 + 偵測備忘稿
- 每張投影片都有備忘稿(
.pptx)→ 這些備忘稿就是旁白。直接簡報:python scripts/present.py "<MEETING_URL>" --deck decks/deck/deck.json - 完全沒有備忘稿 — 或僅部分投影片有 → 該簡報會被標記為
needs_narration(否則沒有備忘稿的投影片會陷入死寂)。為每張缺少備忘稿的投影片撰寫口語化的notes行(從decks/<name>/source.json和投影片圖片中取得資訊),然後簡報撰寫完成的deck.json。這就是為什麼它是一個簡報者,而不是一個螢幕閱讀器。
present.py 會拒絕簡報一份 needs_narration 的投影片,直到每張投影片都有 notes 為止(它會退出並顯示錯誤,指向 source.json)。並沒有**「直接朗讀投影片文字」**的備用方案 — 這是設計使然。因此,切勿將一份沒有備忘稿的原始檔案直接交給 present.py 並期望它開口說話:請先轉換、撰寫 notes,然後再簡報撰寫完成的 deck.json。拒絕機制是安全網,而撰寫旁白是你的工作。
B) 生成有意義的簡報(Word 文件、密集的 PDF 或主題)
文件不是投影片 — 直接顯示它的頁面會造成很差的簡報效果。因此,你需要自行建立簡報。
- 轉換以取得來源內容 + 圖表:
python scripts/doc_to_deck.py "/path/file.docx" --mode generate # 寫入 decks/<name>/deck.json — 一份機械化的草稿,所有 notes 為空,並標記為 needs_narration; # present.py 會拒絕它,直到你撰寫完 notes 為止(這是下一步,非選項) # 以及 decks/<name>/source.json ← 解析後的章節 + 提取的圖片,供你撰寫使用 # 以及 decks/<name>/img/ ← 文件本身的圖表,已經被取出 - 根據
source.json撰寫deck.json— 這是重要的一步。請做好它:- 先擬大綱,再填入內容。 每個主要想法建立一張投影片。在心中建立一份文件章節/標題的檢查清單,確保每個重點都落在某張投影片上 — 不要遺漏任何內容。
- 每張投影片:一個簡短的
title、最多 6 個簡短的bullets,以及notes= 自然的口語旁白(1–4 句話;縮寫請標示拼音,例如「A.P.I.」,以便 TTS 能正確發音)。 - 重複使用來源文件的圖表。
source.json會列出從文件中提取的圖片(位於sections[].images和all_images中)。將相關的圖片放入投影片的image欄位中 — 這樣投影片就會在你的條列重點旁邊顯示該真實圖表(分割版面)。不要憑空發明圖片。 - 以一行介紹投影片開場;以總結收尾(機器人會在最後一張投影片結束後離開)。
- 預覽和簡報(C 和 D 小節)。對於一個沒有文件的主題,請跳過轉換步驟,直接撰寫
decks/<name>.json。
簡報 JSON 結構(文字投影片、圖片投影片,或兩者結合):
{
"title": "我的演講",
"slides": [
{ "title": "介紹", "notes": "口語介紹。" },
{ "title": "一個重點", "bullets": ["簡短詞組", "另一個"], "notes": "旁白。" },
{ "title": "附圖表", "bullets": ["它顯示了什麼"], "image": "fig1.png", "notes": "旁白。" },
{ "image": "slide3.png", "notes": "一張全版真實投影片(顯示模式)。" }
]
}
(bullets/notes/image 均為選填;別名 points 等同於 bullets,say 等同於 notes;只有標題的投影片作為封面。)
C) 預覽(建議)
python scripts/present.py --local --deck decks/<name>/deck.json # 或 decks/<name>.json,或一個原始檔案
會顯示一個 http://localhost:PORT/?ws=local URL — 開啟它即可在不開會的情況下觀看投影片渲染和自動推進的效果。
D) 上線簡報
python scripts/present.py "<MEETING_URL>" --deck <file-or-deck> [--mode show|generate]
即時會議預設為互動模式(需經過同意): 機器人加入會議、自我介紹,然後等待有人指示它開始。有兩種方式可以控制它:
- 透過語音 → 傳送給你(大腦)處理。 程式碼中沒有任何關鍵字比對。 參與者所說的任何內容 — 一旦他們叫了機器人的名字,或在短暫的後續回應視窗內 — 都會傳給你解讀,然後你回覆一個指令。協定見下方。
- 透過配套控制頁面(直接控制)。 一個手機/瀏覽器頁面(上一步 / 暫停 / 下一步 / 點擊投影片 / 重新開始 / 關閉),其連結會由機器人放入會議聊天室,同時也會列印在終端機上(
▸ Controls page: …)— 將終端機上的 URL 直接轉達給使用者;在 Google Meet 上透過聊天室傳遞可能不可靠。按鈕的意圖明確且在程序中、即時地執行(它們不經過你),因此它們是可靠的備用方案,也是無需代理連接時的驅動方式。
當所有其他人離開、達到硬性時間上限、或正常退出時,機器人會自動離開並停止計費 — 孤立無援的機器人不會產生費用。加上 --auto 參數可在不詢問的情況下立即開始簡報;--pace <s> 參數可設定投影片間隔時間。
語音控制 — 你是大腦(重要部分)
在互動模式下,機器人會將其聽到的內容轉發到一個檔案,並執行你回寫的指令。沒有硬編碼的詞組:你理解請求並決定動作。在背景中執行並循環:
- 啟動它(即時模式預設為互動):
python scripts/present.py "<url>" --deck <file> &它會顯示兩個路徑:link/heard.jsonl(機器人 → 你)和link/commands.jsonl(你 → 機器人)。 立即開始監聽 — 打招呼會自行播放,但簡報不會開始,直到你回應第一個「請開始」為止。只讀取新的行(追蹤位元組/行偏移量,或在檔案上阻塞 — 不要重複處理舊行),並在約 45 秒內回覆(之後簡報會自行恢復)。以下是一種高效、類似事件驅動的監聽方式,無需忙碌輪詢:(tail -n +1 -f link/heard.jsonl # 將每個新的語音作為一行資料流輸出;處理它,然後將你的回覆附加到 link/commands.jsonl 中&/tail是 POSIX 指令 — 在 Windows 上請使用你的背景執行工具和Get-Content link/heard.jsonl -Wait。)present.py會在你附加內容到commands.jsonl後的約 0.3 秒內執行。 - 當機器人被叫到名字時(「Presenter,……」)— 或在簡短的跟進回應視窗內 — 將解讀後的指令附加到
commands.jsonl。 - 繼續監聽,直到簡報完成。
指令格式(一個 JSON 物件一行):
{"cmd": "say", "text": "當然,很高興為您介紹。"}
{"cmd": "next"}
{"cmd": "leave"}
say = 機器人說話(無需標點符號,即時文字轉語音)。next = 前進到下一張投影片。leave = 結束會議。present = 開始簡報(如果尚未開始)。完整的協定會列印在終端機上。
故障排除
| 問題 | 解決方案 |
|---|---|
LibreOffice 不可用 錯誤 | sudo apt install libreoffice-impress libreoffice-writer(Ubuntu/Debian)或 |
brew install --cask libreoffice(macOS) | |
present.py 退出,代碼 2 | deck.json 缺少 notes — 請檢視 source.json,撰寫每張投影片的旁白,然後重新執行 |
| 機器人從未加入 | 檢查 API 金鑰和會議 URL。在 present.py 中使用 --verbose 參數以取得更多資訊 |
| 簡報卡住 | 檢查 link/commands.jsonl — 你需要發送 next 來推進。如果機器人正在與你交談,請說「繼續前進」或發送 next |
由 Pattern AI Labs 開發。根據 agentcall.dev 的條款和條件使用。