把Agent历史发布成私有可搜索站点:coding_agent_session_search GitHub Pages/Cloudflare Pages部署完整教程
把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 历史发布成私有可搜索站点?
日常写代码时,你和各种编码 Agent 的对话里沉淀了大量知识:踩坑记录、调试思路、架构决策。但这些会话散落在各家的 JSONL、SQLite、Markdown 里,难以检索,更难分享。
把历史发布成网页站点,能解决三类需求:
- 团队共享:新人打开链接、输入密码,就能在自己浏览器里全文搜索团队积累的调试经验;
- 知识存档:跨设备、跨工具的历史变成一个自包含站点,不依赖任何一台机器;
- 给 AI 用:站点里的检索接口也可以被其他工具链消费。
而最大的顾虑是隐私——会话里常常粘着 API Key、内部路径、未发布的设计。这正是 cass 的 Pages 导出把加密当作默认行为的原因:整个数据库(含搜索索引)在离开你的机器之前就被加密,静态站点上只有密文。
快速上手:安装与索引 coding_agent_session_search
先安装 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 的 Pages 导出采用**信封加密(Envelope Encryption)**模型:
- 每次导出随机生成一个数据密钥 DEK,用 AES-256-GCM 把压缩后的会话数据库切成约 8 MiB 的加密块(chunked AEAD,支持浏览器流式解密);
- 你的密码经 Argon2id(抗 GPU 暴破的慢哈希)派生出 KEK,只用来包裹 DEK,多个密码可以对应多个"密钥槽";
- 站点页面在解锁前只是一个密码输入框——仓库里不存在任何明文会话内容、项目路径或搜索词。
向导还可以生成一个二维码形式的恢复密钥,它保存在本地 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 个常见问题
- 提示
gh CLI not authenticated:GitHub 部署需要先gh auth login;Cloudflare 部署则检查wrangler login或CLOUDFLARE_ACCOUNT_ID+CLOUDFLARE_API_TOKEN是否齐全。 - Bundle 超过 1 GB 被拒绝:这是 GitHub Pages 硬限制。缩小导出范围(加
--since、--agents),或改用--target cloudflare。 - 向导一直等输入:想完全非交互时,把过滤条件、
--target全部写进命令行,或用--config配置文件;加--dry-run可先演练不写文件。 - 浏览器解锁失败:先用
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/。


