> ## 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.

# 05-出错后的恢复与止损

> 面对中断任务、误改文件、测试失败、权限误放、密钥疑似泄露和网络外发时，按情景止血、取证、恢复、升级并完成安全验收。

## 这页解决什么问题

代理任务出错时，最危险的动作往往不是最初那一步，而是慌乱中继续执行、覆盖现场、扩大权限，或用宽泛的回滚命令把正确的工作一起删掉。本页提供一套可重复的处置流程：先停止影响，保留证据，判断范围，选择可逆恢复方式，最后用检查结果证明环境已经恢复到可接受状态。

适用情景：

* Codex 或脚本没有按预期停止，任务被中断或卡住；
* 代理改错文件、改了不该改的文件，或产生未预期的新文件；
* 测试、构建、类型检查失败，无法判断是基线问题还是本次回归；
* 误把审批、网络、完全访问或系统权限放得过宽；
* `.env`、token、API key、SSH key、cookie 或客户数据疑似进入上下文、日志、截图或网络请求；
* 代码、日志或文件被上传、推送、发送到不该去的地址；
* Git 工作区、分支、提交、reflog 或 worktree 需要恢复。

涉及权限时，以当前版本的 `codex --help`、`/status` 和官方文档为准；不要把示例命令当成对生产系统的授权。

> 参考资料：`参考/codex/15-permissions.md`、`参考/codex/16-security.md`、`参考/codex/37-faq.md`、`参考/codex/06-first-task.md`。

## 一、先记住六个动作

```text theme={null}
停止 -> 隔离 -> 保留证据 -> 判断范围 -> 恢复 -> 验收与升级
```

### 1. 停止

立即取消 Codex 当前回合、停止相关脚本，必要时关闭终端任务或测试进程。可以使用界面停止控制、`Esc`、`Ctrl+C` 或终端对应的终止方式，以当前客户端提示为准。不要为了“让它把最后一步做完”继续批准未知操作。

如果是浏览器或桌面任务，先夺回鼠标键盘控制权，确认焦点不在生产窗口、付款页、邮件发送框或删除确认框。无法确认状态时，先停止，不要点击试探。

### 2. 隔离

疑似外发时关闭网络、暂停 CI job、撤销临时域名放行；疑似凭据暴露时暂时禁用账号、token 或 session；代码异常时停止部署、合并和发布；桌面误操作时关闭目标测试应用或断开测试网络。隔离用于阻止新副作用，不是立刻抹掉所有痕迹。

### 3. 保留证据

保存最少必要证据：发生时间、操作者、入口和版本、任务原文、最后一次批准、是否取消、`git status --short`、`git diff --stat`、失败命令和退出码、访问过的 host、上传目标、CI job、PR 或提交编号。证据中的 token、cookie、Authorization、私钥和个人数据先脱敏，不要贴入公开工单。

### 4. 判断范围

回答四个问题：

1. 影响只在工作区，还是进入 Git 历史、远端、日志、缓存、artifact 或外部系统？
2. 影响是文件、配置权限、进程、账号凭据，还是外部业务状态？
3. 是否影响其他人、客户、CI、部署环境或生产资源？
4. 是否有证据证明影响没有继续扩大？

无法证明“没有泄露”时，凭据按已泄露处理；无法证明“没有外部副作用”时，按可能发生处理并升级。

### 5. 恢复

优先使用可逆、范围明确的动作。先恢复到已知状态，再重新执行小步骤；不清楚差异时，不使用 `git reset --hard`、批量删除、强制推送或覆盖备份。

### 6. 验收与升级

恢复后重新检查工作区、权限、网络、凭据、测试和外部审计。涉及生产、客户数据、支付、真实凭据、外发或合规事件时，按组织安全事件、值班和变更流程升级。

## 二、事故记录与启动前检查点

### 最小事故记录

```text theme={null}
时间：
操作者 / 会话：
客户端与版本：
项目路径与 Git 分支：
任务目标与禁止事项：
发现异常的时间与现象：
最后一次确认的命令、审批或点击：
涉及文件、进程、域名和外部系统：
已采取的停止与隔离动作：
凭据是否按已泄露处理：
当前工作区和外部状态：
恢复动作与结果：
未验证事项、负责人和升级对象：
```

