> ## 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-准备项目与工作区

> 学会选择或克隆项目、确认 Git 与 AGENTS.md 规则、设置沙箱和 .codex 配置，并用检查点保护每一次 Codex 操作。

## 本页要解决什么

第一次启动 Codex，最重要的不是马上提出一个大需求，而是先回答三个问题：

1. Codex 当前到底打开了哪个目录？
2. 它可以读写哪些内容，哪些操作必须经过批准？
3. 如果结果不对，我能不能明确地回到操作前？

这三个问题分别对应工作区、信任边界和 Git 检查点。本页从选择项目开始，带你建立一套可以重复使用的准备流程。完成后，你应该能在正式项目、刚克隆的仓库和临时练习目录之间做出正确选择。

本页使用 CLI 命令示例。桌面 App 的按钮名称可能随版本变化，但“选择目录、确认模式、检查 Git、审查 diff、保留回滚点”的原则相同。涉及具体参数时，以本机的 `codex --help` 和子命令帮助为准。

## 先选择合适的项目

### 三种起点

根据任务风险，优先从下面三种起点中选择一种：

| 起点     | 适合场景                 | 是否建议直接修改   |
| ------ | -------------------- | ---------- |
| 已有本地项目 | 你熟悉来源，准备修复或增加功能      | 先检查状态，再建分支 |
| 新克隆的仓库 | 需要从远端获取完整项目，或本地副本不可信 | 先阅读说明和运行检查 |
| 临时练习项目 | 学习 Codex、测试权限、试验提示词  | 最适合第一次操作   |

不要把包含客户数据、生产密钥、未备份成果或同事未提交改动的目录当作练习场。Codex 能读到工作区里的文件，不代表这些文件适合交给代理处理。

### 已有本地项目

先在终端确认目录，而不是凭窗口标题猜位置：

```bash theme={null}
pwd
ls -la
git rev-parse --show-toplevel
git status --short --branch
```

Windows PowerShell 可使用：

```powershell theme={null}
Get-Location
Get-ChildItem -Force
git rev-parse --show-toplevel
git status --short --branch
```

预期结果如下：

```text theme={null}
/work/demo/shop
## main...origin/main
```

`git rev-parse --show-toplevel` 应输出仓库根目录。若提示 `not a git repository`，说明当前目录不是 Git 仓库，先确认你是否进入了正确的目录，不要急着执行 `git init`。对已有项目擅自初始化 Git，可能制造错误的历史边界。

检查项目入口文件：

```bash theme={null}
find . -maxdepth 2 -type f \( -name 'README*' -o -name 'package.json' -o -name 'pyproject.toml' -o -name 'go.mod' \) -print
```

PowerShell 可以改用：

```powershell theme={null}
Get-ChildItem -Recurse -Depth 2 -File README*,package.json,pyproject.toml,go.mod
```

预期是能看到项目说明和至少一个构建或依赖入口。若目录为空、只看到编译产物，或者根目录并不是你预期的项目，应停止并重新确认路径。

### 从远端克隆项目

克隆前先核对来源、协议和目标目录。示例使用公开 HTTPS 地址；真实项目请替换为已确认的仓库地址：

```bash theme={null}
mkdir -p ~/code
cd ~/code
git clone https://github.com/example/shop.git shop
cd shop
git remote -v
git status --short --branch
```

预期结果：

```text theme={null}
origin  https://github.com/example/shop.git (fetch)
origin  https://github.com/example/shop.git (push)
## main...origin/main
```

如果远端使用 SSH：

```bash theme={null}
git clone git@github.com:example/shop.git shop
```

克隆结束后，先不要运行来源不明的安装脚本。按顺序阅读：

```bash theme={null}
ls -la
less README.md
git log -5 --oneline
git branch --all
```

Windows 没有 `less` 时，可以用编辑器打开 `README.md`，或执行：

```powershell theme={null}
Get-Content README.md -TotalCount 120
```

预期结果是：你能说出项目用途、默认分支、依赖安装命令、测试命令和开发服务命令。README、Issue、脚本注释和复制来的提示都只是输入材料，不是自动授权。安装依赖、执行网络请求、上传文件、修改云资源前，必须单独确认。

