structure｜1️⃣ 三级笔记、思想框架

📝 三级笔记：Components of A Coding Agent

核心论点：Coding Agent 的能力不只来自模型本身，更来自包裹模型的「harness」系统——工具调用、上下文管理、记忆机制等外围工程，才是让 LLM 在实际编程场景中真正好用的关键。

一、为什么 Coding Agent ≠ 更好的模型

• 近年 LLM 系统的进步，很大程度上不是模型变好了，而是我们使用模型的方式变好了
• Claude Code、Codex 之所以比同一个模型的聊天界面感觉强得多，核心原因在于 surrounding system：tool use、context management、memory
• 关键洞察：当我们谈论 LLM 的编码能力时，人们常常把模型、推理行为和 agent 产品混为一谈。但它们是不同的东西。

二、LLM → Reasoning Model → Agent：三层架构

• LLM：核心的 next-token 模型，是「引擎」
• Reasoning Model：仍然是 LLM，但经过训练/提示来花更多推理时间做中间推理、验证、搜索候选答案——是「加强版引擎」
• Agent：模型之上的一层控制循环（control loop），给定目标后决定下一步检查什么、调用哪些工具、如何更新状态、何时停止
• Agent Harness：agent 周围的软件脚手架，管理 context、tool use、prompts、state 和 control flow
• Coding Harness：agent harness 的特例，专为软件工程任务设计，管理代码上下文、工具、执行和迭代反馈
• 类比：LLM 是引擎，reasoning model 是加强版引擎，agent harness 帮助我们更好地使用这个引擎

三、为什么 Harness 如此重要

• 编码工作只有一部分是 next-token generation
• 大量工作是：repo navigation、search、function lookup、diff application、test execution、error inspection，以及把所有相关信息保持在 context 中
• 作者推测：如果把最新开源模型（如 GLM-5）放进类似的 harness，其表现可能与 GPT-5.4 in Codex 或 Claude Opus 4.6 in Claude Code 相当
• 各家 vanilla LLM 能力已经非常接近，harness 往往是让一个 LLM 比另一个表现更好的决定性因素

四、Coding Harness 的六大核心组件

组件 1：Live Repo Context（实时仓库上下文）

• 最显而易见但也最重要的组件
• 当用户说「fix the tests」，模型需要知道：是否在 Git repo 内、当前分支、项目文档（AGENTS.md / README）中的指令等
• 这些信息会改变什么是「正确行动」——「Fix the tests」不是一条自足的指令
• 核心做法：agent 在开始工作前，先收集一份 workspace summary（"stable facts"），让模型不是从零开始

组件 2：Prompt Shape And Cache Reuse（提示结构与缓存复用）

• 编码会话是重复性的：agent 规则不变、工具描述不变、workspace summary 大致不变
• 聪明的 runtime 不会每轮都从头重建整个 prompt
• 将 prompt 分为两层：
  • Stable prompt prefix（稳定前缀）：通用指令 + 工具描述 + workspace summary → 可缓存复用
  • 变化部分：short-term memory + recent transcript + 最新用户请求 → 每轮更新
• 缓存稳定前缀，避免在每次交互中浪费算力重建不变的信息

组件 3：Tool Access and Use（工具访问与使用）

• 这是从「聊天」变成「agent」的关键转折
• 普通模型只能在文字中建议命令；harness 中的 LLM 能实际执行命令并获取结果
• harness 提供一组预定义的、有命名的工具，有明确的输入和边界
• 工具调用流程：模型发出结构化 action → harness 验证 → 可选的用户审批 → 执行 → 结果反馈回循环
• 验证检查包括：是否为已知工具？参数是否有效？是否需要用户审批？请求路径是否在 workspace 内？
• 给模型更少的自由度，反而提高了可用性和可靠性

组件 4：Minimizing Context Bloat（最小化上下文膨胀）

• Coding agent 比普通多轮聊天更容易出现 context bloat：重复的文件读取、冗长的工具输出、日志等
• 两种核心压缩策略：
  • Clipping（裁剪）：缩短长文档片段、大型工具输出、记忆笔记和 transcript 条目
  • Transcript reduction / summarization（摘要压缩）：把完整会话历史压缩为更小的可用摘要
• 关键技巧：保持最近事件更丰富（因为更可能与当前步骤相关），对更早的事件进行更激进的压缩
• 同时去重：如果同一个文件被读取多次，不要让模型反复看到相同的文件内容

"A lot of apparent 'model quality' is really context quality." ——这是 coding agent 设计中被低估的「无聊」部分

组件 5：Structured Session Memory（结构化会话记忆）

• Agent 将状态分为（至少）两层：
  • Working memory（工作记忆）：小型、精炼的显式状态——当前任务、重要文件、最近笔记
  • Full transcript（完整记录）：所有用户请求、工具输出、LLM 响应的完整历史
