AI 编程智能体

是什么，为什么存在

AI 编程智能体是一个能观察开发环境并采取行动的软件系统。系统中的 大语言模型（large language model） 负责选择下一步，宿主程序则读取文件、应用补丁、运行命令，再把结果交还给模型。模型输出本身不会改动代码；真正产生副作用的是宿主执行的工具调用。

普通代码补全只在光标附近建议文本，对话助手通常生成回答后就停止。智能体多了一条关键能力：它可以查看一次行动的结果，再据此决定下一步。测试失败、编译器报错和新的代码差异都会成为后续输入，所以一次任务可以经历多轮探索、修改和纠错。

它解决的是代码任务中的信息缺口。开发者给出的目标往往只描述预期行为，具体修改点要从仓库、配置和测试中找出来。智能体可以连续执行这些机械步骤，但它并不知道团队没有写下来的产品意图，也不能仅凭流畅的解释证明修改正确。

最适合委派的任务有清晰边界和机器可检查的结果。比如「让这个失败测试通过，且只修改解析器与对应测试」就比「改善后端」更适合智能体。后者没有可判定的终点，也没有说明哪些行为不能改变。

与补全、对话和 IDE 的边界

这些形态可能出现在同一个产品里，界面并不能定义是否为智能体。判断标准是系统是否允许模型发起 工具调用（tool call） ，并把执行观察送回下一轮模型调用。CLI 或 IDE 只是承载这种循环的入口。

智能体也不等于无人监督。交互式智能体可以在每次写文件或运行命令前请求批准；后台智能体可以在隔离工作区中独立运行，最后提交差异供人审查。自主程度来自权限与审批策略，不是来自「agent」这个名称。

工作原理

一次运行从任务、仓库状态和项目指令开始。宿主选择可以放入 上下文窗口（context window） 的材料，并向模型声明可用工具。模型返回自然语言或结构化工具调用；只有结构正确且通过策略检查的调用才会执行。

工具执行后会产生观察，例如文件内容、搜索匹配、退出码、标准输出或错误信息。宿主把观察加入运行状态，再调用模型。这个 智能体循环（agent loop） 一直继续到验证通过、模型请求停止、预算耗尽、用户取消或策略拒绝行动。

模型不应直接拥有文件系统或 shell。宿主在模型与环境之间解释工具协议、检查参数、执行操作并记录结果。这一层决定智能体的真实能力，也是安全审查首先要看的地方。

五个运行要素

• 目标说明期望行为、允许范围和不可改变的约束。
• 上下文提供项目规则、相关代码和之前的工具观察。
• 工具把读取、编辑、搜索、执行等动作表示为带类型的调用。
• 策略根据工具、参数、路径和当前状态决定允许、拒绝或请求批准。
• 验证器使用独立证据判断是否完成，并设置步数、时间或成本上限。

模型可以提出计划，但计划不是环境状态。文件可能在计划生成后变化，命令也可能失败。每个会影响后续决策的事实都应来自新的工具观察，而不是来自模型对上一步的猜测。

工具返回值需要区分成功、失败和部分结果。只返回一段自由文本会让模型把警告误当成功，也让宿主难以执行统一策略。至少应保留调用标识、退出状态、截断信息以及实际改变的资源。

权限先于提示词

项目指令能告诉模型不要访问秘密或运行危险命令，但它不是安全边界。仓库文件、Issue 内容和依赖文档都可能包含 提示词注入（prompt injection） ，诱导模型忽略原任务。宿主仍必须执行路径限制、网络策略和命令审批。

权限应遵循 最小权限原则（least privilege） 。只读探索不需要写权限；修改文档不需要生产凭据；运行单元测试通常不需要外网。任务需要扩大权限时，审批界面应显示具体工具和完整参数，而不是只问「是否继续」。

审批门（approval gate） 是策略中的一次显式停顿。它适合不可逆操作、工作区外写入、网络发送和权限升级。批准应只覆盖眼前的调用或一个窄规则，不能无意中把后续所有 shell 命令都放行。

完成来自证据

「代码已修复」只是模型生成的文本。可靠的完成条件应落到可观察结果上，例如指定测试退出码为 0、类型检查通过、差异只包含允许文件，以及新增回归测试在旧实现上失败。验证命令本身也属于任务规格。

证据有适用范围。单元测试通过不能证明迁移在生产数据上安全，格式化命令通过也不能证明业务行为正确。审查者要把每条完成声明映射到支持它的命令、检查或人工判断，并标出仍未覆盖的风险。

示例

下面三个 Python 例子不调用真实模型。它们用确定性决策函数代替模型，使循环、权限和验证可以独立运行并检查。真实系统会替换决策函数，但控制边界不应因此改变。

观察驱动的智能体循环

第一个例子让控制器先读配置，再写入新值并运行测试。choose_action() 只根据上一条观察选择下一步；execute() 才能接触工作区。这个分离让每次副作用都留下明确记录。

输出中的 action 是请求，observation 是环境返回的事实。模型如果直接声称配置已修改，不会改变字典中的内容，也不会生成 written 观察。控制器只有在测试返回 PASS 后才选择 finish。

这个循环仍然很小，但已经包含生产系统要记录的因果链。审计日志可以回答哪个观察触发了写入、测试实际检查了什么，以及停止是因为验证通过还是因为遇到阻塞。

