moonbit-orientation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MoonBit Orientation

MoonBit 技能定位

Use this skill to solve MoonBit developer questions by identifying the missing context first. This is an orientation skill, not a bundled copy of all MoonBit documentation.

使用本技能解决MoonBit开发者问题时，需先明确缺失的上下文。本技能是定位类技能，并非MoonBit所有文档的合集。

Default workflow

默认工作流程

Classify the user's situation and likely missing layer.
Check the gotchas below and the freshness gate before choosing a path.
Load the smallest relevant reference file.
If code, APIs, package config, or diagnostics are involved, inspect local files or run the narrowest discovery command before answering.
Give a practical answer: direct capability answer, MoonBit equivalent, exact verification command or link, and narrow validation command when code changed.
If the final answer gives an exact API, import, error-code meaning, target rule, or docs claim, include the command or URL that verifies it. Do this even when the answer is short.

If the user asks for exact standard-library APIs, package APIs, or recently changed behavior, verify with

moon ide doc

, official API docs, package docs, or local project files instead of guessing.

对用户的场景及可能缺失的知识层级进行分类。
在选择解决方案前，先查看下方的注意事项和时效性校验规则。
加载最小范围的相关参考文件。
若涉及代码、API、包配置或诊断信息，需先检查本地文件或执行最精准的发现命令，再给出答案。
提供实用的答案：直接给出能力说明、MoonBit等效方案、精确的验证命令或链接，若代码有变更则给出精准的验证命令。
若最终答案涉及具体API、导入语句、错误代码含义、目标规则或文档声明，需附上验证该内容的命令或URL，即使答案简短也需执行此操作。

若用户询问具体的标准库API、包API或近期变更的行为，需通过

moon ide doc

、官方API文档、包文档或本地项目文件进行验证，而非仅凭猜测。

Freshness gate

时效性校验规则

Some MoonBit facts move faster than model memory: new syntax, experimental features, package availability, package APIs, dependency versions, target support, and command flags. For these, do not turn memory into a final answer.

Use this pattern:

Say the capability-level answer if it is stable.
State that exact APIs, package names, or tool behavior may have changed.
Choose the current source: local project files, installed
```
moon
```
commands, official docs, mooncakes package docs, or the registry.
If the source cannot be checked in the current environment, say so and give the next check. Do not present an unchecked package, import, function, flag, or version as fact.

This is not a rule to verify every stable fact. It is a rule to admit when MoonBit ecosystem or feature knowledge may be stale, then check the latest source before making exact claims.

Keep freshness checks bounded. For package or API discovery, use one local toolchain query and, if needed, one registry or public-docs lookup. If those do not confirm the exact fact, stop and answer "not confirmed from the checked sources" with the next verification command. Do not run many near-duplicate web searches just to prove absence.

Keep discovery narrow. Once a source-of-truth command or document answers the user's requested level of detail, stop searching unless the user asked for examples, signatures, alternatives, or validation by execution. Do not spend extra context proving nearby facts that are not needed for the answer.

When recommending external material, provide a concrete URL from

references/source-map.md

. Do not assume the user has this repository checked out.

部分MoonBit相关信息的更新速度快于模型记忆：新语法、实验性功能、包可用性、包API、依赖版本、目标支持及命令参数等。对于此类信息，切勿将模型记忆作为最终答案。

遵循以下模式：

若能力层面的答案是稳定的，可直接给出。
说明具体API、包名称或工具行为可能已发生变更。
选择当前的权威数据源：本地项目文件、已安装的
```
moon
```
命令、官方文档、mooncakes包文档或注册表。
若当前环境无法检查该数据源，需告知用户并给出下一步的检查方法。切勿将未验证的包、导入语句、函数、参数或版本作为事实呈现。

此规则并非要求验证所有稳定事实，而是要求当MoonBit生态或功能知识可能过时的情况下，先检查最新数据源再给出具体声明。

时效性检查需控制范围。对于包或API发现，仅需执行一次本地工具链查询，若有需要再进行一次注册表或公开文档查询。若这些方式无法确认具体事实，需停止查询并回复“未从已检查的数据源中确认”，同时给出下一步的验证命令。无需多次执行近似重复的网络搜索来证明某项内容不存在。

发现过程需精准。一旦权威命令或文档已回答用户所需的细节程度，除非用户要求示例、签名、替代方案或执行验证，否则停止搜索。无需花费额外精力证明与答案无关的周边事实。

推荐外部资料时，需提供

references/source-map.md

中的具体URL。切勿假设用户已克隆此仓库。

Gotchas

注意事项

