feat: add codex inspector

.github/workflows/go-test.yml

@@ -1,11 +1,12 @@
-name: Go Test Reminder
+name: Go Test
 
 on:
   pull_request:
     paths:
       - '.github/workflows/go-test.yml'
       - 'go.mod'
       - 'go.sum'
+      - 'cli/codex_inspector/**'
       - '**/*.go'
   push:
     branches:
@@ -14,14 +15,15 @@ on:
       - '.github/workflows/go-test.yml'
       - 'go.mod'
       - 'go.sum'
+      - 'cli/codex_inspector/**'
       - '**/*.go'
 
 permissions:
   contents: read
 
 jobs:
   go-test:
-    name: Go test reminder
+    name: Go test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -33,24 +35,8 @@ jobs:
           go-version: '1.21.x'
           cache: true
 
-      - name: Run Go tests as reminder
-        id: go_test
+      - name: Run Go tests
         shell: bash
         run: |
-          set +e
-          go test ./... 2>&1 | tee go-test.log
-          status="${PIPESTATUS[0]}"
-          if [ "$status" -ne 0 ]; then
-            echo "failed=true" >> "$GITHUB_OUTPUT"
-            echo "::warning::go test ./... failed with exit code $status. This workflow is advisory and does not block release packaging."
-          else
-            echo "failed=false" >> "$GITHUB_OUTPUT"
-          fi
-          exit 0
-
-      - name: Write reminder summary
-        if: steps.go_test.outputs.failed == 'true'
-        run: |
-          echo '## Go test reminder' >> "$GITHUB_STEP_SUMMARY"
-          echo '' >> "$GITHUB_STEP_SUMMARY"
-          echo '`go test ./...` failed. This workflow is advisory and does not block release packaging.' >> "$GITHUB_STEP_SUMMARY"
+          set -euo pipefail
+          go test ./...

.github/workflows/release.yml

@@ -90,6 +90,7 @@ jobs:
             GOOS="$os" GOARCH="$arch" go build -trimpath -ldflags "-s -w" -o "$out/bin/retry_exec" ./cli/retry_exec/...
             GOOS="$os" GOARCH="$arch" go build -trimpath -ldflags "-s -w" -o "$out/bin/codex_hook_notify" ./cli/codex_hook_notify/...
             GOOS="$os" GOARCH="$arch" go build -trimpath -ldflags "-s -w" -o "$out/bin/file_share" ./cli/file_share/...
