Communitygithub.com

pattern-ai-labs/built-with-agentcall

一个基于 agentcall.dev 构建的真实世界用例合集——每个文件夹都是一个可独立运行的完整示例。由 Pattern AI Labs 提供。

built-with-agentcall 是什么?

这个技能是一个包含多个真实世界用例的集合,每个用例都基于 agentcall.dev 构建,并作为独立的、可运行的示例文件夹提供。其中的核心技能是“Present”——一个 AI 机器人能够加入在线会议并自主演示文档或主题。它支持两种显示模式:默认的屏幕共享模式(在全屏上显示演示文稿,同时在一个小摄像头窗口中显示机器人面部)和头像模式(将演示文稿仅显示在摄像头图块上)。演示流程分为五个步骤:首先检查 API 密钥并安装依赖,然后将输入(PowerPoint、Word、PDF 或单纯的主题)转换为演示文稿——如果源文件没有演讲者备注,智能体必须为每张幻灯片编写自然的语音旁白。接着可以预览演示,然后以背景进程方式启动机器人加入会议。整个会议期间,智能体通过监听 `heard.jsonl` 文件中的语音输入并回复 `commands.jsonl` 文件来驱动机器人,解释参与者的问题并决定机器人的下一步行动(如前进到下一张幻灯片、回答问题或离开会议)。该技能还包含一个配套控制页面,提供直接的按钮控制(上一页、暂停、下一页等),作为语音控制的可靠备用方案。

兼容平台✓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 <same document>)会重用已编写的 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 · 尊重用户的简要指示——他们的指令决定了演示文稿的内容以及你如何驱动它。 当用户说出不止“展示这个”的时候,捕捉并应用这些指示。它们会进入以下两个位置之一:

  • 编写时(集成到 deck.json 中) —— 任何关于内容或表达方式的指示:
    • “简短些 / 大约 5 分钟 / 每张幻灯片一句话” → 编写更短的 notes;幻灯片停留时间是基于长度的,所以更短的笔记 = 更快的讲话速度。“深入讲解” → 编写更丰富的 notes。
    • “在定价幻灯片上说 ‹X›”、“以笑话开场”、“强调 ‹Y›” → 将该行放入对应幻灯片的 notes 中,以便在正确的位置说出。
    • “跳过路线图幻灯片” → 在编写时删除/合并它。
  • 现场驱动策略(你在运行中执行) —— 任何关于在会议中如何反应的指示:
    • “不要回答关于 ‹Z› / 定价 / 人员配置的问题” → 当此类问题通过 heard.jsonl 传来时,不要回答:用简短的回绝({"cmd":"say","text":"好问题——我们私下再讨论吧。"})代替真实回答。“将所有问答推迟到最后” → 确认并表示将继续演示,而不是在演示中途回答。
    • “在第 3 张幻灯片上暂停讨论”、“只有在我指示时才前进” → 调整你发送 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 传递给用户;在 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 会在大约 0.3 秒内执行你追加到 commands.jsonl 的任何内容。
  2. 当机器人被通过名字称呼时(“演示者,……”)——或在后续对话窗口期间——heard.jsonl 中会出现一条记录。阅读它,决定回复什么,然后将一个命令 JSON 对象追加到 commands.jsonl:
# 发送一条消息(机器人会高声说出)
{"cmd": "say", "text": "这是第 3/12 张幻灯片。它展示了我们的用户增长趋势。问题?"}

# 前进到下一张幻灯片
{"cmd": "next"}

# 返回上一张幻灯片
{"cmd": "prev"}

# 直接跳转到第 5 张幻灯片(灯光熄灭,然后第 5 张幻灯片亮起)
{"cmd": "goto", "slide": 5}

# 进入/退出举牌画面(机器人暂停并更多地面向摄像头对话)
{"cmd": "hold"}    # 暂停;再发送一次则继续

# 结束会议(“感谢您的参与。”离开)
{"cmd": "leave"}

# 用新幻灯片替换当前正在显示的幻灯片(即兴的现场幻灯片——与当前幻灯片无关)
{"cmd": "flash", "title": "一个快速的数字", "bullets": ["$5M ARR", "120% 同比增长"]}

