剥离伪自主神话：剖析 learn-claude-code 的 Harness 驱动架构

1. 痛点突围：它究竟击穿了什么工程死穴？

大批企业级 Agent 开发陷入了对 Low-code 画布与 Prompt 管道编排的路径依赖。开发者耗费大量工时拉取包含数百个条件节点的 DAG 流程图，通过硬编码的 if-else 规则链条强行规训大语言模型。这类系统遇到边缘输入时，往往引发级联崩溃：节点逻辑互相锁死，上下文膨胀迅速吞没窗口上限，代码维护成本呈指数级攀升。这种把模型作为普通文本插值节点的做法，本质上是用确定性软件工程去套用概率计算系统。

shareAI-lab 发布的 learn-claude-code 仓库直接撕裂了这种伪 Agent 假象。该项目通过梳理从 DeepMind DQN、OpenAI Five 到当前代码大模型的进化轨迹，明确提出：Agent 的自主性（Agency）完全来自神经网络反向传播与强化学习训练，外围代码根本无法凭空构造出智能。外部系统的唯一使命是构建高内聚的运行线束（Harness），为内核模型提供稳定、原子化且具备容错能力的操作界面。

💡 架构核心洞见：自主性属于模型内生属性，工程团队的边界是构筑包含工具、环境观察、按需上下文与权限边界的最小线束系统（Harness = Tools + Knowledge + Observation + Action + Permissions）。

这一认知转向将开发者从无休止的规则补丁中彻底解放。工程设计的重心转移到如何构建原子化工具集合、控制环境观测的噪声比，以及建立高吞吐、零副作用的宿主交互层。

2. 核心架构与底层数据流向解析

learn-claude-code 剥离了复杂多 Agent 框架中的多余抽象，将其解构为一个围绕驱动器（Driver）与载具（Vehicle）交互的状态循环。整个系统生命周期严格遵循“环境观测 -> 模型决策 -> 工具执行 -> 状态反馈”的闭环拓扑。

+-------------------------------------------------------------------------+
|                        HOST ENVIRONMENT / RUNTIME                       |
|                                                                         |
|   [Terminal / Filesystem] <------------+                                |
|             |                          |                                |
|      (Raw OS State)                    |                                |
|             v                          |                                |
|   +-------------------+                |                                |
|   | Observation Filter| (Diffs/Trunc)  | (Command Execution)            |
|   +-------------------+                |                                |
|             |                          |                                |
|      (Clean Evidence)                  |                                |
|             v                          |                                |
|   +-----------------------------------------------------------------+   |
|   |                     HARNESS ENGINE CORE                         |   |
|   |                                                                 |   |
|   |  +--------------------+   +----------------------------------+  |   |
|   |  |  Context Manager   |   |        Tool Interface            |  |   |
|   |  | (Pruning & Rolling)|   | (Read / Write / Bash / Glob)     |  |   |
|   |  +--------------------+   +----------------------------------+  |   |
|   +-----------------------------------------------------------------+   |
|             |                                  ^                        |
|      (Curated Context)                  (Tool Call Intent)              |
|             v                                  |                        |
|   +-----------------------------------------------------------------+   |
|   |                    FOUNDATIONAL LLM (DRIVER)                    |   |
|   |         Trained Reasoning Loop (Inference / CoT)                |   |
|   +-----------------------------------------------------------------+   |
+-------------------------------------------------------------------------+

系统的内部数据流包含三个严密的工程控制点：

1. 观测过滤（Observation Filtering）：宿主终端和文件系统的原始输出严禁直接追加至主上下文。工具执行后产生的标准输出和标准错误必须经过截断、Diff 提取或错误堆栈精简，杜绝无意义日志污染模型推理缓存。
2. 按需知识注入（On-demand Knowledge）：工程领域文档、架构决策记录与 API 规范拒绝全量静态预加载，改为通过专门的代码定位工具（如 Glob、Grep）由模型按需动态索取。
3. 原子权限判定（Action Gating）：每个工具调用必须显式通过安全沙箱，区分只读感知（Read/Glob/Grep）与破坏性变更（Write/Bash），将不可逆执行拦截在沙箱安全边界之内。

这一架构放弃了脆弱的图编排节点，把状态控制权完全让渡给模型自身的思考链，代码逻辑专注于保障工具输入参数解析的严格性与执行异常的自愈恢复。

3. 技术选型与性能横向硬核对比

在代码级自主代理的架构选型中，系统依赖的厚重程度直接决定了响应时延与故障排查效率。以下是 learn-claude-code 与业界常见方案的对比：

该方案完全抛弃了繁琐的实体抽象，用干净的底层 API 降低了上下文污染。它不仅缩减了无效 Prompt 负载，更直接消除了框架包装器带来的黑盒异常风险。

4. 手把手极客实操：从零构建最小闭环

下面遵循极简 Harness 哲学，使用 TypeScript 和 Anthropic 原生 SDK 构建一个包含文件读取与命令执行的最小可用系统。

依赖准备

初始化并安装最小依赖包：

mkdir minimal-harness && cd minimal-harness
npm init -y
npm install @anthropic-ai/sdk
npm install -D typescript @types/node tsx

核心执行器实现

创建 agent_runner.ts，写入如下可直接运行的完整闭环代码：