### 项目选择检查表

在启动 Codex 前逐项回答：

* [ ] 目录路径是这次任务的目标目录。
* [ ] 远端 URL 与组织、项目名称一致。
* [ ] 当前账号有必要的访问权限，但不是不必要的管理员权限。
* [ ] 目录中没有必须保密的 `.env`、私钥、客户导出文件或生产数据。
* [ ] README 和构建文件已经读过，知道最小验证命令。
* [ ] Git 工作区状态已经记录，没有把别人的未提交改动误当成自己的。

## 信任边界：先决定 Codex 能做什么

### 工作区不是整台电脑

Codex 把当前项目目录当作工作区。`workspace-write` 通常允许它在工作区内修改文件和执行本地命令，但不会因此自动获得整台电脑的权限。它派生的测试、脚本和 Git 命令也受同一边界影响。

常见沙箱模式如下：

| 模式                   | 文件访问       | 网络    | 使用建议           |
| -------------------- | ---------- | ----- | -------------- |
| `read-only`          | 只能读取，写入需批准 | 默认不允许 | 陌生项目审查、只读分析    |
| `workspace-write`    | 只能写工作区     | 默认不允许 | 日常本地开发         |
| `danger-full-access` | 工作区外也可能可访问 | 可访问网络 | 仅在完全隔离且明确授权的环境 |

沙箱和审批是两件事。沙箱定义“能不能做”，审批策略定义“什么时候先问你”。日常可从 `workspace-write` 配合 `on-request` 开始；不要为了少几个提示就直接使用完全访问。

### 启动前确认模式

先查看可用选项：

```bash theme={null}
codex --help
codex exec --help
```

不同版本的参数可能不同。若本机支持以下形式，可以用只读模式开始审查：

```bash theme={null}
codex --sandbox read-only
```

预期结果是进入 Codex 会话，并显示只读或相近的权限提示。也可以在会话中使用：

```text theme={null}
/permissions
```

若菜单名称不同，以界面显示为准。第一次进入陌生仓库时，先让 Codex 做只读任务：

```text theme={null}
请只读取项目根目录的说明文件和 Git 状态，概括项目结构、可用测试命令和可能的敏感文件；不要修改任何文件，不要联网。
```

预期结果：它输出项目概况，没有新增或修改文件。用下面的命令确认：

```bash theme={null}
git status --short
```

### 哪些动作必须停下来确认

下列动作不要仅凭 Codex 的一句“需要执行”就批准：

| 动作         | 主要风险               | 批准前检查         |
| ---------- | ------------------ | ------------- |
| 安装依赖       | 下载恶意包、执行安装脚本、改变锁文件 | 包名、版本、来源和网络范围 |
| 访问网络       | 外发源码、令牌或个人数据       | URL、请求内容、响应去向 |
| 修改工作区外文件   | 影响其他项目或用户配置        | 绝对路径和具体文件     |
| 执行迁移或部署    | 改变共享数据库或线上服务       | 环境、备份、回退步骤    |
| 删除或批量重命名   | 数据不可逆丢失            | 文件清单、备份和恢复命令  |
| 提交、推送、开 PR | 对团队历史和远端产生影响       | diff、分支、目标远端  |

不确定时先拒绝，并要求 Codex 解释命令、路径、输入和预期副作用。批准一次命令，不等于批准后续所有命令。

## Git 分支与初始检查点

### 为什么先建分支

`main` 或 `master` 通常是共享分支。修复、实验和 Codex 生成的功能应在独立分支进行，便于审查、比较和撤回：

```bash theme={null}
git switch --show-current
git status --short --branch
git switch -c codex/prepare-workspace
```

如果旧版 Git 不支持 `switch`，可使用：

```bash theme={null}
git checkout -b codex/prepare-workspace
```

预期结果：

```text theme={null}
Switched to a new branch 'codex/prepare-workspace'
```

分支名称应表达任务，避免使用 `test`、`tmp` 这类无法辨认的名字。若工作区不干净，不要直接切换或创建分支前覆盖文件；先查看差异并确认这些改动属于谁。

