MoonBit Agent IDE

MoonBit Agent IDE#

概览#

moon ide 是一套专门用于导航、理解和探索 MoonBit 代码库的 CLI 工具。它基于编译器对项目结构的理解，提供具备语义感知能力的代码发现工具。

这些命令使用语义分析而不是文本匹配，因此在代码导航任务中比基于 grep 的搜索更精确。

导航命令适用于模块、多模块工作区以及独立的 .mbtx 脚本。在多模块工作区中，moon ide 遵循各模块所配置的后端。对于单个模块，提供 --target 选项的命令可以选择项目检查所使用的后端。

可用命令#

  • moon ide peek-def：在上下文中定位符号定义

  • moon ide find-references：定位符号在整个项目中的所有用法

  • moon ide rename：计算或应用语义重命名编辑

  • moon ide hover：显示源码位置处的类型和文档

  • moon ide outline：获取文件或包的结构概览

  • moon ide analyze：报告公共 API 的使用次数

  • moon ide doc：结合文档发现并探索 API

  • moon ide workspace-symbols：搜索工作区的顶层符号

  • moon ide codelens：以 JSON 返回引用 CodeLens 条目

  • moon ide gen-symbols：生成包符号索引

符号语法#

接受 <symbol> 参数的命令使用以下模式：

基础符号：

  • [@pkg.]symbol - 包中的符号（例如 parse_int、Array）

  • 如果省略 @pkg.，则搜索当前包和 prelude

类型成员：

  • [@pkg.]Type::member - 类型方法、结构体字段、枚举变体、trait 方法

  • Trait::method for Type - 某个类型对 trait 方法的实现

  • 示例：Array::length、@http.Request::new、Option::None

对于当前包和标准库中的符号，包前缀 @pkg. 是可选的。

moon ide peek-def - 查看符号定义#

快速定位符号定义及其周边上下文。相比用 grep 查找声明，这种方式更快也更准确。

用法#

moon ide peek-def <symbol> [--loc filename[:line[:col]]]

查找模式：

  1. 全局搜索（不带 --loc）：使用上文描述的符号语法搜索模块或工作区。

  2. 限定文件的搜索（--loc filename）：将初次符号查找限定在一个文件中。

  3. 源码位置查找（--loc filename:line[:col]）：解析该位置处的符号，适用于局部变量、被遮蔽的名称和有歧义的符号。同时给出行号和列号时，可以省略单独的 <symbol> 参数。

示例#

$ moon ide peek-def Agent
Found 1 symbols matching 'Agent':

`pub (all) struct Agent` in package moonbitlang/maria/agent at ./agent/agent.mbt:17-47

17 | ///|
   | /// Represents an AI agent that interacts with language models and executes tools.
...|
   | pub(all) struct Agent {
...|
...| }

$ moon ide peek-def Agent --loc ./maria.mbt:7
Definition found at file ./maria/agent/agent.mbt
   | ///
   | /// The `Agent` struct encapsulates the complete state and behavior of an AI agent,
