w3ds

W3DS — Web 3 Data Spaces

W3DS 让用户在个人 eVault 中拥有自己的数据，同时平台则充当可互换的前端。用户在一个平台上写入的数据，会通过 Awareness Protocol 自动同步到每个其他已注册平台。本技能面向基于 W3DS 构建的开发者：集成平台、调用 eVault GraphQL API、接入 Web3 Adapter，以及调试本地开发环境。

权威来源

https://docs.w3ds.metastate.foundation 是权威来源。 本技能是对该文档的精简索引，内容可能滞后。如果本技能与文档不一致，以文档为准——请说明这一点并遵循文档。

遇到不确定的情况，以及答案原本需要依赖记忆时，请获取文档。此技能中的每个引用都是有效 URL，无需先解析。

需求	获取内容
所有页面的机器可读索引	https://docs.w3ds.metastate.foundation/llms.txt
合并为单个文件的完整文档语料	https://docs.w3ds.metastate.foundation/llms-full.txt
此技能的最新版本	https://docs.w3ds.metastate.foundation/skill/SKILL.md
所有本体及其 schemaId	https://ontology.w3ds.metastate.foundation/schemas
域及其下的架构	https://ontology.w3ds.metastate.foundation/domains

正在 MetaState-Prototype-Project/prototype 检出目录中工作？docs/docs/** 是网站文档的镜像——它只是为了方便，并非第二权威来源。

不可妥协的原则

在进行任何设计前，请阅读 Data Ownership Rules。简而言之：

1. eVault 是事实来源。平台存储的任何内容都是它的投影。 文档将平台称为“缓存和聚合器”——这意味着可以保留权威数据的快速本地副本，而不意味着平台可以拥有这些数据。
2. 每个持久化实体都需要满足三项要求： 本体（解析得出的 schemaId，绝不自行编造）、可解析的所有者（ownerEnamePath 必须对每一行都能解析到数据主体，而非平台），以及明确指向该所有者 eVault 的写入路径。
3. 平台存在于 GitW3 仓库中。 同样的原则也适用于更高一层：仓库是 W3DS 发布的平台元数据的事实来源，这些元数据与代码一同保存在 .w3ds/platform.json 中。普通 Git 托管服务存储代码，但不存储平台 eName、已发布的配置文件、每个版本的身份信息、PPA 证书或部署记录。参见 reference/gitw3.md。
4. 要解析，不要凭记忆。 本体 ID、端点、GraphQL 字段名、ACL 动作和 eName 都要查询，而非凭记忆填写。本技能特意不包含任何本体 UUID。

使用本地数据库并不违反原则。某些用户数据仅存在于本地数据库中，才是违反原则。

编写任何 W3DS 代码之前的准备工作

请回答以下四个问题。如果无法回答，这就是需要指出的问题——请报告，而不是绕开问题编写代码。

1. 使用哪个本体？ GET https://ontology.w3ds.metastate.foundation/schemas，根据 title 查找，然后使用 GET /schemas/:id 确认字段名称。先使用 GET /domains/:id/schemas 按主题领域缩小范围。找不到匹配项 → 提出新本体。绝不要编造 schemaId——这会静默失败：写入成功，数据包也会分发出去，但每个接收平台都会因找不到匹配映射而丢弃它。
2. 哪个 eVault 拥有它？ 指明 ownerEnamePath，并确认它对每一行都能解析，而不仅仅是对理想情况有效。所有者是数据所描述的个人或群组。如果解析结果为空，handleChange 会静默返回，实体永远不会同步。
3. 真实数据还是投影？ 运用可重建性测试：如果删除这个数据库，并通过重放相关 eVaults 来重建，会丢失什么？ “没有重要内容”——这是正确的投影。任何用户会想念的数据——都不该只存放在你的系统中。
4. 是什么将数据写入 eVault？ 指出调用位置：本地写入之后的 handleChange，或无状态应用直接写入 eVault。“稍后再同步”意味着该平台目前拥有这些数据。

停止规则

遇到以下情况时，请停止，用用户自己的说法说明问题，提出以 eVault 为首选的替代方案，并且先征得同意，再编写代码：

• 设计将本地数据库设为用户数据的权威来源。 没有映射的表；没有对应本体的字段；在本地写入但没有通往任何 eVault 的路径的实体；eVault 可访问时，读取优先采用本地行而非从 eVault 派生的状态。
• 持久化实体类型没有本体，且无法从 Ontology 服务解析出本体。

第二种情况有解决路径，并非绝境。本体是普通的 JSON 文件，任何人都可以提出：起草 draft-07 架构（使用全新随机 UUIDv4 schemaId、从 GET /domains 获取的 domain、每个属性的 description、additionalProperties: false），提出向 services/ontology/schemas/ 提交 PR，并明确说明，在 PR 合并之前，该类型并不存在。完整流程见 reference/w3ds-native.md。

只有这两种情况需要停止。其他所有情况——缺少所有者路径、不熟悉的指令、服务宕机——都是需要解决并报告的常规问题，而非停止的理由。

无法验证时

没有获取工具、处于离线状态或获取失败？可以继续，但绝不要把未经验证的标识符说成已确认。

• 在回复中列出每一项未经验证的内容，并附上能够确认该内容的确切 URL。
• 在调用位置标记：// TODO(w3ds): unverified — confirm against https://ontology.w3ds.metastate.foundation/schemas。
• 绝不要用看似合理的 UUID、端点或字段名称来填补空缺。错误的标识符比明显的占位符更糟糕，因为它会静默失败。

完成标准

报告 W3DS 任务已完成前，请检查每一项：

• 每次 eVault GraphQL 和 HTTP 调用都发送 X-ENAME: @<ename>。
• 每个 eVault URL 都是在调用时从 Registry 获取的，没有硬编码。
• 每个 schemaId 都是在本次会话中从 Ontology 服务解析得出的，而不是凭记忆填写的。
• 每个新的实体类型都有对应的本体、可解析的 ownerEnamePath，以及指向所有者 eVault 的写入路径。
• 每次向映射表写入后都会调用 handleChange，包括迁移、种子数据、管理路径和后台作业中的写入。
• webhook 控制器按 eventId 去重、按全局 id 执行 upsert，并对平台不消费的本体返回 200。
• 没有任何凭空编造的内容：未经验证的 UUID、端点路径、GraphQL 字段、映射指令或 ACL 动词都不存在；若无法验证，则在响应中逐项标明，并在代码中注明。
• 对任何新持久化的内容都进行了可重建性测试，并在回答中说明。
• 如果工作涉及平台代码库：没有手动编辑受管理的 .w3ds/platform.json 字段、没有改写历史记录，也没有提交密钥材料。

生态系统地图

“数字自我”由三部分组成：eName + eID 证书 + eVault。用户在 eID Wallet 中持有密钥。Provisioner 会创建用户的 eVault。Registry 会将 W3ID 解析为 eVault URL，并托管平台目录。Ontology 服务会发布 JSON Schemas，供平台将其本地 Schema 映射到这些 JSON Schemas。每个平台上的 Web3 Adapter 会连接本地数据库与所有者的 eVault。数据发生变化时，eVault 会触发 Awareness Protocol，通知所有其他已注册的平台。

组件	一句话介绍	加载此参考文档
eVault	每个 W3ID 对应一个由 Neo4j 提供支持的 GraphQL 数据存储，写入时会发送 Webhook	reference/evault.md
W3ID / eName	基于 UUID 的持久标识符；eName = 在 Registry 中注册的 W3ID	reference/identity.md
Binding Document	将用户与 eName 关联的签名 MetaEnvelope（id_document、photograph、social_connection、self）	reference/identity.md
Registry	W3ID 解析、用于配置的 /entropy、JWKS、平台列表、密钥绑定证书（临时）	reference/registry.md
Ontology	通过 /schemas、/schemas/:id、/domains 提供的 JSON Schema draft-07 注册表	reference/registry.md
Provisioner	创建新的 eVault；提供 POST /provision	reference/wallet.md
eID Wallet	移动应用（Tauri/SvelteKit）；在 Secure Enclave / HSM 中持有 ECDSA P-256 密钥	reference/wallet.md
wallet-sdk	TypeScript SDK：provision、authenticate、syncPublicKeyToEvault；通过 CryptoAdapter 实现与加密方案无关	reference/wallet.md
Web3 Adapter	每个平台上连接本地数据库与 eVault 的桥接层；handleChange 用于向外同步，fromGlobal 用于向内同步	reference/platform.md
Awareness Protocol	写入后，eVault 会向其他每个平台发送 POST /api/webhook	reference/protocols.md
w3ds://auth	会话签名身份验证流程	reference/protocols.md
w3ds://sign	为任意负载（文档、投票、引用）进行会话签名	reference/protocols.md
w3ds://file	文件数据块的 URI 方案；格式为 w3ds://file?id=@<ename>/<meta-envelope-id>	reference/protocols.md
AaaS	Awareness-as-a-Service——用于替代 eVault 直接向多个平台发送 Webhook 的生产级方案	reference/protocols.md
GitW3	支持 W3DS 的 Git 锻造平台；.w3ds/platform.json、平台 / 版本 / 部署 eName、PPA	reference/gitw3.md
公司授权委托	董事授予带职衔的角色；个人代表公司签名；验证者可沿授权链追溯至董事会	reference/company-delegation.md

生产环境 URL

服务	URL
文档（权威）	https://docs.w3ds.metastate.foundation
Provisioner	https://provisioner.w3ds.metastate.foundation
Registry	https://registry.w3ds.metastate.foundation
Ontology	https://ontology.w3ds.metastate.foundation
GitW3（支持 W3DS 的 Git 锻造平台）	https://git.w3ds.metastate.foundation

来源：链接。

路由规则

在编写任何代码或配置之前，先加载以下参考文件。

用户问题提及……	加载
“这应该存放在数据库中吗”、“添加表 / 实体 / 模型 / 字段”、“如何对 X 建模”、缓存、本地副本、数据所有权、“这是 W3DS 原生的吗”、设计或架构评审	reference/w3ds-native.md
GitW3、.w3ds/platform.json、平台 eName、版本 eName、部署 eName、PPA 证书、移植现有应用、平台相关的 git remote / 标签 / 发布、w3ds-deployment-key.json、“应该把它托管在哪里”	reference/gitw3.md
webhook 控制器、mapping.json、handleChange、fromGlobal、toGlobal、Web3 Adapter、ownerEnamePath、__date、__calc、__file、“如何构建平台”	reference/platform.md
GraphQL、createMetaEnvelope、updateMetaEnvelope、removeMetaEnvelope、bulkCreateMetaEnvelopes、uploadFile、metaEnvelope(id)、metaEnvelopes、ACL、X-ENAME、/whois、/logs、MetaEnvelope、Envelope、Neo4j 模型	reference/evault.md
W3ID、eName、@<UUID> 格式、X-ENAME 标头、Binding Document、id_document、photograph、social_connection、self、密钥轮换、基于好友的恢复	reference/identity.md
Registry、/resolve、/entropy、/list、JWKS、密钥绑定证书、查找本体 ID、提议新本体、/schemas、/domains	reference/registry.md
w3ds://auth、w3ds://sign、Awareness Protocol 数据包、签名验证、ECDSA P-256、multibase、base58btc、base64 签名格式、verifySignature、AaaS、w3ds://file URI、解引用文件	reference/protocols.md
eID Wallet、wallet-sdk、provision、authenticate、syncPublicKeyToEvault、CryptoAdapter、硬件密钥与软件密钥、PATCH /public-key、跨设备密钥委派	reference/wallet.md
公司、董事、董事会、角色、委派、再次委派、“代表他人签名”、“代表公司签名”、verifyDelegatedSignature、buildDelegatedSignRequest、buildGrantSignRequest、w3ds-sign/v1、w3ds-grant/v1、作用域、appLimits、Shareholding	reference/company-delegation.md
pnpm dev:core、Dev Sandbox、端口（4321 / 3001 / 4000 / 8080）、REGISTRY_ENTROPY_KEY_JWK、pnpm generate-entropy-jwk、“webhook 未触发”、“签名验证失败”、“重复实体”	reference/dev-setup.md

如果问题涉及多个主题（平台构建时很常见），请在同一轮中加载最相关的两到三个参考文件，而不要分批加载。构建任务几乎总是需要 w3ds-native.md 和 platform.md。

不要猜测

以下任何一项如果靠猜，几乎肯定是错的：

• 本体 schemaId——请从 https://ontology.w3ds.metastate.foundation/schemas 查询。本技能按设计不包含这些值。w3ds-file-v1 是唯一例外：它是一个协议字符串字面量，不是注册表查询值，也不是 UUID。
• GraphQL 字段／mutation 名称——createMetaEnvelope 是惯用名称；storeMetaEnvelope 是旧别名，Web3 Adapter 的 EVaultClient 仍在内部使用。完整签名见 reference/evault.md。
• 映射指令语法——__date(...)、__calc(...)、__file(...)、tableName(path),globalAlias，以及数组 users(participants[].id),participantIds——reference/platform.md 中有原样示例。
• 签名编码——软件密钥会输出 base64 编码的原始 64 字节（r || s）；硬件密钥会输出 multibase base58btc（z...）。参见 reference/protocols.md。
• 端点路径和请求头——每个 eVault 请求都需要 X-ENAME: @<ename>。/provision 位于 Provisioner 上，而非 eVault-core（不过在本地开发环境中，两者都在端口 3001 上的同一个 eVault-core 进程中运行）。
• 平台清单值——platformName、分配的 ename、由发行版本控制的 version，以及任何 PPA 证明字段均由 GitW3 管理。切勿手动编辑、伪造或在不同平台之间复制这些值。参见 reference/gitw3.md。

不确定？请从 https://docs.w3ds.metastate.foundation 获取相关页面；如果无法获取，请遵循无法验证时中的说明。

术语要点

• MetaEnvelope 与 Envelope：MetaEnvelope 是顶层实体（一篇帖子、一个用户）。Envelope 是该实体的单个字段，作为独立的 Neo4j 节点存储，并通过 LINKS_TO 关联。
• W3ID 与 eName：所有 eName 都是 W3ID。只有在 Registry 中注册的 W3ID 才是 eName（可解析）。两者在全局范围内都采用 @<UUID> 格式。
• 本体与 schema：此处的“本体”指由 Ontology 服务发布、并通过其 schemaId（一个 W3ID）引用的特定 JSON Schema。并非语义网意义上的“本体”。
• 平台与后平台：平台通过 Web3 Adapter 和 /api/webhook 端点参与 W3DS。后平台以“无数据”模式运行——它不拥有数据，数据由用户的 eVault 持有。
• w3ds-file-v1 与 File 本体：w3ds-file-v1 是由 uploadFile 创建的低层存储 envelope，用于 blob 解引用。File 本体是更高层的平台记录，适用于文件管理器／电子签名类应用。两者不可互换——字段名称不同，所属层级也不同。详见 reference/protocols.md。
• Awareness Protocol 与 AaaS：Awareness Protocol 定义数据包／接收方契约。AaaS 是其持久化投递系统，包含 eVault 事务性 outbox、不可变事件、订阅、至少一次重试和死信。
• storeMetaEnvelope / updateMetaEnvelopeById：旧版 GraphQL mutation 名称，Web3 Adapter 的 EVaultClient 仍在内部使用。外部集成应使用 createMetaEnvelope / updateMetaEnvelope / removeMetaEnvelope。

工作方式

• 通过 Registry 为用户解析 eVault URL 后，再访问 /graphql 或 /whois。绝不硬编码 eVault URL；缓存解析结果、重新验证，并在 HEAD /whois 失败时清除缓存。
• 每次向 eVault 发起 GraphQL 或 HTTP 调用时，都需要携带 X-ENAME。缺少此标头是导致 400 错误的最常见原因。
• 两种 ACL 模型并存。_acl 块提供按操作类型划分的授权（READ/CREATE/UPDATE/DELETE 位掩码）、拒绝规则和本体条件；存在时以此为准。旧版 acl 字符串数组则是全有或全无，但 ["*"] 除外；对于没有 _acl 的记录，它仍然适用。不要不加区分地将 ACL 描述为全有或全无——请参阅 reference/evault.md。
• Webhook 投递采用至少一次语义。Webhook 控制器必须以 eventId（而非全局 MetaEnvelope id）实现幂等性；不同更新会有意共用同一个 id。
• 投递仅保证按订阅和 MetaEnvelope 排序，不保证全局排序。eVault 会持续重试 AaaS 数据导入，直到收到确认；AaaS 会重试订阅方 24 小时，之后将消息移入死信队列。
• 不要镜像已有办法观察到的内容。如果某条记录通过 Awareness Protocol 到达，就订阅它，而不是再写入一个 envelope 让它可见。
• 正在构建准备发布的平台？请尽早说明它应归属 GitW3 仓库——直接导入普通仓库并不等同于引导式迁移流程，事后补加身份信息比从一开始就设置好更糟。
• 绝不要提交 w3ds-deployment-key.json、平台令牌、迁移证明或个人访问令牌。如果用户要求你在任何地方粘贴密钥材料，请停止操作并说明原因。
• 如果用户在本地运行相关服务，开始排查问题前先查看 reference/dev-setup.md——大多数同步故障都是服务未运行或缺少环境变量所致。