AI Agent / 系统课时

更新文档与配置

更新文档与配置

本课以新增请求超时配置为例,演示如何让 Codex同步修改实现、环境变量示例、使用说明和验证命令。完成后,代码默认值、配置名称和文档示例将保持一致,新成员可按说明直接运行项目。

学习目标

  • 找出一次代码变更影响的文档与配置面
  • 保持默认值、变量名和示例命令一致
  • 用自动检查验证配置可加载、文档未过期

建立变更影响清单

配置变更通常至少影响四处:读取代码、默认值、示例配置和用户文档。若项目还有容器、CI 或部署清单,也要搜索同名变量。先让 Codex执行全仓库搜索,再决定实际需要修改的文件。

bash
git grep -n "REQUEST_TIMEOUT_MS"

首次新增变量时,预期可能无输出:

text
<无输出,退出码为 1>

退出码 1 在这里表示没有匹配项,不等于命令异常。随后再搜索相近的旧配置名,避免创建重复概念。

实现并记录配置

下面的模块读取 REQUEST_TIMEOUT_MS,缺省值为 5000 毫秒,并拒绝非正整数。它可以独立运行。

js
// config.mjs
const rawTimeout = process.env.REQUEST_TIMEOUT_MS ?? "5000";
const requestTimeoutMs = Number(rawTimeout);

if (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs <= 0) {
  throw new Error("REQUEST_TIMEOUT_MS must be a positive integer");
}

export const config = {
  requestTimeoutMs
};

console.log(`requestTimeoutMs=${config.requestTimeoutMs}`);

同步更新环境变量示例:

bash
printf '%s\n' 'REQUEST_TIMEOUT_MS=5000' > .env.example

预期结果:

text
已创建或覆盖 .env.example,其中包含 REQUEST_TIMEOUT_MS=5000

在 README 的配置章节中说明变量含义、单位、默认值和合法范围。配置示例不需要伪造控制台输出,但必须能通过后续命令验证。

markdown
## Configuration

`REQUEST_TIMEOUT_MS` controls the outbound request timeout in milliseconds.

- Default: `5000`
- Valid value: a positive integer
- Example: `REQUEST_TIMEOUT_MS=8000 node config.mjs`

验证默认值与覆盖值

先验证不设置变量时使用默认值:

bash
node config.mjs

预期输出:

text
requestTimeoutMs=5000

再验证用户配置能够覆盖默认值:

bash
REQUEST_TIMEOUT_MS=8000 node config.mjs

预期输出:

text
requestTimeoutMs=8000

Windows PowerShell 可使用 $env:REQUEST_TIMEOUT_MS="8000" 后再运行 node config.mjs。不同终端的设置语法可以在文档中分别给出,但变量名和含义必须完全相同。

检查遗漏和冲突

完成修改后,再次搜索变量名,确认实现、示例和文档都已同步。

bash
git grep -n "REQUEST_TIMEOUT_MS"

预期结果类似:

text
.env.example:1:REQUEST_TIMEOUT_MS=5000
README.md:<LINE>:`REQUEST_TIMEOUT_MS` controls the outbound request timeout in milliseconds.
config.mjs:1:const rawTimeout = process.env.REQUEST_TIMEOUT_MS ?? "5000";

<LINE> 是实际行号。若代码默认值为 5000、README 却写 3000,测试可能仍通过,但使用者会得到错误预期,因此文档一致性必须作为验收项。

控制 Codex的修改范围

给 Codex的任务应明确列出必须同步的文件类型,并要求报告未修改项。例如:“新增该环境变量;更新 .env.example 和 README;不要改锁文件;运行默认值与覆盖值验证;最后列出搜索结果。”这样能减少遗漏,也能防止无关依赖升级。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

更新文档与配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通