> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 03-桌面App使用

> 掌握 Codex 桌面 App 中的项目、线程、运行位置、Review、终端、自动化、任务恢复和 Git 清理流程。

## 本页目标

桌面 App 的价值不只是把终端换成窗口，而是把多个 Codex 任务放在一个可观察、可审阅、可恢复的工作台里。本页围绕一条完整链路展开：先确认项目和线程，再选择运行位置；执行中检查权限；完成后审阅 diff、运行验证；最后处理分支、恢复和清理。

本页使用三个核心概念：

* **项目（Project）**：一个本地代码目录或 Git 仓库，决定 Codex 的工作范围。
* **线程（Thread）**：一次有独立上下文的任务会话。一个线程应尽量只负责一个可验收目标。
* **运行位置（Environment）**：任务实际执行的地方，常见选项是 `Local`、`Worktree` 和 `Cloud`。

界面名称、快捷键、模型和默认策略会随版本变化。按钮以当前 App 显示为准，权限弹窗中的实际命令是最后确认点。

## 一、开始前检查

### 1. 确认项目目录和 Git 状态

在系统终端进入项目根目录，执行：

```bash theme={null}
pwd
git status --short --branch
git branch --show-current
git worktree list
```

Windows PowerShell 可执行：

```powershell theme={null}
Get-Location
git status --short --branch
git worktree list
```

预期结果：当前路径、分支和已有改动都符合预期。若目录不是 Git 仓库，Git 命令会明确报错；不要把“命令失败”误认为“工作区干净”。

如果已有未提交改动，先识别它们属于谁。需要时保存补丁：

```bash theme={null}
git diff --binary > before-codex.patch
git diff --cached --binary >> before-codex.patch
```

不要为了让状态变干净而执行 `git reset --hard`、批量删除或覆盖同事的修改。

### 2. 读取项目规则

在 App 中添加项目后，先让 Codex 只读检查：

```text theme={null}
先不要修改文件。请读取项目根目录的 README、AGENTS.md、贡献指南和测试配置，说明：
1. 如何安装依赖、启动和测试；
2. 本次任务可能涉及哪些文件；
3. 哪些文件和目录不应修改；
4. 完成后用哪些命令验收。
信息不足时先列出问题。
```

预期结果：Codex 先给出项目理解和计划，不直接写文件。若它立即修改，暂停线程并检查权限策略与任务范围。

### 3. 写清任务边界

建议每个线程都包含目标、范围、约束、验收和失败处理：

```text theme={null}
目标：修复登录表单提交失败时的错误提示。
范围：只修改 src/login/ 和相关测试。
约束：不改 API 协议，不升级依赖，不修改 .env，不提交或推送。
验收：运行已有登录测试和 lint，展示变更文件、diff 和测试结果。
失败处理：如果测试需要外部服务，先说明，不使用生产地址。
```

## 二、项目与线程

### 项目不是普通聊天

绑定项目的线程拥有明确工作目录，可以读取仓库、运行项目命令并产生代码改动。没有绑定项目的普通聊天适合讨论概念或整理方案，不应当用来修改仓库。

添加项目时选择真实的项目根目录，不要选择包含多个无关仓库的上级目录。新线程打开后，应能看到项目路径、当前运行位置和分支信息。

常见故障处理：

* 项目列表为空：检查登录账号、目录权限和目录是否存在；
* 只能聊天不能改代码：确认线程绑定项目，并检查是否为只读或 Cloud 任务；
* 显示路径不对：停止线程，重新选择项目根目录，不要要求代理自行猜目录。

### 一个线程一个目标

以下任务适合拆成独立线程：修一个缺陷、补一个模块的测试、做一次小范围重构、只读审查分支、生成定期摘要。需求澄清、架构重构、依赖升级和发布不应混成一个没有边界的线程。

并行时遵守三条规则：

1. 只读任务可以共享项目，但避免同时写入同一缓存或启动同一端口；
2. 需要修改同一仓库的任务，优先使用 `Worktree`；
3. 有依赖关系的任务先完成上游并审阅，再创建下游线程。

多个 `Local` 线程同时修改同一目录，会产生覆盖、混合 diff 和不可解释的测试结果。

## 三、Local、Worktree、Cloud

