ArcBlock — docs

AFS

ARC 里 AFS 的路径、provider、能力和查询契约的开发者文档。

编写 provider

从当前 JSON provider 与其 conformance 套件起步，只声明能强制执行的能力。

核心合同

通过拥有该路径的 provider 所声明的能力，使用 AFS 路径操作。

用 Explorer 浏览 AFS

用 AFS Explorer blocklet 在浏览器里浏览、检视、预览任意已挂载的 AFS 路径，URL 与 AFS 路径一一对应。

AFS 快速开始

在选择 provider、mount 或路径之前，先检查本机已安装的 AFS 命令面。

本地巡检 AFS

在指定 arc 版本上，对 mount 与路径做以只读为主、可复跑的本地巡检，不编造存储神话。

AFS

用 AFS 通过路径、能力声明与显式操作，访问由 provider 支撑的资源。

Provider 目录

用分层准入，只把有证据的 provider 写成公开集成——而不是把仓库 package 列表整表公开。

Providers

把 AFS provider 理解为通过路径暴露资源、并拥有能力声明的模块。

AFS recipes

在指定 arc 版本上可重复的 AFS 任务，并写清环境与变更边界。

AFS 参考

术语索引，以及指向 AFS 操作、能力、错误与相关 board 的稳定指针。

运行时边界

区分 mount、权限、实例状态、本地验收与正式发布，避免巡检意外改写用户环境。

Search 与 query

按合同区分 list、类型化 collection query 与 provider 定义的自由文本 search。

Agent Access

How an external agent discovers, connects to, authenticates against, and uses a blocklet running on ARC.

访问分档

一次调用要过四道彼此独立的闸：方法白名单、凭证、路径策略、provider 能力。凭证只过其中一道，不是四道。

HTTP 上的 AFS

一个 JSON-RPC 端点，向不说 MCP 的客户端暴露与 MCP 工具相同的 AFS 操作。

授权客户端

从被拒绝的调用所返回的挑战走到 authorization server、注册客户端、取得凭证并使用它 —— 以及这份凭证打不开什么。

接入你的工具

把 blocklet 添加到 Claude Code 或 Codex CLI，需要读取公开内容以外的东西时再登录。

连接客户端

用 streamable HTTP 把 MCP 客户端指向一个 blocklet host，再用一次不需要握手的匿名 tools/list 确认连接。

声明 agent 能看到什么

blocklet 只声明一次内容集合。这份声明决定每个集合抵达哪些面向 agent 的界面，以及匿名调用方能否读取它。

无浏览器时取得凭证

客户端没有浏览器可跳转时用 device grant：发起、让人批准、轮询，拿到一把 blocklet- 前缀的 access key。

发现面

/.well-known/ 下的四份文档描述 MCP 端点、它的认证要求和它的 authorization server。四份都是匿名 GET。

端点

agent 会用到的每个路径、对应的方法、是否需要凭证，以及由哪个组件提供。

错误

agent 可能撞上的每一种失败、成因和处理方式 —— 按传输层失败与调用内失败分开，因为它们含义不同。

llms.txt

一份简短的指针文档，列出该 host 上的 agent 界面，并为声明了 llms face 的集合提供分片。

Agent 访问

运行在 ARC 上的每个 blocklet 都会暴露一个 MCP 端点和一组发现文档，外部 agent 可以找到它、连接，并读取该 blocklet 已声明的内容。

工具

八个通用 AFS 工具始终存在。三个内容工具只在 blocklet 声明了集合时出现，且它们的 schema 会写明所声明的集合。

理解 agent 访问

端点背后的模型：什么决定一次调用成不成功、blocklet 选择暴露什么、以及哪种客户端该走哪个面。

AIGNE CLI

AIGNE Framework 的官方命令行工具，用来简化 agent 的创建、运行和调试。

内置应用

AIGNE CLI 附带了预打包的应用程序，提供开箱即用的专业功能。这些应用是完整的 AIGNE 项目，您可以直接执行，无需先初始化本地项目。

命令参考

AIGNE 命令行界面（CLI）是您创建、管理和部署 AIGNE agent 的主要工具。本节为所有可用命令及其选项提供了全面的参考，以便于快速查找。

aigne create

aigne create 命令从模板搭建一个新的 AIGNE 项目。它会设置必要的目录结构和配置文件，让你可以立即开始开发你的 Agent。

aigne deploy

aigne deploy 命令会将您的 AIGNE 应用程序打包并作为 Blocklet 部署到指定的 Blocklet Server 端点。这是发布您的 Agent 以供生产使用的标准方式，使其可以作为一个独立的、可执行的服务进行访问。

aigne hub

aigne hub 命令是您管理 AIGNE Hub 连接的中心工具。Hub 提供对托管大语言模型的访问、处理 API 密钥管理并跟踪您的信用额度使用情况。正确配置您的 Hub 连接对于运行使用 Hub 提供的模型的 Agent 至关重要。

aigne observe

aigne observe 命令会启动一个本地 Web 服务器，用于监控和分析 agent 的执行数据。它提供了一个用户友好的界面，用于检查调用链、查看详细的调用信息，并了解您的 agent 在运行期间的行为。该工具对于调试、性能调优以及深入了解您的 agent 如何处理信息并与各种工具和模型交互至

aigne run

aigne run 命令是执行 AIGNE agent 的主要方式。它可以从本地项目目录或直接从远程 URL 运行 agent。它提供了一套灵活的选项，用于提供输入、配置 AI 模型和处理输出，包括用于会话式 agent 的交互式聊天模式。

aigne serve-mcp

将 AIGNE 项目中的 Agent 作为模型上下文协议（MCP）服务器提供服务。此命令通过一个可流式传输的 HTTP 端点暴露您的 Agent，从而实现与支持 MCP 标准的外部系统和应用程序的无缝集成。

aigne test

aigne test 命令为您的 agent 和技能执行自动化测试。它提供了一个内置的单元和集成测试机制，以确保您的 agent 及其依赖的工具在部署前能够正常工作。

贡献指南

我们很高兴您有兴趣为 @aigne/cli 做出贡献！您的帮助对于改善所有人的 AIGNE 开发体验至关重要。无论是修复错误、提出新功能还是改进文档，我们都欢迎您的贡献。

Agents and Skills

在 AIGNE 生态系统中，Agents 和 Skills 是将您的 AI 应用程序变为现实的基本构建块。它们协同工作，创建复杂的、由工具增强的 AI 系统。您可以将 Agent 视为负责推理和对话的大脑，而将 Skills 视为其用于执行操作和与外部世界交互的工具。

核心概念

AIGNE 项目为开发、测试和部署 AI Agent 提供了一个结构化的环境。其核心是一个包含配置文件的目录，这些文件定义了你的 Agent、它们可以使用的技能以及它们连接的语言模型。本节将分解这些基本构建块。

项目配置 (aigne.yaml)

aigne.yaml 文件是 AIGNE 项目的核心。它作为中央清单文件，定义了项目的元数据、语言模型设置以及其核心组件（如 agent 和技能）之间的关系。一个结构良好的 aigne.yaml 是构建强大且有组织的 agent 的第一步。

快速入门

本指南将引导您完成安装 AIGNE CLI、创建新项目以及运行您的第一个 AI agent 的基本步骤。完成本指南后，您将拥有一个在本地运行的 agent。

指南

欢迎阅读 AIGNE CLI 指南。本节提供了实用的分步教程，旨在帮助您掌握常见的开发工作流程。无论您是构建您的第一个自定义 Agent、从远程代码库执行代码，还是为生产环境准备您的应用程序，这些指南都将为您提供必要的指导。

创建自定义 Agent

本指南提供了一个分步教程，指导您如何创建一个新的 JavaScript agent，并将其作为一项技能集成到您的 AIGNE 项目中。Agent 是赋予您的应用程序独特能力的核心可执行组件。通过创建自定义 agent，您可以扩展 AI 的功能，以执行特殊任务、与外部 API 交互或操作本地数据。

部署 Agent

部署你的 AIGNE 项目会将其从本地开发设置转变为一个独立的、可分发的应用程序，称为 Blocklet。这使你的 Agent 可以在生产环境中运行，与他人共享，并无缝集成到更广泛的 Blocklet 生态系统中。aigne deploy 命令会自动完成整个打包和部署过程。

运行远程 Agent

AIGNE CLI 不仅限于运行本地文件系统中的项目。它还提供了一个强大的功能，可以直接从远程 URL 执行 Agent。这对于测试、共享和运行 Agent 非常有用，无需克隆代码仓库或手动下载文件。

概述

您的 Agent 开发指挥中心@aigne/cli 是 AIGNE 框架的官方命令行工具，旨在简化 Agent 开发的整个生命周期。它提供了一套全面的命令来简化项目创建、本地执行、测试和部署，使您能够轻松构建、运行和管理 AIGNE 应用程序。主要特性@aigne/cli 包含了丰富的功能，可以加

AIGNE Framework

面向真实 LLM 应用的 agent 框架：函数式、可组合、TypeScript 优先。

Agent 库

Agent 库提供了一系列预构建、可重用的 Agent，旨在加速复杂 AI 应用程序的开发。通过集成这些现成的组件，您可以轻松编排复杂的工作流、管理并发任务，并自动化多步骤流程，而无需从头构建一切。

Bash

本文档详细介绍了 Bash Agent，它允许在 Agent 工作流中安全地执行 Shell 脚本和命令行工具。您将学习如何配置其沙盒环境、管理命令权限，并将其集成到您的应用程序中以执行系统级操作。

Orchestrator

Orchestrator Agent 提供了一种结构化、可靠的解决方案，用于管理复杂的多步骤 AI 工作流。它将高层目标分解为一系列可管理的任务，按顺序执行它们，并将结果合成为一个连贯的最终响应，从而实现自主的任务规划和执行。

高级主题

掌握了核心概念并构建了基本应用程序后，您就可以开始探索 AIGNE 框架更复杂的功能了。本节专为希望构建复杂、稳健且高度定制化 AI 应用的开发者而设计。在这里，我们将深入探讨高级模式和工具，这些模式和工具可以更好地控制 Agent 定义、提示工程、执行生命周期和数据处理。

使用 YAML 定义 Agent

AIGNE 框架支持使用 YAML 配置文件以声明式方法来定义 Agent。这种方法将 Agent 的定义（其属性、指令和技能）与应用程序的业务逻辑分离开来，从而促进了更好的组织、可重用性，并使复杂 Agent 系统的管理更加容易。

钩子

钩子（Hooks）提供了一种强大的机制，用于观察、拦截 Agent 的执行生命周期并向其中注入自定义逻辑。它们允许您在不改变 Agent 核心实现的情况下，添加日志记录、监控、输入/输出转换以及自定义错误处理等功能。

提示词

与 AI 模型的有效沟通取决于所提供提示词的质量和结构。AIGNE 框架通过其 PromptBuilder 类和集成的 Nunjucks 模板引擎，提供了一个强大的系统，用于创建动态、可复用和结构化的提示词。本指南对这些组件进行了系统性解释。

流式传输

AIGNE 框架为处理来自 Agent 的流式响应提供了强大的支持。这对于需要实时数据处理的应用尤其有用，例如聊天机器人、实时数据源或任何受益于即时增量更新的用户界面。通过在数据可用时立即处理，您可以创建响应更迅速、交互性更强的用户体验。

Agent 类型

AIGNE 框架提供了一套专门的 Agent 类型，每种类型都设计用于执行特定功能。虽然所有 Agent 都继承自基础的 Agent 类，但这些专门的实现为常见任务提供了预构建的功能，从与 AI 模型交互到编排复杂工作流。理解这些类型是构建健壮且高效的应用程序的关键。

AI Agent

AIAgent 是与大语言模型 (LLM) 交互的主要组件。它充当 ChatModel 的直接接口，支持复杂的对话式 AI、函数调用（工具使用）和结构化数据提取。该 Agent 负责处理提示词构建、模型调用、响应解析和工具执行循环等复杂任务。

Function Agent

FunctionAgent 提供了一种封装现有 TypeScript 或 JavaScript 函数的直接方法，从而将它们提升为 AIGNE 框架内的一等 Agent。这使得将自定义业务逻辑、外部 API 交互或任何任意代码无缝集成到 Agent 工作流中成为可能，无需编写大量样板代码。

Image Agent

ImageAgent 是一个专门负责生成图像的 Agent。它充当 ImageModel 的接口，处理输入数据以构建提示，然后请求图像生成服务来创建图像。

MCP Agent

MCPAgent 是一种专门的 Agent，旨在与遵循模型上下文协议 (Model Context Protocol, MCP) 的外部系统进行交互。它充当一座桥梁，允许您的 AIGNE 应用程序连接到远程 MCP 服务器，并利用其功能——例如工具、提示和资源——就好像它们是框架的原生组件一样。这使

Team Agent

TeamAgent 是一种专门的 Agent，它负责协调一组其他 Agent（称为“技能”）来执行复杂任务。它扮演着管理者的角色，根据既定策略指导信息流并协调其技能的执行。这使得创建复杂的工作流成为可能，其中多个专门的 Agent 协同合作，以实现单个 Agent 无法独立完成的目标。

转换 Agent

TransformAgent 是一种专门的 Agent，它提供了一种使用 JSONata 表达式来转换结构化数据的声明式方法。它非常适合需要将数据从一种格式映射、重构或转换为另一种格式，而无需复杂命令式逻辑的场景。

核心概念

要有效使用 AIGNE 框架构建应用程序，首先必须理解其基本架构组件。本节将高阶概述主要构建块及其交互方式。清晰掌握这些概念将有助于更直观地进行开发。

Agents

在 AIGNE 框架中，Agent 是工作的基本单元。它是一个抽象类，为所有专业化的 Agent 类型建立了一个标准契约。一个 Agent 可以被概念化为一个能够执行特定任务、处理信息并与系统中其他 Agent 交互的独立工作者。每一个专业化的 Agent，无论是设计用于与 AI 模型交互、转换数据

AIGNE

AIGNE 类是框架的核心执行引擎。它通过协调多个 Agent 来构建复杂的 AI 应用程序，充当 Agent 交互、消息传递和整体执行流程的主要协调点。

记忆

MemoryAgent 为 Agent 提供了一种机制，使其能够在多次交互中保持状态和记忆信息。它充当一个专门的编排器，不直接处理消息，而是通过两个关键组件来管理记忆操作：用于存储信息的 Recorder 和用于回忆信息的 Retriever。这种关注点分离的设计允许使用灵活且可插拔的记忆存储解决方

模型

模型是专门的 Agent，作为关键的抽象层，为与外部 AI 服务（如大型语言模型 (LLMs) 和图像生成平台）的交互提供标准化接口。它们封装了 API 通信的复杂性，使开发者能够通过一致且统一的契约与各种 AI 提供商合作。

快速入门

本指南提供了设置开发环境并使用 AIGNE 框架运行您的第一个 AI Agent 所需的步骤。整个过程预计在 30 分钟内完成，通过实际操作，帮助您上手框架的基本工作流程。

示例

浏览一系列实际示例，了解 AIGNE 框架的各种功能和工作流模式。本节提供可动手执行的演示，帮助您理解智能对话、MCP 协议集成、记忆机制以及复杂的 Agent 工作流。

AFS 本地文件系统

本指南将演示如何构建一个能够与本地文件系统交互的聊天机器人。通过利用 AIGNE 文件系统 (AFS) 和 SystemFS 模块，您可以让 AI Agent 能够搜索、读取和管理您机器上的文件，将其转变为一个强大的本地数据专家。

聊天机器人

本指南全面介绍了基于 Agent 的聊天机器人示例。您将学习如何在不同模式下运行聊天机器人，将其连接到各种 AI 模型提供商，并使用 AIGNE 可观测性工具来调试其执行过程。本示例旨在开箱即用，让您无需任何本地安装即可开始使用。

MCP Blocklet

本文档介绍了如何利用 AIGNE 框架和模型上下文协议 (MCP) 与托管在 Blocklet 平台上的应用程序进行交互。该示例支持单次执行、交互式聊天模式，以及针对模型和 I/O 管道的自定义设置。

MCP DID Spaces

本文档为通过模型上下文协议（MCP）构建与 DID Spaces 集成的聊天机器人提供全面指南。遵循这些说明，您将能够创建一个 AI Agent，利用 AIGNE 框架的能力，在去中心化存储环境中安全地访问和管理文件。

MCP GitHub

本文档为示例提供了一份全面的指南，演示了如何使用 AIGNE 框架和 GitHub MCP (Model Context Protocol) 服务器与 GitHub 仓库进行交互。您将学习如何设置和运行该示例，使 AI agent 能够执行各种 GitHub 操作，例如搜索仓库和管理文件。

MCP Puppeteer

本指南逐步演示了如何将 AIGNE 与 Puppeteer MCP Server 结合使用以实现自动化网络抓取。通过此示例，您将学习如何构建并运行一个能够访问网站并提取其内容的 AI agent。

MCP Server

本指南说明了如何将 AIGNE 框架 Agent 作为模型上下文协议 (MCP) 服务器运行。阅读完本文档后，您将能够启动服务器，将其连接到 AI 模型，并使用兼容 MCP 的客户端（如 Claude Code）与您的 Agent 进行交互。

MCP SQLite

本指南全面介绍了如何使用由 AIGNE 框架驱动的 AI agent 与 SQLite 数据库进行交互。通过遵循这些步骤，您将学习如何设置必要的组件、运行示例应用程序，并使用 agent 执行创建表和查询数据等数据库操作。

记忆

本指南演示了如何构建一个有状态的聊天机器人，该机器人可以在多个会话之间保留对话历史。通过利用 FSMemory 插件，Agent 可以将回话数据持久化到本地文件系统，使其能够回忆起之前的交互。

DID Spaces 内存

本指南演示了如何使用 DID Spaces 构建一个具有持久化内存的聊天机器人。通过利用 AIGNE 框架中的 DIDSpacesMemory 插件，您的 Agent 能够以去中心化且安全的方式跨多个会话保留对话历史。

Nano Banana

本指南将演示如何构建并运行一个能够生成图像的聊天机器人。通过遵循这些步骤，您将学会如何执行一个预构建的 AIGNE 示例、将其连接到 AI 模型，并使用框架的可观测性工具来检查其行为。

工作流代码执行

执行由 AI 模型动态生成的代码会带来严峻的安全性和可靠性挑战。本指南提供了一个结构化的分步流程，用于使用 AIGNE 框架构建安全的的代码执行工作流。您将学习如何编排一个生成代码的 Coder Agent 和一个在隔离环境中执行代码的 Sandbox Agent。

工作流并发

并行执行任务可以显著提高复杂工作流的效率。本指南演示如何使用 AIGNE 框架构建一个并发工作流，其中多个 Agent 同时处理相同的输入，并将其输出进行聚合。您将学习如何设置并运行一个实际示例，该示例从不同角度同时分析一个产品。

工作流群聊

本指南将演示如何使用 AIGNE 框架构建和运行一个多 Agent 群聊工作流。您将学习如何协调包括一个管理者在内的多个 Agent 来协同完成一项任务，模拟一个团队环境，其中 Agent 共享信息并共同努力实现一个共同目标。

工作流切换

本指南演示了如何构建一个工作流，其中一个 Agent 可以将控制权无缝切换给另一个专门的 Agent。读完本指南后，您将理解如何创建多 Agent 系统，该系统能根据用户输入委派任务，从而实现更复杂、更动态的问题解决。

工作流编排

本指南将演示如何构建并运行一个复杂的工作流，该工作流能够编排多个专门的 AI Agent。您将学习如何协调像 finder、writer 和 proofreader 这样的 Agent，共同完成一项复杂的任务，从初步研究到最终报告生成。

工作流反思

您是否曾需要 AI 不仅能生成内容，还能批判和改进其自身的工作？本指南将演示如何构建一个自我修正的工作流，其中一个 Agent 的输出由另一个 Agent 审查和完善。通过遵循这些步骤，您将学习如何使用 AIGNE 框架实现这一强大的迭代模式。

Workflow Router

您是否曾需要根据用户查询的内容将其引导至不同的专业处理程序？本指南将提供一个完整、分步的演练，指导您构建一个能够智能路由请求的工作流。您将学习如何创建一个“分诊” Agent，该 Agent 会分析输入并将其转发给正确的专业 Agent，例如产品支持或反馈收集。

顺序工作流

本指南演示了如何使用 AIGNE 框架构建并执行顺序工作流。您将学习如何将多个 Agent 链接在一起，其中一个 Agent 的输出成为下一个 Agent 的输入，从而创建一个逐步处理的管道。这种模式非常适合需要一系列明确、有序操作的任务。

模型

AIGNE 框架设计为模型无关，允许您连接到各种第三方 AI 模型提供商。这种灵活性是通过模型适配器系统实现的，其中每个适配器都为特定服务（如 OpenAI、Anthropic 或 Google Gemini）提供标准化的接口。

AIGNE Hub

AIGNE Hub 提供了一个统一的代理层，用于访问来自多个提供商的各种大型语言模型 (LLM)、图像和视频生成服务。通过使用 @aigne/aigne-hub 包，您可以在不同的 AI 模型之间无缝切换，而无需更改客户端应用程序逻辑，所有请求都通过一个统一且一致的 API 端点进行。

Anthropic

本指南介绍了如何在 AIGNE 框架内通过 @aigne/anthropic 包配置和使用 Anthropic 的 Claude 模型。内容涵盖 API 密钥设置、模型实例化以及调用模型以获取标准响应和流式响应。

AWS Bedrock

@aigne/bedrock 包提供了 AIGNE 框架与 Amazon Web Services (AWS) Bedrock 之间直接而强大的集成。这使得开发者能够在他们的 AIGNE 应用程序中利用 AWS Bedrock 提供的各种基础模型，既能受益于 AWS 可扩展且安全的基础设施，又能保持

模型配置

要在 AIGNE 框架内集成和利用各种 AI 模型，您必须首先配置必要的凭证，主要通过环境变量。这确保了与相应第三方服务的安全和正确的身份验证。本指南提供了每个支持的模型提供商所需的特定环境变量。

DeepSeek

本指南介绍了如何通过 @aigne/deepseek 包在 AIGNE 框架内配置和使用 DeepSeek 模型。内容涵盖 API 密钥设置、模型实例化，以及标准和流式响应的示例。

豆包

@aigne/doubao 包提供了 AIGNE 框架与豆包强大的语言和图像生成模型之间的无缝集成。本指南为在您的 AIGNE 应用程序中配置和使用豆包模型提供了完整的参考。

Google Gemini

本指南介绍了如何在 AIGNE 框架内通过 @aigne/gemini 包配置和使用 Google 的 Gemini 模型。内容涵盖 API 密钥设置、模型选择，以及可用于聊天、图像和视频生成的特定功能。

Ideogram

本文档为开发者提供了在 AIGNE 框架内集成和利用 Ideogram 图像生成功能的综合指南。@aigne/ideogram 包提供了与 Ideogram API 的无缝接口，能够通过文本提示生成高质量的图像。

LMStudio

@aigne/lmstudio 包提供了一个模型适配器，用于将 AIGNE 与通过 LM Studio 本地托管的大型语言模型 (LLM) 集成。这使得开发者可以在 AIGNE 框架内利用本地模型的强大功能，从而提供更高的隐私性、控制力和成本效益。

Ollama

@aigne/ollama 包提供了 AIGNE 框架与通过 Ollama 本地托管的 AI 模型之间的无缝集成。这使得开发人员能够利用在自己硬件上运行的各种开源语言模型，确保了 AI 功能的隐私性和离线访问能力。

OpenRouter

OpenRouter 是一个统一的网关，可以访问来自 OpenAI、Anthropic 和 Google 等不同提供商的多种 AI 模型。@aigne/open-router 包提供了一个标准化接口，用于将这些模型集成到 AIGNE 框架中。这使得开发人员只需最少的代码更改即可在不同模型之间切换，并

OpenAI

@aigne/openai 包提供了与 OpenAI 模型套件的无缝集成，允许开发者在 AIGNE 框架内直接利用 GPT 进行聊天补全、DALL-E 进行图像生成以及 Sora 进行视频创作等服务。本文档为安装、配置和使用这些模型提供了全面的指南。

概述

AIGNE 框架设计为模型无关，允许开发者集成来自不同提供商的各种大型语言模型 (LLM) 和图像生成模型。这是通过一个标准化的适配器系统实现的，该系统将每个提供商独特的 API 抽象在一个统一的接口之后。

Poe

用户希望修复一个 D2 图表语法错误。错误消息 invalid style keyword: "font-family" 表明 font-family 在 D2 中不是一个有效的样式属性。我需要移除或更正 D2 代码中的这一行。

xAI

本指南介绍了如何在 AIGNE 框架内配置和使用 xAI 的语言模型，特别是 Grok。内容涵盖了必要软件包的安装、API 密钥的配置、模型的实例化，以及标准和流式调用的示例。

概述

AIGNE 框架是一个函数式 AI 应用开发框架，旨在简化和加速构建可扩展的、Agentic AI 应用的过程。它结合了函数式编程概念、强大的人工智能能力和模块化设计，为开发者提供了一个结构化的环境。

用户指南

欢迎阅读 AIGNE 用户指南。本指南专为非技术背景的读者设计，包括企业领导者、管理人员以及任何对如何利用 AI 自动化复杂任务和简化业务流程感兴趣的人士。您无需任何编程知识即可轻松理解本指南。

常见工作流

在 AIGNE 框架中，单个 Agent 可以执行特定任务。然而，当多个 Agent 协作解决更复杂的问题时，才能发挥系统的真正威力。就像团队成员一样，可以组织 Agent 以结构化的方式协同工作。这些协作模式被称为“工作流”。

决策

阐述了一个“管理者”Agent 分析请求并决定哪个专业化 Agent 最适合处理该任务的场景。

并行任务

在某些情况下，为了提高效率，你需要同时执行多个独立任务。并行任务工作流正是为此目的而设计的。它允许多个 AI Agent 同时处理相同的初始信息，最终将它们的独立结果收集并组合起来。

顺序任务

顺序任务工作流按特定的预定顺序处理一系列任务。它就像一条数字流水线，上一步的输出成为下一步的输入。这种模式非常适合多阶段流程，其中每一步都建立在前一步工作的基础之上。

理解 Agent

在 AIGNE 框架中，“agent”是完成工作的基本构建块。可以将 agent 想象成一个专业的数字工作者，被雇佣来执行特定任务。每个 agent 都有明确的角色和一套技能。就像在现实世界的团队中一样，您可以将单个任务分配给一个 agent，也可以组建一个 agent 团队来处理更复杂的项目。

Agent 团队

虽然单个专门的 Agent 对于特定任务很有用，但有些问题对于一个 Agent 来说过于庞大或复杂，无法单独处理。就像在人类组织中一样，当一项任务需要多个步骤或不同技能时，你会组建一个团队。在 AIGNE 中，Agent 团队是一组为协作解决更大目标而组织的 Agent。

基础 Agent

可以将基础 Agent 想象成一个专业的数字助理，比如一个乐于助人的聊天机器人或一个专注的数据录入员。每个 Agent 都被设计用于执行一种特定类型的任务，并能出色地完成。它根据一套明确的指令进行操作，接收特定的输入，并产生一个结果。

什么是 AIGNE？

