#moonai

当前状态：早期 alpha。1.0.0 之前 API 可能发生变化。当前版本支持 native 目标、主流文本/媒体模型服务商、MCP 客户端，以及面向 OpenCode、Pi、DeepAgents 的 Harness 运行时适配。

#当前阶段

• 提供模型服务商无关的文本、embedding、图片、视频、语音、转录、翻译、realtime、 Files 与 Skills 模型/服务契约。
• 提供 generate_text、stream_text、generate_object、embed、 embed_many、媒体生成、上传、缓冲转录与实时 stream_transcribe 标准层 API。
• generate_text 与 stream_text 共享多步骤工具执行，支持 prepare_step 模型/消息/参数覆盖、工具筛选与排序、停止条件、provider deferred result 与 sandbox-aware 动态描述和 experimental tool caller 路由。
• 通过 JSON 和 SSE 实现可复用的 Open Responses 协议层，并在其上提供独立的官方 OpenAI Responses 模型与 options 层。
• 通过 JSON 和 SSE 实现 OpenAI-compatible Chat Completions，并支持 embedding、legacy completion 和图片生成。
• 通过 JSON 实现 Anthropic Messages 非流式调用，并通过 SSE 实现流式调用，包括 thinking 和 tool_use 内容块。
• 支持 OpenAI 缓冲音频转录，以及基于公共 AudioStream 契约的 Realtime Whisper 实时转录。
• 支持 ByteDance ModelArk 的 Seedream 图片和 Seedance 异步视频生成，以及 Moonshot AI Chat Completions、思考控制和结构化输出。
• 支持 MCP 的 Streamable HTTP、SSE 与 stdio transport、OAuth 发现、工具、资源、prompt、 completion 和 MCP Apps 资源。
• 支持 Harness V1 会话、生命周期状态、Sandbox、工具审批、诊断、WebSocket 与持久 stdio NDJSON bridge，并提供 OpenCode、Pi 和 DeepAgents 适配器。
• 支持文本、URL/base64 图片、音频和文件输入；适配器不支持的媒体类型会明确报错。
• 统一文本、推理、工具调用、结束原因、错误、用量事件，并可选择透传服务商原始事件。
• 支持交错、并行 tool call delta 的增量组装。
• 支持标准采样与推理强度参数、JSON Schema 响应格式、带命名空间的 provider options，以及可覆盖 provider 默认值的调用级 HTTP headers。
• 支持原始请求/响应诊断、provider metadata、typed warnings、可配置重试和协作式取消。
• 为每类核心模型提供确定性 mock、golden SSE fixture 和本地 HTTP 集成测试。

#包结构

#Harness、MCP 与 CLI bridge

///|
let transport = @harness.HarnessV1BridgeTransportConfig::stdio(
  @harness.HarnessV1StdioConfig::new(
    command="your-harness-bridge",
    args=["--stdio"],
  ),
)

///|
let agent = @harness_opencode.createOpenCode(
  @harness_opencode.OpenCodeHarnessSettings::new(transport=transport),
)

#安装

moon add QuietlyChan/moonai

import {
  "QuietlyChan/moonai/ai",
  "QuietlyChan/moonai/provider",
  "QuietlyChan/moonai/openai",
}

#非流式文本生成

///|
let model = @openai.openai(
  "gpt-4.1-mini",
  api_key=@env.get_env_var("OPENAI_API_KEY").unwrap(),
)

///|
let result = @ai.generate_text(
  model,
  prompt="用三句话解释 MoonBit。",
  instructions=@ai.Instructions::text("回答要简洁。"),
)

#流式文本生成

///|
let model = @openai.openai(
  "gpt-4.1-mini",
  api_key=@env.get_env_var("OPENAI_API_KEY").unwrap(),
)

///|
let result = @ai.stream_text(
  model,
  prompt="Explain MoonBit in three sentences.",
  on_event=event => {
    match event {
      @provider.V4TextDelta(delta~, ..) => @stdio.stdout.write(delta)
      _ => ()
    }
  },
)

#多步骤工具与 Sandbox

#诊断、重试与取消

///|
let cancellation = @provider.CancellationToken::new()

///|
let retry_policy = @provider.RetryPolicy::new(
  max_retries=3,
  initial_delay_ms=200,
)

