Codex Skill Analytics

一个完全本地、纯工程实现的 Codex Skill 旁路分析器。它只读扫描 Codex rollout JSONL， 确定性识别 Skill 文档读取、Skill 脚本运行和可识别的显式 Skill 注入，然后增量写入独立 SQLite 数据库。运行时不调用任何模型，也不修改或拦截 Codex。

统计口径

• Invocation：同一轮中同一 Skill 只计一次，与 Codex 当前源码的去重口径一致。
• Access：每次可验证的 SKILL.md 读取或 scripts/ 脚本执行均计一次。
• Same turn：两个 Skill 在同一轮共同调用。
• Sequence：同一轮中相邻的 Skill 调用方向。
• Next in thread：同一线程中相邻的 Skill 调用方向，关系弱于同轮序列。

仅有名称提及、系统 Skill 清单、代码示例和搜索结果不会被算作调用。

一条命令启动 Web

需要 Python 3.11 或更高版本，以及本机 Codex 产生的 ~/.codex/sessions 或 ~/.codex/archived_sessions 历史。

拿到仓库后直接运行：

./run.sh

脚本不安装第三方依赖，会自动增量同步本机 Codex 历史、启动本地服务，并在默认浏览器打开：

http://127.0.0.1:8765/

首次从 GitHub 获取私有仓库时，可使用一行命令：

gh repo clone NauJson/codex-skill-analytics && cd codex-skill-analytics && ./run.sh

停止服务按 Ctrl-C。再次运行仍是增量同步，不会重复计数。如果机器上没有 Codex 历史，Web 仍能打开，但统计结果为空。

NPM / NPX CLI

安装发布包后，可直接启动并打开 Web：

npx codex-skill-analytics

或全局安装，两个命令名都可用：

npm install --global codex-skill-analytics
codex-skill-analytics
# 简写
csa

不带参数时，CLI 会先增量同步本机历史，然后打开 Web。原有子命令可以直接透传：

csa sync
csa summary --days 30
csa events --days 30 --limit 100
csa relations --days 30 --type sequence
csa graph --days 30 --type sequence --output skill-graph.html
csa serve --open

NPM 包不携带、不上传用户的 Codex 历史或 SQLite 数据。它包含 Node 启动器和纯标准库 Python 分析内核；运行机器仍需安装 Python 3.11 或更高版本。可通过 CSA_PYTHON=/path/to/python csa 显式指定解释器。

开发安装与命令行使用

git clone https://github.com/NauJson/codex-skill-analytics.git
cd codex-skill-analytics
python3 -m venv .venv
.venv/bin/pip install -e .

.venv/bin/codex-skill-analytics sync
.venv/bin/codex-skill-analytics summary --days 30
.venv/bin/codex-skill-analytics events --days 30 --limit 100
.venv/bin/codex-skill-analytics trend --days 30
.venv/bin/codex-skill-analytics relations --days 30 --type same-turn
.venv/bin/codex-skill-analytics relations --days 30 --type sequence
.venv/bin/codex-skill-analytics graph --days 30 --type sequence \
  --min-weight 2 --output skill-dependency-graph.html
.venv/bin/codex-skill-analytics serve --open

默认数据库位于：

~/.local/share/codex-skill-analytics/analytics.sqlite3

可用 --db /path/to/file.sqlite3 指定其他位置。

graph 会生成不依赖网络的单文件交互式 HTML。默认的 sequence 图中，A → B 表示同一轮 内 A 后紧接着调用了 B；这是一种从历史观察到的应用依赖，不代表 Skill 源码声明了硬依赖。 也可用 --type same-turn 查看无方向共现，或用 --type next-in-thread 查看线程内跨轮衔接。

serve 默认只监听 127.0.0.1:8765，提供两个独立页面：

• /：调用数量、每日趋势、Skill 排名、作用域分布和最近调用；
• /relations：调用顺序、同轮共现和线程内相邻调用图谱。

页面只通过本机 API 查询同一个 SQLite；“同步最新历史”仍然只读 Codex rollout，并把新增事件 写入旁路数据库。

隐私边界

数据库不保存用户消息、助手消息、推理内容、完整 shell 命令或工具输出。只保存：

• Skill 名称、规范化路径和作用域；
• 线程 ID、轮次 ID、时间戳和当时的工作目录；
• 证据类型、源 JSONL 路径和行号；
• 增量读取的文件偏移量。

rollout 是 Codex 的本地内部格式，不是公开稳定 API。解析器对未知事件采取跳过策略，并通过 源文件偏移量和稳定事件 ID 保证重复同步不会重复计数。

为保证处理超大历史文件时内存有明确上限，单条 JSONL 记录最多读取 16 MiB；超过上限的记录 会跳过并单独计入 oversized_lines，不会混入 malformed_lines。Skill 工具调用记录通常远小于 该上限，但被跳过的记录不会声称已经覆盖。