| 位置         | 执行处             | 改动落点      | 适合场景        | 主要风险         |
| ---------- | --------------- | --------- | ----------- | ------------ |
| `Local`    | 当前电脑的项目目录       | 当前检出和分支   | 日常小改动、快速验证  | 污染已有工作       |
| `Worktree` | 当前电脑的独立 Git 工作树 | 独立目录      | 并行任务、实验、长任务 | 缺少被忽略文件，需清理  |
| `Cloud`    | 云端隔离环境          | 云端结果或变更产物 | 不占本机、后台任务   | 数据外发、网络和授权边界 |

选择前先问：是否要直接修改当前目录，是否需要与其他任务隔离，是否需要脱离本机运行。

### 1. Local：直接改当前目录

适合工作区已确认、任务很小、需要马上在本地 IDE 或开发服务器中查看结果的情况。

操作步骤：

1. 打开正确项目并新建线程；
2. 确认路径、分支和已有改动；
3. 选择 `Local`；
4. 先发送只读计划；
5. 确认计划后再允许写入；
6. 完成后立即打开 Review 查看全量改动。

预期结果：Codex 和 App 内置终端都在当前项目目录中工作，系统终端能看到同一批文件变化。

失败时暂停线程。如果发现目录已有别人的未完成改动，切换到 Worktree 或先人工分离任务，不要顺手整理无关文件。

### 2. Worktree：隔离并行任务

`Worktree` 是本机独立的 Git 工作树。它共享 Git 元数据，但拥有独立文件副本；一个线程的改动不会直接覆盖另一个线程的目录。

操作步骤：

1. 新建线程并选择 `Worktree`；
2. 选择起始分支或提交；
3. 确认项目是 Git 仓库；
4. 发送一个小任务让 App 创建工作树；
5. 在内置终端运行 `git worktree list`；
6. 完成后创建功能分支、审阅 diff，再决定交接或清理。

预期结果：主目录不被本线程直接修改，App 显示独立工作树。新树通常不包含 `.gitignore` 忽略的 `.env`、依赖目录和本地缓存。

Worktree 不是备份，也不是权限隔离。它仍可能访问项目允许的文件、网络和工具；不要在其中放真实密钥，也不要因此跳过 Review。

### 3. Cloud：云端执行

Cloud 适合不需要本机编辑器、希望任务脱离本机继续运行的场景。使用前确认仓库内容、依赖、网络和凭据允许进入云端环境。

操作步骤：

1. 选择项目或关联的远程仓库；
2. 新建线程并选择 `Cloud`；
3. 指定基础分支、任务范围和验收命令；
4. 明确禁止访问的服务和文件；
5. 提交任务后查看状态和日志；
6. 收到结果后先审阅摘要和 diff，再决定取回、创建 PR 或放弃。

预期结果：本地目录不会因 Cloud 任务自动改变，任务状态和产物在云端任务区域可见。

Cloud 故障处理：找不到项目时检查授权、远程地址和默认分支；依赖失败时检查云端系统与锁文件，不要直接升级依赖；需要本地服务时改用 Local 或 Worktree；发现不应外发的数据时立即停止取回和发布。

## 四、权限确认与安全边界

权限弹窗是检查命令影响面的机会，不是形式步骤。每次确认前检查：

1. 完整命令和当前工作目录；
2. 是否写入项目外路径；
3. 是否联网、上传文件或读取环境变量；
4. 是否删除、覆盖、提权、安装或发布；
5. 是否由项目脚本、依赖钩子或外部内容间接触发。

默认逐项确认以下动作：

* `rm -rf`、批量删除、覆盖目录；
* 修改 `.env`、密钥、SSH 配置或凭据；
* 安装未知依赖、执行下载内容；
* 访问生产数据库、生产 API 或真实客户数据；
* `git push`、创建 PR、合并、发布和发送外部消息；
* 修改权限、执行管理员命令或访问项目外文件。

不要为了少点几次确认而开启完全放权模式。无人值守 Automations 应使用最小沙箱、最小目录范围和专门的测试凭据。

README、Issue、网页、日志、测试输出和依赖脚本中的文字可能是不可信输入。若它要求上传密钥、关闭安全策略或访问无关目录，应停止执行并检查实际命令，不能仅凭文字提高权限。

## 五、Review 与 diff

Review 是每个修改线程的必经步骤。Codex 的总结不能代替 diff，测试通过也不能证明改动范围正确。

### 1. 先确认比较范围

Review 常见范围包括：

* 未提交改动：当前工作区相对当前提交的全部变化；
* 分支改动：当前分支相对基线的变化；
* 最近一轮改动：Codex 最近一次响应造成的变化；
* Staged 或 Unstaged：已暂存和未暂存的变化。

