CODESTRUCT: Code Agents over Structured Action Spaces

Idea

CodeStruct 将代码仓库暴露为 named AST entities 组成的 action space，用 readCode 获取完整语法单元，用 editCode 对函数、类和方法执行 insertion、replacement、removal。它改变 Agent 与代码的接口，而无需更换其规划模型或训练权重。

Research Problem

Text-based agents 要么读整文件引入噪声，要么读行范围截断函数。String replacement 还要求重写大量原文，格式漂移会导致 no occurrence，重复片段会导致 multiple occurrence，进而浪费重试 token 或产生空 patch。仅提供 repo map 并未改变最后编辑仍依赖文本匹配的问题。

Insight

代码已自带作用域和命名结构，可以直接作为工具选择器，而不仅用作模型输入特征。把“要改哪个实体”与“在文本中怎样定位和保存”分开，让工具承担边界定位和语法校验，缩短输出并提高操作可靠性。语法有效性仍不等于行为正确。

Method

1. readCode 支持目录浏览、小文件全文、大文件 signatures 摘要，以及 file+selector 的完整实体读取。Selector 可指定 scoped name，如 Class.method，也支持 deterministic name-based fuzzy matching，避免依赖绝对行号。
2. editCode 解析或复用 cached AST，定位 selector 对应节点，取得局部 indentation，按请求在节点后插入、替换节点或删除节点。未找到实体则返回明确错误。
3. 修改后验证 AST 是否存在 syntax error，失败不提交，成功才写回源文件。每次调用构成可跟踪的结构状态转换，Agent 仍需判断功能需求并运行验证。
4. 通过 MCP 将两工具接入现有 Agent，保持其 planning/execution logic。实验在 SWE-Bench Verified 和 CodeAssistBench 上跨模型比较 Pass@1、token/cost 与 empty-patch failures，检查改善是否来自减少接口失败。