multiversx-project-architecture（MultiversX 智能合约项目架构设计技能）Skill 是什么？如何下载？

MultiversX 智能合约项目架构设计技能：让合约工程从第一行代码起就是生产级

它是一套“工程约定”，不是一段代码：技能内置的是 MultiversX 智能合约在生产环境中经过验证的目录结构、模块拆分方式和命名规范，而不是零散的函数片段。
核心思想只有一句：lib.rs 只做模块组合与初始化/升级，业务逻辑分散到 storage、views、config、validation、helpers、events 等独立模块。
覆盖两种工程形态：约 1000 行以内的单合约结构，以及多合约协议所需的工作空间（workspace）结构。
包含 gas 优化与复用细节：静态字节串错误常量、事件模块特质、集中式输入校验、13 个官方 SDK 标准模块的继承方式。
附带可执行判断标准：“什么时候该把代码抽到 common/ 共享 crate”的信号表，以及完整的命名约定表，便于团队协作与审计。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息一览

项目	内容
技能中文名	MultiversX智能合约项目架构设计技能Skill
技能英文名	multiversx-project-architecture
技能 ID	12533
定位	MultiversX 智能合约的生产级项目结构模式

它解决什么问题？

写过 Rust 智能合约的开发者大多踩过同样的坑：一开始所有逻辑都堆在 lib.rs 里，几百行还能忍受，破千行之后每次改动都要在文件里反复翻找；错误信息直接内联写字符串，既不统一也不省 gas；两个合约需要共用同一套结构体时，只能复制粘贴，改一处忘记另一处；新人接手项目时，先要花两周“考古”目录。这个技能把生产项目中已经形成共识的目录与模块组合模式固化成可复用的知识包，让 AI 助手在生成或重构代码时直接按标准执行，而不是每次都临时发挥。

一键安装的思路与步骤

AI 技能（Skill）本质上是把某一领域的专家经验打包成可被 AI 助手加载的能力包。安装后，当你在会话中提到“新建 MultiversX 合约项目”“重构合约目录”“多合约共享代码”等任务时，助手会自动套用这套规范，无需每次手写长篇提示词。

确认前提：拥有一个支持 AI 技能加载的编程助手或客户端；若希望本地编译验证，还需要具备 Rust 工具链与 MultiversX 合约开发环境（如官方构建工具）。
找到入口：打开你所使用平台的技能市场、技能库或插件面板（具体入口以官方说明为准）。
搜索技能：输入英文名 multiversx-project-architecture，或直接输入技能 ID 12533 精确定位。
安装或启用：在详情页点击安装/启用按钮，按平台提示完成授权（具体操作与是否收费以官方说明为准）。
验证是否生效：新建一个会话，输入“帮我为一个 1000 行规模的 MultiversX 单合约生成生产级目录结构和 lib.rs 骨架”。如果输出中出现了 storage.rs、views.rs、config.rs、events.rs、validation.rs、errors.rs、helpers.rs 的拆分，以及 meta/、wasm/、tests/ 目录，说明技能已正常加载。

2. 该技能的主要功能和特点

单合约标准结构：为业务逻辑约 1000 行的合约提供一套固定目录——Cargo.toml、src/（7 个职责单一的模块文件）、meta/、wasm/、tests/integration_test.rs，从第一天起就避免了“所有逻辑都在 lib.rs”的常见问题。
多合约工作空间结构：为存在多个交互合约的协议提供 [workspace] 组织方式，包含 common/（constants、errors、structs、math、events 五个子 crate）、多个合约目录以及可选的 proxy-definitions/。
lib.rs 特质组合模式：主合约文件只做模块声明 + 特质继承 + #[init] / #[upgrade]，端点内部只做“校验 → 建缓存 → 委托处理 → 缓存提交”，业务实现全部下沉。
gas 友好的错误常量写法：用 pub static ERROR_XXX: &[u8] = b"..." 替代内联字符串，因为编译器会对静态引用去重，比内联字面量更省 gas，配合 require! 使用。
事件模块化：事件以 #[multiversx_sc::module] 独立成 EventsModule，用 #[event("deposit")] 加 #[indexed] 参数定义，避免事件散落各处。
集中式输入校验：ValidationModule 依赖 StorageModule，提供 validate_payment 等组合校验方法和细粒度 require_* 方法，端点里一行调用即可。
共享代码判断标准：把“什么时候该抽到 common/”写成一张明确的信号表——同结构体/同数学函数/同错误消息/同事件/协议常量在 2 个以上合约出现时，就应上移。
官方 SDK 标准模块清单：列出 multiversx-sc-modules 中 13 个可直接继承的模块（only_admin、pause、default_issue_callbacks、esdt、governance、bonding_curve、token_merge、subscription、staking、features、users、ongoing_operation、claim_developer_rewards、dns）及导入路径，避免重新实现已有功能。
统一命名约定表：合约 crate 用 kebab-case、模块文件用 snake_case、存储键用 camelCase、错误常量用 SCREAMING_SNAKE、模块特质用 PascalCase、端点用 snake_case、视图在 ABI 中用 camelCase——让多人协作时不必反复争论风格。

