Skip to content

codex_inspector.md

Latest commit

 

History

History
220 lines (160 loc) · 11.4 KB

codex_inspector.md

File metadata and controls

220 lines (160 loc) · 11.4 KB
Raw

codex_inspector 使用说明

codex_inspector 是本机 Codex Inspector。它启动一个只绑定本机地址的 HTTP 服务，用浏览器查看 ~/.codex 里的历史 session、活跃度统计和记忆内容。

当前状态：实验工具。它会进入 tag Release 的 Go 二进制包，但不在根目录 install.sh 默认稳定安装清单中。

用途

场景 能力
查看 Codex 使用活跃度 统计 session 总量、事件数量、日/周/月维度和 heatmap
回收 token 用量 从 token_count 事件统计每个 session 的累计 token、本轮 token、cached input、reasoning output、context window 和 rate limit
排查历史对话 按时间范围浏览 session，按原始顺序展示 user、assistant、tool call、tool result 和 system event
查看记忆内容 浏览 MEMORY.md、memory_summary.md、rollout_summaries/，支持关键词搜索和详情预览
诊断数据源 检查关键路径是否存在，只读探测 SQLite schema

启动方式

快速安装到用户级目录：

./cli/codex_inspector/install.sh
codex_inspector -addr 127.0.0.1:8787

默认安装到 $HOME/.local/bin/codex_inspector。脚本支持 macOS 和 Linux，默认只写当前用户目录；只有显式传 --system 或 --allow-sudo 时，才会尝试使用 sudo 写系统目录。

自定义安装目录：

./cli/codex_inspector/install.sh --prefix "$HOME/.local"

系统级安装：

./cli/codex_inspector/install.sh --system

从仓库根目录构建：

go build -o output/codex_inspector ./cli/codex_inspector/...

启动本机服务：

./output/codex_inspector -addr 127.0.0.1:8787

指定 Codex home，适合用脱敏 fixture 做演示或截图：

./output/codex_inspector -codex-home /tmp/codex-inspector-fixture -addr 127.0.0.1:8787

历史 session summary 会缓存到本机 SQLite 文件，用于减少重复解析历史 rollout。默认路径放在系统临时目录下的用户隔离子目录，避免 macOS/Linux 上用户 cache 目录权限异常影响页面使用：

系统 默认 cache
macOS ${TMPDIR:-/tmp}/life_tools-codex-inspector-<uid>/session_summary_cache.sqlite
Linux /tmp/life_tools-codex-inspector-<uid>/session_summary_cache.sqlite

可以显式指定或禁用：

./output/codex_inspector -cache-path /tmp/codex_inspector_cache.sqlite
./output/codex_inspector -no-cache
./output/codex_inspector -cache-workers 2
./output/codex_inspector -cache-workers 0

-cache-workers 控制启动后的后台自动补齐，默认是 2。设为 0 时不会自动补齐；Diagnostics 页面上的手动 build/rebuild 仍可执行一次。

打开浏览器访问：

http://127.0.0.1:8787

数据源

