CodexMonitor

CodexMonitor 是一款基于 Tauri 的应用，用于在本地工作区中编排多个 Codex 代理。它提供了一个侧边栏来管理项目、一个用于快速操作的主屏幕，以及基于 Codex 应用服务器协议的对话视图。

功能特性

工作区与线程

• 添加并持久化工作区，对其进行分组和排序，并从主页仪表板快速跳转到最近的代理活动。
• 每个工作区启动一个 codex app-server 实例，恢复线程并跟踪未读及运行状态。
• 使用工作树和克隆代理进行隔离工作；工作树存储在应用数据目录下（支持旧版 .codex-worktrees）。
• 线程管理：固定/重命名/归档/复制，每个线程都有草稿功能，并可停止或中断正在进行的回合。
• 可选的远程后端（守护进程）模式，用于在另一台机器上运行 Codex。
• 远程设置助手，用于自托管连接（检测 Tailscale 或为 TCP 模式引导主机）。

编辑器与代理控制

• 支持图片附件（通过选择器、拖放或粘贴），并可配置后续行为（在运行时选择“队列”或“转向”）。
• 使用 Shift+Cmd+Enter（macOS）或 Shift+Ctrl+Enter（Windows/Linux）发送单条消息的相反后续操作。
• 自动补全技能（$）、提示词（/prompts:）、评审（/review）和文件路径（@）。
• 模型选择器、协作模式（启用时）、推理力度、访问模式和上下文使用环形控件。
• 语音输入支持长按说话快捷键和实时波形显示（Whisper）。
• 渲染推理/工具/差异项，并处理批准提示。

Git 与 GitHub

• 显示差异统计、暂存/未暂存文件差异、撤销/暂存控件以及提交日志。
• 分支列表支持检出/创建分支，并显示上游领先或落后数量。
• 通过 gh 工具查看 GitHub Issues 和 Pull Requests（列表、差异、评论），并在浏览器中打开提交和 PR。
• PR 编辑器：“Ask PR”可将 PR 上下文发送到新的代理线程。

文件与提示库

• 文件树支持搜索、文件类型图标，并可在 Finder 或资源管理器中显示文件位置。
• 提示库用于全局或工作区级别的提示：可创建/编辑/删除/移动提示，并在当前或新线程中运行。

用户界面与体验

• 可调整大小的侧边栏、右侧面板、计划面板、终端和调试面板，尺寸会持久保存。
• 响应式布局（桌面、平板、手机），支持标签页导航。
• 侧边栏使用情况和账户配额计量器，以及主页使用情况快照。
• 终端停靠区支持多标签页后台命令（实验性功能）。
• 应用内更新通过提示框驱动下载和安装，调试面板可复制或清空内容，支持声音通知，并提供平台特定的窗口效果（macOS 的叠加标题栏 + 鲜艳效果），以及透明度降低开关。

系统要求

• Node.js + npm
• Rust 工具链（稳定版）
• CMake（构建原生依赖所需；语音输入/Whisper 使用 CMake）
• LLVM/Clang（Windows 上需要 Clang 来通过 bindgen 构建语音输入依赖）
• 已安装 Codex CLI，并可在 PATH 中以 codex 命令调用（或在应用/工作区设置中配置自定义 Codex 二进制文件）
• Git CLI（用于工作树操作）
• GitHub CLI (gh) 用于 GitHub Issues/PR 集成（可选）

如果遇到原生构建错误，请运行：

npm run doctor

快速开始

安装依赖：

npm install

以开发模式运行：

npm run tauri:dev

iOS 支持（开发中）

iOS 支持目前仍在开发中。

• 当前状态：移动端布局已运行，远程后端流程已打通，iOS 默认使用远程后端模式。
• 当前限制：终端和语音输入功能在移动端版本中仍不可用。
• 桌面端行为保持不变：macOS、Linux 和 Windows 仍以本地优先，除非显式选择远程模式。

iOS + Tailscale 设置（TCP）

当您需要通过 Tailscale 尾网将 iOS 应用连接到桌面托管的守护进程时，请使用此方法。 官方指南：docs/mobile-ios-tailscale-blueprint.md。

1. 在桌面和 iPhone 上分别安装并登录 Tailscale（同一尾网）。
2. 在桌面版 CodexMonitor 中，打开 设置 > 服务器。
3. 设置一个 远程后端令牌。
4. 在 移动访问守护进程 中，点击 启动守护进程。
5. 在 Tailscale 助手 中，使用 检测 Tailscale 功能，并记下建议的主机地址（例如 your-mac.your-tailnet.ts.net:4732）。
6. 在 iOS 版 CodexMonitor 中，打开 设置 > 服务器。
7. 输入桌面端的 Tailscale 主机地址和相同的令牌。
8. 点击 连接并测试，确认连接成功。

