Noorle — AI Agent Runtime & MCP Gateways

Noorle 插件示例

一套全面的 WebAssembly 插件示例，展示了使用 WebAssembly Component Model 和 WASI 0.2 构建 Noorle 平台插件的真实应用模式。导出的函数会自动成为 MCP 工具，无需任何配置。

• 🧩 插件开发文档
• 🔌 MCP 网关的工作方式
• 🚀 五分钟快速入门
• ⌨️ Noorle CLI

🎯 本仓库提供的内容

本仓库提供了可运行的 Noorle 插件示例，展示了以下内容：

• HTTP API 集成 - 使用 OpenWeatherMap、NewsAPI、arXiv 和 Exchange Rate API 的真实应用示例
• 多语言支持 - 使用 Rust、Go、Python、JavaScript 和 TypeScript 实现
• WASI 0.2 模式 - 使用现代 WebAssembly System Interface 实现安全、沙箱化执行
• Component Model - 使用 WIT 构建类型安全、与语言无关的插件接口
• 生产模式 - 错误处理、环境配置和测试策略

🛠️ 展示的技术

• WebAssembly Component Model - 新一代 WASM 模块组合
• WASI Preview 2 - 用于访问网络、文件系统和环境的安全系统接口
• WIT（WebAssembly Interface Types） - 与语言无关的接口定义
• 跨语言编译 - TinyGo、ComponentizeJS、componentize-py 和 cargo-component

📚 适用对象

• 为 Noorle 平台构建插件的开发者
• 学习 WebAssembly Component Model 最佳实践
• 了解 WASI 0.2 HTTP 客户端模式
• 探索跨语言 WASM 开发
• 构建安全、沙箱化的 API 集成

每个示例都包含详尽的文档、本地测试说明和可用于生产环境的代码模式。

可用示例

🌦️ 天气插件

从 OpenWeatherMap API 获取实时天气信息。

提供 5 种语言版本：

• Rust - 使用 waki HTTP 客户端实现高性能，并演示如何返回复杂的非基本类型记录
• Go - 使用 WASI HTTP 绑定进行 TinyGo 编译
• Python - 使用 componentize-py 直接调用 WASI 绑定
• JavaScript - 使用 ComponentizeJS 调用原生 fetch() API
• TypeScript - 提供完整 IDE 支持的类型安全开发

功能：

• 获取任意城市的当前天气数据
• 支持公制和英制单位
• 通过环境变量安全管理 API 密钥
• 妥善处理网络故障
• 返回包含嵌套字段（温度、风力、天气状况）的复杂天气响应

📰 新闻插件

使用 NewsAPI.org 搜索全球新闻文章和突发新闻标题。

提供以下版本：

• Rust - 集成 NewsAPI.org 并使用结构化记录类型

功能：

• 按关键词或主题搜索新闻文章
• 返回结构化文章数据（标题、描述、URL、来源）
• 演示包含嵌套结构的复杂记录类型
• 处理速率限制和身份验证错误
• 通过环境变量安全管理 API 密钥

💱 汇率插件

提供实时货币兑换和汇率信息。

提供以下版本：

• Rust - 使用多个 API 端点并支持故障回退

功能：

• 获取任意基础货币的当前汇率
• 转换不同货币之间的金额
• 列出所有支持的货币
• 主 API 失败时自动回退到备用 API
• 无需 API 密钥——使用免费的货币数据源

✈️ Amadeus 航班插件

使用 Amadeus API 搜索航班报价和旅行信息。

提供版本：

• Go - TinyGo 实现，演示复杂非基本记录类型输入

功能：

• 搜索城市之间的航班报价
• 接受复杂的搜索参数（出发地、目的地、日期、乘客）
• 演示如何在 WASI 组件中处理嵌套输入结构
• 通过环境变量安全管理 API 凭据
• 返回详细的航班信息，包括价格和航段

📚 ArXiv 插件

从 arXiv 仓库搜索和下载学术论文。

提供版本：

• Rust - 使用 Atom/RSS 源解析并下载 PDF

功能：

• 在 arXiv 上搜索学术论文
• 直接下载论文 PDF
• 提供结构化元数据，包括作者、摘要和分类
• 使用 feed-rs 高效解析信息源

技术栈

