agent-instagram

Agent Instagram

面向 AI Agent 的 Instagram 私信命令行工具。支持浏览器 Cookie 提取（零配置，可从 Chromium 浏览器提取）和用户名/密码身份验证（支持 2FA）。使用 Instagram 的私有移动端 API 读取和发送私信。

使用以下任一入口点：

• 全局安装：agent-instagram ...
• 单次执行：bunx --package agent-messenger agent-instagram ...

核心概念

• Thread ID = Instagram 为私信对话分配的标识符。由 chat list 返回的数字字符串。
• 浏览器 Cookie 提取 = 推荐的身份验证方式。从已登录 instagram.com 的 Chromium 浏览器（Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium）提取 Cookie。零配置。
• 用户名/密码身份验证 = 备用方式。使用 Instagram 凭据进行身份验证。支持通过 SMS 或身份验证器应用进行双重身份验证。
• 基于 HTTP = 每条命令行命令都会发送 HTTP 请求并返回。不会保持持久连接，也不会运行后台进程。SDK 还提供实时监听器（InstagramHybridListener、InstagramRealtimeListener），可流式接收私信 — 见下文的SDK：实时事件。
• 多账号 = 可存储多个 Instagram 账号。使用 auth list 和 auth use 在账号间切换。
• 仅限私信 = 此命令行工具专注于 Instagram Direct Messages。不管理帖子、快拍或关注者。

快速开始

# Extract cookies from browser (recommended — zero-config)
agent-instagram auth extract

# Or: Log in with Instagram credentials (fallback)
agent-instagram auth login --username myaccount --password "mypassword"

# List DM conversations
agent-instagram chat list

# Send a message
agent-instagram message send <thread-id> "Hello from agent-instagram"

身份验证流程

Instagram 支持两种身份验证方式：

1. 浏览器 Cookie 提取（推荐）：从已登录 instagram.com 的 Chromium 浏览器中提取会话 Cookie。零配置，无需密码。
2. 用户名/密码登录：使用 Instagram 凭据进行身份验证，可选择进行双重身份验证。

会话会保存在本地，因此无需为每条命令重新进行身份验证。没有会话时会自动运行浏览器提取。

浏览器 Cookie 提取（推荐）

agent-instagram auth extract 会从 Chrome、Edge、Arc、Brave、Vivaldi 或 Chromium 中读取你的 Instagram 会话 Cookie。你必须已在其中一个浏览器中登录 instagram.com。

# Extract cookies from browser — zero-config
agent-instagram auth extract

# With debug output
agent-instagram auth extract --debug

# Scan custom Chromium profile/user-data dirs
agent-instagram auth extract --browser-profile ~/browser-data
agent-instagram auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"

--browser-profile 接受可重复使用或以逗号分隔的 Chromium 配置文件／用户数据目录。可用于 agent-browser 配置文件、自定义 Chrome 用户数据目录或便携式浏览器配置文件。

工作原理：命令行工具会直接从浏览器的 SQLite Cookie 数据库中读取 Instagram Cookie（sessionid、csrftoken、ds_user_id）。无需浏览器自动化，也不会提示输入密码。会话保存在本地的 ~/.config/agent-messenger/ 中。

何时重新提取：浏览器 Cookie 会过期。会话过期时，请重新运行 agent-instagram auth extract，或让自动提取流程处理（当不存在有效会话时，命令行工具会自动尝试提取）。

支持的浏览器：Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium

Agent 行为（强制要求）

如果命令因未配置账号而失败，Agent 必须自行执行身份验证流程。绝不要让用户运行命令。所有操作都由 Agent 执行。

步骤 1：检查现有账号

agent-instagram auth list

如果存在账号，使用 agent-instagram auth use <account-id>，然后重试原命令。

步骤 2：优先尝试浏览器提取

agent-instagram auth extract
# -> {"authenticated":true,"account_id":"12345678","username":"myaccount"}