注意事项：

• 桌面守护进程必须在 iOS 连接期间保持运行。
• 如果测试失败，请确认两台设备都在 Tailscale 中在线，并且主机地址和令牌与桌面设置一致。

无桌面 UI 的独立守护进程管理

当您希望在不打开桌面应用的情况下启用 iOS 远程模式时，可以使用独立的守护进程控制 CLI。

构建二进制文件：

cd src-tauri
cargo build --bin codex_monitor_daemon --bin codex_monitor_daemonctl

示例：

# 查看当前守护进程状态
./target/debug/codex_monitor_daemonctl status

# 使用 settings.json 中的主机和令牌启动守护进程
./target/debug/codex_monitor_daemonctl start

# 停止守护进程
./target/debug/codex_monitor_daemonctl stop

# 打印等效的启动命令
./target/debug/codex_monitor_daemonctl command-preview

常用选项：

• --data-dir <path>：包含 settings.json 和 workspaces.json 的应用数据目录。
• --listen <addr>：覆盖绑定地址。
• --token <token>：覆盖令牌。
• --daemon-path <path>：指定 codex-monitor-daemon 二进制文件路径。
• --json：输出机器可读格式。

iOS 前置条件

• 已安装 Xcode 和命令行工具。
• 已安装 Rust 的 iOS 目标：

rustup target add aarch64-apple-ios aarch64-apple-ios-sim
# 可选（Intel Mac 模拟器构建）：
rustup target add x86_64-apple-ios

• 已配置 Apple 签名（开发团队）。
  • 在 src-tauri/tauri.ios.local.conf.json 中设置 bundle.iOS.developmentTeam 和 identifier（推荐用于本地机器设置），或
  • 在 src-tauri/tauri.ios.conf.json 中设置这些值，或
  • 在设备脚本中传递 --team <TEAM_ID>。
  • build_run_ios*.sh 和 release_testflight_ios.sh 会自动合并 src-tauri/tauri.ios.local.conf.json（如果存在）。

在 iOS 模拟器上运行

./scripts/build_run_ios.sh

选项：

• --simulator "<name>"：指定目标模拟器。
• --target aarch64-sim|x86_64-sim：覆盖架构。
• --skip-build：复用当前的应用包。
• --no-clean：保留 src-tauri/gen/apple/build 目录，以便多次构建。

在 USB 设备上运行

列出可发现的设备：

./scripts/build_run_ios_device.sh --list-devices

在特定设备上构建、安装并启动：

./scripts/build_run_ios_device.sh --device "<设备名称或标识符>" --team <TEAM_ID>

附加选项：

• --target aarch64 用于覆盖架构。
• --skip-build 用于复用当前的应用程序包。
• --bundle-id <id> 用于启动非默认的捆绑包标识符。

首次设置设备通常需要：

1. iPhone 已解锁，并已信任此 Mac。
2. iPhone 上已启用开发者模式。
3. 至少在 Xcode 中批准过一次配对/签名。

如果签名尚未准备好，可以从脚本流程中打开 Xcode：

./scripts/build_run_ios_device.sh --open-xcode

iOS TestFlight 发布（脚本化）

使用端到端脚本归档、上传、配置合规性、分配测试组并提交进行 Beta 审核。

./scripts/release_testflight_ios.sh

该脚本会自动从 .testflight.local.env（已忽略于 Git）加载发布元数据。对于新设置，请将 .testflight.local.env.example 复制到 .testflight.local.env 并填写相应值。

发布构建

构建生产环境的 Tauri 包：

npm run tauri:build

生成的工件将位于 src-tauri/target/release/bundle/（平台特定子文件夹）。

Windows（可选）

Windows 构建是可选的，并使用单独的 Tauri 配置文件，以避免 macOS 专用的窗口效果。

npm run tauri:build:win

生成的工件将位于：

• src-tauri/target/release/bundle/nsis/（安装程序 exe）
• src-tauri/target/release/bundle/msi/（msi）

注意：在 Windows 上从源代码构建需要 LLVM/Clang（用于 bindgen / libclang），以及 CMake。

类型检查

运行 TypeScript 检查器（不输出）：

npm run typecheck

注意：npm run build 也会在打包前端之前运行 tsc。

验证

推荐的验证命令：

