Agent 改完代码后，让开发文档与实现保持一致

Agent 修改配置名称后，要更新开发者真正会照着操作的说明：示例命令、可接受的值、默认行为、错误处理和迁移说明。每一项表述都要能追溯到变更后的源码。同时，区分命令是否实际执行，以及仅从代码看它应当怎样运行。

“改进了报告配置”这样流畅的概述，并不能告诉下一位开发者应该设置哪个变量。README 若保留旧变量，甚至可能比缺少说明更误导：命令或许仍能运行，却在不声不响地使用默认值。

本教程构造了一个小型虚构报告脚本及其修订后的 README。下面的代码、路径和旧版文档都是原创教学材料。命令与输出仅用于说明，并未为本文实际执行。

从读者要完成的操作入手

假设一位开发者希望本地报告脚本输出 JSON。Agent 已经重命名一个环境变量，并增加校验。文档的任务，是让这位开发者能够选择输出格式，并识别无效配置。

虚构的旧实现用以下代码选择格式：

output = os.environ.get("REPORT_FORMAT", "text")

旧版 README 的说明如下：

英文锁定原文：

## Print a report

Run the script from the repository root:

```sh
REPORT_FORMAT=json python3 tools/summary.py
```

Set REPORT_FORMAT to json for structured output. Omit it for text.

完整中文对照：

## 打印报告

在仓库根目录运行脚本：

```sh
REPORT_FORMAT=json python3 tools/summary.py
```

将 REPORT_FORMAT 设为 json 可获得结构化输出。不设置则输出文本。

这段文字描述的是旧配置。它没有提到无效值，因为示例中后来新增的校验在那个阶段还不存在。

重写前，先找出这次变更影响的所有读者操作。这里有三项：运行默认报告、请求 JSON，以及修正被拒绝的值。从旧命令迁移则是值得明确说明的第四项操作。

先读变更后的代码，再写说明

下面是这个虚构示例位于 tools/summary.py 的完整替换脚本：

import json
import os
import sys


