名称： plaud-api
描述： 用于访问 Plaud 录音笔数据（录音、转录文本、AI 摘要）——指导凭证设置并提供 plaud_client.py 的使用模式
aliases:
- plaud
- plaud-recordings

Plaud API 技能

访问 Plaud 录音笔数据，包括录音文件、转录文本和 AI 生成的摘要。

概述

Plaud API 提供对以下内容的访问：
- 音频文件：来自 Plaud 设备的 MP3 录音
- 转录文本：包含说话人分离的完整文字转录
- AI 摘要：自动生成的笔记和摘要

核心原则：使用 plaud_client.py（本技能包已包含），而非直接调用原始 API。该客户端负责处理身份验证、错误处理和响应解析。

何时使用本技能

在以下情况使用本技能：
- 用户提及 "Plaud"、"Plaud 录音" 或 "来自 Plaud 的转录"
- 需要访问录音笔数据
- 处理来自 Plaud 设备的录音、转录文本或 AI 笔记时

交互式凭证设置教程

使用 Plaud API 前，您需要从网页应用中提取凭证。

步骤 1：访问 Plaud 网页应用

在 Chrome 中打开：https://web.plaud.ai

如果尚未登录，请使用您的 Plaud 账户登录。

步骤 2：打开 Chrome 开发者工具

按 F12（Mac 上按 Cmd+Option+I）打开开发者工具。

步骤 3：查找 localStorage 值

1. 在开发者工具中点击 Application 标签页
2. 在左侧边栏中，展开 Local Storage
3. 点击 https://web.plaud.ai

步骤 4：复制所需值

找到并复制以下两个值：

步骤 5：创建 .env 文件

在技能目录中创建或更新 .env 文件（~/.claude/skills/plaud-api/）：

# 进入技能目录
cd ~/.claude/skills/plaud-api
cp .env.example .env
# 使用您的实际凭证编辑 .env 文件

或直接创建：

cat > ~/.claude/skills/plaud-api/.env << 'EOF'
PLAUD_TOKEN=bearer eyJ...your_full_token_here...
PLAUD_API_DOMAIN=https://api-euc1.plaud.ai
EOF

重要：包含完整的令牌，包括 "bearer " 前缀。

步骤 6：验证设置

测试凭证是否有效：

cd ~/.claude/skills/plaud-api
python3 plaud_client.py list

如果成功，您将看到录音文件列表，包含文件 ID、时长和名称。

首次设置：如果需要，请安装依赖项：

pip install -r ~/.claude/skills/plaud-api/requirements.txt

.env 文件格式

PLAUD_TOKEN=bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
PLAUD_API_DOMAIN=https://api-euc1.plaud.ai

注意：
- 令牌包含 "bearer " 前缀
- API 域名是区域特定的（欧盟用户：api-euc1，美国用户可能不同）

快速参考

所有命令都应在技能目录中运行（~/.claude/skills/plaud-api）：

常用模式

获取最近的转录文本

cd ~/.claude/skills/plaud-api

# 列出文件以查找 ID
python3 plaud_client.py list

# 获取特定文件的转录文本
python3 plaud_client.py details <file_id> --json | jq '.data.trans_result'

文件 ID 查找

文件 ID 是 32 位十六进制字符串。可以从以下位置找到：
1. URL：https://web.plaud.ai/file/{file_id}
2. 列表输出：python3 plaud_client.py list 的第一列
3. JSON 输出：python3 plaud_client.py list --json | jq '.[].id'

获取 AI 摘要

python3 plaud_client.py details <file_id> --json | jq '.data.ai_content'

批量操作

# 将所有录音下载到一个文件夹
python3 plaud_client.py download-all -o ./all_recordings

# 获取所有文件 ID
python3 plaud_client.py list --json | jq -r '.[].id'

仅提取转录文本

# 获取纯文本转录（所有片段连接）
python3 plaud_client.py details <file_id> --json | jq -r '.data.trans_result.segments[].text' | tr '\n' ' '

错误处理

令牌刷新

Plaud 令牌有效期较长（约 10 个月），但过期时：

1. 登录 https://web.plaud.ai
2. 打开开发者工具 > Application > Local Storage
3. 复制新的 tokenstr 值
4. 更新您的 .env 文件

API 参考

详细的 API 文档，请参阅本技能目录中包含的 PLAUD_API.md。

plaud_client.py 使用的关键端点：
- GET /file/simple/web - 列出所有文件
- GET /file/detail/{file_id} - 获取包含转录的文件详情
- GET /file/download/{file_id} - 下载 MP3 音频
- GET /filetag/ - 获取文件标签/文件夹

包含的文件