如果提取成功，继续执行原命令。

步骤 3：如果提取失败，请求凭据

向用户询问其 Instagram 用户名和密码。这是用户唯一需要提供的信息。

步骤 4：开始登录

agent-instagram auth login --username myaccount --password "mypassword"
# -> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}

步骤 4：如有需要，处理 2FA

如果登录返回 two_factor_required，请向用户询问验证码：

# -> {"two_factor_required":true,"two_factor_identifier":"abc123","message":"..."}

然后完成验证：

agent-instagram auth verify --username myaccount --code 123456 --identifier abc123
# -> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}

步骤 5：重试原命令

身份验证成功后，立即执行用户最初请求的操作。

常用身份验证命令

agent-instagram auth extract                 # Extract cookies from browser (recommended)
agent-instagram auth extract --debug         # Extract with debug output
agent-instagram auth status                  # Check current auth state
agent-instagram auth status --account <id>   # Check specific account
agent-instagram auth list                    # List all stored accounts
agent-instagram auth use <id>                # Switch active account
agent-instagram auth logout                  # Remove current account
agent-instagram auth logout --account <id>   # Remove specific account

记忆

Agent 会维护 ~/.config/agent-messenger/MEMORY.md 文件，作为跨会话的持久记忆。该文件由 Agent 管理。CLI 不会读取或写入此文件。使用 Read 和 Write 工具来管理记忆文件。

读取记忆

在每项任务开始时，使用 Read 工具读取 ~/.config/agent-messenger/MEMORY.md，加载之前发现的会话 ID、联系人姓名和偏好。

• 如果文件尚不存在，也没关系。继续操作，并在首次有有用信息需要存储时创建文件。
• 如果无法读取文件（权限问题、目录不存在），则继续操作，不使用记忆。

写入记忆

发现有用信息后，使用 Write 工具更新 ~/.config/agent-messenger/MEMORY.md。以下情况需要写入：

• 发现会话 ID 和联系人姓名后（通过 chat list）
• 发现群聊名称和参与者后
• 用户告知你某个别名或偏好时（“把这个称为家庭群”“我的工作聊天是 X”）

写入时，请包含文件的完整内容。Write 工具会覆盖整个文件。

存储内容

• 带有联系人／群聊名称的会话 ID
• 你自己的用户名和用户 ID
• 用户指定的别名（“家庭群”“工作聊天”）
• 常用会话 ID
• 交互中表达的任何用户偏好

不应存储的内容

切勿存储身份验证凭据、密码、会话令牌或任何敏感数据。切勿存储完整消息内容（仅存储 ID 和聊天上下文）。

格式／示例

# Agent Messenger Memory

## Instagram Account

- Username: myaccount
- User ID: 12345678

## Conversations

- `340282366841710300949128138443434234567` - Alice (private)
- `340282366841710300949128138443434234568` - Bob (private)
- `340282366841710300949128138443434234569` - Project Team (group, 5 members)

## Aliases

- "alice" -> `340282366841710300949128138443434234567`
- "project" -> `340282366841710300949128138443434234569` (Project Team)

## Notes

- User prefers --pretty output

记忆可帮助你跳过重复的 chat list 调用。如果你已在之前的会话中获知会话 ID，请直接使用。

命令

身份验证命令

# Extract cookies from browser (recommended — zero-config)
agent-instagram auth extract
agent-instagram auth extract --debug

# Log in (interactive: prompts for username/password)
agent-instagram auth login

# Log in (non-interactive: pass credentials as flags)
agent-instagram auth login --username <username> --password <password>

# Log in with debug output (shows raw API responses)
agent-instagram auth login --username <username> --password <password> --debug

# Complete 2FA verification (non-interactive)
agent-instagram auth verify --username <username> --code <code> --identifier <identifier>

# Resolve a security challenge — send verification code
agent-instagram auth challenge --username <username> --method email
agent-instagram auth challenge --username <username> --method sms