AIGNE（发音为 [ˈei dʒən]，类似 "agent" 去掉 "t" 的发音）是一个用于开发 AI 应用程序的函数式框架。它旨在通过结合函数式编程、模块化设计和强大的人工智能功能，简化和加速构建可扩展的现代化应用程序的过程。

AIGNE Hub

多家 LLM 供应商的统一适配层，同时管理所有 Blocklet 的 API key 用量。

API 参考

本文档提供了 AIGNE Hub RESTful API 的技术规范。通过本指南，您将了解如何进行身份验证并与聊天补全、图像生成和嵌入等核心端点进行交互，从而实现与您的应用程序的稳健后端集成。

API 身份验证

对 AIGNE Hub API 的请求进行安全身份验证是实现程序化访问和集成的关键步骤。本指南清晰地介绍了使用 API 密钥授权您的应用程序的分步流程，确保所有交互都是安全的并得到正确识别。

聊天补全

本文档提供了聊天补全 API 端点的详细规范。通过本指南，您将学会如何生成对话式 AI 响应、管理流式传输以及利用特定于模型的参数来构建稳健的应用程序。该端点是创建交互式、基于文本的体验的核心。

嵌入

本文档为 AIGNE Hub 嵌入 API 端点提供了详细的规范。通过本指南，您将学习如何将文本转换为数值向量表示，这是语义搜索、文本聚类和相似性分析等任务的基础步骤。

图像生成

本文档提供了图像生成端点的技术规范。遵循本指南，您将能够通过构建请求、指定模型和参数以及处理返回的图像数据，将 AI 驱动的图像创建功能集成到您的应用程序中。

部署场景

选择正确的部署模型对于使 AIGNE Hub 与您的特定运营和业务目标保持一致至关重要。本文档概述了两种可用的主要部署场景，并提供了清晰的比较，以指导您的架构决策。每种模式都旨在满足不同的用例，从企业内部使用到面向公众的商业服务。

企业自托管

在您自己的基础设施内部署 AIGNE Hub，可以让您的组织完全控制 AI 模型访问、数据隐私和运营成本。本指南提供了一种结构化的方法，用于配置和管理自托管的 AIGNE Hub 实例，以实现安全的企业内部使用。

服务提供商模式

准备好提供您自己的多租户 AI 服务了吗？本指南详细介绍了如何在 AIGNE Hub 中激活服务提供商模式。您将学习如何启用基于积分的计费系统、集成 Payment Kit 以及定义自定义定价，从而为您的用户创建一个可盈利的 AI 网关。

核心功能

本节将深入技术层面，探讨 AIGNE Hub 的关键功能。阅读完毕后，您将理解该平台的主要能力，从统一的 AI 模型交互和提供商管理，到强大的安全性和详尽的分析，为充分利用该系统奠定坚实的基础。

使用量与成本分析

了解 AI 模型的使用情况对于管理成本、监控性能和确保资源公平分配至关重要。本文档详细介绍了如何查询使用情况统计数据、跟踪成本以及解读 AIGNE Hub 用于分析和报告的数据模型。

Provider 管理

有效管理上游 AI Provider 对于维护一个可靠且经济高效的 AI 网关至关重要。AIGNE Hub 集中管理此过程，提供统一的界面来连接、配置和管理各种 AI 服务的凭证。本节详细介绍处理 Provider 设置、凭证和模型费率的流程。

安全与访问

一个安全且管理良好的系统对于任何企业级部署都至关重要。本节详细介绍 AIGNE Hub 强大的安全架构，涵盖身份验证、凭证管理、访问控制和日志记录，以确保您 AI 操作的完整性和机密性。

快速入门

本指南提供了一条直接、面向任务的路径，用于部署和操作 AIGNE Hub。遵循这些步骤，可在 30 分钟内配置一个功能齐全的实例，从而实现与上游 AI 提供商和下游应用程序的即时集成。

概述

是否在为管理日益增多的 API 密钥、计费系统以及与不同 AI 提供商的集成而烦恼？本文档将全面介绍 AIGNE Hub，这是一个统一的 AI 网关，旨在简化这种复杂性。您将了解其核心功能、主要优势和系统架构，从而清晰地认识到它在基础设施管理方面的价值。

发布说明

本文档详细记录了 AIGNE Hub 的所有重要变更、新功能和错误修复。DevOps 和 SRE 团队可利用这些信息来跟踪平台的演进，了解每次更新的影响，并据此安排升级。

AIGNE Studio

用可视化方式搭建 LLM 工作流和 AI agent，不需要写代码。

介绍

概览

入门指南

概览

启动 AI Studio

在开始之前，您需要安装 DID 钱包，您可以参考 https://support.didwallet.io/howToDownload 完成钱包的下载安装。

AIGNE WebSmith

建在 AIGNE Framework 上的网站生成工具，由 AI 驱动。

高级功能

掌握了生成和更新网站的基础知识后，您可以探索 AIGNE WebSmith 的高级功能，以实现更精细的控制，并添加独特而强大的视觉元素。本节将介绍如何管理组件库以及如何利用专用组件来构建更具动态和吸引力的页面。

使用自定义组件库

由 AIGNE WebSmith 生成的网站是由一个预先设计的、称为组件的可视化元素库构建的。虽然 WebSmith 包含一套标准组件，但您可以使用 Pages Kit 项目来定义和管理自定义组件库。这允许根据您的特定需求量身定制设计和功能。本节将介绍如何使用 component pull 命令，将

使用特殊组件

AIGNE WebSmith 包含一个特殊组件库，旨在以最少的配置为您的网站添加强大的视觉和交互元素。这些预构建的组件处理复杂的功能，让您能够高效地创建引人入胜的用户体验。

终端播放器

终端播放器是一个专用组件，用于在您的网站上显示可交互的、预先录制的终端会话。该组件是演示命令行指令、展示软件安装过程或以清晰、可重放的格式引导用户完成技术流程的有效工具。

快速入门

本指南是您快速搭建可用网站的最佳路径：安装 AIGNE CLI、收集源材料、运行 aigne web generate、批准计划并审查生成的页面——所有操作一站式完成。

指南

需要管理您的日常网站运营吗？本部分提供了常见操作的分步指南，例如创建网站、发布更新、管理翻译以及自定义外观和风格。请遵循这些教程，以确保您的网站顺利运行。

清理工作区

本指南将指导您安全地运行 aigne web clear，无论您是想清除生成的页面、重置缓存数据，还是在移交项目前移除授权令牌。

创建网站

使用本指南，只需一个命令即可将您的源材料转换为可上线的网站。您将检查可用的 aigne web generate 标志，批准 AI 生成的站点地图，并了解完成的页面在磁盘上的存放位置。

自定义主题

统一的颜色、字体和间距能让您的网站显得更专业。本指南将详细介绍如何借助 AI 生成新的 WebSmith 主题，并将其应用到您的线上网站。

交互模式（测试版）

注意：交互模式目前处于测试阶段。虽然功能齐全，但您可能会遇到意外行为。在我们不断改进此体验的过程中，我们非常感谢您的反馈。本指南将引导您启动 aigne web chat，用自然语言与 WebSmith 对话，并让助手代您触发生成/更新/发布操作。chat 命令提供了一个交互式的对话界面，用于构建

本地化网站

使用本指南运行 aigne web translate，选择您想要的页面和语言，并保存本地化版本，以便与您的主站点一同发布。

管理偏好设置

本指南将指导您如何配置 aigne web prefs，包括如何列出已保存的规则、启用或禁用它们，以及移除不再需要的条目。

Publish Website

网站生成后，最后一步是让它在线可访问。本指南涵盖了使用 AIGNE WebSmith 发布网站的各种方法，确保您可以选择最适合您技术和预算要求的选项。

发布到现有网站

本指南将向您展示如何发布到您已运营的 ArcBlock 驱动的网站。发布到您自己的基础设施可以让您完全控制托管、集成和部署。在继续之前，请确保您的网站兼容且配置正确。

发布到新的专用网站

本指南将引导您创建并发布到全新的专用网站。这是一项付费服务，提供完全托管的环境，支持自定义域名和专用资源——非常适合专业项目。整个过程完全自动化：运行命令，完成一次性设置和支付，您的网站即可上线。

发布到 WebSmith Cloud

本指南将引导您发布到 WebSmith Cloud——一个免费托管服务，让您的网站公开可访问而无需管理任何基础设施。这是新用户的推荐起点，非常适合开源项目、个人作品集或社区网站。

添加页面

使用 AIGNE WebSmith 可以轻松扩展您的网站。本指南将说明如何使用 aigne web add-page 命令将新页面无缝集成到您的网站结构中，并自动更新内容和内部链接。

更新网站

使用本指南选择正确的更新工作流程，然后深入了解关于结构或页面级变更的详细子指南。

管理更新历史

本指南将指导您审计 WebSmith 所做的所有更改。aigne web history 命令会记录每一次生成或更新操作，因此您始终可以了解更改了什么、何时发生以及为何应用了反馈。

移除页面

需要清理您的网站结构吗？本指南将说明如何使用 aigne web remove-page 命令安全地删除页面，自动查找由此产生的任何损坏链接，并重新生成受影响的内容以保持网站的完整性。

更新页面

当您需要对单个页面运行 aigne web update 时——重写部分内容、插入新模块、重新排序区块或删减过时内容——而不想更改网站的其余部分，请使用本指南。

更新结构

当您想在批准计划前使用 aigne web generate 重塑站点地图（例如添加或删除页面）时，请遵循本指南。

概述

本文档对 AIGNE WebSmith 进行了高层级的介绍。阅读完毕后，您将了解其核心目标、关键功能以及用于自动化创建专业网站（从初始规划到最终发布）的基础工作流程。

参考

本部分为 AIGNE WebSmith 提供了详细的技术资料，专为寻求有关命令、配置选项、素材准备和许可的特定深度信息的用户设计。如需实用的分步指南，请查阅入门指南或指南部分。

命令参考

本参考列出了 AIGNE WebSmith CLI 的所有可用命令，包括别名、参数和使用示例。

配置参考

config.yaml 文件是您网站生成的核心控制面板。理解其设置，可以帮助您定制 AI 输出的方方面面，从页面结构到内容基调。本指南提供了完整、逐字段的参考，以帮助您精确地修改您的网站。

准备材料

优秀的网站始于运行 aigne web generate 之前。本指南为您提供了一份具体的清单，用于收集简报、源文档和证明材料，以便 WebSmith 能够构建出反映您需求、引用正确证据并减少修订周期的页面。

问题排查

本指南帮助你诊断和修复使用 AIGNE WebSmith 时的常见问题。如果在生成、发布或配置过程中遇到问题，请查看以下场景的解决方案。

发布日志

本文档记录了 AIGNE WebSmith 的所有版本更新，包含新功能、错误修复和其他变更，按版本以降序时间顺序组织。

ARC CLI

ARC 的命令行：在终端里声明、构建、部署和检查一个站点或一个 Blocklet。

arc afs

arc afs 是 AFS 文件系统操作的命令组：列目录、读写文件、删除、搜索，执行 action，以及管理挂载。

arc attach

arc attach 把本地目录反向挂载进一个远程 arc daemon，当成一个 provider 暴露出去，让一台你没有 shell 权限的机器能通过 AFS 读到你本地的文件。

arc blocklet

arc blocklet 覆盖 blocklet 包和实例的整个生命周期：脚手架、构建、检查、列表、单个部署，或者整队部署。

arc collections

arc collections 是 blocklet.yaml 里 collections: 声明的编写工具——目前能做的是扫描 content/ 帮你生成这段片段。

arc completion

arc completion 把 bash / zsh / fish 的补全脚本打到 stdout——它自己从不写文件，落地成文件是你自己控制的一步。

arc deploy

arc deploy 注册或发布一个 blocklet：本地跟 daemon 注册用于开发，或者发布到 DID Space（本地或远程）用于真正的分发。

arc did

arc did 管理身份与信任：生成 DID 身份、签发和验证可验证凭证，以及管理你信任哪些签发方。

arc drain

arc drain 是一个长驻进程，盯着工作台账（work ledger），把就绪的工作派给一个空闲 peer，直到就绪集合清空为止。

arc dsl

arc dsl 校验、检查、格式化、生成、检视 AUP DSL 相关的产物，pages/layout.aup 这类文件用的就是这套语言。

arc mcp

arc mcp 把 stdio 桥接到运行中 AFS daemon 的 MCP endpoint，让 Claude Desktop 或任何 stdio MCP 客户端能跟 AFS 对话。daemon 没跑的话会自动启动。

arc network

arc network doctor 从这台机器上探测代理发现、DNS、HTTPS 和 WebSocket 连通性，每一项检查单独成行报告。

arc provider

arc provider 处理 provider 包相关的操作，目前是把一个 provider 的 AUP 资源树发布到 Cloudflare Pages，让它能通过 URL 被引用。

arc serve

arc serve 通过 HTTP 或 MCP 启动一个 AFS 服务，让 CLI 之外的东西（浏览器、agent、MCP 客户端）能通过网络和你的 AFS 实例对话。

arc service

arc service 管理具名 AFS 后台实例：list、start、stop、restart、status、delete、gc、url、logs。

arc skill

ARC 内置 how-to booklet：list、按名 show、装进宿主 .agents/.claude skills。尚不是 gh skill 式包管理，也不盘点 AFS /.skills。

arc space

arc space manages local DID Space data: inspecting what's stored, moving data between two subtrees with a single sync command, and claiming, checking and repairing folder-backed spaces.

arc upgrade

arc upgrade 把 arc 本身升级到最新发布的版本，或者升级/降级到指定的固定版本。

arc vault

arc vault 是加密密钥存储：先 init 一个 vault，然后按 group/name 组织，get/set/list/delete 密钥。

退出码

每条 arc 命令都用退出码报告结果——0 表示成功，另有七个各不相同的非零值（其中一个已预留但还没有产出）——脚本不用读报错文本就知道遇到的是哪一类失败。

安装

用官方安装器装上 arc，再读一遍它打印出来的版本行。

概览

arc 是操作 ARC 运行时实例的命令行工具：AFS 文件系统、身份与信任、密钥、部署、AUP DSL，都通过它来管理。

ArcBlock 招聘

ArcBlock 的职位信息。

ArcBlock 媒体资源

ArcBlock 的媒体素材说明。

AIGNE Logos

All image resources

ArcSphere Logos

全部品牌资源 zip

DID Logos

所有图像资源

ArcBlock Logos

所有媒体素材资源

Payment Kit 指南

Payment Kit 的使用说明：核心功能一览。

如何配置其他支付方式

本指南介绍如何为兼容 EVM 的链配置其他付款方式。 1. 添加 EVM 链支付方式导航至：支付管理 → 设置 → 添加支付方式接着，输入以下内容：名称：链名称，例如“Ethereum” 或 “Base”。描述：该网络的简短描述（例如，“Polygon 是一个可扩展的以太坊二层网络”）

开发指南

概览

如何开启打赏功能?

@blocklet/payment-react 提供了一个强大的打赏功能，通过 CheckoutDonate 组件和可选的 DonateProvider，开发者可以轻松为文章、内容或其他服务添加打赏支持，与 Blocklet 的支付基础设施无缝集成。本指南将详细介绍如何启用打赏功能，包括安装依赖和

如何为 Launcher 应用开启透支保护

订阅守护服务是确保订阅服务连续性的重要工具，即使扣费失败也能避免服务中断。以下是开启该功能的具体操作步骤。步骤 1：访问应用管理页面打开 Launcher 应用管理页面，查看您的所有应用。在此页面可以选择需要管理的应用。步骤 2：进入订阅详情找到需要开启订阅守护服务的应用，点击管理订阅

Payment Kit 事件监听机制

Payment Kit 提供两种事件监听方式，让您能够及时响应系统中的各类事件。

自定义通知处理指南

Payment Kit 支持应用方自行处理通知，提供两种配置方式。

欢迎使用 Payment Kit

Payment Kit 是 ArcBlock 推出的一款功能强大的支付解决方案，专为开发者设计，帮助他们在应用中快速实现多样化的支付功能。无论是创建产品、生成支付链接，还是打造高级支付体验，Payment Kit 都能提供灵活而高效的支持。

安全

- How to configure and enable the Vault Wallet

用户指南

- Enable SubGuard™ for subscriptions?

如何为应用配置并启用冷钱包（Vault Wallet）

1. 冷钱包（Vault Wallet）的核心作用

AI 应用工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io

Android 开发工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io

JS 全栈工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io 工作职责 💡 根据个人能力、兴趣可以选择参加下面的任意多项工作设计和实现面向用户的产品功能，交付高质量的、用户体验流畅的 WEB应用，甚至跨端应用参与 Blocklet Server 内核功能、控制台功能的设计、实现和交付，确

HR 助理（已招满）

工作地点：中国大陆（远程工作）职位概述：我们正在寻找一位充满热情和专业的 HR 助理加入我们团队。该职位的主要职责是协助处理日常招聘事务，包括但不限于简历筛选、候选人沟通、面试协调等任务。我们期望您能够积极主动地与团队合作，确保招聘流程的高效和顺畅。主要职责：与外部招聘服务提供商（比如电鸭社

iOS 开发工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io 岗位职责设计和实现面向用户的产品功能，交付高质量的软件，包括但不限于：DID Wallet iOS 版本, DID Wallet iOS SDK 优化各个项目的交付流水线和自动化水平为我们的客户和合作伙伴提供技术支持能力要求有

工作机会

为什么加入 ArcBlock？

JS 后端工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io 岗位职责设计和实现面向用户的产品功能，交付高质量的、高性能的、安全的后端服务参与 Blocklet Server 内核功能的讨论、设计、实现和交付，提供稳定、高性能的应用运行时参与 Blocklet Launcher 功能的设

我们的招聘流程如何？

成功加入 ArcBlock 需要经历哪些步骤？如何准备？可以看看 CEO 老冒亲笔写的两篇文章：

服务运维工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io 岗位职责梳理和实施全面且自动化的线上服务数据收集、监控、报警流程负责线上服务器中 Blocklet Server 的日常运维，比如升级、诊断负责自动化、标准化的线上服务数据、团队代码和知识库备份负责线上服务的日常安全防护，比如

UI/UX 设计师（已招满）

工作地点：远程工作（中国大陆优先）主要职责负责设计用户界面和优化用户体验，确保我们的产品直观、易用且富有吸引力与多名开发同事密切合作，共同推进项目落地参与 ArcBlock UX Library 建设，构建体验优良的业务层组件库对现有产品提出建议并提出可行的设计解决方案能力要求热爱自

WEB 前端工程师（已招满）

对这个职位感兴趣的请简历发到： hr@arcblock.io

ArcBridge Node

无需信任第三方的跨链组件，用于资产跨链转移。

How to add stake for your node?

Login to your ArcBridge Node, and open "Stake" page Click "Add Stake" on the Stake page Input stake amount in the stake dialog: Complete the stake wit

Join ArcBridge

You can join ArcBridge by just run the following blocklet:

ARC 架构

ARC 架构的开发者文档：AFS、AFS UI、AUP、Web Device、Blocklet、身份、数据空间，以及产品沿革的边界。

AFS UI

把 AFS UI 理解为把 AFS 数据与能力投影到交互与站点 UI 的架构视角，而不是与 AUP、Web Device 并列的第三套 authoring board。

ARC 与 AFS

把 AFS 当作路径与能力层，把 ARC 当作承载挂载、Blocklet 与 CLI 入口的运行时外壳。

合同与证据

把 ARC 文档陈述分为当前合同、架构、实验性或沿革，并明确每种状态需要的证据。

心智模型

用一张简短术语图理解 ARC 架构，再打开真正拥有该任务的 board。

ARC 架构

在进入具体开发指南前，先定位 AFS、AFS UI、AUP、Web Device、Blocklet、身份与 Data Space 的关系。

产品层次

判断任务属于 AFS、AFS UI、AUP、Web Device、Blocklet 还是身份层，并保持各自合同分离。

产品沿革与边界

把旧 ArcBlock 产品名映射到当前 ARC 归属，不承诺完整功能等价。

参考

架构术语索引，以及指向 AFS、AUP、Web Device、Blocklets、Identity 与 ARC CLI board 的链接。

AUP

ARC 里 AUP 的编写、校验和运行时行为的开发者文档。

用 DSL 编写

把 DSL 当作 AUP 的 source-first 编写层，并明确生成 JSON 的兼容边界。

调用者身份与安全

UI tree 可以表达意图，但身份、path scope、写权限和嵌入信任仍是独立的 server-side 决定。

AUP 能力导览

走查 web slideshow 作为 AUP 宿主：18 个 primitive + widget（需要时用 readonly shell）、Markdown 表面与 deck 媒体宿主。硬排除仅 rtc 与 camera-preview。

CLI 诊断参考

选择真正回答问题的诊断；没有一条绿灯等于浏览器或设备验收。

核心概念

从语义 tree、事件、session 与 capability 理解 AUP，而不从某个 renderer 倒推协议。

自定义 primitive 与 Web widget

区分可移植 primitive 与 Web widget，也区分 custom 名称被接受和每个 target 都有实现。

设备能力与降级

由设备报告实际 primitive 能力，再按 AUP 的显式降级链处理有限 target。

App、page 与 shell

声明紧凑的 app manifest，并把 shell、page discovery 与命名导航留在一份可审阅的 source 边界中。

组件、循环与 i18n

用 compile-time component 与 loop 组织 source；用 runtime list 和 locale contract 处理数据与语言。

事件、导航与可见性

用当前 DSL sugar 写 click、命名页导航和局部更新，并保持 visible 的版本边界。

生成、lint 与迁移

保持 DSL source 可读，验证其语义；只有兼容消费者确实需要时才物化 JSON。

DSL 语言参考

按编写层次导航 DSL，再用 compiler 与 validation 确认目标版本的精确 grammar。

节点、值与 sugar

用可读的 node sugar 表达作者意图，同时知道它会编译成哪种语义 AUP node。

DSL 来源模型

区分可编辑 DSL 来源、自动生成 artifact 与仍然使用它们的兼容消费者。

事件、状态与绑定

区分读取、写入、server-managed prop binding、UI 状态和用户事件。

示例：AFS 数据绑定

用 DSL Showcase 的 list-template source 区分 runtime AFS list 和 compile-time loop，再在实际 target 核验 scope。

示例：交互流程

用 DSL Showcase 的 overlay source 思考多步交互，同时把 source 证据和 target acceptance 分开。

示例：本地状态与事件

把当前 DSL Showcase 的 `set-sugar` source 当作 source-level state/event 例子，而不是已部署行为保证。

示例：最小 app

把已验证的 `minimal-app` recipe 当作有边界的端到端路径，而不是纯协议文件脚手架。

示例：Web layout

用已验证的 Web Device first site 作为静态 Web layout 例子，不把它写成通用 interactive-renderer 声明。

示例与证据

用注册路由、源码和明确的证据边界选择 Showcase 与 recipe 例子。

建立第一个 AUP app

用 minimal-app recipe 建立一条已验证的 ARC AUP 起步路径。

Frame、bridge 与嵌入 surface

只有信任、origin 与 runtime 边界明确时才使用 frame、bridge 与 surface。

起步

从最小完整 app 开始，建立、检查、运行并查看 AUP。

live 示例：范围与合同

让文档保持只读，同时在同一份 reference page 中放入 source、runtime output 与精确的验收边界。

节点、事件与消息参考

使用小而清晰的语义 node 合同，并把编写语义与 renderer transport 细节分开。

AUP 在 Web Device 中

区分 AUP 的静态 HTML tree 渲染、页面 layout 组合与 Web Device 的站点职责。

AUP

用 AUP 描述界面，用 DSL 编写来源，并由 ARC 在目标设备上运行。

Patch、scene 与 capability 参考

理解 render-first 更新、目标报告的 capability，以及刻意保持很窄的 degradation 合同。

Primitive 类型分类与证据

区分 18 个跨设备 primitive、42 个 Web-only widget，以及目标实际报告的能力。

AUP primitives

每个跨设备 AUP primitive 一页：合同、document 能力、fallback 与 sample 边界。

`action` primitive

声明按钮或导航 action，不在 document target 上承诺 exec。

`afs-list` primitive

afs-list 列出 AFS 支撑的条目；document 可渲染空态或静态子节点，但 live 路径数据合同尚未闭环。

`calendar` primitive

calendar 是结构化日期表面；document 为 unsupported，可能降级为 table 或 text。

`canvas` primitive

canvas 是绘制表面意图；document 为 unsupported，向 media 或 text 降级。

`chart` primitive

chart 是 full-web 上的跨设备 primitive；静态文档不得声称 live chart。

`chat` primitive

chat 是面向 session 的 primitive；document 没有 chat 能力 chain。

`editor` primitive

editor 可在 document 上渲染为本地 textarea；不要承诺可写 IDE 或 AFS 回写。

`explorer` primitive

explorer 是 list/stat/preview 表面的组合模式，不是 document widget。

`input` primitive

在 document 上编写未绑定表单控件；不要在 docs 页放入 bind 与写入路径。

`map` primitive

map 是地理表面的可移植意图；document 为 unsupported，向 media 或 text 降级。

`media` primitive

用可移植 media primitive 绑定 image / video / audio / avatar，并提供 docs-safe 的 live 图片 sample。

`overlay` primitive

overlay 留给交互 session；document 报告 unsupported，并沿 chain 向 text 降级。

`rtc` primitive

rtc 依赖媒体权限；共享 chain 以 unsupported 结束。

`surface` primitive

surface 是跨设备挂载意图；不要与 Web Device layout surface 混淆。

`table` primitive

用 table primitive 呈现列式数据；区分 GFM 表与 chart 降级表。

`text` primitive

用可移植 text primitive 表达可读文案、标题与 admonition。

`time` primitive

以 partial document 支持展示时间值；不要在静态 docs 中承诺 live 时钟。

`view` primitive

用可移植容器 primitive 表达结构、tabs 与 steps，不要把它当成 layout.aup 的站点 section。

产品层次与适用范围

先判断任务属于 AUP 语义、DSL 编写、renderer，还是 Web Device 站点。

参考

按当前版本查阅 AUP 节点、补丁、支持矩阵、DSL 与产物边界。

发布与兼容性

把 CLI/runtime、source checkout、生成 artifact 和 Showcase material 当作独立的兼容证据。

Renderer、session 与支持范围

把可加载 source、可由目标呈现的 tree，以及已经实际验收的交互分开。

在 ARC 中运行

说明 AUP 怎样进入 renderer、session 与具体设备表面。

语义 tree

用稳定 id、type、props、binding 和 children 描述界面意图，而不是某个设备的像素。

Session、patch 与 scene

把交互式整 tree 渲染、增量 patch 与设备上下文分开理解。

来源、artifact 与 JSON 兼容性

区分 ARC 实际读取的 source 和生成出来的兼容产物，但不把它们误写成两套 UI 模型。

验证、运行与查看

格式化、检查并直接运行 minimal-app，在浏览器中验收 AUP。

AUP Web-only widgets

全部 42 个 AUP_WIDGETS 条目的导航 hub——一页一 widget；不是多 widget 正文参考。

afs-dropzone

AUP Web-only widget `afs-dropzone`：用途、边界、表面、fallback 与证据。

afs-preview

AUP Web-only widget `afs-preview`：用途、边界、表面、fallback 与证据。