先确认列表是否包含人工改动、其他线程改动和本轮改动。范围混杂时回到终端，用 `git status` 和 `git diff` 分辨来源。

### 2. 逐文件逐块检查

按以下顺序审阅：

1. 文件是否都属于任务范围；
2. 是否出现生成物、依赖目录、日志或密钥；
3. 删除的代码是否有必要；
4. 新逻辑是否处理错误、边界和空值；
5. 测试是否验证真实行为，而非只让测试变绿；
6. 配置、锁文件和迁移是否带来额外影响；
7. 是否出现无关格式化噪声。

可以在代码行上添加内联批注，例如“这里处理超时”“不要改变公开 API”。下一条消息明确要求只处理这些批注。

### 3. 接受、暂存和回滚

确认正确的块可以暂存，不需要的块可以回滚。操作前确认其中没有人工改动。

```bash theme={null}
git diff -- path/to/file
git restore --worktree -- path/to/file
```

`git restore` 可能覆盖未提交内容。执行前再次查看 diff，不能用整个仓库回滚解决单文件问题。

### 4. 提交前验证

```bash theme={null}
git diff --check
git status --short
git diff --stat
git diff --cached --check
```

再运行项目真实存在的测试、lint 或构建命令。先读 `package.json`、Makefile、README 或项目脚本，不要盲目执行不存在的命令。

## 六、内置终端与 Actions

### 1. 先确认终端位置

打开线程内置终端后执行：

```bash theme={null}
pwd
git status --short --branch
git worktree list
```

Windows 中 `pwd` 不可用时使用 `Get-Location`。预期结果是终端目录与当前线程的 Local 或 Worktree 一致。

终端和 Codex 共享文件，但你自己输入的命令同样可能删除文件、联网或修改外部系统。

### 2. 按状态、差异、验证执行

```bash theme={null}
git status --short
git diff --stat
<项目已有的测试命令>
```

开发服务器要记录端口、日志和停止方式。并行 Worktree 应使用不同端口，避免多个线程互相抢占。

### 3. 使用 Actions

Actions 可把测试、格式化和启动开发服务器等常用命令放到 App 中快速调用。配置前阅读项目脚本，确保不会把生产配置、真实数据或凭据写入日志。

预期结果：点击后终端显示完整命令和退出状态，失败时保留原始错误。Action 不是审批替代品，也不会自动判断命令安全。

## 七、分支、Handoff 与合并

### 1. detached HEAD 与创建分支

App 创建的 Worktree 可能默认处于 detached HEAD，即指向某个提交但没有可推送的分支名称。

需要交付时，使用 App 中“在此创建分支”或等效功能，创建明确名称，例如 `fix/login-timeout`。完成后用以下命令确认：

```bash theme={null}
git status --short --branch
git branch --show-current
```

预期结果：显示正确功能分支，不把主分支误当成工作分支继续修改。

### 2. 同一分支不能同时检出

Git 不允许同一分支同时在两个工作树中检出。如果出现：

```text theme={null}
fatal: 'feature/example' is already used by worktree at '...'
```

先运行：

```bash theme={null}
git worktree list
```

不要强行删除目录或重复检出。可以回到占用它的 Worktree、切换另一个分支、使用 Handoff，或确认任务结束后再清理。

### 3. Handoff

Handoff 用来在 Local 和 Worktree 之间转移线程位置。常见路径是：

1. 在线程 Worktree 中完成实现；
2. 打开 Review 并记录问题；
3. Handoff 到 Local；
4. 在熟悉的 IDE、终端和本地服务中验收；
5. 提交到明确的功能分支。

也可以把 Local 线程交接到 Worktree，让它后台继续运行。Handoff 依赖 Git 操作，因此 `.gitignore` 中的 `.env`、缓存和依赖不会自动移动。需要它们时使用安全的本地环境配置，不要把秘密值提交进仓库。

## 八、Automations

Automations 适合周期性、可重复、范围清晰的任务，例如每日提交摘要、定期巡检或持续跟踪一个长期线程。通常要求 App 运行、项目仍在磁盘上且电脑可执行任务。

### 1. 先手动验证提示词

不要直接创建定时任务，先在普通线程中运行：

```text theme={null}
读取当前仓库最近 24 小时的提交，按主题生成中文摘要。
只读，不修改文件，不联网，不发送消息。
如果没有提交，明确写出“过去 24 小时没有新提交”。
```

预期结果：输出稳定、范围正确、没有副作用。结果不理想时修改提示词，而不是提高权限。