///|
let result = @ai.generate_text(
  model,
  prompt="解释 MoonBit。",
  retry_policy~,
  cancellation_token=cancellation,
)

///|
let chat_model = @openai.openai_chat(
  "gpt-4.1-mini",
  api_key=@env.get_env_var("OPENAI_API_KEY").unwrap(),
)

///|
let provider = @openai.create_openai(
  api_key~,
  organization="org-example",
  project="proj-example",
)

#Anthropic Messages

///|
let model = @anthropic.anthropic(
  "claude-sonnet-4-20250514",
  api_key=@env.get_env_var("ANTHROPIC_API_KEY").unwrap(),
)

///|
let response = @ai.stream_text(
  model,
  prompt="用三句话解释 MoonBit。",
  provider_options={
    "anthropic": {
      "thinking": { "type": "enabled", "budgetTokens": 4096 },
    },
  },
  on_event=event => {
    match event {
      @provider.V4TextDelta(delta~, ..) => @stdio.stdout.write(delta)
      @provider.V4ReasoningDelta(delta~, ..) => ()
      _ => ()
    }
  },
)

///|
let advisor = @anthropic.advisor_20260301(
  model="claude-opus-4-8",
  max_uses=3,
  caching=@anthropic.AnthropicAdvisorCaching::new(
    ttl=@anthropic.AnthropicCacheOneHour,
  ),
)

///|
let result = @ai.generate_text(
  model,
  prompt="实现迁移，并让 advisor 审查计划。",
  tools=@ai.tool_set([("advisor", advisor)]),
)

#OpenAI-compatible 服务商

///|
let deepseek = @openai_compatible.openai_compatible(
  provider_name="deepseek",
  base_url="https://api.deepseek.com",
  model_id="deepseek-chat",
  api_key~,
  preserve_reasoning=true,
)

///|
let response = @ai.stream_text(
  deepseek,
  prompt="What is MoonBit?",
  reasoning_effort=@provider.High,
  on_event=event => {
    match event {
      @provider.V4TextDelta(delta~, ..) => @stdio.stdout.write(delta)
      _ => ()
    }
  },
)

///|
let provider = @openai_compatible.create_openai_compatible(
  provider_name="example-gateway",
  base_url="https://example.com/v1",
  api_key~,
  query_params={ "api-version": "2026-08" },
  supports_structured_outputs=true,
)

#Open Responses 服务商

///|
let provider = @open_responses.create_open_responses(
  provider_name="my-provider",
  url="https://example.com/v1/responses",
  api_key~,
)

///|
let model = provider.language_model("my-model")

#Provider options 与推理强度

///|
let model = @openai_compatible.openai_compatible(
  provider_name="example-gateway",
  base_url="https://example.com/v1",
  model_id="example-model",
  api_key~,
)

///|
let response = @ai.generate_text(
  model,
  prompt="解释其中的取舍。",
  provider_options={
    "exampleGateway": {
      "reasoningEffort": "high",
      "user": "user-1",
    },
  },
)

#结构化输出与多模态输入

///|
let object = @ai.generate_object(
  model,
  {
    "type": "object",
    "properties": { "answer": { "type": "string" } },
    "required": ["answer"],
  },
  prompt="请使用 JSON 回答。",
  name="answer",
)

///|
let response = @ai.generate_text(
  model,
  messages=[
    @ai.ModelMessage::user_parts([
      @ai.ModelContentPart::text("描述这张图片。"),
      @ai.ModelContentPart::image_url("https://example.com/moon.png"),
    ]),
  ],
)

#Embedding、Completion 和图片

///|
let provider = @openai.create_openai(api_key~)

///|
let vector = @ai.embed(
  provider.embedding("text-embedding-3-small"),
  "MoonBit",
)

///|
let completion = @ai.generate_text(
  provider.completion("gpt-3.5-turbo-instruct"),
  prompt="MoonBit 是",
)

///|
let images = @ai.generate_image(
  provider.image("gpt-image-1"),
  "一枚精确的 MoonBit 语言标志",
  n=2,
  size="1024x1024",
)

#设计方向

#示例

moon run examples/basic_chat -- "Explain MoonAI briefly."
moon run examples/tool_calling -- "Calculate 42 * 8."
moon run examples/web_agent/backend

#开发

moon info
moon fmt --check
moon check
moon test

OPENAI_API_KEY=... moon run src/cmd/main

#许可证