框架手册：让演化的代理框架变得可读、可导航且可编辑

摘要

现代AI代理的能力不仅取决于其基础模型，还取决于其调控框架（harness）——该框架负责构建提示词、管理状态、调用工具并协调执行。随着模型、API、环境和需求的变化，调控框架需要不断修改。在实施变更之前，开发人员或编码代理必须识别所有实现目标行为的代码位置。这之所以困难，是因为生产级调控框架规模庞大、耦合紧密且行为分散，而修改请求描述的是系统应该做什么，代码库却按文件和模块组织。代码搜索、代码库索引和长上下文处理虽有助于审查，但仍需手动恢复这种“行为到代码”的映射。因此，行为定位（behavior localization）成为调控框架演化的核心瓶颈。我们提出了Harness手册（Harness Handbook），这是一种通过静态分析和LLM辅助结构化从调控框架代码库中自动合成的行为中心化表示，将每种行为与其对应代码源相链接。我们还引入了行为引导渐进式披露（Behavior-Guided Progressive Disclosure, BGPD），该技术引导代理从高层行为逐步进入相关实现细节，并对照当前代码源验证候选位置。在两个开源调控框架的多样化修改请求上，基于手册辅助的规划在使用更少规划令牌的同时，提升了行为定位和编辑规划质量，在分散代码点、低频执行路径及跨模块交互场景中改进最为显著。因此，复杂代理系统的演化不仅取决于生成编辑本身，更在于确定这些编辑应作用于何处。

English

The capability of a modern AI agent depends not only on its foundation model but also on its harness, which constructs prompts, manages state, invokes tools, and coordinates execution. As models, APIs, environments, and requirements evolve, the harness must be continually modified. Before such a change can be made, a developer or coding agent must identify all code locations that implement the target behavior. This is difficult because production harnesses are large, tightly coupled, and behaviorally distributed, while modification requests describe what the system should do and repositories are organized by files and modules. Code search, repository indexing, and long-context processing ease inspection, but still leave this behavior-to-code mapping to be recovered by hand. Behavior localization is therefore a central bottleneck in harness evolution. We introduce the Harness Handbook, a behavior-centric representation synthesized automatically from a harness codebase via static analysis and LLM-assisted structuring, linking each behavior to its corresponding source. We also introduce Behavior-Guided Progressive Disclosure (BGPD), which guides agents from high-level behaviors to relevant implementation details and verifies candidate locations against the current source. On diverse modification requests from two open-source harnesses, Handbook-Assisted planning improves behavior localization and edit-plan quality while using fewer planner tokens, with the largest gains on scattered sites, rarely executed paths, and cross-module interactions. Evolving complex agentic systems thus depends not only on generating edits, but also on determining where those edits should be made.

框架手册：让演化的代理框架变得可读、可导航且可编辑

Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

摘要

Support