
<!-- path: toolchain/index.md -->
# 工具链

- [MoonBit 的构建系统](moon/index.md)：`moon`构建系统的完整手册。
- [MoonBit 的 Agent IDE](moonide/index.md)：`moon ide`（代理 IDE）的完整手册。
- [MoonBit 的 VSCode 插件](vscode/index.md)：关于 VSCode 插件的提示。

其他工具链

- [WebAssembly 工具链](wasm/index.md)：如何在 MoonBit 中使用 Wasm。
- ...

# 目录：

* [Moon 构建系统](moon/index.md)
  * [MoonBit 构建系统教程](moon/tutorial.md)
  * [运行 `.mbtx` 脚本](moon/script-mode.md)
  * [使用与发布包](moon/package-manage-tour.md)
  * [工作区支持](moon/workspace.md)
  * [`moon`的命令行帮助](moon/commands.md)
  * [模块配置](moon/module.md)
  * [包配置](moon/package.md)
  * [测量代码覆盖率](moon/coverage.md)
* [MoonBit Agent IDE](moonide/index.md)
  * [概览](moonide/index.md#overview)
  * [符号语法](moonide/index.md#symbol-syntax)
  * [`moon ide peek-def` - 查看符号定义](moonide/index.md#moon-ide-peek-def-view-symbol-definitions)
  * [`moon ide find-references` - 追踪所有用法](moonide/index.md#moon-ide-find-references-track-all-usages)
  * [`moon ide outline` - 获取结构概览](moonide/index.md#moon-ide-outline-get-structural-overview)
  * [`moon ide doc` - 发现与探索 API](moonide/index.md#moon-ide-doc-discover-and-explore-apis)
* [MoonBit VSCode 插件](vscode/index.md)
  * [命令](vscode/index.md#commands)
  * [操作](vscode/index.md#actions)
  * [代码透镜](vscode/index.md#code-lens)
* [WebAssembly 集成](wasm/index.md)
  * [组件模型](wasm/index.md#component-model)
  * [自定义导出和导入](wasm/index.md#custom-export-and-import)
  * [问与答](wasm/index.md#q-a)

<!-- path: toolchain/moon/index.md -->
## Moon 构建系统

## 目录：

* [MoonBit 构建系统教程](tutorial.md)
  * [先决条件](tutorial.md#prerequisites)
  * [创建一个新模块](tutorial.md#creating-a-new-module)
  * [理解模块目录结构](tutorial.md#understanding-the-module-directory-structure)
  * [使用包](tutorial.md#working-with-packages)
  * [选择目标后端](tutorial.md#choosing-a-target)
  * [包导入](tutorial.md#package-importing)
  * [创建和使用新包](tutorial.md#creating-and-using-a-new-package)
  * [添加测试](tutorial.md#adding-tests)
* [运行 `.mbtx` 脚本](script-mode.md)
  * [运行 `.mbtx` 文件](script-mode.md#run-a-mbtx-file)
  * [从 stdin 运行 `.mbtx` 脚本](script-mode.md#run-a-mbtx-script-from-stdin)
* [使用与发布包](package-manage-tour.md)
  * [设置 mooncakes.io 账户](package-manage-tour.md#setup-mooncakes-io-account)
  * [设置 MoonBit 项目](package-manage-tour.md#setup-moonbit-project)
  * [添加依赖](package-manage-tour.md#add-dependencies)
  * [从模块导入包](package-manage-tour.md#import-packages-from-module)
  * [移除依赖](package-manage-tour.md#remove-dependencies)
  * [发布你的模块](package-manage-tour.md#publish-your-module)
* [工作区支持](workspace.md)
  * [初始化工作区](workspace.md#initialize-a-workspace)
  * [添加成员](workspace.md#add-members)
  * [在工作区根目录工作](workspace.md#work-at-workspace-root)
  * [同步成员版本](workspace.md#sync-member-versions)
* [`moon`的命令行帮助](commands.md)
  * [`moon`](commands.md#moon)
  * [`moon new`](commands.md#moon-new)
  * [`moon build`](commands.md#moon-build)
  * [`moon check`](commands.md#moon-check)
  * [`moon run`](commands.md#moon-run)
  * [`moon test`](commands.md#moon-test)
  * [`moon clean`](commands.md#moon-clean)
  * [`moon fmt`](commands.md#moon-fmt)
  * [`moon doc`](commands.md#moon-doc)
  * [`moon info`](commands.md#moon-info)
  * [`moon bench`](commands.md#moon-bench)
  * [`moon add`](commands.md#moon-add)
  * [`moon remove`](commands.md#moon-remove)
  * [`moon install`](commands.md#moon-install)
  * [`moon tree`](commands.md#moon-tree)
  * [`moon login`](commands.md#moon-login)
  * [`moon register`](commands.md#moon-register)
  * [`moon publish`](commands.md#moon-publish)
  * [`moon package`](commands.md#moon-package)
  * [`moon update`](commands.md#moon-update)
  * [`moon coverage`](commands.md#moon-coverage)
  * [`moon coverage analyze`](commands.md#moon-coverage-analyze)
  * [`moon coverage report`](commands.md#moon-coverage-report)
  * [`moon coverage clean`](commands.md#moon-coverage-clean)
  * [`moon generate-build-matrix`](commands.md#moon-generate-build-matrix)
  * [`moon upgrade`](commands.md#moon-upgrade)
  * [`moon shell-completion`](commands.md#moon-shell-completion)
  * [`moon version`](commands.md#moon-version)
* [模块配置](module.md)
  * [名称](module.md#name)
  * [版本](module.md#version)
  * [依赖管理](module.md#dependency-management)
  * [元信息](module.md#meta-information)
  * [包含和排除](module.md#include-and-exclude)
  * [首选目标](module.md#preferred-target)
  * [支持的目标](module.md#supported-targets)
  * [源目录](module.md#source-directory)
  * [警告列表](module.md#warning-list)
  * [Rule](module.md#rule)
  * [脚本](module.md#scripts)
* [包配置](package.md)
  * [新格式（`moon.pkg`）](package.md#new-format-moon-pkg)
  * [名称](package.md#name)
  * [格式化](package.md#formatter)
  * [is-main](package.md#is-main)
  * [导入依赖](package.md#importing-dependencies)
  * [最大并发测试数](package.md#maximum-concurrent-tests)
  * [条件编译](package.md#conditional-compilation)
  * [支持的目标](package.md#supported-targets)
  * [原生存根文件](package.md#native-stub-files)
  * [链接选项](package.md#link-options)
  * [Rule 和 dev_build](package.md#rule-and-dev-build)
  * [警告列表](package.md#warnings-list)
  * [虚拟包](package.md#virtual-package)
* [测量代码覆盖率](coverage.md)
  * [在测试中运行代码覆盖率](coverage.md#running-code-coverage-in-tests)
  * [可视化覆盖率结果](coverage.md#visualizing-the-coverage-results)
  * [跳过覆盖检查](coverage.md#skipping-coverage)

<!-- path: toolchain/moonide/index.md -->
## MoonBit Agent IDE

### 概览

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

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

#### 可用命令

- **`moon ide peek-def`**：在上下文中定位符号定义
- **`moon ide find-references`**：定位符号在整个项目中的所有用法
- **`moon ide outline`**：获取文件或包的结构概览
- **`moon ide doc`**：结合文档发现并探索 API

### 符号语法

所有 `moon ide` 子命令都接受 `<symbol>` 参数，支持以下模式：

**基础符号：**

- `[@pkg.]symbol` - 包中的符号（例如 `parse_int`、`Array`）
- 如果省略 `@pkg.`，则搜索当前包和 prelude

**类型成员：**

- `[@pkg.]Type::member` - 类型方法、结构体字段、枚举变体、trait 方法
- 示例：`Array::length`、`@http.Request::new`、`Option::None`

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

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

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

#### 用法

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

**两种模式：**

1. **全局搜索**（不带 `-loc`）：使用上文描述的符号语法在整个项目中搜索
2. **上下文搜索**（提供 `-loc`）：在指定位置将 `<symbol>` 作为子串进行匹配
   - 行号必须精确；列号可选（作为提示使用）
   - `<symbol>` 参数按纯文本匹配，不会按符号语法解析
   - 当符号名有歧义或出现在多个上下文中时非常有用

#### 示例

```bash
$ 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 {
...|
...| }
```

```bash
$ 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` - 追踪所有用法

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

#### 用法

```bash
moon ide find-references <symbol>
```

注意：目前还不支持 `-loc` 参数。始终执行全局搜索。

#### 示例

```bash
$ moon ide find-references 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 {
...|
...| }
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 outline` - 获取结构概览

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

#### 用法

```bash
moon ide outline <path/to/file_or_directory>
```

两种模式：

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

#### 示例

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

```bash
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 {
```

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

```bash
$ 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。

#### 用法

```bash
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.]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" 的所有符号

#### 示例

**搜索类型方法：**

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

type String

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

**探索一个包：**

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

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

**查询特定函数：**

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

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

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

```bash
$ 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) -> Int?
  Returns ... omitted ...
```

<!-- path: toolchain/vscode/index.md -->
## MoonBit VSCode 插件

MoonBit 为 Visual Studio Code 提供了一个插件，可以在 [Visual Studio 市场](https://marketplace.visualstudio.com/items?itemName=moonbit.moonbit-lang) 和 [Open VSX 仓库](https://open-vsx.org/extension/moonbit/moonbit-lang) 中找到。

### 命令

该插件提供了几个命令，可以通过 [命令面板](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) 访问

- 选择后端：它允许你在多个后端之间切换
- 重启 MoonBit 语言服务器：它允许你重启语言服务器，以防它无响应或有一些过时的状态。
- 安装 MoonBit 工具链：手动触发安装过程。该扩展将检查已安装的 MoonBit 工具链是否与扩展的版本匹配。
- 获取 LSP 的编译器版本：它将显示扩展使用的 MoonBit 编译器版本。
- 切换多行字符串：帮助在纯文本与 MoonBit 的 [多行字符串语法](../../language/fundamentals.md#string) 之间切换所选文本。

### 操作

该插件还提供了几个操作，可以通过 [快速修复](https://code.visualstudio.com/docs/editing/refactoring#_code-actions-quick-fixes-and-refactorings) 访问

- 添加缺失的分支：当遇到 [错误 0011](../../language/error_codes/E0011.md) 时，它允许你填充 `match` 表达式的分支

### 代码透镜

该插件为每个顶级代码块，特别是测试块，提供代码透镜。

提供的功能包括：

- 格式化：格式化代码块
- 测试 / 基准：测试或基准测试代码块
- 调试（仅限 JavaScript 后端）：使用调试器测试测试块
- 更新：更新代码块中的 [快照测试](../../language/tests.md#snapshot-tests)
- 跟踪：打开/关闭测试块的跟踪，其中每个赋值将在其旁边呈现值

<!-- path: toolchain/wasm/index.md -->
## WebAssembly 集成

MoonBit 是一种提供对 WebAssembly 进行一流支持的编程语言。

### 组件模型

查看 [本教程](component-model-tutorial.md) 了解如何在 MoonBit 中使用 [组件模型](https://component-model.bytecodealliance.org/)。

### 自定义导出和导入

查看 [FFI](../../language/ffi.md) 部分，了解如何导入或导出函数。

### 问与答

1. 问：什么是 `spectest.print_char`

   A: 这是 MoonBit 打印的方式。它一次打印一个 UTF-16 Unicode 代码。为了可移植性，避免使用 `println`。如果这确实出现在最终结果中，请考虑使用 [`wasm-merge`](https://github.com/WebAssembly/binaryen) 或类似工具。