+            GOOS="$os" GOARCH="$arch" go build -trimpath -ldflags "-s -w" -o "$out/bin/codex_inspector" ./cli/codex_inspector/...
 
             cp README.MD install.sh "$out/"
             cp sample/life_tools/*.json "$out/sample/life_tools/"

AGENTS.md

@@ -17,6 +17,7 @@
 - `cli/retry_exec/`：命令失败重试和失败通知工具。
 - `cli/codex_hook_notify/`：Codex lifecycle hook 飞书提醒工具。
 - `cli/file_share/`：临时 HTTP 文件分享工具。
+- `cli/codex_inspector/`：本机 Codex 历史会话、活跃度和记忆内容只读查看工具，当前是实验 CLI，不进默认安装清单。
 - `cli/video_subtitle/`：单视频自动生成中文字幕工具，详细说明见 `docs/cli/video_subtitle.md`。
 - `emby_plugins/video_subtitle/`：Emby Server 插件，后端调用 `video_subtitle` 生成字幕，详细说明见 `docs/plugins/emby_video_subtitle.md`。
 - `gui/interview_timer/`：macOS 面试悬浮计时 GUI 应用，说明见 `docs/gui/interview_timer.md`。
@@ -161,11 +162,13 @@ emby_plugins/video_subtitle/install.sh --help
 `.github/workflows/swift-mac-app.yml` 负责 `gui/interview_timer` 的 Swift 单测、编译和未签名 `.app` 发布。
 
 - tag 触发规则保持 `v*`，避免普通分支 push 意外创建 Release；`pull_request` 只能做 dry-run，不能创建 Release。
-- Go 测试放在 `.github/workflows/go-test.yml`，Python 单元测试放在 `.github/workflows/python-test.yml`，测试失败只能写 GitHub warning 和 summary，不能让 reminder workflow 或 release workflow 失败。
-- Go 二进制包只放稳定 CLI 工具：`renameV1`、`check_keywords`、`retry_exec`、`codex_hook_notify`、`file_share`。
+- Go 测试放在 `.github/workflows/go-test.yml`，PR 时必须真实运行 `go test ./...`，不能做成只提醒不阻塞的 reminder。
+- Python 单元测试放在 `.github/workflows/python-test.yml`，失败只写 GitHub warning 和 summary，不能阻塞 release workflow。
+- Go 二进制包包含稳定 CLI 工具：`renameV1`、`check_keywords`、`retry_exec`、`codex_hook_notify`、`file_share`；`codex_inspector` 作为实验工具参与 release 二进制产物，但仍不进入根目录 `install.sh` 默认安装清单。
 - `video_subtitle` 只能按源码包发布，不能宣传成免依赖二进制；它仍依赖 Python、ffmpeg、TOS、ASR 和 LLM 配置。
 - Emby 插件包只放 `LifeTools.Emby.VideoSubtitle.Emby.dll` 和文档，不要把 `MediaBrowser.*`、`Emby.*` 或核心库 DLL 打进插件发布包。
 - `InterviewTimer` macOS App 只在 macOS runner 上构建，tag 发布包为未签名的 `InterviewTimer.app` zip，不要把它塞进根目录 `install.sh` 或 Go 二进制发布包。
+- 新增 CLI、构建入口、release 产物或测试要求时，必须检查 `.github/workflows/*` 是否需要同步，避免代码合入后没有 CI 或 tag 发布产物缺失。
 - 修改发布包内容时同步更新 `docs/release.md` 和 README 的发布入口。
 - 发布 workflow 需要 `permissions: contents: write`，不要扩大到无关权限。
 

README.MD

@@ -2,6 +2,20 @@
 
 个人日常使用的小工具集合，按应用类型组织源码：命令行程序放在 `cli/`，插件程序放在 `emby_plugins/`，图形界面程序放在 `gui/`。
 
+## 界面预览
+
+下面这些工具带有浏览器或桌面界面，截图均使用脱敏演示数据。点击截图可进入对应文档。
+
+| Codex Inspector：总览 | Codex Inspector：会话详情 |
+|---|---|
+| [<img src="docs/assets/codex_inspector/overview-1440.png" alt="Codex Inspector Overview" width="520">](docs/cli/codex_inspector.md) | [<img src="docs/assets/codex_inspector/sessions-1440.png" alt="Codex Inspector Sessions" width="520">](docs/cli/codex_inspector.md) |
+| 本机只读查看 Codex 会话数量、token 用量、活跃度热力图和最近 session。 | 按原生交互顺序查看 user、assistant、tool call、tool result 和 raw JSONL。 |
+
+| file_share | Emby 字幕插件 | InterviewTimer |
+|---|---|---|
+| [<img src="docs/assets/file_share/overview-1440.png" alt="file_share browser UI" width="340">](docs/cli/file_share.md) | [<img src="docs/assets/emby_video_subtitle/control-page-1440.png" alt="Emby video subtitle plugin" width="340">](docs/plugins/emby_video_subtitle.md) | [<img src="docs/assets/interview_timer/panel.png" alt="InterviewTimer floating panel" width="260">](docs/gui/interview_timer.md) |
+| 临时启动本机只读 HTTP 文件分享服务，支持浏览、下载和目录打包。 | 在 Emby Web 中选择媒体、配置参数并提交字幕生成任务。 | macOS 悬浮面试计时器，按模板推进多环节流程。 |
+
 ## 快速安装
 
 支持 Linux 和 macOS。仓库根目录执行下面命令，默认安装稳定命令行工具：`renameV1`、`check_keywords`、`retry_exec`、`codex_hook_notify`、`video_subtitle`、`file_share`。
@@ -43,6 +57,7 @@
 | CLI | `codex_hook_notify` | `cli/codex_hook_notify/` | `codex_hook_notify` | 接收 Codex hook 并推送飞书提醒 | [docs/cli/codex_hook_notify.md](docs/cli/codex_hook_notify.md) |
 | CLI | `file_share` | `cli/file_share/` | `file_share` | 临时启动只读 HTTP 文件分享服务 | [docs/cli/file_share.md](docs/cli/file_share.md) |
 | CLI | `video_subtitle` | `cli/video_subtitle/` | `video_subtitle` | 为单个视频生成简体中文字幕 | [docs/cli/video_subtitle.md](docs/cli/video_subtitle.md) |
+| Experimental CLI | `codex_inspector` | `cli/codex_inspector/` | `codex_inspector` | 本机只读查看 Codex 会话、token 用量、活跃度和记忆内容 | [docs/cli/codex_inspector.md](docs/cli/codex_inspector.md) |
 | Plugin | Emby 字幕插件 | `emby_plugins/video_subtitle/` | `LifeTools.Emby.VideoSubtitle.Emby.dll` | 在 Emby 后台调用 `video_subtitle` 生成字幕 | [docs/plugins/emby_video_subtitle.md](docs/plugins/emby_video_subtitle.md) |
 | GUI | InterviewTimer | `gui/interview_timer/` | `InterviewTimer.app` | macOS 面试悬浮计时器 | [docs/gui/interview_timer.md](docs/gui/interview_timer.md) |
 
@@ -60,6 +75,38 @@
 | `build.sh` | 构建 Go CLI 工具到 `output/`。 |
 | `install.sh` | 安装 CLI 工具、示例配置和可选 hook。 |
 
+`codex_inspector` 当前是实验工具，不在根目录 `install.sh` 默认稳定安装清单中。需要快速试用时使用专用安装脚本，默认安装到用户级目录 `$HOME/.local/bin`，不会写 `/usr/local`、`/etc`，也不会主动 sudo：
+
+```bash
+./cli/codex_inspector/install.sh
+codex_inspector -addr 127.0.0.1:8787
+```
+
+macOS 和 Linux 都支持自定义前缀；只有显式传 `--system` 或 `--allow-sudo` 时才会尝试写系统目录：
+
+```bash
+./cli/codex_inspector/install.sh --prefix "$HOME/.local"
+./cli/codex_inspector/install.sh --system
+```
+
+也可以不安装，直接单独构建：
+
+```bash
+go build -o output/codex_inspector ./cli/codex_inspector/...
+./output/codex_inspector -addr 127.0.0.1:8787
+```
+
+历史 session summary 会写入本机 SQLite cache，加速重复浏览；可通过 `-cache-path` 指定位置，或用 `-no-cache` 禁用。
+
+cache 是派生数据，不写入 `~/.codex`。服务启动时只打开已有 cache；cache 缺失时页面仍会实时解析 JSONL，Diagnostics 页面可以手动创建。已有健康 cache 会按 `-cache-workers` 后台补齐历史 session，默认 2 个 worker，`0` 表示关闭自动补齐：
+
+```bash
+codex_inspector -cache-workers 2
+codex_inspector -cache-workers 0
+```
+
+Diagnostics 支持查看 cache 状态并执行 `Create cache`、`Fill missing cache`、`Backup and rebuild cache`。损坏 cache 会先重命名为 `.corrupt.<timestamp>.bak`，再新建 cache。
+
 ## 构建与验证
 
 构建 Go CLI：
@@ -97,4 +144,4 @@ swift build --product InterviewTimerApp
 
 ## 发布
 
-推送 `v*` tag 会通过 GitHub Actions 构建 GitHub Release 资产，包括 Linux/macOS Go 二进制包、`video_subtitle` 源码包、Emby 插件包和未签名的 `InterviewTimer.app` 包。发布流程见 [docs/release.md](docs/release.md)。
+推送 `v*` tag 会通过 GitHub Actions 构建 GitHub Release 资产，包括 Linux/macOS Go 二进制包、`video_subtitle` 源码包、Emby 插件包和未签名的 `InterviewTimer.app` 包。Go 二进制包包含 `codex_inspector`，但它仍是实验工具，不进入默认安装清单。发布流程见 [docs/release.md](docs/release.md)。

cli/codex_inspector/AGENTS.md

@@ -0,0 +1,56 @@
+# codex_inspector 维护规则
+
+`codex_inspector` 是实验 CLI，用浏览器只读查看本机 Codex session、活跃度、token 统计、memory 和 diagnostics。改动时优先保持实现简单，不引入复杂前端构建链、任务队列或配置系统。
+
+## 回归样例维护
+
+功能回归样例统一维护在：
+
+```text
+docs/cli/codex_inspector_regression.md
+```
+
+每次修改 `cli/codex_inspector/` 下的代码或静态资源时，必须检查是否需要同步更新该文档。以下改动必须新增或更新回归样例：
+
+- 新增或调整 Overview、Sessions、Memory、Diagnostics 页面内容。
+- 新增或调整按钮、菜单、时间范围、搜索、raw JSONL 展开、token usage 展示。
+- 修改 `/api/overview`、`/api/sessions`、`/api/memory`、`/api/diagnostics` 或 cache API。
+- 修改 JSONL parser、SessionSummary、token 聚合、memory 读取、redaction 规则。
+- 修改 SQLite summary cache 的状态、后台补齐、重建、损坏识别、降级或 CLI 参数。
+- 修改响应式布局、移动端断点、heatmap 行列规则或数字格式化规则。
+
+如果改动不需要更新回归样例，提交说明或 PR 描述中必须写清原因，例如：
+
+```text
+Regression docs unchanged: only internal variable rename; no behavior, API, UI, parser, cache, or privacy boundary changed.
+```
+
+## 样例质量要求
+
+新增样例必须包含：
+
+- 前置数据或 fixture。
+- 操作步骤。
+- 期望结果。
+- 可由 AI 工具自动检查的断言点，例如 API 字段、selector、文本、console error、network error、viewport overflow。
+
+样例不得包含真实 `~/.codex` 内容、真实 session 文本、真实路径、auth、token、cookie、secret、API key 或内部信息。需要敏感字段时只能使用假值，并明确期望展示为脱敏值。
+
+## 验证要求
+
+涉及 Go 行为时优先运行：
+
+```bash
+go test ./cli/codex_inspector
+go build -o output/codex_inspector ./cli/codex_inspector/...
+```
+
+涉及前端交互或布局时，启动服务后用 Chrome 检查 Overview、Sessions、Memory、Diagnostics，并至少覆盖：
+
+```text
+390x844
+768x1024
+1440x900
+```
+
+纯文档改动不需要运行 Go 测试，但必须检查 diff，确认文档链接、命令、页面名称和 API 名称与当前实现一致。