npm run lint
npm run test
npm run typecheck
cd src-tauri && cargo check

代码库导航

对于任务导向的文件查找（“如果你需要 X，就编辑 Y”），请使用：

• docs/codebase-map.md

项目结构

src/
  features/         功能拆分的 UI + hooks
  features/app/bootstrap/      应用启动编排
  features/app/orchestration/  应用布局/线程/工作区编排
  features/threads/hooks/threadReducer/  线程 reducer 分片
  services/         Tauri IPC 封装
  styles/           按区域划分的 CSS
  types.ts          共享类型
src-tauri/
  src/lib.rs        Tauri 应用后端命令注册表
  src/bin/codex_monitor_daemon.rs  远程守护进程 JSON-RPC 进程
  src/bin/codex_monitor_daemon/rpc/  守护进程 RPC 域处理程序
  src/shared/       应用 + 守护进程共用的后端核心
  src/shared/git_ui_core/      git/github 共用核心模块
  src/shared/workspaces_core/  作业空间/工作树共用核心模块
  src/workspaces/   作业空间/工作树适配器
  src/codex/        codex 应用服务器适配器
  src/files/        文件适配器
  tauri.conf.json   窗口配置

笔记

• 工作区会持久化到应用数据目录下的 workspaces.json。
• 应用设置会持久化到应用数据目录下的 settings.json（主题、后端模式/提供商、远程端点/令牌、Codex 路径、默认访问模式、UI 缩放、后续消息行为）。
• 功能设置在 UI 中支持，并在加载/保存时同步到 $CODEX_HOME/config.toml（或 ~/.codex/config.toml）。稳定功能包括：协作模式（features.collaboration_modes）、个性（personality）和后台终端（features.unified_exec）。实验性功能包括：应用（features.apps）。控制能力仍遵循 Codex 的 features.steer，但后续默认行为由设置 → Composer 控制。
• 启动时及窗口获得焦点时，应用会重新连接并刷新每个工作区的线程列表。
• 线程通过使用工作区的 cwd 过滤 thread/list 结果来恢复。
• 选择线程时始终调用 thread/resume 以从磁盘刷新消息。
• 如果 CLI 会话的 cwd 与工作区路径匹配，则会显示；除非被恢复，否则不会实时显示。
• 应用通过 stdio 使用 codex app-server；详见 src-tauri/src/lib.rs 和 src-tauri/src/codex/。
• 远程守护进程入口点为 src-tauri/src/bin/codex_monitor_daemon.rs；RPC 路由位于 src-tauri/src/bin/codex_monitor_daemon/rpc.rs，域处理程序位于 src-tauri/src/bin/codex_monitor_daemon/rpc/。
• 共享域逻辑位于 src-tauri/src/shared/（尤其是 src-tauri/src/shared/git_ui_core/ 和 src-tauri/src/shared/workspaces_core/）。
• Codex 主目录根据工作区设置（若已设置）解析，其次为旧版 .codexmonitor/，最后为 $CODEX_HOME/~/.codex。
• 工作树代理位于应用数据目录下（worktrees/<workspace-id>）；旧版 .codex-worktrees/ 路径仍受支持，且应用不再编辑仓库的 .gitignore 文件。
• UI 状态（面板大小、透明度切换、最近线程活动）存储在 localStorage 中。
• 自定义提示从 $CODEX_HOME/prompts（或 ~/.codex/prompts）加载，可选带前言描述/参数提示。

Tauri IPC 接口

前端调用位于 src/services/tauri.ts 中，并映射到 src-tauri/src/lib.rs 中的命令。当前接口包括：