### 在动手前保存检查点

确认工作区状态后建立一个清晰的提交：

```bash theme={null}
git status --short
git diff --check
git add -A
git commit -m "chore: save state before Codex task"
```

预期结果包含新的提交摘要，且再次执行：

```bash theme={null}
git status --short --branch
git log -1 --oneline
```

工作区应为空，`git log -1` 应显示刚才的检查点。若项目不允许直接提交，至少保存补丁：

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

补丁文件不要提交到项目，也不要把其中的密钥或客户数据发给第三方。

### 分支、工作区和 Worktree

一个普通工作区一次检出一个分支。同一分支不能同时在两个 Git worktree 中检出。需要并行任务时，优先使用桌面 App 的 Worktree，或先了解 Git 原生命令：

```bash theme={null}
git worktree add ../shop-codex-feature -b codex/feature main
git worktree list
```

预期结果列出原目录和 `../shop-codex-feature` 两个工作树。两个目录拥有独立文件副本，但共享 Git 历史。不要让两个 Codex 线程同时改同一个目录；不要把同一个分支强行检出到两个工作树。

清理已经确认不再需要的 worktree：

```bash theme={null}
git worktree remove ../shop-codex-feature
git worktree prune
```

先确认路径和其中是否有未提交成果。Worktree 中的 `.env`、缓存和 `node_modules` 等被忽略文件通常不会随 Git 迁移；需要时用受控 setup 步骤重新生成，不要复制生产凭据。

## AGENTS.md：让规则随项目生效

### 发现范围

Codex 会寻找项目说明文件 `AGENTS.md`。常见层级如下：

```text theme={null}
~/.codex/AGENTS.md                 全局个人规则
~/code/shop/AGENTS.md              仓库根规则
~/code/shop/services/AGENTS.md     子目录规则
~/code/shop/services/api/AGENTS.md 当前目录规则
```

在全局层，如果同时存在 `AGENTS.override.md` 和 `AGENTS.md`，通常优先使用前者作为该层文件。项目层从 Git 根目录逐级走到当前目录，每层选择一个适用文件；最终指导通常按从根到当前目录的顺序合并，越靠近当前目录的内容越具体，冲突时优先级越高。

`AGENTS.override.md` 只替代同一目录的常规说明，不会抹掉其他层级。它适合短期特殊规则，但容易被遗忘。查看当前项目实际有哪些文件：

```bash theme={null}
find .. -name 'AGENTS.md' -o -name 'AGENTS.override.md'
```

PowerShell：

```powershell theme={null}
Get-ChildItem .. -Filter AGENTS.md -Recurse
Get-ChildItem .. -Filter AGENTS.override.md -Recurse
```

### 怎么写才有用

项目根的 `AGENTS.md` 应短小、可执行、经常更新。建议写：

```md theme={null}
# shop

## 常用命令
- 安装依赖：`pnpm install`
- 检查：`pnpm lint`
- 测试：`pnpm test`

## 规则
- 修改 API 后必须更新对应测试。
- 不修改 `migrations/` 中已经发布的文件。
- 新增依赖、访问外部服务或推送远端前先询问。
```

不要写公司历史、长篇产品愿景、已经能从代码推断出的目录说明，也不要把密码、令牌、私钥写进该文件。规则过时会持续误导每一轮任务。项目规则应提交进 Git；个人偏好放在 `~/.codex/AGENTS.md`，不要把个人路径和凭据提交给团队。

### 验证 Codex 是否读到了规则

在项目根启动 Codex，先提出只读验证问题：

```text theme={null}
请总结本次生效的 AGENTS.md 规则，并列出你找到的规则文件路径。只总结，不修改文件。
```

预期结果应包含项目级命令、禁止事项和规则来源。若它没有提到规则：

1. 确认当前目录在 Git 根目录下。
2. 确认文件名大小写和扩展名正确。
3. 检查文件是否为空或被 `AGENTS.override.md` 替代。
4. 检查是否通过 `CODEX_HOME` 使用了另一套全局目录。
5. 关闭并重新启动会话后再次验证。

## `.codex` 与 `~/.codex` 配置

