pp-chrome-history

pp-chrome-history

前置条件：安装 CLI

此技能会调用 chrome-history-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install chrome-history --cli-only
   

2. 验证：chrome-history-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。此方式会安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请改为将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/productivity/chrome-history/cmd/chrome-history-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法通过 $PATH 找到二进制文件目录。在验证成功前，请勿继续执行此技能中的命令。

chrome-history-pp-cli 会读取本地 Chrome 历史记录 SQLite 数据库，将其快照保存到 ~/.cache/chrome-history/，构建离线全文索引，并回答有关浏览记录的问题。只读、零网络——任何数据都不会离开设备。每个查询命令都支持 --json 和 --select，并且也通过 chrome-history-pp-cli mcp 将相同功能作为 MCP 工具提供——查询工具为只读；只有 sync 和 archive_enable/archive_disable 会更改本地状态（仅在设备上，不会访问网络）。还可选择启用持续累积的归档（默认关闭），留存 Chrome 后续清理或用户清除的历史记录——请参阅下文的归档。

适用场景

查询历史记录数据库中的 Chrome 活动：“找找我看过的那个页面”“我最近在研究什么”“Chrome 把我的浏览记录分成了哪些主题”“我在 X 上花了多少时间”“我下载了什么”“我以前访问过这个网站吗”。

不适用场景（反向触发条件）

• 非 macOS——**仅支持 macOS。**Chrome 数据库路径和“完全磁盘访问权限”机制均为 macOS 特有；目前尚不支持 Linux/Windows。
• 实时/已打开的标签页——这些内容不在历史记录 SQLite 数据库中（Chrome 将其保存在二进制会话文件中）。此工具用于查询历史记录，不用于查看当前标签页。
• Safari 历史记录——请使用单独的 CLI（Safari 的历史记录存储方式不同；chrome-history-pp-cli 只读取 Chrome 数据）。
• 书签、密码、自动填充、Cookie——不在此工具的范围内；它仅读取历史记录数据库。

分类（适用于 Agent）

静态类别映射 domains 较为粗略；journeys 会显示 Chrome 自带的（杂乱）分类。若要准确分类主题，请读取 --json 中的标题/URL，并自行推断主题——Agent 的推断效果优于静态映射和 Chrome 的分类（尤其是在将历史记录归类到个人知识库时）。

设置

确保 chrome-history-pp-cli 位于 $PATH 中（例如通过 go install 安装，或将构建好的二进制文件链接到 ~/go/bin）。然后对 Chrome 历史记录创建一次快照（可随时重新运行以刷新——Chrome 会锁定其数据库，因此即使 Chrome 处于打开状态，此工具也能安全地复制数据库）：

chrome-history-pp-cli sync      # build/refresh the local snapshot
chrome-history-pp-cli doctor    # health check; warns if Chrome's DB schema drifts from the tested version

如果 doctor 报告 Chrome 数据库无法读取，请为终端授予“完全磁盘访问权限”（系统设置 → 隐私与安全性 → 完全磁盘访问权限）。

回答问题前无需运行 sync——查询命令会读取已有快照。只有在需要获取更新的浏览记录时才运行 sync（或者首次使用且尚无快照时）。

归档：保留 Chrome 会删除的历史记录

默认情况下，快照会镜像 Chrome 当前的历史记录——当 Chrome 清理旧访问记录或用户清除历史记录时，这些记录也会在下次 sync 时从快照中移除。可选的归档会保留一份不断累积、持久化的副本，让历史记录不受 Chrome 清理的影响。此功能需要主动启用，默认关闭——一般询问“我浏览过什么”只需查询快照，因此不要不加思索地启用它。

chrome-history-pp-cli archive enable     # turn on the durable archive (seeds from the current snapshot)
chrome-history-pp-cli sync --accumulate  # refresh: append new visits into the archive (dedup on url+visit_time)
chrome-history-pp-cli archive status --json

• 启用后，读取操作会自动从归档中获取结果（归档是快照的超集）——查询方式无需改变；search/list/domains/report/heatmap/timeline/sql 都会直接查看更完整的历史记录。Chrome 专属的丰富视图（journeys/downloads/searches/dwell/graph/profile/visited）仍会读取当前快照。
• 使用 sync --accumulate 保持数据最新（追加记录，绝不删除）。
• 管理归档：archive disable（停止累积，保留文件） · archive clobber（将归档重置为基于当前快照的新基线） · archive reset --force [--purge]（关闭此模式并移动 archive.db；使用 --purge 则删除它） · archive vacuum（压缩）。

主要命令

• 查找：search <query>（FTS）、visited <url|domain>、topic <name>（合并 FTS 和 Journeys）、list、searches（你过去的搜索词）
• 汇总：domains、report（时间和效率分类）、heatmap、profile（行为摘要）、dwell（估算网站停留时间）
• 还原：journeys（Chrome 自带的主题聚类）、timeline <date>（按会话整理）、rabbitholes（分心浏览轨迹）、graph（导航图）
• 数据：downloads、sql "<SELECT…>"（只读）、sync、doctor、version、mcp
• 归档（持久化历史记录，需主动启用）：archive enable|status|disable|clobber|reset|vacuum、sync --accumulate

用法示例

# Find a page you half-remember
chrome-history-pp-cli search "github actions cache" --since 30d --limit 20

# What topics has Chrome grouped my browsing into? (its own Journeys clusters)
chrome-history-pp-cli journeys --limit 25

# Everything I browsed about a topic (FTS + clusters merged) — good for feeding a vault/agent
chrome-history-pp-cli topic "model context protocol" --since 90d --json

# Where did my time go this week, and what was productive vs distracting?
chrome-history-pp-cli report --since 7d

# A behavioral snapshot: peak hours, busiest weekday, top domains/searches
chrome-history-pp-cli profile

# Agent-friendly: narrow deeply nested output to just the fields you need
chrome-history-pp-cli journeys --json --select label,page_count --limit 10

# Keep history that Chrome would later prune/clear (opt-in, one-time enable + periodic refresh)
chrome-history-pp-cli archive enable
chrome-history-pp-cli sync --accumulate     # run periodically; reads then see the fuller archive automatically

Agent 注意事项

• 解析时优先使用 --json，并使用 --select a,b（点分路径）缩减响应内容。
• 查询命令会读取已有的本地快照——读取前无需运行 sync。只有在需要获取更新的浏览记录时才运行 sync（如果存储中确实没有任何数据，查询会提示 run sync first）。开启归档模式后，sync/sync --accumulate 也会写入持久化归档，因此不要仅为读取而运行 sync。
• searches/downloads/journeys 是 Chrome 专属功能；未来的 Safari CLI 会报告“不可用”，而不会伪造数据。
• 所有数据都保留在设备本地；浏览数据不会离开你的设备。