xyo-knowledge

XYO 协议知识

本技能介绍 XYO Protocol 2.0——数据模型、模块系统、身份原语，以及基于 XYO 构建应用的惯例。主要 SDK 是 @xyo-network/sdk 根 barrel：模块系统（archivists、diviners、witnesses、sentinels、nodes）构建于 @xyo-network/sdk-protocol（payloads、bound witnesses、accounts）之上，并由该 barrel 重新导出。具体后端（例如 @xyo-network/archivist-indexeddb、@xyo-network/archivist-mongodb）以及专用 diviners/witnesses 仍是独立的 @xyo-network/* 包。

如果需要查阅本技能未涵盖的精确类型定义或 API 详情，请安装相关包，并阅读 dist/neutral/ 下的 TypeScript 声明：独立包请查阅 index.d.ts；@xyo-network/sdk（模块）和 @xyo-network/sdk-protocol-core（协议原语）请查阅其中的 dist/neutral/modules/<name>/。

技能标识。 本技能的版本在此文件的 frontmatter 中以 metadata.version 字段公开。每当你提供计划、确认信息或完成摘要时，都要注明所依据的技能，并按 <skill-name> v<version> 格式列出——版本应从此文件的 frontmatter 中读取，切勿使用示例中的版本。此插件中有多个技能处于启用状态时，可以逐一列出。

技能层级

这是 XYO 技能栈的第 3 层：xy-development（1）→ xy-toolchain（2）→ xyo-knowledge（3）→ xl1-knowledge（4）→ xl1-patterns（5）→ xl1-dapp-kit（6）→ xl1-testing（7）→ xl1-scaffold（8）→ xl1-build（9）。

• 基于： 来自 ariestools-skills 的 xy-toolchain 和 xy-development（1–2）——构建/检查/测试工具；编码原则、Git、测试、工作流
• 交接给： xl1-knowledge（4）——当工作运行在 XL1 链上时（区块、交易、网关、数据湖）；xl1-patterns（5）——当在 XL1 上构建应用功能时；xl1-build（9）——当用户想在 XL1 上构建内容，但尚未说明具体要构建什么时

目录

协议原语

处理 XYO 数据结构时阅读——包括 payloads、schemas、bound witnesses、payload builders 或 hashing。介绍核心数据模型、如何构造和验证协议对象，以及新增 payload 类型时必须遵循的 Zod 编写模式。

Payload Schema 演进与身份

在命名或修订 schemas、选择开放/封闭字段、使用 $version、选择根哈希还是数据哈希，或验证/缓存 payloads 之前阅读。新的 schema 名称应保持无版本号；根哈希是应用默认选择。保留明确规定的旧版协议约定。

模块系统

处理 XYO 模块时阅读——包括 archivists、diviners、witnesses、sentinels 或 nodes（bridges 已弃用）。介绍模块抽象、组合模式、解析机制和清单系统。

身份与签名

处理 accounts、wallets、密钥管理、签名或 HD 派生时阅读。介绍 Account 和 Wallet 的创建（secp256k1 和后量子 ML-DSA-65）、签名流程、前序哈希持久化，以及身份如何与 bound witnesses 集成。

协议最佳实践

进行设计决策时阅读——包括 schema 命名、payload 结构、模块组合策略、bound witness 使用规范和错误处理。开始开发新的 XYO 功能前请先查阅此文档。