Empryo 复合工具全解析:一行指令搞定重命名、移动与重构

原创2026-10-12 10:47:081,262 阅读

Empryo 复合工具全解析:一行指令搞定重命名、移动与重构

Empryo 是一款面向桌面、终端与 CI 的 AI coding harness(AI 编程代理工具),它能自动绘制仓库地图、按符号精确编辑代码、跑通检查后提交。它的杀手锏是复合工具(Compound Tools):把"重命名 → 改所有引用 → 修 import → 跑检查"这种多步任务压缩成一次调用,你只需一行自然语言指令,就能搞定跨文件重命名、符号移动与代码重构。

为什么需要复合工具?

传统 AI 助手改代码时,Agent 要"盲猜":先 grep 找引用、再逐个文件编辑、然后猜测试命令……每一步都在烧 token 和步数:

Agent: I'll run the tests with `npm test`
Shell: npm ERR! missing script: test
Agent: Let me try `npx jest`...

Empryo 的思路是:让工具一次做完整个任务。Agent 不用解释每一步,也不用猜命令。官方给出的实测对比(在 8 个文件中重命名一个导出类):

指标 手动分步方式 rename_symbol 复合工具
Agent 步数 19 步 3 步
Token 成本 $0.228 $0.036

工具自己找到符号、执行 LSP 重命名、验证零残留引用,然后汇报结果——没有探索、没有猜测、没有验证循环。

Empryo 复合工具重命名重构演示

复合工具全家福:一张表看懂

Empryo 的复合工具覆盖"改代码 → 验证"的完整链路,核心成员如下(完整列表见 constants.ts):

工具 一句话说明
rename_symbol 跨所有文件重命名符号,LSP 驱动并自动验证
move_symbol 把符号移到另一个文件 + 更新所有 import
rename_file 重命名/移动文件 + 更新所有引用者
refactor 提取函数/变量、整理 import、格式化
project 自动检测工具链,跑 lint / typecheck / test / build,支持 23 个生态
navigate 查定义、引用、调用层级、类型层级
read 按行号区间或按符号名读取文件
ast_edit TypeScript/JavaScript 的手术式 AST 编辑,65+ 种操作

官方文档入口:compound-tools.mdx。

rename_symbol:跨文件重命名,零残留引用

最常用的场景:类名、函数名改掉了,但几十个文件还在引用旧名字。传统做法是全局搜索替换,风险极高(字符串匹配会误伤同名变量、注释、字符串字面量)。

你只需要说:

> rename UserService to AccountService

Agent 直接调用 rename_symbol——一次基于 LSP 的调用更新每一个文件,并自动验证不存在悬空引用(dangling references)。

关键特性:

  • ✅ 支持函数、类、类型、接口、变量、枚举,不需要告诉它符号在哪个文件
  • ✅ 同名符号有多个时,Agent 会停下来让你选择,不会乱改
  • ✅ 重命名前可先运行 /lsp status 确认 LSP 已挂载
  • ✅ 所有改动自动保存检查点,Ctrl+B 一键全部回退

实现源码:rename-symbol.ts。

Empryo 桌面端仓库地图

move_symbol 与 rename_file:移动代码不断链

重构时最麻烦的不是"移动",而是"移动后修好所有 import 和 re-export"。Empryo 把这两件事做成了单步操作。

移动符号到别的文件:

> move parseConfig from src/utils.ts to src/config/parser.ts

符号被移走,项目里所有 import 同步更新,re-export 自动修正。完整支持 TypeScript、JavaScript、Python、Rust。

重命名/移动文件:

> rename src/old-name.ts to src/utils/new-name.ts

文件移动 + 所有引用者路径更新,一次完成。

底层采用事务机制:先暂存所有文件写入,全部校验通过(包括安全检查)才一次性落盘,任何一步失败则整体回滚,不会出现"改了一半"的中间态。核心实现:move-symbol.ts。

refactor 与 ast_edit:手术级代码重构

refactor 工具封装了 LSP 的 Code Action,四句话覆盖日常重构:

> extract lines 42-58 of handler.ts into a function called validateInput   # 提取函数
> clean up imports in src/api.ts                                            # 整理 import
  • 提取函数:refactor extract_function 是 LSP 代码动作,提取出的代码自动带上正确的参数和返回类型
  • 整理 import:通过 LSP 排序、去重、删除未使用的导入

