内容
# Codex History Hub
[简体中文](README.md) | [English](README.en.md)
Local-first、源数据只读的 Codex 会话聚合器。它将一个或多个 `CODEX_HOME` 索引到独立 SQLite 数据库，并通过本地网页和 MCP 提供跨项目、归档与子代理历史查询。
> 当前为 alpha 版本。请先阅读[隐私与安全](#隐私与安全)，不要上传 Hub 数据库或真实会话文件。
## 能力与边界
- 以 Codex 的 `state_5.sqlite` 为线程索引，按 `rollout_path` 增量读取 `sessions/` 和 `archived_sessions/`。
- 覆盖主会话、归档会话、子代理、用户/助手消息及工具事件。
- 提供本地只读网页，以及 5 个 MCP 工具用于近期上下文、搜索、线程读取和项目总览。
- 不读取 `auth.json`、Cookie、API Key 或 `logs_2.sqlite`，不修改 Codex 原始数据库、JSONL 或侧栏。
- 不合并或改写 Codex 原生账号会话库；所有索引和长期总结仅写入 Hub 自己的数据库。
## 安装
需要 Python 3.10 或更新版本，无第三方运行时依赖。
```powershell
git clone <YOUR_REPOSITORY_URL>
cd codex-history-hub
python -m venv .venv
.\.venv\Scripts\python -m pip install -e .
```
注册当前 Windows 用户的 Codex Home：
```powershell
codex-history-hub --db data/history-hub.db add-source `
--name local-codex `
--path "$env:USERPROFILE\.codex"
codex-history-hub --db data/history-hub.db sync
codex-history-hub --db data/history-hub.db status
```
macOS/Linux 可将路径写为 `${CODEX_HOME:-$HOME/.codex}`。另一个独立 `CODEX_HOME` 可用不同 `--name` 再次注册；旧式纯 JSONL 目录使用 `--type jsonl`。
也可通过环境变量设置数据库位置：
```powershell
$env:HISTORY_HUB_DB = "D:\private\codex-history\history-hub.db"
codex-history-hub status
```
## 本地网页
Windows 用户可双击 `open-history-hub.cmd`。也可以运行：
```powershell
codex-history-hub --db data/history-hub.db serve
```
然后访问 `http://127.0.0.1:8765`。服务立即同步一次，此后默认每 30 秒增量同步。页面包含主会话、子代理、归档、来源、模型提供方、项目和关键词筛选，工具事件默认折叠。
网页只允许绑定 `localhost`、`127.0.0.1` 或 `::1`。项目没有远程认证机制，因此会拒绝 `0.0.0.0` 和其他非回环地址。
## 全局 MCP 配置
将下列配置加入用户级 Codex `config.toml`。所有路径都应替换为本机实际的绝对路径；建议直接使用虚拟环境的 Python，避免依赖当前工作目录或系统 PATH。
```toml
[mcp_servers.history_hub]
command = "D:\\path\\to\\codex-history-hub\\.venv\\Scripts\\python.exe"
args = [
"-m", "history_hub",
"--db", "D:\\private\\codex-history\\history-hub.db",
"mcp"
]
```
重启 Codex 或新开任务后，可调用：
- `history_get_recent_context`：项目总览和最近 3 条主会话；子代理默认排除。
- `history_search`：搜索全部会话，包括归档和子代理。
- `history_get_thread`：按需读取选中线程；工具输出默认排除。
- `history_get_project_summary`：读取长期项目总览。
- `history_update_project_summary`：仅更新 Hub 数据库中的项目总览。
每次 MCP 工具调用前都会执行增量同步，因此网页无需常驻。
## 隐私与安全
Hub 在写入和输出时对常见 API Key、访问令牌、私钥、JWT、邮箱和用户主目录路径进行脱敏。Web/MCP 输出还会移除源根目录、rollout 文件路径和可能带凭据的 Git URL。升级后的数据库会执行一次 Hub 内部脱敏迁移；原始 Codex 文件始终不变。
这些规则不能识别所有自然语言中的个人信息。请遵守以下原则：
- `data/`、`*.db`、SQLite sidecar 和日志已被 `.gitignore` 排除，永远不要强制提交。
- Hub 数据库仍包含完整聊天内容，以及增量同步必需的本机源路径；应将其视为敏感文件。
- 分享截图、导出结果或数据库前必须人工复核。
- 不要将本地网页通过端口转发、代理或公网地址直接暴露。
- 安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，不要在 issue 中粘贴真实会话或凭据。
## 开发与验证
```powershell
python -m compileall -q history_hub tests
python -m unittest discover -s tests -v
```
CI 会在 Windows 与 Ubuntu、Python 3.10 和 3.13 上执行安装、编译和全部测试。贡献要求与隐私测试规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
本项目采用 [MIT License](LICENSE)。版本号遵循语义化版本，本次安全与通用化升级为 `0.3.0`。
