---
title: 可移植 Rust Plugin
description: 创建一个可移植 Rust Plugin，并交付经过验证的 Bundle。
---

普通、可安装的 Agent Tool 使用这条路径。Rust 脚手架把业务行为留在同一份源码
中，由 SDK 派生 Capability Descriptor、Wasm lowering、Process entrypoint 与
package metadata。

## 1. 创建项目

```sh
# 同一源码生成可移植 Wasm 与可信 Native Process
lenso plugin new example.echo

# 只生成 Wasm
lenso plugin new example.echo --runtime wasm

# 只生成可信 Process
lenso plugin new example.echo --runtime process
```

默认 Multi-output 项目同时满足可移植性与原生进程兼容性。Process Plugin 拥有普通
本地进程权限，不是 Sandbox。

```text
example.echo/
├── Cargo.toml
├── Cargo.lock
└── src/
    ├── lib.rs     # 业务行为
    └── main.rs    # multi/process 项目生成的 Process entrypoint
```

该脚手架有意保持狭窄：它只创建 Agent Tool Provider，并不是任意 Capability
provider、有状态 Plugin、Web UI 或 Bun 项目的通用生成器。

## 2. 实现行为

初始脚手架使用公共 Macro，不要求手写 Adapter Protocol：

```rust title="src/lib.rs"
use lenso_agent_tool_sdk::prelude::*;
use schemars::JsonSchema;

#[derive(Debug, serde::Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
struct Arguments {
    text: String,
}

#[lenso::plugin]
#[derive(Clone, Copy, Debug, Default)]
struct Plugin;

#[lenso_agent_tool_sdk::tool_provider]
impl Plugin {
    #[tool(name = "example.echo", description = "Echo text.")]
    fn execute(arguments: Arguments) -> Result<ExecuteResponse, ExecuteError> {
        Ok(ExecuteResponse {
            content: arguments.text,
            content_type: ContentType::Text,
            metadata_json: "{}".try_into().unwrap(),
        })
    }
}
```

`Arguments` 类型会成为 Tool 的 JSON Schema。预期的非法输入返回
`ExecuteError`；panic 或损坏的运行时边界仍然属于 Runtime Failure。

## 3. 运行开发循环

```sh
lenso plugin check
lenso plugin dev --implementation auto --operation execute --request-json \
  '{"name":"example.echo","arguments_json":"{\"text\":\"hello\"}"}'
lenso plugin dev --watch --operation execute --request-json \
  '{"name":"example.echo","arguments_json":"{\"text\":\"hello\"}"}'
```

`check` 会构建所有声明的实现并检查 Descriptor 一致性。`dev` 会跨越真实 Adapter
边界，并不会把直接调用 Rust 函数当作测试捷径。`--watch` 在修改后重新构建，
并再次运行同一个请求。

需要显式比较输出时，使用 `--implementation wasm`、`process` 或 `all`。

## 4. 打包 Release

```sh
lenso plugin pack
```

`pack` 构建 Release Artifact，要求所有实现暴露相同 Contract，在 `dist/` 下写出
一个不可变 `.lenso-plugin` 归档，再通过安装时使用的 verifier 重新打开这些字节。

通过[向 App 添加 Plugin](/docs/zh/core/plugin-composition)安装生成的 Bundle。其他
Capability 角色应先定义 Contract，再使用 [Linked Rust Plugin](/docs/zh/core/linked-rust-plugin)
路径或已支持的强类型 SDK。

需要两个同类 Capability 的独立 Provider，或有状态构造与清理时，继续阅读
[命名依赖](/docs/zh/core/named-dependencies)和[document-sync 完整示例](/docs/zh/core/document-sync)。