WebAssembly 组件模型

所有插件均使用 WebAssembly 组件模型和 WASI 0.2，提供：

• 安全性：基于能力的沙箱机制，支持细粒度权限
• 可移植性：可在任何 WASI 0.2 运行时（wasmtime、wasmer、浏览器）上运行
• 组合性：插件可在组件间导入和导出接口
• 语言无关：WIT 接口支持无缝互操作

特定语言工具链

Rust

• 使用 wasm32-wasip2 目标，生成优化的 WASM 输出
• 使用 wit-bindgen 集成组件模型
• 使用 waki 作为 WASI 原生 HTTP 客户端
• 以零成本抽象和最小二进制文件体积为特点

Go

• 使用 TinyGo 编译器生成高效的 WASM 二进制文件
• 使用 wit-bindgen-go 提供类型安全的绑定
• 直接访问 WASI HTTP 接口
• 采用适用于 WASM 的 Go 惯用模式

Python

• 使用 componentize-py 将 Python 编译为 WASM
• 直接使用 WASI HTTP 绑定，无需外部库
• 使用内置库原生处理 JSON
• 使用数据类和枚举确保类型安全

JavaScript

• 使用带有 StarlingMonkey 运行时的 ComponentizeJS
• 基于 SpiderMonkey（Firefox 的 JS 引擎）
• 支持原生 fetch() API
• 支持 ES 模块和现代 JavaScript 特性

TypeScript

• 提供完整的类型安全和编译时检查
• 采用两阶段编译：TypeScript → JavaScript → WASM
• 支持 IDE 智能感知和自动补全
• 提供类型安全的 JSON 序列化

入门指南

前置条件

安装 Noorle CLI

安装 Noorle CLI 以构建和部署插件：

选项 1：快速安装（推荐）

curl -L cli.noorle.dev | sh

选项 2：下载特定平台的二进制文件 从 GitHub Releases 下载适用于你平台的最新版本。

详细文档请参阅 CLI 参考。

WebAssembly 工具集

为简化开发体验，Noorle 插件使用一套标准的 WASM 工具。运行 noorle plugin prepare 时会自动安装这些工具：

• wasmtime - 用于本地测试的 WebAssembly 运行时
• wkg - 用于依赖管理的 WIT 软件包管理器
• wasm-tools - WebAssembly 组件实用工具
• Rust 工具链 - 上述工具的必需组件（这些工具由 Rust 构建）

所有语言模板中的构建脚本都会使用这些工具，确保生成一致的 WASM 组件。

快速入门

1. 克隆仓库：

git clone https://github.com/noorle/plugin-examples
cd plugin-examples

2. 选择一个示例和语言：

cd rust/weather

3. 准备开发环境：

# Install required WASM tools (one-time setup)
noorle plugin prepare

# Or check if tools are already installed
noorle plugin prepare --check

prepare 命令会运行模板的 prepare.sh 脚本，该脚本会：

• 检查所需的开发工具
• 安装缺失的依赖项（需征得你的许可）
• 配置 WASM 开发环境
• 确保所有模板使用一致的工具

4. 配置环境变量（如有需要）：

cp .env.example .env
# Add your API key to .env

5. 构建插件：

noorle plugin build

此命令会运行模板的 build.sh 脚本，该脚本会：

• 将代码编译为 WebAssembly
• 生成 Component Model 绑定
• 生成 dist/plugin.wasm
• 创建用于部署的 .npack 归档文件

6. 本地测试：

# Example for rust weather plugin (Rust version)
wasmtime run --wasi http --env OPENWEATHER_API_KEY=your_key \
  --invoke 'check-weather("Austin", metric)' dist/plugin.wasm

7. 部署到 Noorle：

# Authenticate first
noorle login

# Deploy the plugin
noorle plugin deploy

# Or build and deploy in one step
noorle plugin publish

Noorle CLI 工作流

Noorle CLI 为插件开发提供了精简的工作流：

创建新插件

# List available templates
noorle plugin list-templates

# Create from template
noorle plugin init my-plugin --template rust

# Interactive template selection
noorle plugin init my-plugin

开发命令

# Check/install dependencies
noorle plugin prepare         # Interactive installation
noorle plugin prepare --check  # Check only
noorle plugin prepare --ci     # Non-interactive for CI/CD