afs-stat

AUP Web-only widget `afs-stat`：用途、边界、表面、fallback 与证据。

agent

AUP Web-only widget `agent`：用途、边界、表面、fallback 与证据。

app-footer

AUP Web-only widget `app-footer`：用途、边界、表面、fallback 与证据。

app-header

AUP Web-only widget `app-header`：用途、边界、表面、fallback 与证据。

auto-fire

AUP Web-only widget `auto-fire`：用途、边界、表面、fallback 与证据。

auto-surface

AUP Web-only widget `auto-surface`：用途、边界、表面、fallback 与证据。

block-revealer

AUP Web-only widget `block-revealer`：用途、边界、表面、fallback 与证据。

blocklet-embed

AUP Web-only widget `blocklet-embed`：用途、边界、表面、fallback 与证据。

breadcrumb

AUP Web-only widget `breadcrumb`：用途、边界、表面、fallback 与证据。

broadcast

AUP Web-only widget `broadcast`：用途、边界、表面、fallback 与证据。

camera-preview

AUP Web-only widget `camera-preview`：用途、边界、表面、fallback 与证据。

chip

AUP Web-only widget `chip`：用途、边界、表面、fallback 与证据。

comments-surface

AUP Web-only widget `comments-surface`：用途、边界、表面、fallback 与证据。

deck

AUP Web-only widget `deck`：用途、边界、表面、fallback 与证据。

entity-overview

AUP Web-only widget `entity-overview`：用途、边界、表面、fallback 与证据。

finance-chart

AUP Web-only widget `finance-chart`：用途、边界、表面、fallback 与证据。

frame

AUP Web-only widget `frame`：用途、边界、表面、fallback 与证据。

globe

AUP Web-only widget `globe`：用途、边界、表面、fallback 与证据。

hero-widget

AUP Web-only widget `hero-widget`：用途、边界、表面、fallback 与证据。

key-value-list

AUP Web-only widget `key-value-list`：用途、边界、表面、fallback 与证据。

moonphase

AUP Web-only widget `moonphase`：用途、边界、表面、fallback 与证据。

natal-chart

AUP Web-only widget `natal-chart`：用途、边界、表面、fallback 与证据。

pagination

AUP Web-only widget `pagination`：用途、边界、表面、fallback 与证据。

photo-story

AUP Web-only widget `photo-story`：用途、边界、表面、fallback 与证据。

post-editor

AUP Web-only widget `post-editor`：用途、边界、表面、fallback 与证据。

progress-bar-3d

AUP Web-only widget `progress-bar-3d`：用途、边界、表面、fallback 与证据。

scroll-explainer

AUP Web-only widget `scroll-explainer`：用途、边界、表面、fallback 与证据。

searchable-dropdown

AUP Web-only widget `searchable-dropdown`：用途、边界、表面、fallback 与证据。

skills

AUP Web-only widget `skills`：用途、边界、表面、fallback 与证据。

terminal

AUP Web-only widget `terminal`：用途、边界、表面、fallback 与证据。

text-highlight

AUP Web-only widget `text-highlight`：用途、边界、表面、fallback 与证据。

text-image-expand

AUP Web-only widget `text-image-expand`：用途、边界、表面、fallback 与证据。

ticker

AUP Web-only widget `ticker`：用途、边界、表面、fallback 与证据。

tooltip

AUP Web-only widget `tooltip`：用途、边界、表面、fallback 与证据。

type-block

AUP Web-only widget `type-block`：用途、边界、表面、fallback 与证据。

url-default

AUP Web-only widget `url-default`：用途、边界、表面、fallback 与证据。

webgl-hero

AUP Web-only widget `webgl-hero`：用途、边界、表面、fallback 与证据。

wm

AUP Web-only widget `wm`：用途、边界、表面、fallback 与证据。

wm-surface

AUP Web-only widget `wm-surface`：用途、边界、表面、fallback 与证据。

xeyes

AUP Web-only widget `xeyes`：用途、边界、表面、fallback 与证据。

区块链指南

ArcBlock 区块链的使用说明：功能与帮助。

区块链 SDK（Node.js）

@ocap/client 是把应用连到 OCAP Chain 的客户端库，可用于 Node.js 和浏览器。

API 参考

欢迎来到 OCAP Client API 参考。本节为所有可用的类、方法和数据类型提供了一个全面且可搜索的参考。无论您是在寻找 GraphQL 方法的细节、交易辅助函数的参数，还是响应对象的结构，您都可以在这里找到所需的详细信息。

辅助方法

GraphQLClient 类是与 OCAP 驱动的区块链进行交互的主要接口。它提供了一套全面的方法，用于查询链状态、发送交易以及订阅实时事件。它被设计为可以在 Node.js 和浏览器环境中无缝工作。

数据类型

本节为 OCAP 客户端 API 中使用的所有自定义数据结构、输入参数和响应对象提供了全面的参考。理解这些类型对于有效与 OCAP 区块链交互至关重要。

底层 API

底层 API 提供了对整个交易生命周期的精细控制。与对细节进行抽象的高级 API 不同，这些方法允许您手动构建、编码、签名和发送交易。这对于高级场景非常理想，例如多重签名工作流，其中不同方需要在交易广播前对其进行签名。

查询与变更方法

OCAP Client 通过 GraphQL 与区块链进行交互。其方法主要分为两类：

高级 API

交易助手是 OCAP Client 内置的高级函数，它抽象了创建和签署常见交易的复杂性。您无需手动构建交易对象，而是可以使用这些便捷方法来处理创建资产、转移通证、质押和执行原子交换等工作流。这些助手可确保交易结构的正确性，并显著简化开发过程。

核心概念

本节深入探讨了构成 OCAP Client 库的基本原则和架构决策。理解这些核心概念将帮助您充分发挥该库的潜力，编写更高效的代码，并更有效地排查问题。

客户端架构

OCAP 客户端采用模块化架构设计，以满足不同 JavaScript 环境和特定用例的需求。它并非提供一个“一刀切”的库，而是提供了多种客户端实现，每种实现都针对特定上下文进行了优化，例如 Node.js 后端或对包大小敏感的 Web 应用程序。这种方法让您可以根据需要选择最高效的客户端，从而在必要

事件订阅

OCAP Client 提供了一个强大的实时事件订阅系统，允许您的应用程序实时监听链上活动。该功能基于 WebSocket 构建，提供与区块链节点的持久连接，无需通过持续轮询来检查更新。

Gas 费支付

在大多数区块链系统中，每笔交易都需要发起者支付一笔费用，通常称为“Gas 费”。对于可能没有原生货币来支付这些费用的新用户来说，这可能是一个巨大的障碍。OCAP 客户端引入了 Gas 费支付功能，允许应用开发者代付这些费用，从而为他们的用户创造无缝的“无 Gas 费”体验。

交易生命周期

每一个修改区块链状态的操作，例如转移通证或创建资产，都是通过交易来执行的。理解交易的生命周期是使用 OCAP 客户端构建应用程序的基础。此过程涉及四个主要阶段：准备、编码、签名和发送。

快速入门

欢迎！本指南将帮助您在 30 分钟内快速上手 OCAP Client。您将学习如何安装该客户端，将您的应用程序连接到兼容 OCAP 的区块链，并进行您的第一次 API 调用以验证您的设置。

基本用法

本指南将引导您完成 OCAP Client 的基本入门步骤。您将学习如何初始化客户端、连接到 ArcBlock Beta Chain，并执行基本查询以确保一切设置正确。

安装

OCAP Client 是一个 JavaScript 库，可将您的应用程序连接到 OCAP 区块链。它同时适用于 Node.js 和浏览器环境。本指南将引导您使用包管理器安装该客户端。

操作指南

本节提供使用 OCAP 客户端完成常见任务的实用分步说明。每篇指南都设计成一个独立的教程，旨在帮助您实现特定目标，从管理账户到执行复杂的原子交换。

委托权限

委托权限是一项强大的功能，它允许一个账户（委托人）授权另一个账户（受托人）代表其发送特定类型的交易。这对于需要为用户执行操作但又不想直接访问用户主私钥的应用程序尤其有用。例如，您可以将权限委托给特定于应用程序的密钥，以转移某些资产或与智能合约进行交互，通过限制该密钥的权限范围来增强安全性。

管理账户

在由 OCAP 驱动的区块链上，账户本质上是与一个地址关联的状态，由一对加密密钥（公钥和私钥）控制。一个需要理解的关键概念是，账户是隐式创建的。一旦账户收到第一笔入账交易（例如代币或资产转移），它就正式在链上存在了。没有显式的 createAccount 交易。

管理资产 (NFT)

本指南将全面介绍如何使用 OCAP Client 管理非同质化代币 (NFT)，也称为资产的整个生命周期。您将学习如何从零开始创建新资产、更新其属性、建立用于标准化铸造的资产工厂，以及如何从该工厂获取新资产。

管理通证

本指南提供使用 OCAP Client 管理同质化通证的分步说明。您将学习如何设置通证工厂（它作为您通证的蓝图），然后用它来铸造（创建新通证）和销毁（销毁现有通证）。这些操作是在您的应用程序中创建和管理自定义经济体系的基础。

质押通证和资产

质押是将通证或资产 (NFT) 锁定给特定接收者的过程，通常是为了保障网络安全、参与治理或赚取奖励。本指南使用 OCAP Client 详细介绍了整个质押生命周期的分步操作，包括创建质押、撤销质押、领回资产以及因惩罚性原因罚没质押。

转移通证和 NFT

本指南将逐步引导您使用 OCAP Client 在账户之间转移可替代通证（包括原生通证和自定义通证）和非替代通证（NFT 或资产）。所有转移操作的主要方法是 client.transfer()。

概述

OCAP Client 是一个功能强大且通用的 JavaScript 库，旨在将您的应用程序连接到由 OCAP 驱动的区块链。它提供了一个精简、对开发者友好的界面，用于读取和写入数据、管理数字资产以及监听链上事件。该客户端可用于任何 Node.js 或基于浏览器的环境，为后端服务和前端应用程序提供统

区块链工具库

处理钱包、大数和 DID 的工具库。

@arcblock/did

该软件包提供了一个 JavaScript 库，用于处理 ArcBlock 的去中心化身份（DID）协议。它允许你创建、管理和验证 DID，这对于在 OCAP 平台上构建应用程序至关重要。本节介绍了该库的基本功能。

API 参考

本节为 @arcblock/did 库中的所有公共函数和类型提供了全面的 API 参考。它包括用于创建、验证和检查去中心化身份（DID）等常见任务的实用、可直接复制粘贴的代码片段。

核心概念

本节解释了 ArcBlock 去中心化身份（DID）背后的基本概念。在 ArcBlock 生态系统中，DID 不仅仅是一个标识符；它是一个自包含、自描述的实体，内嵌了自身的加密属性。这种设计实现了一个通用且可互操作的身份系统。

入门指南

本指南提供了一个快速、分步的演练，帮助您启动并运行 ocap-libs。只需几分钟，您将安装必要的软件包，创建您的第一个去中心化身份（DID），生成一个兼容的加密钱包，并学习如何使用一些有用的工具函数。

概述

欢迎阅读 OCAP 库的官方文档，这是一个用于构建去中心化身份应用的综合套件。本指南提供了将强大的、自主主权的身份功能集成到您的应用中所需的一切。其核心是三个主要包：@arcblock/did、@ocap/wallet 和 @ocap/util。它们共同提供了一个完整的工具集，用于在去中心化环境中创

@ocap/util

@ocap/util 包是一个基础库，提供了一系列在多个 OCAP JS 库之间共享的基本辅助函数。它被设计成同构的，可以在 Node.js 和浏览器环境中无缝工作。该模块简化了数据类型转换、编码/解码、大数算术和联合曲线计算等常见任务，确保了应用程序的一致性和可靠性。

API 参考

这是 @ocap/util 包中所有可用工具函数的综合参考。它为数据转换、大数算术、UUID 生成和联合曲线计算提供了实用示例。

@ocap/wallet

该软件包提供了创建和使用与 OCAP 兼容的加密钱包的实用函数。生成的钱包还与 ArcBlock 的去中心化身份（DID）系统兼容，使您能够无缝管理加密密钥、签署消息和验证签名。

API 参考

本节提供了 Wallet 对象及其工厂函数的详细文档。您将找到每个函数的描述、其参数、返回值，以及用于创建钱包、签署消息和验证签名等常见操作的实用代码示例。

核心概念

本节介绍 @ocap/wallet 包背后的基本概念。你将了解什么是钱包对象、其结构、创建它的不同方式，以及它与去中心化身份 (DID) 的关键关系。

Conceptual Guides

- Understanding DIDs

Frequently Asked Questions

How the documentation is organized?

Getting Started

If you are an intermediate or advanced javascript developer, you can start from Send first transaction.

How-to Guides

- Create Account

Reference Guides

- Working with DIDs

Setup Node.js

About why Node.js is required and how to install Node.js please refer to Blocklet Developer Guide

Create Account

An account is a data entry that's stored in the chain ledger, on-chain accounts are controlled by off-chain wallets, see understanding accounts and w

Create Token

此文档描述如何从 ArcSwap 界面上创建 Token。

Query Accounts

Query account by address

Query NFT

Query NFT State

Query Transactions

The listTransactions query allows you to fetch a list of transactions on the blockchain based on various criteria. This can be useful for monitoring s

Send first transaction

In this tutorial you will learn how to connect to a running chain and send your first transaction.

迁移指南

- Upgrade from 1.18.x to 1.19.x

Transaction Types

Account Related

Understanding DIDs

What is DID?

Understanding NFTs

We use the term NFT and Asset interchangeably throughout this documentation because they mean the same thing on the ArcBlock chain. What is NFT? NFTs

Understanding Tokens

What is token?

Understanding Transactions

A transaction must be encoded and signed by the sender's wallet, once sent to the chain, it's decoded and verified, and then executed and appended to

理解可验证的凭证

学习经过验证的凭证的基本概念、心理模型、使用案例和好处，了解其与 NFT 之间的区别。

Understanding Wallets and Accounts

What is Wallet?

从 1.18.x 升级到 1.19.x

ArcBlock 的区块链在 v1.19.x 增加了原生的 Passkey 支持，意味着 Passkey 可以在区块链上有对应的账户，可以像其他账户一样签名和发送交易。

Welcome

ArcBlock blockchain is an open, secure, and extensible billing layer for the ArcBlock ecosystem, the blockchain has native DID support, and it's wide

Work with Verifiable Credentials

@arcblock/vc includes several utility functions to issue and verify verifiable credentials and their presentations.

Working with DIDs

Utility functions to create/inspect did, and do did-based auth, an implementation of abt-did-protocol

Blocklet CLI

@blocklet/cli 的开发者指南，涵盖安装和各项功能。

高级主题

欢迎来到高级主题部分。虽然核心工作流涵盖了日常开发和服务器管理，但本节深入探讨了用于微调和维护您的 blocklet 的更专业的命令。这些实用程序可帮助您管理 blocklet 的去中心化身份并执行特定的清理任务。

清理 Blocklet

blocklet cleanup 命令是一个实用工具，用于对安装在 Blocklet Server 上的特定 blocklet 执行维护任务。它允许您清除 blocklet 的专用缓存或禁用其自动备份配置。

DID 文档管理

每个 blocklet 都由一个去中心化标识符（DID）来标识，该标识符与一个 DID 文档相关联。此文档包含关键的元数据，例如公钥和服务端点，允许其他服务安全地发现您的 blocklet 并与之交互。虽然 Blocklet Server 通常会自动管理此文档，但在某些情况下需要手动更新。

Blocklet 工作流

Blocklet CLI 提供了一套全面的命令，支持 Blocklet 从初始项目创建到最终分发的整个生命周期。这些工作流旨在简化开发，确保构建、测试和部署应用程序的过程顺畅高效。

组件管理

Blocklet 可以由其他 Blocklet 组成，这些 Blocklet 被称为组件。这个强大的功能允许您通过组装更小的、可复用的部分来构建复杂的应用程序。Blocklet CLI 提供了一组命令来帮助您在项目的 blocklet.yml 文件中管理这些组件依赖。

添加组件

blocklet add 命令用于将一个新组件作为依赖项添加到你的 blocklet 中。它会自动更新你的 blocklet.yml 文件中的 components 部分，并添加必要的配置。

移除组件

blocklet remove 命令提供了一种从 blocklet 的 blocklet.yml 元数据文件中移除组件依赖的直接方法。此操作会更新您的项目配置，以反映该组件不再是依赖项。

Component Studio CLI

blocklet component 命令是一个方便的代理，用于执行来自 @blocklet/component-studio-cli 包的命令。这使你可以直接从终端与 Component Studio 交互，而无需全局安装该包或手动管理其版本。

分发

在您的 blocklet 开发和打包完成后，下一步是让它可供他人安装和使用。Blocklet CLI 提供了两种主要的分发方法：直接部署到 Blocklet Server 或上传到 Blocklet Store 以供公众发现。

连接到商店

在将 blocklet 上传到 Blocklet Store 之前，您首先需要将本地 CLI 与其连接。blocklet connect 命令有助于完成一次性设置过程，该过程使用特定的商店对您的计算机进行身份验证，并在本地保存必要的凭据，以供将来执行 blocklet upload 等命令时使用。

部署 Blocklet

blocklet deploy 命令是将 Blocklet 从本地开发环境推送到正在运行的 Blocklet Server 实例的直接途径。这对于在预发布环境中进行测试或直接部署到生产环境至关重要。该命令一步即可处理项目的打包、版本控制和上传。

上传到商店

成功打包 blocklet 后，分发的下一步是将其上传到 Blocklet Store。blocklet upload 命令会将你的 blocklet 包发送到指定的商店，使其可供他人发现和安装。这是公共分发的主要方法。

本地开发

在本地开发和测试您的 blocklet 是工作流程中至关重要的一部分。Blocklet CLI 提供了一套强大的工具，可以在连接到本地 Blocklet Server 的实时重载环境中运行您的 blocklet，执行一次性脚本，并轻松调试您的应用程序。本节将介绍本地开发循环中的基本命令。

调试 Blocklet

blocklet debug 命令是一个供开发者使用的实用工具，用于在正在运行的 blocklet 上设置环境变量，主要用于启用详细日志记录和其他调试功能，而无需重新构建或重新部署。

开发模式

blocklet dev 命令是本地开发的关键工具。它以实时重新加载的开发模式运行您的 blocklet，并将其连接到正在运行的 Blocklet Server 实例。这通过自动处理 blocklet 作为临时组件的安装、启动和日志流，实现了快速迭代。

执行脚本

blocklet exec 命令是一个强大的实用工具，用于在已安装 blocklet 的实时上下文中运行脚本。这对于数据库迁移、数据填充或任何需要访问 blocklet 运行时环境变量的一次性脚本等任务来说非常有价值。

打包与版本控制

完成 blocklet 的开发和测试后，下一步是准备分发。这涉及两个关键过程：版本控制（为您的发布版本分配一个唯一标识符）和打包（将您所有的代码和资产打包成一个可部署的单一构件）。Blocklet CLI 提供了专门的命令来简化此工作流程。

打包 Blocklet

blocklet bundle 命令是开发生命周期中的关键一步。它将你的 blocklet 的源代码、资产和元数据打包到一个标准的 .blocklet 目录中，使其可供部署或分发。

管理版本

blocklet version 命令是一个方便的实用工具，用于更新 blocklet.yml 文件中的 blocklet 版本号。它遵循语义化版本（semver）规则，以确保版本号的一致性和可预测性增长。这是在打包和分发 blocklet 新版本之前执行的关键步骤。

项目设置

启动一个新的 blocklet 项目非常简单。Blocklet CLI 提供了两个主要命令来引导您的开发环境，具体取决于您是从头开始还是转换现有项目。这些命令可以帮助您生成必要的元数据文件（例如 blocklet.yml）并建立标准的项目结构。

创建项目

blocklet create 命令是启动新 Blocklet 项目的最快方法。它使用 create-blocklet，这是一个交互式脚手架工具，可让您从各种官方入门模板中进行选择。此命令是引导新应用程序的推荐方法。

初始化项目

blocklet init 命令是一个交互式实用工具，可帮助您在现有目录中为新的 blocklet 创建基本结构。它会生成核心的 blocklet.yml 元数据文件和其他必要的样板文件，将您当前的文件夹转变为一个功能性的 blocklet 项目。

命令参考

Blocklet CLI 提供了一套全面的命令，用于管理您的 Blocklet Server 实例和单个 blocklet 项目。本参考分为两大类，帮助您快速找到特定任务所需的命令。

blocklet

blocklet 命令是管理 Blocklet 项目整个生命周期的主要接口。它提供了一套全面的子命令，用于初始化、开发、打包、部署和管理 Blocklet 及其组件。

blocklet server

blocklet server 命令是管理 Blocklet Server 实例生命周期和配置的主要工具。它允许您初始化、启动、停止和监控服务器及其上运行的所有 blocklet。这些命令对于自行托管 Blocklet Server 的服务器管理员和开发人员至关重要。

配置

正确的配置对于运行 Blocklet Server 实例以及使用 Blocklet CLI 与其和其他服务进行交互至关重要。本指南重点介绍作为开发者用于连接到 Blocklet Stores 和管理开发环境的本地 CLI 设置。这些设置使用 blocklet config 命令进行管理。

环境变量

环境变量提供了一种强大的方式来配置 Blocklet Server 及其运行的 blocklet。它们会覆盖配置文件中的默认设置和值，使其成为在不同环境（如开发、预演和生产）中定制设置的理想选择。

快速入门

本指南将引导您完成让第一个 Blocklet Server 实例启动并运行的基本步骤。只需几分钟，您就可以从安装到拥有一个功能齐全的服务器。

概述

Blocklet CLI 是您管理 Blocklet Server 和开发 Blocklet 的主要工具。它提供了一套全面的命令，用于处理从本地开发和测试到打包和部署应用程序的所有事务。

服务器管理

blocklet server 命令是您管理 Blocklet Server 实例生命周期的主要工具。它允许您初始化配置、启动和停止服务器守护进程、检查其状态以及执行各种维护任务。这套命令确保您可以直接从命令行完全控制您的服务器环境。

清理服务器

blocklet server cleanup 命令是一个用于执行各种服务器级维护任务的实用工具。它通过清除缓存、重置状态或管理网络配置来帮助您解决问题，而无需停止整个服务器。

获取服务器信息

blocklet server info 命令是一个重要的诊断工具，旨在收集并显示 Blocklet Server 环境的全面摘要。它收集从硬件和操作系统详细信息到软件版本和服务器配置的所有内容，使其在调试或为支持提供系统信息时非常有价值。

初始化服务器

blocklet server init 命令通过在当前工作目录中创建一个专用的配置目录 .blocklet-server 来初始化一个新的 Blocklet Server 实例。该目录包含 config.yml 文件和运行服务器所需的其他资产。该过程可以通过引导式设置以交互方式执行，也可以使用命令

查看日志

blocklet server logs 命令是用于故障排除和监控的重要工具。它不直接显示日志内容，而是提供与 Blocklet Server 守护进程及任何已安装 blocklet 相关的所有日志文件的确切路径。这使您可以使用 cat、tail 或 less 等标准命令行工具轻松定位和检查日志。

迁移数据库

blocklet server migrate 命令是扩展 Blocklet Server 实例的关键实用工具。它有助于将服务器的底层数据库从默认的 SQLite（非常适合开发和简单设置）迁移到更强大、更具可扩展性的系统，如用于生产环境的 PostgreSQL。

启动服务器

blocklet server start 命令是启动 Blocklet Server 实例的主要方法。它会初始化并以后台守护进程的方式运行所有必要的组件，使你的服务器及其 blocklet 可被访问。

检查状态

blocklet server status 命令是监控 Blocklet Server 实例及其内部运行的所有 blocklet 健康状况的重要工具。它能快速、全面地提供整个系统的快照，从核心服务器进程到单个 blocklet 的状态。

停止服务器

blocklet server stop 命令会优雅地关闭正在运行的 Blocklet Server 实例。此过程包括停止所有正在运行的 blocklet、路由引擎、核心服务器进程以及任何关联的 Docker 容器。

升级服务器

本文档提供了将 Blocklet Server 命令行界面（CLI）升级至最新可用版本的说明。

Blocklet 平台

理解 Blocklet 平台并在它上面开发的指南。

Request Entity too Large

Blocklet Server limits file size on uploading within a certain range for efficiency considerations, since larger file uploads will consume more resour

管理 Blocklet 版本

这份文档提供了关于如何管理 Blocklet 版本控制的指南，确保发布时的一致性和清晰度。语义化版本控制 Blocklet 版本遵循语义化版本控制（SemVer）原则。 SemVer 由用点分隔的三个数字组成：MAJOR.MINOR.PATCH。主要版本号：指的是发生不兼容更改或重大功能增强时

Blocklet SDK (Browser)

Blocklet JS SDK 是 Blocklet 平台提供用于浏览器中的部分辅助工具库。

测试 Blocklet

应用创建完成后，我们可以在本地直接安装这个 Blocklet，来测试它是否满足预期。

添加组件

本文档介绍如何在您的站点中安装 Blocklet，并说明不同安装方式的特点、适用场景及注意事项。 Blocklet 提供三种安装方式：通过 Store 安装通过 URL 安装本地上传安装 1. 通过 Store 安装此方式最为简单，适合新手或希望快速安装官方推荐 Blocklet 的用户。

权限控制模型

Blocklet Service 为 Blocklet 提供的访问控制基于 RBAC(Role-based access control)

Access Key

什么是 Access Keys

Application vs Blocklet

在开始开发 Blocklet 之前，让我们首先了解什么是应用程序以及什么是 Blocklet。

如何给 Blocklet 绑定域名并且生成 SSL/TLS 证书

概述

Blocklet GitHub Actions

如果你使用的是 GitHub Actions 来管理 Blocklet 应用的打包、发布、部署等流程，那么你将在本文中更高效的 Blocklet 应用部署指南。

Blocklet CLI

Blocklet CLI 提供了用于控制和管理 Blocklet 的 blocklet 命令行工具。使用以下语法从终端运行 blocklet 命令：

理解 Blocklet 组合

This page is in draft and needs to be updated

理解 Blocklet 生命周期

This doc is a draft and needs to be updated

Blocklet SDK (Node.js)

Blocklet SDK for blocklet developers used in Node.js environments

节点架构概述

this page is a draft and need to be updated

Blocklet Server CLI

Blocklet Server CLI 提供 Blocklet Server 命令行工具，用于在本地计算机中控制和管理 Blocklet Server。使用以下语法从终端运行 Blocklet Server 命令：

节点请求流转

this page is a draft and need to be updatedTBD: Blocklet server routing pipeline

Blocklet Server 故障排查自查清单

前言

Blocklet Service

Blocklet Service 为 Blocklet 提供了一些开箱即用的服务。

存储 Blocklet 状态

Using local database

Blocklet Studio

Blocklet Studio 是什么？

创建 Blocklet

在创建 Blocklet 前，需成为 Blocklet Store 的开发者。请参阅:

删除 Blocklet

在 Blocklet Studio 列表中，您可以点击某个 Blocklet 的删除按钮以删除该 Blocklet：

上传静态资源

