agent-scripts 的 Beeper 技能:用 SQLite 与全文检索在本地挖掘 iMessage/WhatsApp 聊天历史

原创2026-10-10 23:45:001,167 阅读

agent-scripts 的 Beeper 技能:用 SQLite 与全文检索在本地挖掘 iMessage/WhatsApp 聊天历史

本文以 agent-scripts 仓库中的 skills/beeper/SKILL.md 为核心,讲解 Agent 如何借助 macOS 上 Beeper 客户端的本地缓存数据库 BeeperTexts/index.db,通过 SQLite 与全文检索(FTS)回答基于 iMessage/WhatsApp 桥接消息的"模糊联系人线索"类历史问题。读完你将掌握该技能的数据源位置与表结构线索、四步检索工作流、可直接复制运行的探测命令,以及处理私密消息时必须遵守的安全边界。

技能定位:为 Agent 准备的"本地历史"检索入口

beeper 是 agent-scripts 仓库中的一个 Agent 技能(Skill),全部定义位于 skills/beeper/SKILL.md。技能文件头部携带 YAML front matter:

---
name: beeper
description: "Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS."
---

这与仓库的整体技能规范一致:按 README.md 的约定,每个 skills/<name>/SKILL.md 都必须有 name 与 description 字段,description 保持简短、面向路由触发而非文档说明;技能正文保持精炼、可执行。同时,skills.sh.json 将 beeper 归入 "Comms & Knowledge" 分组,与 notcrawl(Notion 归档)、obsidian(Obsidian 库)、whatsapp(WhatsApp 路由)、reminders、sonos、speaking、things-todo、twilio-sms 并列,定位为"通讯与个人知识档案"类能力。

该技能的典型使用场景是:用户只记得"某段时间、某个桥接渠道(iMessage 或 WhatsApp)上某个模糊的联系人",而 Beeper 恰好把多个渠道的历史聚合在本地一份数据库里——技能便指引 Agent 直接查询这份本地缓存,而不是去猜测具体应用。

数据源:BeeperTexts/index.db 与 mx_room_messages_fts