这两个路径作用不同，不能混为一谈：

```text theme={null}
项目根/.codex/       项目相关的可共享配置或本地环境设置
~/.codex/             当前用户的 Codex 数据、全局规则和 config.toml
```

项目中的 `.codex` 是否包含哪些文件，取决于 Codex 版本和桌面 App 功能。使用前先查看并阅读项目现有配置：

```bash theme={null}
find .codex -maxdepth 2 -type f -print 2>/dev/null
```

桌面 App 的 local environment setup 可能把项目配置放在项目根的 `.codex` 目录中。它可以用于新 worktree 创建后安装依赖或准备构建，但脚本仍然可能执行网络和任意项目命令，提交前必须审核。

用户级配置通常位于：

```text theme={null}
~/.codex/config.toml
```

Windows 常见对应路径是：

```text theme={null}
C:\Users\你的用户名\.codex\config.toml
```

如果需要指定备用项目说明文件名或调整合并大小，参考本机版本支持的配置项，例如：

```toml theme={null}
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536
```

不要盲目覆盖现有 `config.toml`。先备份并查看帮助或官方文档：

```bash theme={null}
cp ~/.codex/config.toml ~/.codex/config.toml.backup
```

修改用户级配置后重启 Codex。项目 `.codex` 适合可审查、可共享的项目设置；`~/.codex` 适合个人设置。两者都不应保存明文密钥。

## workspace 与 read-only 的实际选择

### 推荐的切换顺序

对陌生仓库采用三步：

1. `read-only`：读取说明、检查结构、让 Codex 出计划。
2. `workspace-write`：只允许修改当前项目，执行小范围任务。
3. 需要联网或访问工作区外内容时：临时批准单个动作，完成后恢复限制。

不要把“工作区可写”理解成“可以随便执行脚本”。项目内的脚本也可能删除文件、启动服务或读取环境变量。

### 用最小实验验证边界

在临时目录创建测试项目：

```bash theme={null}
mkdir -p ~/codex-sandbox-demo
cd ~/codex-sandbox-demo
git init
printf 'hello\n' > README.md
git add README.md
git commit -m "initial demo"
codex --sandbox read-only
```

进入会话后请求：

```text theme={null}
请创建 check.txt，写入 sandbox test。先说明你需要的权限，不要执行其他命令。
```

预期结果：只读模式下 Codex 无法直接写入，可能请求批准或报告被沙箱拒绝。拒绝请求后，退出会话并检查：

```bash theme={null}
test ! -e check.txt && printf 'check.txt was not created\n'
```

如果改用 `workspace-write`，该文件可能在工作区内被创建。再次测试后查看：

```bash theme={null}
git status --short
git diff -- README.md
ls -la
```

这个实验只在空目录做，不要拿真实项目验证完全访问。实验的验收标准是：你能解释哪个模式允许写入、哪个动作触发审批，以及如何用 Git 看见新增文件。

## 一次完整的工作区检查

启动 Codex 前，建议把下面命令保存为自己的检查清单：

```bash theme={null}
printf 'directory: '; pwd
printf 'root: '; git rev-parse --show-toplevel
git switch --show-current
git status --short --branch
git diff --stat
git diff --check
git log -1 --oneline
find . -maxdepth 2 -name 'AGENTS*' -print
```

预期结果应满足：

* `directory` 是任务目录，而不是用户主目录或桌面目录。
* `root` 是你预期的 Git 根目录。
* 当前分支是任务分支，不是无意间停留在共享分支。
* `git status` 的已有改动已经被识别和记录。
* `git diff --check` 没有空白错误。
* 能看到最近一次检查点提交。
* 能列出会影响当前目录的 `AGENTS.md` 文件。

若命令中任意一项与预期不符，先修正环境，暂不启动修改型任务。

## 临时练习项目：第一次使用的默认选项

没有把握时，创建一个三行代码的练习项目：

```bash theme={null}
mkdir -p ~/codex-practice
cd ~/codex-practice
printf 'def add(a, b):\n    return a + b\n' > main.py
git init
git add main.py
git commit -m "initial practice project"
git status --short --branch
```