如果你有一些静态资源的项目，可以直接使用 Blocklet Studio 创建 Blocklet, 并且发布到 Blocklet Store 中。

Blocklet UI

Blocklet UI 是一个用于快速构建 Blocklet 的前端组件库。区别于一般的 UI 组件库，Blocklet UI 提供的组件通常需要工作在 Blocklet 环境中，在页面渲染时，Blocklet UI 会读取 Blocklet 运行时信息 (称为 Blocklet Meta), 比如

blocklet.js

什么是 blocklet.js？

blocklet.yml

DID

开发付费 Blocklet

this page is a draft and need to be updated设置价格在 blocklet.yml:payment.price 中为 blocklet 设置价格。见 blocklet.yml: price价格分成blocklet 售卖所得收入默认会按照 7:3 的比例分给商店

打包 Blocklet

简介

和 DID Wallet 通信

和 DID 钱包建立连接

概念指南

平台概览理解 Blocklet 理解 Blocklet 生命周期理解组合型 Blocklet 理解付费 Blocklet 节点架构概述节点请求流转权限控制模型

开发最佳实践

- Developing Blocklet in Docker

创建 Blocklet

Blocklet 类型

Compose Blocklets

What is Blocklet Composition?

创建 Docker 类型的 Blocklet

阅读须知：

创建第一个 Blocklet

通常我们有两种创建 Blocklet 应用的方式: Create Blocklet 和 blocklet create 命令，后者是由 @blocklet/cli 提供的一个命令，并且在前者的基础上构建而成。

How to add custom well-known URI

In some cases you may want to add custom well-known URI on your website, such as:

自定义个人中心页面

随着 Blocklet 自身的推进，极大可能会诞生一个个人中心页的需求，得益于 Blocklet 平台的可组合性，我们在设计之初已经为应用提供了多 Blocklet 个人中心页的能力。下文将详细介绍如何通过 Blocklet 组件来为整个应用注入一个定制化的个人中心页面。

抵御 CSRF 攻击

概览

部署 Blocklet

如果你是 blocklet 的开发者，或者你有 blocklet 的 release bundle, 你可以将 blocklet 直接部署到你的 Blocklet Server 中

开发 Blocklet

启动开发

在 Docker 中开发 Blocklet

当你在处于某些原因，不能或不想在电脑中直接安装 @blocklet/cli ，此时如果需要开发 blocklet，那么就会陷入困境。因为 @blocklet/cli 是开发或运行 blocklet 必不可少的工具下文将介绍如何在电脑不安装 @blocklet/cli ，而通过 Docker 来开发

使用 GitHub Codespaces 进行开发

准备 Blocklet Server

Enable Web Application Firewall

This page need to be updated Blocklet Server has opt-in support for Web Application Firewall with following open-source projects: https://github.com/o

Event Bus Service (Beta)

Event Bus service is a powerful communication system that helps your blocklet's components work together seamlessly. Imagine it as a smart messaging c

常见问题

文档是如何组织的？

入门指南

如果你是一个中级或高级开发者，并且你已经对 Blocklet 的工作原理有了基本的了解，你可以从创建第一个应用开始。

如何配置安全规则

安全规则概述

操作指南

创建应用开发应用用户和通行证和 DID Wallet 通信存储应用状态设计和使用应用偏好创建组合型应用开发组件开发付费应用应用打包发布应用部署应用到节点读写区块链数据应用管理和维护

如何将本地 Blocklet 以应用形式安装到本地的 Server 中？

问：如何将本地的 Blocklet 作为应用（而不是作为组件）直接安装到本地运行的 Server 中。答： 1. 在浏览器中访问 Server - Blocklet 列表页，点击 “安装应用” - “从 URL 安装“ 2. 将 blocklet 打包后，复制 blocklet bundle 目录

制作资源后，如何利用 URL 安装

第一步：制作资源后，点击“安装“，并复制链接

Image Service

Image Service is an image processing service embedded in the Blocklet Server, and its basic capabilities include image cropping, scaling, format conve

安装 Blocklet CLI

目前只能在 Linux(Ubuntu) 或 macOS 上安装和运行 Blocklet Server，Windows 平台下的用户请使用 Docker 来运行。Blocklet CLI 是能够同时用来管理 Blocklet Server 和 Blocklet 的命令行工具，而 Blocklet Se

集成 Blocklet Studio

ArcBlocklet 的开发者们应该都熟悉这张图，它展示了 AIGNE 如何利用 Blocklet Studio 和 Blocklet Store 形成飞轮效应。AIGNE 的用户可以创建许多应用并发布到 Store，从而反哺 AIGNE 的生态系统。事实上，任何 Blocklet 的开发者都可以

已知问题

this page is a draft and need to be updatedCluster Mode你可以在 blocklet.yml 中声明 blocklet 以 Cluster 模式运行，提升性能。capabilities: clusterMode: trueblocklet 安装后

Claude

前置检查

Cline

前置检查

Cursor

前置检查

Roo Cline

前置检查

Blocket MCP Server

Blocket 提供了官方的 Model Context Protocol (MCP) 服务器，让您能够在支持 MCP 的 AI 应用程序中访问 Blocket 数据。

Windsurf

前置检查

Witsy

前置检查

Not using 80/443 ports?

Sometimes after you initialize and start a blocklet server and find that the server is not using 80/443 ports, this may happen for several reasons:

DID Connect

开发者指南

OAuth Server

This is work in progress, will introduce more about how OAuth work in Blocklet Server 简介 Blocklet Service 可以作为 OAuth Server 服务，支持标准 OAuth 2.0 授权码模式（Au

应用管理和维护

如何自定义 Blocklet Logo

Setup with AWS EC2

Running in AWS

性能最佳实践

this page is a draft and needs to be updated

Permission Issues on Linux

Usually, it's recommended to run blocklet server as a non-root user for security reasons, and you should always use the same user that created the ser

平台概览

应用创建Create Blocklet 你的助手在创建新的 blocklet 项目或 monorepo。应用开发Blocklet Server blocklet 运行时间和管理控制台。Blocklet Services 认证和通知服务，开箱即可使用。Blocklet CLI 用于在 blocklet

发布 Blocklet

前置条件

发布 Blocklet

发布应用到 Blocklet Store

读写区块链数据

this page is a draft and need to be updated ArcBlock chain: @ocap/client Ethereum chain: web3.js

参考指南

blocklet.yml blocklet.js Blocklet 开发套件 Blocklet Service Blocklet 命令行节点命令行 Blocklet UI GitHub Actions 安全最佳实践性能最佳实践已知问题获得节点的其他方法

资源型 Blocklet

如果一个 Blocklet 仅关联了资源而未关联任何组件，则定义为资源型 Blocklet。资源型 Blocklet 是一种高级用法，旨在复用某些 Blocklet 的资源。

Migration Guide

- 1.17.x 升级与迁移指南

Blocklet Manager

- Adding a component

安全最佳实践

this page is a draft and need to be updated blocklet security: sk, config, data backup server security: sk, ssh, data-disk access-key: passport integ

1.17.x 升级与迁移指南

概览

OpenAPI Service

OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本，因为它是由 SmartBear Software 捐赠给 OpenAPI Initiative，并在2015年从 Swagger 规范重命名为 OpenAPI 规范。

为应用组件添加 PWA 集成

在目前的版本中，PWA 的集成仍处于早期阶段，我们将持续优化 PWA 在应用中的集成体验确保 @blocklet/cli 的版本大于 1.16.38-beta-20250115-235439-bb5a1c1b 在文章的开头，我们需要先了解什么是 PWA (Progressive Web App)

获得节点的其他方法

通过本文档您可以了解到在不同的环境中运行一个 Blocklet Server 节点，包括:

设置 DID Wallet

为什么我需要 DID 钱包？

设置 Node.js

如果你的开发环境中已经安装了 Node.js v20+，你可以安全地跳过这一步。为什么是 Node.js?Blocklet 工具箱中的大部分组件都是用 Node.js 构建的，所以需要安装 Node.js 才能使用。请确保 Node.js 的版本是 v20 及以上。要想知道你是否已经安装了 Nod

Setup on Ubuntu + FNM

Ubuntu is a popular Linux distribution loved by the developer community, Blocklet Server can run on it with the following steps.

Setup on Ubuntu + Nodesource

For how to get your server up and running on ubuntu with nodesource, please checkout the recording here: https://asciinema.org/a/629699

发布资源表单中各输入项的含义

源图不含可提取文本；重新生成页面时应保留其导出图片。

Theming

本综合指南涵盖了 Theming 功能的各个方面，从基本用法到高级功能和技术细节

如何转移 Blocklet

如果需要修改 Blocklet 的所有者，需要通过转移 Blocklet实现，本文将介绍如何转移 Blocklet. 必要条件只有 Blocklet 的所有者才有权限转移。转移 Blocklet 所有者后对应用的一些影响访问权限：原所有者将会丧失所有者权限，但是可能有其他访问权限，取决于实际的

使用 Grafana 配置 OAuth Server

前提条件

理解 Blocklet

Blocklet 生态系统中的核心概念及概念之间的关系如下图所示：

理解付费 Blocklet

this page is a draft and need to be updated

用户和通行证

Blocklet Auth Service 为 Blocklet 提供基于 DID 的身份认证和基于通行证的访问控制。

使用 @blocklet/logger

您可以使用@blocklet/logger管理 Blocklet 运行时的日志，具体操作步骤如下：

设计和使用应用偏好

什么是 Blocklet 偏好？

使用 Docker 容器运行 Blocklet

Blocklet Server 支持让 Blocklet 运行在 Docker 容器中，从而为每个 Blocklet 提供更好的隔离效果。

Can not access server/blocklet with DID Domain?

If you can not access your blocklet or server with DID Domain (in the following screenshot)

WebHooks

什么是 Webhook？

欢迎

欢迎来到 Blocklet，Web3 应用程序构建平台。

When stuck in maintenance mode?

Blocklet server supports several maintenance operations directly from the server dashboard:

When stuck on a blank screen?

If your website shows a blank screen and refreshing and clearing cache does not help, please consider the following steps to recover:

为什么在 Blocklet Store 上看不到已经上传的 Blocklet?

当用户在使用上传到 Store 的功能成功上传后(如下图), 我们需要进入 Store 中发布应用, 才能在 Store 市场上看到我们的 Blocklet.

Setup with Docker

Starting a server with Docker

How to mange static asset cache?

The Blocklet Server is designed to cache specific assets within its routing engine to enhance performance. These assets include the Blocklet Logo, JS/

Setup with ArcBlock Launcher

Launching a server via ArcBlock Launcher

Blocklet SDK（浏览器）

@blocklet/js-sdk 是 Blocklet 的浏览器端 JavaScript SDK。

SDK 客户端

SDK 客户端提供了与 @blocklet/js-sdk 交互的主要入口点。它提供了一个主要的 BlockletSDK 类，该类捆绑了所有可用的服务，以及几个工厂函数（getBlockletSDK、createAxios、createFetch），以便于访问和实例化。

API 参考

欢迎来到 @blocklet/js-sdk 的 API 参考文档。本节为 SDK 暴露的所有类、方法、函数和类型提供了详细的技术文档。它适用于需要精确了解 SDK 组件及其功能的开发人员。

AuthService

AuthService 提供了一个全面的 API，用于管理用户账户的各个方面。它处理用户个人资料、隐私和通知设置、关注其他用户等社交互动，以及注销和删除账户等关键身份验证操作。您可以通过 SDK 实例的 sdk.auth 访问它。

BlockletService

BlockletService 提供了访问 blocklet 元数据的方法。此元数据由 Blocklet 对象表示，包含应用程序名称、URL 前缀、版本和组件挂载点等基本信息。

ComponentService

ComponentService 提供了一个便捷的 API，用于与主应用中挂载的组件 blocklet 进行交互。它允许您检索这些组件的元数据，并构建指向其页面或 API 端点的绝对 URL。

服务

@blocklet/js-sdk 被组织成几个服务类，每个类负责一个特定的功能领域。这些服务充当不同 Blocklet API 端点的专用客户端，提供了一种结构化且直观的方式来与平台的功能进行交互。

FederatedService

FederatedService 提供了一个用于与统一登录站点群设置进行交互的 API。它允许您检索有关控制登录会话的“主”应用和用户正在交互的“当前”应用的信息。这对于创建诸如统一应用切换器之类的功能，或了解用户在相连的 Blocklet 群组中的会话上下文至关重要。

TokenService

TokenService 提供了一个低级 API，用于直接与会话令牌和刷新令牌进行交互。它处理从各自的浏览器存储位置存储和检索这些令牌的逻辑：会话令牌存储在 cookie 中，刷新令牌存储在 localStorage 中。

UserSessionService

UserSessionService 提供了一个 API，用于获取和管理用户在不同设备和应用程序中的登录会话。该服务对于构建功能至关重要，这些功能允许用户查看其活跃的登录位置、了解哪些设备访问了他们的账户以及管理这些会话。

类型

本节提供了 @blocklet/js-sdk 导出的核心 TypeScript 类型和接口的详细参考。在您的项目中使用这些类型可以帮助您利用 TypeScript 的静态分析和自动完成功能，以获得更好的开发体验。

快速入门

本指南将引导您完成安装 @blocklet/js-sdk 并进行首次 API 调用的基本步骤。我们的目标是让您在几分钟内就能上手。

身份验证

@blocklet/js-sdk 旨在通过自动处理基于令牌的复杂安全性，实现无缝的身份验证。它在后台管理会话令牌和刷新令牌，让您可以专注于构建应用程序的功能。

指南

欢迎阅读 @blocklet/js-sdk 的实践指南。本节旨在帮助您快速上手并完成常见任务。每个指南都提供了分步说明和代码示例，帮助您在 Blocklet 应用中集成关键功能，例如进行安全的 API 调用、处理用户身份验证和管理会话。

发起 API 请求

@blocklet/js-sdk 提供了功能强大、预先配置好的辅助工具，用于向您的 Blocklet 服务发起 API 请求。这些辅助工具，createAxios 和 createFetch，旨在自动处理身份验证和会话管理的复杂性，让您可以专注于构建应用程序的功能。

管理用户会话

@blocklet/js-sdk 提供了一个 UserSessionService，帮助您在不同设备上获取和管理用户登录会话。这对于构建“安全”或“设备”页面等功能特别有用，用户可以在这些页面上查看所有活动会话，了解其帐户在何处被使用。

概述

@blocklet/js-sdk 是一个功能全面的 JavaScript 库，旨在简化与 Blocklet 服务的交互。无论你是在构建前端应用还是后端服务，该 SDK 都提供了一套强大的工具来处理身份验证、会话管理和 API 通信，让你能够专注于功能构建，而无需处理底层细节。

Blocklet SDK（Node.js）

@blocklet/sdk 用于在 Node.js 里开发应用并接入系统能力。

API 参考

欢迎来到 Blocklet SDK API 参考。本节详细介绍了 SDK 导出的所有模块、类、函数和实用工具。无论您是管理用户、发送通知，还是保护您的应用程序，都可以在这里找到必要的详细信息。

类型定义

Blocklet SDK 是强类型的，可帮助您编写更健壮、更易于维护的代码。本节提供了在使用用户会话、通知、事件和 blocklet 配置时会遇到的最常见 TypeScript 类型和接口的参考。了解这些类型将有助于确保类型安全，并有效利用 IDE 的自动完成功能。

授权中间件

auth 中间件是一个功能强大的工具，可为你的 blocklet 路由添加一个授权层。它与会话中间件协同工作，通过验证用户的角色、特定权限、KYC (Know Your Customer) 状态以及所使用的身份验证方法来保护端点。这确保了只有经过授权的用户才能访问敏感或受限的资源。

身份验证

在现代 Web 应用程序中，强大的身份验证和授权对于安全和用户管理至关重要。Blocklet SDK 提供了一套全面的工具，可无缝实现这些功能，利用去中心化身份（DID）提供安全且以用户为中心的体验。

DID Connect

Blocklet SDK 提供了一种简化方法，通过使用 DID Connect 将去中心化身份集成到您的应用中。这允许用户使用 DID 钱包安全登录和管理他们的数据，提供无密码、以用户为中心的身份验证体验。实现此功能的核心组件是 WalletAuthenticator 和 WalletHandler

Session 中间件

session 中间件是 Blocklet SDK 身份验证系统的核心组件。它充当 Express.js 路由的守门员，验证请求者的身份，并在成功验证后将 SessionUser 对象附加到 req.user 属性上。这使得后续的中间件和路由处理程序可以轻松访问经过身份验证的用户信息。

核心概念

Blocklet SDK 建立在几个基本概念之上，这些概念构成了您构建的任何应用程序的支柱。理解这些核心支柱——配置、钱包管理和安全——对于利用 SDK 的全部功能来创建健壮、安全和可扩展的 Blocklet 至关重要。

配置与环境

Blocklet SDK 提供了一种强大而统一的方式来管理应用程序的配置和环境变量。它将来自多个来源的设置聚合到一个易于使用的界面中，确保您的 Blocklet 能够访问所有必要的信息，从应用程序元数据到特定于组件的设置。

安全工具

Blocklet SDK 包含一套强大的安全工具，旨在保护您的应用程序数据和通信。这些工具可帮助您处理敏感信息，确保 API 调用的完整性，并防止跨站请求伪造（CSRF）等常见的 Web 漏洞。

钱包管理

在 Blocklet SDK 中，钱包是一个基本的加密对象，代表了你的应用程序的身份。它对于签署数据、验证请求以及与区块链网络交互至关重要。SDK 提供了一个强大而便捷的工具 getWallet，可以直接从你的应用程序的环境变量中创建和管理钱包实例。

快速入门

本指南将引导您完成安装 Blocklet SDK 并启动一个最小化应用程序的基本步骤。我们的目标是帮助您在短短几分钟内从零开始，得到一个可以正常工作的示例。

指南

欢迎来到 Blocklet SDK 指南。本节提供实用的分步教程，帮助您解决常见挑战并在您的 Web 应用程序中实现关键功能。

组件间通信

在一个由多个组件组成的 Blocklet 应用中，使它们能够安全可靠地相互通信至关重要。Blocklet SDK 提供了一个高级实用工具 component.call，专为此目的而设计。该方法通过处理服务发现、请求签名和自动重试，简化了组件间的 API 调用。

使用 Web 服务器中间件

Blocklet SDK 捆绑了一套功能强大、即用型的 Express.js 中间件。这些工具旨在处理常见的 Web 开发挑战，如安全性、SEO 和单页应用程序（SPA）路由，让你可以用更少的样板代码构建更健壮、功能更丰富的 blocklet。

概述

Blocklet SDK (@blocklet/sdk) 是在 ArcBlock 平台上构建应用程序的基础工具包。它通过提供一套全面的实用工具、服务和中间件来处理 Blocklet 的核心功能，从而简化了开发过程，让您可以专注于应用程序的独特功能。

Blocklet 服务

BlockletService 是一个功能强大的客户端，作为您的 blocklet 与底层 ABT Node 服务交互的主要接口。它将复杂的 GraphQL 查询和 HTTP 请求封装成一个简洁的、基于 promise 的 JavaScript API，从而简化了用户管理、会话处理、基于角色的访问控

服务

Blocklet SDK 提供了一套强大的服务客户端，从而简化了直接 API 调用的复杂性。这些客户端提供了一个清晰的编程接口，用于与核心 Blocklet 功能进行交互，例如用户管理、实时通知和组件间事件处理。通过使用这些服务，您可以用更少的代码构建更健壮、功能更丰富的应用程序。

事件总线

事件总线提供了一种强大的发布-订阅机制，允许您的 blocklet 内部的不同组件，甚至不同 blocklet 之间（在同一个 ABT Node 实例内）以解耦的方式相互通信。这对于广播系统范围的状态变化或事件非常理想，而无需组件之间有直接的依赖关系。

通知服务

通知服务是 Blocklet SDK 的核心组件，使您的应用程序能够向用户发送各种类型的通知并订阅实时事件。该服务充当底层 ABT Node 通知功能的接口，处理从简单的用户消息到发送至 DID 钱包、电子邮件和其他渠道的丰富交互式通知的所有事务。

Blocklet Server SDK（Node.js）

@blocklet/server-js 是把 Web 应用连到 Blocklet Server 的官方 JS 库。

高级用法

本节涵盖了面向需要超越标准客户端方法或解决问题的开发人员的高级主题。在这里，您将学习如何直接对 Blocklet Server API 执行原始 GraphQL 查询，以及如何启用调试以检查底层的请求和响应。

调试

在使用 @blocklet/server-js 构建应用程序时，您可能会遇到 API 请求、身份验证或数据获取方面的问题。为了帮助您排查这些问题，客户端提供了详细的调试日志。这使您可以检查发送的原始 GraphQL 查询、接收的响应以及其他内部操作。

原始查询和订阅

虽然 @blocklet/server-js 库为大多数常见的 GraphQL 操作提供了便捷的辅助方法，但在某些情况下，您可能需要更大的灵活性或访问 SDK 尚未公开的功能。对于这些高级用例，该库允许您直接执行原始 GraphQL 查询和订阅。

API 参考

欢迎阅读 @blocklet/server-js 的完整 API 参考。本部分为通过 Blocklet Server Client 提供的每个 GraphQL 查询、变更和类型提供了详细的文档。无论您是需要获取数据、修改服务器状态，还是了解您正在使用的数据结构，这都是您的综合指南。

变更

变更是用于在 Blocklet Server 上创建、更新或删除数据的 GraphQL 操作。@blocklet/server-js 库提供了一组方便的方法来包装这些变更，使您可以轻松地从应用程序执行写入操作。

数据与操作

本节详细介绍 Blocklet Server 中用于数据管理和操作任务的变更操作，主要侧重于创建和管理备份，以及迁移数据结构。这些操作对于数据完整性、更新和灾难恢复至关重要。

网络与服务

本节详细介绍在 Blocklet Server 上管理网络和服务可用的变更操作。您可以执行配置路由规则、管理 SSL/TLS 证书、设置 Webhook 以及处理通知等操作。有关检索网络和服务数据的方法，请参阅网络与服务查询部分。

节点和 Blocklet 管理

本节为与管理 Blocklet Server 节点及其上运行的 Blocklet 的生命周期和配置相关的变更操作提供了详细参考。这些操作允许您以编程方式安装、启动、停止、配置和升级单个 Blocklet 和节点本身。

发布与项目

本节详细介绍可用于管理 blocklet 项目整个生命周期的 mutation，从创建和发布管理到连接 blocklet 商店和发布您的作品。这些 mutation 使您能够以编程方式控制项目的开发、版本控制和分发方式。

用户与访问管理

本节提供了在 Blocklet 中管理用户、角色、权限、邀请和访问密钥的变更操作的详细参考。这些操作对于控制访问和管理应用程序中的身份至关重要。

查询

查询用于从 Blocklet Server 获取数据。@blocklet/server-js 库提供了一组与可用 GraphQL 查询相对应的方法，使得无需编写原始 GraphQL 即可轻松检索信息。

数据与运营

本节提供了用于从 Blocklet Server 获取运营数据的 GraphQL 查询的详细参考。这些查询对于监控系统健康状况、管理备份、审计活动以及深入了解流量模式至关重要。有关数据和运营的变更操作，请参阅数据与运营变更操作部分。

网络与服务

本节为 Blocklet Server 上所有与网络和服务相关的 GraphQL 查询提供了详细的参考。这些方法允许您获取路由、域名、证书、Webhook 和通知的数据及配置。如需进行修改这些设置的操作，请参阅网络与服务变更部分。

节点和 Blocklet 管理

本节为用于管理和检索有关 Blocklet Server 节点及其运行的 Blocklet 信息的 GraphQL 查询提供了详细参考。这些查询允许您监控状态、获取配置和访问生命周期信息。

发布与项目

本节为用于管理发布项目、发布版本和相关资源的 GraphQL 查询提供了详细的参考。这些查询允许您检索有关 blocklet 发布生命周期的信息。对于修改此数据的操作，例如创建或更新项目和发布版本，请参阅发布与项目变更文档。

用户与访问管理

本节提供了在 Blocklet Server 中管理用户、角色、权限、会话和访问密钥相关查询的详细参考。这些查询允许您检索有关应用程序用户及其访问级别的信息。

类型

Blocklet Server Client API 利用各种 GraphQL 类型来构建查询和变更的数据结构。本节为整个 API 中使用的所有数据类型、输入对象、枚举和标量提供了全面的参考。理解这些类型对于构建有效的请求和解释来自 Blocklet Server 的响应至关重要。

身份验证

@blocklet/server-js 库提供两种主要方法来验证 API 请求：Auth Token 和 Access Key。合适的方法取决于您的应用程序环境和安全要求。Auth Token 通常用于面向用户的应用程序（如浏览器），而 Access Key 则专为安全的服务器到服务器通信而设计。

快速入门

本指南将引导你逐步了解并开始使用 @blocklet/server-js 库。你将学习如何安装客户端、连接到 Blocklet Server，并进行你的第一次 API 调用。

概述

@blocklet/server-js 库是与 Blocklet Server GraphQL API 交互的官方 JavaScript 客户端。它为 Node.js 和基于浏览器的应用程序提供了一个便捷且强大的接口，用于与 Blocklet Server 实例通信，从而简化了管理 blocklet

Blocklet Service

给 Blocklet 用的一组开箱即用服务，包括认证、通知等。

Developer Guide

Welcome to the Developer Guide for Blocklet Service. This guide provides comprehensive information for developers who want to programmatically integra

Authentication Service

The Authentication Service provides a comprehensive solution for managing user identity, authentication, and session control within your blocklet. It

Discovery & SEO Services

Effective Search Engine Optimization (SEO) and content discoverability are critical for any web application's success. They ensure that your blocklet

Open Graph

Overview

OpenEmbed

This is a placeholder for a diagram. Do not edit this line directly.

EventBus Service

The EventBus Service is a messaging system that facilitates communication between different blocklets and the core system. It employs a publish-subscr

Image Service

The Image Service provides robust, on-the-fly image processing capabilities through a simple URL-based API. Developers can perform various manipulatio

KYC Service

The Know Your Customer (KYC) Service provides a standardized way to verify user identity attributes within your application. This service enables deve

MCP Service

The Model Context Protocol (MCP) Service provides a standardized way for blocklets and their components to expose AI-powered tools and capabilities. I

Notification Service

The Blocklet Service provides a robust, multi-channel Notification Service designed to streamline communication with your users. Instead of building a

OAuth Service

The OAuth Service enables developers to integrate third-party authentication providers and to expose a standard OAuth 2.0 interface for their own appl

Overview

Blocklet Service is a foundational layer that provides a suite of ready-to-use, reusable services for blocklets. It is designed to run within a Blockl

User Guide

This guide is for administrators and non-technical users, providing step-by-step instructions for configuring and managing the Blocklet Service throug

AIGNE Hub

The AIGNE Hub acts as a centralized control panel for integrating and managing AI capabilities across all your blocklets. It simplifies the administra

Blocklet Studio

Blocklet Studio is a no-code platform designed for administrators to create, manage, and publish new blocklets using pre-built templates. It streamlin

Dashboard

The Dashboard is the central administrative interface for your Blocklet Service. It functions as the primary hub for managing blocklets, monitoring th

Developers

