TokenCap：为什么我们用确定性 AST 重构而非让 LLM 生成代码

dev.to · AI#AST#重构#LLM

Editor brief · 编辑速览

TokenCap 选择用 tree-sitter AST 确定性遍历执行重构命令，而非 LLM 生成式改写，避免了字符串字面量误匹配、变量遮蔽、barrel 文件重导出遗漏等问题，并附实际输出示例。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

当开发者让 AI 代理执行"将项目中的 handleUser 重命名为 processUser"时，大多数代理执行的是模糊的 grep 搜索，并尝试逐个文件重写。

这种做法容易出现边界情况错误：

过度匹配：在字符串字面量或无关注释中错误地重命名了 handleUser。

变量遮蔽：与已存在的作用域内变量发生冲突。

遗漏导出：在 barrel 文件中忘记了重导出的名称。

在 TokenCap 中，重构命令通过确定性的 tree-sitter AST 遍历来执行，而不是生成式 token 预测。

# Safely rename a function across the entire call graph
tokencap refactor rename src/auth.js:validateSession authenticateSession --dry-run

Inspecting 58 files...
Resolved 12 exact symbol references:
  ✓ src/auth.js:24: declaration
  ✓ src/middleware/session.js:15: call site
  ✓ src/routes/api.js:82: call site
  - Skipping string literal at src/tests/mock.js:12 ("validateSession")
Dry run complete: 12 references updated across 3 files with 0 syntax errors.

类似地，tokencap refactor rm-dead 使用我们的 AST 调用解析图来检测未被调用且未导出的死函数，并安全地将它们剪枝。

通过让 LLM 负责高层决策，让 TokenCap 负责确定性的语法树转换，重构操作可以保持安全且可复现。

文档见 tokencap.vansharora.app