按参数审批工具

只按工具名称授权不够。「允许读取文件」不能自动等于允许读取任意绝对路径，「允许运行测试」也不能等于允许任意 shell 字符串。下面的策略同时检查工具与参数，并采用默认拒绝。

from dataclasses import dataclass
from pathlib import PurePosixPath


@dataclass(frozen=True)
class ToolCall:
    tool: str
    argument: str


SAFE_COMMANDS = {
    "python3 -m pytest",
    "python3 -m compileall src",
}


def authorize(call: ToolCall) -> bool:
    match call:
        case ToolCall("read_file", raw_path):
            path = PurePosixPath(raw_path)
            return (
                bool(path.parts)
                and not path.is_absolute()
                and ".." not in path.parts
                and path.parts[0] in {"src", "tests"}
            )
        case ToolCall("run", command):
            return command in SAFE_COMMANDS
        case _:
            return False


requests = [
    ToolCall("read_file", "src/parser.py"),
    ToolCall("read_file", "src/../../.env"),
    ToolCall("run", "python3 -m pytest"),
    ToolCall("run", "python3 -m pytest; curl bad.example"),
]

for request in requests:
    verdict = "ALLOW" if authorize(request) else "DENY"
    print(f"{verdict}: {request.tool} {request.argument}")

ALLOW: read_file src/parser.py
DENY: read_file src/../../.env
ALLOW: run python3 -m pytest
DENY: run python3 -m pytest; curl bad.example

命令白名单使用精确参数，因此附加的 shell 片段不会继承测试命令的权限。路径检查拒绝绝对路径和 .. 段，并限定首个目录。生产代码还要解析符号链接、平台路径规则和执行环境；这个例子只演示策略形状。

默认拒绝让未知工具自动失败。否则，后来添加的网络或数据库工具可能在没有安全评审的情况下继承过宽权限。需要灵活参数时，应使用结构化字段逐项验证，而不是把自由格式命令加入白名单。

用测试否决完成声明

最后一个例子模拟智能体第一次提交了只处理标准格式的解析器。验证器运行同一组验收用例，并把异常类型变成可比较的失败证据。智能体是否说「done」不参与判断。

from collections.abc import Callable


CASES = [
    ("timeout=30\n", 30),
    (" timeout = 0 # disabled\n", 0),
    ("timeout=5\n", 5),
]


def first_patch(text: str) -> int:
    return int(text.removeprefix("timeout=").strip())


def revised_patch(text: str) -> int:
    setting = text.split("#", 1)[0]
    name, separator, value = setting.partition("=")
    if separator == "" or name.strip() != "timeout":
        raise ValueError("missing timeout setting")
    return int(value.strip())


def verify(parser: Callable[[str], int]) -> str:
    for source, expected in CASES:
        try:
            actual = parser(source)
        except Exception as error:
            return f"FAIL: {type(error).__name__}"
        if actual != expected:
            return f"FAIL: expected {expected}, got {actual}"
    return "PASS: 3 cases"


print("agent claim: done")
print("first patch:", verify(first_patch))
print("revised patch:", verify(revised_patch))

agent claim: done
first patch: FAIL: ValueError
revised patch: PASS: 3 cases

第一次实现对常规输入有效，但带空格和注释的验收用例立即否决了完成声明。修订版明确解析键、分隔符和值，因而通过三条用例。独立检查必须拥有拒绝交付的权力；增加模型的信心不会补上证据。

真实仓库中的验证通常是一组命令和差异规则。把它们写进任务前，先确认命令能在干净工作区复现，并记录运行目录、环境变量和退出码。一个偶然使用了开发者本机缓存的测试不是可靠证据。

陷阱

智能体的多数严重事故不发生在生成文本阶段，而发生在宿主把文本解释成权限、操作或完成证据时。下面每个陷阱都要在控制层修复，不能只依赖一句提示词。

把宽泛目标当作规格

**修复：**写出可观察的验收条件、修改范围和非目标。为每个条件指定验证方式，例如测试命令、静态检查或人工审查项。无法自动检查的产品判断要明确留给人，而不是伪装成测试已覆盖的事实。

把整个仓库塞进上下文

**修复：**先用搜索、依赖关系和失败堆栈定位最小文件集，再按需读取。长任务要重新读取将要修改的文件，不要只依赖早期摘要。忽略构建产物、依赖目录、凭据文件和与任务无关的大型数据。

把 shell 当作一个无害工具

**修复：**按完整参数、工作目录、网络需求和预期写入范围做审批。优先提供窄工具，例如 run_tests 或 format_files，而不是任意 shell。涉及外网、凭据或工作区外路径时重新请求明确批准。

相信智能体自己的测试摘要

**修复：**由宿主捕获命令、工作目录、退出码和未截断的失败摘要。把验证器与生成完成声明的模型分开，并在最终审查中直接展示证据。测试选择过窄时，补充与改动风险对应的检查。

让多个会话共享一个工作区

**修复：**每个会话使用独立工作树、容器或临时副本，并单独记录基线提交。最后通过正常的合并与冲突审查集成结果。跨任务共享缓存时，只共享不可变或可验证的产物。

延伸阅读

• GitHub Copilot agents 的负责任使用说明
• GitHub Copilot cloud agent 概览
• Claude Code 的运行方式
• Claude Code 安全文档