Empryo 复合工具全解析:一行指令搞定重命名、移动与重构
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 的复合工具覆盖"改代码 → 验证"的完整链路,核心成员如下(完整列表见 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。
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 为它配了三层保险:
- 检查点(Checkpoints):每轮对话自动存档,
Ctrl+B/Ctrl+F前后穿梭,/checkpoint undo同时回退对话和磁盘文件。详见:checkpoints.mdx - 编辑前诊断快照:编辑前采集 LSP 诊断,编辑后只回流新产生的错误,避免 Agent 被历史错误干扰
- 事务回滚:
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
重命名、跑测试、写提交信息,全程无需你描述任何步骤。
更多可复制的指令示例(重命名、移动、测试、提交流程):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,同一套地图与记忆,体验一致。🚀