预期：目录只包含 `main.py` 和 `.git`，工作区干净。先做只读任务：

```text theme={null}
请解释 main.py，并先列出你会如何验证修改结果。不要修改文件。
```

再做一个小修改：

```text theme={null}
给 add 增加类型注解，只修改 main.py，不要新增依赖，不要运行联网命令。完成后说明修改原因。
```

退出会话后验收：

```bash theme={null}
git diff -- main.py
git diff --check
python -m py_compile main.py
git status --short
```

预期是只有 `main.py` 发生预期修改，Python 编译检查成功。若 diff 包含其他文件，或者出现依赖、配置和删除操作，先停止并回滚，不要因为任务很小就跳过检查。

## 失败、回滚与恢复

### 未提交改动的回滚

先查看范围：

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

只放弃一个明确文件：

```bash theme={null}
git restore --source=HEAD -- main.py
```

放弃当前检查点之后的全部工作区改动：

```bash theme={null}
git restore .
git clean -nd
```

`git restore .` 会丢弃已跟踪文件的所有未提交修改；`git clean -nd` 只是预览未跟踪文件。确认清单后，才考虑使用会删除未跟踪文件的命令。不要在同事可能正在使用的目录中执行批量回滚。

### 已提交改动的回滚

如果改动已经提交但还没有共享，先查看提交：

```bash theme={null}
git log --oneline --decorate -5
git show --stat HEAD
```

共享分支上不要改写历史。用新的反向提交：

```bash theme={null}
git revert <commit-id>
```

预期结果是产生一个新的 revert 提交，原提交仍留在历史中。涉及数据库、部署或外部服务时，Git 回滚代码并不等于回滚外部状态，必须使用对应的备份、迁移回退或平台恢复流程。

### 不确定时保留证据

在回滚前保存：

```bash theme={null}
git diff > ../codex-failed-change.patch
git status --short > ../codex-failed-status.txt
```

同时记录 Codex 执行过的命令、审批过的网络操作、失败测试输出和当前分支。这样即使回滚，也能说明发生了什么，不会把问题变成无法复现的“刚才好像改过”。

## 最终验收

在把项目交给下一步任务前，逐项确认：

* [ ] Codex 从正确项目目录启动，路径已用命令验证。
* [ ] 当前分支是任务分支，或你明确批准在现有分支工作。
* [ ] 动手前已有 Git 提交或可用补丁检查点。
* [ ] `AGENTS.md` 的全局、仓库和子目录层级已检查，冲突规则已理解。
* [ ] `.codex` 与 `~/.codex` 的用途没有混淆，配置变更已备份并在重启后验证。
* [ ] 陌生项目先用过 `read-only`，实际修改只在必要时切到 `workspace-write`。
* [ ] 没有把 `.env`、令牌、私钥、客户数据或缓存提交进 Git。
* [ ] `git diff --stat` 和 `git diff` 只显示预期文件。
* [ ] `git diff --check` 通过，且至少运行了一条项目规定的最小测试或构建命令。
* [ ] 失败时知道使用单文件 `git restore`、补丁或 `git revert` 的哪一种恢复方式。

## 本页小结

选择项目时先看来源和数据敏感度；进入项目后先看路径、Git 状态和说明文件；让 Codex 先在 `read-only` 下建立认识，再在 `workspace-write` 下做小修改；用 `AGENTS.md` 固化项目规则，用 `.codex` 保存可审查的项目设置，用 `~/.codex` 管理个人配置；每次重要操作前都留 Git 检查点。

最小可靠流程可以压缩为：

```text theme={null}
选项目 -> 确认路径 -> 检查 AGENTS.md -> 选择沙箱 -> 切任务分支
-> 建 Git 检查点 -> 先只读分析 -> 小范围修改 -> 看 diff 和测试
-> 满意后提交，不满意就按证据回滚
```

参考资料：`参考/codex/02-core-concepts.md`、`参考/codex/06-first-task.md`、`参考/codex/11-agents-md.md`、`参考/codex/25-worktrees.md`。动态命令、参数和界面以本机 Codex 版本及官方文档为准。