# Resolve a security challenge — submit verification code
agent-instagram auth challenge --username <username> --code <code>

# Check auth status
agent-instagram auth status
agent-instagram auth status --account <id>

# List stored accounts
agent-instagram auth list

# Switch active account
agent-instagram auth use <id>

# Remove account
agent-instagram auth logout
agent-instagram auth logout --account <id>

Whoami 命令

# Show current authenticated user
agent-instagram whoami
agent-instagram whoami --pretty
agent-instagram whoami --account <account-id>

输出包含已通过身份验证的用户身份信息。

聊天命令

# List DM conversations (sorted by most recent activity)
agent-instagram chat list
agent-instagram chat list --limit 50
agent-instagram chat list --account <id>

# Search conversations by name
agent-instagram chat search "alice"
agent-instagram chat search "alice" --limit 10
agent-instagram chat search "alice" --account <id>

输出包含：

• id - 会话 ID
• name - 联系人或群聊名称
• type - private 或 group
• is_group - 布尔值
• participant_count - 参与者人数
• unread_count - 未读消息数
• last_message - 最近一条消息的预览

消息命令

# List messages in a conversation
agent-instagram message list <thread-id>
agent-instagram message list <thread-id> --limit 50
agent-instagram message list <thread-id> --limit 10 --account <id>

# Send a text message to a thread
agent-instagram message send <thread-id> <text>
agent-instagram message send <thread-id> "Hello!" --account <id>

# Send a text message to a user by @username
agent-instagram message send-to <username> <text>
agent-instagram message send-to @alice "Hello!"

# Search messages by text content
agent-instagram message search <query>
agent-instagram message search "meeting" --thread <thread-id>
agent-instagram message search "hello" --limit 10

# Search Instagram users by username
agent-instagram message search-users <query>
agent-instagram message search-users "alice"

输出格式

JSON（默认）

所有命令默认输出 JSON，供 AI 使用：

{
  "id": "340282366841710300949128138443434234567",
  "name": "Alice",
  "type": "private",
  "is_group": false,
  "participant_count": 2,
  "unread_count": 3,
  "last_message": {
    "id": "29876543210987654",
    "thread_id": "340282366841710300949128138443434234567",
    "from": "12345678",
    "timestamp": "2026-03-29T10:30:00.000Z",
    "is_outgoing": false,
    "type": "text",
    "text": "See you tomorrow!"
  }
}

Pretty（易读格式）

使用 --pretty 标志获取格式化输出：

agent-instagram chat list --pretty

全局选项

选项	说明
--pretty	输出易读格式，而不是 JSON
--account <id>	为此命令使用指定账户

常见用法

查看未读消息

# List conversations to see unread counts
agent-instagram chat list --limit 20

# Read messages from a specific conversation
agent-instagram message list <thread-id> --limit 10

向联系人发送消息

# Find the contact first
agent-instagram chat search "Alice"

# Send to the thread ID
agent-instagram message send <thread-id> "Hey, are we still on for tomorrow?"

在群聊中回复

# Find the group
agent-instagram chat search "Project Team"

# Send to the group thread
agent-instagram message send <thread-id> "Status update: deployment complete."

错误处理

所有命令都会返回统一的错误格式：

{
  "error": "Not authenticated. Run \"agent-instagram auth login --username <username>\" first."
}

常见错误：

• Not authenticated - 未配置账户。运行 auth extract 或 auth login。
• Session expired or missing - 会话已失效。运行 auth extract 从浏览器重新提取会话，或运行 auth login 重新登录。
• Login failed - 用户名或密码错误。请仔细检查凭据。
• Two-factor authentication failed - 两步验证代码错误。获取新代码，然后再次尝试运行 auth verify。
• Rate limited - 请求过多。请稍候再试。

备注