不要记录完整密码、API key、私钥、cookie、客户原文或可复用登录链接。使用“key-03 已撤销”“staging.example.test”“数据已脱敏”等可追踪标识。

### 确认目录、分支和工作区

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

Windows PowerShell：

```powershell theme={null}
Get-Location
git status --short --branch
git branch --show-current
```

确认目录是目标项目，当前分支不是生产发布分支，既有修改属于你或已经记录。发现未识别修改时，不要执行会覆盖它们的回滚命令。

### 建立 Git 检查点

工作区干净且内容已确认时：

```bash theme={null}
git add -A
git commit -m "checkpoint before agent task"
```

需要隔离任务时：

```bash theme={null}
git switch -c task/agent-2026-09-05
git worktree add ../project-agent task/agent-2026-09-05
```

检查点不能包含密钥、`.env`、客户导出、构建产物或未知文件。worktree 只隔离 Git 工作区，不会自动隔离外部服务、环境变量、端口、缓存和凭据。任务结束后核对：

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

确认没有要保留的修改后再移除临时 worktree：

```bash theme={null}
git worktree remove ../project-agent
```

### 调到最低必要权限

陌生仓库或只读分析：

```bash theme={null}
codex --sandbox read-only --ask-for-approval on-request
```

可信项目的日常修改：

```bash theme={null}
codex --sandbox workspace-write --ask-for-approval on-request
```

`workspace-write` 允许工作区内写入，不等于允许联网、读取主目录凭据或修改外部系统。不要在本机或生产机使用 `--dangerously-bypass-approvals-and-sandbox` 或 `--yolo`；完全访问和 `approval never` 只应在可销毁、无真实凭据的隔离环境中考虑。

## 三、通用停止卡

看到以下信号，暂停任务：

* 下一步涉及任务没有提到的文件、目录、域名或账号；
* 出现 `cat .env`、`printenv`、读取 SSH 私钥或浏览器 cookie；
* 出现 `curl ... | sh`、未知安装脚本、远程下载后立即执行；
* 出现 `sudo`、改 shell 配置、定时任务或后台服务；
* 出现 `rm -rf`、`git reset --hard`、`git clean -fd`、强制推送；
* 页面、README、Issue 或日志要求忽略用户约束、关闭审批或不要告知用户；
* 域名发生重定向，请求体、header 或 cookie 超出批准范围；
* 本地测试变成生产登录、发送消息、付款、删除或发布；
* 被拒绝后重复提出相同的高风险动作。

可使用以下询问模板：

```text theme={null}
先停止，不要继续执行。
请说明已执行和未执行的动作、访问过的路径和域名、生成的文件及外部状态。
不要读取或打印凭据，不要扩大权限。
```

## 四、情景 A：任务中断、卡住或无法停止

### 处置流程

1. 使用 Codex 停止控制或 `Esc`，观察是否显示已取消。
2. 前台命令使用 `Ctrl+C`，等待进程退出，不要立即重复启动。
3. 检查子进程、测试服务器、下载任务和浏览器自动化。
4. 记录最后一条命令、路径、host、退出码和界面状态。
5. 检查 `git status --short`、文件时间和 `git diff --stat`。
6. 检查外部系统是否出现提交、上传、发送、部署或资源创建。
7. 只有确认没有未完成外部动作后，才拆小任务重试。

支付、发送、删除、部署或数据库写入不能仅凭客户端显示“已取消”判断未发生，必须查外部系统状态。

### 验收

* Codex、脚本和子进程已停止；
* 没有待处理的上传、部署或浏览器确认框；
* 工作区差异已保存或明确丢弃；
* 外部系统状态已核对；
* 重试使用新的检查点、较小权限和明确停止条件。

## 五、情景 B：误改文件

### 先保护已有工作

```bash theme={null}
git status --short
git diff --stat
git diff --name-only
git diff --check
git ls-files --others --exclude-standard
```