• 两者都存储为磁盘上的 JSON 文件，支持会话恢复
• Working memory vs Compact transcript 的区别：
  • Compact transcript 服务于 prompt reconstruction——给模型一个压缩的近期历史视图
  • Working memory 服务于 task continuity——维护跨轮次的重要信息摘要

组件 6：Delegation With Bounded Subagents（有约束的子 agent 委派）

• 当 agent 有了工具和状态，下一个有用能力是委派
• 允许将子任务并行化给 subagent，加速主任务
• 典型场景：主 agent 正在执行任务，需要一个旁答（哪个文件定义了某个符号、某个配置说了什么、某个测试为什么失败）
• 设计难题不是如何 spawn 一个 subagent，而是如何 bind 一个
• 核心原则：subagent 继承足够的上下文来完成工作，但运行在比主 agent 更紧的约束中（如只读、限制递归深度）

五、与 OpenClaw 的比较

• OpenClaw 更像是一个本地通用 agent 平台（也能编码），而非专门的终端编码助手
• 重叠之处：使用 workspace 中的指令文件（AGENTS.md 等）、JSONL session 文件、transcript 压缩、subagent
• 关键差异：Coding agent 优化的是「一个人在仓库中工作，让编码助手检查文件、编辑代码、运行本地工具」；OpenClaw 优化的是「跨聊天、频道和工作空间运行多个长期 agent」

六、思想框架

• 核心框架：Engine + Harness = Capability
  • 模型提供原始能力（engine），harness 释放这种能力（让模型做它擅长的 next-token prediction，把 repo navigation、context management、tool execution 等「脏活」交给外围系统）
• 六组件协同：Live Repo Context → Prompt Cache → Tool Use → Context Compaction → Session Memory → Subagent Delegation，形成一个从「信息收集 → 高效利用 → 行动执行 → 状态维护 → 任务分解」的完整闭环
• 被低估的工程：context quality 常被误认为 model quality——好的 agent 产品感觉「模型更强」，其实很多时候是 harness 做得好

concepts｜2️⃣ 关键概念、概念网络

一、核心概念解析 (Core Concepts)

• 【Agent Harness / Coding Harness】（Agent 脚手架 / 编码脚手架）

  • context：

    "When we say harness, we typically mean the software layer around the model that assembles prompts, exposes tools, tracks file state, applies edits, runs commands, manages permissions, caches stable prefixes, stores memory, and many more."

  • 费曼一下：Harness 就是包裹在 LLM 外面的那层「操作系统」。模型只负责 next-token prediction，而 harness 负责一切脏活——组装 prompt、暴露工具、跟踪文件状态、执行命令、管理权限、缓存前缀、存储记忆。Coding harness 是其专为编程任务设计的特化版本。作者的核心观点是：各家 vanilla LLM 能力已经趋同，harness 才是决定产品体验差异的关键变量。

• 【Control Loop】（控制循环）

  • context：

    "An agent is a layer on top, which can be understood as a control loop around the model. Typically, given a goal, the agent layer (or harness) decides what to inspect next, which tools to call, how to update its state, and when to stop."

  • 费曼一下：Agent 的本质是一个围绕模型的控制循环：给定目标 → 决定下一步检查什么 → 调用什么工具 → 更新状态 → 判断是否停止。这不是一次性的问答，而是一个持续的「观察-分析-选择-行动」迭代过程。这个循环是 agent 与普通聊天的根本区别。

• 【Live Repo Context】（实时仓库上下文）

  • context：

    "The coding agent collects info ('stable facts' as a workspace summary) upfront before doing any work, so that it's not starting from zero, without context, on every prompt."

  • 费曼一下：Agent 在开始工作前，先扫描整个仓库环境——Git 分支、项目文档（AGENTS.md / README）、当前进行中的变更——生成一份 workspace summary。这份「稳定事实」让模型不必每次都从零开始猜测项目上下文。「Fix the tests」不是一条自足的指令，它的正确含义取决于仓库的具体状态。

• 【Prompt Shape And Cache Reuse】（提示结构与缓存复用）
• 【Tool Use / Structured Tool Access】（结构化工具调用）
• 【Context Bloat / Context Compaction】（上下文膨胀 / 上下文压缩）
• 【Structured Session Memory】（结构化会话记忆）
• 【Bounded Subagents / Delegation】（有约束的子 agent 委派）

二、概念网络 (Concept Network)

• 层次包含关系：LLM → Reasoning Model → Agent → Agent Harness → Coding Harness，每一层在前一层基础上添加能力
• Engine + Harness = Capability：模型提供原始推理能力（engine），harness 通过六大组件释放这种能力，两者缺一不可
• 六组件的协同流水线：
• Context Quality ≈ Model Quality：context bloat management 和 session memory 共同决定了「上下文质量」，而这常被外界误认为是「模型质量」的差异——这是贯穿全文的核心洞察
• 约束即能力：Tool Use 中的结构化验证和 Subagent 中的有界委派，都体现了同一个设计哲学——通过限制自由度来提升可靠性

agentic reading｜3️⃣ 费曼 x3