把Agent历史发布成私有可搜索站点:coding_agent_session_search GitHub Pages/Cloudflare Pages部署完整教程

原创2026-10-13 22:58:551,733 阅读

把Agent历史发布成私有可搜索站点:coding_agent_session_search GitHub Pages/Cloudflare Pages部署完整教程

coding_agent_session_search(命令行简称 cass)是一款用 Rust 编写的一体化工具,能把 Codex、Claude Code、Gemini、Cursor、Aider 等 11+ 家编码 Agent 的本地会话历史统一索引成可搜索的"第二大脑"。它的 cass pages 命令更进一步:把这份 Agent 历史导出为一个端到端加密的静态站点,一键部署到 GitHub Pages 或 Cloudflare Pages——没有密码的人打开页面只能看到解锁框,内容绝不会泄露。🔐

为什么要把 Agent 历史发布成私有可搜索站点?

coding_agent_session_search (cass) TUI搜索结果页:跨Codex、Claude Code、Gemini、Cursor等编码Agent会话历史的统一全文搜索界面

日常写代码时,你和各种编码 Agent 的对话里沉淀了大量知识:踩坑记录、调试思路、架构决策。但这些会话散落在各家的 JSONL、SQLite、Markdown 里,难以检索,更难分享。

把历史发布成网页站点,能解决三类需求:

  • 团队共享:新人打开链接、输入密码,就能在自己浏览器里全文搜索团队积累的调试经验;
  • 知识存档:跨设备、跨工具的历史变成一个自包含站点,不依赖任何一台机器;
  • 给 AI 用:站点里的检索接口也可以被其他工具链消费。

而最大的顾虑是隐私——会话里常常粘着 API Key、内部路径、未发布的设计。这正是 cass 的 Pages 导出把加密当作默认行为的原因:整个数据库(含搜索索引)在离开你的机器之前就被加密,静态站点上只有密文。

快速上手:安装与索引 coding_agent_session_search

coding_agent_session_search (cass) 项目插画:Rust 构建的统一编码Agent会话搜索工具,聚合Codex、Claude、Gemini、Cursor等多个来源

先安装 cass 二进制(无需 clone 源码,仓库内也提供了 install.sh 安装脚本):

# Homebrew(macOS Apple Silicon / Linux)
brew install dicklesworthstone/tap/cass

# 或从 crates.io 构建
cargo install coding-agent-search

然后把本机各 Agent 的历史建立索引(首次运行会自动发现 Codex、Claude Code 等来源):

cass index

验证一下能搜到东西:

cass search "authentication error" --limit 5

索引完成后,你就可以进入 Pages 发布环节了。

一键部署:cass pages 的三种方式

直接运行 cass pages 会进入交互式向导(选内容 → 秘密扫描 → 设密码 → 站点信息 → 选部署目标 → 预览摘要 → 确认),向导流程定义在 src/pages/wizard.rs 中。如果偏好脚本化,用下面的参数即可跳过交互。

方式一:部署到 GitHub Pages

前置条件:安装 gh CLI 并已登录(gh auth login),以及 git。部署器会自动建仓库、推 gh-pages 孤儿分支、写 .nojekyll 并开启 Pages,逻辑见 src/pages/deploy_github.rs:

cass pages --target github --project my-agent-archive \
  --agents codex,claude_code \
  --since -90d

向导会要求你设置站点密码(Argon2id 派生密钥),完成后你的站点就发布在 你的用户名.github.io/my-agent-archive,把链接和密码通过不同渠道发给同事即可。

GitHub Pages 有硬性限制(代码中同样内置了校验,见 src/pages/deploy_github.rs):站点总量 ≤ 1 GB、单文件 > 100 MiB 直接拒绝、50–100 MiB 会警告。超出范围时先用 --since、--agents、--workspaces 收窄内容。

方式二:部署到 Cloudflare Pages

Cloudflare 没有上述文件/体积限制,还支持 COOP/COEP 响应头。两种方式认证:wrangler login,或直接设置 API 凭据(环境变量定义见 src/pages/deploy_cloudflare.rs):

export CLOUDFLARE_ACCOUNT_ID=<你的账号ID>
export CLOUDFLARE_API_TOKEN=<你的API令牌>

cass pages --target cloudflare --project my-agent-archive \
  --agents codex,claude_code,gemini

方式三:本地导出 + 浏览器预览

不想立刻上线?可以先只生成站点文件,再在本地起个 HTTP 服务检查效果:

# 只导出,不部署
cass pages --export-only ./out

# 本地预览(默认端口 8080,可加 --no-open 不自动开浏览器)
cass pages preview ./out --port 8080 --no-open

导出的目录里,site/ 是可直接部署的公开部分,private/ 存放绝不上传的恢复密钥物料。

cass TUI 会话详情视图:完整渲染Agent会话中的Markdown正文、代码块与工具调用内容

看懂加密:为什么没有密码就什么都看不到