import Anthropic from "@anthropic-ai/sdk";
import { execSync } from "node:child_process";
import * as fs from "node:fs";
import * as path from "node:path";

// 初始化 Anthropic 客户端实例
const client = new Anthropic();

// 定义具备原子能力的线束工具集
const tools: Anthropic.Tool[] = [
  {
    name: "read_file",
    description: "读取指定路径的文件内容并以 UTF-8 文本返回",
    input_schema: {
      type: "object",
      properties: {
        filepath: { type: "string", description: "目标文件的相对或绝对路径" },
      },
      required: ["filepath"],
    },
  },
  {
    name: "execute_command",
    description: "在受限沙箱中运行 Shell 命令并捕获 stdout/stderr 输出",
    input_schema: {
      type: "object",
      properties: {
        command: { type: "string", description: "待运行的 Shell 命令" },
      },
      required: ["command"],
    },
  },
];

// 工具的具体宿主分发与异常自愈
function executeHarnessTool(name: string, input: Record<string, unknown>): string {
  try {
    if (name === "read_file") {
      const targetPath = path.resolve(String(input.filepath));
      return fs.readFileSync(targetPath, "utf-8");
    }
    if (name === "execute_command") {
      // 设定单次命令执行上限为 10 秒，输出截断为 2000 字符防止爆炸
      const rawOutput = execSync(String(input.command), { timeout: 10000, encoding: "utf-8" });
      return rawOutput.length > 2000 ? rawOutput.slice(0, 2000) + "...[Truncated]" : rawOutput;
    }
    throw new Error(`未受支持的工具类型: ${name}`);
  } catch (err: unknown) {
    const error = err as Error;
    return `ToolExecutionError: ${error.message}`;
  }
}

// 核心线束驱动循环
async function runHarnessLoop(taskPrompt: string) {
  const messageHistory: Anthropic.MessageParam[] = [
    { role: "user", content: taskPrompt }
  ];

  while (true) {
    const response = await client.messages.create({
      model: "claude-3-5-sonnet-latest",
      max_tokens: 4096,
      tools: tools,
      messages: messageHistory,
    });

    // 记录模型的推理文本与工具调用请求
    messageHistory.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      console.log("\n[任务完成] 模型输出：\n", response.content.find(c => c.type === "text")?.text);
      break;
    }

    if (response.stop_reason === "tool_use") {
      const toolUseBlocks = response.content.filter(
        (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
      );

      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of toolUseBlocks) {
        console.log(`[工具调用] ${block.name}(${JSON.stringify(block.input)})`);
        const output = executeHarnessTool(block.name, block.input as Record<string, unknown>);
        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: output,
        });
      }

      // 回传执行观测数据，由模型评估下一步操作
      messageHistory.push({ role: "user", content: toolResults });
    }
  }
}

// 启动验证任务：检查本机 package.json 的依赖定义并打印信息
runHarnessLoop("读取当前目录下的 package.json 文件，查看并分析其核心依赖项。");

执行测试与预期输出

配置环境并执行文件：

export ANTHROPIC_API_KEY="your-api-key"
npx tsx agent_runner.ts

系统启动后终端应产出如下结构的确定性输出：

[工具调用] read_file({"filepath":"package.json"})

[任务完成] 模型输出：
 本项目的核心依赖为 `@anthropic-ai/sdk`，用于同大语言模型进行结构化交互。
开发依赖包含 `typescript`、`@types/node` 与 `tsx`，支持直接执行 TypeScript 运行时脚本。

5. 生产落地踩坑指南与避坑建议 (Gotchas)

在将此类 Harness 架构推向生产环境或处理巨型代码仓库时，盲目的工具暴露与无节制的上下文流转会迅速破坏稳定性。必须重点防范以下工程陷阱：

⚠️ 避坑预警 [终端输出无界膨胀与上下文污染]： 直接向模型返回 npm install、grep 或单元测试的全量日志，会瞬间吃光 Context 窗口，并严重稀释模型的注意力分配。在生产环境下，必须对所有 Shell 和读取工具部署截断中间件。如果标准输出超过 100 行，仅保留前 30 行和最后 70 行的堆栈信息，中间以包含行数统计的标识符压缩替代，强迫模型在必要时追加精细查询。

⚠️ 避坑预警 [文件写入操作的并发读写破坏]： 当赋予模型修改代码的权限时，通过整体重写长文件容易引发随机丢行、格式被格式化引擎破坏等隐性 Bug。不可直接提供全量 write_file 接口，应使用基于精确锚点的 str_replace 机制或 git patch 语法，并配置写入前校验机制。修改生效后必须自动触发无副作用的语法静态检查（如 tsc --noEmit），一旦抛出语法错误，直接把解析异常作为 Observation 塞入下一轮循环让模型立即自愈修复。

⚠️ 避坑预警 [无隔离环境下的命令执行越界]： 赋予 Harness 运行 Shell 权限等同于赋予潜在的系统接管风险。禁止直接使用原生运行环境执行未知操作。所有写权限命令必须通过轻量级 Docker 容器、Linux namespace 或限制特定只读根目录的沙箱进程，网络连接默认设置白名单隔离，防止出现模型将生产凭据误读或发送至不可信公网的恶性事故。