Communitygithub.com

pattern-ai-labs/built-with-agentcall

由 Pattern AI Labs 打造的真實世界應用案例合集,每個資料夾都是一個可直接執行的獨立範例。

built-with-agentcall 是什麼?

此技能提供一個名為「Presenter」的 AI 簡報機器人,能夠加入線上會議並簡報文件或主題。它會將簡報以螢幕分享的方式直接顯示在會議主畫面上,並以機器人的聲音進行旁白,同時自動切換投影片。此外,機器人會以小視窗形式顯示其頭像,營造出類似真人簡報的體驗。使用者也可以透過 `--avatar-mode` 參數,改為將簡報內容直接顯示在頭像視窗中。此技能支援顯示 PowerPoint、PDF 等投影片格式,也能將 Word 文件或純主題自動生成一份結構化簡報。所有簡報內容與投影片導覽皆由使用者透過 JSON 指令控制,機器人不會直接朗讀投影片文字,確保簡報的互動性與智慧性。此技能主要用於開發者工具環境(如 Claude Code、Coder 等),透過命令列即可執行,適合需要自動化簡報或模擬真人簡報的場景。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add pattern-ai-labs/built-with-agentcall

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Presenter — 在會議中簡報文件(或主題)

一個 AI 機器人加入會議並進行簡報:預設情況下,簡報會以螢幕分享的形式完整顯示在會議主畫面上,由機器人的聲音旁白並自動推進,而機器人的臉部會顯示在一個小的攝影機方塊中。(如果傳入 --avatar-mode 參數,或使用者說「以頭像模式加入」,則會改為將簡報顯示在攝影機方塊上,呈現原本的單一方塊外觀。)兩種模式都不需要點擊器。

顯示模式: 螢幕分享是預設模式(全螢幕投影片顯示,並有簡報者的臉部);頭像模式 (--avatar-mode) 則將簡報僅顯示在攝影機方塊上。其他所有功能 — 語音控制、配套遙控器、旁白、問答 — 在兩種模式下運作方式完全相同。

主要使用情境:使用者提供會議連結和一份文件(PDF、PowerPoint 或 Word),機器人即可進行簡報。 也可以僅從一個主題開始。

請依序執行(完整流程 — 每次固定,不繞路)

0 · 預檢(一次)。

  • API 金鑰 — 依此順序檢查,如果已存在則不要詢問(一個設定檔,與 AgentCall 使用同一個;這是 load_api_key 使用的確切順序):
    1. ~/.agentcall/config.json 存在且包含 api_key?→ 準備就緒。
    2. 已設定 AGENTCALL_API_KEY 環境變數?→ 準備就緒。
    3. 以上皆無?→ 詢問使用者取得金鑰(在 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 小節。

嚴格規則(以下每一條都曾經讓實際的簡報流程失敗 — 程式碼會強制執行其中大部分規則,請不要試圖規避):

  1. 切勿將原始文件直接傳遞給 present.py 後就撒手不管。 轉換 → 檢查 needs_narration 標記 → 撰寫 notes → 再進行簡報。拒絕退出(錯誤碼 2)是通知你該撰寫旁白的信號,而不是一個可以跳過的錯誤。
  2. 切勿透過重新轉換來覆蓋已撰寫的 deck.json。 未變更的來源 → 會自動重複使用;只有在使用者明確要求重新轉換時,才刪除該簡報資料夾。
  3. 切勿編造一個佔位用的簡報或在鏡頭前道歉。 如果轉換失敗,present.py 會直接退出 — 修正輸入內容(或安裝 LibreOffice)後重新啟動。一個從未加入會議的機器人,比一個看起來有問題的機器人要好。
  4. 切勿讓會議持續運行。 present.py 會在每次退出時自行停止計費 — 但如果是你啟動的,請確認該程序在簡報結束時確實已退出。

1b · 重視使用者的簡短指示 — 這些指示會影響簡報的內容 AND 你的操作方式。 當使用者說出任何超出「簡報這個」範圍的內容時,請記錄下來並加以應用。這些指示會落在以下兩個地方之一:

  • 撰寫時(寫入 deck.json) — 任何關於內容或表達方式的指示:
    • 「保持簡潔 / 大約 5 分鐘 / 每張投影片一句話」 → 撰寫較短的 notes;投影片停留時間是根據長度計算的,所以較短的筆記 = 更快的演講。「深入探討」 → 撰寫更豐富的 notes。
    • 「在價格頁上說 ‹X›」、「用一個笑話開場」、「強調 ‹Y›」 → 將那句內容放入該張特定投影片的 notes 中,以便在確切的位置說出。
    • 「跳過路線圖那張」 → 在撰寫時刪除/合併該投影片。
  • 即時驅動策略(由你執行) — 任何關於在會議中反應的指示:
    • 「不要回答關於 ‹Z› / 價格 / 人數的問題」 → 當此類問題透過 heard.jsonl 傳來時,請勿回答:改以簡短的迴避回覆({"cmd":"say","text":"好問題 — 我們會後再討論。"})代替真正的回答。「將所有問答延後到最後」 → 先確認並繼續簡報,而不是在簡報中途回答問題。
    • 「在第三張投影片暫停討論」、「只有在我說可以時才前進」 → 調整你發送 next/present 指令的頻率。 請在整個會議過程中記住這些規則 — 它們適用於整個通話,而不僅僅是第一張投影片。如果某個要求不明確,請在啟動前詢問使用者。

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 或主題)