• 会话持久化：登录会话存储在 ~/.config/agent-messenger/instagram/ 中。如果 Instagram 检测到异常活动，会话可能会过期。
• 封禁风险：Instagram 会监控自动化行为。避免大量发送消息、快速连续发送或批量操作。发送多条消息时，请适当拉开命令间隔。
• 多账户：可同时存储多个 Instagram 账户。使用 auth list 查看所有账户，并使用 auth use <id> 切换。
• 仅支持文本：目前仅支持文本消息。媒体、语音消息和表情回应为只读（在消息列表中显示为类型标记）。
• agent-instagram 默认返回 JSON，使用 --pretty 可输出缩进格式。

故障排除

agent-instagram: command not found

agent-instagram 不是 npm 包名称。 npm 包名称是 agent-messenger。

如果已全局安装该包，可直接使用 agent-instagram：

agent-instagram chat list --pretty

如果尚未安装该包，请使用 --package 进行安装并运行：

npx -y --package agent-messenger agent-instagram chat list --pretty
bunx --package agent-messenger agent-instagram chat list --pretty
pnpm dlx --package agent-messenger agent-instagram chat list --pretty

切勿在未指定 --package agent-messenger 的情况下运行 npx agent-instagram、bunx agent-instagram 或 pnpm dlx agent-instagram。由于 agent-instagram 不是 npm 包名称，这些命令会失败或安装错误的包。

登录时出现 "challenge_required" 错误

Instagram 可能要求进行额外验证（例如，从 Instagram 应用确认你的身份）。请在手机上打开 Instagram 应用，完成所有安全验证，然后重试登录。

会话频繁过期

Instagram 会根据设备指纹和活动模式使会话失效。如果会话经常过期：

1. 避免频繁重新验证身份
2. 拉开 API 调用的间隔
3. 不要快速切换多个 IP 地址

SDK：实时事件

InstagramHybridListener 通过 Instagram 的 MQTToT 传输方式建立连接（与 edge-mqtt.facebook.com 建立持久 TLS 连接），如果连接失败则自动回退到轮询。它会通过设有上限的指数退避策略重试实时连接。对于大多数使用场景，推荐使用此监听器。

InstagramRealtimeListener 是纯实时选项，不会回退到轮询——如果你需要直接使用 MQTToT，并希望自行处理重连，请使用它。

两者都使用非官方私有 API，风险范围与现有轮询监听器相同。

设置

import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'

const client = await new InstagramClient().login()
const listener = new InstagramHybridListener(client, {
  pollInterval: 5000,         // fallback poll interval in ms
  realtimeRetryBaseMs: 2000,  // backoff base for realtime reconnect
  realtimeRetryMaxMs: 60000,  // backoff cap
})

或者，使用纯实时模式：

import { InstagramClient, InstagramRealtimeListener } from 'agent-messenger/instagram'

const client = await new InstagramClient().login()
const listener = new InstagramRealtimeListener(client)

监听事件

listener.on('connected', ({ userId, transport }) => {
  // transport is 'realtime' or 'polling' (hybrid only)
  console.log(`Listening as ${userId} via ${transport}`)
})

listener.on('message', (msg) => {
  // msg.id, msg.thread_id, msg.from, msg.timestamp
  // msg.is_outgoing, msg.type, msg.text, msg.media_url
  if (msg.is_outgoing) return
  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
})

listener.on('error', (err) => {
  console.error(err.message)
})

listener.on('disconnected', () => {
  // hybrid listener retries realtime automatically
})

生命周期

await listener.start()  // connects via MQTToT (or starts polling fallback)
listener.stop()         // clean shutdown

事件类型

事件	负载（Hybrid）	负载（Realtime / Polling）	描述
message	InstagramMessageSummary	InstagramMessageSummary	收到新的 DM
connected	{ userId: string; transport: 'realtime' | 'polling' }	{ userId: string }	监听器已启动
disconnected	—	—	连接已关闭
error	Error	Error	连接或 API 错误