# TurnScope

[![CI](https://github.com/tageecc/turnscope/actions/workflows/ci.yml/badge.svg)](https://github.com/tageecc/turnscope/actions/workflows/ci.yml) · [MIT License](LICENSE) · [English](README.md)

TurnScope 是用于分析 Codex 本地会话耗时的只读终端工具。它关联 rollout 记录、thread 元数据与 SQLite telemetry，以 Turn 为单位展示耗时、Tool 活动、Skill 与 MCP 归因以及 Token 用量。

所有分析均在本机完成。TurnScope 不修改 Codex 状态，也不传输会话数据。

![TurnScope 时间线与事件详情](docs/turnscope-preview.svg)

## 运行要求

- 本地 Codex 状态目录，其中包含 `state_5.sqlite`、`logs_2.sqlite` 和会话 rollout 文件
- 使用 npm 安装时需要 Node.js 18 或更高版本；从源码安装时需要 Go 1.26 或更高版本

默认状态目录为 `~/.codex`。

## 安装

通过 npm 安装 TurnScope：

```bash
npm install --global turnscope
turnscope --latest
```

也可以直接运行：

```bash
npx turnscope --latest
```

npm 包支持 macOS、Linux 和 Windows 的 ARM64 与 x64 平台。六个平台的原生二进制均包含在唯一的 `turnscope` 包中，安装过程不执行额外的下载脚本。

通过 Go 安装：

```bash
go install github.com/tageecc/turnscope/cmd/turnscope@latest
```

从源码构建：

```bash
git clone https://github.com/tageecc/turnscope.git
cd turnscope
make build
```

## 使用

打开会话选择器：

```bash
turnscope
```

打开最新会话、指定 thread 或指定 Turn：

```bash
turnscope --latest
turnscope --thread THREAD_ID
turnscope --thread THREAD_ID --turn 0
```

直接输出报告，不启动 TUI：

```bash
turnscope --latest --plain
```

### 命令行选项

| 选项 | 说明 | 默认值 |
| --- | --- | --- |
| `--codex-home PATH` | Codex 状态目录 | `~/.codex` |
| `--thread ID` | 打开指定 thread | 会话选择器 |
| `--latest` | 打开最近更新的 thread | 关闭 |
| `--turn N` | 打开从 0 开始编号的 Turn | 最后一个 Turn |
| `--plain` | 输出文本报告，不启动 TUI | 关闭 |
| `--no-motion` | 关闭 TUI 动效 | 关闭 |
| `--limit N` | 会话选择器最多加载的会话数 | `100` |
| `--version` | 输出版本信息 | 关闭 |

## 视图

| 视图 | 展示内容 |
| --- | --- |
| Overview | Turn 总耗时、首 Token、首段可见输出、Tool wall time、Model / orchestration 残差和数据源统计 |
| Timeline | 已记录事件的 Waterfall、并行 Tracks 和比例 Flame Allocation |
| Tools | Tool 名称、来源、记录耗时、相对耗时占比和 Skill 归因 |
| Skills | direct/inferred 归因、调用次数、Tool 累计耗时以及首个到最后一个归因调用的 wall span |
| MCP | Server readiness、Tool cache 状态、可用 Tool 数、调用次数和调用耗时 |
| Tokens | Input、cached input、total output、reasoning output、estimated visible output、上下文占用和吞吐率 |

在 Timeline 中选中事件并按 `Enter` 可打开详情。Tool 事件会在相应字段可用时显示已记录的 Input、Output 预览、路由信息、状态和总耗时。Summary、Input 和 Output 页面只展示 Codex 本地记录中实际存在的数据；加密的 Reasoning payload 不会被解码。

## Timeline 快捷键

| 按键 | 操作 |
| --- | --- |
| `v` | 在 Waterfall、Tracks 和 Flame Allocation 之间切换 |
| `j/k`、`↑/↓`、`,/.` | 选择事件 |
| `h/l` | 平移时间窗口 |
| `+/-` | 围绕当前事件缩放 |
| `f` | 聚焦当前事件；再次按下恢复整个 Turn |
| `/` | 按事件、Tool、Skill、MCP、详情文本或 Call ID 筛选 |
| `c` | 只显示包含耗时区间的事件 |
| `Enter` | 打开或关闭事件详情 |
| `Tab`、`Shift+Tab` | 切换详情页 |
| `s`、`i`、`o` | 打开 Summary、Input 或 Output |
| `PgUp/PgDn`、`Ctrl+U/Ctrl+D`、`Home/End` | 滚动详情 |

使用 `←/→` 或 `1`–`6` 切换主视图，`[`/`]` 切换 Turn，`r` 重新加载数据，`Esc` 返回上一层。

## 计时口径

| 指标 | 定义 |
| --- | --- |
| Turn duration | 已完成 Turn 使用 `task_complete` 记录的 `duration_ms`；仍在运行且缺少 `task_complete` 时，使用 `task_started` 到最后一条已记录事件的区间。 |
| Time to first token | Codex 在 Turn 完成时记录的 `time_to_first_token_ms`，该时间点可能早于首段可见文本。 |
| First visible output | `task_started` 到第一条 `response.content_part.added` 的区间。 |
| Tool cumulative time | 当前 Turn 内所有 Tool 调用时长之和，重叠调用分别计入。 |
| Tool wall time | Tool 执行区间的并集，并发调用的重叠部分只计一次。 |
| Visible output time | 第一条 `response.content_part.added` 到最后一条 `response.output_text.done` 的区间。 |
| Model / orchestration | `max(0, Turn duration - Tool wall time - Visible output time)`。该残差可能包含请求传输、服务端等待、上下文处理、模型推理和客户端编排，不等同于模型推理耗时。 |
| Flame Allocation | 按比例展示 Model / orchestration、Tool wall time 和 Visible output time，并非 CPU 采样调用栈。 |

依赖缺失 telemetry 的指标保持为空，不使用估算值补全。

## 数据处理

TurnScope 读取以下文件：

```text
~/.codex/sessions/**/rollout-*.jsonl
~/.codex/state_5.sqlite
~/.codex/logs_2.sqlite
```

SQLite 使用 `mode=ro` 和 `query_only(1)` 打开，同时兼容数据库位于 `~/.codex/sqlite/` 的目录结构。

每次 Tool 调用最多保留 64 KiB Output 作为内存预览，报告元数据仍记录完整大小。Reasoning 详情仅包含 Codex 已落盘的明文 summary 或 content。

会话记录可能包含 Prompt、Tool 参数、Output 和本地路径。复制或公开详情前应检查相关内容。

## 开发

```bash
make test
go test -race ./...
go vet ./...
make build
make npm-test
make npm-packages
```

贡献规范见 [CONTRIBUTING.md](CONTRIBUTING.md)，漏洞报告方式见 [SECURITY.md](SECURITY.md)。

## 许可证

[MIT](LICENSE)

TurnScope 是独立项目，与 OpenAI 没有隶属关系。