instagram-skill

用途

Instagram CLI 是 Instagram 的终端客户端，智能体可借助它代表用户从命令行与 Instagram 交互。它暴露的是“单次执行”命令：打印结果到标准输出后即退出，适合脚本编写和工具调用场景。

列出收件箱：instagram-cli inbox [--limit <n>] [--output json]，返回最近会话，每项包含 id、title、users、lastMessage、lastActivity、unread。
搜索会话：instagram-cli inbox --search <query> [--limit <n>] [--output json]，按用户名和会话标题搜索并按相关度合并结果。
发送消息：instagram-cli send <thread> --text <message> 或 --file <path> [--type photo|video]。--text 与 --file 互斥；媒体类型默认从扩展名推断，可用 --type 覆盖。
读取消息：instagram-cli read <thread> [--limit <n>] [--cursor <cursor>] [--mark-seen]，返回按最新优先排序的消息，可用上次响应的 cursor 分页读取更早消息，--mark-seen 在获取后标记会话已读。JSON 中每条消息含 id、itemType、text、userId、username、timestamp、isOutgoing。
下载消息媒体：instagram-cli read <thread> --message-id <id> --download <path>，按 ID 查找消息（分页至多 --max-pages，默认 10）并保存媒体，未提供扩展名时自动推断。
回复消息：instagram-cli reply <thread> --message-id <id> --text <text>。
撤回消息：instagram-cli unsend <thread> --message-id <id>。
多账号：所有命令支持 -u <username> / --username <username> 指定已登录账号；省略则使用通过 instagram-cli auth switch 设置的默认账号。

前置条件：所有单次命令要求用户已登录（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。

获取收件箱找到目标会话：INBOX=$(instagram-cli inbox --output json --limit 20)，解析其中的 id 字段定位目标线程。
读取最近消息（用线程 ID 更快）：THREAD_ID="340282366920938463..."，instagram-cli read "$THREAD_ID" --limit 10 --output json。
回复或发送：instagram-cli send "$THREAD_ID" --text "On my way!" --output json。
标记已读：instagram-cli read "$THREAD_ID" --mark-seen。

适合需要从命令行或由智能体自动完成 Instagram 私信读写、搜索、媒体下载、回复、撤回和多账号切换的操作，尤其是多步自动化流程和需要解析结构化结果的脚本场景。