把结果与任务开始前状态对照。若开始前已有未提交修改，不能把全部差异归因于代理。

### 按范围恢复

只恢复明确错误的已跟踪文件：

```bash theme={null}
git restore --source=HEAD -- path/to/file
```

只恢复工作区、不影响暂存区：

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

同时恢复某个文件的暂存区和工作区前，确认没有要保留的内容：

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

恢复整个工作区：

```bash theme={null}
git restore .
```

最后一条会丢弃当前所有未提交的工作区修改，只能在确认全部不要时使用。未跟踪文件不会被 `git restore` 删除；删除前先预览：

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

只有确认清单全部可丢弃后，才考虑 `git clean -fd -- path/to/file`。不确定时保留文件或先导出补丁：

```bash theme={null}
git diff > ../agent-current.patch
git diff --binary > ../agent-current.binary.patch
```

### 验收

确认目标文件恢复到明确版本，原有修改没有被覆盖，未跟踪文件已经分类，`git diff --check` 通过，状态只显示预期内容，补丁和临时副本不在仓库中。

## 六、情景 C：测试、构建或类型检查失败

### 先保存现场

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

保存不含秘密的错误输出、测试名称、退出码和环境版本。不要复制完整环境变量、连接串或生产日志。

### 与基线比较

有检查点时，在独立 worktree 运行基线：

```bash theme={null}
git worktree add ../project-baseline HEAD
cd ../project-baseline
<项目的最小测试命令>
```

再在任务 worktree 运行同一命令：

| 结果        | 判断            | 下一步            |
| --------- | ------------- | -------------- |
| 基线通过，改动失败 | 很可能是本次回归      | 缩小 diff，修复后重跑  |
| 基线也失败     | 原有问题或环境问题     | 记录基线失败，不伪装成完成  |
| 两边随机失败    | 不稳定环境或外部依赖    | 固定依赖、隔离网络、重复验证 |
| 命令无法启动    | 安装、路径、权限或配置问题 | 先修环境，不盲改业务代码   |

要求代理一次只处理一个失败类别：

```text theme={null}
测试失败。先不要扩大修改范围。
列出失败测试、第一处错误、基线是否也失败，以及准备修改的文件。
不得读取凭据、联网、升级依赖或修改全局配置。
确认后只修复这个失败，再运行同一条测试命令。
```

不要删断言、跳过测试、降低校验、锁死错误输出或修改全局配置来制造假绿。修复后查看 diff，并记录命令、结果和未覆盖范围。

### 验收

基线与修复结果可区分；失败原因、命令和退出码已记录；相关格式、类型、单元测试、集成测试或构建已完成；仍失败的项目已升级，而不是标记为完成。

## 七、情景 D：权限、审批或网络误放

### 立即收紧

误启用完全访问、`approval never`、全局网络、全局域名白名单、永久浏览器访问或系统辅助功能时：

1. 停止任务和子进程；
2. 关闭网络或移除临时域名放行；
3. 退出高权限会话；
4. 检查配置、启动参数和 `/status`；
5. 撤销“始终允许”、MCP、插件、浏览器扩展和不再需要的系统权限；
6. 审计高权限期间的命令、文件和网络请求；
7. 无法确认访问范围时，按可能越权处理并升级。

不要用“改回配置文件”替代审计。已放开的权限可能已经让动作发生。

### 验收

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

确认沙箱、审批、工作区目录和网络符合任务需要；不再需要的永久授权已撤销；高权限期间的访问已核对；没有把高权限配置提交到仓库或复制到共享机器；继续任务使用低权限新会话和新检查点。

## 八、情景 E：密钥或隐私数据疑似泄露

### 按已泄露处理的信号

密钥被打印到对话、终端、日志、截图、CI artifact 或错误堆栈；`.env`、SSH 私钥、云凭据、cookie、客户导出被不必要读取；命令、插件、网页或 API 可能外发敏感内容；秘密进入 Git、远端、PR、Issue、聊天或工单；或无法确认上传是否包含敏感数据。