数据源 读取内容 用途 写入
~/.codex/session_index.jsonl id、thread_name、updated_at session 列表标题和更新时间 否
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl JSONL 事件流 session 详情、消息统计、工具调用统计、token 用量统计 否
~/.codex/memories/MEMORY.md Markdown 文本 记忆索引总览和搜索 否
~/.codex/memories/memory_summary.md Markdown 文本 记忆摘要预览 否
~/.codex/memories/rollout_summaries/*.md Markdown 文本 相关 rollout 列表和详情预览 否
~/.codex/state_5.sqlite schema Diagnostics 页面只读探测 否
~/.codex/goals_1.sqlite schema Diagnostics 页面只读探测 否
~/.codex/memories_1.sqlite schema Diagnostics 页面只读探测 否
~/.codex/auth.json 不读取内容 Diagnostics 只标记为排除项 否
系统 tmp 目录下的 life_tools-codex-inspector-<uid>/session_summary_cache.sqlite 脱敏 session summary、token 统计、文件大小和修改时间 历史数据缓存，不存 raw JSONL 或完整对话，不写 ~/.codex 是

历史 session 详情页使用分页读取。若列表或 SQLite cache 已经提供可信 SessionSummary，后端会用其中的事件总数作为 hint，读取到当前页事件窗口后停止；今天仍在变化的 rollout 不使用该 hint，继续实时解析。

页面说明

页面 内容
Overview 统计卡片、默认最近一周时间筛选、快捷时间范围、最近半年活跃度 heatmap、月度趋势和最近 session
Sessions 左侧 session 列表，右侧按原生顺序分页展示消息、工具调用、工具结果、系统事件和 token usage 摘要；raw JSONL 按行展开时再加载
Memory 左侧记忆文件列表，右侧详情预览；支持关键词搜索
Diagnostics 数据源状态、SQLite schema 探测结果和只读边界

顶部菜单负责全局数据源状态和时间范围入口。左侧菜单只负责页面切换。小屏幕下左侧菜单会折叠成页面上方的两列导航。

右上角时间范围影响统计卡片、月度趋势、最近 session 和 Sessions 列表。Activity heatmap 不跟随该筛选，固定展示最近 183 天；鼠标悬停单元格时显示日期和当日对话次数。

大数字使用 k、m、b 简写，分别代表千、百万、十亿。精确值保留在指标悬浮提示中。

Diagnostics 的 Summary cache 面板展示派生 cache 生命周期：

状态 页面动作 后端行为
missing Create cache 新建 SQLite cache 并后台补齐今天以前的 rollout
healthy Fill missing cache 只补齐缺失或过期的历史 summary
corrupt Backup and rebuild cache，二次确认 将损坏文件改名为 .corrupt.<timestamp>.bak 后新建 cache
rebuilding 展示进度 返回当前 job，不重复启动
disabled 无操作按钮 -no-cache 下只实时解析 JSONL
unavailable 无操作按钮 展示权限、busy timeout 或其他非损坏错误

后端 API：

API 方法 用途
/api/cache/status GET 返回 cache 状态和 job 进度
/api/cache/build POST 创建或补齐 cache；job 运行中返回当前 job
/api/cache/rebuild POST 仅用于 corrupt cache 的备份重建；job 运行中返回当前 job

架构

flowchart TD
    A["Browser UI (127.0.0.1)"] --> B["Go HTTP server"]
    B --> C["Session parser"]
    B --> D["Memory reader"]
    B --> E["Diagnostics reader"]
    C --> F["session_index.jsonl"]
    C --> G["sessions/YYYY/MM/DD/rollout-*.jsonl"]
    C --> N["tool-owned summary cache.sqlite"]
    D --> H["memories/MEMORY.md"]
    D --> I["memories/memory_summary.md"]
    D --> J["memories/rollout_summaries/*.md"]
    E --> K["state_5.sqlite schema"]
    E --> L["goals_1.sqlite schema"]
    E --> M["memories_1.sqlite schema"]
Loading

渲染校验状态：当前机器未安装 mmdc 或 mermaid 命令；通过 npx 临时运行 @mermaid-js/mermaid-cli 需要下载并执行外部包，未被当前安全策略允许。因此该 Mermaid 图已按语法约束编写，但未完成本机实际渲染校验。

隐私边界

  • 默认监听 127.0.0.1，只服务当前用户。
  • 不实现登录、账号或权限系统，不适合暴露到局域网或公网。
  • 安装脚本默认写 $HOME/.local/bin，不写 /usr/local、/etc 或 /var；系统级安装必须显式传 --system 或 --allow-sudo。
  • 不写入 ~/.codex，不修改 session、memory、SQLite 或配置文件。
  • 不读取 auth.json 内容。
  • 历史 summary cache 默认写在系统 tmp 下的用户隔离目录，cache 目录权限为 0700，文件权限固定为 0600；也可以用 -cache-path 指定位置。缓存不包含 raw JSONL 或完整对话内容，只包含脱敏后的 SessionSummary、token 聚合、文件大小和修改时间。
  • 损坏 cache 不直接删除，只在用户触发 rebuild 时改名为 .corrupt.<timestamp>.bak 后重建。
  • JSON 和文本展示层会脱敏常见 auth、token、cookie、password、secret、api_key、access_key 字段。
  • raw JSONL 展开能力按行读取并展示脱敏后的 JSONL，方便排查格式和事件顺序；页面不默认下载完整 raw JSONL，不用于导出完整敏感内容。
  • token usage 只读取 Codex JSONL 中的结构化 token_count 元数据，不读取或推断账单、账号或认证信息。

脱敏截图

以下截图来自脱敏 fixture，不包含真实对话、真实 token 或内部信息。

Overview

Overview

Sessions

Sessions

Memory

Memory

Mobile

Mobile

故障排查

现象 原因 处理
页面显示没有 session session_index.jsonl 或 sessions/ 不存在，或时间筛选太窄 查看 Diagnostics，清空时间筛选后刷新
某个 session 没有详情 索引里有 session，但 rollout JSONL 不存在或无法匹配 查看 session 列表里的路径和 Diagnostics 数据源
点击 session 后一直 loading 冷启动正在建立 session 索引，或目标 JSONL 文件很大 等待首次索引完成；详情接口会优先使用缓存中的 id -> path，首屏只返回有限事件，后续通过 Load more events 追加
token 统计为 0 该历史 JSONL 没有 event_msg.type=token_count，或格式不同 这是兼容性缺失，不影响对话查看；Diagnostics 和 raw JSONL 可用于确认格式
CPU 占用高 首次历史范围加载需要解析该范围内尚未缓存的历史 rollout；今天的数据实时解析；直接打开未缓存的超大 session 仍可能扫描目标文件 等待首次缓存写入；后续历史请求会复用 SQLite summary cache；历史详情页在有 summary hint 时只扫描当前事件窗口，raw JSONL 按行加载，避免浏览器一次性渲染完整会话
cache 状态是 missing cache 文件尚未创建 在 Diagnostics 点击 Create cache
cache 状态是 corrupt SQLite 返回明确损坏错误 在 Diagnostics 二次确认后点击 Backup and rebuild cache
cache 状态是 unavailable 权限、busy timeout 或其他非损坏错误 处理错误原因；页面会降级实时解析 JSONL
cache 文件权限不符合预期 旧版本或手动创建的 cache 文件权限过宽 删除 cache 文件后重启，或执行 chmod 600 <cache-path>
raw JSONL 缺少部分内容 单行过大时后端会限制返回长度 到本机文件系统只读查看原文件
SQLite schema 没有展示 系统没有 sqlite3 命令，或数据库不存在 安装 sqlite3 或忽略 schema 诊断
浏览器访问不到服务 服务未启动或地址不是 127.0.0.1:8787 检查启动命令和终端输出

验证

推荐验证命令：

go test ./cli/codex_inspector
go build -o output/codex_inspector ./cli/codex_inspector/...
./output/codex_inspector -cache-workers 2

页面验证需要启动服务后用 Chrome 检查：

  • Overview、Sessions、Memory、Diagnostics 四个页面能正常渲染。
  • Chrome console 没有相关 error。
  • 390x844、768x1024、1440x900 三类视口没有文字重叠、按钮溢出、菜单遮挡或横向滚动失控。

功能回归样例见 codex_inspector_regression.md。修改页面、API、parser、redaction、SQLite summary cache 或响应式布局时，必须同步更新对应回归样例。