cass 的 Pages 导出采用**信封加密(Envelope Encryption)**模型:

  1. 每次导出随机生成一个数据密钥 DEK,用 AES-256-GCM 把压缩后的会话数据库切成约 8 MiB 的加密块(chunked AEAD,支持浏览器流式解密);
  2. 你的密码经 Argon2id(抗 GPU 暴破的慢哈希)派生出 KEK,只用来包裹 DEK,多个密码可以对应多个"密钥槽";
  3. 站点页面在解锁前只是一个密码输入框——仓库里不存在任何明文会话内容、项目路径或搜索词。

向导还可以生成一个二维码形式的恢复密钥,它保存在本地 private/ 目录、永不随站点发布,打印或存入密码管理器即可作为第二把钥匙。

另外两个隐私相关的默认行为值得知道:

  • 路径隐私:--path-mode 默认为 relative(只存相对路径),可选 basename、full、hash,避免把本机绝对路径公开出去;
  • 共享档位:--share-profile 提供 public(抹掉主目录路径、用户名、项目名、邮箱等个人信息)、team、personal(不脱敏)三档;加密导出默认 team,且凭据类内容从不被改写——交给秘密扫描去拦截。

发布前安全自检:--scan-secrets 先扫敏感信息

会话里不小心贴过的 token、密码是最大泄露面。发布前可以单独跑一次扫描(只扫描、不导出):

# 人读模式,列出发现的疑似凭据
cass pages --scan-secrets --verbose

# 脚本/CI 模式:发现即非零退出
cass pages --scan-secrets --fail-on-secrets --json

支持用正则白/黑名单微调:--secrets-allow 'INTERNAL-.*'、--secrets-deny 'sk-<a href="https://link.gitcode.com/i/0d313ca98919bfb9a3e1712b4127144b" target="_blank">A-Za-z0-9]{16,}'。扫描与脱敏逻辑位于 [src/pages/secret_scan.rs 与 src/pages/redact.rs。

⚠️ 顺带提醒:虽然技术上支持 --no-encryption 明文导出,但会要求你显式加 --i-understand-unencrypted-risks 确认风险——除非内容确实完全公开,否则请保持加密。

部署后密钥管理:cass pages key 轮换密码

密码泄露或成员变动时,不必重新导出整个站点。cass pages key(实现见 src/pages/key_cli.rs)直接在已导出的包上管理密钥槽,完整文档见 docs/RECOVERY.md:

# 查看密钥槽(无需密码)
cass pages key list --archive ./out

# 增加第二个密码槽
cass pages key add-password --archive ./out

# 生成恢复密钥槽(密钥只显示一次,请妥善保存)
cass pages key add-recovery --archive ./out

# 吊销某个槽(最后一个槽不可吊销)
cass pages key revoke --archive ./out --slot 2

# 整体轮换:用新密码重新加密全部数据
cass pages key rotate --archive ./out

出于安全设计,密码永远不接受命令行传参(argv 对同机进程可见),交互输入或用 --password-stdin 从标准读入。

cass pages 常用参数速查表

参数 作用
--target local | github | cloudflare 部署目标,省略时进入交互式向导
--project <名称> 站点项目名(GitHub 仓库名 / Cloudflare 项目名)
--agents a,b,c、--workspaces p1,p2 按 Agent / 工作区过滤导出内容
--since -90d、--until ... 时间窗口过滤(支持 ISO 日期与 -7d、-1w 等相对偏移)
--path-mode relative|basename|full|hash 路径隐私档位(默认 relative)
--share-profile public|team|personal 脱敏档位
--scan-secrets / --fail-on-secrets 只扫描敏感信息 / CI 中失败退出
--export-only <目录> 仅导出文件,不部署
--preview <目录> + --port 本地 HTTP 预览
--config pages.json 非交互配置驱动,支持环境变量引用;--example-config 打印示例,--validate-config 只做校验

完整配置结构见 src/pages/config_input.rs。

部署失败排查:4 个常见问题

  1. 提示 gh CLI not authenticated:GitHub 部署需要先 gh auth login;Cloudflare 部署则检查 wrangler login 或 CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN 是否齐全。
  2. Bundle 超过 1 GB 被拒绝:这是 GitHub Pages 硬限制。缩小导出范围(加 --since、--agents),或改用 --target cloudflare。
  3. 向导一直等输入:想完全非交互时,把过滤条件、--target 全部写进命令行,或用 --config 配置文件;加 --dry-run 可先演练不写文件。
  4. 浏览器解锁失败:先用 cass pages key list --archive ./out 确认槽位存在;若密码确实丢了,使用导出时保存的恢复密钥(QR/文本),或执行 key rotate 换新密码后重新发布。

小结

coding_agent_session_search 让"搜索自己的 Agent 历史"变得毫秒级,而 cass pages 让这份历史安全地走出去:信封加密 + 密钥槽轮换 + 发布前秘密扫描,构成一条从"本地第二大脑"到"私有可搜索站点"的完整链路。无论你是选 GitHub Pages 的免费托管,还是 Cloudflare Pages 的无限制空间,整个过程都只是几条命令的事。🚀

更多背景可参考仓库中的 docs/planning/PLAN_TO_CREATE_GH_PAGES_WEB_EXPORT_APP.md 设计文档,以及 Pages 功能源码目录 src/pages/。

登录后查看全文
coding_agent_session_search