1. 项目概述一个为开发者与AI智能体打造的Otter.ai命令行工具如果你和我一样每天要处理大量的会议录音和转录文本那么Otter.ai这个工具你一定不陌生。它确实是个会议记录的神器能自动识别不同说话人生成带时间戳的文本。但痛点也随之而来当我想批量导出上周所有站会的记录或者想用脚本自动分析会议中的“行动项”时面对Otter的网页界面只能一次次手动点击、下载效率极低。更别提想让我正在用的AI编程助手比如Claude Code或Cursor直接去读取和分析这些会议记录了几乎不可能。这就是otterai-cli诞生的背景。它不是一个官方产品而是一个由社区开发者构建的开源命令行工具核心目标就一个把Otter.ai的数据和能力变成一行行可编程、可脚本化、可被AI智能体直接调用的命令。简单来说它为你和你的AI助手在本地终端和Otter.ai的云端数据之间架起了一座高效、自动化的桥梁。这个工具非常适合以下几类人追求效率的开发者希望通过脚本自动化处理会议记录比如每日自动归档、关键词提取、生成会议纪要。AI智能体Agent的重度用户希望让你使用的Claude、Cursor、GPTs等AI助手能够直接访问、查询、总结你的会议历史构建更强大的个人知识库和工作流。有批量处理需求的知识工作者需要定期备份所有会议转录或将其转换为特定格式如Markdown以便纳入笔记系统。喜欢折腾命令行和自动化流程的极客享受用管道pipe将不同工具串联起来打造个性化工作流的乐趣。接下来我将带你从零开始深入拆解这个工具的设计思路、核心功能、实战用法并分享我在集成和使用过程中踩过的坑和总结的技巧。2. 核心设计思路为什么是CLI以及如何服务AI智能体2.1 从API到CLI封装与易用性的平衡otterai-cli并非凭空造轮子其底层依赖于另一个开源库gmchad/otterai-api这个库完成了与Otter.ai私有API通信的重任。那么为什么还需要这个CLI层呢这涉及到工具链中常见的分层设计思想。底层API库提供了最基础的函数调用比如list_speeches(),get_transcript()。这对于在Python脚本中调用非常合适但它要求使用者必须具备一定的编程能力并且需要自己处理认证、错误、参数解析等“脏活累活”。而CLI命令行界面的价值在于它将这些复杂的功能封装成一个个直观的命令比如otter speeches list使得任何会使用终端的人都能立即上手无需编写一行代码。更重要的是CLI是脚本化和自动化的天然接口。在Unix哲学中一个优秀的CLI工具应该做到“只做一件事并做好”同时其输出应该易于被其他程序如grep,jq,awk解析。otterai-cli深谙此道其--json输出选项就是为了让它的执行结果能无缝嵌入到Shell脚本或更复杂的数据流水线中。2.2 为AI智能体而生结构化输出与技能Skill集成这是otterai-cli最前瞻性的设计。传统的CLI工具服务于人类而它明确将“AI智能体”列为目标用户。这带来了两个关键设计决策第一一切皆可JSON。对于AI来说解析自然语言文本如表格、列表是困难且容易出错的但解析结构化的JSON数据却是其强项。几乎所有的list和get命令都支持--json标志返回机器可读的数据结构。例如AI智能体可以轻松地执行otter speeches list --days 7 --json然后从返回的JSON数组中提取出otid会议的唯一标识符再进行下一步操作。第二原生支持Agent Skill。项目内置了一个skills/otterai-cli/目录里面包含了一个符合 Agent Skill 规范的文件。这个文件就像一个“使用说明书”当被复制到兼容的AI智能体如Claude Code、Cursor的技能目录后智能体就能自动“学会”如何使用otter命令。这意味着你不需要在每次对话中反复教AI“如何列出会议”它已经内置了这个能力可以直接调用。这极大地提升了人机协作的流畅度。注意这种设计思路代表了工具开发的一个新趋势工具不仅要为人服务还要为人的“数字延伸”——AI智能体服务降低它们使用复杂服务的门槛。2.3 安全与凭证管理Keychain优先策略处理云端服务的认证是CLI工具的关键一环。otterai-cli采用了多层次、安全的凭证管理策略优先级从高到低如下环境变量(OTTERAI_USERNAME,OTTERAI_PASSWORD): 最高优先级适用于CI/CD流水线、Docker容器或临时会话避免在脚本中硬编码密码。操作系统密钥链(macOS Keychain, Windows Credential Locker): 通过Python的keyring库实现。执行otter login后凭证会被安全地存储在这里。这是对个人用户最推荐的方式既安全又无需每次输入。本地配置文件(~/.otterai/config.json): 作为密钥链的降级备选方案。如果系统不支持密钥链凭证会以明文形式存储在这里。出于安全考虑应尽量避免依赖此方式。这种设计既保证了交互式使用的便捷性一次登录长期有效也满足了自动化场景的需求通过环境变量注入同时充分利用了操作系统的安全设施来保护敏感信息。3. 从安装到实战手把手配置与核心命令详解3.1 环境准备与安装推荐使用现代Python工具链项目要求Python 3.10。我强烈建议使用uv这个新兴的、速度极快的Python包管理器和安装器来安装它这能避免很多因环境冲突导致的问题。# 安装 uv (如果尚未安装) curl -LsSf https://astral.sh/uv/install.sh | sh # 使用 uv 全局安装 otterai-cli uv tool install otterai-cli安装完成后otter命令就会出现在你的系统路径中。你可以通过otter --help验证安装是否成功。实操心得相比于传统的pip install otterai-cliuv tool install会将工具安装在一个独立、隔离的环境中完全不会干扰你项目本地的Python依赖。这对于管理多个CLI工具来说非常清爽。更新工具也只需uv tool upgrade otterai-cli。3.2 首次登录与认证配置安装后第一步是登录。在终端中直接运行otter login这会打开一个交互式提示让你输入Otter.ai的账号和密码。成功后凭证会按上文所述策略保存。你可以通过以下命令管理认证状态otter user # 查看当前认证的用户 otter logout # 登出并清除本地保存的凭证对于自动化场景请在运行命令前设置环境变量export OTTERAI_USERNAMEyour_emailexample.com export OTTERAI_PASSWORDyour_password # 之后运行任何 otter 命令都将自动使用这些凭证无需交互3.3 核心命令全解析像管理本地文件一样管理会议otterai-cli的命令结构非常清晰围绕speeches会议记录、speakers讲话人、folders文件夹这几个核心资源展开。3.3.1 会议Speeches管理你的数据入口列出会议 (list)这是最常用的命令用于探索和定位目标会议。# 基础列表显示最近的会议 otter speeches list # 列出过去7天内的会议 otter speeches list --days 7 # 仅列出“Work”文件夹下的会议 otter speeches list --folder Work # 以JSON格式输出便于脚本处理 otter speeches list --json关键参数解析--days N: 过滤N天内的记录。注意Otter.ai API可能对免费账户有访问时间范围限制如果设置过大可能返回空。--folder NAME/ID: 按文件夹筛选。名称匹配是模糊的建议先otter folders list确认准确名称。--source owned|shared: 筛选自己创建的或他人共享的会议。--json: 输出结构化JSON这是与AI智能体或脚本交互的关键。获取会议详情与全文 (get)获取单个会议的元数据和完整的、分段的转录文本。otter speeches get jqb7OHo6mrHtCuMkyLN0nUS8mxY otter speeches get jqb7OHo6mrHtCuMkyLN0nUS8mxY --json # JSON格式包含transcripts数组重要概念Speech ID (otid vs speech_id) Otter.ai内部有两套ID系统这是最容易混淆的地方。speech_id: 形如22WB27HAEBEJYFCA在网页版URL或界面中常见。但API不接受这个IDotid: 形如jqb7OHo6mrHtCuMkyLN0nUS8mxY是Otter.ai GraphQL API使用的唯一标识符。所有otter命令中需要的SPEECH_ID参数指的都是otid。务必使用otter speeches list列出的otid字段。下载会议内容 (download)这是核心的导出功能支持多种格式。# 下载为纯文本 (.txt) otter speeches download jqb7OHo6mrHtCuMkyLN0nUS8mxY --format txt # 下载为PDF (.pdf) otter speeches download jqb7OHo6mrHtCuMkyLN0nUS8mxY --format pdf # 下载为Markdown (.md) - 强烈推荐用于笔记集成 otter speeches download jqb7OHo6mrHtCuMkyLN0nUS8mxY --format md --output my_meeting_notes # 下载原始音频 (.mp3) otter speeches download jqb7OHo6mrHtCuMkyLN0nUS8mxY --format mp3格式选择建议txt: 最通用适合后续用grep、awk进行文本处理。md: 最佳可读性和可编辑性自带YAML Frontmatter元数据能无缝导入Obsidian、Logseq等双链笔记软件。srt: 字幕文件格式可用于视频剪辑。mp3: 获取原始录音用于存档或二次分析。3.3.2 Markdown导出的高级定制Frontmatter配置Markdown导出是otterai-cli的一大亮点因为它生成了对知识管理极其友好的格式。# 使用默认Frontmatter字段包含标题、摘要、讲话人、时间等 otter speeches download $OTID --format md # 自定义Frontmatter字段和顺序 otter speeches download $OTID --format md --frontmatter-fields title,speech_id,summary,created_at # 完全禁用Frontmatter otter speeches download $OTID --format md --frontmatter-fields none默认生成的Markdown文件头部是这样的YAML块这为后续的检索和关联提供了丰富的元数据--- title: Weekly Standup summary: Discussed sprint progress and blockers... speakers: [Alice, Bob] start_time: 2025-02-20T10:00:00Z end_time: 2025-02-20T10:30:00Z duration_seconds: 1800 source: owned speech_id: 22WB27HAEBEJYFCA folder: Work folder_id: 12345 --- **Alice (00:00):** Lets go over the sprint updates. **Bob (00:05):** I finished the login module...3.3.3 搜索与内容管理在会议内搜索 (search)无需打开网页直接在终端里搜索某次会议的转录内容。otter speeches search action items jqb7OHo6mrHtCuMkyLN0nUS8mxY这个命令会返回所有包含“action items”的对话片段显示说话人和文本对于快速定位讨论要点非常有用。管理会议 (rename,move,trash)# 重命名会议 otter speeches rename jqb7OHo6mrHtCuMkyLN0nUS8mxY Project Kickoff - Revised Title # 将会议移动到“Archive”文件夹文件夹不存在时会报错 otter speeches move jqb7OHo6mrHtCuMkyLN0nUS8mxY --folder Archive # 移动会议到新文件夹如果文件夹不存在则自动创建 otter speeches move jqb7OHo6mrHtCuMkyLN0nUS8mxY --folder Q1 Reviews --create # 将会议移至垃圾箱 otter speeches trash jqb7OHo6mrHtCuMkyLN0nUS8mxY3.3.4 讲话人与文件夹管理这些命令帮助你整理和标准化你的Otter.ai资料库。# 列出所有识别出的讲话人 otter speakers list # 创建一个新的讲话人标签用于后续手动标注 otter speakers create New Contractor # 列出所有文件夹 otter folders list # 创建一个新文件夹 otter folders create Client Meetings4. 自动化与AI智能体集成实战4.1 Shell脚本自动化批量导出与定期备份CLI的威力在于可以嵌入Shell脚本实现复杂的自动化流程。下面是一个实战脚本示例用于每周一自动备份上一周所有“Standup”会议的Markdown笔记到指定目录并按日期归档。#!/bin/bash # 文件名backup_weekly_standups.sh # 描述备份上周所有标题包含“standup”的会议记录为Markdown BACKUP_DIR$HOME/Documents/MeetingBackups/$(date %Y-%m-%d) mkdir -p $BACKUP_DIR # 使用JSON输出配合jq过滤出上周的、标题含standup的会议otid otter speeches list --days 7 --json | \ jq -r .speeches[] | select(.title | test(standup; i)) | .otid | \ while read -r otid; do # 从会议详情中获取更安全的文件名移除特殊字符 safe_title$(otter speeches get $otid --json | jq -r .speech.title | gsub([^a-zA-Z0-9]; _)) output_file${BACKUP_DIR}/${safe_title}.md echo 备份会议: $otid 到 $output_file otter speeches download $otid --format md --output $output_file # 避免请求过快触发速率限制 sleep 1 done echo 备份完成文件保存在: $BACKUP_DIR你可以使用cron或launchd等工具将这个脚本设置为定时任务实现完全无人值守的会议记录备份。4.2 为AI智能体赋能打造你的会议知识库助手这是otterai-cli最激动人心的应用场景。假设你正在使用一个支持Agent Skill的AI编程助手如Cursor你可以通过以下步骤让它获得访问你会议记录的超能力。第一步安装技能找到你的AI助手存放技能的目录例如Cursor通常在其配置目录下有一个skills文件夹将otterai-cli项目中的skills/otterai-cli/整个文件夹复制进去。重启你的AI助手。第二步配置环境变量为了让AI助手在后台调用otter命令时能通过认证你需要在启动AI助手的环境比如终端中预先设置好凭证。export OTTERAI_USERNAMEyour_email export OTTERAI_PASSWORDyour_password # 然后在这个终端里启动你的AI助手如 cursor .第三步与AI助手对话现在你可以直接向AI助手发出自然语言指令它会自动调用otterai-cli技能来执行。例如你“帮我找出上周所有提到‘技术债’的会议并把相关片段总结一下。”AI助手内部思考调用otter speeches list --days 7 --json获取会议列表。遍历列表对每个会议调用otter speeches search “技术债” $OTID。收集所有搜索结果进行归纳总结然后输出给你。一个更具体的AI工作流示例你想让AI帮你从昨天的产品评审会中提取行动项Action Items。# AI智能体可以在后台执行类似这样的逻辑 # 1. 找到最新的产品评审会议 OTID$(otter speeches list --days 2 --json | jq -r .speeches[] | select(.title | test(产品评审; i)) | .otid | head -1) # 2. 获取完整的转录文本JSON格式 TRANSCRIPT_JSON$(otter speeches get $OTID --json) # 3. 将JSON文本和你的指令“提取行动项”一起送入LLM进行分析 # 这部分取决于AI智能体自身的实现 echo $TRANSCRIPT_JSON | your_llm_processing_tool --prompt 请从以上会议记录中提取所有行动项按负责人分类列出。通过这种方式你的AI助手不再是一个与世隔绝的语言模型而是变成了一个能够主动查询、分析你个人工作记忆会议记录的智能伙伴。4.3 构建会议分析流水线你可以将otterai-cli作为数据提取器与其他命令行工具结合构建强大的文本分析流水线。示例统计每周会议高频词# 导出上周所有会议为文本合并后使用常见文本分析工具如tr, sort, uniq统计词频 otter speeches list --days 7 --json | jq -r .speeches[].otid | while read otid; do otter speeches download $otid --format txt --output /tmp/transcript_$$.txt 2/dev/null cat /tmp/transcript_$$.txt done | tr [:upper:] [:lower:] | tr -cs [:alnum:] \n | sort | uniq -c | sort -nr | head -20这个流水线会输出过去一周你所有会议中出现频率最高的20个单词帮助你快速了解讨论焦点。5. 常见问题、故障排查与进阶技巧5.1 安装与认证问题Q1: 使用uv tool install安装后运行otter命令提示“command not found”。A1: 这通常是因为uv的全局工具安装路径没有添加到系统的PATH环境变量中。uv通常会将工具安装在~/.local/binLinux/macOS或%USERPROFILE%\.local\binWindows。请检查该路径是否已在你的PATH中。你可以通过uv tool list查看已安装工具的位置或直接使用uvx --from otterai-cli otter来临时运行。Q2: 执行otter login成功但运行其他命令时仍报“Authentication required”。A2: 按以下步骤排查检查当前用户运行otter user确认显示的是你登录的邮箱。检查凭证存储如果你使用了密钥链可以尝试登出再登入otter logout otter login。在某些Linux发行版上密钥环服务如gnome-keyring可能没有启动。会话过期Otter.ai的会话可能过期。尝试重新登录。环境变量冲突如果你设置了OTTERAI_USERNAME和OTTERAI_PASSWORD环境变量CLI会优先使用它们。请确保这些变量的值是正确且未过期的。5.2 命令执行与API错误Q3: 运行otter speeches list返回空列表或错误但我确定账户里有会议。A3:参数过滤过严检查--days参数是否设置得太小或者--folder参数指定的文件夹名称是否准确大小写敏感。API限制Otter.ai的非官方API可能存在未公开的限制例如对免费账户只能访问最近一定数量的会议或一定时间范围的数据。尝试不使用任何过滤参数otter speeches list看看。网络问题确保你的网络可以正常访问Otter.ai服务。Q4: 下载音频mp3或PDF时失败但下载txt正常。A4: 某些格式如mp3, pdf的生成和下载可能依赖于Otter.ai服务器的额外处理或者对你的账户类型免费版/付费版有所限制。请确认在Otter.ai网页版上相同的会议是否能成功导出这些格式。查看命令行返回的具体错误信息。如果提示“格式不支持”或“处理中”可能是该会议尚未完成对应格式的生成。Q5: 错误提示Rate limit exceeded。A5: 你发送的API请求太快触发了Otter.ai服务器的速率限制。解决方案增加延迟在脚本的循环命令之间加入sleep命令如sleep 2暂停2秒。减少请求优化你的脚本避免不必要的API调用。例如批量操作时先获取所有ID再集中处理。5.3 使用技巧与最佳实践技巧1始终使用--json进行脚本编程当你需要将otter命令的输出传递给其他工具如jq进行解析时务必使用--json标志。文本表格输出虽然对人友好但对程序解析极不友好。jq工具是你的强大盟友可以轻松地过滤、映射和提取JSON数据。技巧2妥善管理你的otid由于otid是长字符串在脚本中直接硬编码容易出错。建议使用变量存储或通过jq查询动态获取。# 不好的做法 otter speeches download jqb7OHo6mrHtCuMkyLN0nUS8mxY --format md # 好的做法通过标题查找ID OTID$(otter speeches list --json | jq -r .speeches[] | select(.titleWeekly Standup 2023-10-26) | .otid) otter speeches download $OTID --format md技巧3利用Markdown Frontmatter构建知识图谱将会议导出为带Frontmatter的Markdown后你可以将其导入到像Obsidian这样的笔记软件中。利用Frontmatter中的speakers、folder、date等字段你可以轻松创建数据库视图、链接相关会议和人物从而将零散的会议记录变成结构化的个人或团队知识库。技巧4为AI智能体创建安全的凭证环境不建议将明文密码写入长期保存的脚本。对于AI智能体更好的方式是在启动AI前在一个独立的、受控的Shell会话中设置环境变量。或者探索使用操作系统密钥链的编程接口但这种方式更复杂。最安全且简单的方式仍然是让AI助手运行在已通过otter login完成交互式认证的终端环境中。技巧5组合使用发挥管道威力Unix哲学强调“组合小程序”。otterai-cli完美契合这一点。你可以将其与find、grep、sed、pandoc文档转换等无数工具结合。例如将一周的会议记录导出为Markdown然后用pandoc合并成一个PDF周报整个过程完全自动化。