1
月
在社区成长 1 月
LEVEL 1
1 XP
AI 编程 IDE 真正提高效率的地方，不只是少敲几行代码，而是缩短“理解问题—建立验证—修改实现—确认影响”的循环。反过来，如果把模糊需求直接交给 Agent，并允许它自由修改文件和执行命令，原本十分钟的修复也可能变成一次难以审查的重构。
这篇文章用一个可在本地复现的 Python 小项目，演示怎样在支持 AI 对话、代码补全或 Agent 的 IDE 中完成一次受控修复。流程适用于 VS Code 搭配编程助手，以及其他具有类似能力的 AI 编辑器；具体按钮、上下文引用方式和命令审批设置，以实际产品版本为准。
一、背景：一个看起来没问题的配置解析函数
假设某个开发工具需要读取请求超时时间。配置可能来自 JSON，也可能来自环境变量，因此输入既可能是整数，也可能是字符串。
旧实现非常简短：
def parse_timeout(value):
if not value:
return 30
return int(value)
这段代码能处理部分正常输入，但它悄悄混淆了多个概念：缺省值、零、布尔值、浮点数，以及非法字符串。比如 0 会被当成“没有配置”，1.9 会被截断成 1，True 会变成 1。
如果只向助手说“优化这个函数”，它可能补类型提示、增加异常捕获，甚至把非法输入全部改成默认值。代码看起来更完整了，业务规则却未必正确。
我们先把需求写清楚：
1. None 表示未配置，返回默认值 30。
2. 接受整数，或者去除首尾空白后的 ASCII 十进制数字字符串。
3. 有效范围为 1～300，包含两端。
4. 字符串允许前导零，例如 '030'。
5. 布尔值、浮点数、空字符串、正负号、全角数字和其他类型都不接受。
6. 非法输入统一抛出 ValueError，不静默降级。
这些规则只是本次示例的明确约定，并不是所有项目都应照搬。关键是先决定契约，再讨论实现。
二、原理：把 AI 的建议放进可验证的闭环
一次可靠修复，需要三类约束共同工作。
第一类是上下文约束。助手需要知道目标函数、调用位置、现有测试与项目规范，但不需要读取整台电脑，更不需要接触生产配置。
第二类是行为约束。用输入与预期结果描述功能，比“更健壮”“更优雅”更容易验证。测试负责把这些描述固定下来。
第三类是改动约束。先限定可修改文件和禁止操作，再审查实际 diff。小补丁更容易发现错误归因、无关重构和测试被弱化等问题。
注意，测试通过只代表通过了当前测试集合，不代表代码天然正确。测试本身也需要人工核对，尤其不能让助手同时随意修改实现与预期结果。
三、前置条件与本地环境
准备 Python 3.10 或更新版本、Git，以及一个支持 AI 辅助的 IDE。示例不需要接口密钥、生产数据或外部业务服务。
在新目录中执行：
mkdir ai-ide-timeout-lab
cd ai-ide-timeout-lab
git init
python -m venv .venv
激活虚拟环境。macOS/Linux 使用：
source .venv/bin/activate
Windows PowerShell 使用：
.\.venv\Scripts\Activate.ps1
如果本机策略不允许运行激活脚本，不必为了练习修改系统策略，可以直接使用 .venv\Scripts\python.exe 替代后续命令中的 python。
安装测试依赖：
python -m pip install pytest
目录结构保持简单：
ai-ide-timeout-lab/
timeout_config.py
tests/
test_timeout_config.py
.gitignore
在 .gitignore 中加入：
.venv/
__pycache__/
.pytest_cache/
注意：.gitignore 只是 Git 的忽略规则，不等于 AI 工具的上下文排除规则。需要另行检查所用助手的文件访问、索引和数据处理设置。
四、分步骤实践
步骤 1：建立可回退的基线
把前面的旧实现写入 timeout_config.py，然后提交：
git add .
git commit -m "chore: add timeout parsing baseline"
git switch -c fix/timeout-validation
如果 Git 提示没有配置提交身份，按团队要求配置后再继续，不要让助手擅自修改全局 Git 配置。
步骤 2：让助手先分析，不立即写代码
在 IDE 中只提供目标文件和需求，发送类似指令：
“阅读 timeout_config.py，暂时不要修改文件。根据以下输入契约，列出旧实现违反的规则，并给出测试矩阵。区分已经从代码确认的问题和仍需确认的假设。不要安装依赖，不要访问网络，不要执行终端命令。”
随后附上前文六条需求。
在真实工程中，还应补充搜索调用点，确认调用方是否依赖旧行为。例如，某个入口可能把空字符串当成默认值。修改公共函数之前，必须确认这属于待修复缺陷，还是会破坏兼容性的行为变更。
步骤 3：先建立失败测试
在 tests/test_timeout_config.py 中写入：
import pytest
from timeout_config import parse_timeout
@pytest.mark.parametrize(('value', 'expected'), [
(None, 30),
(1, 1),
(300, 300),
('30', 30),
(' 30 ', 30),
('030', 30),
])
def test_accepts_valid_timeout(value, expected):
assert parse_timeout(value) == expected
@pytest.mark.parametrize('value', [
True, False, 0, -1, 301, 1.9,
'', ' ', '0', '301', '-1', '+1',
'1.0', '３０', [], {},
])
def test_rejects_invalid_timeout(value):
with pytest.raises(ValueError):
parse_timeout(value)
执行：
python -m pytest -q
此时应出现测试失败。重点不是失败数量，而是确认失败原因确实来自旧函数的行为，而不是导入错误或测试语法错误。
可以让助手解释失败日志，但要求它按“输入—实际行为—期望行为”对应分析。不要只接受一句“测试失败是因为校验不足”。
步骤 4：约束助手生成最小补丁
给助手明确指令：
“只修改 timeout_config.py，实现已确认的输入契约。不要修改测试，不要增加依赖，不要重构其他文件。先说明修改方案，再生成补丁。非法输入统一抛出 ValueError。”
一个符合本次约定的实现如下：
import re
def parse_timeout(value: object) -> int:
if value is None:
return 30
if isinstance(value, bool):
raise ValueError('timeout must not be boolean')
if isinstance(value, int):
timeout = value
elif isinstance(value, str):
text = value.strip()
if re.fullmatch(r'[0-9]+', text) is None:
raise ValueError('timeout must contain ASCII digits')
timeout = int(text)
else:
raise ValueError('unsupported timeout type')
if not 1 <= timeout <= 300:
raise ValueError('timeout must be between 1 and 300')
return timeout
这里有两个值得审查的细节：
其一，Python 中 bool 是 int 的子类，所以必须先排除布尔值，再判断整数。调换顺序会让 True 和 False 进入整数分支。
其二，本例明确只接受 ASCII 数字，因此使用 [0-9]，而不是直接使用 str.isdigit()。后者能够识别某些非 ASCII 数字字符，不符合这里的输入契约。
本例没有对异常消息做精确断言，因为需求只规定异常类型。如果调用方依赖特定错误码或错误消息，需要把它们单独纳入接口契约和测试。
步骤 5：验证补丁，而不是相信完成声明
重新运行：
python -m pytest -q
git diff --check
git diff --stat
git diff
git status --short
每条命令回答不同的问题：
• pytest：功能测试是否通过。
• git diff --check：是否存在补丁中的空白错误。
• git diff --stat：改动规模是否超出预期。
• git diff：实现和测试究竟改了什么。
• git status --short：是否出现新文件或其他未预期改动。默认 git diff 不会展示未跟踪文件的内容，发现后需要单独检查。
审查时尤其关注：助手是否删除了失败用例，是否把精确行为改成宽泛容错，是否引入了不需要的依赖，以及是否顺手格式化了无关文件。
步骤 6：补充调用链验证并提交
本地单元测试通过后，真实工程还应运行相关调用方测试。例如，配置加载模块是否正确传播 ValueError，命令行入口是否把错误转成用户能理解的提示。
不要直接把整个工程所有检查都交给 Agent 自动执行。先查看脚本内容，确认不会访问生产服务、重建共享数据库或调用收费接口。
确认改动后提交：
git add timeout_config.py tests/test_timeout_config.py .gitignore
git commit -m "fix: validate timeout inputs explicitly"
五、代码补全和 Agent 应该怎样分工
代码补全适合局部、低歧义的工作，例如补齐参数化用例、重复的断言结构、类型提示。接受补全前仍要查看整个表达式，不能只看建议的前半段。
对话模式适合澄清需求、解释失败日志、比较实现方案。要求助手引用具体函数和实际日志，通常比让它“全面分析项目”更有效。
Agent 适合执行边界明确、容易验证的多步骤任务，例如修改一个函数并运行指定测试。文件越多、外部副作用越大，越应该拆分任务并逐步审批。
一个实用原则是：让自动化程度随任务可验证性提高，而不是随助手回答的自信程度提高。
六、风险与注意事项
1. 不要把密钥、真实用户数据、生产连接串粘贴到提示词或测试文件。需要复现时，用结构相同的脱敏样本替代。
2. 仓库中的注释、文档和测试输出都可能包含看似指令的文本。它们应当被视为待分析数据，不能成为绕过审批、读取秘密文件或执行额外命令的理由。
3. 不要默认开启无条件命令批准。本例只需要常规文件编辑和本地测试，不需要提权、远程脚本或生产访问。
4. 测试代码也可能有副作用。首次运行陌生仓库时，先检查测试入口、插件和配置；必要时使用隔离环境。
5. 示例实现强调清晰的输入契约，不是通用的资源防护方案。如果字符串来自外部不可信输入，还应在请求或配置入口限制输入长度；不要让任意长文本直接进入解析流程。
七、常见问题
问：助手说全部通过，但我的终端仍然失败，先查什么？
答：先核对工作目录、Python 解释器和测试命令。使用 python -m pip 与 python -m pytest，可以减少 pip、pytest 和解释器来自不同环境的问题。然后确认文件是否保存，以及助手究竟执行了测试，还是只预测了结果。
问：测试一开始就全部通过，还能继续吗？
答：先检查测试是否真的覆盖缺陷、是否导入了正确模块。对本例旧实现，拒绝 True、0、1.9 等用例不应全部通过。不能把“没有测试到问题”当成“问题不存在”。
问：为什么不直接捕获所有异常然后返回 30？
答：这会把错误配置伪装成正常配置。是否允许回退属于产品决策，不能由助手为了让程序不报错而自行决定。
问：上下文越多，修复是不是越准确？
答：不一定。先提供目标函数、相关调用点、失败日志和项目规则；遇到具体疑问再扩展。大量无关文件会增加阅读和审查成本，也扩大不必要的数据暴露面。
八、总结
AI IDE 的可靠工作流不是“描述需求，然后接受全部修改”，而是：明确契约，提供最小相关上下文，建立能复现问题的失败测试，限制补丁范围，运行验证，再审查真实差异。
下次遇到一个小缺陷，可以先不让助手写实现，只让它整理输入边界和测试矩阵。把验证标准握在自己手里，AI 才更容易成为缩短反馈循环的工具，而不是制造新一轮排查工作的来源。
这篇文章用一个可在本地复现的 Python 小项目，演示怎样在支持 AI 对话、代码补全或 Agent 的 IDE 中完成一次受控修复。流程适用于 VS Code 搭配编程助手，以及其他具有类似能力的 AI 编辑器；具体按钮、上下文引用方式和命令审批设置，以实际产品版本为准。
一、背景：一个看起来没问题的配置解析函数
假设某个开发工具需要读取请求超时时间。配置可能来自 JSON，也可能来自环境变量，因此输入既可能是整数，也可能是字符串。
旧实现非常简短：
def parse_timeout(value):
if not value:
return 30
return int(value)
这段代码能处理部分正常输入，但它悄悄混淆了多个概念：缺省值、零、布尔值、浮点数，以及非法字符串。比如 0 会被当成“没有配置”，1.9 会被截断成 1，True 会变成 1。
如果只向助手说“优化这个函数”，它可能补类型提示、增加异常捕获，甚至把非法输入全部改成默认值。代码看起来更完整了，业务规则却未必正确。
我们先把需求写清楚：
1. None 表示未配置，返回默认值 30。
2. 接受整数，或者去除首尾空白后的 ASCII 十进制数字字符串。
3. 有效范围为 1～300，包含两端。
4. 字符串允许前导零，例如 '030'。
5. 布尔值、浮点数、空字符串、正负号、全角数字和其他类型都不接受。
6. 非法输入统一抛出 ValueError，不静默降级。
这些规则只是本次示例的明确约定，并不是所有项目都应照搬。关键是先决定契约，再讨论实现。
二、原理：把 AI 的建议放进可验证的闭环
一次可靠修复，需要三类约束共同工作。
第一类是上下文约束。助手需要知道目标函数、调用位置、现有测试与项目规范，但不需要读取整台电脑，更不需要接触生产配置。
第二类是行为约束。用输入与预期结果描述功能，比“更健壮”“更优雅”更容易验证。测试负责把这些描述固定下来。
第三类是改动约束。先限定可修改文件和禁止操作，再审查实际 diff。小补丁更容易发现错误归因、无关重构和测试被弱化等问题。
注意，测试通过只代表通过了当前测试集合，不代表代码天然正确。测试本身也需要人工核对，尤其不能让助手同时随意修改实现与预期结果。
三、前置条件与本地环境
准备 Python 3.10 或更新版本、Git，以及一个支持 AI 辅助的 IDE。示例不需要接口密钥、生产数据或外部业务服务。
在新目录中执行：
mkdir ai-ide-timeout-lab
cd ai-ide-timeout-lab
git init
python -m venv .venv
激活虚拟环境。macOS/Linux 使用：
source .venv/bin/activate
Windows PowerShell 使用：
.\.venv\Scripts\Activate.ps1
如果本机策略不允许运行激活脚本，不必为了练习修改系统策略，可以直接使用 .venv\Scripts\python.exe 替代后续命令中的 python。
安装测试依赖：
python -m pip install pytest
目录结构保持简单：
ai-ide-timeout-lab/
timeout_config.py
tests/
test_timeout_config.py
.gitignore
在 .gitignore 中加入：
.venv/
__pycache__/
.pytest_cache/
注意：.gitignore 只是 Git 的忽略规则，不等于 AI 工具的上下文排除规则。需要另行检查所用助手的文件访问、索引和数据处理设置。
四、分步骤实践
步骤 1：建立可回退的基线
把前面的旧实现写入 timeout_config.py，然后提交：
git add .
git commit -m "chore: add timeout parsing baseline"
git switch -c fix/timeout-validation
如果 Git 提示没有配置提交身份，按团队要求配置后再继续，不要让助手擅自修改全局 Git 配置。
步骤 2：让助手先分析，不立即写代码
在 IDE 中只提供目标文件和需求，发送类似指令：
“阅读 timeout_config.py，暂时不要修改文件。根据以下输入契约，列出旧实现违反的规则，并给出测试矩阵。区分已经从代码确认的问题和仍需确认的假设。不要安装依赖，不要访问网络，不要执行终端命令。”
随后附上前文六条需求。
在真实工程中，还应补充搜索调用点，确认调用方是否依赖旧行为。例如，某个入口可能把空字符串当成默认值。修改公共函数之前，必须确认这属于待修复缺陷，还是会破坏兼容性的行为变更。
步骤 3：先建立失败测试
在 tests/test_timeout_config.py 中写入：
import pytest
from timeout_config import parse_timeout
@pytest.mark.parametrize(('value', 'expected'), [
(None, 30),
(1, 1),
(300, 300),
('30', 30),
(' 30 ', 30),
('030', 30),
])
def test_accepts_valid_timeout(value, expected):
assert parse_timeout(value) == expected
@pytest.mark.parametrize('value', [
True, False, 0, -1, 301, 1.9,
'', ' ', '0', '301', '-1', '+1',
'1.0', '３０', [], {},
])
def test_rejects_invalid_timeout(value):
with pytest.raises(ValueError):
parse_timeout(value)
执行：
python -m pytest -q
此时应出现测试失败。重点不是失败数量，而是确认失败原因确实来自旧函数的行为，而不是导入错误或测试语法错误。
可以让助手解释失败日志，但要求它按“输入—实际行为—期望行为”对应分析。不要只接受一句“测试失败是因为校验不足”。
步骤 4：约束助手生成最小补丁
给助手明确指令：
“只修改 timeout_config.py，实现已确认的输入契约。不要修改测试，不要增加依赖，不要重构其他文件。先说明修改方案，再生成补丁。非法输入统一抛出 ValueError。”
一个符合本次约定的实现如下：
import re
def parse_timeout(value: object) -> int:
if value is None:
return 30
if isinstance(value, bool):
raise ValueError('timeout must not be boolean')
if isinstance(value, int):
timeout = value
elif isinstance(value, str):
text = value.strip()
if re.fullmatch(r'[0-9]+', text) is None:
raise ValueError('timeout must contain ASCII digits')
timeout = int(text)
else:
raise ValueError('unsupported timeout type')
if not 1 <= timeout <= 300:
raise ValueError('timeout must be between 1 and 300')
return timeout
这里有两个值得审查的细节：
其一，Python 中 bool 是 int 的子类，所以必须先排除布尔值，再判断整数。调换顺序会让 True 和 False 进入整数分支。
其二，本例明确只接受 ASCII 数字，因此使用 [0-9]，而不是直接使用 str.isdigit()。后者能够识别某些非 ASCII 数字字符，不符合这里的输入契约。
本例没有对异常消息做精确断言，因为需求只规定异常类型。如果调用方依赖特定错误码或错误消息，需要把它们单独纳入接口契约和测试。
步骤 5：验证补丁，而不是相信完成声明
重新运行：
python -m pytest -q
git diff --check
git diff --stat
git diff
git status --short
每条命令回答不同的问题：
• pytest：功能测试是否通过。
• git diff --check：是否存在补丁中的空白错误。
• git diff --stat：改动规模是否超出预期。
• git diff：实现和测试究竟改了什么。
• git status --short：是否出现新文件或其他未预期改动。默认 git diff 不会展示未跟踪文件的内容，发现后需要单独检查。
审查时尤其关注：助手是否删除了失败用例，是否把精确行为改成宽泛容错，是否引入了不需要的依赖，以及是否顺手格式化了无关文件。
步骤 6：补充调用链验证并提交
本地单元测试通过后，真实工程还应运行相关调用方测试。例如，配置加载模块是否正确传播 ValueError，命令行入口是否把错误转成用户能理解的提示。
不要直接把整个工程所有检查都交给 Agent 自动执行。先查看脚本内容，确认不会访问生产服务、重建共享数据库或调用收费接口。
确认改动后提交：
git add timeout_config.py tests/test_timeout_config.py .gitignore
git commit -m "fix: validate timeout inputs explicitly"
五、代码补全和 Agent 应该怎样分工
代码补全适合局部、低歧义的工作，例如补齐参数化用例、重复的断言结构、类型提示。接受补全前仍要查看整个表达式，不能只看建议的前半段。
对话模式适合澄清需求、解释失败日志、比较实现方案。要求助手引用具体函数和实际日志，通常比让它“全面分析项目”更有效。
Agent 适合执行边界明确、容易验证的多步骤任务，例如修改一个函数并运行指定测试。文件越多、外部副作用越大，越应该拆分任务并逐步审批。
一个实用原则是：让自动化程度随任务可验证性提高，而不是随助手回答的自信程度提高。
六、风险与注意事项
1. 不要把密钥、真实用户数据、生产连接串粘贴到提示词或测试文件。需要复现时，用结构相同的脱敏样本替代。
2. 仓库中的注释、文档和测试输出都可能包含看似指令的文本。它们应当被视为待分析数据，不能成为绕过审批、读取秘密文件或执行额外命令的理由。
3. 不要默认开启无条件命令批准。本例只需要常规文件编辑和本地测试，不需要提权、远程脚本或生产访问。
4. 测试代码也可能有副作用。首次运行陌生仓库时，先检查测试入口、插件和配置；必要时使用隔离环境。
5. 示例实现强调清晰的输入契约，不是通用的资源防护方案。如果字符串来自外部不可信输入，还应在请求或配置入口限制输入长度；不要让任意长文本直接进入解析流程。
七、常见问题
问：助手说全部通过，但我的终端仍然失败，先查什么？
答：先核对工作目录、Python 解释器和测试命令。使用 python -m pip 与 python -m pytest，可以减少 pip、pytest 和解释器来自不同环境的问题。然后确认文件是否保存，以及助手究竟执行了测试，还是只预测了结果。
问：测试一开始就全部通过，还能继续吗？
答：先检查测试是否真的覆盖缺陷、是否导入了正确模块。对本例旧实现，拒绝 True、0、1.9 等用例不应全部通过。不能把“没有测试到问题”当成“问题不存在”。
问：为什么不直接捕获所有异常然后返回 30？
答：这会把错误配置伪装成正常配置。是否允许回退属于产品决策，不能由助手为了让程序不报错而自行决定。
问：上下文越多，修复是不是越准确？
答：不一定。先提供目标函数、相关调用点、失败日志和项目规则；遇到具体疑问再扩展。大量无关文件会增加阅读和审查成本，也扩大不必要的数据暴露面。
八、总结
AI IDE 的可靠工作流不是“描述需求，然后接受全部修改”，而是：明确契约，提供最小相关上下文，建立能复现问题的失败测试，限制补丁范围，运行验证，再审查真实差异。
下次遇到一个小缺陷，可以先不让助手写实现，只让它整理输入边界和测试矩阵。把验证标准握在自己手里，AI 才更容易成为缩短反馈循环的工具，而不是制造新一轮排查工作的来源。