sui-sdks

Sui SDK

MCP 工具： 如果你的环境支持，也请查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），以获取最新答案。使用它来核实信息，以及查找这些参考文件未涵盖的细节。

大多数 AI Agent 对 Sui SDK 的回答都令人困惑、过时或混淆不清。本技能可解决三种最常见的问题：

1. 把社区 SDK 当作官方 SDK 推荐。 Mysten Labs 仅维护两个 SDK：TypeScript（@mysten/sui）和 Rust（sui-rust-sdk 系列 crate）。其他 SDK 均由社区维护。
2. 混淆 TypeScript SDK 的不同代际。 旧版 @mysten/sui.js 包在 v1.0 时更名为 @mysten/sui。v2 客户端 API（client.core.*、用 include 替代 show*、用 SuiGrpcClient 替代 SuiClient）与 v1 不同。
3. 未使用已安装的大模型文档。 每个 @mysten/* 包都会将 docs/llms-index.md 和特定主题的 Markdown 文件附带到 node_modules。Agent 在回答前应先阅读这些文档；它们保证与已安装的版本一致。

本技能中的所有模式均来源于：

• https://docs.sui.io/references/sui-sdks（权威 SDK 清单）
• https://sdk.mystenlabs.com/sui（TypeScript SDK 参考）
• https://sdk.mystenlabs.com/sui/llm-docs（随包附带的大模型文档规范）
• https://github.com/MystenLabs/sui-rust-sdk（Rust SDK 源码）
• https://docs.rs/sui-transaction-builder（Rust PTB 构建器）

如果不确定某个 SDK 中的具体 API，请查阅相关文档页面，不要根据其他 SDK 的接口进行推断。

---

参考文件

typescript — TypeScript SDK（@mysten/sui v2）

路径： typescript.md 适用场景： 编写、审查或迁移导入 @mysten/sui 的 TypeScript/JavaScript 代码；在 TS 中构建 PTB；选择使用 SuiGrpcClient 还是 SuiGraphQLClient；使用 v2 Core API；或从 SDK v1（@mysten/sui.js）迁移。 涵盖内容： 安装、导入、客户端类及其适用场景、v2 Core API、PTB 构建、纯值/对象输入、余额和 Coin 意图、执行与状态检查、waitForTransaction、密钥对、离线构建、赞助交易、v1→v2 迁移表，以及用于 kiosk/suins/deepbook/walrus/seal/zksend 的 $extend 模式。

rust — Rust SDK（sui-* crates）

路径： rust.md 适用场景： 编写与 Sui 交互的 Rust 代码，包括 CLI 工具、后端服务、验证器和索引器。也适用于在新的模块化 crate 与单体仓库中的旧版 sui-sdk crate 之间进行选择。 涵盖内容： 五个 crate（sui-sdk-types、sui-crypto、sui-rpc、sui-graphql、sui-transaction-builder）、带端到端示例的 TransactionBuilder API、使用 sui-crypto 签名、来自 sui-rpc 的 gRPC 客户端、与旧版 sui-sdk crate 的关系，以及“intents”功能标志（高级 Coin / Balance 意图）。

community — 社区 SDK（Python、Go、Dart、Kotlin、Swift、Vue）

路径： community.md 适用场景： 用户询问或正在使用非 TS、非 Rust 的 SDK 时。也适用于评估语言选择的风险（维护者响应速度、相较官方 SDK 的功能差距）。 涵盖内容： 各社区 SDK 的代码仓库、维护者、安装方式、支持与不支持的功能、注意事项，以及关于是否使用该 SDK 或通过 FFI 包装器调用 Rust/TS SDK 的建议。

mapping — 跨 SDK 操作映射

路径： mapping.md 适用场景： 将代码从一个 SDK 移植到另一个 SDK、编写多语言参考，或回答“如何在 SDK Y 中执行操作 X”。 涵盖内容： 并排对照表，映射 TS 和 Rust SDK 中约 10 种核心 Sui 操作（构建 PTB、拆分 gas、moveCall、转账、签名并执行、等待、查询对象/自有对象/余额、dry-run），并提供语法对照。

llm-docs — 使用 node_modules 中附带的文档

路径： llm-docs.md 加载时机： Agent 在编写代码前需要权威且与版本匹配的 TypeScript API 文档时。如果 node_modules/@mysten/*/docs/llms-index.md 存在，请务必先查看。 涵盖内容： docs/llms-index.md 约定、哪些 @mysten/* 包附带该文件、如何阅读索引和目标页面，以及如何在项目的 AGENTS.md / CLAUDE.md 中配置它。

路由指南

任务	加载
“我应该使用哪个 SDK？”	（本文件）+ mapping
编写与 Sui 交互的 TS/JS 代码	typescript + llm-docs
编写与 Sui 交互的 Rust 代码	rust
使用 pysui / ksui / suikit / sui-go / mofalabs/sui	community
用户提到 Go / Python / Dart / Kotlin / Swift / Vue（即使只是随口提及，例如“我的团队使用 Go”）	community（始终如此——语言限制优先于性能建议）
跨语言迁移	mapping +（目标 SDK 文件）
从 @mysten/sui.js / SDK v1 迁移	typescript
前端 / React 集成	首先路由至 frontend-apps 技能（涵盖 React hooks、钱包连接、查询模式），然后在此处使用 typescript 构建 Transaction
深入了解 PTB 语义	路由至 ptbs 技能，然后在此处使用特定语言的文件
数据访问模式（gRPC 与 GraphQL 或索引器）	路由至 accessing-data 技能
完整项目设置	所有参考文件（或特定 SDK 文件 + llm-docs）
代码审查	所有参考文件

技能内容

核心概念

• 官方支持的 SDK 有两个。 TypeScript（@mysten/sui）和 Rust（sui-rust-sdk crates）。两者均由 Mysten Labs 维护，并随协议更改同步更新。对于非 Rust 语言中的性能关键路径，可通过 FFI（Foreign Function Interface，外部函数接口）从 Python、Go、Swift 等调用 sui-rust-sdk，让这些语言无需依赖社区封装即可使用官方 SDK。
• 其他所有 SDK 均来自社区。 Python（pysui）、Go（block-vision/sui-go-sdk）、Dart（mofalabs/sui）、Kotlin（mcxross/ksui）、Swift（opendive/suikit）、Vue（SuiFansCN/suiue）。它们通常无法及时跟进协议更新，功能覆盖情况也各不相同。请将其视为尽力维护的项目。
• TS SDK 有两代客户端。 v1 使用 SuiClient + @mysten/sui.js。v2 使用来自 @mysten/sui 的 SuiGrpcClient / SuiJsonRpcClient / SuiGraphQLClient。JSON-RPC 已弃用；新代码默认使用 gRPC。
• Rust SDK 有两代。 新的模块化 crates（sui-sdk-types、sui-crypto、sui-rpc、sui-transaction-builder）是推荐使用的接口。所谓“旧版 Rust SDK”是 sui monorepo 中的单体 sui-sdk crate；它使用 JSON-RPC（已弃用），不建议将其作为新代码的目标。
• 每个 @mysten/* 包都附带适用于 LLM 的文档。 查找 node_modules/@mysten/sui/docs/llms-index.md，并在询问用户澄清 API 之前，先按照其中的指引操作。文档与已安装的版本完全匹配。
• 构建在 SDK 之上的框架。 @mysten/dapp-kit-react（React 钱包集成；Vue / vanilla / Svelte / Web Components 使用 @mysten/dapp-kit-core）、@mysten/kiosk、@mysten/suins、@mysten/deepbook-v3、@mysten/walrus、@mysten/seal、@mysten/zksend、@mysten/enoki——这些都是构建在 @mysten/sui 之上的轻量层。Mysten 扩展通过 v2 client.$extend(...) 模式集成；dApp Kit 则不通过该模式集成（它是 React 框架，而非客户端扩展——参见 frontend-apps 技能）。不带后缀的 @mysten/dapp-kit 包名指的是已弃用、仅支持 JSON-RPC 的前身。

规则

1. 默认使用 TypeScript 或 Rust，但要尊重语言限制。 对于任何新的 Sui 项目，建议使用 TypeScript（@mysten/sui）或 Rust（sui-rust-sdk crates）——除非用户指定了某种语言（Go、Python、Dart、Kotlin、Swift、Vue）或表示“我的团队使用 X”。此时应以 community.md 为准：指出规范的社区 SDK（Go 使用 block-vision/sui-go-sdk，Python 使用 pysui 等），提示其可能过时的风险，并提供通过 FFI 使用 Rust 作为备用方案。如果用户已说明团队使用的语言，不要建议用 TypeScript 或 Rust 替换该语言。 例如，如果用户说“我的团队使用 Go”，就不要建议改用 TypeScript——应推荐 Go 社区 SDK 和／或通过 FFI 使用 Rust。
2. 对于 TypeScript，始终使用 @mysten/sui，绝不使用 @mysten/sui.js。 带 .js 后缀的软件包已停留在 v1，不会再收到更新。使用该软件包的旧代码应迁移。
3. 对于 TypeScript v2，默认使用 SuiGrpcClient。 SuiJsonRpcClient 用于兼容旧版，但 JSON-RPC 已弃用；SuiGraphQLClient 适用于专门的关系查询流程。决策说明请参阅 typescript.md。
4. 对于 Rust，优先使用 sui-rust-sdk crates，而非旧版单体仓库 sui-sdk。 分别导入 sui-transaction-builder、sui-sdk-types、sui-crypto、sui-rpc——只为实际使用的部分付费。
5. 编写 TS 代码前，检查 node_modules/@mysten/*/docs/llms-index.md。 如果项目已安装 @mysten/sui，这些文档就是权威且与版本匹配的资料。先阅读索引，再阅读目标页面。
6. 不要混用 v1 和 v2 的 TS 模式。 使用 SuiClient、TransactionBlock、getFullnodeUrl、options: { showEffects }、signAndExecuteTransactionBlock 或 result.effects?.status?.status 的代码属于 v1。要么整体迁移，要么全部保留在 v1——只迁移一半的文件会引入错误。
7. 必须说明社区 SDK 的注意事项。 推荐或使用社区 SDK 时，需说明它由社区维护，可能无法及时跟进协议更新。依赖它之前，检查仓库的最后一次提交时间以及它对最新 Sui 版本的支持情况。
8. v2 中通过 $extend() 集成框架。 client.$extend(suins(), deepbook({ address })) 是 v2 模式。不要直接实例化 SuinsClient 或 DeepBookClient——这是 v1 的写法。
9. 将前端问题引导至 frontend-apps skill。 用户询问 React hooks、钱包连接或 dApp Kit 查询模式时，明确指引他们查看 frontend-apps skill，了解 hook 层级的详情。此 skill 仅涵盖 SDK 选择和 Transaction 构造。
10. 不确定时引用文档。 官方 TS SDK 文档位于 sdk.mystenlabs.com。SDK 清单位于 docs.sui.io/references/sui-sdks。Rust SDK 文档位于 docs.rs（按 crate 分类）和 mystenlabs.github.io/sui-rust-sdk/<crate_name>/（例如 /sui_transaction_builder/）。

