instagram-skill

Instagram CLI — Agent 使用指南

Instagram CLI（instagram-cli）是 Instagram 的终端客户端。对于 Agent，它提供单轮命令，将内容打印到标准输出后退出，非常适合用于脚本编写和工具调用。

所有单轮命令都要求用户已登录（instagram-cli auth login）。 如果命令返回身份验证错误，请先提示用户登录。请勿自行尝试使用 CLI 登录。

---

线程解析

所有针对线程的命令都接受一个 <thread> 参数，并按以下顺序解析：

1. 线程 ID（20 位以上的数字，例如 340282366920938463...）——直接使用，不会产生额外的 API 调用
2. 用户名——准确的 Instagram 用户名（例如 johndoe）
3. 线程标题——在收件箱中进行模糊搜索（例如 "Book Club"）

**多步工作流的最佳实践：**首先调用 inbox --output json 获取线程 ID， 然后将这些 ID 直接传给后续命令。这样可以避免重复的搜索 API 调用， 而且比按用户名或标题匹配更可靠。

---

JSON 输出

所有命令都接受 -o json / --output json。响应遵循以下封装格式：

{ "ok": true, "data": { ... } }
{ "ok": false, "error": "message" }

需要以编程方式解析结果时，始终使用 --output json。

---

命令

列出收件箱

instagram-cli inbox [--limit <n>] [--output json]

返回最近的线程。每个线程包含：id、title、users、lastMessage、lastActivity、unread。

# Get 10 most recent threads as JSON
instagram-cli inbox --limit 10 --output json

搜索线程

instagram-cli inbox --search <query> [--limit <n>] [--output json]

按用户名和线程标题搜索，并根据相关性得分合并结果。

instagram-cli inbox --search "alice" --output json

发送消息

instagram-cli send <thread> --text <message> [--output json]
instagram-cli send <thread> --file <path> [--type photo|video] [--output json]

<thread> 可以是线程 ID、用户名或标题。--text 和 --file 不能同时使用。 媒体类型会根据扩展名自动检测；使用 --type 可覆盖检测结果。

instagram-cli send johndoe --text "Hey, are you free tonight?"
instagram-cli send 340282366920938463123456789 --text "Got it!"
instagram-cli send "Book Club" --file ./photo.jpg --output json

读取消息

instagram-cli read <thread> [--limit <n>] [--cursor <cursor>] [--mark-seen] [--output json]

按从新到旧的顺序返回消息。使用上一条响应中的 cursor 翻页获取更早的消息。 传入 --mark-seen 可在获取消息后将线程标记为已读。

instagram-cli read johndoe --limit 20 --output json
instagram-cli read 340282366920938463123456789 --mark-seen

JSON 输出中的每条消息都包含：id、itemType、text、userId、username、timestamp、isOutgoing。

下载消息中的媒体

instagram-cli read <thread> --message-id <id> --download <path> [--output json]

按 ID 查找消息（最多翻页 --max-pages 次，默认为 10），并保存媒体文件。 如果未提供文件扩展名，系统会自动推断。

instagram-cli read johndoe --message-id 340282366... --download ./media

回复消息

instagram-cli reply <thread> --message-id <id> --text <text> [--output json]

针对特定消息发送线程回复。

instagram-cli reply johndoe --message-id 340282366... --text "Totally agree!"

撤回消息

instagram-cli unsend <thread> --message-id <id> [--output json]

instagram-cli unsend johndoe --message-id 340282366...

---

多账户支持

所有命令都接受 -u <username> / --username <username>，以指定已登录的账户。 省略该参数时，将使用通过 instagram-cli auth switch 设置的默认账户。

instagram-cli inbox -u myworkaccount --output json
instagram-cli send johndoe --text "Hi" -u mypersonalaccount

---

典型 Agent 工作流

# 1. Get inbox to find the right thread
INBOX=$(instagram-cli inbox --output json --limit 20)
# Parse "id" fields from INBOX to find the target thread

# 2. Read recent messages (use thread ID for speed)
THREAD_ID="340282366920938463..."
instagram-cli read "$THREAD_ID" --limit 10 --output json

# 3. Reply or send
instagram-cli send "$THREAD_ID" --text "On my way!" --output json

# 4. Mark as seen
instagram-cli read "$THREAD_ID" --mark-seen

---

错误处理

• 身份验证错误 → 用户需要运行 instagram-cli auth login
• “No thread found matching” → 无法解析该用户名或标题；请先尝试 inbox --search
• JSON 输出中的 "ok": false → error 字段包含原因
• 速率限制／网络错误会以错误消息显示；如有需要，请采用退避策略重试