### 2. 创建自动化

创建时明确说明：

* 运行频率和时区；
* 使用的项目；
* 运行在 Local 还是 Worktree；
* 是否允许写文件、联网或创建分支；
* 没有值得报告的内容时如何处理；
* 输出进入哪里。

Git 仓库的自动化优先选择 Worktree，避免后台任务改到正在编辑的文件。只有明确需要改主检出，并且安排了备份和锁定时间时才使用 Local。

### 3. 独立自动化与线程自动化

独立自动化每次从新的运行开始，适合日报和巡检。线程自动化回到同一线程继续，适合跟踪一个长期任务；提示词必须说明每次唤醒如何判断进度、何时停止、何时需要人工确认。

### 4. 验证和失败处理

创建后依次执行：

1. 在 Automations 列表确认频率、项目和运行位置；
2. 手动触发一次；
3. 检查日志和 diff；
4. 观察前几次输出；
5. 不再需要时及时归档。

预期结果：任务在预定位置运行，结果进入收件箱或对应线程；没有值得报告的内容时按规则归档，不会悄悄修改主目录。

App 未运行、电脑休眠、项目移动、权限不足或 Worktree 缺依赖都可能导致失败。先看日志和路径，再修复环境，不要直接改成完全访问。

## 九、任务恢复

### 1. 恢复仍在列表中的线程

重新打开原线程，先发送：

```text theme={null}
先不要修改文件。请恢复上下文：说明项目路径、运行位置、分支、已有改动、上一轮验证结果和未完成事项。
```

确认摘要后再继续。不要在新线程中凭记忆重复执行安装、迁移或删除。

### 2. App 或电脑中断

恢复后依次检查：

```bash theme={null}
git status --short --branch
git diff --stat
git worktree list
```

同时查看线程最后一条消息、终端日志和测试退出状态。被中断的依赖安装、迁移或批量重命名可能只完成一半，确认状态前不要直接重跑破坏性命令。

### 3. Worktree 被清理

Codex 管理的临时 Worktree 可能因归档或数量上限被清理。线程记录通常仍在，App 可能提供恢复快照的入口。恢复前确认快照时间和基线分支，恢复后重新检查 `git status` 和 Review。

重要成果应及时创建明确分支并提交，不要只留在可能被回收的临时 Worktree 中。

### 4. 结果不可信

若摘要与 diff 不一致、测试结果缺失或声称执行了看不到的命令：

1. 停止提交、推送和发布；
2. 保存线程 ID、日志和 diff；
3. 用终端重新运行只读检查；
4. 要求 Codex 列出实际命令；
5. 必要时在干净 Worktree 中复现。

## 十、清理与回滚

### 1. 正确的收尾顺序

1. Review 确认范围；
2. 运行测试、lint 或构建；
3. 创建功能分支并提交；
4. 按团队流程推送和创建 PR；
5. 确认分支已合并或成果已保存；
6. 归档线程；
7. 删除不再需要的临时 Worktree；
8. 检查 `git worktree list` 和磁盘占用。

不要先清理再确认结果，也不要删除仍被进行中、置顶或长期任务使用的 Worktree。

### 2. 清理 Worktree

优先使用 App 的归档或删除入口，因为它能同步线程记录和托管状态。需要检查 Git 时：

```bash theme={null}
git worktree list
git worktree prune --dry-run
```

确认路径、线程和分支都不再需要后，才执行实际清理。不要手动删除 `.codex/worktrees` 下的目录来绕过 App 状态。

长期环境应使用永久 Worktree 或明确分支，并约定负责人和清理时间。临时实验在确认结果已丢弃后及时归档，避免依赖和构建缓存长期占用磁盘。

### 3. 回滚

未提交的单文件改动可在 Review 中按文件或代码块回滚。终端回滚前先保存：

```bash theme={null}
git diff --binary > before-rollback.patch
git status --short
```

已提交的错误不要改写共享分支历史，应创建反向修复提交。已推送的错误按 PR、发布和回滚流程处理。数据库、外部服务和自动化配置使用各自的迁移回退、版本回滚和禁用开关。

## 十一、完整实战流程

下面演示“补充输入校验并增加测试”的可恢复流程，命令以项目实际脚本为准。

### 第一步：创建隔离线程

打开 Git 仓库，确认路径和账号，创建线程，选择 `Worktree`，从稳定分支开始。

预期结果：线程显示 Worktree，主目录保持原状。不能选择 Worktree 时，确认 `git rev-parse --show-toplevel` 成功，并检查是否有冲突工作树。

