# codex_manager

**Repository Path**: jamie_818/codex_manager

## Basic Information

- **Project Name**: codex_manager
- **Description**: codex终端管理器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex 原生会话管理器

本项目是一个本地桌面端 Codex 原生会话管理器，核心场景是集中管理多个目录下的 Codex CLI 会话。它提供目录管理、原生历史扫描、会话详情展示、标题生成和应用内续聊能力，运行环境以 Windows 为主，依赖本机 Codex CLI 与现有登录态。

## 界面示意

下图为脱敏后的界面样例图，所有目录名、路径、会话标题和消息内容均为演示数据。

![Codex 原生会话管理器界面示意](assets/screenshots/ui-demo-v1.0.5.svg)

## 主要能力
- 目录列表管理：新增、编辑、删除、打开目录。
- 目录活跃度展示：左侧目录显示最近会话时间、最近会话标题/摘要，并按最近活跃时间自动排序。
- 原生会话扫描：读取 `~/.codex/sessions/` 下的 `.jsonl` 会话文件，并按目录筛选。
- 项目备注与搜索：支持为目录保存备注，并按目录名或备注快速筛选。
- 会话搜索与筛选：支持按标题和摘要搜索会话，并按最近 7 天、未命名、消息数等条件筛选。
- 会话详情与对话展示：显示会话元信息、摘要预览与消息气泡，支持历史折叠与滚动。
- 会话标题增强：自动生成更友好的中文标题（保存在本地状态文件）。
- 应用内续聊：在界面内直接发送消息，支持中断与运行过程反馈。
- 外部终端入口：通过 Windows Terminal 打开新的 Codex 会话或恢复已有会话。
- 默认软件图标：当前默认使用 `assets/icons/icon-01-terminal-orbit.ico`，同时用于窗口图标和 `exe` 打包图标。

## 当前 UI 技术栈
- 主界面已切换到 `PySide6 / Qt`。
- 仓库内仍保留旧的 Tkinter 代码，作为过渡期参考实现，不再作为默认入口。

## 项目结构
- `src/main.py`：程序入口。
- `src/codex_terminal_manager/app.py`：Tkinter 主界面与交互逻辑。
- `src/codex_terminal_manager/store.py`：应用状态持久化。
- `src/codex_terminal_manager/codex_native.py`：原生会话读取与解析。
- `src/codex_terminal_manager/chat_runner.py`：`codex exec` / `resume` 调用与事件解析。
- `src/codex_terminal_manager/codex_cli.py`：定位 Codex CLI 可执行文件。
- `docs/`：设计说明、功能梳理与迭代记录。

## 运行环境
- Python 3.11+（建议与本机 Codex CLI 匹配的版本）
- PySide6 6.10.2
- Windows 10/11（默认通过 Windows Terminal 拉起外部会话）
- 已安装并可用的 Codex CLI（`codex`）

如果系统中只有 `codex.ps1`，还需要可用的 `pwsh`。

## 本地运行
```powershell
python -m pip install -r requirements.txt
$env:PYTHONPATH='src'
python src\main.py
```

## 图标资源
- 图标方案目录：`assets/icons/`
- 当前选定默认图标：`icon-01-terminal-orbit`
- 可批量重新生成图标资源：
  ```powershell
  powershell -ExecutionPolicy Bypass -File tools\generate_icons.ps1
  ```
- 推荐使用打包脚本生成 `exe`，它会自动清理残留的 `TCL_LIBRARY` / `TK_LIBRARY` 并选择可用的 Qt Python 环境：
  ```powershell
  powershell -ExecutionPolicy Bypass -File tools\build_exe.ps1
  ```

## 运行测试
```powershell
$env:PYTHONPATH='src'
python -m unittest discover -s tests
```

## 使用提示
- 原生会话数据来自 `~/.codex/sessions/`，请勿直接把真实会话文件提交到仓库。
- 本地状态文件默认写入 `%USERPROFILE%/.codex/.codex_terminal_manager/`，不可写时回退到 `%LOCALAPPDATA%/CodexTerminalManager/`。
- 性能诊断日志默认写入与状态文件同目录下的 `perf.log`，可用于分析切目录/切会话卡顿。
- 左侧目录列表会按最近会话时间自动排序，并显示最新会话缩略。
- 中间会话列表支持搜索、筛选，并显示更新时间、消息数和摘要缩略。
- 工具栏的“终端新建会话 / 终端恢复会话”会拉起外部 Windows Terminal。
- “删除原生会话”会直接删除对应 `.jsonl` 文件，且不可恢复。

## 下载与发布
- 可执行文件随发布标签提供，当前版本对应标签：`v1.0.6`。
- 标签产物位于 `dist/codex会话管理器-V1.0.6.exe`。
- Gitee 的 tag 页面默认只提供源码归档；Windows `exe` 需要作为 Release 附件单独上传。
- 直接下载：`https://gitee.com/jamie_818/codex_manager/releases/download/v1.0.6/codex%E4%BC%9A%E8%AF%9D%E7%AE%A1%E7%90%86%E5%99%A8-V1.0.6.exe`

## 打包说明
- 打包 `exe` 时优先使用：
  ```powershell
  powershell -ExecutionPolicy Bypass -File tools\build_exe.ps1
  ```
- 若需手动执行 `PyInstaller`，应先清理残留的 `TCL_LIBRARY` / `TK_LIBRARY`，再显式指定默认图标，并把运行时所需的 `png` / `ico` 一并打入包内：
  ```powershell
  Remove-Item Env:TCL_LIBRARY -ErrorAction SilentlyContinue
  Remove-Item Env:TK_LIBRARY -ErrorAction SilentlyContinue
  py -3.14 -m PyInstaller --noconfirm --clean --windowed --onefile --name "codex会话管理器-V1.0.6" --icon "assets\icons\icon-01-terminal-orbit.ico" --add-data "assets\icons\icon-01-terminal-orbit.ico;assets/icons" --add-data "assets\icons\icon-01-terminal-orbit.png;assets/icons" --add-data "assets\icons\chevron-down.svg;assets/icons" src\main.py
  ```

## 文档入口
- 功能梳理：`docs/codex-原生会话管理器-功能梳理.md`
- 迭代记录：`docs/codex-原生会话管理器-迭代记录.md`
- 设计文档：`docs/V1.0.1-工具栏动作澄清迭代设计.md`
- 打包说明：`docs/V1.0.2-Windows可执行包打包说明.md`