欢迎来到 AI Agent × Web3 的交汇点！

这篇教程专门为从未用过 Moss 去进行开发的同学设计。我们将一起使用 Moss 的软件开发工具包（SDK），从零到一编写一个能在本地运行的 TypeScript 脚本。

这个小 Demo 会模拟一个 AI 智能体（Agent）接收到用户一句话指令（例如：“帮我把 1 个 MON 存为 WMON 吧”）后，如何在完全不暴露私钥、不花一分钱本金的情况下，安全地在真实的 Monad 主网分叉状态上完成“寻找路径、构建交易、链上沙盒演练、安全对账”的完整闭环。

0. 环境准备

在开始前，请确保你的电脑上已安装了以下基础环境：

• Node.js >= 22（Moss 项目使用了较新的现代特性，需要 Node 22 或以上版本）
• pnpm 包管理工具（如果未安装，可运行 npm install -g pnpm 安装）

---

1. 快速创建项目并安装依赖

首先，我们在本地建立一个全新的空白项目，并引入 Moss 的核心软件包。

在你的终端中运行以下命令：

# 1. 创建并进入项目目录
mkdir my-first-moss-agent && cd my-first-moss-agent

# 2. 初始化项目
pnpm init

# 3. 安装 Moss 核心开发包与 TypeScript 运行环境
pnpm add @themoss/core @themoss/simulator @themoss/system @themoss/erc
pnpm add -D typescript @types/node tsx

文件目录结构

在项目根目录下创建一个 src 文件夹，我们所有的代码都写在 src/agent.ts 中：

my-first-moss-agent/
├── package.json
├── node_modules/
└── src/
    └── agent.ts

2. 核心概念秒懂

在使用 Moss 开发前，我们需要理解它的 3 个核心角色：

• Runtime（运行时）：它连接真实的区块链网络（例如 Monad 主网的 RPC）。所有的链上模拟、状态查询都通过它发起。
• Registry（能力货架）：AI 智能体直接交互的中心。我们把各种智能合约适配器（如 ERC20 转账模块、WMON 包装模块）注册进货架，Agent 就可以在这里查寻和调用它们。
• Simulator（模拟器）：安全防线。负责在沙盒中回放交易的底层痕迹（Trace），验证钱有没有被多扣，授权有没有超标。

---

3. 编写你的第一个 Agent 脚本

新建并打开 src/agent.ts 文件，将以下代码完整粘贴进去。每一行关键代码我们都做好了保姆级的中文字释：

import { Registry } from "@themoss/core";
import { ercManifest } from "@themoss/erc";
import { createTraceSimulator } from "@themoss/simulator";
import { monadRuntime, systemManifest } from "@themoss/system";

// 1. 初始化 Moss 运行时（这里指向 Monad 主网的公共节点，仅用于模拟和查询）
const runtime = monadRuntime({
  rpcUrl: "https://rpc.monad.xyz" 
});

// 2. 创建能力注册机（货架）
const registry = new Registry(runtime);

// 3. 将 Moss 官方提供的系统内置适配器（包含 WMON）、以及通用的代币（ERC20）模块上架
for (const manifest of [systemManifest, ercManifest]) {
  registry.use(manifest);
}

// 4. 初始化链上 Trace 模拟器
const simulator = createTraceSimulator(runtime);

// ==========================================
// 核心 Agent 智能体函数
// ==========================================
async function runAgent(userPrompt: string, walletAddress: string) {
  console.log(`🤖 Agent 收到用户原始指令: "${userPrompt}"`);

  // 第一步：自然语言解析（本 Demo 使用轻量规则模拟，如果是生产环境，可将 prompt 传给 OpenAI/Claude 进行意图拆解）
  let actionVerb = "";
  let amountStr = "";

  if (userPrompt.includes("包装") || userPrompt.includes("wrap")) {
    actionVerb = "wrap";
    // 简单提取用户说出的数字
    const match = userPrompt.match(/\d+(\.\d+)?/);
    amountStr = match ? match[0] : "1.0";
  } else {
    console.log("❌ Agent 无法理解此操作，为了资产安全，拒绝动作。");
    return;
  }

  console.log(`🔍 Agent 意图拆解成功 -> 动作: ${actionVerb}, 金额: ${amountStr}`);

  // 第二步：发现能力 (Discover)
  // Agent 在货架中寻找谁能做 "wrap" 动作
  const capabilities = registry.discover({ verb: actionVerb });
  if (capabilities.length === 0) {
    console.log(`❌ 未找到可以执行 "${actionVerb}" 的协议适配器！`);
    return;
  }
  
  // 选定第一个匹配的提供者（例如系统默认的 wmon 协议）
  const target = capabilities[0];
  console.log(`🎯 匹配到协议提供方 -> 协议: ${target.protocol}, 方法: ${target.method}`);

  // 第三步：加载参数规范 (Load)
  // 这一步能让 Agent 知道需要传什么参数（比如 token 符号、精确数字，避免 AI 瞎写参数）
  const contractStub = registry.load([target]);
  console.log("📝 协议契约加载完毕，正在为您组装未签名的交易...");

  // 第四步：构建交易计划 (Action)
  // 此时 Moss 会将人类懂的 1.0 换算成链上的 18 位大数，并组装成 Plan
  const plan = await registry.action(target.protocol, target.method, walletAddress, {
    amount: amountStr,
  });

  console.log(`🚀 交易计划组装成功！`);
  console.log(`   - 意图说明: ${plan.intent}`);
  console.log(`   - 期望变动: 将最多扣除您 ${plan.expects.out.amountMax} 个 MON`);

  // 第五步：终极安全防御门——沙盒演练 (Simulate)
  // 在真实链上快照中回放这笔交易，确认资产实际变动是否与“期望变动”完全一致
  console.log("🛡️ 正在将交易送往链上仿真沙盒进行预演对账...");
  const { results, halted } = await simulator.simulate([plan]);

  if (halted) {
    console.error(`❌ 仿真回放中断！原因: ${halted.reason}`);
    return;
  }

  // 第六步：安全审查与送审
  const result = results[0];
  const isSafe = result.warnings.length === 0;

  if (isSafe) {
    console.log("\n=============================================");
    console.log("✅【安全审计通过】模拟运行完全正确！");
    console.log("   实际发生的资金流转为:", JSON.stringify(result.effects, null, 2));
    console.log("   [安全提示] 您现在可以放心地把以下交易数据送往您的钱包（Metamask/本地私钥脚本）进行签名了：");
    console.log("   待签名交易数据 (Plan.txs):", JSON.stringify(plan.txs, null, 2));
    console.log("=============================================\n");
  } else {
    console.log("\n=============================================");
    console.log("🚨【高警拦截】模拟中发现危险的非预期账目变动！");
    console.log("   警告码 (Warnings):", result.warnings);
    console.log("   已自动为您强行熔断拦截，切勿进行钱包签名操作！");
    console.log("=============================================\n");
  }
}