### 第二步：先要计划

```text theme={null}
先不要修改。检查输入校验实现、现有测试和项目约定。
提出最小修改计划，列出文件、边界条件、测试命令和不应触碰的文件。
```

预期结果：Codex 给出计划并指出不确定项。确认后再进入实现。

### 第三步：限定修改

```text theme={null}
按已确认计划实现，只修改列出的文件。
不要升级依赖，不要读取或修改 .env，不要访问生产服务，不要提交或推送。
完成后展示 git status、diff 摘要和实际运行的测试命令。
```

遇到权限确认时，核对命令、目录和网络范围。安装依赖前确认锁文件和包来源。

### 第四步：终端与 Review 双检

```bash theme={null}
git status --short --branch
git diff --stat
git diff --check
```

打开 Review，逐文件逐块检查。发现无关变更时，先停止扩展范围，再回滚无关块。

预期结果：只有任务相关文件被修改，空白检查通过，分支和 Worktree 正确。

### 第五步：运行验证

运行项目已有的测试和 lint。失败时记录完整输出，区分实现错误、环境缺失和外部服务不可用。只修复与失败对应的范围；不要为了通过测试切换生产服务或放宽权限。

每次修复后重新看 diff，不要连续批准一串无法解释的命令。

### 第六步：保存成果

确认结果后创建功能分支并提交，提交前检查 staged diff。推送和创建 PR 属于外部动作，应单独确认目标远端和 PR 内容。

预期结果：成果有明确分支和提交，主目录没有被污染，提交说明包含测试结果和已知限制。

### 第七步：收尾或恢复

还要继续就保留线程和 Worktree；已合并且不再需要就归档线程并清理临时 Worktree。中断后重新打开原线程，先执行恢复检查，不要创建新线程重复操作。

## 十二、故障速查

| 现象             | 先检查                    | 处理方式                    |
| -------------- | ---------------------- | ----------------------- |
| 改动出现在错误目录      | 项目路径、运行位置、`pwd`        | 停止线程，保存 diff，确认后恢复或回滚   |
| 两个任务互相覆盖       | 是否都使用 `Local`          | 改用 Worktree，区分分支        |
| Worktree 缺依赖   | `.gitignore`、setup、锁文件 | 使用安全 setup，不复制真实 `.env` |
| 分支被占用          | `git worktree list`    | Handoff、换分支或清理结束的工作树    |
| Review 有无关文件   | 是否已有人工改动               | 分辨来源，按块回滚，勿整仓库重置        |
| Automation 不运行 | App、电脑、项目是否可用          | 查看日志，先手动触发，不直接提权        |
| 测试失败但摘要说成功     | 原始输出、退出码、实际命令          | 以可复现结果为准                |
| 中断后可能重复执行      | 原线程、Git 状态、迁移记录        | 先恢复状态，再决定是否重跑           |
| Cloud 不能取回     | 授权、分支、网络和数据策略          | 确认边界，必要时改用本机 Worktree   |

## 验收清单

完成后至少确认：

* 项目路径和线程运行位置正确；
* 当前分支不是误用的主分支，或 Local 修改已获明确批准；
* Review 范围清楚，diff 只包含预期文件；
* 没有提交密钥、`.env`、客户数据、缓存或无关生成物；
* 测试、lint、构建或只读检查有实际输出和退出状态；
* Handoff、提交、推送、PR 和发布没有被误当成自动步骤；
* 自动化使用明确频率、最小权限和可清理的位置；
* 线程、分支、Worktree 和快照仍能在需要时恢复；
* 临时 Worktree 和自动化结果已按任务状态清理；
* 失败、未验证假设和下一步动作已记录。

## 小结

稳定的桌面 App 工作流是：**确认项目和线程，选择运行位置；执行中核对权限；完成后用终端和 Review 验证；确认分支和结果后再提交；最后按状态恢复或清理。**

日常小改动可用 `Local`，同一仓库的并行任务优先用 `Worktree`，需要脱离本机运行时再评估 `Cloud`。运行位置不是安全边界，Codex 的总结也不能替代 diff 和测试。可交付结果必须范围可解释、改动可审阅、验证可复现、权限可追溯、失败可恢复。

参考资料：`参考/codex/07-desktop-app.md`、`参考/codex/25-worktrees.md`、`参考/codex/27-automation.md`。动态信息以当前桌面 App 的设置、权限提示和官方文档为准。