The Developer Tools section provides administrators with access to a suite of powerful tools for monitoring, debugging, and understanding the inner wo

Logs

The Logs section provides administrators with direct access to real-time and historical log data generated by the blocklet. This tool is essential for

Performance

The Performance section provides administrators with essential tools to monitor the runtime health and resource utilization of blocklets. Consistent m

DID Connect

DID Connect is a comprehensive user and identity management center designed for administrators. It provides a centralized suite of tools for managing

Members

The Members section within DID Connect serves as the central administrative hub for user management. It provides a comprehensive interface for viewing

OAuth Apps

OAuth Apps functionality allows your service to act as an OAuth 2.0 provider. This enables third-party applications to securely access user data throu

Passports

A Passport is a verifiable digital credential issued to a user, serving as proof of identity or authorization within your application. As a fundamenta

Security

For administrators, the Security section is where you define advanced security rules, access policies, and response handling to protect your applicati

Settings

The Settings section within DID Connect is the central control panel for administrators to configure authentication policies, user verification proces

DID Spaces

DID Spaces provides a decentralized and secure storage solution integrated directly into your Blocklet Service. It allows administrators to manage app

Backups

The Backups feature, integrated with DID Spaces, provides a robust solution for safeguarding your application's data. It allows administrators to esta

Storage

The Storage section, part of the DID Spaces service, provides administrators with essential tools for monitoring and managing the storage resources al

Integrations

The Integrations section provides the tools necessary to connect your Blocklet Service with external systems and to manage programmatic access via the

Access Keys

Access Keys provide a method for granting programmatic access to your blocklet's services. They are used by applications, scripts, or external service

MCP Servers

The Model Context Protocol (MCP) provides a standardized framework that allows the main blocklet and its components to expose and consume AI-powered t

WebHooks

WebHooks provide a mechanism for your Blocklet Service to send real-time notifications to external services. By subscribing to specific system events,

Operations

The Operations section provides a centralized suite of tools for administrators to manage and monitor the production environment of their blocklets. I

Advanced

The Advanced settings section provides administrators with access to powerful, low-frequency administrative functions. These tools are intended for cr

Analytics

The Analytics section provides essential tools for understanding your blocklet's performance and user engagement. It allows administrators to monitor

Audit Logs

The Audit Logs service provides administrators with a comprehensive and chronological record of all activities that occur within the system. This feat

Notifications

Overview

Website

The Website service provides a centralized control panel for administrators to manage all aspects of a site's public-facing presentation. This include

Branding

The Branding section allows administrators to customize the application's visual identity to align with their brand. Proper branding ensures a consist

Domains

Proper domain configuration is fundamental to establishing your website's brand identity and ensuring users can easily access your services. This sect

Navigation

The Navigation section provides administrators with the tools to configure and manage the navigation menus for the website. This includes creating, ed

Theming

The Theming section provides administrators with granular control over the visual appearance of their website, ensuring a consistent and on-brand user

Blocklet Spec

@blocklet/meta 规定 Blocklet 的元数据格式，并提供解析与校验工具。

API 参考

@blocklet/meta 库提供了一套全面的实用函数，用于以编程方式与 blocklet.yml 元数据进行交互。这些帮助函数简化了常见的任务，如解析、验证、数据操作和安全操作。无论您是构建开发工具、自定义 blocklet 运行时，还是与 Blocklet 生态系统交互的应用程序，这些 API

组件与状态工具

@blocklet/meta 库提供了一套全面的工具函数，旨在简化与 BlockletState 对象的交互。Blocklet（尤其是复合型 Blocklet）被表示为一个组件树。这些工具提供了强大而高效的方法来遍历此树、查找特定组件、检查其状态以及为运行时操作、UI 渲染和管理任务提取关键信息。

DID 与 Wallet 实用工具

本节提供了与去中心化标识符 (DID) 和加密钱包相关的实用函数的详细参考。这些辅助函数对于管理 Blocklet 的身份、生成特定于应用的钱包以及从用户会话中提取身份信息至关重要。

文件实用工具

该模块提供了一组用于与文件系统上的 blocklet.yml 文件进行交互的底层函数。它包括用于定位、读取和写入元数据文件的实用工具，以及自定义的 Joi 扩展，以简化文件路径和 DID 的验证。

元数据助手

这些实用函数是您从远程源获取、处理和验证 Blocklet 元数据的工具包。无论您是从商店 URL 还是本地文件路径解析 Blocklet，这些助手对于任何需要与本地不可用的 Blocklet 交互的工具或应用程序（如启动器、开发工具或注册表服务）都至关重要。

其他实用工具

本节介绍由 @blocklet/meta 提供的一系列专用辅助函数。这些实用工具处理诸如解析和创建通信通道字符串以及从地址生成独特的、视觉上可识别的图标 (Blockies) 等任务。

导航工具

这些函数是在基于 Blocklet 的应用程序中构建动态用户界面的引擎。它们解析并处理来自 blocklet 元数据（blocklet.yml）及其当前状态的 navigation 属性，将主 blocklet 及其所有子组件的导航项聚合为一个统一的、可供渲染的结构。

解析与验证

本节为用于读取、解析和验证 blocklet.yml 文件的函数提供了详细参考。这些实用工具是与 Blocklet 规范交互的编程接口，可确保你的 blocklet 元数据正确、完整，并可供 Blocklet Server 和其他工具使用。

安全工具

@blocklet/meta 库提供了一套用于处理加密操作的安全工具。这些函数对于确保数据的完整性和真实性至关重要，特别是用于签署和验证 Blocklet 元数据和 API 响应。它们构成了 Blocklet 生态系统内信任的基石。

URL 和路径工具

本节提供了一组辅助函数，用于创建 URL 友好的字符串和验证 URL 路径。这些工具对于在你的 blocklet 应用中生成干净、有效且一致的路由和链接至关重要。

快速入门

本指南简要介绍了如何使用 @blocklet/meta 库。您将学习如何安装该软件包并执行最常见的任务：解析 blocklet.yml 文件以在您的应用程序中访问其元数据。

概述

@blocklet/meta 是 Blocklet 生态系统中的一个基础库，作为管理 blocklet 元数据的权威工具包。它为 blocklet.yml 清单文件建立了正式规范，并提供了一套全面的实用函数，用于以编程方式解析、验证、修复和与此元数据交互。

Blocklet 规范 (blocklet.yml)

blocklet.yml 文件是每个 Blocklet 的核心。它是一个 YAML 清单，定义了有关应用程序的所有基本元数据，是 Blocklet Server 和生态系统中其他工具的唯一真实来源。

组合 (组件)

Blocklet 组合是一项强大的功能，它允许你通过组装更小的、独立的 Blocklet 来构建复杂的模块化应用程序。这种方法促进了可重用性、关注点分离和更轻松的维护。blocklet.yml 文件中的 components 属性是此功能的基础，用于定义一个 Blocklet 对其他 Blockle

核心元数据

核心元数据字段确立了 Blocklet 的基本身份。它们为在 Blocklet 生态系统中的识别、版本控制和可发现性提供了必要的一目了然的信息。每个 blocklet.yml 文件都必须定义这些基础属性才被视为有效。

分发与链接

本节涵盖了 blocklet.yml 中用于定义 Blocklet 如何打包分发以及提供其源代码、主页、文档和其他资源基本链接的字段。正确配置这些字段对于 Blocklet 的可发现性、用户信任以及融入 Blocklet 生态系统至关重要。

执行与环境

blocklet.yml 中的执行和环境配置是 Blocklet 运行的蓝图。它指定了必要的运行时，定义了系统要求，向用户公开了配置选项，并与 Blocklet 的生命周期挂钩。正确设置此部分对于创建可移植、健壮且用户友好的应用程序至关重要。

接口与服务

Blocklet 通过 interfaces 与外部世界交互，并通过 services 增强其功能，提供强大、可复用的功能。blocklet.yml 中的 interfaces 属性是暴露应用程序网页、API 和其他端点的基石。services，例如内置的身份验证服务，可以附加到这些接口上，以提供通

变现

Blocklet 开发者可以通过由 OCAP（开放能力访问协议）和 NFT 提供支持的内置支付系统将其工作变现。当用户购买一个 blocklet 时，他们会收到一个唯一的 NFT（一个 BlockletPurchaseCredential），作为所有权的证明。整个过程在 blocklet.yml 元

人员与所有权

恰当地署名作者并明确贡献和维护的角色，对于一个健康的开源生态系统至关重要。在 blocklet.yml 中，你可以使用三个不同的字段来指定参与项目的人员：author、contributors 和 maintainers。所有这些字段都使用一个通用的 person 模式。

安全与资源

安全和资源管理对于创建可信赖且可互操作的 Blocklet至关重要。blocklet.yml 规范为此提供了两个关键字段：signatures 用于确保元数据的完整性和真实性，resource 用于定义和捆绑共享资产，以便与其他 Blocklet 组合。

UI 与主题

本节详细介绍 blocklet.yml 文件中的 navigation 和 theme 属性。这些属性有助于定义 blocklet 对用户界面的贡献，控制其在菜单中的显示方式，并指定其外观和感觉，以确保一致的用户体验。

Blocklet Store

发布和获取 Blocklet 应用的平台。

Best practice

NOTE: this page is in draft and is subject to change.

Blocklet Detail Page

Instructions on obtaining a meticulously configured blocklet detail page.

Frequently asked questions

Q：How to create a blocklet from scratch?

Publish your blocklet

TODO: this page is not yet complete

Choose License

TODO: this page need to be updated

Request Entity too large

Blocklet Store limit blocklet bundle size within a certain range for efficiency considerations, since larger bundles takes much more time to download

Developer Program Policies

Effective Date: 2024-06-01 Welcome to the Blocklet Store Developer Program. The following policies are designed to ensure a safe, trustworthy, and eff

Get your developer passport

如果我们要在 Blocklet Store 发布应用，需要获得该商店颁发的 Developer 证书。

Internationalize your blocklet

This page describes how to support multiple languages of an blocklet in the Blocklet Store.

列表信息

欢迎阅读 Blocklet 商店应用开发指南，本文档旨在为所有开发者提供完整的开发应用列表信息，以帮助您顺利通过应用审核。标题在 blocklet.yml 或者 Blocklet Studio 中为您的应用提供标题；要求如下：语言：英文；字符：不超过 40 个字符，尽量保持在一行内，不要换行

如何修复 Logo 和截屏的尺寸和比例？

为了确保 Blocklet 详情页的展示效果，我们会要求 Blocklet 开发者提供的图片满足特定的要求，详见：我们在 Blocklet Studio 中提供了便利的工具来方便开发者添加 Logo 和 Screenshot 的时候自动裁剪到要求的宽高比和尺寸。下面是具体的用法：如果你使用

Manage your blocklet

TODO: this page need to be updated, topics to be covered: auto publish, private publish

Prepare your Blocklet

Best practice Internationalize your blocklet

Error: Bundles with the same did cannot in different stores

If you encounter the above error when publishing your blocklet to the blocklet store, like the following screenshot

Publish your Blocklet

Permission Modes

At the heart of permission models of Blocklet Store is the DID and Verifiable Credential-based developer passport mechanism, an advanced system for

提供图片

欢迎阅读应用开发指南，本文档旨在为所有开发者提供图片，以帮助您顺利通过应用审核。您需要在 Blocklet 商店中提供以下两类图片以供使用：应用 Logo 和屏幕截图，提供有吸引力的图片会增加您的应用被注意到的机会。应用 Logo 您必须在 Blocklet 的 Bundle 文件中提供应用

Blocklet 页面如何上传/更新不同链接及视频？

如何新建 Blocklet 并上传不同链接及视频：

Terms and Policies

- Developer Program Policies

What is blocklet store

NOTE: this page is in draft and is subject to change.

如何制作精美的应用截图？

Blocklet Store 一直致力于为开发者和用户提供卓越的体验。为了进一步提升应用的展示效果，降低图片制作成本，我们即将迎来一次重要的更新！

Blocklet UI（React）

@blocklet/ui-react 提供 Blocklet 开发常用的界面组件。

组件

本节为 Blocklet UI React 库中所有可用的 UI 组件提供了全面的参考文档。每个组件都附有其属性 (props)、实际使用示例和最佳实践的文档，以确保能无缝集成到您的应用程序中。

组件管理

组件管理提供了一套工具，用于在正在运行的应用程序中动态安装、发布和管理 blocklet 组件。此功能使应用程序能够模块化和可扩展，允许管理员和开发人员添加或更新功能，而无需对核心应用程序进行完全重新部署。

BlockletStudio

BlockletStudio 组件提供了一个精简的、可嵌入的用户界面，用于发布和管理 blocklet 资源。它通过渲染一个全页 iframe 来运行，该 iframe 从指定的 blocklet 服务加载一个专用的发布界面。这使得您的应用程序能够提供一致且强大的资源管理体验，而无需从头开始构建 U

ComponentInstaller

ComponentInstaller 是一个实用工具组件，为依赖其他 blocklet 的功能充当网关。它会验证指定的组件依赖项是否已安装。如果未安装，它会为管理员（默认为 owner 或 admin 角色）提供一个用户友好的界面，以便直接进行安装。如果用户缺少必要的权限，它会显示一条消息，建议他们

布局

布局组件是构建 Blocklet 应用用户界面的基础构建块。它们提供了一个一致且可预测的框架，包括主 Header、Footer 和内容区域。通过利用这些组件，您可以确保在整个应用中提供专业且一致的用户体验，因为它们会根据 Blocklet 的元数据自动进行调整。

Dashboard

Dashboard 组件为 blocklet 应用程序提供了一个预构建的响应式布局，通常用于管理界面或以用户为中心的视图。它通过解析 blocklet 的元数据，自动构建一个包含侧边栏、头部和主内容区域的标准仪表盘。该组件显著减少了构建常见应用程序结构的样板代码。

Footer

Footer 组件为你的应用提供了一个标准化的、响应式的页脚。它通过读取 blocklet 的元数据来自动填充其内容——包括品牌信息、导航链接、社交媒体图标和版权信息。这种数据驱动的方法确保了一致性并简化了配置。

Header

Header 组件为 Blocklet 应用提供了一个响应式且可定制的页眉。它通过直接从 blocklet 的配置（blocklet.yml）中读取元数据，自动填充导航链接、应用 logo 和用户会话控件。该组件旨在以最少的配置创建一个功能丰富且一致的页眉。

通知

本节详细介绍了可用于实现实时用户通知系统的组件和实用工具。该系统旨在通过专用的 UI 组件和浮动提示消息向用户及时传递更新。

用户管理

用户管理套件提供了一系列预构建的 React 组件，旨在处理与用户相关的基本功能。这些组件简化了在您的应用中实现用户个人资料、会话管理和组织切换的过程，确保了用户体验的一致性和可靠性。

UserCenter

UserCenter 组件是一个全面的、预构建的界面，提供完整的用户个人资料和设置管理页面。它集成了多种功能，包括用户信息显示、通行证管理、隐私控制、通知设置和 DID 存储管理，为用户提供了一个集中的枢纽。

UserSessions

UserSessions 组件渲染一个全面的数据表格，用于显示和管理用户的登录会话。它清晰地概览了用户在各种设备上的所有活跃、已过期和离线会话，让用户能够控制其账户安全。

工具

本节提供了关于一系列辅助组件、高阶组件 (HOC) 和实用函数的文档。这些工具旨在简化常见的开发任务、管理应用程序主题和处理复杂的数据结构。

Icon

Icon 组件是一个基于 Material-UI 的 Avatar 组件构建的灵活实用工具。它旨在从多种来源渲染图标，包括 Iconify 图标字符串、图像 URL 和基于字符的“字母头像”。这种多功能性使其成为一个标准化组件，可用于处理应用程序中的大多数图标和头像显示需求。

核心概念

本文档解释了 Blocklet UI React 库的基本原则。其核心设计理念是元数据驱动方法，即 Header、Footer 和 Dashboard 等 UI 组件会根据 blocklet 的元数据自动配置和渲染。这种策略确保了一致性，减少了样板代码，并实现了能适应用户角色和语言偏好的动态 UI。

快速入门

本指南将引导你逐步安装 @blocklet/ui-react 库并渲染你的第一个组件。目标是在最短的时间内在你的应用程序中拥有一个功能完备的 Header 和 Footer。

Hooks API

本节为库中可用的自定义 React Hooks 提供了详细参考。这些 hooks 旨在封装和复用有状态逻辑，从而简化 Blocklet 环境中的常见任务和交互。

操作指南

本节提供了使用该库的组件完成常见任务和实现特定工作流的实用分步指南。每个指南都设计为一套独立的操作说明，旨在帮助您高效地实现特定目标。

概述

@blocklet/ui-react 库提供了一系列核心 React 组件，旨在加速 Blocklet 应用程序的开发。它通过智能地利用 blocklet 的元数据来简化通用用户界面元素的创建，使开发人员能够以最少的工作量构建一致且功能丰富的 UI。

Blocklets

ARC Blocklet 开发者文档：Package 与 Instance、本地运行、manifest、surface 与发布边界。

读 agent 运行看板

Agent Observability 的 dashboard 回答「我的 agent 最近干了什么」——失败、花销离群、轮次、按应用汇总——以及它哪几个数字与标签不符。

在 Traces 里读一次 agent 运行

打开 Agent Observability 里的一条 agent run trace：你被允许看到哪些 run、列表与它的过滤器、逐轮时间线、事件 inspector，以及 trace assistant。

在 Agent Observability 里读你的 AI 消耗

读懂 Agent Observability blocklet 的 AI 用量面——个人视角、管理视角，以及两者共同绑定的 AFS 路径；对账边界全部在活环境上核验过。

编写 Blocklet

组织声明的能力、数据边界与 Web surface，不要混为一谈。

检查、构建与 inspect

运行 arc blocklet check、build、inspect、dev 并附真实输出；把每条命令当作不同证明。

本地创建与运行

用 arc blocklet create 脚手架，校验后用 blocklet run 或 service start 本地 serve——不需要 DID Space。

数据与 AFS

从 Blocklet 使用 AFS 路径、mount、seed 与集合声明，而不把产品契约绑到某个存储引擎。

Discuss Kit 谱系

定位当前 Discuss Kit 参考实现所覆盖的复制型讨论数据——不声称旧产品功能全量对等。

入门

安装 arc，选择 recipe，并走完本地 package → check → run 路径，再考虑任何远程发布。

生命周期

把本地观察、package 检查、构建产物与远程发布/部署分成不同生命周期阶段。

Manifest 与能力

用当前解析器与检查器接受的 blocklet.yaml 字段声明 Blocklet——不是愿望清单。

Blocklets

理解 ARC 的应用 package-and-instance 单元，从本地起步，并明确编写、运行与发布边界。

Package 与 Instance

把可交付的 Blocklet package 与某次具体运行或配置的 instance 区分开。

发布与部署

严格区分本地 daemon 注册、本地 DID Space 发布、远程 --server 发布与 Pages 部署——未验证路径标为 experimental。

参考

Blocklet 命令、manifest 字段组、生命周期状态与证据边界索引（ARC 2.0.0-beta.28）。

参考应用

把 ArcBlock/arc blocklets/ 下的真实 package 当作有边界的例子——不是通用模板或产品对等证明。

测试与诊断

Blocklet 失败时收集源码、契约、运行时与可见 surface 证据，并把失败映射到正确命令。

Web surface

在 Blocklet 内用 AUP 表达界面语义、用 Web Device 渲染 Web 内容/站点——外链，不复制 primitive 目录。

Create Blocklet

用一条命令生成一个 Blocklet 项目骨架的命令行工具。

添加应用模板

this page is a draft and need to be updatednaming conventiontemplate attributesdisplay on template gallery

可用脚本

通过 create-blocklet 工具创建出来的项目，会在 package.json 中配置好对应的 npm script来方便开发者使用。

目录结构

在创建后，你的项目应该像这样：

组合应用的目录结构

在创建后，你的项目应该像这样:

如何创建组合应用

什么是组合应用

快速上手

Create Blocklet 是一个官方支持的 Blocklet 创建工具，可以快速创建 Blocklet ，并且可以自动添加到项目中。

如何创建单个应用？

create-blocklet 支持两种创建模式，分别是创建单个应用和创建 monorepo 类型的组合应用

自定义你的应用

在每个 Blocklet 应用的根目录中都存在一个 blocklet.yml 文件，它是 Blocklet 应用的配置文件，包括项目的名称、版本、作者、项目的描述等配置信息。

FAQ

文档是如何组织的？

vite-plugin-wss-hmr

This page need to be updated

操作手册

如何创建单个应用？如何创建组合应用自定义你的应用应用版本管理添加应用模板更多开发资源

安装 Blocklet CLI

关于为什么需要 Blocklet Server 以及如何安装和设置 Blocklet Server，请参考Blocklet 开发者指南。

应用版本管理

通过 create-blocklet 工具创建出来的项目，已经自动配置好了对应的版本管理脚本

入门指南

如果你是一个中级或高级开发者，并且你已经对 Blocklet 的工作原理有了基本的了解，你可以从创建第一个 Blocklet开始。

参考指南

设置 DID 钱包

关于为什么需要 DID 钱包以及如何设置 DID 钱包，请参考Blocklet 开发者指南。

设置 Node.js

关于为什么需要 Node.js 以及如何安装 Node.js，请参考Blocklet 开发者指南。

欢迎

欢迎来到 Create Blocklet 你的 Blocklet 项目助理

vite-plugin-blocklet

Creator Studio

面向内容创作者的工具。

Forum

Forum Blocklet 是 Discuss Kit 的一款定制化应用包，专为希望搭建论坛的用户和团队设计。

FAQs

Overview

Getting Started

Overview

How To Guides

Overview

How to use the "Knowledge Planet" Blocklet

Introducing

Blog

Blog Blocklet 是 Discuss Kit 的一款定制化应用包，专为那些希望搭建个人或企业博客的用户设计。

Knowledge Planet (Beta)

This blocklet is in beta and is not recommended for production use

Personal Website (Beta)

This blocklet is in beta and is not recommended for production use

Bookmarklet

Bookmarklet Blocklet 是 Discuss Kit 的一款定制化应用包，旨在为各类用户提供一个简洁高效的网页保存与管理解决方案。

Doc

Doc Blocklet 是 Discuss Kit 的一款定制化应用包，专为构建和维护知识库系统的用户与团队打造。

Welcome

Overview

DID Connect 指南

连接用户和应用的开放协议与开发套件。

DID Connect UI（React）

@arcblock/did-connect-react 提供 DID Connect 的界面组件和会话管理。

高级主题

当您熟悉 SessionProvider 和 DidConnect 等核心组件后，就可以开始探索 @arcblock/did-connect-react 库更强大、更灵活的功能了。本节将介绍一些高级主题，帮助您构建更复杂、更健壮、更用户友好的去中心化身份应用。

身份验证方法

DID Wallet 是主要且最安全的身份验证方法，但 @arcblock/did-connect-react 也为多种替代登录方法提供了强大的支持，以提供灵活性并满足不同用户的偏好。本节详细介绍如何将 OAuth（社交登录）、Passkeys（无密码身份验证）和统一登录集成到您的应用程序中。

工具函数

@arcblock/did-connect-react 库导出了一系列工具函数，旨在简化与身份验证流程、数据处理和 API 通信相关的常见任务。虽然核心组件和钩子处理了大多数用例，但这些工具为高级集成或自定义实现提供了精细的控制。

API 参考

本节为 @arcblock/did-connect-react 库中使用的所有主要 TypeScript 类型提供了全面的参考。理解这些数据结构对于有效使用像 SessionProvider 这样的组件和像 useConnect 这样的钩子至关重要。

核心组件

@arcblock/did-connect-react 库围绕几个核心组件构建，它们为将去中心化身份集成到您的应用程序中提供了基础。这些组件处理会话管理和面向用户的连接界面。

连接 UI (DidConnect)

DidConnect 组件是一个预构建的、全面的 UI 解决方案，用于处理各种去中心化身份（DID）连接流程。它为登录、认证和个人资料请求等操作提供了用户友好的界面，并开箱即用地支持多种连接方式。

会话管理 (SessionProvider)

SessionProvider 是 @arcblock/did-connect-react 库的基石。它是一个 React Context Provider，封装了所有与会话相关的逻辑、状态和操作。通过使用 SessionProvider 包装您的应用程序，您可以将用户的会话信息和身份验证方法提供给

快速入门

本指南将引导你完成使用 @arcblock/did-connect-react 将去中心化身份（DID）验证集成到你的 React 应用中的基本步骤。只需几分钟，你就能拥有一个功能齐全的登录和登出流程。

Hooks

@arcblock/did-connect-react 库提供了一套功能强大的 React Hooks，可实现编程控制和灵活的数据访问。虽然 SessionProvider 提供了一种方便的基于上下文的方法，但 Hooks 为您提供了复杂 UI 和高级用例所需的精细控制。

useConnect

useConnect hook 提供了一种强大的、编程化的方式来打开、关闭和管理 DidConnect UI 模态框。当您需要比声明式的 Button 组件提供更多对连接流程的控制时，例如从自定义 UI 元素、菜单项或响应应用程序事件来触发模态框，它就是理想的解决方案。

useDid

useDid Hook 是一个便捷的实用程序，可以轻松地从 session.user 对象中提取和使用特定的 DID 相关信息。它简化了用户对象的解析过程，无需手动处理即可获取永久 DID、钱包信息和已连接账户等常用数据。

useOAuth & usePasskey

DidConnect 组件和 useConnect hook 为所有身份验证方法提供了全面的、预构建的用户界面，但你可能需要构建自定义的身份验证流程。useOAuth 和 usePasskey hook 提供了对社交登录 (OAuth) 和无密码身份验证 (Passkey) 底层逻辑的直接访问。

概述

@arcblock/did-connect-react 库提供了一套全面的 React 组件和钩子，旨在将去中心化身份 (DID) 功能无缝集成到您的 Web 应用程序中。它使用 ArcBlock 的 DID 钱包简化了用户身份验证和会话管理的过程，为传统的登录系统提供了一种安全且用户友好的替代方案

UI 组件

@arcblock/did-connect-react 库包含一组预设样式、辅助性的 UI 组件，旨在帮助你以一致且美观的方式显示 DID 相关信息。这些组件与核心连接流程无缝协作，并基于强大的 @arcblock/ux 和 @mui/material 库构建，确保在你的应用程序中拥有一致的外观和感

Address

Address 组件是一个专门的 UI 元素，旨在以清晰、可读和用户友好的格式显示去中心化标识符 (DID) 地址。它通过提供缩短和轻松复制的选项，智能地处理 DID 典型的长字符串，从而增强了整体用户体验。

头像

Avatar 组件是显示用户头像的一种简单便捷的方式。它可以根据用户的去中心化身份标识（DID）自动生成一个独特的头像，或者显示来自指定 URL 的图像。

按钮

ConnectButton 组件提供了一个预设样式且易于识别的按钮，用于启动 DID Connect 身份验证过程。它简化了为你的应用程序登录流程创建一致用户体验的过程。该按钮采用官方 DID Connect 品牌风格，包括徽标和配色方案，为用户提供了清晰的操作指引。

Logo

Logo 组件提供了一种简单且一致的方式，在您的应用程序中显示官方的 DID Connect 徽标。它是一个专为品牌展示而设计的直观视觉组件，确保您的用户能够识别这种熟悉的去中心化身份连接方式。