而更底层的 ast_edit 是首个 AST 原生 AI 编辑器:对 TypeScript/JavaScript 文件,它不按文本匹配,而是按"符号种类 + 名字"进行结构化修改。65+ 种操作覆盖改返回类型、加参数、增删类成员、换继承关系等,且支持原子批量——一批操作要么全成功、要么全不应用。编辑前后还会对比诊断,新出现的类型错误立刻回流给 Agent 修复。

你不需要手动调用它,Agent 处理 TS/JS 文件时会自动优先选择。完整操作参考:ast-edit.mdx,工具实现:refactor.ts。

project 工具:自动探测工具链,不再猜测试命令

"跑一下测试"看似简单,实际上每个项目的命令都不同。project 工具通过扫描配置文件和锁文件自动识别工具链(bun.lock → bun test,Cargo.toml → cargo test,go.mod → go test……),覆盖 23 个生态:

你对它说 它实际执行
"run tests" project(action: "test")
"run the auth tests" project(action: "test", file: "auth")
"lint and fix" project(action: "lint", fix: true)
"typecheck" project(action: "typecheck")
"build" project(action: "build")

更妙的是:当 Agent 通过 shell 手跑了 bun run lint 之类的命令,结果里会附带提示"下次请用 project(action: "lint")",持续把 Agent 教育到最优路径上。Monorepo 场景下,project(action: "list") 能自动发现 pnpm workspace、Cargo workspace、Go workspace 的所有子包。详见:project.mdx。

Empryo 终端界面

安全网:改错了怎么办?

复合工具动作大,Empryo 为它配了三层保险:

  1. 检查点(Checkpoints):每轮对话自动存档,Ctrl+B / Ctrl+F 前后穿梭,/checkpoint undo 同时回退对话和磁盘文件。详见:checkpoints.mdx
  2. 编辑前诊断快照:编辑前采集 LSP 诊断,编辑后只回流新产生的错误,避免 Agent 被历史错误干扰
  3. 事务回滚:move_symbol 等多文件写入是"全有或全无",失败自动还原;ast_edit 在编辑前做文件快照,若磁盘文件中途被改动则直接拒绝

快速上手:3 步开始用

第 1 步:安装(仓库为只读镜像,安装请使用官方渠道)

curl -fsSL https://empryo.com/install.sh | bash   # macOS / Linux
irm https://empryo.com/install.ps1 | iex          # Windows

第 2 步:打开项目。Empryo 会先绘制仓库地图——文件、符号、导入关系全部索引并排序,"知道一次编辑会碰到什么,再动手"。

第 3 步:自然语言下指令,比如:

> rename UserService to AccountService, then run tests and commit

重命名、跑测试、写提交信息,全程无需你描述任何步骤。

Empryo 先绘制仓库地图再编辑代码

更多可复制的指令示例(重命名、移动、测试、提交流程):rename-refactor.mdx 和 test-and-commit.mdx。

常见问题 FAQ

Q:复合工具和普通文本替换有什么本质区别? A:普通替换是字符串匹配,同名就全改,容易误伤;rename_symbol 走 LSP 语义解析,只改真正的引用,改完自动验证零残留,且成本更低(8 文件重命名仅 3 步 / $0.036)。

Q:重命名时同名符号很多,会改错吗? A:不会。检测到歧义时 Agent 会暂停并请你选择目标符号;所有写入走事务提交,失败整体回滚。

Q:支持哪些语言? A:重命名/移动/重构基于 LSP,覆盖 TypeScript、JavaScript、Python、Rust 等主流语言;ast_edit 专门针对 TS/JS(.ts .tsx .js .jsx .mts .cts .mjs .cjs),其他文件自动回退到通用编辑工具。

Q:改坏了能撤销吗? A:能。检查点 + Ctrl+B 一键回退,undo_edit 也可逆向撤销单次编辑,文件内容、引用更新全部还原。

总结

Empryo 复合工具的设计哲学可以概括为一句话:一次调用做完一整件事。rename_symbol、move_symbol、refactor、project 把"找引用 → 改代码 → 修 import → 跑检查"的冗长链路封装成原子操作,配合检查点回滚与 LSP 诊断回流,让"一行指令搞定重命名、移动与重构"真正成为日常。无论你用桌面端、终端还是 CI,同一套地图与记忆,体验一致。🚀

登录后查看全文
Empryo