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

# 代理、上下文、工具与模型

> 本篇解释代理、上下文、工具和模型如何共同完成一次任务。

# 代理、上下文、工具与模型

上一页讲了 Codex 的四种入口，但入口只是外在形式。真正决定它如何完成任务的，是四个互相配合的部分：**代理、上下文、工具和模型**。

> 本篇主要参考 `参考/codex/02-core-concepts.md`、`参考/codex/11-agents-md.md` 和 `参考/codex/19-memory.md`。参考材料中的核心表达可以概括为“想 → 做 → 看”，本篇把它整理成适合站点入门读者的心智模型。

## 先看整体关系

一次 Codex 任务大致可以抽象成下面这条链：

```text theme={null}
你的目标
   ↓
模型理解目标,结合上下文形成下一步计划
   ↓
代理选择工具执行动作
   ↓
读取文件 / 搜索代码 / 运行命令 / 修改文件
   ↓
获得输出和错误,再次送回上下文
   ↓
模型检查结果,决定继续、修正或结束
```

模型不是直接“看见整个电脑”，代理也不是无限权限的执行器。它每一步能看到什么、能做什么，取决于当前上下文、已连接工具以及沙箱和审批边界。

## 代理（Agent）

代理是能够在多轮动作中推进任务的执行主体。参考材料使用了一个很准确的三字结构：

1. **想**：读取相关文件、检查目录、分析报错和任务约束；
2. **做**：调用终端、编辑文件、运行测试或其他工具；
3. **看**：查看命令输出、测试结果和 diff，判断是否需要继续。

例如用户说“这个测试为什么失败”，代理可能按以下顺序工作：

```text theme={null}
读取测试文件
→ 查找被测实现
→ 运行失败测试
→ 阅读错误输出
→ 修改最小范围代码
→ 再次运行测试
→ 汇报根因和验证结果
```

这就是代理与普通代码生成的区别：它把代码、命令和结果组织成一个闭环。

## 上下文（Context）

上下文是 Codex 在当前任务中可以利用的信息集合。它可能包括：

* 当前请求和之前的对话；
* 工作目录、文件内容和搜索结果；
* 命令输出、测试失败信息和 Git diff；
* 项目中的 `AGENTS.md` 指令；
* 通过 `@file`、选中代码或其他方式明确提供的内容；
* 已连接工具返回的结果。

上下文并不是越多越好。无关文件、冗长背景和重复说明会消耗上下文空间，还可能让真正重要的约束不够突出。

### 怎样提供高质量上下文

推荐按“目标、范围、约束、验收”提供信息：

```text theme={null}
目标: 修复登录接口在 token 过期时返回 500 的问题。
范围: 只检查 src/auth/ 和对应测试,不要修改数据库迁移。
约束: 保持现有错误响应格式,不要新增第三方依赖。
验收: 运行 pytest tests/auth -q,并补充一个过期 token 测试。
```

如果你在 IDE 中，可以选中相关代码或用 `@file` 引用文件；如果在 CLI 中，可以明确写出路径，让代理少做猜测。

### `AGENTS.md` 是稳定上下文

参考材料把 `AGENTS.md` 比作项目的“入职手册”或“交接清单”。它适合放每一轮都应遵守的确定性规则，例如：

* 项目使用什么语言、框架和包管理器；
* 测试、构建、格式化和 lint 命令；
* 目录约定和命名规则；
* 哪些目录不能修改；
* 提交前必须完成哪些检查。

示例：

```md theme={null}
# 项目规则

## 常用命令
- `pytest -q` - 运行测试
- `ruff check .` - 运行静态检查

## 约定
- 新增函数必须有类型注解
- 修改完成后先运行相关测试

## 禁区
- 不要直接修改 `migrations/` 中已经提交的文件
- 新增生产依赖前先向我确认
```

信息越接近当前工作目录，通常越具体；根目录规则可以作为全局约束，子目录规则可以补充模块的特殊要求。重要规则不要只依赖自动记忆。

## 工具（Tools）

工具是代理把计划变成实际动作的接口：

| 工具类别 | 典型动作               | 作用           |
| ---- | ------------------ | ------------ |
| 文件工具 | 读取、搜索、编辑、创建文件      | 了解和修改代码库     |
| 终端工具 | 运行测试、构建、Git 和包管理命令 | 获取可验证的运行结果   |
| 版本控制 | 查看 diff、提交、切换分支    | 追踪改动并提供回滚点   |
| 外部连接 | MCP、浏览器或云端服务       | 访问本地之外的工具和数据 |

工具调用不等于无限授权。每个动作仍然受到当前工作目录、沙箱、审批策略和工具自身安全标记的影响。

## 模型（Model）

模型负责理解任务、分析上下文和决定下一步；代理负责调度动作；工具负责执行动作。三者不要混为一谈：模型强不代表它可以突破沙箱，工具多不代表每个工具都默认可用，代理会循环也不代表它能替你确认需求。

模型选择通常需要在质量、速度和成本之间取平衡：

| 任务              | 通常的选择思路                  |
| --------------- | ------------------------ |
| 查目录、解释简单代码      | 速度优先的轻量模型即可              |
| 常规开发和 Bug 修复    | 使用默认推荐模型，从中等推理强度开始       |
| 跨模块重构、复杂调试和设计审查 | 选择能力更强的模型，并提供清晰验收条件      |
| 批量自动化           | 优先稳定、可预测和结构化输出，不要只追求最大模型 |

具体模型名称和可用档位变化较快，使用时可以通过入口提供的模型选择器或 `/model` 查看当前可用项。

## 一次任务的完整循环

把四个概念合在一起，一次任务可以拆成六步：

1. **接收目标**：理解用户想要的结果和限制；
2. **加载上下文**：读取项目规则、相关文件和已有改动；
3. **制定下一步**：决定先搜索、先运行测试还是先询问；
4. **调用工具**：执行读取、编辑、命令或外部工具动作；
5. **检查反馈**：分析输出、错误、测试和 diff；
6. **继续或交付**：必要时修正，完成后报告改动与验证结果。

你可以把这个循环理解为一个会自我检查的开发搭档，但不能把它理解为“自动正确”。它可能选错文件、错误解释业务规则或引入不必要改动，所以验收环节不可省略。

## 记忆与规则的区别

参考材料特别强调了 `AGENTS.md` 与 Memories 的区别：

| 机制          | 谁维护            | 适合放什么             | 可靠性          |
| ----------- | -------------- | ----------------- | ------------ |
| `AGENTS.md` | 你或团队手动维护       | 必须每次生效的项目规则       | 确定性，随仓库共享    |
| Memories    | Codex 根据过往会话生成 | 稳定偏好、反复出现的工作方式和经验 | 异步生成，属于补充上下文 |

“测试必须使用 `pytest`”应写进 `AGENTS.md`；“这个项目通常先启动本地服务再调试”可以作为记忆候选。密码、API key、token 等敏感信息不应写入项目规则、日志或记忆。

## 小结

* 代理通过“想 → 做 → 看”的循环推进任务；
* 上下文决定它当前知道什么，应该精简并明确范围；
* 工具把计划变成文件、命令和外部服务动作，但仍受权限边界约束；
* 模型负责理解和决策，不等于拥有执行权限；
* `AGENTS.md` 保存确定性的项目规则，自动记忆只作为补充；
* 任务结果必须通过测试、diff 和人工判断验收。

下一篇将把这套循环放进真实的安全边界中：[任务循环、沙箱、审批与 Git](/01-认识-Codex/04-任务循环沙箱审批与Git)。