“没有看到响应”不等于“没有发送”；网络默认关闭也不能覆盖已经开启的网络、浏览器登录态、插件或外部进程。

### 止血、轮换、通知

1. 停止 Codex、脚本、浏览器自动化和相关 CI job。
2. 关闭网络或撤销临时域名访问。
3. 不要在原会话粘贴新密钥验证。
4. 记录受影响凭据类型和时间范围，不记录完整值。
5. 先撤销旧凭据，再生成新的短期、低权限凭据。
6. 注销相关浏览器 session、OAuth token、PAT 和云会话。
7. 通知凭据所有者、安全负责人和服务管理员。
8. 保存脱敏证据，不删除服务端审计日志。
   \| 类型 | 立即动作 | 后续核对 |
   \|---|---|---|
   \| API key / PAT | 撤销并重发 | 调用记录、host 和权限 |
   \| SSH key | 撤销 deploy key 或删除授权 | 登录和仓库访问日志 |
   \| 云密钥 | 禁用旧 key | 资源、区域和权限使用 |
   \| 数据库密码 | 修改密码、终止旧连接 | 查询、导出和连接来源 |
   \| OAuth / cookie | 撤销 session 和 token | 登录地点和授权应用 |
   \| CI secret | 暂停流水线并轮换 | 日志、artifact、缓存和 fork |
   \| webhook | 轮换并验证回调 | 重复投递和伪造请求 |

### Git 历史中的秘密

先轮换，再清理。普通 `git restore` 或新的提交不能让旧提交消失：

1. 撤销并轮换秘密；
2. 暂停推送、合并和发布；
3. 检查远端、PR、镜像、缓存和 fork；
4. 按组织流程使用受控历史清理工具；
5. 强制推送或重写共享历史前，取得仓库负责人、安全负责人和协作者批准；
6. 用秘密扫描和服务端审计确认残留范围。

### 验收

旧凭据已撤销；新凭据未进入会话、命令行、Git、日志或截图；访问日志、artifact 和缓存已检查；受影响范围有记录；无法确认的部分写入未验证假设并完成升级。

## 九、情景 F：代码、日志或文件已经网络外发

外发可能通过 `curl`、包管理器、Git remote、插件、MCP、浏览器上传、截图、错误上报、CI artifact 或第三方 API 发生。

### 处置流程

1. 停止命令、任务和重试队列；
2. 记录目标 host、最终 URL、HTTP 方法、时间和数据类别；
3. 关闭网络或撤销目标域名放行；
4. 取消未完成上传、部署和外部任务；
5. 不再次访问可疑地址“测试一下”；
6. 检查请求日志、shell 历史、浏览器下载、插件日志和 CI 记录；
7. 联系目标服务管理员，按流程保留或删除数据；
8. 含凭据或个人数据时按泄露流程轮换和升级。

核对重定向后的 host、query、header、cookie、请求体、shell 管道输出、Git remote、浏览器账号和上传文件。服务端是否保存日志、缓存、artifact 或备份也要确认。

### 验收

已经确认是否发生请求、上传、推送或提交；目标、时间、数据类别和外部状态有记录；外发通道已关闭或收紧；受影响密钥已轮换；外部服务清理和审计请求已交办；调查命令没有再次外发数据。

## 十、Git 恢复：restore、revert、reflog

### `git restore`：撤销未提交文件修改

```bash theme={null}
git restore -- path/to/file
git restore --source=HEAD -- path/to/file
```

它恢复工作区文件，不删除提交，也不改变分支指针；执行前必须确认会丢弃的内容。

### `git revert`：用新提交撤销已提交内容

共享分支上的错误提交不要直接改写历史：

```bash theme={null}
git show --stat <commit>
git log --oneline --decorate -n 10
git revert <commit>
```

`revert` 保留原提交和审计链。回退后仍要测试，因为反向提交可能与后续提交冲突。

### `git reflog`：找回本地曾指向的状态

误执行 reset、切错分支或提交看似消失时：