技能指定的唯一数据源有两条(见 skills/beeper/SKILL.md 的 ## Source 一节):

  • 数据库:~/Library/Application Support/BeeperTexts/index.db
  • 全文索引表:mx_room_messages_fts

两点值得注意:

  1. 路径含空格:Application Support 之间存在空格,因此所有 SQLite 命令中路径必须加引号。技能示例使用 "$HOME/Library/Application Support/BeeperTexts/index.db",其中 $HOME 由 shell 展开、外层双引号保证路径不被拆分。
  2. mx_ 前缀:从表名 mx_room_messages_fts 可以推断,Beeper 底层采用 Matrix 协议风格的命名(mx_ 前缀),房间与消息数据以 Matrix 模式落盘;技能工作流中提到的 accounts、participants 以及各 room 表即围绕这一模型组织。

mx_room_messages_fts 是一个 SQLite FTS 全文索引表。之所以用 FTS 而不是 LIKE '%关键词%',是因为消息正文的检索需要分词、词级匹配与近似查询,FTS 能直接返回 rowid 和命中片段(content),并把结果通过 rowid 与消息明细表关联起来取回完整元数据。技能中的第二个探测命令恰好印证了该表直接可用 rowid, content 两列:

sqlite3 "$HOME/Library/Application Support/BeeperTexts/index.db" \
  "select rowid, content from mx_room_messages_fts where mx_room_messages_fts match 'query' limit 20;"

四步检索工作流

技能定义了一条明确的检索路径(skills/beeper/SKILL.md 的 ## Workflow 一节),核心思想是"先定域、后搜索、再收窄、带置信度地报告":

第一步:从 accounts、participants 与 room 表识别可能的账号/桥接/房间。 在动手全文搜索之前,先摸清本地缓存里有哪些账号、哪些桥接渠道(iMessage、WhatsApp 等)、哪些房间。这样后续搜索才能锚定在正确的范围内,而不是对整库盲目扫描——技能明确要求"Start by inspecting accounts/rooms before broad searching"。

第二步:用 FTS 做文本发现。 针对用户提供的模糊线索(人名、短语、日期附近的关键词),对 mx_room_messages_fts 执行 match 查询,先拿到一批候选命中的 rowid 与正文片段。

第三步:按日期、参与人、房间收窄。 候选结果往往过多或过宽,需要用 FTS 得到的 rowid 关联回消息明细表,结合时间戳、发送者、所属房间等元数据(具体列名以实际库为准)进一步过滤,把候选压缩到可读规模。

第四步:输出时报告房间/账号名称、日期跨度与置信度。 最后把命中结果连同"来自哪个房间/账号、覆盖哪个日期范围、证据有多可靠"一起汇报,让使用者能判断这条线索的来源与可信程度,而不是丢一串裸的 rowid。

可直接复用的探测命令

技能提供了两条标准探测命令,均可在终端原样运行。

第一条用于了解本地缓存中有哪些账号:

sqlite3 "$HOME/Library/Application Support/BeeperTexts/index.db" \
  "select * from accounts limit 20;"

select * 适合一次性摸清表结构;若之后要反复查询,建议先观察列名,再改为 select <具体列> 以减小输出体积。

第二条用于按关键词做全文检索(将 query 替换为实际关键词):

sqlite3 "$HOME/Library/Application Support/BeeperTexts/index.db" \
  "select rowid, content from mx_room_messages_fts where mx_room_messages_fts match 'query' limit 20;"

基于 SQLite FTS 的标准语法,可以在不改变数据源的前提下做如下扩展:

  • 前缀匹配:match 'query*' 可命中以 query 开头的词(如人名缩写或词根变体);
  • 短语匹配:match '"exact phrase"' 精确匹配连续短语,适合搜完整昵称或固定用语;
  • 布尔组合:FTS5 支持 AND / OR / NOT,例如 match 'alice AND lunch';
  • 列限定:若表定义了可检索列,可写 content:query 将检索限制在正文列内;
  • 只读打开:为保险起见可加 -readonly 参数:sqlite3 -readonly "$HOME/Library/Application Support/BeeperTexts/index.db" "...",从工具层面杜绝误写。

与仓库其他技能的边界与协同

beeper 只负责"查本地缓存"这一件事。仓库内与之相邻的通讯类技能各有分工(分组见 skills.sh.json):

  • WhatsApp 深度操作:路由到 skills/whatsapp/SKILL.md,它区分了只读归档工具 wacrawl(首选历史/搜索)与联网设备工具 wacli(备用账号、发送、变更),并强调"未经明确请求不发送、不变更状态";
  • Notion 归档:skills/notcrawl/SKILL.md 面向 ~/.notcrawl/notcrawl.db 的本地存档;
  • Obsidian 库:skills/obsidian/SKILL.md 面向 ~/obsidian 的笔记库。

当用户的问题是"跨 iMessage/WhatsApp 桥的模糊联系线索"时,beeper 是首选入口;一旦确认问题落在 WhatsApp 生态、需要实时同步或发送等能力,再切换至 whatsapp 技能。这种"按数据源路由"的设计与仓库整体思路一致:每个技能各管一段工具工作流。

隐私与安全边界

该技能在末尾明确给出了一条底线:"Keep results local; this DB can contain private messages."(结果保持在本地;此数据库可能包含私密消息)。实操上对应三条纪律:

  1. 不外传:查询产出的正文、联系人、账号信息属于个人私密数据,不得写入公共渠道、社交平台或未经授权的服务;仓库的 AGENTS.MD 对内部信息与隐私披露同样设有硬性规则,技能与之一致。
  2. 只读操作:对 index.db 只做 SELECT/match 查询,优先使用 sqlite3 -readonly 打开,绝不写入、不修改、不删除缓存数据。
  3. 输出收敛:汇报时只给房间/账号名、日期跨度与置信度,避免大段贴出完整私密对话原文。

技能工程的规范化:front matter 与校验

beeper 技能体保持精炼,是仓库"技能正文应 terse and operational"(README.md)这一约定的直接体现——与其把命令细节写进文档,不如给出精准的路由描述与最关键的探测命令,让 Agent 按流程执行。

这类技能文件还受到仓库工程化手段的约束:脚本 scripts/validate-skills 会遍历全部 skills/*/SKILL.md,校验 front matter 必须位于文件首行且以 --- 闭合、name 与 description 必须是非空字符串、技能名不得重复。因此 beeper 的 front matter 既是路由元数据,也是通过校验的硬性要求,可执行 scripts/validate-skills 对全部技能做一致性检查。

综上,beeper 是一个"小而专"的 Agent 技能:数据源明确(一份 SQLite 缓存 + 一张 FTS 表)、流程清晰(定域 → FTS → 收窄 → 带置信度汇报)、边界严格(只读、本地、不外泄)。掌握它,就能让 Agent 高效地回答"这条模糊线索到底是谁、什么时候、在哪个桥接渠道上说过"这类本地历史问题。

登录后查看全文
agent-scripts