和普通工具比强在哪？ 通用 AI 助手能写出“能编译通过的合约”，但往往结构随意、重复代码多、错误处理风格不统一；通用脚手架只生成空的骨架，不告诉你模块该怎么切分、什么时候该抽公共 crate。这个技能提供的是同时覆盖“结构 + 边界 + 复用策略”的一套完整决策体系，输出结果更接近可以直接进入审计流程的工程。

3. 如何使用该技能？

以下按“从零新建”和“重构存量”两条主线给出可参考的调用方式。

步骤 1：先声明项目形态与规模

在提问时明确说明是单合约还是多合约协议、大致代码量。例如：

“我要写一个约 800 行的流动性池合约，请按 MultiversX 生产级结构生成目录和每个文件的职责说明。”

步骤 2：生成目录骨架与文件清单

预期输出是第 2 部分提到的那套 src/ 分层结构；若助理只给了一个 lib.rs，说明任务描述不够明确，可补充“使用 lib.rs 特质组合模式”。

步骤 3：逐个生成模块文件

可分批索取，例如：

“生成 storage.rs，包含 totalSupply、feeRate 两个存储映射，存储键用 camelCase。”

预期得到 #[storage_mapper] 定义集合，并且关键字与命名约定表一致（如 "totalSupply"、"feeRate"）。

步骤 4：组装 lib.rs

典型输出形态如下，端点内部只做委托：

#[multiversx_sc::contract]
pub trait MyContract:
    storage::StorageModule
    + config::ConfigModule
    + views::ViewsModule
    + events::EventsModule
    + validation::ValidationModule
    + helpers::HelpersModule
{
    #[init]
    fn init(&self) { /* 仅初始化逻辑 */ }

    #[endpoint]
    fn main_operation(&self) {
        self.validate_payment(&payment);
        let mut cache = cache::StorageCache::new(self);
        self.process_operation(&mut cache, &payment);
    }
}

步骤 5：补齐错误、事件与校验

“用静态字节串方式定义 6 个错误常量，并写一个 ValidationModule，包含 require_token_supported 和 require_amount_positive。”

预期得到 pub static ERROR_NOT_SUPPORTED: &[u8] = b"Not supported"; 这类常量和对应 require! 校验方法。

步骤 6：多合约时引入工作空间与公共 crate

“我的协议包含 pool、staking、governance 三个合约，请给出 workspace 的 Cargo.toml 和 common/ 下的五个子 crate 结构。”

预期输出 [workspace] members 列表（含各合约及其 meta）、common-* 包的 Cargo.toml 依赖写法（multiversx-sc 版本以你项目实际使用为准，技能示例为 0.64.0）。

步骤 7：按需继承 SDK 标准模块

“给合约加上管理员控制和暂停能力。”

预期在特质列表中出现 multiversx_sc_modules::only_admin::OnlyAdminModule 与 multiversx_sc_modules::pause::PauseModule，并在端点里调用 self.require_caller_is_admin(); 与 self.require_not_paused();。

步骤 8：重构存量项目

把现有 lib.rs 贴给助手，要求“按模块职责拆分，保持端点签名与存储键不变”，可得到等价但结构清晰的重构方案。建议先在分支上执行并跑通集成测试再合并。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
multiversx-project-architecture（本技能）	生产级合约工程结构知识包	单合约/多合约目录模式、`lib.rs` 组合模式、errors/events/validation 标准写法、共享 crate 判断标准、SDK 模块清单、命名约定	需在支持技能的 AI 助手平台安装启用（入口以官方说明为准），无需额外配置	新建合约项目、重构存量合约、多合约协议搭建、团队规范统一	优势：输出即工程规范，附带决策依据（何时抽公共 crate）；不足：只解决“结构与组织”，具体业务算法仍需自己实现与测试
通用 AI 助手（无技能）	通用代码生成	可写任意语言的合约片段	零门槛	快速查语法、写单个函数	优势：灵活；不足：结构不稳定、缺少 MultiversX 特有约定，容易产出逻辑全堆在 `lib.rs` 的代码
官方合约构建工具链（如 sc-meta 等）	编译、测试、部署工具	合约构建、wasm 产物生成、元数据 / ABI 处理	需本地安装 Rust 工具链与官方工具	构建与部署环节	优势：官方支持、可复现构建；不足：面向“构建”而非“架构设计”，不提供模块拆分建议（具体能力以官方说明为准）
手动对照官方示例仓库模仿	人工学习	参考现成合约的目录组织	需要自行甄别示例质量	小规模试水	优势：无需额外工具；不足：示例风格不统一，难以形成团队规范，重构成本高

从对比可以看出，本技能的差异点在于：它不参与“编译”和“部署”，也不负责业务逻辑实现，专门解决“代码该怎么组织、什么该复用、什么该下沉”这类架构决策问题，与构建工具是互补关系而非替代关系。

5. 该技能的典型应用场景与实际体验情况

