仅用 970 行 Python 代码构建高效编程智能体：nano-harness 深度解析与基准测试

在当前大语言模型 (LLM) 开发的领域中，复杂化似乎成了一种趋势。开发者们倾向于使用庞大的框架、复杂的编排图、记忆系统和繁琐的 UI 面板。然而，“nano-harness” 项目证明了：效率往往源于简洁。通过编写约 970 行非空 Python 代码，我们构建了一个在 Terminal-Bench 2.0 测试中达到 59.6% 成功率的编程智能体，这一表现足以媲美许多规模庞大的商业系统。

本文将深入解析 nano-harness 的架构逻辑、代码行得分比 (Score-per-Line-of-Code) 理念，以及如何利用 n1n.ai 提供的稳定、高速 API 来驱动你自己的智能体系统。

核心理念：代码行得分比 (Score-per-Line-of-Code)

nano-harness 的核心命题是：在保持代码极简、可读的前提下，在真实基准测试中跑出有意义的分数。受 Andrej Karpathy 的 nanoGPT 启发，该项目的设计初衷是让开发者能够在一顿饭的时间内读完所有核心源码。

在构建智能体时，“Harness”（外壳/环境）是开发者真正可以进行工程化设计的部分。模型负责提供“智能”，而 Harness 负责提供环境、约束和可靠性。对于使用 n1n.ai 的开发者来说，轻量级的 Harness 意味着更快的迭代速度，以及在不同模型（如 Claude 3.5 Sonnet 或 GPT-4o）之间切换时更低的延迟。

架构设计：5 个文件，3 个工具

nano-harness 仅由 5 个核心文件组成：agent.py（智能体逻辑）、tools.py（工具定义）、providers.py（供应商接口）、prompts.py（提示词工程）和 cli.py（命令行入口）。它仅依赖三个基础工具：

1. Bash: 持久化 Shell。当前的路径 (CWD)、环境变量和进程状态在多次调用之间保持一致。
2. Read File: 支持行号读取和切片，有效管理上下文窗口 (Context Window)。
3. Edit File: 基于精确唯一字符串匹配的替换工具，确保代码修改的精准度。

通过持久化的 Bash 终端，Harness 无需专门编写 ls、grep 或 install 等工具。模型只需执行标准的 Shell 命令即可，这极大地增强了系统的灵活性。

关键实现：可靠性循环与验证门控

一个编程智能体的优劣取决于它是否能“保持在线”且“保持诚实”。在 nano-harness 中，“保持在线”意味着能够处理瞬时 API 故障并优雅地处理上下文溢出。

以下是工具执行逻辑的简化示例：

def execute_tool(tool_call, shell_state):
    try:
        if tool_call['name'] == "bash":
            # 在持久化子进程中执行
            result = shell_state.run(tool_call['arguments']['command'])
            return {"status": "success", "output": result.stdout, "exit_code": result.returncode}
        # ... 其他工具处理
    except Exception as e:
        return {"status": "error", "message": str(e)}

“保持诚实”则通过 验证门控 (Verify Gate) 实现。当模型发出“任务完成”信号时，Harness 会发起挑战：“请重新阅读任务要求，运行相关检查，并证明你确实完成了。” 只有在挑战发起后出现了工具执行凭证（如通过了单元测试），系统才会接受完成信号。这有效防止了模型在任务未完成时产生“幻觉成功”。

Terminal-Bench 2.0 基准测试数据

我们在 Harbor 框架下对 89 个任务进行了测试，每个任务都在独立的 Docker 容器中运行。

为了稳定地运行此类高强度测试，可靠的 API 访问至关重要。n1n.ai 提供的聚合 API 能够承受长达 16 小时的连续基准测试压力，确保任务不会因连接中断而前功尽弃。

对抗性审查的启示：从 4/10 到 6/10

在开发过程中，最重要的一步是引入了独立前沿模型的“对抗性代码审查”。最初，审查模型仅给出了 4/10 的评分，并指出一个致命缺陷：Bash 工具仅捕获了输出流，却忽略了退出状态码 (Exit Status)。这意味着即使测试失败，只要输出看起来没报错，验证门控就会被误导。

审查后的关键修复：

• 状态码映射：非零的 Shell 退出码现在会触发工具错误。
• 权限保留：edit_file 工具修复了在 Linux 容器中编辑文件时导致可执行权限丢失的问题。
• 上下文截断修复：解决了在序列化过程中工具参数意外恢复原始大小的 Bug。

给开发者的专业建议 (Pro Tips)

1. 错误即信息：确保你的 Harness 能将错误清晰地反馈给模型。如果命令执行失败，模型需要看到具体的错误码，而不仅仅是空的输出。
2. 有状态 vs 无状态：虽然无状态工具更易实现，但有状态工具（如持久化 Shell）能让模型更自然地执行复杂的多步操作。
3. 成本控制：基准测试非常昂贵。一次全量 89 任务的运行可能消耗超过 300 万个 Token。使用 n1n.ai 这样的聚合平台，可以让你轻松对比不同供应商的价格，找到测试阶段性价比最高的路径。
4. MDX 语法安全：在编写文档或智能体提示词时，务必转义特殊字符。例如，小于号使用 <，花括号使用 \{变量\} 进行包裹，以避免解析错误。

为什么极简 Harness 至关重要？

大型框架往往将“魔力”隐藏在多层抽象之下。通过从零构建，你可以精准掌握上下文窗口的管理方式、工具的分发逻辑以及系统瓶颈所在。nano-harness 证明了你不需要 10,000 行代码也能构建出解决真实工程问题的智能系统。

Harness 的职责不是“变聪明”——聪明是模型的事。Harness 的职责是保持运行，并拒绝让任何人撒谎，包括模型，也包括开发者自己。

准备好构建你自己的智能体了吗？从坚实的架构和高性能的 API 开始。

在 n1n.ai 获取免费 API 密钥。