codex-workspaces 0.1.0__tar.gz → 0.2.0__tar.gz

{codex_workspaces-0.1.0 → codex_workspaces-0.2.0}/CHANGELOG.md

@@ -11,6 +11,13 @@ This project follows a simple changelog format while it is still pre-release.
 - Added the cross-platform Python 3 package with the `codex-workspaces` console script.
 - Added Linux/macOS symlink switching and Windows symlink/junction support.
 - Added Python unit tests for workspace validation, creation, migration, switching, CLI dispatch, and platform safety behavior.
+- Added `doctor` diagnostics for platform, path, link, and Codex terminal status.
+- Added workspace size and modified-time metadata to `list`.
+- Added workspace `rename`, guarded `delete --force`, and local `note` management.
+- Added read-only local SQLite token usage stats with `stats`.
+- Added the unified `~/.codex-workspaces/` root with workspace metadata, account snapshots, and default-account restore behavior.
+- Added legacy workspace migration with `migrate`, `migrate --dry-run`, and `init <workspace> --migrate-current`.
+- Added legacy account import with `accounts import-legacy` and workspace auth import with `accounts import-workspaces`.
 - Added `pyproject.toml`, package metadata, editable install support, and PyPI-ready build configuration.
 - Added GitHub Actions CI for Linux, macOS, Windows, and Python 3.9/3.11/3.13.
 - Added GitHub Actions Trusted Publishing workflow for PyPI releases.
@@ -20,9 +27,7 @@ This project follows a simple changelog format while it is still pre-release.
 - Added current workspace inspection.
 - Added workspace switching through the active `~/.codex` symlink.
 - Added Codex app stop, start, and restart commands.
-- Added workspace creation with `codex-workspaces create <workspace>`.
-- Added first-time migration with `codex-workspaces create <workspace> --migrate-current`.
-- Added `--migrate` as a short alias for `--migrate-current`.
+- Added workspace initialization with `codex-workspaces init <workspace>`.
 - Added self-install support with `codex-workspaces install [directory]`.
 - Added English and Chinese command output, controlled by system language or `CODEX_WORKSPACES_LANG`.
 - Renamed the command, package, module, docs, and environment variables to `codex-workspaces` / `CODEX_WORKSPACES_*`.
@@ -33,7 +38,8 @@ This project follows a simple changelog format while it is still pre-release.
 - Refuses to switch workspaces when `~/.codex` exists but is not a symlink.
 - Delegates stop, switch, and restart commands to Terminal.app when they are run from a detected Codex terminal environment.
 - Refuses start and migration commands when they are run from a detected Codex terminal environment.
-- Refuses first-time migration while the Codex app is still running.
-- Refuses first-time migration when the script cannot confirm whether the Codex app is running.
-- Refuses first-time migration when the target workspace directory already exists.
+- Backs up legacy workspace/account sources before migration and never deletes old directories automatically.
+- Keeps login-temp account login flows deferred instead of mixing interactive login into migration.
+- Saves live `auth.json` before account or workspace switches when an active account is configured.
+- Uses a lock file under `~/.codex-workspaces/lock` for account and workspace switching.
 - Limits workspace names to letters, numbers, dots, underscores, and hyphens.

{codex_workspaces-0.1.0 → codex_workspaces-0.2.0}/MANIFEST.in

@@ -1,5 +1,4 @@
 include CHANGELOG.md
 include README.zh-CN.md
-include codex-workspaces
 recursive-include docs *.md
 recursive-include tests *.py