# 将当前幻灯片变暗并切换回主摄像头(适合即兴的屏幕共享或白板讨论)
{"cmd": "camera_only"}
# 退出摄像头独占模式并恢复显示当前幻灯片
{"cmd": "un_camera_only"}

# 将机器人移出频道(仅限 Discord)——语音聊天 + 文本频道中的控制消息。机器人在文本频道中发布+固定控制链接。
{"cmd": "channel_leave"}
# 将机器人移回频道(仅限 Discord)——它可以通过 `channel_leave` 的链接或直接被命令重新邀请。

heard.jsonl 中每条记录的样子:

{"speaker": "Alex", "text": "演示者,第三张幻灯片上的数字呢?", "slide": 3, "ts": 1700000000}

协议非常简单: 关于内容的问题→解释(say)。控制问题→例如将幻灯片切换到显示相关数据的页面(goto)。调整措辞→对此做出承诺,然后 say。不要试图通过机器人编写错误的幻灯片来扮演齐格弗里德和罗伊——如果用户想说“我现在会绕过定价幻灯片”,可以,但在编写期间提出,如果这是现场问题,请指出你将跳过它。

最重要的事情(不要搞错): 机器人只能做你告诉它做的事情。如果有人说“演示者,你能跳过第三张幻灯片吗?”:先认识到它目前位于幻灯片 3,然后调用 goto 到幻灯片 4。如果你试图用新的 deck.json 重新加载——在运行时不可能做到,你不会更新显示的内容,演示文稿会变得不同步。唯一的控制方法是 commands.jsonl。 没有其他后门。

演示选项参数

python scripts/present.py <args>

参数默认值描述
--deck <path>必需演示文稿 JSON 文件的路径,或 decks/ 目录中的一个目录名,或 RawShow / RawGenerate
--name "..."配置中的 name机器人在会议中使用的显示名称
--voice "..."配置中的 voiceTTS 语音(请参阅语音文档)
--local无在本地浏览器中运行(无会议)
--avatar-mode无仅使用摄像头图块——无屏幕共享;演示文稿显示在相机图块上
--auto无立即开始演示,无需等待“开始”
--pace <秒>按长度每张幻灯片之间的最小演示停留时间(覆盖基于笔记的长度)
--unattended无语音控制关闭——仅通过控制页面驱动
`--mode showgenerate`auto

配置

~/.agentcall/config.json:

{
  "api_key": "...",
  "name": "演示者",
  "voice": "默认"
}

故障排除

  • present.py 拒绝使用 needs_narration — 正确:你需要编写 notes。打开 decks/<name>/source.json 并填充 deck.json。请勿尝试通过 --mode show 或修改标志来绕过。
  • 共享屏幕卡在“等待中” — 重新加入;会议平台偶尔会延迟处理屏幕共享。
  • 仅限 Discord:bot 命令失败 — 检查机器人的频道权限(需要 发送消息、嵌入链接、固定消息、查看频道、连接、说话、视频)。channel_leave 之后通过文本频道中的控制链接重新邀请机器人,或使用发送到该频道的直接命令。
  • 语音未播放 — 检查会议音频设置;机器人加入时是否已静音。(在 Discord 上,机器人有独立的聊天/语音状态。)
  • 页面处于空闲状态一段时间后断开连接 — 暂停/关闭电脑片刻后恢复。如果恢复后未收到消息,请重新加载控制页面或重新开始演示。
  • Control page: Link not clickable in chat — Print the console line (▸ Controls page: …) directly to the user; Meet chats are unreliable.
  • doc_to_deck.py 需要 LibreOffice(适用于 docx/doc 格式和旧版 ppt)—— brew install --cask libreoffice / apt install libreoffice / 下载。

库 / 依赖项

agentcall-sdk[voice]>=1.0.0
Pillow>=10.0.0
python-pptx>=1.0.0
requests>=2.31.0

(在 pip install -r requirements.txt 中全部列出。)

相关技能