AI Agent / 系统课时
更新文档与配置
更新文档与配置
本课以新增请求超时配置为例,演示如何让 Codex同步修改实现、环境变量示例、使用说明和验证命令。完成后,代码默认值、配置名称和文档示例将保持一致,新成员可按说明直接运行项目。
学习目标
- 找出一次代码变更影响的文档与配置面
- 保持默认值、变量名和示例命令一致
- 用自动检查验证配置可加载、文档未过期
建立变更影响清单
配置变更通常至少影响四处:读取代码、默认值、示例配置和用户文档。若项目还有容器、CI 或部署清单,也要搜索同名变量。先让 Codex执行全仓库搜索,再决定实际需要修改的文件。
git grep -n "REQUEST_TIMEOUT_MS"首次新增变量时,预期可能无输出:
<无输出,退出码为 1>退出码 1 在这里表示没有匹配项,不等于命令异常。随后再搜索相近的旧配置名,避免创建重复概念。
实现并记录配置
下面的模块读取 REQUEST_TIMEOUT_MS,缺省值为 5000 毫秒,并拒绝非正整数。它可以独立运行。
// 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}`);同步更新环境变量示例:
printf '%s\n' 'REQUEST_TIMEOUT_MS=5000' > .env.example预期结果:
已创建或覆盖 .env.example,其中包含 REQUEST_TIMEOUT_MS=5000在 README 的配置章节中说明变量含义、单位、默认值和合法范围。配置示例不需要伪造控制台输出,但必须能通过后续命令验证。
## 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`验证默认值与覆盖值
先验证不设置变量时使用默认值:
node config.mjs预期输出:
requestTimeoutMs=5000再验证用户配置能够覆盖默认值:
REQUEST_TIMEOUT_MS=8000 node config.mjs预期输出:
requestTimeoutMs=8000Windows PowerShell 可使用 $env:REQUEST_TIMEOUT_MS="8000" 后再运行 node config.mjs。不同终端的设置语法可以在文档中分别给出,但变量名和含义必须完全相同。
检查遗漏和冲突
完成修改后,再次搜索变量名,确认实现、示例和文档都已同步。
git grep -n "REQUEST_TIMEOUT_MS"预期结果类似:
.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;不要改锁文件;运行默认值与覆盖值验证;最后列出搜索结果。”这样能减少遗漏,也能防止无关依赖升级。