...|
24 | pub(all) struct Agent {
   |                 ^^^^^
   |   /// UUID generator for creating unique identifiers.
...|

moon ide find-references - 追踪所有用法#

了解一个符号在整个代码库中的使用位置和方式。

用法#

moon ide find-references <symbol>
moon ide find-references <token> --loc <path[:line[:col]]>
moon ide find-references --loc <path:line:col>

不带 --loc 时，该命令会在当前模块或工作区中搜索语义符号。文件形式和源码位置形式的行为与 peek-def 相同，并支持局部变量和被遮蔽的名称。

默认不包含定义。添加 --include-definition 可将其包含在内。使用 --json 时，每个结果还包含 is_test 字段，用于标识测试块和测试文件中的引用。

示例#

$ moon ide find-references Agent --include-definition
`pub (all) struct Agent` in package moonbitlang/maria/agent at ./agent/agent.mbt:17-47
17 | ///|
   | /// Represents an AI agent that interacts with language models and executes tools.
...|
   | pub(all) struct Agent {
...|
...| }
Found 98 references of this symbol:
./agent/agent_tool.mbt:41:8-41:13:
   | /// * `agent` : The agent instance whose tools will be enabled or disabled.
   | /// * `tool_names` : A set containing the names of tools that should be enabled.
   | ///   Tools not in this set will be disabled.
41 | pub fn Agent::set_enabled_tools(
   |        ^^^^^
   |   agent : Agent,
   |   tool_names : Set[String],
...

moon ide codelens - 获取引用 CodeLens#

返回源码文件中顶层声明的局部引用和全局引用 CodeLens 条目：

moon ide codelens path/to/file.mbt

输出始终为 JSON 数组。局部引用的位置包含 is_test 字段，范围使用从 1 开始的 行:列-行:列 位置。

moon ide outline - 获取结构概览#

快速扫描文件或包的结构，理解其组织方式。

用法#

moon ide outline <path/to/file_or_directory>

两种模式：

  • moon ide outline path/to/file.mbt - 查看单个文件的结构

  • moon ide outline path/to/directory - 查看包内所有 .mbt 文件的结构

示例#

包结构 - 查看所有文件及其顶层符号：

moon ide outline .
maria.mbt:
 L05 | pub struct Maria {
       ...
 L71 | pub fn Maria::close(self : Maria) -> Unit {
       ...
 L84 | pub async fn Maria::start(self : Maria, prompt? : String) -> Unit {

文件结构 - 查看单个文件的详细结构：

$ moon ide outline ./internal/readline/readline.mbt
 L0002 | priv struct Edit {
         ...
 L0008 | pub enum KeyName {
         ...
 L0045 | pub struct Key {
         ...
 L1369 | pub async fn Interface::start(self : Interface) -> Unit {
         ...
 L1383 | pub async fn Interface::read_line(self : Interface) -> String {
         ...
 L1390 | pub async fn Interface::read_key(self : Interface) -> Key {
         ...

moon ide doc - 发现与探索 API#

查询文档并发现可用的符号、包和 API。

用法#

moon ide doc '<query>'

查询语法#

查询语法专门用于符号和包的发现：

空查询 - 列出可用包或符号：

  • moon ide doc ''

    • 在模块内：显示所有可用包（包括依赖和 moonbitlang/core）

    • 在包内：显示当前包中的所有符号

    • 在包外：显示所有可用包

按名称查找：

  • moon ide doc "[@pkg.]function_name" - 查找函数或值

  • moon ide doc "[@pkg.]TypeName" - 查找类型（内建类型不需要前缀）

  • moon ide doc "[@pkg.]Type::member" - 查找类型方法或字段

包探索：

  • moon ide doc "@pkg" - 列出一个包中所有导出符号

  • moon ide doc "@encoding/utf8" - 支持嵌套包

  • 示例：moon ide doc "@json"、moon ide doc "@buffer"

通配匹配（Globbing） - 使用 * 通配符进行部分匹配：

  • moon ide doc "String::*rev*" - 查找名称中包含 "rev" 的所有 String 方法

  • moon ide doc "*parse*" - 查找名称中包含 "parse" 的所有符号

示例#

搜索类型方法：

# Search for String methods in standard library:
$ moon ide doc "String"

type String

  pub fn String::add(String, String) -> String
  # ... more methods omitted ...

探索一个包：

$ moon ide doc "@buffer"
moonbitlang/core/buffer

fn from_array(ArrayView[Byte]) -> Buffer
# ... omitted ...

查询特定函数：

$ moon ide doc "@buffer.new"
package "moonbitlang/core/buffer"

pub fn new(size_hint? : Int32) -> Buffer
  Creates ... omitted ...

使用通配匹配查找相关函数：

$ moon ide doc "String::*rev*"
package "moonbitlang/core/string"

pub fn String::rev(String) -> String
  Returns ... omitted ...
  # ... more

pub fn String::rev_find(String, StringView) -> Int32?
  Returns ... omitted ...
目录