```bash theme={null}
git reflog --date=local
git show --stat <reflog-commit>
git branch recovery/2026-09-05 <reflog-commit>
```

先建立恢复分支，再决定如何带回内容。reflog 是本地记录，不是远端审计，也不会无限期保留。

### `reset` 的边界

`reset --hard` 可能丢弃未提交内容。共享分支和不明状态下不要使用；确需使用时，先复制工作区、保存补丁、记录当前 HEAD，并确认没有他人修改。

恢复后检查：

```bash theme={null}
git status --short --branch
git diff --stat
git diff --check
git log --oneline --decorate -n 5
```

## 十一、分支、worktree 与外部状态

任务分支未推送时，确认需要保留的内容已备份后，再删除已合并分支：

```bash theme={null}
git switch main
git branch -d task/fix-login-timeout
```

不要用 `-D` 绕过保护。任务分支已经推送时，优先修复提交或 `git revert`，不要对共享分支强制推送。秘密清理需要重写历史时，必须经过负责人批准、备份、冻结窗口和协作者通知。

检查 worktree：

```bash theme={null}
git worktree list
git -C ../project-agent status --short --branch
git -C ../project-main status --short --branch
```

Git worktree 不能阻止两个任务同时写同一个远端、部署环境、文件锁、端口或测试数据库。发生交叉污染时先停止相关任务，记录来源，再按外部系统的回滚机制处理。

## 十二、事故升级

以下情况不能自己收尾，应立即通知项目负责人、安全负责人或值班人员：

* 真实密钥、客户数据、个人数据或生产配置可能泄露；
* 发生未知域名外发、账号异常访问、数据下载或权限提升；
* 生产系统、支付、删除、发布或数据库写入已经发生；
* 共享分支、公共仓库、PR、CI artifact 或镜像包含秘密；
* 无法确认影响范围，或审计日志可能被覆盖；
* 恢复需要强制推送、历史重写、服务端删除或管理员权限；
* 同类问题可能影响其他项目、账号或自动化任务。

升级消息应包括时间线、影响对象、已停止动作、凭据处理、证据位置、当前状态、未验证假设和请求的决策。不要贴秘密原文、完整日志或未经脱敏的客户数据。

## 十三、分情景恢复卡

### 中断任务

```text theme={null}
停止任务和子进程
-> 检查上传、部署、发送和提交是否在途
-> 保存状态、命令、退出码和外部记录
-> 缩小任务与权限后再重试
```

### 误改文件

```text theme={null}
保存 status / diff
-> 区分既有修改与本次修改
-> 按文件 restore 或保留补丁
-> 检查未跟踪文件
-> 重新运行最小验证
```

### 测试失败

```text theme={null}
保存失败输出
-> 在干净基线复跑
-> 判断基线失败还是回归
-> 一次只修一个原因
-> 用同一命令复验并记录剩余风险
```

### 权限误放

```text theme={null}
停止高权限会话
-> 关闭网络、撤销永久授权
-> 核对 /status 和配置
-> 审计高权限期间动作
-> 用低权限新会话重新开始
```

### 密钥疑似泄露

```text theme={null}
停止并隔离
-> 旧凭据立即撤销
-> 检查日志、历史、artifact 和调用记录
-> 生成新凭据并最小化权限
-> 通知安全负责人并记录未验证范围
```

### 网络外发

```text theme={null}
停止重试并记录目标
-> 核对最终 host、请求体和外部状态
-> 关闭外发通道
-> 按数据类别通知和轮换
-> 完成服务端审计与清理
```

## 十四、安全验收

恢复完成不等于任务完成。至少执行：

### 工作区与 Git

```bash theme={null}
git status --short --branch
git diff --stat
git diff --check
git ls-files --others --exclude-standard
```

确认只剩预期修改；没有秘密、客户数据、截图、补丁、下载包或临时配置进入仓库。

### 权限与网络

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

确认沙箱、审批、工作区目录和网络符合任务需要。关闭临时网络，移除不再需要的域名、MCP、插件、浏览器扩展和系统授权，确认没有遗留全局完全访问或“始终允许”。