For standard-library and dependency APIs, default to
```
moon ide doc
```
in the user's project. It reflects the installed toolchain and dependencies better than memory or stale docs.
For ecosystem package availability, do not infer existence from a familiar technology name. Check mooncakes or
```
moon add <candidate>
```
in a disposable or user project before naming a dependency as available.
```
llvm
```
is nightly-only. Stable backend guidance should use
```
wasm
```
,
```
wasm-gc
```
,
```
js
```
, or
```
native
```
;
```
--target all
```
excludes
```
llvm
```
.
Do not answer exact API names by translating from Rust, Go, JavaScript, or OCaml names. Discover the MoonBit API first.
Do not send users to "the docs" without a concrete URL or command.
Local
```
moon.mod.json
```
and
```
moon.pkg.json
```
beat generic advice for package names, imports, targets, and dependencies.
For
```
E####
```
diagnostics, use
```
moon check --explain
```
or the exact online error page pattern before inventing a cause.

对于标准库和依赖API，默认使用用户项目中的
```
moon ide doc
```
。它比模型记忆或过时文档更能反映已安装的工具链和依赖情况。
对于生态包的可用性，切勿从熟悉的技术名称推断其存在。在将某个依赖列为可用之前，需在临时项目或用户项目中通过mooncakes或
```
moon add <候选包>
```
进行检查。
```
llvm
```
仅在夜间版本中可用。稳定后端建议使用
```
wasm
```
、
```
wasm-gc
```
、
```
js
```
或
```
native
```
；
```
--target all
```
不包含
```
llvm
```
。
切勿通过翻译Rust、Go、JavaScript或OCaml的名称来回答具体API名称。需先查找MoonBit对应的API。
切勿仅引导用户去“查看文档”而不提供具体URL或命令。
本地的
```
moon.mod.json
```
和
```
moon.pkg.json
```
在包名称、导入语句、目标及依赖方面的优先级高于通用建议。
对于
```
E####
```
类诊断信息，需先使用
```
moon check --explain
```
或对应的在线错误页面模板，再推测原因。

Verification contract

验证约定

Treat MoonBit facts as three tiers:

Stable capability facts: language/toolchain shape covered by this skill, such as no class-inheritance-first model, typed errors, common stable targets, and
```
llvm
```
being nightly-only.
Verified exact facts: exact API names, signatures, package names, imports, target config, and local project conventions confirmed by
```
moon ide
```
, local files, generated interfaces, official docs, or mooncakes.
Unverified guesses: plausible API names or behavior inferred from another language, memory, or naming convention.

Never present unverified guesses as facts. If an exact fact is not verified, say what must be checked and provide the command or URL. Prefer "I can answer the capability, but the exact API needs

moon ide doc '*json*'

" over a plausible module or function name.

If a verification command fails, returns no result, or was only checked outside the user's project, do not cite it as if it proved the exact API. Say what the failure means and give the next source, for example package installation,

moon tree

, mooncakes package docs, or a local dependency file.

If you did verify an exact fact, say so compactly: "Verified with

moon ide doc '@json'

" or "Source: <URL>". Do not omit the verification source after naming exact imports, functions, or error meanings.

Do not cite this skill's own reference files as the final verification source for users. The final answer should cite an external URL, a local project file, or a command result. The skill is guidance for the agent, not user-facing evidence.

This rule still applies when a reference file contained the answer. Use the reference file to route the work, then cite the public URL, command, or local project file named by that reference.

Avoid "likely" guesses for exact API behavior. For unknown calls such as

Json.parse

result.unwrap()

, say "verify whether this returns typed errors or a result-like value" instead of guessing which one it uses.

将MoonBit相关事实分为三个层级：

稳定能力事实：本技能涵盖的语言/工具链框架，例如无类继承优先模型、类型化错误、常见稳定目标及
```
llvm
```
仅在夜间版本可用等。
已验证的具体事实：通过
```
moon ide
```
、本地文件、生成的接口、官方文档或mooncakes确认的具体API名称、签名、包名称、导入语句、目标配置及本地项目约定。
未验证的猜测：从其他语言、模型记忆或命名规则推断出的看似合理的API名称或行为。

切勿将未验证的猜测作为事实呈现。若具体事实未经验证，需说明需检查的内容并提供对应的命令或URL。例如，优先回复“我可以回答能力层面的问题，但具体API需要执行

moon ide doc '*json*'

来确认”，而非给出看似合理的模块或函数名称。

若验证命令执行失败、无返回结果或仅在用户项目外进行了检查，切勿将其作为具体API的证明。需说明失败的含义并给出下一个数据源，例如包安装、

moon tree

、mooncakes包文档或本地依赖文件。

若已验证具体事实，需简洁说明：“已通过

moon ide doc '@json'

验证”或“来源：<URL>”。在给出具体导入语句、函数或错误含义后，切勿省略验证来源。