// ==========================================
// 运行测试
// ==========================================
// 使用一个公开的测试测试地址（不需要提供任何私钥，因为模拟是不消耗真实资金的！）
const TEST_WALLET = "0xCcCccCCCcCCcccCcCccccCcCCCCcccccCcCCcCcC";

async function start() {
  // 模拟一次正确的操作
  await runAgent("帮我把 0.5 个 MON 包装成 WMON", TEST_WALLET);
}

start().catch((err) => {
  console.error("运行时发生错误:", err);
});

4. 运行与结果验证

在命令行中使用 tsx 命令直接编译并运行我们刚写的代码：

pnpm exec tsx src/agent.ts

控制台预期输出：

如果网络畅通，你会看到如下的完整生命周期输出：

🤖 Agent 收到用户原始指令: "帮我把 0.5 个 MON 包装成 WMON"
🔍 Agent 意图拆解成功 -> 动作: wrap, 金额: 0.5
🎯 匹配到协议提供方 -> 协议: wmon, 方法: wrap
📝 协议契约加载完毕，正在为您组装未签名的交易...
🚀 交易计划组装成功！
   - 意图说明: Wrap 0.5 MON into WMON
   - 期望变动: 将最多扣除您 0.5 个 MON
🛡️ 正在将交易送往链上仿真沙盒进行预演对账...

=============================================
✅【安全审计通过】模拟运行完全正确！
   实际发生的资金流转为: [
     {
       "type": "asset",
       "asset": "MON",
       "direction": "out",
       "amount": "0.5",
       "holder": "0xCcCccCCCcCCcccCcCccccCcCCCCcccccCcCCcCcC",
       "recipient": "0x30a23C4C165bC77443D82431417a85be6041b315"
     },
     {
       "type": "asset",
       "asset": "WMON",
       "direction": "in",
       "amount": "0.5",
       "holder": "0xCcCccCCCcCCcccCcCccccCcCCCCcccccCcCCcCcC",
       "recipient": "0xCcCccCCCcCCcccCcCccccCcCCCCcccccCcCCcCcC"
     }
   ]
   [安全提示] 您现在可以放心地把以下交易数据送往您的钱包（Metamask/本地私钥脚本）进行签名了：
   待签名交易数据 (Plan.txs): [{"to":"0x30a23C4C165bC77443D82431417a85be6041b315","value":"500000000000000000","data":"0xd0e30db0"}]
=============================================

5. 进阶：如何将这个 Demo 对接真正的 AI 大模型（LLM）？

在这个 Demo 中，我们使用了简单的正则表达式来解析用户的自然语言。在生产环境中，这应该交由大语言模型（LLM）的**工具调用（Tool Calling）**功能来实现。

以下是实现对接大模型的推荐逻辑框图：

 用户输入："我想拿 1 个 WMON 换成 USDC"
                 │
                 ▼
 1. 询问 LLM (传入用户 Prompt + Moss 提供的四个工具 discover/load/action/simulate 作为 Agent Tool 描述)
                 │
                 ▼
 2. LLM 决定调用工具：
    👉 首先调用 `discover({ verb: "swap" })` -> 得到 kuru 协议
    👉 接着调用 `load` -> 获取 kuru 协议的参数字段 (tokenIn, tokenOut, amount)
    👉 最终 LLM 决定填入参数，调用 `action` -> 获得 Plan
                 │
                 ▼
 3. LLM 将 Plan 的内容传给 `simulate` 工具进行沙盒验证。
                 │
                 ▼
 4. 只有当 `simulate` 报告 warnings 数组长度为 0，并且 LLM 确认实际划转方向与用户要求对齐后，Agent 才会交出交易包由用户钱包签名。

恭喜你！

你已经成功完成了自己的第一个 Moss Agent Demo 开发！

通过 Moss，你不需要接触一行 ABI，也不需要为复杂的交易细节抓耳挠腮。Moss 为 AI Agent 扫清了链上开发的障碍，同时也为你的 Web3 资产树立了一道牢不可破的安全防线。