### 凭据与隐私

* 旧 key、token、cookie、session 和 SSH key 已撤销，或有证据证明未触及；
* 新凭据只通过受控 secret 注入，不出现在命令行、提示词、日志、截图和 Git；
* 工作区、`/tmp`、artifact、缓存、CI 日志和下载目录已检查；
* 客户数据、个人数据和内部 URL 已脱敏；
* 服务端调用日志和登录审计没有未解释的访问。

### 测试与外部状态

* 最小复现已经通过；
* 相关格式、类型、单元测试、集成测试或构建已经完成；
* 基线失败和环境限制单独记录；
* 外部状态、数据库、测试账号、浏览器 session 和临时资源已恢复或明确交接；
* 没有用跳过测试、关闭安全检查或扩大权限制造假成功。

### 记录与升级

* 时间线、命令、审批、证据和恢复动作已记录；
* 未验证假设和剩余风险有负责人；
* 需要升级的事件已经通知正确对象；
* 记录不包含可复用秘密；
* 至少落实一项改进：更小权限、更小任务、更清晰检查点、更严格网络限制或更好监控。

## 十五、不要这样恢复

* 还没看 diff 就执行 `git restore .`；
* 用 `git reset --hard` 覆盖同事的未提交工作；
* 用 `git clean -fd` 清理未知文件却不先预览；
* 为了测试变绿而删除测试或放宽鉴权；
* token 进日志后只删本地日志、不轮换 token；
* 疑似外发后再次请求可疑地址确认；
* 用 `--yolo` 或 `approval never` 重新跑一遍；
* 把完整事件日志、`.env` 或截图贴到公开 Issue；
* 在共享分支上强制推送以掩盖错误提交；
* 看到客户端显示中断，就假设上传、部署或付款没有发生。

恢复的目标是可证明地降低影响，不是让屏幕尽快变绿。

## 十六、可直接复制的任务约束

### 开始前

```text theme={null}
先读取相关文件和测试，不要修改无关内容。
先报告当前目录、Git 分支、工作区状态和计划。
默认不联网，不读取 .env、SSH 私钥、云凭据、cookie、客户数据或生产日志。
网络、上传、删除、提权、提交、推送和发布都必须先暂停并说明。
开始前建立可恢复的 Git 检查点，完成后展示 diff 和验证结果。
```

### 发生异常时

```text theme={null}
立即停止，不要重试或扩大权限。
列出已执行和未执行的动作、路径与域名、生成的文件和外部状态。
保留必要的脱敏证据，不要打印或粘贴凭据。
先给出影响范围、恢复选项和风险，再等待确认。
```

### 测试失败时

```text theme={null}
不要删除测试、跳过检查、升级依赖或修改全局配置来制造通过。
先保存非敏感错误输出，并在干净基线复跑同一命令。
区分基线失败、环境失败和本次改动回归。
一次只修复一个原因，修改后展示 diff 并重新验证。
```

## 小结

安全恢复不是记住一条万能回滚命令，而是保持顺序和边界：先停止、隔离、保留证据；再区分工作区、Git 历史、凭据、网络和外部系统；最后用明确检查结果证明已经恢复。

最重要的判断：

1. **未提交文件改动**优先用范围明确的 `git restore`，不要盲目恢复整个工作区。
2. **已提交或已推送错误**优先用新提交和 `git revert`，共享历史不要随意重写。
3. **疑似泄露凭据**按已泄露处理，先撤销轮换，再调查清理。
4. **不确定的外部副作用**不能靠本地界面推断，必须查服务端记录并升级。

完成处置后应能回答：

```text theme={null}
当前还有哪些进程在运行？
工作区、分支和历史是否只包含预期内容？
权限和网络是否收回到最低必要范围？
哪些数据被读取、写入、上传或进入日志？
凭据、外部状态和测试结果是否已经核对？
还有哪些事实没有证据，谁负责继续处理？
```

答不出其中任何一项，就不要把任务标记为完成。对生产、客户数据、支付、真实凭据和未知外发，继续按组织事件响应流程处理。