切勿将本技能自身的参考文件作为用户的最终验证来源。最终答案需引用外部URL、本地项目文件或命令执行结果。本技能是给Agent的指导，而非面向用户的证据。

即使参考文件中包含答案，此规则依然适用。使用参考文件引导工作流程，然后引用该参考文件中提到的公开URL、命令或本地项目文件。

避免对具体API行为进行“可能”的猜测。对于未知调用（如

Json.parse

或

result.unwrap()

），需说明“请验证该调用返回的是类型化错误还是类Result的值”，而非猜测其具体行为。

Situation routing

场景路由

Learning MoonBit or asking where to start: read

references/question-routing.md

and

references/source-map.md

Asking "Does MoonBit have X?", API availability, or quick capability questions: read
```
references/answer-shapes.md
```
first. Load
```
references/capabilities-faq.md
```
only when the quick shape does not cover the concept or the user asks for a broader comparison. If exact APIs are involved, use
```
references/lookup-recipes.md
```
.
Coming from Go, Rust, TypeScript, OCaml, or another language: read
```
references/mental-models.md
```
.
Writing, reviewing, or refactoring MoonBit code: read
```
references/idioms.md
```
.
Debugging compiler output,
```
moon
```
output, package errors, backend errors, or diagnostics with an
```
E####
```
code: read
```
references/diagnostics-playbook.md
```
and the relevant recipe in
```
references/lookup-recipes.md
```
.
Setting up modules, packages, workspaces, tests, docs, coverage, or build targets: read
```
references/toolchain-map.md
```
.
Choosing between official docs, mooncakes API docs, the Tour, examples, error code docs, or local project inspection: read
```
references/source-map.md
```
.

For tasks that span multiple areas, read the most specific reference first, then one secondary reference if needed.

学习MoonBit或询问入门路径：阅读

references/question-routing.md

和

references/source-map.md

。

询问“MoonBit是否支持X？”、API可用性或快速能力类问题：先阅读
```
references/answer-shapes.md
```
。仅当快速指南未涵盖相关概念或用户要求更全面的对比时，才加载
```
references/capabilities-faq.md
```
。若涉及具体API，需使用
```
references/lookup-recipes.md
```
。
有Go、Rust、TypeScript、OCaml或其他语言背景：阅读
```
references/mental-models.md
```
。
编写、评审或重构MoonBit代码：阅读
```
references/idioms.md
```
。
调试编译器输出、
```
moon
```
命令输出、包错误、后端错误或带有
```
E####
```
代码的诊断信息：阅读
```
references/diagnostics-playbook.md
```
及
```
references/lookup-recipes.md
```
中的相关指南。
设置模块、包、工作区、测试、文档、覆盖率或构建目标：阅读
```
references/toolchain-map.md
```
。
在官方文档、mooncakes API文档、入门教程、示例、错误代码文档或本地项目检查之间进行选择：阅读
```
references/source-map.md
```
。

对于跨多个领域的任务，先阅读最具体的参考文件，若有需要再阅读一个次要参考文件。

Missing-layer checklist

缺失知识层级检查表

Before answering, decide whether the unknown is most likely:

language semantics
MoonBit idiom or style
toolchain behavior
package, dependency, or standard-library API
backend limitation or target-specific behavior
official docs, examples, or error-code reference
project-local convention

State uncertainty briefly when it matters, but do not stop at uncertainty if a recipe can resolve it. For concrete code work, prefer a narrow validation command such as

moon check

moon test

, or

moon build

with the relevant

--target

在给出答案前，需判断未知内容最可能属于以下哪一类：

语言语义
MoonBit惯用写法或风格
工具链行为
包、依赖或标准库API
后端限制或特定目标的行为
官方文档、示例或错误代码参考
本地项目约定

当不确定性对答案有影响时，需简要说明，但若有指南可解决该不确定性，则无需停留在不确定状态。对于具体代码工作，优先使用精准的验证命令，如

moon check

、

moon test

或带有相关

--target

参数的

moon build

。

Boundaries

边界限制

Do not pretend this skill contains the full language specification.
Do not provide exact standard-library signatures unless they were verified.
Do not use this skill for maintaining the
```
moonbit-docs
```
repository itself; use the repo maintainer skill for docs, translation, Sphinx, or example maintenance workflows.
Keep answers practical: show the next source to check, the likely fix, and the narrow command that would validate it.

切勿声称本技能包含完整的语言规范。
除非已验证，否则切勿提供具体的标准库签名。
切勿使用本技能维护
```
moonbit-docs
```
仓库本身；文档、翻译、Sphinx或示例维护工作需使用仓库维护者技能。
答案需实用：展示下一步需检查的来源、可能的修复方案及可验证该方案的精准命令。