03-桌面App使用 - 从0开始的AI Coding 学习

本页目标

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

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

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

一、开始前检查

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

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

pwd
git status --short --branch
git branch --show-current
git worktree list

Windows PowerShell 可执行：

Get-Location
git status --short --branch
git worktree list

预期结果：当前路径、分支和已有改动都符合预期。若目录不是 Git 仓库，Git 命令会明确报错；不要把“命令失败”误认为“工作区干净”。如果已有未提交改动，先识别它们属于谁。需要时保存补丁：

git diff --binary > before-codex.patch
git diff --cached --binary >> before-codex.patch

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

2. 读取项目规则

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

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

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

3. 写清任务边界

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

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

二、项目与线程

项目不是普通聊天

绑定项目的线程拥有明确工作目录，可以读取仓库、运行项目命令并产生代码改动。没有绑定项目的普通聊天适合讨论概念或整理方案，不应当用来修改仓库。添加项目时选择真实的项目根目录，不要选择包含多个无关仓库的上级目录。新线程打开后，应能看到项目路径、当前运行位置和分支信息。常见故障处理：

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

一个线程一个目标

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

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

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

三、Local、Worktree、Cloud

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

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

1. Local：直接改当前目录

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

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

预期结果：Codex 和 App 内置终端都在当前项目目录中工作，系统终端能看到同一批文件变化。失败时暂停线程。如果发现目录已有别人的未完成改动，切换到 Worktree 或先人工分离任务，不要顺手整理无关文件。

2. Worktree：隔离并行任务

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

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

预期结果：主目录不被本线程直接修改，App 显示独立工作树。新树通常不包含 .gitignore 忽略的 .env、依赖目录和本地缓存。 Worktree 不是备份，也不是权限隔离。它仍可能访问项目允许的文件、网络和工具；不要在其中放真实密钥，也不要因此跳过 Review。

3. Cloud：云端执行

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

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

预期结果：本地目录不会因 Cloud 任务自动改变，任务状态和产物在云端任务区域可见。 Cloud 故障处理：找不到项目时检查授权、远程地址和默认分支；依赖失败时检查云端系统与锁文件，不要直接升级依赖；需要本地服务时改用 Local 或 Worktree；发现不应外发的数据时立即停止取回和发布。

四、权限确认与安全边界

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

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

默认逐项确认以下动作：

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. 逐文件逐块检查

按以下顺序审阅：

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

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

3. 接受、暂存和回滚

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

git diff -- path/to/file
git restore --worktree -- path/to/file

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

4. 提交前验证

git diff --check
git status --short
git diff --stat
git diff --cached --check

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

六、内置终端与 Actions

1. 先确认终端位置

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

pwd
git status --short --branch
git worktree list

Windows 中 pwd 不可用时使用 Get-Location。预期结果是终端目录与当前线程的 Local 或 Worktree 一致。终端和 Codex 共享文件，但你自己输入的命令同样可能删除文件、联网或修改外部系统。

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

git status --short
git diff --stat
<项目已有的测试命令>

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

3. 使用 Actions

Actions 可把测试、格式化和启动开发服务器等常用命令放到 App 中快速调用。配置前阅读项目脚本，确保不会把生产配置、真实数据或凭据写入日志。预期结果：点击后终端显示完整命令和退出状态，失败时保留原始错误。Action 不是审批替代品，也不会自动判断命令安全。

七、分支、Handoff 与合并

1. detached HEAD 与创建分支

App 创建的 Worktree 可能默认处于 detached HEAD，即指向某个提交但没有可推送的分支名称。需要交付时，使用 App 中“在此创建分支”或等效功能，创建明确名称，例如 fix/login-timeout。完成后用以下命令确认：

git status --short --branch
git branch --show-current

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

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

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

fatal: 'feature/example' is already used by worktree at '...'

先运行：

git worktree list

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

3. Handoff

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

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

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

八、Automations

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

1. 先手动验证提示词

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

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

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

2. 创建自动化

创建时明确说明：

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

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

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

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

4. 验证和失败处理

创建后依次执行：

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

预期结果：任务在预定位置运行，结果进入收件箱或对应线程；没有值得报告的内容时按规则归档，不会悄悄修改主目录。 App 未运行、电脑休眠、项目移动、权限不足或 Worktree 缺依赖都可能导致失败。先看日志和路径，再修复环境，不要直接改成完全访问。

九、任务恢复

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

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

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

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

2. App 或电脑中断

恢复后依次检查：

git status --short --branch
git diff --stat
git worktree list

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

3. Worktree 被清理

Codex 管理的临时 Worktree 可能因归档或数量上限被清理。线程记录通常仍在，App 可能提供恢复快照的入口。恢复前确认快照时间和基线分支，恢复后重新检查 git status 和 Review。重要成果应及时创建明确分支并提交，不要只留在可能被回收的临时 Worktree 中。

4. 结果不可信

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

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

十、清理与回滚

1. 正确的收尾顺序

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

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

2. 清理 Worktree

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

git worktree list
git worktree prune --dry-run

确认路径、线程和分支都不再需要后，才执行实际清理。不要手动删除 .codex/worktrees 下的目录来绕过 App 状态。长期环境应使用永久 Worktree 或明确分支，并约定负责人和清理时间。临时实验在确认结果已丢弃后及时归档，避免依赖和构建缓存长期占用磁盘。

3. 回滚

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

git diff --binary > before-rollback.patch
git status --short

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

十一、完整实战流程

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

第一步：创建隔离线程

打开 Git 仓库，确认路径和账号，创建线程，选择 Worktree，从稳定分支开始。预期结果：线程显示 Worktree，主目录保持原状。不能选择 Worktree 时，确认 git rev-parse --show-toplevel 成功，并检查是否有冲突工作树。

第二步：先要计划

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

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

第三步：限定修改

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

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

第四步：终端与 Review 双检

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 的设置、权限提示和官方文档为准。

​本页目标

​一、开始前检查

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

​2. 读取项目规则

​3. 写清任务边界

​二、项目与线程

​项目不是普通聊天

​一个线程一个目标

​三、Local、Worktree、Cloud

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

​2. Worktree：隔离并行任务

​3. Cloud：云端执行

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

​五、Review 与 diff

​1. 先确认比较范围

​2. 逐文件逐块检查

​3. 接受、暂存和回滚

​4. 提交前验证

​六、内置终端与 Actions

​1. 先确认终端位置

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

​3. 使用 Actions

​七、分支、Handoff 与合并

​1. detached HEAD 与创建分支

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

​3. Handoff

​八、Automations

​1. 先手动验证提示词

​2. 创建自动化

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

​4. 验证和失败处理

​九、任务恢复

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

​2. App 或电脑中断

​3. Worktree 被清理

​4. 结果不可信

​十、清理与回滚

​1. 正确的收尾顺序

​2. 清理 Worktree

​3. 回滚

​十一、完整实战流程

​第一步：创建隔离线程

​第二步：先要计划

​第三步：限定修改

​第四步：终端与 Review 双检

​第五步：运行验证

​第六步：保存成果

​第七步：收尾或恢复

​十二、故障速查

​验收清单

​小结