场景一：DeFi 团队从零启动新合约 角色是合约负责人。痛点在于刚开始时“能跑就行”，三个月后要加功能才发现改一处牵连全身。使用方式是让助手先产出一套带 meta/、wasm/、tests/ 的完整目录与各文件职责注释，再按模块逐个填充业务。实际体验：上手难度低，属于“提问即得”的类型；效果上最明显的是 lib.rs 长度被控制在几十行，端点逻辑清晰可读；注意事项是生成后要人工确认 Cargo.toml 中的依赖版本与团队既有工程一致，避免版本漂移。

场景二：把 2000 行的存量合约重构为模块化结构 角色是接手老项目的开发者。痛点是一次审计意见写着“缺少集中输入校验、错误信息散落”。使用方式是把现有代码交给技能，要求按 storage / views / config / validation / events / helpers 拆分并保持端点签名与存储键不变。实际体验：拆分建议质量取决于你提供的代码完整度，建议一次只拆一个关注点（先拆存储、再拆校验）；注意事项是重构后必须跑集成测试，尤其是升级迁移路径（#[upgrade]），并确认存储键名完全没有变化，否则会影响线上数据。

场景三：多合约协议的共享代码治理 角色是协议架构师，负责 pool、staking、governance 三个合约。痛点是同一种精度常量在三个合约里各写一遍，改一次漏两个。使用方式是用技能提供的信号表判断哪些内容该上移到 common/constants、common/math、common/errors，再让助手生成 [workspace] members 与各 common-* 包的依赖配置。实际体验：信号表是这套技能中最有“决策价值”的部分，能避免过早抽象；注意事项是不要为了复用而过度拆分，只有一个合约用到的类型留在本地即可。

场景四：审计前的代码规范化准备 角色是准备提交审计的小团队。使用方式是让助手核对命名约定（合约 crate 用 kebab-case、端点用 snake_case、视图在 ABI 中用 camelCase）和 SDK 标准模块使用情况——例如已经有 only_admin 和 pause 就不必自己再写一遍管理员与暂停逻辑。实际体验：能显著减少“样式类”审计意见；注意事项是 SDK 标准模块的行为语义（如暂停后哪些端点受限）仍需自己确认，不能只依赖生成结果。

6. 该技能能为用户带来的价值

提升效率：目录骨架、模块划分、Cargo.toml 配置这类“每次开新项目都要重做一遍”的准备工作，从半年级别的经验摸索变成一次提问即可获得，项目启动阶段的重复劳动被大幅压缩。
降低门槛：不熟悉 MultiversX 工程惯例的 Rust 开发者，也能直接产出符合生产规范的结构，不必靠读十几个开源仓库来反推“大家的 lib.rs 为什么这么短”。
减少隐性成本：把 lib.rs 控制在“只做组合”的长度，意味着后续每一次功能迭代的定位成本都更低；静态字节串错误常量与集中校验，则在 gas 消耗和可读性上同时获益。
统一团队语言：命名约定表、共享 crate 信号表让“该放哪里”“该叫什么”不再依赖个人偏好，Code Review 从风格争论回到业务本身。
长期可维护性：多合约工作空间 + common/ 分层让协议在扩容时不必推倒重来，也为后续审计、交接和新人 onboarding 提供了清晰的阅读路径。

7. 常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认生效？ 在支持 AI 技能的平台技能市场或技能库中搜索英文名 multiversx-project-architecture 或技能 ID 12533，进入详情页按提示安装并启用即可（具体入口与操作以官方说明为准）。验证方法：让助手生成一个单合约骨架，若输出包含 storage.rs、views.rs、validation.rs、errors.rs 等分模块文件以及 meta/、wasm/、tests/ 目录，说明已生效。

Q2：使用这个技能收费吗？ 技能本身是否收费、是否有免费额度，取决于你所用平台的规则，以官方说明为准。技能不额外要求你安装任何私有依赖；本地编译验证所需的 Rust 工具链与 MultiversX 开发环境是开源工具，自行准备即可。

Q3：它适合谁用？我只写过 Solidity 有必要用吗？ 最适合三类人：正在启动 MultiversX 新合约项目的团队、需要重构“逻辑全堆在 lib.rs”的存量项目的开发者、以及要管理多个相互调用合约的协议架构师。如果你只有 Solidity 经验，这个技能尤其有价值——它直接告诉你 MultiversX 工程里“模块特质怎么组合”“存储映射放哪里”“哪些能力官方已经提供好了”，能省掉大量对照示例仓库的时间。

Q4：它和官方构建工具是替代关系吗？ 不是。构建工具负责编译、生成 wasm 产物和处理元数据/ABI；本技能负责架构层面的组织方式与复用决策。两者是互补关系，正常流程是“先用技能定结构，再用构建工具编译测试”。

Q5：生成的结构能直接上线吗？还需要注意什么？ 不能。技能提供的是结构与组织规范，业务逻辑、权限模型、边界条件仍需你自己实现并充分测试。上线前请重点检查三件事：存储键名是否与既有版本一致（涉及升级兼容）、#[upgrade] 迁移逻辑是否覆盖数据变化、以及是否正确复用了 SDK 标准模块而非重复实现。