{codex_workspaces-0.1.0/src/codex_workspaces.egg-info → codex_workspaces-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-workspaces
-Version: 0.1.0
+Version: 0.2.0
 Summary: Cross-platform Codex workspace switcher with a preserved macOS shell workflow.
 Author: blockchain-project-lives
 Project-URL: Homepage, https://github.com/blockchain-project-lives/codex-workspaces
@@ -30,21 +30,25 @@ Requires-Dist: twine>=5; extra == "dev"
 
 English | [简体中文](README.zh-CN.md) | [Changelog](CHANGELOG.md)
 
-`codex-workspaces` switches between multiple Codex workspace directories by keeping each workspace in `~/.codex-<name>` and pointing the active `~/.codex` path at the selected workspace.
+`codex-workspaces` switches between multiple Codex workspace directories under `~/.codex-workspaces/workspaces/` and points the active `~/.codex` path at the selected workspace.
 
 The project now has two entry points:
 
 - A cross-platform Python 3 CLI for Linux, macOS, and Windows.
-- The original macOS Bash script, still kept at [`codex-workspaces`](codex-workspaces), for users who installed the shell workflow directly.
+- The original macOS Bash script, still kept at [`macos/codex-workspaces`](macos/codex-workspaces), for users who installed the shell workflow directly.
 
 On macOS, the Python CLI preserves the original app workflow: stop Codex App, switch the workspace link, and start Codex App again. On Linux and Windows, app control is skipped and the CLI only switches the workspace link.
 
 ## Features
 
-- Manage workspace directories such as `~/.codex-work` and `~/.codex-personal`.
+- Manage workspace directories such as `~/.codex-workspaces/workspaces/work`.
+- Manage account snapshots under `~/.codex-workspaces/accounts/`.
 - Switch the active `~/.codex` symlink or directory link.
-- Create workspace directories and migrate an existing real `~/.codex` directory.
+- Initialize workspace directories with metadata.
+- Temporarily switch the current workspace account with `accounts use`, then restore the workspace default account.
+- Migrate older `~/.codex-<name>` workspaces and import legacy `~/.codex-accounts` auth snapshots.
 - Keep macOS Codex App stop/start/restart support.
+- Show local token usage stats from Codex `state_*.sqlite` in read-only mode.
 - Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
 - Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
 - Package as a Python project with tests, CI, and PyPI publishing workflow.
@@ -76,10 +80,10 @@ Install from a local checkout for development:
 python3 -m pip install -e ".[dev]"
 ```
 
-The legacy macOS shell installer is still available:
+The legacy macOS shell installer is still available from the `macos/` directory:
 
 ```bash
-tmp="$(mktemp -t codex-workspaces.XXXXXX)" && curl -fsSL https://raw.githubusercontent.com/blockchain-project-lives/codex-workspaces/main/codex-workspaces -o "$tmp" && bash "$tmp" install && rm -f "$tmp"
+tmp="$(mktemp -t codex-workspaces.XXXXXX)" && curl -fsSL https://raw.githubusercontent.com/blockchain-project-lives/codex-workspaces/main/macos/codex-workspaces -o "$tmp" && bash "$tmp" install && rm -f "$tmp"
 ```
 
 ## Workspace Layout
@@ -88,25 +92,67 @@ Default layout:
 
 ```text
 ~/.codex           -> active workspace link
-~/.codex-work      workspace directory named work
-~/.codex-personal  workspace directory named personal
+~/.codex-workspaces/
+  config.json
+  state.json
+  lock
+  workspaces/
+    work/
+      auth.json
+      .codex-workspace.json
+    personal/
+      auth.json
+      .codex-workspace.json
+  accounts/
+    acct_work/
+      auth.json
+      meta.json
 ```
 
-Customize paths with `CODEX_WORKSPACES_LINK` and `CODEX_WORKSPACES_PREFIX`.
+Customize paths with `CODEX_WORKSPACES_LINK` and `CODEX_WORKSPACES_ROOT`.
 
 ## Usage
 
-Create workspaces:
+Initialize workspaces:
 
 ```bash
-codex-workspaces create personal
-codex-workspaces create work
+codex-workspaces init personal
+codex-workspaces init work
 ```
 
-If you already have a real `~/.codex` directory, migrate it first:
+Migrate older `~/.codex-<name>` directories without deleting the originals:
 
 ```bash
-codex-workspaces create personal --migrate-current
+codex-workspaces migrate --dry-run
+codex-workspaces migrate
+```
+
+If your current `~/.codex` is a real directory instead of a link, migrate it into a named workspace explicitly:
+
+```bash
+codex-workspaces init personal --migrate-current
+```
+
+Set up account snapshots after Codex has created an `auth.json` in the active workspace:
+
+```bash
+codex-workspaces use work --no-stop --no-start
+codex-workspaces accounts save work
+codex-workspaces accounts set-default work acct_work --activate
+codex-workspaces accounts list
+```
+
+Standalone accounts can be initialized and later populated from the current workspace `auth.json`:
+
+```bash
+codex-workspaces accounts init research
+codex-workspaces accounts save research
+```
+
+Import legacy `codex-accounts` AUTH-mode snapshots:
+
+```bash
+codex-workspaces accounts import-legacy ~/.codex-accounts
 ```
 
 Switch workspaces:
@@ -128,6 +174,28 @@ Inspect workspaces:
 ```bash
 codex-workspaces list
 codex-workspaces current
+codex-workspaces doctor
+codex-workspaces stats
+codex-workspaces stats work --days 14
+```
+
+Switch accounts within the current workspace:
+
+```bash
+codex-workspaces accounts use acct_personal
+codex-workspaces accounts restore-default
+```
+
+`accounts use` only changes the current workspace `active_account_id`; it does not change `default_account_id`. Entering a workspace with `codex-workspaces use <workspace>` restores that workspace's default account when one is configured.
+
+`auth.json` contains credentials. Do not commit workspace directories, account snapshots, SQLite state, sessions, or shell snapshots to git; the project `.gitignore` excludes these patterns for local checkouts.
+
+Manage workspace metadata and lifecycle:
+
+```bash
+codex-workspaces note work "main paid workspace"
+codex-workspaces rename work main
+codex-workspaces delete old-workspace --force
 ```
 
 Control Codex App on macOS:
@@ -138,6 +206,8 @@ codex-workspaces start
 codex-workspaces restart
 ```
 
+`stats` only reads local SQLite files such as `state_*.sqlite` or `sqlite/state_*.sqlite`. It does not call quota or refresh private APIs.
+
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -145,7 +215,7 @@ codex-workspaces restart
 | `CODEX_APP_NAME` | `Codex` | macOS app name to control. |
 | `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
 | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
-| `CODEX_WORKSPACES_PREFIX` | `$HOME/.codex-` | Workspace directory prefix. |
+| `CODEX_WORKSPACES_ROOT` | `$HOME/.codex-workspaces` | Managed root for workspaces, accounts, backups, and lock file. |
 | `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
 
 Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
@@ -163,6 +233,6 @@ Design, test, and release notes live in [`docs/`](docs/).
 
 ## Publishing
 
-CI runs tests on Linux, macOS, and Windows across Python 3.9, 3.11, and 3.13. The `Publish to PyPI` workflow builds and publishes distributions when a GitHub Release is published or the workflow is run manually.
+CI runs tests on Linux, macOS, and Windows across Python 3.9, 3.11, and 3.13. The `Publish to TestPyPI` workflow runs for `v*` tags, and the `Publish to PyPI` workflow publishes from `release/v*` branches or manual runs.
 
 Configure TestPyPI and PyPI Trusted Publishing for this repository before using the release workflows. See [`docs/RELEASE.zh-CN.md`](docs/RELEASE.zh-CN.md).

codex_workspaces-0.2.0/README.MD

@@ -0,0 +1,210 @@
+# codex-workspaces
+
+English | [简体中文](README.zh-CN.md) | [Changelog](CHANGELOG.md)
+
+`codex-workspaces` switches between multiple Codex workspace directories under `~/.codex-workspaces/workspaces/` and points the active `~/.codex` path at the selected workspace.
+
+The project now has two entry points:
+
+- A cross-platform Python 3 CLI for Linux, macOS, and Windows.
+- The original macOS Bash script, still kept at [`macos/codex-workspaces`](macos/codex-workspaces), for users who installed the shell workflow directly.
+
+On macOS, the Python CLI preserves the original app workflow: stop Codex App, switch the workspace link, and start Codex App again. On Linux and Windows, app control is skipped and the CLI only switches the workspace link.
+
+## Features
+
+- Manage workspace directories such as `~/.codex-workspaces/workspaces/work`.
+- Manage account snapshots under `~/.codex-workspaces/accounts/`.
+- Switch the active `~/.codex` symlink or directory link.
+- Initialize workspace directories with metadata.
+- Temporarily switch the current workspace account with `accounts use`, then restore the workspace default account.
+- Migrate older `~/.codex-<name>` workspaces and import legacy `~/.codex-accounts` auth snapshots.
+- Keep macOS Codex App stop/start/restart support.
+- Show local token usage stats from Codex `state_*.sqlite` in read-only mode.
+- Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
+- Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
+- Package as a Python project with tests, CI, and PyPI publishing workflow.
+
+## Requirements
+
+- Python 3.9 or newer for the Python CLI.
+- macOS is required only for Codex App control commands: `start`, `stop`, and `restart`.
+- Linux and macOS use directory symlinks.
+- Windows uses directory symlinks when available and falls back to directory junctions.
+
+## Install
+
+Install the Python CLI from PyPI:
+
+```bash
+python3 -m pip install codex-workspaces
+```
+
+For isolated CLI installs, `pipx` is recommended:
+
+```bash
+pipx install codex-workspaces
+```
+
+Install from a local checkout for development:
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+The legacy macOS shell installer is still available from the `macos/` directory:
+
+```bash
+tmp="$(mktemp -t codex-workspaces.XXXXXX)" && curl -fsSL https://raw.githubusercontent.com/blockchain-project-lives/codex-workspaces/main/macos/codex-workspaces -o "$tmp" && bash "$tmp" install && rm -f "$tmp"
+```
+
+## Workspace Layout
+
+Default layout:
+
+```text
+~/.codex           -> active workspace link
+~/.codex-workspaces/
+  config.json
+  state.json
+  lock
+  workspaces/
+    work/
+      auth.json
+      .codex-workspace.json
+    personal/
+      auth.json
+      .codex-workspace.json
+  accounts/
+    acct_work/
+      auth.json
+      meta.json
+```
+
+Customize paths with `CODEX_WORKSPACES_LINK` and `CODEX_WORKSPACES_ROOT`.
+
+## Usage
+
+Initialize workspaces:
+
+```bash
+codex-workspaces init personal
+codex-workspaces init work
+```
+
+Migrate older `~/.codex-<name>` directories without deleting the originals:
+
+```bash
+codex-workspaces migrate --dry-run
+codex-workspaces migrate
+```
+
+If your current `~/.codex` is a real directory instead of a link, migrate it into a named workspace explicitly:
+
+```bash
+codex-workspaces init personal --migrate-current
+```
+
+Set up account snapshots after Codex has created an `auth.json` in the active workspace:
+
+```bash
+codex-workspaces use work --no-stop --no-start
+codex-workspaces accounts save work
+codex-workspaces accounts set-default work acct_work --activate
+codex-workspaces accounts list
+```
+
+Standalone accounts can be initialized and later populated from the current workspace `auth.json`:
+
+```bash
+codex-workspaces accounts init research
+codex-workspaces accounts save research
+```
+
+Import legacy `codex-accounts` AUTH-mode snapshots:
+
+```bash
+codex-workspaces accounts import-legacy ~/.codex-accounts
+```
+
+Switch workspaces:
+
+```bash
+codex-workspaces work
+codex-workspaces use personal
+codex-workspaces switch work
+```
+
+On macOS, switching stops and restarts Codex App by default. Skip those steps when needed:
+
+```bash
+codex-workspaces work --no-stop --no-start
+```
+
+Inspect workspaces:
+
+```bash
+codex-workspaces list
+codex-workspaces current
+codex-workspaces doctor
+codex-workspaces stats
+codex-workspaces stats work --days 14
+```
+
+Switch accounts within the current workspace:
+
+```bash
+codex-workspaces accounts use acct_personal
+codex-workspaces accounts restore-default
+```
+
+`accounts use` only changes the current workspace `active_account_id`; it does not change `default_account_id`. Entering a workspace with `codex-workspaces use <workspace>` restores that workspace's default account when one is configured.
+
+`auth.json` contains credentials. Do not commit workspace directories, account snapshots, SQLite state, sessions, or shell snapshots to git; the project `.gitignore` excludes these patterns for local checkouts.
+
+Manage workspace metadata and lifecycle:
+
+```bash
+codex-workspaces note work "main paid workspace"
+codex-workspaces rename work main
+codex-workspaces delete old-workspace --force
+```
+
+Control Codex App on macOS:
+
+```bash
+codex-workspaces stop
+codex-workspaces start
+codex-workspaces restart
+```
+
+`stats` only reads local SQLite files such as `state_*.sqlite` or `sqlite/state_*.sqlite`. It does not call quota or refresh private APIs.
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CODEX_APP_NAME` | `Codex` | macOS app name to control. |
+| `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
+| `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
+| `CODEX_WORKSPACES_ROOT` | `$HOME/.codex-workspaces` | Managed root for workspaces, accounts, backups, and lock file. |
+| `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
+
+Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
+
+## Development
+
+```bash
+python3 -m pip install -e ".[dev]"
+python3 -m pytest
+python3 -m build
+python3 -m twine check dist/*
+```
+
+Design, test, and release notes live in [`docs/`](docs/).
+
+## Publishing
+
+CI runs tests on Linux, macOS, and Windows across Python 3.9, 3.11, and 3.13. The `Publish to TestPyPI` workflow runs for `v*` tags, and the `Publish to PyPI` workflow publishes from `release/v*` branches or manual runs.
+
+Configure TestPyPI and PyPI Trusted Publishing for this repository before using the release workflows. See [`docs/RELEASE.zh-CN.md`](docs/RELEASE.zh-CN.md).

codex_workspaces-0.2.0/README.zh-CN.md

@@ -0,0 +1,210 @@
+# codex-workspaces
+
+[English](README.MD) | 简体中文 | [更新日志](CHANGELOG.md)
+
+`codex-workspaces` 用来切换多个 Codex 工作区目录。默认把每个工作区放在 `~/.codex-workspaces/workspaces/` 下，并让当前生效的 `~/.codex` 指向选中的工作区。
+
+项目现在有两个入口：
+
+- 跨平台 Python 3 CLI，支持 Linux、macOS 和 Windows。
+- 原来的 macOS Bash 脚本，仍保留在 [`codex-workspaces`](macos/codex-workspaces)，兼容已经使用 shell 安装方式的用户。
+
+在 macOS 上，Python CLI 保留原来的 App 流程：关闭 Codex App、切换工作区链接、再启动 Codex App。在 Linux 和 Windows 上，CLI 会跳过 App 启停，只切换工作区链接。
+
+## 功能
+
+- 管理 `~/.codex-workspaces/workspaces/work` 这类工作区目录。
+- 管理 `~/.codex-workspaces/accounts/` 下的账号快照。
+- 切换当前 `~/.codex` 软链接或目录链接。
+- 初始化带元数据的工作区目录。
+- 通过 `accounts use` 临时切换当前工作区账号，并可恢复工作区默认账号。
+- 迁移旧版 `~/.codex-<name>` 工作区，并导入旧 `~/.codex-accounts` 账号快照。
+- 保留 macOS 上 Codex App 的 `stop`、`start`、`restart`。
+- 以只读方式读取 Codex `state_*.sqlite`，展示本地 token 用量统计。
+- 在检测到 Codex 内置 Terminal 且无法安全转交时，阻止危险操作。
+- 支持中英文输出，可通过 `CODEX_WORKSPACES_LANG` 指定。
+- 提供 Python 包、测试、GitHub CI 和 PyPI 发布工作流。
+
+## 要求
+
+- Python 3.9 或更新版本。
+- 只有 `start`、`stop`、`restart` 这类 Codex App 控制命令要求 macOS。
+- Linux 和 macOS 使用目录软链接。
+- Windows 优先使用目录软链接，不可用时回退到目录 junction。
+
+## 安装
+
+从 PyPI 安装 Python CLI：
+
+```bash
+python3 -m pip install codex-workspaces
+```
+
+推荐用 `pipx` 做隔离安装：
+
+```bash
+pipx install codex-workspaces
+```
+
+本地开发安装：
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+旧版 macOS shell 安装方式仍可从 `macos/` 目录使用：
+
+```bash
+tmp="$(mktemp -t codex-workspaces.XXXXXX)" && curl -fsSL https://raw.githubusercontent.com/blockchain-project-lives/codex-workspaces/main/macos/codex-workspaces -o "$tmp" && bash "$tmp" install && rm -f "$tmp"
+```
+
+## 工作区目录
+
+默认布局：
+
+```text
+~/.codex           -> 当前工作区链接
+~/.codex-workspaces/
+  config.json
+  state.json
+  lock
+  workspaces/
+    work/
+      auth.json
+      .codex-workspace.json
+    personal/
+      auth.json
+      .codex-workspace.json
+  accounts/
+    acct_work/
+      auth.json
+      meta.json
+```
+
+可通过 `CODEX_WORKSPACES_LINK` 和 `CODEX_WORKSPACES_ROOT` 自定义路径。
+
+## 使用
+
+初始化工作区：
+
+```bash
+codex-workspaces init personal
+codex-workspaces init work
+```
+
+迁移旧版 `~/.codex-<name>` 目录，不会自动删除旧目录：
+
+```bash
+codex-workspaces migrate --dry-run
+codex-workspaces migrate
+```
+
+如果当前 `~/.codex` 是真实目录而不是链接，需要显式迁移成一个命名工作区：
+
+```bash
+codex-workspaces init personal --migrate-current
+```
+
+在 Codex 已经在当前工作区写入 `auth.json` 后，设置账号快照：
+
+```bash
+codex-workspaces use work --no-stop --no-start
+codex-workspaces accounts save work
+codex-workspaces accounts set-default work acct_work --activate
+codex-workspaces accounts list
+```
+
+单独账号可以先初始化，再从当前工作区的 `auth.json` 保存进去：
+
+```bash
+codex-workspaces accounts init research
+codex-workspaces accounts save research
+```
+
+导入旧 `codex-accounts` 的 AUTH 模式账号快照：
+
+```bash
+codex-workspaces accounts import-legacy ~/.codex-accounts
+```
+
+切换工作区：
+
+```bash
+codex-workspaces work
+codex-workspaces use personal
+codex-workspaces switch work
+```
+
+macOS 上默认会在切换前后关闭和启动 Codex App。需要时可以跳过：
+
+```bash
+codex-workspaces work --no-stop --no-start
+```
+
+查看工作区：
+
+```bash
+codex-workspaces list
+codex-workspaces current
+codex-workspaces doctor
+codex-workspaces stats
+codex-workspaces stats work --days 14
+```
+
+在当前工作区临时切换账号：
+
+```bash
+codex-workspaces accounts use acct_personal
+codex-workspaces accounts restore-default
+```
+
+`accounts use` 只修改当前工作区的 `active_account_id`，不会修改 `default_account_id`。执行 `codex-workspaces use <工作区>` 进入某个工作区时，如果配置了默认账号，会恢复该工作区默认账号。
+
+`auth.json` 包含认证凭据，不要提交到 git。工作区目录、账号快照、SQLite 状态、sessions 和 shell snapshots 已在本项目 `.gitignore` 中排除。
+
+管理工作区备注和生命周期：
+
+```bash
+codex-workspaces note work "主力付费工作区"
+codex-workspaces rename work main
+codex-workspaces delete old-workspace --force
+```
+
+macOS 上控制 Codex App：
+
+```bash
+codex-workspaces stop
+codex-workspaces start
+codex-workspaces restart
+```
+
+`stats` 只读取本地 SQLite 文件，例如 `state_*.sqlite` 或 `sqlite/state_*.sqlite`。它不会调用 quota 或 refresh 私有接口。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `CODEX_APP_NAME` | `Codex` | macOS App 名称。 |
+| `CODEX_QUIT_TIMEOUT` | `20` | 等待 App 退出的秒数。 |
+| `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | 当前工作区链接路径。 |
+| `CODEX_WORKSPACES_ROOT` | `$HOME/.codex-workspaces` | workspaces、accounts、backups 和 lock 所在管理根目录。 |
+| `CODEX_WORKSPACES_LANG` | 自动 | 强制输出语言，可设为 `en` 或 `zh`。 |
+
+工作区相关配置只使用 `CODEX_WORKSPACES_*` 变量。
+
+## 开发
+
+```bash
+python3 -m pip install -e ".[dev]"
+python3 -m pytest
+python3 -m build
+python3 -m twine check dist/*
+```
+
+设计、测试和发布说明见 [`docs/`](docs/)。
+
+## 发布
+
+CI 会在 Linux、macOS、Windows 上测试 Python 3.9、3.11、3.13。`Publish to TestPyPI` 工作流会在 `v*` tag 上运行，`Publish to PyPI` 工作流支持从 `release/v*` 分支或手动触发发布。
+
+发布前需要在 TestPyPI 和 PyPI 分别配置 Trusted Publishing。详见 [`docs/RELEASE.zh-CN.md`](docs/RELEASE.zh-CN.md)。