def main():
    output = os.environ.get("REPORT_OUTPUT", "text")
    if output not in {"text", "json"}:
        print("REPORT_OUTPUT must be text or json", file=sys.stderr)
        return 2

    summary = {"open": 3, "total": 8}
    if output == "json":
        print(json.dumps(summary, sort_keys=True))
    else:
        print(f"Open: {summary['open']}; total: {summary['total']}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

这段简短源码足以支持几项文档决定：它只读取 REPORT_OUTPUT；缺少这个配置时选择 text；两个允许值都是小写字符串，并且要求完全匹配，所以空字符串也是无效值。遇到无效配置，函数会在打印报告前返回。

源码没有为 REPORT_FORMAT 实现兼容别名。沿用旧 README 的命令，并不能让这个替换脚本输出 JSON。只要 REPORT_OUTPUT 不存在，即使设置了旧变量，脚本也会走文本分支。

这些判断来自展示的源码，而不是 Agent 对其修改意图的描述；它们的范围也小于实际运行结论。读过代码，并不能证明某个仓库确实在文档所写路径下有这个文件，也不能证明读者已经具备可用的解释器。

把源码事实对应到文档位置

用一张简短映射表查漏，填写这次变更中实际出现的标识符和分支。

这是一种维护辅助，不是另一份需要永久维护的规范。文档修订完成后，源码与面向读者的操作说明仍是关键材料。如果某次迁移不太直观，审阅记录中可以保留这张映射表帮助解释。

完整替换受影响的 README 小节

只修改第一条命令里的变量，可能会把下方相互矛盾的文字留在原处。下面给出完整替换小节，覆盖读者需要完成的操作，同时不加入代码里没有的功能：

英文锁定原文：

## Print a sample report

This script prints a fixed teaching sample with 3 open items out of 8 total
items. It does not read a database or calculate live project totals.

### Requirements and location

Save the accompanying example as tools/summary.py. The commands below use
a POSIX-style shell and an available Python 3 interpreter named python3.
Run them from the directory containing tools/.

These commands and outputs are illustrative examples, not recorded runs.
Check the interpreter and command behavior in your target environment.

### Choose an output format

| Variable | Accepted values | When absent |
| --- | --- | --- |
| REPORT_OUTPUT | text, json | text |

Values are case-sensitive. An empty value is invalid.

For text, set the format explicitly:

```sh
REPORT_OUTPUT=text python3 tools/summary.py
```

Expected text for the accompanying sample:

```text
Open: 3; total: 8
```

For JSON:

```sh
REPORT_OUTPUT=json python3 tools/summary.py
```

Expected JSON for the accompanying sample:

```json
{"open": 3, "total": 8}
```

When REPORT_OUTPUT is absent, the script selects text. If your shell
already defines it, invoking the script without a prefix uses that value.

### Invalid configuration

A value other than text or json is intended to produce this diagnostic on
standard error and exit with status 2, without printing a report:

```text
REPORT_OUTPUT must be text or json
```

The success branches return status 0.

### Migrate the old setting

Replace REPORT_FORMAT with REPORT_OUTPUT in scripts and local command
examples. This version does not read REPORT_FORMAT. Setting only the old
variable leaves REPORT_OUTPUT absent and therefore selects text, unless
REPORT_OUTPUT is already set elsewhere in the environment.

完整中文对照：

## 打印一份示例报告

这个脚本打印一组固定的教学样例：共8项，其中3项尚未完成。
它不读取数据库，也不计算项目的实时总数。

### 环境要求与文件位置

将随附示例保存为 tools/summary.py。以下命令使用 POSIX 风格的 shell，
并要求有名为 python3 的可用 Python 3 解释器。
从包含 tools/ 目录的位置运行这些命令。

这里的命令和输出是说明性示例，不是实际运行记录。
请在目标环境检查解释器及命令行为。

### 选择输出格式

| 变量 | 允许值 | 不存在时 |
| --- | --- | --- |
| REPORT_OUTPUT | text, json | text |

值区分大小写。空值属于无效值。

输出文本时，明确设置格式：

```sh
REPORT_OUTPUT=text python3 tools/summary.py
```

随附样例的预期文本：

```text
Open: 3; total: 8
```

输出 JSON：

```sh
REPORT_OUTPUT=json python3 tools/summary.py
```

随附样例的预期 JSON：

```json
{"open": 3, "total": 8}
```

当 REPORT_OUTPUT 不存在时，脚本选择文本输出。如果 shell 已定义了
这个变量，不带变量前缀直接调用脚本，使用的仍是环境中的那个值。

### 无效配置

text 或 json 以外的值，预期会在标准错误上输出以下诊断信息，
以状态码2退出，并且不打印报告：

```text
REPORT_OUTPUT must be text or json
```

成功分支返回状态码0。

### 迁移旧配置

把脚本和本地命令示例中的 REPORT_FORMAT 替换为 REPORT_OUTPUT。
此版本不读取 REPORT_FORMAT。只设置旧变量，会使 REPORT_OUTPUT
继续处于不存在的状态，因而选择文本；但如果环境的其他位置已经
设置了 REPORT_OUTPUT，则使用已经设置的值。

注意这里对环境作出的限定。如果开发者已经导出了其他值，“不填变量就输出文本”的说法并不完整。文档应描述代码实际检查的条件：该变量在进程环境中不存在。

区分源码审阅与实际执行

本文完成的是源码示例、映射表和替换文档。如果采用这个示例，以下运行检查仍待执行：

把这套方法用于真实仓库时，对实际执行的每一项检查，记录准确版本、环境、命令和观察结果。如果命令无法运行，就保留这个限制，不要把另一环境中的成功结果复制到 README 里。

GitHub 的仓库指令指南要求构建和验证说明以仓库实际情况为依据，包括命令前置条件和验证。这里的完整示例，是对这一原则的编辑应用，并不是 GitHub 规定的 README 格式。

给下一位 Agent 一份范围明确的文档请求

请求中写明读者要完成的操作，以及应当依据的证据：

英文锁定原文：

Update the reporting instructions to match this code change.

Read the current tools/summary.py and the affected README section first.
Map configuration names, accepted values, defaults, errors, and migration
behavior to the source before editing. Use the current implementation
as evidence; do not expand the previous agent's summary into new features.

Replace contradictory examples and prose together. Keep the explanation
focused on choosing a format and recovering from invalid configuration.

Report which commands you actually ran, with the environment and result.
Mark unexecuted checks as pending. Return the documentation diff and any
code/documentation conflict that needs a separate implementation decision.

完整中文对照：

更新报告操作说明，使其与这次代码变更一致。

先阅读当前 tools/summary.py 和受影响的 README 小节。
编辑前，把配置名称、允许值、默认值、错误和迁移行为
对应到源码。以当前实现为依据，不要把前一个 Agent 的概述
扩写成代码里没有的新功能。

同时替换相互矛盾的示例与说明文字。说明聚焦于怎样选择格式，
以及怎样从无效配置中恢复。

报告实际运行过哪些命令，附环境和结果。
未执行的检查标为待办。返回文档差异，以及任何需要单独作出
实施决定的代码与文档冲突。

如果代码与预期行为不一致，先指出冲突，再决定怎样写 README。下一位开发者需要与现有实现相符的说明，也需要清楚知道还有哪些事项必须作决定或实际运行后才能确认。