常见错误

• 将社区 SDK 称为“Python SDK”或“Go SDK”，仿佛它们是官方 SDK。 没有官方的 Python 或 Go SDK。请写明具体的软件包（pysui、block-vision/sui-go-sdk），并注明它们由社区维护。
• 告诉用户 SuiClient 是推荐的客户端。 那是 v1 的做法。v2 使用 SuiGrpcClient（或将 SuiJsonRpcClient 作为已弃用的迁移过渡方案）。
• 推荐 @mysten/sui.js。 这是已弃用的软件包名称。请始终使用 @mysten/sui。
• 混淆两个 Rust SDK。 新的 sui-rust-sdk crates（在 crates.io 上以独立 crate 发布，例如 sui-sdk-types / sui-transaction-builder / sui-rpc）与 sui monorepo 中旧的 sui-sdk crate 不同。新代码应使用前者。
• 在本地已安装 TS 文档时仍从网上获取。 如果项目已安装 @mysten/sui，请改为阅读 node_modules/@mysten/sui/docs/llms-index.md——它与已安装的版本相匹配。
• 将 SDK 版本写死。 SDK API 会不断演进。建议说“安装最新的 @mysten/sui”，然后查阅随附文档，而不是将建议绑定到特定版本。
• 为后端代码推荐 @mysten/dapp-kit。 dApp Kit 是面向 React 的前端框架。后端或 CLI 代码应直接使用 @mysten/sui。
• 直接提供 React Hook 详情，而不是引导用户查看 frontend-apps skill。 用户询问 React Hook、钱包连接模式或 dApp Kit 查询模式时，不要从本 skill 提供 Hook 层级的代码。应明确告诉用户：“关于 React Hook 详情，请参阅 frontend-apps skill。”本 skill 仅涵盖 SDK 选择和 Transaction 构建；Hook 层级的指导请参阅 frontend-apps skill。
• 默认对任何客户端使用 JSON-RPC。 JSON-RPC 已弃用；Sui Foundation 主网全节点将在 2026 年 7 月 27 日当周禁用它。默认使用 gRPC（或在进行关系型查询时使用 GraphQL）。SuiJsonRpcClient 仍可用于迁移，但不应作为默认选项。