DID Connect SDK（Node.js）

@arcblock/did-connect-js 帮 Node.js 应用接入 DID Connect 做认证。

API 参考

本节提供了 DID Connect SDK 中可用的核心类、构造函数、方法和选项的详细文档。理解这些组件是为您的应用程序构建强大且安全的身份验证流程的关键。

WalletAuthenticator

WalletAuthenticator 是 DID Connect 会话中服务器端逻辑的核心类。它负责创建认证请求、签署响应以及验证从用户钱包返回的数据。它独立于任何特定的 Web 框架运行，处理所有加密操作和 JWT 管理。

WalletHandlers

WalletHandlers 类是一个高级实用工具，旨在将 DID Connect 工作流无缝集成到 Express.js 或类似的服务器端框架中。它能为给定操作自动设置所有必需的 API 端点，处理您的应用程序与用户的 DID Wallet 之间的通信。

协议声明

协议声明 (Agreement Claim) 是一个强大的工具，用于获取用户对服务条款、隐私政策或任何其他正式协议的明确同意。此声明并非简单的复选框，而是要求用户对文档的哈希（摘要）进行加密签名，从而创建一个可验证且不可否认的同意记录。

资产声明

资产声明用于请求用户出示特定链上数字资产（如非同质化代币 NFT）的所有权证明。这对于 NFT 门控访问等场景尤其有用，在此类场景中，服务或内容的准入仅限于特定资产的所有者。

资产或 VC 声明

assetOrVC 声明提供了一种灵活的方式，可以要求用户出示其拥有链上资产（如 NFT）或符合指定标准集的可验证凭证（VC）的所有权证明。这对于需要灵活访问控制的场景特别有用，因为这些场景可以接受多种形式的资格证明。

Auth Principal 声明

authPrincipal 声明是任何 DID Connect 会话的基石。它是最基本、最常用的声明，旨在要求用户连接他们的钱包并选择一个去中心化标识符（DID）与您的应用程序进行交互。这第一步会建立一个安全的会话，并为应用程序提供用户的主要 DID，所有后续的交互都将基于此 DID 构建。

声明参考

DID Connect 使应用程序能够从用户的数字钱包请求特定信息或操作。这些请求被称为“声明（claims）”。每种声明类型都为不同的目的而设计，从简单的身份验证到复杂的多步骤工作流，如交易签名或出示数字凭证。

加密密钥声明

encryptionKey 声明是一项强大的功能，它允许您的应用程序从用户的钱包中请求一个秘密加密密钥。该密钥是根据钱包的主密钥和您提供的 salt 确定性地派生出来的。它使应用程序能够加密用户特定数据，而无需处理用户的主私钥，从而增强了安全性和隐私性。

密钥对声明

密钥对声明是一项强大的功能，允许你的应用程序请求用户的钱包生成一个新的加密密钥对。这对于创建新的、特定于应用程序的账户或身份特别有用，这些账户或身份由用户的钱包安全管理，但专用于与你的服务进行交互。

准备交易声明

prepareTx 声明是 dApp 的一个强大工具，尤其是在需要用户完成并签署交易的支付和资产转移场景中。与标准的 signature 声明（其中整个交易是预先定义的）不同，prepareTx 会向钱包发送一个部分构造的交易。然后，钱包负责添加必要的输入（如代币或资产）以满足指定的 require

Profile Claim

Profile Claim 用于向用户的 DID Wallet 请求个人信息。这是许多应用程序的基础步骤，通过在用户明确同意的情况下安全地获取用户数据，从而实现用户注册、个性化体验和通信等功能。

签名声明

签名声明是一种多功能工具，用于请求用户使用与其 DID 关联的私钥对任意数据进行签名。此加密签名作为用户已查看并批准该数据的不可否认的证明，有效地展示了对其数字身份的控制权。常见用例包括签署消息、授权交易或确认委托。

可验证凭证声明

可验证凭证 (Verifiable Credential, VC) 是一种数字化的、防篡改的凭证，可用于证明持有者的某些信息。可验证凭证声明允许您的应用程序请求用户从其 DID 钱包中出示特定的 VC，以证明其属性、资格或权利。

示例

欢迎来到示例部分。在这里，您将找到一系列实用的端到端示例，旨在帮助您快速理解和实现 DID Connect 的各种功能。每个示例都提供了一个带有可运行代码片段的真实场景，以指导您完成整个过程。

多链连接

DID Connect 的设计充分考虑了互操作性，其功能已超越 ArcBlock 生态系统。你可以配置它，使其与以太坊和 Solana 等其他主流区块链无缝交互。本示例将演示如何设置一个 DID Connect 会话，以请求在以太坊网络上执行操作。

多步骤会话

在许多实际应用中，单次交互不足以完成一项任务。您可能需要引导用户完成一系列步骤，例如首先注册个人资料，然后验证资产所有权，最后签署用户协议。DID Connect 库允许您将多个会话链接在一起，形成一个单一、无缝的多步骤工作流，从而简化这些复杂的交互。

出示 NFT

本示例演示了如何将应用程序中特定内容或功能的访问权限限制为拥有特定非同质化通证（NFT）或链上资产的用户。这是一种常见的 Web3 模式，用于专属会员、活动门票或特殊数字物品。

简单登录

本示例提供了一个分步指南，介绍如何使用 DID Connect 实现一个基本的用户登录系统。其目标是使用用户的 DID 钱包对用户进行身份验证，并检索其姓名和电子邮件地址等基本个人资料信息。这是该库最常见的用例之一。

交易支付

此示例演示了 DID Connect 的一个常见且强大的用例：请求用户签署并提交链上交易以进行支付。此模式非常适合电子商务结账、服务订阅、内容购买或任何需要转移代币或资产的场景。

快速入门

本指南提供了一个最小化的分步示例，帮助您在 Node.js 应用程序中设置一个基本的 DID Connect 会话。在本教程结束时，您将拥有一个可以工作的服务器，能够通过用户的 DID 钱包请求其个人资料信息。

指南

欢迎阅读 DID Connect 指南。本部分提供了实用、分步的说明，用于实现常见的用例和利用库的高级功能。无论您是设置第一个 DID Connect 会话，还是构建复杂的多步骤工作流，这些指南都旨在帮助您成功。

链接工作流

DID Connect 允许你将多个不同的身份验证会话链接在一起，通过一次初始交互为用户创建一个无缝的多步骤流程。这对于复杂的场景非常理想，例如用户注册后进行 KYC，或者登录后进行交易确认。

委托连接

委托连接是一项高级功能，通过允许应用程序使用临时的或较低权限的“Agent” DID 执行 DID Connect 操作，同时仍向最终用户展示其主要的、官方的 DID，从而增强了安全性。这意味着应用程序的主私钥永远不会暴露在处理日常交互的热钱包中。

处理钱包响应

正如请求声明指南所示，在为 DID Connect 会话定义声明后，下一个关键步骤是处理来自用户 DID 钱包的响应。@arcblock/did-connect-js 库提供了一套全面的生命周期回调，用于管理会话的每一种可能结果，无论用户是批准、拒绝还是会话超时。

请求声明

在 DID Connect 会话中，“声明”是你向用户钱包请求的特定信息或操作。这可以是任何内容，从他们的姓名和电子邮件，到证明资产所有权的加密签名。本指南将引导你了解向用户请求声明的不同方式。

DID Connect 工作流

DID Connect 会话是一个安全的、去中心化的身份验证过程，允许用户使用其 DID 钱包与去中心化应用（DApp）进行交互。本指南将端到端地分解整个过程，从最初的二维码扫描到最终处理用户的响应。

概述

欢迎使用 DID Connect，这是一个专为使用去中心化标识符（DID）进行无缝且安全身份验证而设计的协议。本库 @arcblock/did-connect-js 提供了将 DID Connect 集成到您的 Node.js 应用程序中所需的工具，使用户能够登录、证明资产所有权、签署交易等，所有操

怎么增加/切换账号？

从站点的右上角，点击个人头像打开个人控制面板点击头像下方的账号一栏，就能看到当前登录的所有账户和添加账号的按钮如果点击切换其他账号，则会自动切换至其他账号，无需再进行登录操作如果点击添加账户，则会打开正常的 DID Connect 流程，完成账户的登录。登录成功的账户也会显示在这个列表中

如何将我的社交账户绑定到钱包？

您可以通过 Google、Apple 等社交账号轻松连接到部分 Blocklet，无需立即设置 DID Wallet。

开发者指南

概览

通过 URL 制定 DID Connect 的行为

在某些情况下，需要在任意链接中能够使用户能够快速切换指定账号，此时可以通过 URL 参数来定制 DID Connect 部分行为

快速开始

集成 DID Connect 最简单的方式是先创建 Blocklet。如果你还不清楚如何创建 Blocklet，请参考： Create Blocklet 文档前置条件已经安装并且配置好 DID Wallet，并且手机和电脑连接到相同的局域网已经创建好使用 React 模板的 Blockl

关于文档

你将在这里了解到关于 DID Connect 的一切。

DID Connect 协议

DID Connect 协议是一个开放协议，它利用密码学技术，提供了一种安全、去中心化的机制，旨在连接用户与 DApp。在此协议中，我们将 Connect 定义为用户向 DApp 提供所请求声明应答的流程。

DID Connect 工作流程

术语表

常见问题

- How to use DID Connect in other frameworks

用户指南

- How do I update profile?

配置 OAuth 登录

- Configure GitHub login

配置 Auth0 登录

Auth0 是一个第三方登录的管理平台，通过 auth0，可以轻松的接入 Google, Apple, GitHub 等登录方式。Blocklet Server 支持为一个 Blocklet 配置并开启 Auth0 的登录。

配置 GitHub 登录

Github 提供了 OAuth 的登录方式，用户便可以通过 GitHub 账户来登录接入了 GitHub OAuth 的应用。对于用户来说，可以不需要再去记住不同的账户和密码，对于应用来说，无需再自己开发一套登录注册体系。所以无论对用户还是应用的开发者来说，都是一件好事。

配置 Google 登录

Google 提供了 OAuth 的登录方式，用户便可以通过 Google 账户来登录接入了 Google OAuth 的应用。对于用户来说，可以不需要再去记住不同的账户和密码，对于应用来说，无需再自己开发一套登录注册体系。所以无论对用户还是应用的开发者来说，都是一件好事。

参考

- DID Connect Protocol

请求摘要签名