文件不是投影片 — 直接顯示它的頁面會造成很差的簡報效果。因此,你需要自行建立簡報。

  1. 轉換以取得來源內容 + 圖表:
    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/         ← 文件本身的圖表,已經被取出
    
  2. 根據 source.json 撰寫 deck.json — 這是重要的一步。請做好它:
    • 先擬大綱,再填入內容。 每個主要想法建立一張投影片。在心中建立一份文件章節/標題的檢查清單,確保每個重點都落在某張投影片上 — 不要遺漏任何內容。
    • 每張投影片:一個簡短的 title、最多 6 個簡短的 bullets,以及 notes = 自然的口語旁白(1–4 句話;縮寫請標示拼音,例如「A.P.I.」,以便 TTS 能正確發音)。
    • 重複使用來源文件的圖表。 source.json 會列出從文件中提取的圖片(位於 sections[].images 和 all_images 中)。將相關的圖片放入投影片的 image 欄位中 — 這樣投影片就會在你的條列重點旁邊顯示該真實圖表(分割版面)。不要憑空發明圖片。
    • 以一行介紹投影片開場;以總結收尾(機器人會在最後一張投影片結束後離開)。
  3. 預覽和簡報(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> 參數可設定投影片間隔時間。

語音控制 — 你是大腦(重要部分)

在互動模式下,機器人會將其聽到的內容轉發到一個檔案,並執行你回寫的指令。沒有硬編碼的詞組:你理解請求並決定動作。在背景中執行並循環:

  1. 啟動它(即時模式預設為互動): 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 秒內執行。
  2. 當機器人被叫到名字時(「Presenter,……」)— 或在簡短的跟進回應視窗內 — 將解讀後的指令附加到 commands.jsonl。
  3. 繼續監聽,直到簡報完成。

指令格式(一個 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 退出,代碼 2deck.json 缺少 notes — 請檢視 source.json,撰寫每張投影片的旁白,然後重新執行
機器人從未加入檢查 API 金鑰和會議 URL。在 present.py 中使用 --verbose 參數以取得更多資訊
簡報卡住檢查 link/commands.jsonl — 你需要發送 next 來推進。如果機器人正在與你交談,請說「繼續前進」或發送 next

由 Pattern AI Labs 開發。根據 agentcall.dev 的條款和條件使用。

相關技能