Harness手冊：讓進化中的智能體框架變得可讀、可導航與可編輯

摘要

现代AI智能体的能力不仅取决于其基础模型，还取决于其控制框架——该框架负责构建提示词、管理状态、调用工具以及协调执行流程。随着模型、应用程序接口、环境与需求不断演进，控制框架也必须持续调整。在进行此类变更之前，开发者或编程智能体必须识别所有实现目标行为的代码位置。这一过程极为困难，因为生产环境中的框架规模庞大、耦合紧密且行为分布零散，而修改请求描述的是系统应实现的功能，代码库却按文件与模块组织。代码搜索、代码库索引及长上下文处理虽能简化审查工作，但仍需人工将行为与代码进行一一映射。因此，行为定位成为框架演进的核心瓶颈。我们提出"框架手册"这一行为导向型表征，通过静态分析与大语言模型辅助结构化，从框架代码库中自动合成，将每个行为与其对应源代码关联起来。我们还提出"行为引导渐进式披露"方法，引导智能体从高层行为出发，逐步深入相关实现细节，并依据当前源码验证候选定位。在来自两个开源框架的多样化修改请求测试中，基于手册辅助的规划方法在提升行为定位与编辑方案质量的同时，减少了规划所需的令牌消耗。对于分散的代码位置、低频执行路径及跨模块交互场景，该方法提升尤为显著。由此可见，复杂智能体系统的演进不仅取决于生成编辑方案本身，更在于精准确定编辑的实施位置。

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手冊：讓進化中的智能體框架變得可讀、可導航與可編輯

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

摘要

Support