• 设置/配置/文件：get_app_settings、update_app_settings、get_codex_config_path、get_config_model、file_read、file_write、codex_doctor、menu_set_accelerators。
• 工作区/工作树：list_workspaces、is_workspace_path_dir、add_workspace、add_clone、add_worktree、worktree_setup_status、worktree_setup_mark_ran、rename_worktree、rename_worktree_upstream、apply_worktree_changes、update_workspace_settings、remove_workspace、remove_worktree、connect_workspace、list_workspace_files、read_workspace_file、open_workspace_in、get_open_app_icon。
• 线程/回合/评审：start_thread、fork_thread、compact_thread、list_threads、resume_thread、archive_thread、set_thread_name、send_user_message、turn_interrupt、respond_to_server_request、start_review、remember_approval_rule、get_commit_message_prompt、generate_commit_message、generate_run_metadata。
• 账户/模型/协作：model_list、account_rate_limits、account_read、skills_list、apps_list、collaboration_mode_list、codex_login、codex_login_cancel、list_mcp_server_status。
• Git/GitHub：get_git_status、list_git_roots、get_git_diffs、get_git_log、get_git_commit_diff、get_git_remote、stage_git_file、stage_git_all、unstage_git_file、revert_git_file、revert_git_all、commit_git、push_git、pull_git、fetch_git、sync_git、list_git_branches、checkout_git_branch、create_git_branch、get_github_issues、get_github_pull_requests、get_github_pull_request_diff、get_github_pull_request_comments。
• 提示词：prompts_list、prompts_create、prompts_update、prompts_delete、prompts_move、prompts_workspace_dir、prompts_global_dir。
• 终端/听写/通知/使用情况：terminal_open、terminal_write、terminal_resize、terminal_close、dictation_model_status、dictation_download_model、dictation_cancel_download、dictation_remove_model、dictation_request_permission、dictation_start、dictation_stop、dictation_cancel、send_notification_fallback、is_macos_debug_build、local_usage_snapshot。
• 远程后端辅助工具：tailscale_status、tailscale_daemon_command_preview、tailscale_daemon_start、tailscale_daemon_stop、tailscale_daemon_status。

CodexMonitor 快速上手指南

CodexMonitor 是一款基于 Tauri 构建的桌面应用，旨在协调本地工作区中的多个 Codex 智能体（Agents）。它提供侧边栏项目管理、主页快捷操作以及基于 Codex 应用服务器协议的对话视图。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

系统依赖

• Node.js + npm: 用于前端构建和依赖管理。
• Rust 工具链 (stable): 用于编译 Tauri 后端。
• CMake: 构建原生依赖项所需（特别是语音识别/Whisper 功能）。
• LLVM/Clang:
  • Windows 用户必须安装，用于通过 bindgen 构建语音识别依赖。
  • macOS/Linux 通常已预装或通过 Xcode Command Line Tools 提供。
• Git CLI: 用于工作树（worktree）操作。
• GitHub CLI (gh): （可选）用于集成 GitHub Issues 和 Pull Requests。

Codex 环境

• Codex CLI: 必须已安装并在 PATH 中可用（命令为 codex），或者在应用设置中配置自定义二进制路径。

提示：如果遇到原生构建错误，可运行 npm run doctor 进行诊断。

安装步骤

1. 克隆项目

首先获取源代码（假设您已 fork 或拥有仓库权限）：

git clone https://github.com/Dimillian/CodexMonitor.git
cd CodexMonitor

2. 安装依赖

使用 npm 安装前端及构建依赖：

npm install

(注：国内开发者若遇网络问题，可配置 npm 镜像源，例如：npm config set registry https://registry.npmmirror.com)

3. 验证环境（可选）

运行类型检查和代码验证以确保环境就绪：

npm run typecheck
npm run lint
cd src-tauri && cargo check

基本使用

启动开发模式

安装完成后，直接运行以下命令启动开发服务器。这将同时构建前端并运行 Tauri 桌面应用窗口：

npm run tauri:dev

核心功能概览

应用启动后，您将看到以下主要界面和功能：

1. 工作区管理 (Workspaces)

   • 在侧边栏添加本地项目文件夹作为工作区。
   • 每个工作区会自动启动一个独立的 codex app-server 实例。
   • 支持查看最近的活动线程、未读消息及运行状态。

2. 智能体交互 (Composer)

   • 在对话框中输入指令，支持图片拖拽上传。
   • 快捷键：使用 Shift+Cmd+Enter (macOS) 或 Shift+Ctrl+Enter (Win/Linux) 发送相反类型的跟进消息（如在运行时切换“排队”与“引导”模式）。
   • 自动补全：输入 $ (技能), /prompts: (提示词), @ (文件路径) 可获得智能提示。

3. Git 集成

   • 查看文件差异统计、暂存/取消暂存文件。
   • 直接管理分支（检出/创建）及查看上游同步状态。
   • 若安装了 gh，可直接在应用内查看和操作 GitHub Issues 与 PR。

4. 远程模式 (可选)

   • 如需在手机端（iOS）或其他设备连接此实例，可在 Settings > Server 中启用 "Remote backend" 模式，并配合 Tailscale 进行组网连接。

构建生产版本

如果您需要生成可分发的安装包：

macOS / Linux:

npm run tauri:build

产物位于 src-tauri/target/release/bundle/。

Windows (需显式指定):

npm run tauri:build:win

产物包含 NSIS 安装程序 (.exe) 和 MSI 安装包。