用imsg读取iMessage聊天历史:chats与history命令的实战教程
用imsg读取iMessage聊天历史:chats与history命令的实战教程
imsg 是一个运行在 macOS 上的开源命令行工具(CLI),可以直接读取本机 Messages 数据库,把 iMessage / SMS 的会话列表和聊天历史输出到终端。本文用两条最核心的命令——imsg chats 与 imsg history,带你从零开始把 iMessage 聊天历史读出来,并学会按日期、发言人、附件做过滤。
一、imsg 是什么?先花 30 秒了解
- 本地直读:直接打开
~/Library/Messages/chat.db(SQLite 数据库),只读模式,不经过任何中间服务。 - 无守护进程:不需要安装后台服务、不需要 Node/Python 运行时。
- 面向自动化:所有输出都支持
--json,方便管道处理或喂给 AI Agent。
💡 核心思路:
imsg chats负责"找到会话、记下编号",imsg history负责"按编号读取历史"。两步完成。
二、一键安装与权限授予(最快配置方法)
1. 用 Homebrew 安装
brew install steipete/tap/imsg
imsg --version
要求 macOS 14 或更新版本。详见 docs/install.md。
2. 授予"完整磁盘访问"权限(关键一步)
imsg 要读取 Messages 数据库,macOS 会把这个文件锁在 Full Disk Access 后面:
- 打开 系统设置 → 隐私与安全性 → 完整磁盘访问权限;
- 把你运行
imsg的终端(Terminal、iTerm2 等)加入列表; - 退出并重新打开终端,权限才会生效。
验证是否成功:
imsg chats --limit 3
能看到最近的 3 个会话就说明配置完成。如果报错 unable to open database file 或 authorization denied,说明权限还没生效,参考 docs/troubleshooting.md 和 docs/permissions.md 逐项排查。
三、imsg chats:列出最近会话,拿到 chat-id
chats 命令按最近活跃度排序列出会话,是读取历史前的必经步骤(源码实现见 ChatsCommand.swift):
imsg chats --limit 20 # 列出最近 20 个会话
imsg chats --limit 20 --json | jq -s
文本模式下会显示 id、name、service、last_message_at 四列。其中 id(即 chat rowid)就是下一步 history 命令要用的编号。
实用小技巧
- 只看未读会话:
imsg chats --unread-only --json
- 筛选群聊或短信会话(配合
jq):
imsg chats --json | jq -s 'map(select(.is_group == true))'
imsg chats --json | jq -s 'map(select(.service == "SMS"))'
- 查看单个会话的详细信息(用
group命令,它同样适用于单聊,可理解为"会话详情"):
imsg group --chat-id 42
它会一次性返回会话编号、GUID、服务类型、参与成员、群聊标志等路由信息,适合在写脚本前先确认目标。完整字段说明见 docs/chats.md。
四、imsg history:读取 iMessage 聊天历史的核心命令
拿到 chat-id 后,history 命令就能按从新到旧的顺序读取单个会话的全部历史(源码实现见 HistoryCommand.swift):
imsg history --chat-id 42 --limit 50
imsg history --chat-id 42 --limit 50 --json | jq -s
⚠️ 注意:--limit 默认为 50,且在过滤器生效之后才截断。也就是说 --limit 20 --start ... 返回的是"日期窗口内的最新 20 条",而不是"全局最新 20 条再过滤"。
按日期区间过滤历史消息
--start 和 --end 都接受带时区的 ISO 8601 格式,且都可以省略其一:
# 查询 5 月 1 日到 5 月 6 日之间的消息
imsg history --chat-id 42 \
--start 2026-05-01T00:00:00Z \
--end 2026-05-06T00:00:00Z \
--json
# 只要 5 月 1 日之后的所有消息
imsg history --chat-id 42 --start 2026-05-01T00:00:00Z --json
# 只要 5 月 6 日之前的所有消息
imsg history --chat-id 42 --end 2026-05-06T00:00:00Z --json
群聊中按发言人过滤
--participants 接收逗号分隔的原始句柄(手机号或邮箱),匹配的是消息的 sender 字段:
imsg history --chat-id 42 --participants "+14155551212,jane@example.com" --json
附带读取附件元数据
JSON 输出默认就包含附件信息(文件名、MIME 类型、字节数、磁盘路径);加上 --attachments 后人类可读输出也会显示:
imsg history --chat-id 42 --attachments --json
如果安装了 ffmpeg,还可以用 --convert-attachments 把 CAF 音频转 M4A、GIF 转 PNG 首帧,方便喂给模型处理。
五、JSON 输出与流式处理:读取大量历史的最佳实践
--json 模式每行输出一个 JSON 对象(NDJSON),进度和警告都走 stderr,stdout 可以放心管道传输。读取大量历史时,推荐流式写文件而不是整体缓冲:
imsg history --chat-id 42 --limit 5000 --json \
| jq -c 'select(.is_from_me == false)' \
> inbound.ndjson
每条消息对象的核心字段包括:id、chat_id、guid、sender、is_from_me、text、created_at、attachments 等,完整 schema 见 docs/json.md。
几个值得一提的细节:
- 富文本自动还原:部分消息把文字存在二进制的
attributedBody列里,imsg history会自动解码并填回标准text字段,默认开启,无需任何参数。 - Tapback(点赞/爱心)不重复出现:反应行默认从历史输出中隐藏,避免与每条被反应的消息重复;想看实时反应请用
imsg watch --reactions。 - 性能友好:附件和反应的查询按批次合并,读取 1000 条带附件的历史消息依然很快。
六、常见问题快速排查
| 现象 | 原因与解决 |
|---|---|
报 unable to open database file |
终端(或其父进程)没有完整磁盘访问权限;授权后需重启终端再试 |
| 读取成功但返回 0 行 | Messages.app 未登录,或 ~/Library/Messages/chat.db 不存在,可先 ls -la 确认 |
| 用 SSH 连入看不到联系人姓名 | 属正常现象,JSON 中始终保留原始 sender 句柄,自动化不受影响 |
更完整的诊断清单见 docs/troubleshooting.md。
七、下一步:从"读历史"走向"看实时、发出去"
掌握 chats + history 后,你可以继续尝试 docs/quickstart.md 中的完整工作流:
imsg watch --chat-id 42 --json # 实时流式接收新消息
imsg send --to "+14155551212" --text "on my way"
| 想做的事 | 对应文档 |
|---|---|
| 会话字段与路由标识详解 | docs/chats.md |
| 历史查询全部参数 | docs/history.md |
| 实时监听新消息与 Tapback | docs/watch.md |
| 发送文本与文件 | docs/send.md |
| 统计消息与媒体数量 | docs/stats.md |
总结
imsg chats --limit N:按活跃度列出会话,记住你要的id;imsg history --chat-id N:按编号读取历史,配合--limit、--start/--end、--participants、--attachments精确过滤;--json+jq:把 iMessage 历史变成任何脚本或 AI Agent 都能消费的数据流。
全程只需要授予一次完整磁盘访问权限,无需任何后台服务——这就是用 imsg 读取 iMessage 聊天历史的极简路径。🚀