# Build plugin
noorle plugin build           # Runs build.sh, creates WASM

# Validate configuration
noorle plugin validate noorle.yaml

# Create deployment package
noorle plugin pack            # Creates .npack archive

部署命令

# Authentication
noorle login                  # OAuth device flow
noorle logout                 # Clear tokens

# Deploy to platform
noorle plugin deploy          # Deploy existing .npack
noorle plugin publish         # Build + deploy

项目结构

每个插件都遵循一致的结构：

language/plugin-name/
├── src/ or app.*        # Main implementation
├── wit/
│   └── world.wit        # Component interface definition
├── noorle.yaml          # Plugin permissions and config
├── prepare.sh           # Dependency setup script
├── build.sh             # Build script
├── .env.example         # Environment template
├── README.md            # Detailed documentation
└── dist/
    ├── plugin.wasm      # Compiled WASM component
    └── *.npack          # Deployment archive

关键文件说明

• prepare.sh：检查并安装开发工具（wasmtime、wkg、wasm-tools）
• build.sh：特定语言的构建脚本，用于生成 WASM 输出
• world.wit：插件 API 的 WebAssembly Interface Types 定义
• noorle.yaml：指定权限、环境变量和元数据

展示的关键概念

HTTP 客户端集成

• 从沙盒化的 WASM 组件发起外部 API 调用
• 特定语言的 HTTP 客户端模式
• 超时处理和连接管理
• 请求/响应流式处理

环境配置

• 安全管理 API 密钥
• 通过环境变量进行配置
• noorle.yaml 中基于能力的权限

错误处理

• 处理网络故障的稳健模式
• API 错误处理
• Result 类型和错误传播
• 使用回退机制实现平稳降级

JSON 处理

• 解析和序列化外部 API 数据
• 类型安全的数据结构
• 处理可选字段和 null 值

组件接口设计

• 清晰的 WIT 接口定义
• 语言与 Component Model 之间的类型映射
• 导出带有文档说明参数的函数
• 使用 Result 类型处理错误

学习路径

1. 从 Weather Plugin 开始：通过复杂的记录类型学习 HTTP 集成和基本模式
2. 尝试 News Plugin：了解 NewsAPI 集成、速率限制和结构化数据处理
3. 探索 Exchange Rate：了解回退策略和数据缓存
4. 研究 ArXiv Plugin：掌握 Feed 解析和二进制文件处理
5. 比较不同语言：了解不同语言如何解决同一问题

最佳实践

安全性

• 切勿将 API 密钥或机密硬编码
• 使用环境变量进行配置
• 在 noorle.yaml 中指定最小权限
• 验证所有外部数据

性能

• 根据使用场景选择合适的语言
• 优化二进制文件大小（尤其是使用 TinyGo/Rust 时）
• 在适当的场景实现缓存
• 对大型响应使用流式处理

错误处理

• 始终返回 Result 类型
• 提供有意义的错误消息
• 为暂时性故障实现重试逻辑
• 为关键服务添加回退机制

开发

• 编写全面的测试
• 为所有导出函数编写文档
• 遵循特定语言的惯用写法
• 在适用时使用类型安全机制

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

添加新示例

1. 选择一个实用的使用场景
2. 至少使用一种语言实现
3. 附上全面的 README
4. 添加测试和文档
5. 遵循现有模式和结构

资源

• Noorle CLI 参考
• WebAssembly 组件模型
• WASI 0.2 规范
• WIT 接口类型

许可证

MIT 许可证及 Noorle 平台附加条款

版权所有 (c) 2024 Noorle

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或出售本软件副本的权利，以及允许获得本软件的人这样做的权利，但须符合以下条件：

本版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

Noorle 平台集成附加条款：

• 这些示例经过优化，并获得 Noorle 平台的官方支持
• 部署到 Noorle 时，插件必须遵守 Noorle 的服务条款
• Noorle 团队可以将这些示例用于平台文档和推广

本软件按“原样”提供，不附带任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，无论是基于合同、侵权还是其他原因，对于因本软件或本软件的使用或其他交易而产生、引起或与之相关的任何索赔、损害或其他责任，作者或版权持有人均不承担责任。

支持

• GitHub 问题
• Noorle 文档