此功能基本上与请求签名类似，区别在于它能够简化要签名的数据，并保护签名的原始内容，请参阅本文以了解如何使用 DID Connect 签署数据摘要。基本流程与“快速入门”章节一致，请按如下所示更改处理程序中的代码： const { toTypeInfo } = require('@arcblo

请求多个索赔

在某些情况下，您可能需要在一次 DID Connect 中进行多次签名，以获得更顺畅的体验。请参阅本文，了解如何通过 DID Connect 进行多项声明。基本流程与“快速入门”章节一致，请按如下方式更改处理程序中的代码： const { fromBase58, toBase58 } = requ

请求多个步骤

类似于请求多个声明，您可以在一次 DID Connect 中完成多个签名操作，不过这与之前的功能有所不同，请参阅本文以了解如何在 DID Connect 中执行多步操作。基本过程与“快速入门”章节保持一致，请按以下方式修改处理程序中的代码： const { fromBase58, toBase

请求NFT

在某些情况下，您可能需要查看您的DID Wallet中是否持有特定的NFT或VC。例如，如果您曾参加过ArcBlock devcon 2021，请参阅本文以了解如何使用DID Connect请求一些NFT或VC。

请求支付

在某些情况下，您可能需要向 Blocklet 支付费用，请阅读本文以了解如何通过 DID Connect 请求付款。基本过程与“快速入门”章节一致，请按如下方式修改处理程序中的代码： / eslint-disable no-console /const { fromTokenToUnit }

请求签名

基本的流程与快速开始章节中一致，将 handler 中代码改为以下内容：

怎么管理存储？

从网站的右上角个人头像，点击出现菜单，点击个人中心按钮在个人中心页面，点击设置按钮，打开存储管理标签页在该页面中可以查看当前连接的 DID Spaces 应用，也可以重新将当前应用连接至其他的 DID Spaces 应用

订阅 DID Connect 事件

概览

怎么更改通行证？

在访问 blocklet 的过程中，可能会遇到某些页面提示没有权限来访问，此时就代表你当前登录所使用的通行证权限不足，你可以考虑切换账号或者切换通行证来提升当前账户的权限。

怎么更新个人信息？

打开任意站点（例如 https://www.arcblock.io/zh ），从右上角点击个人的头像点击个人中心，跳转到个人中心页面点击页面中的头像，进行个人信息切换

类型速查表

协议

怎么管理登录会话？

从网站的右上角个人头像，点击出现菜单，点击个人中心按钮在个人中心页面，点击设置按钮，打开会话管理标签页该页面中可以查看当前账户所有的登录情况，包括登录的操作系统、浏览器信息、用户信息、首次活动时间、最近活动时间、最近的登录 IP 地址和行政区域同时当前用户可在页面中对其他的登录会话进行管理，可

如何在其他框架中使用 DID Connect

DID Connect 目前仅支持 React 调用，Vue.js, svelte, Solid.js, AngularJS 暂无计划跟进。

DID Names

基于 NFT 和可验证凭证的命名服务。

操作指南

设置域名的帮助文档:

使用 didnames CLI 批量托管域名

DID Names 提供了 didnames CLI 工具，方便从其它域名服务商更方便的托管域名到 DID Names.

常见问题解答

概述

托管域名

DID Domain 支持托管从其他域名注册商注册的域名，并颁发 NFT 之后，可以通过 NFT 在 Blocklet 平台使用该域名。

如何修改名称服务器和 DNS 解析

不同的注册商有不同的修改方式，本篇文档将演示一些注册商修改名称服务器和 NS 记录的方法。

在自己的 Blocklet Server 启用 DID Domain

旧版本的 Blocklet Server 上默认没有启用 DID Domain, 需要手动配置 DID Domain 服务的地址来启用:

订阅 DID 域名

在使用 DID 域名之前，需要先获得一个域名。可以按照下面的步骤获得一个域名。

如何将 Namecheap 中的域名托管到 DID Names

如果您在 namecheap.com 上购买了域名，可以参考下面的文档修改名称服务器。

介绍

DID 域名是什么？

术语

DID 域名和 DID Names 有什么关系？ DID 域名是一种类型的 DID Names 服务。统一本文中出现的“顶级域名”、“二级域名”和“子域名”概念由于许多人对顶级域名、二级域名和子域名的概念理解不一致，本文将对这些概念进行统一说明：顶级域名(Top-level domain, T

开始

如何在区块链平台上获取和使用域名:

升级 DID Names 订阅

如果您想将您的 DID 域名订阅从按月计费更改为按年计费，请查看下面的视频：

使用 DID 域名

有两种添加 DID 域名的方式:

DID Space SDK（Node.js）

@blocklet/did-space-js 在 Node.js 里以编程方式与 DID Space 交互。

API 参考

欢迎查阅 DID Space Client SDK 的完整 API 参考。本部分为每个可用的类、方法和命令提供了详细的文档。它旨在成为一个全面的资源，帮助您快速找到特定信息并了解 SDK 的全部功能。

NFT 命令

用于处理 NFT 相关资产及其关联 DID 文档的专门命令。这些命令简化了将以非同质化代币（NFT）形式表示的数字资产存储到您的 DID 空间中的过程。

PutNftObjectCommand

PutNftObjectCommand 是一个专门的命令，旨在上传数字资产（如图像、视频或音频文件），并同时创建或更新其关联的 DID 文档。此过程有效地将去中心化标识符（DID）链接到特定的数据片段，这是在 DID 空间内管理非同质化代币（NFT）和其他可验证数字资产的关键步骤。

对象命令

对象命令是用于在 DID Space 内与单个文件（或“对象”）进行交互的核心工具。它们为所有 CRUD（创建、读取、更新、删除）操作提供了基本构建块，允许您以编程方式上传、下载、列出和删除文件。

DeleteObjectCommand

DeleteObjectCommand 用于从您的 DID Space 中永久删除一个对象。此操作不可逆。

GetObjectCommand

GetObjectCommand 用于从您的 DID Space 中检索或下载对象。对象的内容以可读流的形式返回，这使得它能够高效处理任何大小的文件，而不会消耗过多的内存。

ListObjectsCommand

ListObjectsCommand 用于从您的 DID Space 中的指定路径检索对象列表，这些对象可以是文件或目录。它通过选项提供了灵活性，支持扁平化（仅列出直接子项）和递归（列出所有嵌套项）的目录遍历。

PutObjectCommand

PutObjectCommand 用于在您的 DID Space 中上传新对象或更新现有对象。此命令功能多样，可以处理各种数据类型，例如文件、字符串或缓冲区，是向您的空间添加内容的主要方法。

SpaceClient

SpaceClient 是与 DID Space API 交互的主要接口。它是 SDK 的主要入口点，负责处理配置、身份验证以及向您的 DID Space 分派命令。

同步命令

用于在 DID Space 中同步本地文件夹和远程目录状态的高级命令。这些命令通过自动检测差异并执行必要的操作，简化了保持目录同步的复杂过程。

SyncFolderPullCommand

SyncFolderPullCommand 是一个高级命令，旨在将 DID Space 中的远程目录同步到本地文件夹。它会智能地比较远程源和本地目标之间的文件，仅下载新的或已更新的文件。这能有效地确保您的本地目录是远程数据的最新镜像。

SyncFolderPushCommand

SyncFolderPushCommand 是一个高级命令，旨在高效地将本地目录与您的 DID Space 中的远程目录同步。它能智能地比较本地和远程状态，上传新的或已修改的文件，并可选择性地删除远程存在但本地已不存在的文件。此命令简化了诸如部署静态网站、备份重要数据或分发数字资产等常见任务。

客户端初始化与身份验证

SpaceClient 是与 DID Space 网络交互的主要接口。在上传文件或管理数据之前，您必须首先使用正确的配置和身份验证凭据创建客户端实例。本指南将引导您了解初始化和验证 SpaceClient 的各种策略。

核心概念

本节深入探讨了驱动 @blocklet/did-space-js SDK 的基本原则和架构模式。理解这些概念将帮助您更有效地使用该库，并更有信心地解决问题。该 SDK 构建在三大支柱之上：强大的命令模式、灵活的身份验证方法和安全的请求签名机制。

请求签名

为了确保与您的 DID Space 的每次交互的安全性和完整性，所有 API 请求都受到强大的加密签名机制的保护。此过程保证了请求的真实性——即由声明的身份发送——并且在传输过程中未被篡改。

快速入门

欢迎使用 DID Space Client SDK！本指南将引导您完成安装、配置 SDK 并执行您的第一次文件上传等基本步骤。只需几分钟，您就可以开始运行了。

指南

欢迎来到指南部分。在这里，您将找到实用的分步教程，旨在帮助您使用 DID Space Client SDK 完成常见任务和实现特定功能。每个指南都侧重于真实世界的工作流程，提供完整的代码示例和最佳实践。

管理文件夹预览

DID Space 允许您为任何文件夹设置自定义预览。此功能使您能够定义文件夹在应用程序中的呈现方式，将简单的文件列表转变为丰富的交互式体验，例如画廊、文档预览，甚至是迷你应用程序。这是通过文件夹的 .meta 目录中一个特殊的 preview.yml 文件来管理的。

同步文件夹

对于静态网站托管、数据备份或协作资产管理等应用而言，保持本地目录与 DID Space 中的远程目录同步是一项常见需求。DID Space 客户端 SDK 通过两个强大的高级命令简化了这一过程：SyncFolderPushCommand 和 SyncFolderPullCommand。

概述

欢迎使用 DID Space Client SDK for JavaScript！这是一个功能强大、现代化的库，专为 Node.js 环境设计，使您能够无缝地与 DID Space 进行交互。如果您正在构建用户真正拥有和控制其数据的应用程序，那么您来对地方了。

工具函数

@blocklet/did-space-js 库导出了一系列工具函数，旨在简化您在构建应用程序时遇到的常见任务。这些辅助函数处理诸如 DID 格式化、URL 规范化、编码和错误解析等操作，让您可以专注于核心应用程序逻辑。

DID Spaces 指南

DID Spaces 的使用说明：功能、特性和求助渠道。

DID Spaces UI（React）

@blocklet/did-space-react 提供连接和使用 DID Spaces 的 React 组件。

API 参考

本节是对 DIDSpaceConnect 和 DIDSpaceConnection 组件中用作属性 (props) 的关键 TypeScript 类型和接口的参考。理解这些数据结构对于开发者充分利用该库的全部功能、确保类型安全以及在 TypeScript 环境中正确配置组件至关重要。

类型

本节为整个 DID Space 组件库中使用的核心 TypeScript 类型和接口提供了详细的参考。理解这些数据结构对于在您的应用程序中正确设置组件属性类型和管理状态至关重要。

组件

DID Space React 库提供了一套核心组件，以简化连接和与 DID Spaces 交互的过程。这些组件封装了复杂的身份验证、状态检查和数据显示逻辑，让您可以轻松构建功能丰富的应用程序。

DIDSpaceConnect

DIDSpaceConnect 组件提供了一个多功能按钮，用于启动与 DID Space 的连接。它简化了各种认证流程，包括初始连接和重新连接，并可以与用户会话集成以进行持久化存储。

DIDSpaceConnection

DIDSpaceConnection 组件是一个多功能的 UI 卡片，旨在显示已连接 DID Space 的关键信息。它提供了一种清晰且互动的方式来展示空间的详细信息，包括其 NFT 头像、名称、DID 和当前连接状态。

快速入门

本指南将引导您完成将 DID Space 功能集成到您的 React 应用程序中的基本步骤。您将学习如何安装必要的软件包，并实现一个基础组件，让用户能够连接到他们的 DID Space 并查看其详细信息。

概览

欢迎阅读 @blocklet/did-space-react 的文档。该库提供了一套 React 组件，旨在简化将 DID Space 集成到您的应用程序中的过程。借助这些工具，您可以毫不费力地让用户连接他们的 DID Space 并显示相关信息，从而创造无缝且去中心化的用户体验。

DID Spaces 数据保留策略更新

欢迎来到 ArcBlock 社区！在这里，我们致力于为您提供一个分享见解、报告问题、寻求帮助以及激发创新的平台。为了优化资源并持续提供高质量的服务，我们计划从 2024 年 12 月 1 日 0 时 0 分（UTC 时间）开始，对 Prod Spaces 站点上超过半年的过期 DID Space

AIGNE

场景描述

应用示例

为了帮助开发者深入理解应用如何集成 DID Spaces 并实现正常运行，我们特意准备了以下示例来协助理解。

DID Spaces v0.5.83: OAuth 集成 DID Space

本次更新带来的新特性如下：

使用 @blocklet/did-space-js 读写 DID Space

概览

备份 Blocklet 到 DID Space

概览

获得 DID Space

概览

在首次登录应用时获得 DID Space 的 endpoint

概览

获得 DID Space 的 endpoint

概览

在安装启动流程中获得 DID Space 的 endpoint

概览

数据保留策略

概览

开发人员最佳实践

以下是正确使用 DID Spaces 的一些指南。

安装 DID 钱包

你可以参考 https://support.didwallet.io/howToDownload 完成钱包的下载安装.

常见问题

- Data retention policy

用户指南

概览

开发者指南

概览

MCP Server

概览

欢迎

概览

修复连接 DID Space 时的 CORS 错误

概览

通过安装 Personal DID Spaces 创建 DID Space

概览

免费领取 DID Space

概览

Draft: 购买 DID Space

概览

参考术语

DID Spaces

Draft: Default Space 如何付费升级？

这只是一个草稿，待完善

如何使用网关地址连接 DID Space

概览

Blocklet 的自动备份卡住了，如何快速恢复？

概览

如何重新订阅已经过期的 DID Space

概览

切换 NFT Blender 绑定的 DID Space

概览

DID Spaces v0.4.26 发布: 订阅全面采用按量付费 & 支持付费升级 Default Space

经过工程师们的不懈努力，DID Spaces 正式发布新版本 v0.4.26。本次更新的主要功能有订阅全面采用按量付费，正式支持付费升级 Default Space，以及新用户的 Default Space 创建在统一登录账号下。另外还有一些用户体验的改进。新特性订阅全面采用按量付费订阅的 D

存储 DID Wallet 的数据

概览

NFT Maker

场景描述

应用连接 DID Space，存储、展示个性化数据

概览

定价政策

概览

还原 Blocklet

概览

还原 Blocklet 到 Blocklet Server

概览

还原 Blocklet 到 Launcher

概览

存储个人数据

概览

DID Spaces v0.4 发布: 支持读写应用空间

截止目前，DID Spaces 的新版本 v0.4 已经发布。这次的更新包括新增的读写组件空间功能，以及其他一些改进和修复。

Todo List

概览

DID Spaces v1.0.48 Release: Support for reading and writing application spaces.

DID Spaces 重磅升级

DID Spaces v0.6.0：OAuth 集成 DID Spaces

本次更新的主要亮点为 OAuth 账户集成 DID Spaces，此外还有一些改进和社区反馈的修复。 OAuth 账户集成 DID Spaces 在最新的版本中， Prod Spaces 会自动地给每个 OAuth 账户赠送一块永久免费的 Default Space，并支持 OAuth 账户在任何地

变更日志

- Draft: Purchase DID Space

应用案例

目前，已经有一些线上应用接入了 DID Spaces，并运行良好。这些应用包括：

DID Wallet 指南

DID Wallet 的使用说明：支持多条链，把身份和资产放在一起管理。

如何开始

- What is DID wallet？

如何添加链？

打开你的钱包并转到首页点击右上角的设置。点击链管理在ArcBlock中可以管理Beta链的显示或隐藏 Ropsten、Rinkeby、Goerli、Kovan、币安智能链以及币安智能链测试网的显示隐藏可以在以太坊链下进行管理。

如何添加一个代币？

支持哪些链和代币?

如何添加ERC721 NFT？

在代币列表页面上，找到以太坊代币（取决于您的NFT在哪条链上），并进入代币详情页面; 选择您的ERC721 NFT账户，点击“更多”按钮进入账户详情页面; 点击详情页右上角的按钮，选择添加 ERC721。在显示的页面上，输入NFT合约地址和tokenId，然后点击添加。如果这个NFT属于您的账户，

如何备份助记词？

打开DID钱包并转到资产的主页。点击右上角的图标进入设置页面。继续点击右上角的图标进入设置页面。

如何连接 Dapp？

DID钱包支持三种连接DApps的方式：

如何跨链？

哪些帐号可以发起跨链

如何创建钱包？

DID钱包的创建过程非常简单。只需点击一次即可完成钱包创建。

如何下载 DID钱包？

DID Wallet目前支持在多个客户端平台上安装。

如何打开Face ID？

1. 进入菜单页面

如何找到跨链交易的哈希？

找到你进行跨链交易的账户，点击“在区块浏览器中查看” 找到 Withdraw Token 类型的交易点击进入交易详情，点击复制这个哈希

如何生成备份文件？

备份文件是完全恢复钱包的一种方式。有关如何恢复钱包的更多信息，请参考其他帮助文档。

如何获得原生ABT？

目前，获得 Native ABT 的唯一方式是：首先在以太坊主网上获得ERC20 ABT资产，然后通过ArcBridge将ERC20 ABT兑换为本地ABT，ArcBridge是内置在DID钱包中的跨链桥。

如何将您的NFT/通行证提供给 Dapp

你的 NFT 在哪里

如何为 Dapp 提供个人资料

如何创建个人资料

如何恢复跨链桥（质押/提现）历史记录？

我们目前只支持恢复提现记录。

如何从一个Dapp中恢复通行证？

从Dapp网页

如何恢复钱包？

DID 钱包支持两种方式恢复您的钱包：

如何将ABT交换到以太坊主网

目前，将您的本地ABT提取到以太坊主网（或加密交易所）的唯一方法是Arc Bridge。

管理资产

- How to add a token?

管理钱包

- How to turn on Face ID?

Q&A

- How to find the hash of a bridge transaction?

扫码功能可以做些什么？

DID Connect, 扫码最重要的功能是扫描DID Connect 二维码并进行后续操作; 请注意：连接 DID Connect，不会向第三方泄露您的私钥 Wallet Connect, 扫描Wallet Connect 二维码可以连接Wallet Connect，并进行相应操作；请注意：连接

What if I forget wallet password?

The DID wallet is a non-custodial wallet that does not store any information elsewhere. If your password is lost or forgotten, we can NOT help you get

什么是DID？

由DID技术实现的去中心化身份的体验和使用与传统数字身份非常不同：首先，您将不仅仅拥有一个DID，而是根据身份场合的需要拥有多个DID。每个DID都将为您提供一个独立的私人通道，使用终身加密与其他个人、组织或事物进行通信。因此，您可以更好地选择您的身份进行沟通，并更好地保护您的隐私。传统互联网的"人

DID钱包是什么？

DID钱包是一种领先的数字钱包，支持集中式身份和数字资产管理。

什么是助记词？

助记词是另一种明文私钥的形式，最初由BIP39提出，其目的是帮助用户记住复杂的私钥。

什么是质押冷却期？

质押冷却期

什么是罚没者？

罚没者

什么是质押？

在 Arcblock 区块链系统中，质押是一种获取权益并防止不良行为的方式。简单来说，质押就像是把你的资产暂时锁在一个特定的账户里，以此来换取一些好处或特权，同时也起到约束作用。具体来说，用户需要将一些资产锁定到一个特定的 DID 账户下，并指定一个罚没者和提取冷却期。质押就像是押金，用户可以选

支持哪些链和代币？

DID钱包支持ArcBlock链、以太坊主网、EVM兼容链（如BNB智能链），以及未来更多不同的链。

Why wallet has multiple addresses?

When a new DID Wallet is initialized, there are three addresses by default. Respectively is:

AIGNE DocSmith

建在 AIGNE Framework 上的文档生成工具，直接从源码产出结构化的多语言文档。

配置参考

config.yaml 文件是您文档生成的核心控制面板。通过调整其中的设置，您可以控制 AI 如何生成文档，包括文档结构、内容风格和语言支持等。本指南提供了每个配置字段的详细说明，帮助您根据项目需求进行精确调整。

初始设置

本指南将逐步引导您完成 AIGNE DocSmith 的交互式设置过程。该过程在您首次执行 aigne doc create 时会自动运行，但您也可以手动启动。其目标是创建一个 config.yaml 文件，用于存储您生成文档时的偏好设置。

管理偏好设置

您是否曾希望您的 AI 助手能记住您的指示？本指南将说明如何查看、移除和切换已保存的文档创建偏好设置，让您能够精细控制 AI 的输出，并确保其始终遵循您项目的特定风格。

问题排查

本指南帮助你诊断和修复使用 AIGNE DocSmith 时的常见问题。如果在生成、发布或配置过程中遇到问题，请查看以下场景的解决方案。

入门指南

本指南提供了安装 AIGNE DocSmith 并生成您的第一套文档的直接、分步流程。该过程旨在几分钟内完成，让您只需最少的设置即可从项目文件生成文档。

指南

本节提供了使用 AIGNE DocSmith 执行常见文档任务的结构化分步说明。每个指南都旨在引导您完成一个特定的工作流程，从最初的生成到最终的发布。

添加文档

您是否发现您的文档存在缺漏？aigne doc add-document 命令提供了一种简单直接的交互式方法，可将新主题引入您现有的文档结构中，确保您的内容与项目同步增长。

清理

需要重置您的项目或移除敏感数据？本指南将说明如何使用 aigne doc clear 命令安全地移除生成的文件、配置设置和缓存信息，帮助您维护一个整洁有序的工作区。

评估文档

想知道您的文档是否达到了标准？本指南将介绍 evaluate 命令，这是一个强大的工具，可以系统地评估您文档的质量和完整性，并提供清晰、可操作的报告来指导您进行改进。您将学习如何运行评估并解读其结果。

创建文档

本指南将引导您使用单个命令，从项目的源文件创建一套完整的文档。该过程设计得简单直接，从初始分析到最终内容创建，并包含一个交互式审查步骤，以确保输出的结构完全符合您的需求。

交互模式

是否对复杂的命令行选项感到不知所措？本指南将介绍如何使用交互模式，这是一个对话式界面，可以简化文档处理过程的每一步。阅读完毕后，您将能够使用简单、自然的语言指令来创建、更新、本地化和发布您的文档。

管理历史记录

是否想知道您的文档在何时进行了哪些更改？AIGNE DocSmith 会详细记录每一次更新。本指南将向您展示如何访问和阅读此历史记录，以便轻松追踪文档的演变过程。

发布文档

当您的文档创建后，最后一步是将其发布到线上。本文档将提供一个分步指南，指导您如何使用 aigne doc publish 命令来发布文档，使其可供您的受众访问。

移除文档

要保持文档的准确性，不仅需要添加内容，还需要进行精简。本指南详细介绍如何使用 aigne doc remove-document 命令从项目中安全地删除文档，确保您的文档集保持整洁和相关性。

本地化文档

将您的文档提供多种语言版本对于触及全球受众至关重要。本指南提供了使用 aigne doc localize 命令将您的内容本地化为 12 种受支持语言中任意一种的分步过程，确保您的文档对世界各地的用户来说都易于访问和理解。

更新内容

本指南介绍如何使用 update 命令修改现有文档。您可以通过反馈更新文档内容、添加或更新图表以及移除图表。

更新文档

随着项目的演进，您的文档也需要与时俱进。本节为您提供了一个中心枢纽，涵盖了所有与修改文档集相关的任务，确保其保持准确和相关。在这里，您将找到关于修改现有内容、整合新文档以及移除过时文件的指南。

概述

AIGNE DocSmith 是一款文档工具，它利用 AI 分析您项目的源代码并自动生成文档。它构建于 AIGNE Framework 之上，能够生成与您的代码库同步的结构化、多语言文档。这一过程解决了手动编写文档所面临的挑战，如耗时、易过时和不一致等问题。

发布日志

了解 AIGNE DocSmith 的最新动态。本页面按时间顺序记录了该工具每个版本的新功能、性能改进和错误修复。

DIF Hackathon 指南（2024）

2024 年 DIF Hackathon 的要点说明。

FAQ

Q1: What to do if I failed to connect to test store

Building on DID Connect

Introduction

Building with DID Wallet

The DID Wallet Dapp template provides a powerful foundation for building decentralized identity applications. Following this guide, you can create a f

Building on AIGNE

Introduction

Building on DID Spaces

Introduction

DIF Hackathon Guide (2024)

Welcome to the ArcBlock DIF Hackathon! As proud Decentralized Identity Foundation (DIF) members, we are thrilled to invite developers of all skill le

身份与数据空间

ARC 的调用者上下文、按 DID 划分的存储、会话数据视图，以及它们经过验证的边界。

调用者上下文

ARC 在受信的服务端上下文中解析调用者身份与可选的 instance membership，而不是根据 UI 消息或客户端提供的路径。

核心模型

在选择集成路径之前，先把已验证的调用者上下文、DID 作用域存储，以及文档用语 Data Space 分开。

当前合同边界

在做出运行时、部署或管理承诺之前，先弄清当前身份与数据空间文档的极限。

这里的 “Data Space” 指什么

把 Data Space 当作讨论数据上下文与可见性的用语，而不是已经公开的 ARC SDK 表面名称。

ARC 中的 DID Connect

ARC 内嵌 DID Connect service 代码，把受信凭据解析为调用者信息以及可选的 instance membership 上下文。

DID 作用域存储

当数据需要 DID 作用域的逻辑存储边界时，把 DID Space 作为 AFS provider 挂载，并按 transport 分别看待能力。

证据与版本边界

用源码、测试与隔离 CLI 运行，对照指定 ARC release 复验身份与数据空间主张。

集成身份

把已验证的调用者上下文当作进入 session 视图与 provider 策略的交接面；只在运行时已经解析凭据的地方接入 DID Connect。

检查本地空间

在 ARC 2.0.0-beta.42 上，对隔离 root 运行 arc space list、sync、tree、path、rm，并阅读真实输出。

身份与数据空间

理解 ARC 的调用者上下文、DID 作用域存储、session 数据视图，以及把它们分开的边界。

参考与边界

核对哪些身份与数据空间陈述是当前合同、哪些是架构用语、哪些仍需按 release 取证。

Session 数据

阅读 ARC 为单个 session 组合的调用者专用、临时与可选 space 视图。

用户、临时与 space 视图

session 收到受约束的 AFS 视图：自己的用户数据、session 本地临时数据，以及可选的调用者 space 视图。

Blocklet Launcher

ArcBlock 的托管服务，用来更快地把 Blocklet 跑起来。

数据保留政策

账单逾期后，数据不会被立刻删除。在逾期后，分为已逾期和已取消两个阶段，在这两个阶段可以对应用和数据做不同的处理。

在已有的 Blocklet Server 上启动应用

Blocklet Launcher 支持将应用安装在已有的 Blocklet Server 上，无论是在自己服务器上启动的还是在 Blocklet Launcher 上购买的专用空间。

在专用空间启动应用

专用空间（Dedicated Space) 是一个独立的服务器实例，采取预付费收费方式。主要步骤选择 Blocklet 购买专用空间等待准备好专用空间安装 Blocklet 配置 & 启动 1. 选择 Blocklet 在 https://store.blocklet.dev/ 中选择准

无法在按需空间中安装某些 Blocklet

原因

启动按需应用

按需空间（On-demand）的计费方式基于组件数量和使用时长，这种更加精细的计费模式使用户能够更灵活地根据实际需求进行订阅。新的计费方式采用了我们的 Payment Kit 带来的订阅模式，能自动支付自动扣费，不需要担心忘记付费服务停止的问题。主要步骤选择 Blocklet 购买按需空间安

常见问题解答

按需空间和专用空间之间有什么区别？

快速上手

概览

参考指南

了解定价和数据保留政策。

欢迎

Blocklet Launcher 是 ArcBlock 提供的托管服务，旨在提高您在启动和运行 Blocklet 时的效率。

定价政策

最新版 Launcher 升级了付费方式，目的是方便用户购买和维护空间。新的付费方式更方便，计费粒度更精确，可以更好的帮助用户按需使用。

转移应用的订阅

适用场景

媒体资源

ArcBlock 与 DID 的官方标识、组合和配色。从本 board 下载 SVG 和 PNG。

ArcBlock 标识

官方立方体、wordmark、横版和竖版组合，以及 ABT token 标识。每个 lockup 都有浅底和深底样张，并提供 SVG 和 PNG 下载。

DID 标识

官方 DID、DID Names、DID Spaces、DID Connect、DID Wallet 标识。每个 lockup 都有浅底和深底样张，并提供 SVG 和 PNG 下载。

媒体资源

ArcBlock 与 DID 的官方标识、组合和配色。从本 board 下载 SVG 和 PNG。

用法

浅底和深底该用哪份官方文件，以及从官方 SVG 取出的色值。

Media Kit

上传和托管媒体资源的 Blocklet：拖拽上传、图片标签、CDN 接入。

API 参考

欢迎查阅 Blocklet Uploader 包的 API 参考。本节为前端和后端库导出的所有组件、函数、props 和配置选项提供了全面的详细信息，是您获取深入技术信息的首选资源。

组件属性

组件是将功能齐全的文件上传界面集成到您的 React 应用程序中的主要方式。它构建于流行的 Uppy 库之上，并通过一套全面的属性实现高度可定制。本指南为所有可用属性提供了详细参考，使您能够根据特定需求定制上传器的行为、外观和功能。

前端：@blocklet/uploader

@blocklet/uploader 包提供了一个功能强大且高度可定制的 React 组件，用于在 Blocklet 生态系统中处理文件上传。它构建于 Uppy 之上，Uppy 是一个设计精良、模块化的开源文件上传器，可确保强大且用户友好的体验。

可用插件

@blocklet/uploader 通过几个强大的定制插件扩展了核心 Uppy 库。这些插件与 Blocklet 生态系统（特别是媒体套件）无缝集成，提供 AI 图像生成、浏览以前上传的文件和访问共享资源等功能。当您使用

与 Hooks

对于更高级的用例，您可能需要从应用程序的不同部分触发 Uploader，或以编程方式控制其行为。UploaderProvider 组件及其关联的 hooks 提供了一种灵活的方式，使用 React 的 Context API 将 Uploader 的 UI 与其触发器解耦。

initCompanion(options)

initCompanion 函数用于初始化和配置 Uppy Companion 中间件，该中间件是让用户能够从 Unsplash、Google Drive、Instagram 或直接 URL 等远程来源导入文件的关键。此函数是对官方 @uppy/companion 库的封装，旨在实现与 blockl

initDynamicResourceMiddleware(options)

initDynamicResourceMiddleware 是一个功能强大的 Express 中间件，旨在动态地从一个或多个指定目录提供文件。与 initStaticResourceMiddleware 不同，它会实时主动监视文件系统的变化（添加、删除、修改），因此非常适合用于提供在运行时可能发生变

后端：@blocklet/uploader-server

@blocklet/uploader-server 包提供了一套 Express.js 中间件，旨在处理 blocklet 后端的各种文件处理任务。它作为 @blocklet/uploader 前端组件的服务器端对应部分，支持直接文件上传、与远程源集成以及资源服务等功能。

initLocalStorageServer(options)

initLocalStorageServer 函数是用于处理从用户设备直接上传文件到你的 Blocklet 本地存储的核心中间件。它利用了强大的 Tus 可续传上传协议，确保上传过程可靠，并能在网络中断后恢复。

initStaticResourceMiddleware(options)

initStaticResourceMiddleware 是一个功能强大的 Express 中间件，旨在从其他已安装的 blocklet 中提供静态资源。这使得您的应用程序可以从依赖组件中访问共享资源，例如图片、样式表或字体，而无需了解它们在文件系统中的确切位置。

实用函数

@blocklet/uploader/utils 模块导出了一系列辅助函数，旨在简化与文件处理、URL 操作、Uppy 实例自定义和网络配置相关的常见任务。这些实用程序由 Uploader 组件内部使用，但您也可以在应用程序中使用它们以进行更高级的集成。

概念

@blocklet/uploader 包的设计兼具强大的功能和易于集成的特点。要充分利用它们，了解为其功能提供支持的核心概念和关键集成至关重要。本节探讨了上传器背后的基础技术和设计原则。

国际化 (i18n)

@blocklet/uploader 组件在设计时考虑到了全球用户，为多种语言和文本定制提供了强大的支持。这使您能够创建无缝的用户体验，让您的用户无论身在何处都能感到亲切自然。

与 Media Kit 集成

@blocklet/uploader 包专为与 Media Kit blocklet 的无缝、零配置集成而设计。Media Kit 为媒体存储、管理和处理提供集中式服务。当 Uploader 组件检测到 Media Kit 安装在同一环境中时，它会自动增强其功能，而无需开发者进行任何额外设置。这种自

与 Uppy 集成

@blocklet/uploader 包直接构建于 Uppy 之上，Uppy 是一个为 Web 设计的时尚、模块化且开源的文件上传器。我们没有从头开始构建文件上传器，而是利用了 Uppy 强大的核心引擎、广泛的插件生态系统和精致的用户界面。这使我们能够提供一个健壮且功能丰富的上传体验，同时专注于在

后端设置 (@blocklet/uploader-server)

本指南将引导你在基于 Express.js 的 Blocklet 中设置 @blocklet/uploader-server 包。该包提供了必要的服务器端中间件，用于处理由 @blocklet/uploader 前端组件发起的文件上传。

快速入门

本指南将引导您完成将功能强大的文件上传器集成到您的 Blocklet 中的基本步骤。我们将涵盖前端 UI 组件和可选的后端服务器设置，以帮助您快速上手。

前端设置 (@blocklet/uploader)

本指南将引导你完成在 Blocklet 中安装和集成 @blocklet/uploader React 组件的过程。该组件基于强大且可扩展的 Uppy 文件上传器构建，为文件上传提供了一个功能丰富的用户界面。

配置插件

@blocklet/uploader 组件构建于灵活而强大的 Uppy 文件上传器之上。这种架构允许通过基于插件的系统进行广泛的定制。Uploader 开箱即用地预先配置了几个基本插件，以及为与 Blocklet 生态系统集成而设计的特殊插件。

创建自定义插件

@blocklet/uploader 具有可扩展性设计。虽然它内置了几个强大的插件，但你也可以轻松添加自己的自定义选项卡，以集成独特的工作流、连接到专有服务或提供专门的用户界面。本指南将向你展示如何使用提供的 VirtualPlugin 组件创建一个新的插件选项卡。

指南

欢迎来到指南部分。在这里，您将找到实用的、面向任务的演练，以帮助您为上传器实现常见功能和自定义。这些指南建立在入门部分介绍的概念之上，为真实场景提供了分步说明。

处理上传

文件成功上传后，您通常需要在客户端和服务器上执行操作。本指南介绍了如何在 @blocklet/uploader 前端组件和 @blocklet/uploader-server 中间件中使用 onUploadFinish 回调来处理文件及其元数据。

集成远程源 (Companion)

要允许用户从外部来源（如直接 URL 或 Unsplash 等服务）导入文件，您需要在后端设置 Uppy 的 Companion 服务。@blocklet/uploader-server 包提供了一个方便的 initCompanion 函数，可以简化此过程。

概述

Blocklet Uploader 是一个专为 blocklets 设计的综合文件上传解决方案，它构建于强大且可扩展的 Uppy 文件上传器之上。它由两个主要软件包组成，协同工作以提供从浏览器用户界面到服务器文件处理的无缝体验。

NFT Studio

让数字创作者掌握创作全过程的工具。

概念指南

NFT 是什么?

通过 NFT Blender + AI 工具快速制作6000个龙年春节主题 NFT

先放几张成果图出来

生态项目

概述

常见问题

概述

如何给 Blocklet 绑定域名

为什么需要给 Blocklet 绑定域名?

如何搭建一个完整的 NFT 项目

概述

如何在本地挂载 NFT 系列 Blocklet

概述

如何将 NFT 模板发布到 Blocklet Store 中

概述

如何使用 SDK 上传 NFT 到 DID Spaces

概述

如何使用 AIGC 生成 NFT 图像资源

概述

如何使用 NFT Blender 管理素材

概述

如何使用 NFT Maker 创建 Collection

你可以前往以下网页了解更多

如何使用 SDK 回收或重新发布 NFT

概述

Midjourney

概述

快速上手

概览

操作指南

概览

欢迎

概览

官方项目

你可以前往以下网页了解更多

参考指南

概览

NFT Studio + Payment Kit 集成

如何添加 Stripe 支付，收取虚拟货币外的其它货币需要前往 Payment Kit 中添加新的支付方式，添加完成后重启所有应用，再前往 NFT Maker 进行配置多币种铸造即可如何使用 Payment Kit 中的余额分为 2 种情况：虚拟货币支付：在 DID Wallet 中找到

示例项目

概览

Stable Diffusion（DrawThings）

概述

Stable Diffusion（InvokeAI）

概述

Payment Kit UI（React）

@blocklet/payment-react 是 Blocklet 支付相关界面的 React 组件库。

组件

@blocklet/payment-react 库提供了一套全面的预构建 React 组件，旨在加速支付、订阅和捐赠功能的开发。这些组件进行了分类，以帮助您找到适合工作的工具，无论您需要的是完整的即用型解决方案，还是用于构建自定义体验的精细 UI 元素。

业务逻辑组件

业务逻辑组件是专门设计的 React 组件，用于处理与订阅和发票管理相关的复杂、有状态的操作。这些组件封装了完整的用户流程，例如支付逾期发票或恢复已取消的订阅，让您可以通过最少的设置轻松地将高级功能集成到您的应用程序中。

自动充值组件

自动充值功能通过在用户信用余额低于指定阈值时自动为其充值，确保服务不中断。该功能由两个主要组件管理：AutoTopup，用于显示当前配置；以及 AutoTopupModal，用于提供设置界面。

OverdueInvoicePayment

OverdueInvoicePayment 组件是一个专用工具，旨在处理特定客户或订阅的逾期发票支付。它通过自动获取逾期发票并为用户提供一个清晰的界面来结算其未付账款，从而简化了流程。

ResumeSubscription

ResumeSubscription 组件为用户提供了一个简单的 UI，用于恢复已取消的订阅。它会渲染一个对话框，引导用户完成确认过程，并自动处理需要重新质押等复杂场景。

Checkout 组件

@blocklet/payment-react 库提供了一套高级 Checkout 组件，旨在为各种支付场景提供完整、即用型的入口点。这些组件封装了从选择产品到完成支付的整个用户流程，让您能够以最少的设置集成复杂的支付体验。

CheckoutDonate

CheckoutDonate 组件为您的应用程序添加捐赠功能提供了一个灵活且易于集成的解决方案。它支持多种显示模式，从一个简单的打开结账对话框的按钮，到一个由您完全控制的自定义 UI。

CheckoutForm

CheckoutForm 组件是处理支付链接和结账会话的主要入口点。它作为一个高级封装器，根据提供的 ID 获取所有必要数据，并渲染相应的支付或捐赠界面。此组件是将完整的结账流程集成到您的应用程序中的最简单方法。

CheckoutTable

CheckoutTable 组件为订阅结账提供了一个完整的、开箱即用的解决方案。它会获取并渲染一个价格表，允许用户选择一个方案，然后无缝地将他们过渡到支付表单以完成购买。这个高级组件是将基于方案的支付流程集成到您的应用程序中的最快方法。

历史组件

@blocklet/payment-react 库提供了一套历史组件，旨在为您的用户提供清晰详细的过往活动视图。这些组件对于构建客户门户、账户仪表盘和管理界面至关重要，用户可以在这些界面中跟踪他们的账单、支付和信用使用情况。

CreditGrantsList

CreditGrantsList 组件渲染一个分页表格，用于显示客户的信用额度授予情况。它清晰地概述了每笔授予的状态、剩余额度、范围和有效期。

CreditTransactionsList

CreditTransactionsList 组件渲染了一个包含所有信用额度交易的详细分页表格，提供了信用额度使用和调整的清晰日志。它非常适合在客户门户或管理仪表板中使用，以跟踪信用额度的授予和消耗情况。

CustomerInvoiceList

CustomerInvoiceList 组件用于渲染客户的发票历史记录。它会从支付服务中获取并显示发票数据，并提供两种不同的布局：一种是按日期分组的简单列表，支持无限滚动；另一种是详细的分页表格。此组件必须在 PaymentProvider 内部使用才能正常工作。

CustomerPaymentList

CustomerPaymentList 组件呈现客户付款的详细历史记录。它通过无限滚动自动处理获取、分页和按日期对付款进行分组，为用户的交易历史提供清晰有序的视图。

UI 组件

@blocklet/payment-react 库提供了一套粒度化的 UI 组件，旨在为您在构建支付和结账界面时提供最大的灵活性。与封装了整个流程的高级结账组件不同，这些组件是用于创建自定义用户体验的构建块。

表单元素

@blocklet/payment-react 库提供了一系列精细的输入组件，旨在简化自定义支付和联系信息表单的创建。这些元素在构建时充分考虑了验证和用户体验，能够与 react-hook-form 顺畅集成，为数据收集提供了一个强大而灵活的解决方案。

AddressForm

AddressForm 组件提供了一个预构建的用户界面，用于收集账单地址信息。它与 react-hook-form 无缝集成，并包含针对邮政编码等字段的内置、特定国家/地区的验证。

CountrySelect

CountrySelect 组件提供了一个用户友好的国家选择下拉菜单。它具有可搜索列表、显示国旗，并提供响应式设计，可适应桌面和移动设备。该组件设计用于在 react-hook-form 管理的表单中使用。

CurrencySelector

CurrencySelector 组件提供了一个用户友好的界面，用于从可用选项列表中选择支付货币。它会显示每种货币的徽标、符号和关联的支付方式，方便用户做出选择。该组件通常在较大的支付或结账表单中使用。

PhoneInput

PhoneInput 组件提供了一个用户友好的国际电话号码输入字段。它与 react-hook-form 无缝集成，并包含一个带有国旗和拨号代码的可搜索国家选择器、自动号码格式化以及由 google-libphonenumber 提供支持的强大验证功能。

PaymentSummary

PaymentSummary 组件是任何结账流程中至关重要的 UI 元素。它提供了订单的详细分类，包括所有订单项、试用期信息、质押要求和最终总金额。它的设计是响应式的，可以为移动设备调整其布局。

PricingTable

PricingTable 组件是一个灵活的 UI 元素，旨在以结构化的响应式表格显示订阅计划和定价选项。它允许用户在计费周期（例如，月度、年度）之间切换，选择他们偏好的货币，并选择一个计划以继续。

快速入门

本指南将引导您完成安装 @blocklet/payment-react 并将一个基础、功能齐全的支付表单集成到您的应用程序中的基本步骤。只需几分钟，您就可以拥有一个可用的结账体验。

指南

欢迎来到指南部分。在这里，您将找到关于超出单个组件使用范围的高级主题的深入文章。这些指南旨在帮助您自定义库的外观，并利用其强大的实用功能来构建更复杂的支付解决方案。

主题化

了解如何使用内置的主题提供器和 Material-UI 主题选项来自定义支付组件的外观。@blocklet/payment-react 库基于 Material-UI 构建，让您能够广泛地控制支付流程的观感。

工具函数

@blocklet/payment-react 库导出了一套工具函数和类，旨在简化常见任务，例如发出 API 请求、管理缓存、处理日期、格式化价格和设置国际化。这些工具旨在与库的组件和提供程序无缝协作。

Hooks

@blocklet/payment-react 库提供了一组自定义 React hooks，用于封装和简化通用逻辑，例如处理实时事件或适应不同的屏幕尺寸。这些 hooks 允许您用最少的样板代码轻松地将高级功能集成到您的组件中。

useMobile

useMobile hook 是一个方便的实用程序，用于检测应用程序是否在移动尺寸的设备上查看。它通过利用 Material-UI 的断点系统，帮助您直接在 React 逻辑中创建响应式布局和组件。

useSubscription

useSubscription Hook 提供了一种使用 WebSocket 从支付服务订阅实时事件的简单方法。它处理连接、订阅和清理逻辑，让您可以专注于应用程序如何响应像 invoice.paid 这样的事件。

概述

@blocklet/payment-react 是一个全面的 React 组件库，旨在简化将支付流程、订阅和捐赠系统集成到您的 Blocklet 中的过程。它基于 Payment Kit 构建，提供了一套预构建、可定制且生产就绪的组件，帮助您以最少的精力构建强大的支付体验。

提供者

Context 提供者是 @blocklet/payment-react 的一个核心概念。它们充当您应用程序部分的包装器，使用 React 的 Context API 将必要的数据和函数传递给嵌套在其中的所有组件。这避免了需要通过组件树的多个层级手动向下传递 props。

DonateProvider

DonateProvider 是一个关键的上下文提供程序，用于管理应用程序中所有与捐赠相关的组件的状态和设置。它负责从后端获取配置、为提高性能而缓存配置，并将其提供给像 CheckoutDonate 这样的组件。

PaymentProvider

PaymentProvider 是 @blocklet/payment-react 库的基石。它作为一个上下文提供者，必须包裹您的应用程序或相关的支付组件。它负责获取必要的设置、管理应用程序状态，并向其所有子组件提供辅助函数和 API 客户端。

Payment Kit SDK（Node.js）

@blocklet/payment-js 用于调用 Payment Kit 的 API。

API 参考

API 参考为 PaymentKit Node.js SDK 中可用的每个资源和方法提供了详细的文档。每个资源都有一个专门的页面，其中包含有关其方法、参数、返回值和使用示例的全面信息。

结账会话

结账会话代表客户进行付款时的会话。它是收集付款详细信息以创建一次性付款或订阅的主要机制。创建会话后，您需要将客户重定向到一个安全的、托管的支付页面。付款完成后，客户将被重定向回您的应用程序。

优惠券

优惠券是为您的产品和服务提供折扣的强大工具。优惠券对象包含有关特定折扣的信息，例如百分比折扣或固定金额折扣。要使优惠券可兑换，您必须将其与一个或多个促销代码关联。此 API 允许您创建、管理和跟踪优惠券的使用情况。

信用额度授予

信用额度授予对象用于向您的客户发放信用额度，这些信用额度可用于抵扣未来的账单，尤其适用于基于用量或基于信用额度的计费模型。每次授予都会跟踪总金额、剩余余额、状态以及任何特定的适用性规则。

信用交易

信用交易对象记录客户信用余额的每一次变动。这包括授予、消耗、调整和过期。您可以使用此 API 检索客户信用活动的详细历史记录。

客户

客户对象允许您创建和管理您的企业所服务的客户。它们存储了联系方式、地址和账单历史等基本信息，这些信息是创建订阅和处理付款的基础。

发票

发票 API 允许您创建、管理和最终确定发票。它提供了处理各种计费场景的全面功能，包括一次性支付、定期订阅和基于信用的计费。您可以检索详细的发票信息、应用折扣、管理质押操作以及搜索历史记录。

Meter 事件

Meter 事件是您向特定 Meter 报告的使用记录。每个事件代表客户执行的可量化操作，可用于在使用量计费或信用计费模型中从其余额中扣除信用。在报告事件之前，您必须首先创建一个 Meter。

计量器

计量器用于定义和跟踪基于信用点的计费使用情况。它们代表您计费的特定功能或资源，例如 API 调用、数据存储或计算时间。每个计量器都会聚合发送给它的使用事件。

支付货币

支付货币 API 允许您管理可接受支付的货币。这包括标准的基于区块链的代币（如 ERC-20 或 ArcBlock 原生代币），以及用于实现基于信用的计费系统的自定义信用货币。

支付意图

支付意图 (Payment Intent) 是一个表示您向客户收款意图的对象，并跟踪支付过程的生命周期。它是 PaymentKit API 中的核心对象，控制着从客户到您的资金流动。支付意图可以与结账会话关联，用于面向用户的支付流程，也可以直接用于服务器端操作。

支付链接

支付链接是一个可共享、可重复使用的页面，用于销售产品或服务。您可以为一组特定的产品和价格创建一个链接，并通过各种渠道与多个客户共享。这样无需构建完整的结账流程，即可快速便捷地收款。

支付方式

支付方式对象代表了客户可以使用的不同支付途径，例如通过 Stripe（信用卡、银行账户）或各种加密货币网络。此 API 允许您配置、管理和列出可供客户使用的支付方式。

价格

Price 对象定义了特定产品的收费金额和频率。它将价格金额和货币与产品相关联。例如，一个产品可以有多个价格，每个价格使用不同的货币或计费周期。

产品

产品对象代表您向客户提供的商品、服务或数字信用。您可以将它们视为目录中的项目。每个产品可以有一个或多个相关联的价格。

促销代码

促销代码是客户在结账时可以输入的特定、面向用户的代码，用于获得折扣。每个促销代码都链接到一个父级优惠券，该优惠券定义了实际的折扣（例如，八折优惠、10 美元折扣）。这种两级结构允许您创建多个指向同一基础折扣的唯一代码，从而可以轻松跟踪不同的营销活动或分发渠道。

退款

退款对象代表向客户返还先前收费的资金。您可以创建新的退款、检索现有退款的详情，并列出所有退款以用于会计核算。创建退款时，其初始状态为 pending，并将被异步处理。

设置

设置 API 允许您管理 PaymentKit 中的各种配置，例如创建捐赠小部件或设置通知处理程序。每个设置都是一个可配置的资源，由其 type 和 mountLocation 标识。

订阅项目

订阅项目代表客户订阅的特定产品和价格。它们是订阅的组成部分，对于管理循环计费至关重要，特别是对于按使用量计费的计划。

Webhook 端点

Webhook 端点允许 PaymentKit 向您的服务器发送异步事件通知。这对于处理成功付款、订阅更新或收费失败等事件至关重要。通过创建和管理 Webhook 端点，您可以确保您的应用程序与付款和客户的状态保持同步。

核心概念

PaymentKit Node.js SDK 旨在处理各种计费场景。本节提供了实现最常见支付工作流程的实用指南。无论您是设置简单的一次性收费、管理定期订阅，还是构建复杂的基于积分的系统，这些指南都将引导您了解关键概念和实施步骤。

基于信用点的计费

基于信用点的计费是一种灵活的按需付费模式，非常适合使用量不固定的服务，例如 API 调用、数据存储或计算时间。客户消费他们已购买或获赠的信用点，而不是支付固定的周期性费用。

积分充值

PaymentKit 的基于积分的计费系统允许客户通过充值来补充其积分余额。您可以将一种积分货币配置为可充值，从而实现手动单次充值和当余额低于设定阈值时的自动充值。

折扣

PaymentKit 提供了一套使用 Coupons 和 Promotion Codes 的灵活折扣系统。这使您能够为客户提供各种类型的折扣，例如百分比折扣、固定金额折扣和限时优惠。

一次性付款

PaymentKit 提供了多种灵活的方式来处理商品或服务的一次性收费。本指南将详细介绍 Node.js SDK 中可用的三种主要方法，帮助您根据具体需求选择最佳方案。

Webhook

Webhook 是与 PaymentKit 构建可靠且可扩展集成的重要机制。与其持续轮询 API 以获取状态变更，您可以配置一个 Webhook 端点，当您账户中发生某些事件时，PaymentKit 将会向您指定的 URL 发送实时的 HTTP POST 通知。

环境

PaymentKit SDK 在两种不同的模式下运行：生产模式用于处理真实交易，测试模式用于开发和测试。每个 API 请求都在这些环境之一中执行。默认情况下，SDK 在生产模式下初始化。在开发期间使用测试模式来构建和验证您的集成至关重要，以免影响您的生产数据或产生真实费用。以编程方式配置您可以使用

快速入门

本指南将引导您完成在项目中启动和运行 PaymentKit Node.js SDK 的基本步骤。只需几分钟，您就可以安装 SDK，为测试环境进行配置，并进行您的第一次 API 调用。

概述

PaymentKit Node.js SDK 对 PaymentKit REST API 进行了便捷的封装，使您能够直接在 Node.js 应用程序中构建功能强大且灵活的支付体验。无论您是处理一次性购买、管理周期性订阅，还是实施复杂的基于信用的计费模型，该 SDK 都通过一个简洁、现代且完全类型化的

SDK 结构

PaymentKit Node.js SDK 基于模块化的、面向资源的架构构建。此设计可确保与 PaymentKit API 不同部分的交互是一致、可预测且稳健的。SDK 的核心使用一个中央实用工具为每个 API 资源（如客户、产品等）生成方法，该工具处理与底层 PaymentKit Blockle

Web Device

用 ARC Web Device 构建静态站点的开发者文档。

AUP layout 边界

把 AUP 用作 source-first 页面 layout 输入，同时把直接静态 tree 渲染和 layout component composition 分开。

编写站点

Web Device 文档草稿：配置、组合和扩展一个已有站点。

组件解析

找到目标 runtime 实际解析的 component；不要把历史 component 名称当成永久通用 catalog。

Layout components

Default theme 与本站 layout component 的导航 hub——一页一单元；不是多组件正文参考。

使用与覆盖组件

把可复用的 Web 呈现放在组件中，再有意识地从 theme 或 site 层覆盖。

`access-gate`

Web Device layout component `access-gate`：用途、边界、作者入口、证据与 sample 诚实边界。

`content-card`

Web Device layout component `content-card`：用途、边界、作者入口、证据与 sample 诚实边界。

`detail-content`

Web Device layout component `detail-content`：用途、边界、作者入口、证据与 sample 诚实边界。

`detail-sidebar`

Web Device layout component `detail-sidebar`：用途、边界、作者入口、证据与 sample 诚实边界。

`event-card`

Web Device layout component `event-card`：用途、边界、作者入口、证据与 sample 诚实边界。

`event-hero`

Web Device layout component `event-hero`：用途、边界、作者入口、证据与 sample 诚实边界。

`hero-banner`

Web Device layout component `hero-banner`：用途、边界、作者入口、证据与 sample 诚实边界。

`news-ticker`

Web Device layout component `news-ticker`：用途、边界、作者入口、证据与 sample 诚实边界。

`page-sections`

Web Device layout component `page-sections`：用途、边界、作者入口、证据与 sample 诚实边界。

`page-stack`

Web Device layout component `page-stack`：用途、边界、作者入口、证据与 sample 诚实边界。

`platform-stack`

Web Device layout component `platform-stack`：用途、边界、作者入口、证据与 sample 诚实边界。

`portal-footer`

Web Device layout component `portal-footer`：用途、边界、作者入口、证据与 sample 诚实边界。

`portal-header`

Web Device layout component `portal-header`：用途、边界、作者入口、证据与 sample 诚实边界。

`post-hero`

Web Device layout component `post-hero`：用途、边界、作者入口、证据与 sample 诚实边界。

`product-frame`

Web Device layout component `product-frame`：用途、边界、作者入口、证据与 sample 诚实边界。

`product-frame-gallery`

Web Device layout component `product-frame-gallery`：用途、边界、作者入口、证据与 sample 诚实边界。

`product-hero`

Web Device layout component `product-hero`：用途、边界、作者入口、证据与 sample 诚实边界。

`product-showcase`

Web Device layout component `product-showcase`：用途、边界、作者入口、证据与 sample 诚实边界。

`related-content`

Web Device layout component `related-content`：用途、边界、作者入口、证据与 sample 诚实边界。

`site-home`

Web Device layout component `site-home`：用途、边界、作者入口、证据与 sample 诚实边界。

site `container-members`

本站 layout component `container-members`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `content-card`

本站 layout component `content-card`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `editorial-feed`

本站 layout component `editorial-feed`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `event-detail`

本站 layout component `event-detail`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `globe`

Layout component `globe`：把 COBE WebGL 地球用作 figure、scene 或 backdrop。抄 AUP，设 variant 和可选 markers。不是 AUP 的 globe primitive。

site `glossary-index`

本站 layout component `glossary-index`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `landing-hero`

本站 layout component `landing-hero`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `landing-shell`

本站 layout component `landing-shell`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `leaf-shadow`

Layout component `leaf-shadow`：gobo 循环 overlay（视频或程序化 canvas）加 mix-blend-multiply。src 指向 100–400 KB 片段；用 gobo-loop 从一句场景描述做出新片段。

site `object-card`

本站 layout component `object-card`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `page-breadcrumb`

本站 layout component `page-breadcrumb`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `period-index`

本站 layout component `period-index`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `product-meta`

本站 layout component `product-meta`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `related-objects`

本站 layout component `related-objects`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `site-footer`

本站 layout component `site-footer`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `term-meta`

本站 layout component `term-meta`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

site `topic-meta`

本站 layout component `topic-meta`（`.web/components`）：用途、边界、证据与 sample 诚实边界。

`tag-list`

Web Device layout component `tag-list`：用途、边界、作者入口、证据与 sample 诚实边界。

`tech-hero`

Web Device layout component `tech-hero`：用途、边界、作者入口、证据与 sample 诚实边界。

`technology-card`

Web Device layout component `technology-card`：用途、边界、作者入口、证据与 sample 诚实边界。

限制谁能读一页

先声明集合默认权限，再用 access 收紧单条记录，发布前核对 serve-time 门。

内容访问参考

Web Device serve-time 访问门的字段、解析顺序、承认规则、HTTP 头与发现边界。

内容对象、元数据与语言

把一篇内容保留为目录化对象，并用明确的读取优先级管理正文和元数据。

Web Device 内容 Markdown

区分内容对象中的 Markdown、AUP text primitive 与 .web 组件，再从已验证的 source-plus-rendered 示例开始写。

内容站

通过保留目录形状的内容对象，并声明明确的 list/detail 呈现合同来添加 content collection。

自定义组件

添加一个完整 site component，核验 resolver contract，再从 page 组合它而不是复制呈现 tree。

定制主题与 tokens

先定制一层 site-owned token；把 local component overlay 当成另一个需明确核验的机制。

诊断站点

从最窄的失败边界开始，再区分 source、build 与陈旧/错误的本地预览。

目录与文件约定参考

按职责定位每一项公开 Web Device 约定，而不是复制一棵历史目录树。

建立第一个站点

从空目录建立一个可由 Web Device 直接在本地渲染的最小静态站点。

起步

Web Device 文档草稿：从范围确认到第一个可本地运行的网站。

Hero 实验室 · webgl-hero 背景

基于 webgl-hero widget 的 landing-hero heroVisual 候选目录，附精确配置与如实评价。

页面内评审模式

用 ?review=1 打开已渲染的 Web Device 页面，把锚定到文字的反馈写在内容项旁的 .review/ 里，并用页面批准与条目处理两级状态跟踪。

安装 ARC CLI

安装当前的 ARC 发布版，并确认终端能运行 arc。

Markdown 指令与结构

content-reader MD 指令与结构的导航 hub——一页一单元；不是多单元正文参考。

在 Markdown 中使用卡片

用 link-card、info-card 与 card-group 组织文档入口，并在正文中直接查看它们的只读渲染结果。

在 Markdown 中嵌入外部和内部内容

写出受支持的外部或同站 Markdown 嵌入语法，并在本页直接检查渲染出的 frame——源代码与 live 结果同页。

在 Markdown 中写表格与提示

把 GFM 表格和 GitHub 风格提示直接放入 Web Device 内容对象，并在同一页检查实际输出。

编写并嵌入 Markdown Slides

把一份 Markdown 内容对象写成可阅读的 slides，用 named layout 挂载播放器，并作为同站 16:9 播放器嵌入——本页含源代码与 live 播放器。

在 Markdown 中写步骤

用 steps 与 step directive 组织只读教程，并直接查看真实的编号结果与嵌套规则。

`:::action-card`

在 action-card 中放置导航选择，不承诺 exec 或数据写入。

`::::card-group`

在 document 网格中分组导航卡片，并验证 fence 深度与真实渲染。

`::embed`

将受支持的 URL 嵌入为沙箱 frame 或 media 块，并记录拒绝时的 fallback。

fenced code

Web Device Markdown 结构（structure） `fenced-code`：用途、边界、作者入口、证据与 sample 诚实边界。

Generic MD directive (incl. `::input`)

Web Device Markdown 指令（directive） `generic-directive`：用途、边界、作者入口、证据与 sample 诚实边界。

GFM admonition

在内容 Markdown 中放置 GitHub 风格 callout，并在同一页查看真实 document 渲染。

GFM table

在内容 Markdown 中放置 pipe 表，并在同一页查看真实 document 渲染。

heading

Web Device Markdown 结构（structure） `heading`：用途、边界、作者入口、证据与 sample 诚实边界。

image (inline)

Web Device Markdown 结构（structure） `image`：用途、边界、作者入口、证据与 sample 诚实边界。

`:::info-card`

放置非交互 info card，并在同一页查看只读正文。

`::link-card`

用 link-card 组织导航入口，并在同一页查看只读渲染结果。

list

Web Device Markdown 结构（structure） `list`：用途、边界、作者入口、证据与 sample 诚实边界。

paragraph

Web Device Markdown 结构（structure） `paragraph`：用途、边界、作者入口、证据与 sample 诚实边界。

raw HTML

Web Device Markdown 结构（structure） `raw-html`：用途、边界、作者入口、证据与 sample 诚实边界。

`slides: true` front matter

将内容记录标记为 slides，用 HR 分页，并诚实链接 live slides demo。

`:::step`

在 steps 下嵌套单步正文；完整 live sample 与 steps 容器同页。

`::::steps`

用 steps/step fence 编写静态编号教程，并查看真实 document 渲染。

thematicBreak / HR

把水平线当作分隔符；在 slides: true 下它们成为幻灯片边界。

文件夹媒体画廊（`::gallery`）

在内容条目旁放媒体文件夹，用 layout、密度与可选 lightbox 呈现；本页含每种模式的可运行样例。

沉浸式视频画廊（Expose 风格）

在文件夹画廊里把封面静图与短视频配对，让 stage/expose/story 的 plate 先显示封面，再无缝进入静音循环。

沉浸式 plate

最小信息站

先用已本地验证的 first-site path 建立小型信息站点，再添加内容集合或 theme overlay。

Web Device

用 Web Device 从 AFS 中的页面、内容和站点配置构建静态网站。

页面变体

给同一条页面 URL 声明几种成品渲染，在现有的 ?review=1 HUD 上比较，并把访客分流和写作期挑选分开。

用 AUP 建立页面

让页面 layout 组合站点组件，并理解 ARC 当前的 layout 查找顺序。

组合页面与布局

先给每个 route 建立 layout 边界，再把可复用呈现放进 Web component、读者数据放进内容对象。

预览、构建与发布

把本地验收、构建产物和正式发布保持为三个独立阶段。

发布与维护

Web Device 文档草稿：预览、构建、发布、检查和诊断站点。

实作指南

按任务组织的站点与 AUP 组合路径，只链接规范单元页与已验证指南——不在此复述组件 API。

实作：绑定 source 到 layout

声明 content source，再以完整 `$source.` 写入 layout section——只串联指南与单元页。

实作：集合列表页

用 source 绑定与 layout 组件单元页搭出内容集合列表——本页不复述 props。

实作：文档 board

用 surface 与组件单元页搭出文档 board 壳——合同仍在各单元页。

实作：第一站

按既有入门步骤与单元页顺序，搭出可本地运行的最小 Web Device 站点——不在此复述组件 API。

实作：文章中的 slides

用 MD 结构单元与 deck widget 单元把 Markdown 文章变成 slides——不在此复述 API。

参考

Web Device 文档：目录、语法、组件、surface、Markdown 与版本契约。

准备与适用范围

用 ARC 2.0.0-beta.25 从一个本地 blocklet 开始验证最小 Web Device 站点。

路由与语言参考

把已声明 page/content 映射为 route family，再添加 locale variant 而不复制一棵站点树。

路由、导航与语言

从页面和内容的声明推导路径，并把 locale 作为同一站点的视图而非复制站点。

运行、检查与查看

检查、构建并直接运行本地 blocklet，在浏览器中验收 Web Device 页面。

收藏与笔记（save 能力）

在 blocklet.yaml 的 save: 上声明页面收藏和划词笔记。默认开启，未登录不出现，侧栏或页面按钮。

SEO、链接与可访问性

把生成的 SEO/链接检查当作底线，再以人工可访问性检查收尾。

Showcase 映射

把 showcase-dsl / showcase 页面映射到 AUP primitive 与 widget 单元页，并说明如何本地跑 Showcase——不是全量托管。

全站配置

用 .web/site.yaml 集中声明语言、显示、SEO、模板与主题选择。

站点配置参考

用 `site.yaml` 表达站点级标量配置，并让 token、redirect 和 asset 保持在各自独立文件中。

理解站点目录

用 pages、content 与 .web 分开表达页面、内容对象和站点能力。

幻灯实验 · 上界

讲解密度上界样张：一层装饰（AIGC 图板 + shell）、字色纸面有章法、board 与 mark——Path A，不写自由 HTML。

Slide lab · coolbackgrounds

Three coolbackgrounds-inspired surfaces on porcelain paper: topo-soft, facet-soft, horizon-band.

Slide lab · dune

guizang-inspired dune pack: sand paper, charcoal type, topo-soft default.

幻灯片实验 · 论述风

实验性论述 deck：板式、tone、ink 主题。路径 A：AUP 双模式上的真实构图。

幻灯片实验 · 密排

实验性偏密 deck：短 grid 媒体、紧凑对照、短论点。仍然防溢出 —— 密不等于乱。

Slide lab · kraft

guizang-inspired kraft paper theme: warm stock, serif display, paper-grain default.

幻灯片实验 · shell 演示

实验性 shell-demo deck：每页一个 live shell（chart、map、calendar）。边界说明不与视觉页混写。

幻灯实验 · surface

讲解向演示 deckSurface：策展的 CSS 抽象背景作为默认装饰层。零图片资产。

幻灯片实验 · 视觉优先

实验性视觉优先 deck：单图、mosaic、grid、定比 stage。验证 16 by 9 播放器内的 media-fill 纪律。

Web Device Slides 示例

供 Web Device Slides 指南直接运行的小型 Markdown 演示文稿。

Web Device Markdown Slides 概览

概括 Markdown Slides 为什么把 presentation 和可阅读页面放在同一份内容对象中。

内容源绑定参考

引用四字段 source 合同，但不把页面查询误写成全站变量。

把内容绑定到页面

先声明一个内容 source，再以 $source 名称把它交给页面 layout。

Surfaces

Web Device surface 包导航 hub——一页一 surface；不是多 surface 正文参考。

`comments-surface` surface

Web Device surface `comments-surface`：用途、边界、作者入口、证据与 sample 诚实边界。

`docs-page` surface

Web Device surface `docs-page`：用途、边界、作者入口、证据与 sample 诚实边界。

`in-page-toc` surface

Web Device surface `in-page-toc`：用途、边界、作者入口、证据与 sample 诚实边界。

`pagination` surface

Web Device surface `pagination`：用途、边界、作者入口、证据与 sample 诚实边界。

`search-page` surface

Web Device surface `search-page`：用途、边界、作者入口、证据与 sample 诚实边界。

主题与 token 参考

引用 token 与 theme 边界，但不把 palette/tone 和 component-overlay 选择混成一件事。

主题与 tokens

用 token 建立稳定的视觉词汇，并把 theme library 选择和 component overlay 分开。

理解站点

Web Device 文档草稿：理解一个已有站点的目录、页面、内容、路由与语言。

版本兼容性

每一条命令和行为声明都应以实际产生证据的 ARC 版本来阅读。

Web3 Kit

构建 Web3 应用的一组现成模块。

如何安装 Point Up

Point Up 本身并没有任何实际的业务逻辑，它只提供了最基本的，纯粹的积分相关的能力。因此它的使用场景更多的是被组合进已有的业务逻辑中。

定制徽章的规则

Point Up 还支持配置定制的徽章规则，徽章规则的场景是，当我们在我们的业务逻辑中，希望用户完成一些特定的行为之后，给他们点亮一些个性的徽章，让用户在使用应用的过程中可以额外获得更多的成就感。

在 Virtual Gift Card 中

如果你的服务中安装了 Virtual Gift Card

在 DiscussKit 中

如果你的服务中安装了 DiscussKit

How to use components from Store?

Pages Kit is designed with extensibility in mind. You can use custom components from Blocklet Store to extend its capabilities.

通过代码调用的方式

上面的通过配置的方式使用 Point Up 需要对应的 Blocklet 已经支持了 Point Up 的能力。实现这些能力也很简单，只需要通过 Blocklet SDK 进行特定能力的 API 调用即可实现。如果你也在开发自己的 Blocklet，并且想把 Point Up 的积分能力融入到你的

通过配置的方式

目前已经有一些 Blocklet 支持通过配置的方式使用 Point Up 的积分能力，下面是常见的几种 Blocklet

AD Kit (Beta)

This blocklet is in beta and is not recommended for production use

AI Kit

Overview

Daily Attendance

Overview

Discuss Kit

Overview

如何收集书签

如果你遇到了喜欢的网站和内容，想要把它收集下来，那么 Discuss Kit 的 Bookmark 模块可以帮助你更高效的完成这个事情！

Discuss Kit

- How to use the Blog Module

如何使用 Blog 模块

如果你遇到了开心的事情，想要把它记录下来，那么 Discuss Kit 的 Blog 模块可以帮助你完成这个事情！

偏好设置

希望这篇文档，能帮助各位了解如何对 Discuss Kit 进行偏好设置

使用积分的规则

打开 Point Up 的管理控制台，切换到 “使用积分规则” Tab，然后点击页面的添加按钮开始添加第一条使用积分的规则

Pages Kit

- Custom Component

如何使用 Doc 模块

如果你遇到了需要提供文档给其它用户使用的场景，那么 Discuss Kit 的 Doc 模块可以帮助你完成这个事情！

Lucky Draw

Overview

如何配置积分规则

Point Up 支持多种类型的积分规则，可以参照下面的文档进行配置。

赚取积分的规则

打开 Point Up 的管理控制台，切换到 “赚取积分规则” Tab，然后点击页面的添加按钮开始添加第一条赚取积分的规则

Pages Kit

Overview

内置包清单

React

自定义组件

- How to use third-party dependencies (CDN)

如何使用第三方依赖（CDN）

前言

Point Up

概述

Promotion Kits

Overview

在 Lucky Draw 中

前面我们介绍了两种配置使用 Point Up 的方式，都是在让用户在我们的服务中获得积分，那么 Lucky Draw 这个 Blocklet 的出现是为了让用户可以去使用他们的积分做一些有趣的事情，比如进行一次激动人心的幸运抽奖。

如何使用积分规则

在 ArcBlock 平台，一个复杂的服务总是会有若干个小的 Blocklet 组合而成，Point Up 也是这样，一个基于 Blocklet 平台的服务可以通过组合进 Point Up 让自己的整个服务快速的拥有积分能力。

Token Prize Pool

Overview

Tweet Token (Share 2 Win)

Overview

积分等级的规则

Point Up 也支持配置不同的等级规则，当用户累计领取的积分达到等级规则之后，便可以获得对应的等级展示。

Virtual Gift Card

Overview

Vote Kit

Overview

Waiting List

Overview

FAQs

Overview

Getting Started

Overview

How To Guides

WIP

Reference Guide

WIP

Sample Projects

WIP

Welcome

Overview

ArcBlock 白皮书 V1

ArcBlock 技术白皮书：平台架构与核心组件。

ArcBlock 技术白皮书

概要