# @geoprotocol/geo-sdk 中文文档

规范地址：https://npmcn.com/package/%40geoprotocol/geo-sdk/

版本：0\.20\.6
npm 元数据更新时间：2026-11-11T19:13:40.758Z
中文译文更新时间：2026-11-16T04:53:09.562Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geoprotocol/geo-sdk
原文对照：https://npmcn.com/package/%40geoprotocol/geo-sdk/?lang=original
项目主页：https://github.com/geobrowser/geo-sdk#readme
源码仓库：https://github.com/geobrowser/geo-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.4 MB，718 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2026-01-23T10:09:40.452Z
- 最新版本发布：2026-11-11T19:13:39.740Z
- 近 30 天下载量：4983（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

与"图"互动的工具集.

## 安装

```sh
npm install @geoprotocol/geo-sdk
```

也可以使用：`pnpm add @geoprotocol/geo-sdk`、`yarn add @geoprotocol/geo-sdk`、`bun add @geoprotocol/geo-sdk`

## README

# 地理 SDK

与"图"互动的工具集.

## 安装

```sh
npm install @geoprotocol/geo-sdk
```

## 大赦国际

如果您使用AI编码助手(如克洛德代码, Codex, Cursor)与这个SDK合作, 请检查 [地理浏览器/地理技能](https://github.com/geobrowser/geo-skills) 帮助代理有效使用Geo SDK的技能和提示.

## 概览

### 数据流动

"图"中的数据同时生活在链外和链上. 这些数据是写给IPFS的,由此产生的内容标识符在被索引堆栈读取之前被放入链上. 在索引器完成数据处理后,它被API所曝光.

![CleanShot 2025-01-22 at 10 51 23@2x](https://github.com/user-attachments/assets/f0cee8e0-43f9-4663-a2e7-54de6d962115)

### 空间

在图上,知识被组织成空间. 任何人都可以为社区、项目或个人创造空间。 空间在链上组织成一套智能合同. 这些合同代表空间本身、数据和管理过程.

### 实体

一个实体是一个独特的标识符,代表一个人,一个地方,一个想法,一个概念,或者其他任何东西. 实体由描述实体的三重关系组成。 一个实体的数据可以同时由多个空间组成. 这种财产使得图中的多元化得以实现.

[更多关于实体和知识图](https://www.geobrowser.io/space/720eb279c64d56735dccd17a2a416ba2/a72654b014fa405bbf1250ba901bc082)

### 关系

关系描述图中的边缘. 关系本身就是包含关系细节的实体. 例如,一家公司可以拥有团队成员. 每个团队成员关系可以有一个属性来描述人物加入团队的时间. 这是一个属性图模型.

### 操作和编辑

该图中的数据被存储为 Op( 操作) 。 操作是适用于实体的一组更改。 修改可以是设定或删除三重关系或关系。 三重和关系都作为行动组织代表.

在写入数据时,这些操作被分组为称为编辑的逻辑集. 一个编辑器有一个名称,作者和元数据来代表一组更改. 此编辑在被上传到IPFS之前被编码为二进制表示.

[GRC-20 中的操作和编辑](https://github.com/yanivtal/graph-improvement-proposals/blob/new-ops/grcs/0020-knowledge-graph.md#101-operations-op)

## 使用

首选的API有两个部分:

-   `Ops` 建立GRC-20操作.
-   `createGeoClient(...)` 处理配置的工作流程,如API呼叫、上传、RPC读取和交易呼叫数据.

```ts
import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });

const { id: entityId, ops } = Ops.entities.create({
  name: "Test Entity",
  description: "Created with the new API",
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

await walletClient.sendTransaction({ to: tx.to, data: tx.calldata });
```

### 赞助的EIP-7702 交易

使用 `createGeoWalletClient` 需要枢密院支持的道德操守办公室、当地道德操守办公室或 在保存 EOA 的同时发送 Geo 赞助交易的其他支持的签名符 地址作为账户身份.

```ts
import {
  GeoTestnetConfig,
  createGeoClient,
  createGeoWalletClient,
} from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });

const walletClient = await createGeoWalletClient({
  signer, // Privy viem wallet client, EIP-1193 provider, or local account
  network: GeoTestnetConfig,
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

await walletClient.sendTransaction({ to: tx.to, data: tx.calldata });
```

`GeoTestnetConfig` 包括Geo默认的赞助RPC URL. 使用 `defineGeoNetworkConfig` 当您想要使用自定义链 RPC URL 时 赞助项目.

### 进口

当方便重要时使用根包 :

```ts
import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";
```

用于捆绑敏感代码的子路径导出

```ts
import { entities, relations } from "@geoprotocol/geo-sdk/ops";
import { createGeoClient } from "@geoprotocol/geo-sdk/client";
import {
  GeoTestnetConfig,
  defineGeoNetworkConfig,
} from "@geoprotocol/geo-sdk/networks";
```

使用 `Ops` 从 `@geoprotocol/geo-sdk` 对于行动建设者。 配置工作流程位于后面 `createGeoClient`。 。 。 .

### 网络配置

使用内置测试网配置 :

```ts
import { GeoTestnetConfig, createGeoClient } from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });

console.log(geo.network.id); // "TESTNET"
```

`network` ,客户端则需要完整配置对象。 过 `GeoTestnetConfig`,而不是字符串 `"TESTNET"`。 。 。 .

定义自定义部署 :

```ts
import { createGeoClient, defineGeoNetworkConfig } from "@geoprotocol/geo-sdk";

const local = defineGeoNetworkConfig({
  id: "LOCAL",
  name: "Local Geo",
  apiOrigin: "http://localhost:3000",
  chain: {
    id: 31337,
    name: "Anvil",
    rpcUrl: "http://localhost:8545",
  },
  contracts: {
    SPACE_REGISTRY_ADDRESS: "0x0000000000000000000000000000000000000001",
    DAO_SPACE_FACTORY_ADDRESS: "0x0000000000000000000000000000000000000002",
  },
});

const geo = createGeoClient({ network: local });
```

运行时间不提供时通过抓取执行 `globalThis.fetch`,或者当您想要测试隔离时:

```ts
const geo = createGeoClient({
  network: GeoTestnetConfig,
  fetch: customFetch,
});
```

### 当地合同 V2 验证

在与本地geobrowser 合同核对时, 部署该堆 首先,它写 `.deployments.json`,然后将SDK选入测试指向它:

```sh
cd /path/to/local-geobrowser
just init-infra
just init-contract

cd /path/to/geo-sdk
GEO_LOCAL_GEOBROWSER_DEPLOYMENTS=/path/to/local-geobrowser/.deployments.json \
  pnpm exec vitest run src/contracts-v2/local-geobrowser.e2e.test.ts
```

测试建立自定义 `defineGeoNetworkConfig(...)` 从部署文件 并解码 DAO 创建、更新- 投票设定提案和版本投票 与合同v2 ABIs的调取数据.

## 操作 API

Ops函数构建操作数组,在发布前可以合并.

```ts
import type { Op } from "@geoprotocol/geo-sdk";

const ops: Op[] = [];
ops.push(...entityOps);
ops.push(...relationOps);
```

### 属性、 类型和实体

创建属性、类型和实体:

```ts
import { Ops } from "@geoprotocol/geo-sdk";

const { id: websitePropertyId, ops: propertyOps } = Ops.properties.create({
  name: "Website",
  dataType: "TEXT",
});

const { id: restaurantTypeId, ops: typeOps } = Ops.types.create({
  name: "Restaurant",
  properties: [websitePropertyId],
});

const { id: restaurantId, ops: entityOps } = Ops.entities.create({
  name: "Yum Yum",
  description: "A restaurant serving fusion cuisine",
  types: [restaurantTypeId],
  values: [
    {
      property: websitePropertyId,
      type: "text",
      value: "https://example.com",
    },
  ],
});

const ops = [...propertyOps, ...typeOps, ...entityOps];
```

更新一个实体 :

```ts
const { ops } = Ops.entities.update({
  id: restaurantId,
  name: "Yum Yum Kitchen",
  values: [
    {
      property: websitePropertyId,
      type: "text",
      value: "https://yum.example",
    },
  ],
});
```

未设置属性值 :

```ts
const { ops } = Ops.entities.update({
  id: restaurantId,
  unset: [
    { property: websitePropertyId },
    { property: descriptionPropertyId, language: "all" },
  ],
});
```

创建关系属性 :

```ts
const { id: likesPropertyId, ops } = Ops.properties.create({
  name: "Likes",
  dataType: "RELATION",
  relationValueTypes: [restaurantTypeId],
});
```

### 类型值

实体值为已键入对象。 这个 `type` 字段决定值形状 :

```ts
import { Ops } from "@geoprotocol/geo-sdk";

const { ops } = Ops.entities.create({
  name: "Cafe visit",
  values: [
    { property: namePropertyId, type: "text", value: "Morning Coffee" },
    { property: openPropertyId, type: "boolean", value: true },
    { property: visitsPropertyId, type: "integer", value: 42 },
    { property: ratingPropertyId, type: "float", value: 4.8 },
    { property: openedDatePropertyId, type: "date", value: "2024-01-15" },
    { property: opensAtPropertyId, type: "time", value: "08:30:00Z" },
    {
      property: reviewedAtPropertyId,
      type: "datetime",
      value: "2024-01-15T14:30:00Z",
    },
    {
      property: schedulePropertyId,
      type: "schedule",
      value: "FREQ=WEEKLY;BYDAY=MO,WE,FR",
    },
    {
      property: locationPropertyId,
      type: "point",
      lon: -122.4194,
      lat: 37.7749,
    },
    {
      property: bytesPropertyId,
      type: "bytes",
      value: new Uint8Array([1, 2, 3]),
    },
  ],
});
```

### 关系

创建、更新和删除关系实体 :

```ts
import { Ops, Position } from "@geoprotocol/geo-sdk";

const { id: relationId, ops: createRelationOps } = Ops.relations.create({
  fromEntity: personId,
  toEntity: restaurantId,
  type: likesPropertyId,
  position: Position.generate(),
});

const { ops: updateRelationOps } = Ops.relations.update({
  id: relationId,
  position: Position.generateBetween(previousPosition, nextPosition),
});

const { ops: deleteRelationOps } = Ops.relations.delete({
  id: relationId,
});
```

关系还可以带有自己的实体价值:

```ts
const { ops } = Ops.relations.create({
  fromEntity: personId,
  toEntity: companyId,
  type: teamMemberPropertyId,
  entityName: "Team member",
  entityValues: [
    {
      property: joinedDatePropertyId,
      type: "date",
      value: "2024-05-01",
    },
  ],
});
```

### 块

创建带有生成或稳定ID的文本和数据块 :

```ts
import { Ops } from "@geoprotocol/geo-sdk";

const { id: textBlockId, ops: textBlockOps } = Ops.textBlocks.create({
  fromId: pageId,
  text: "# Heading",
});

const { id: dataBlockId, ops: dataBlockOps } = Ops.dataBlocks.create({
  fromId: pageId,
  sourceType: "QUERY",
  id: stableDataBlockId,
});
```

### 图像

图像创作经过 `geo.images.create(...)`。配置客户端上传图像,在可能时检测到维度,并返回图像实体操作.

### 评论

创建一个实体的注释 :

```ts
import { Ops } from "@geoprotocol/geo-sdk";

const { id: commentId, ops } = Ops.comments.create({
  content: "Looks good to me.",
  replyTo: {
    entityId,
    spaceId,
  },
});
```

当您已有回覆链上下文时创建嵌入式注释 :

```ts
const { ops } = Ops.comments.create({
  content: "Replying to the parent comment.",
  replyTo: {
    entityId: parentCommentId,
    spaceId,
  },
  replyToRelations: [
    {
      entityId: rootEntityId,
      spaceId,
      position: "a0",
    },
  ],
});
```

更新评论 :

```ts
const { ops } = Ops.comments.update({
  id: commentId,
  content: "Updated comment text.",
  resolved: true,
});
```

使用 `geo.comments.create(...)` 当从配置的 API 获取回执链上下文时.

### 二. 审查

创建和更新提案审查业务:

```ts
import { Ops } from "@geoprotocol/geo-sdk";

const { id: reviewId, ops: createReviewOps } = Ops.proposalReviews.create({
  proposal: {
    id: proposalId,
    name: "Improve restaurant data",
  },
  pass: true,
  content: "The proposal is complete and accurate.",
  completeness: 1,
  accuracy: 0.8,
  skill: 0.8,
  effort: 0.6,
});

const { ops: updateReviewOps } = Ops.proposalReviews.update({
  proposalReviewId: reviewId,
  pass: false,
  content: "Needs more sources.",
});
```

## 客户端 API

一次创建已配置的客户端,并将其用于需要API来源,上传,RPC URL或合同地址的工作流程.

```ts
import { GeoTestnetConfig, Ops, createGeoClient } from "@geoprotocol/geo-sdk";

const geo = createGeoClient({ network: GeoTestnetConfig });
```

### `geo.api`

使用 `geo.api.graphql(...)` 用于低级图QL请求:

```ts
const response = await geo.api.graphql<{
  entity: { id: string; name: string | null } | null;
}>(`
  query {
    entity(id: "3af3e22d21694a078681516710b7ecf1") {
      id
      name
    }
  }
`);

if (response.errors) {
  console.error(response.errors);
}
```

使用 `geo.api.getEditCalldata(...)` 当调用数据必须来自 API:

```ts
const { to, data } = await geo.api.getEditCalldata({
  spaceId,
  cid: "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
});

await walletClient.sendTransaction({ to, data });
```

对于个人空间编辑, 偏好 `geo.personalSpaces.publishEdit(...)`。 。 。 .

### `geo.images`

在一个呼叫中上传图像并构建图像实体操作 :

```ts
const imageFromUrl = await geo.images.create({
  url: "https://example.com/cover.png",
  name: "Cover image",
  description: "Image used as the space cover.",
});

console.log(imageFromUrl.id);
console.log(imageFromUrl.cid);
console.log(imageFromUrl.ops);
```

也可以通过一个 `Blob` 直接 :

```ts
const file = new Blob([imageBytes], { type: "image/png" });

const imageFromBlob = await geo.images.create({
  blob: file,
  name: "Cover image",
});

console.log(imageFromBlob.cid);
```

### `geo.storage`

使用 `geo.images.create(...)` 当您想要上传一个图像并在一个呼叫中创建图像实体操作。 使用 `geo.storage.uploadImage(...)` 仅当您需要原始上传的 CID 并检测到没有图形操作的维度时 :

```ts
const uploaded = await geo.storage.uploadImage({
  url: "https://example.com/photo.png",
});

console.log(uploaded.cid);
console.log(uploaded.dimensions);
```

上传 CSV 内容 :

```ts
const cid = await geo.storage.uploadCSV(`name,score
Alice,10
Bob,8`);
```

### `geo.entities`

从空格中删除一个实体:

```ts
const { ops } = await geo.entities.delete({
  id: entityId,
  spaceId,
});
```

实体删除查询所配置的API在目标空间中的当前值和关系,然后建立操作来取消这些值并删除这些关系. 该实体在该空间中向空态过渡;它没有在全球被摧毁.

### `geo.comments`

在保存回复链时创建注释 :

```ts
const comment = await geo.comments.create({
  content: "This should be easier to find.",
  replyTo: {
    entityId,
    spaceId,
  },
});
```

对另一项评论的答复:

```ts
const reply = await geo.comments.create({
  content: "Following up here.",
  replyTo: {
    entityId: comment.id,
    spaceId,
  },
});
```

更新评论 :

```ts
const { ops } = geo.comments.update({
  id: comment.id,
  content: "Updated comment text.",
  resolved: true,
});
```

### `geo.personalSpaces`

检查地址是否有个人空间 :

```ts
const hasExistingSpace = await geo.personalSpaces.hasSpace({
  address: account.address,
});
```

创建个人空间 :

```ts
const createSpace = geo.personalSpaces.create({
  name: "Alice",
  accountAddress: account.address,
});

await walletClient.sendTransaction({
  to: createSpace.to,
  data: createSpace.calldata,
});
```

`geo.personalSpaces.create(...)` 并返回初始配置文件 。 在创建 - 空格交易被挖掘后, 您知道新的 `spaceId`并立即将生成的空间实体设定为空间主题:

```ts
const profileTx = await geo.personalSpaces.publishEdit({
  name: "Create personal space profile",
  spaceId,
  author: spaceId,
  ops: createSpace.ops,
});

await walletClient.sendTransaction({
  to: profileTx.to,
  data: profileTx.calldata,
});

const topicTx = geo.personalSpaces.setTopic({
  spaceId,
  topicId: createSpace.spaceEntityId,
});

await walletClient.sendTransaction({
  to: topicTx.to,
  data: topicTx.calldata,
});
```

发布编辑到个人空间 :

```ts
const { ops } = Ops.entities.create({
  name: "Test Entity",
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

await walletClient.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});
```

这个 `author` 字段是作者的个人空间ID,而不是钱包地址.

### `geo.daoSpaces`

DAO帮助者瞄准合同v2表面. 投票设置使用百分比 和二级投票时间 合同的比基整数。 使用 DAO 合同的网络配置 位于合同v2部署点.

```ts
const votingSettings = {
  partialPercentageSupportThreshold: 50,
  universalPercentageSupportThreshold: 90,
  flatSupportThreshold: 1,
  quorum: 1,
  durationInSeconds: 2 * 24 * 60 * 60,
  disableFastPathAccessForNewMembers: true,
  executionGracePeriodInDays: 14,
};
```

创建 DAO 空间 :

```ts
const tx = await geo.daoSpaces.create({
  name: "Research DAO",
  author: authorSpaceId,
  initialEditorSpaceIds: [authorSpaceId],
  initialMemberSpaceIds: [authorSpaceId],
  votingSettings,
});

await walletClient.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});
```

在 DAO 创建编辑中包含额外的初始操作 :

```ts
const { ops } = Ops.entities.create({
  name: "DAO Welcome Page",
});

const tx = await geo.daoSpaces.create({
  name: "Research DAO",
  author: authorSpaceId,
  initialEditorSpaceIds: [authorSpaceId],
  votingSettings,
  ops,
});
```

向 DAO 空间建议编辑 :

```ts
const { ops } = Ops.entities.update({
  id: entityId,
  name: "Updated entity name",
});

const proposal = await geo.daoSpaces.proposeEdit({
  name: "Update entity name",
  ops,
  author: authorSpaceId,
  callerSpaceId: authorSpaceId,
  daoSpaceId,
  votingMode: "FAST",
});

await walletClient.sendTransaction({
  to: proposal.to,
  data: proposal.calldata,
});
```

创建新版本的现有编辑建议 :

```ts
const updatedProposal = await geo.daoSpaces.proposeEdit({
  name: "Update entity name, revision 2",
  ops,
  author: authorSpaceId,
  callerSpaceId: authorSpaceId,
  daoSpaceId,
  proposalId,
  updateProposal: true,
  versionId: 2,
});
```

若为 `updateProposal: true` 设置和 `versionId` 被省略, SDK 读取 dAO 地址来自 `SpaceRegistry.spaceIdToAddress(...)`,然后读取 `latestProposalVersion(...)` 从已配置的 RPC 网络上传编辑前. 过 `versionId` 当您已经知道下一个版本或当您的自定义网络配置没有 RPC URL 时.

管理 DAO 成员和编辑器 :

```ts
const addMember = geo.daoSpaces.proposeAddMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  newMemberSpaceId: memberSpaceId,
  votingMode: "FAST",
});

const removeMember = geo.daoSpaces.proposeRemoveMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  memberToRemoveSpaceId: memberSpaceId,
});

const addEditor = geo.daoSpaces.proposeAddEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  newEditorSpaceId: editorSpaceId,
});

const removeEditor = geo.daoSpaces.proposeRemoveEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  editorToRemoveSpaceId: editorSpaceId,
});
```

编辑器只更改支持 `SLOW` 投票。 成员更改可以使用默认或明示 `votingMode`。 。 。 .

建议的投票设定修改:

```ts
const updateVoting = geo.daoSpaces.proposeUpdateVotingSettings({
  authorSpaceId,
  spaceId: daoSpaceId,
  votingSettings: {
    partialPercentageSupportThreshold: 60,
    universalPercentageSupportThreshold: 95,
    flatSupportThreshold: 2,
    quorum: 2,
    durationInSeconds: 5 * 24 * 60 * 60,
    disableFastPathAccessForNewMembers: true,
    executionGracePeriodInDays: 14,
  },
});
```

只支持更新投票设置 `SLOW` 投票.

管理一个空格的快速路径访问 :

```ts
// Editor-only, takes effect immediately. Not a proposal, so there is no proposalId.
// Any space can be restricted, including another editor, and lifting it takes a SLOW vote.
const restrict = geo.daoSpaces.restrictMemberFastPath({
  authorSpaceId: editorSpaceId,
  spaceId: daoSpaceId,
  memberSpaceId,
});

// Lifting a restriction is a governance action: SLOW proposal only.
const unrestrict = geo.daoSpaces.proposeUnrestrictMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  restrictedMemberSpaceId: memberSpaceId,
});

// Adds a space and lifts its restriction in one SLOW proposal (addMember, then unrestrictSpace).
// The way back to fast-path access for a space that left while restricted: a restricted space can't request membership itself.
const addBack = geo.daoSpaces.proposeAddMemberWithFastPath({
  authorSpaceId,
  spaceId: daoSpaceId,
  newMemberSpaceId: memberSpaceId,
});
```

仅使用 `proposeAddMemberWithFastPath` 对于已经不是成员或编辑器的空间,一旦添加,将保留限制(DAO限制新成员,或者空间已经限制). 否则,该提案将无法执行.

请求加入 DAO 空间 :

```ts
const request = geo.daoSpaces.proposeRequestMembership({
  authorSpaceId: requesterSpaceId,
  spaceId: daoSpaceId,
});

await walletClient.sendTransaction({
  to: request.to,
  data: request.calldata,
});
```

DAO建议 ID 和 DAO 空间 ID 是 bytes16 十六元字符串,通常是 `0x` 加上32个十六进制字符.

就一项提案进行表决:

```ts
const vote = geo.daoSpaces.voteProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
  versionId: 1,
  vote: "YES",
});

await walletClient.sendTransaction({
  to: vote.to,
  data: vote.calldata,
});
```

`versionId` 默认为 `1`在对后一提案进行表决时明确通过 版本.

执行已通过的提案:

```ts
const execute = geo.daoSpaces.executeProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
});

await walletClient.sendTransaction({
  to: execute.to,
  data: execute.calldata,
});
```

### `geo.responses`

在三个独立轴线上响应一个实体:

-   校正 : `upvote`, (中文(简体) ), `downvote`,以及 `unvote`
-   斯丹斯: `agree`, (中文(简体) ), `disagree`,以及 `unagree`
-   速度 : `verify`, (中文(简体) ), `dispute`,以及 `unverify`

每个清晰的方法只去除其匹配的响应类型. 譬如说, `unverify` 不从同一个用户中去掉一个上标或协议.

创建目录响应调用数据 :

```ts
const upvote = geo.responses.upvote({
  authorSpaceId,
  spaceId,
  entityId,
});

const downvote = geo.responses.downvote({
  authorSpaceId,
  spaceId,
  entityId,
});

const unvote = geo.responses.unvote({
  authorSpaceId,
  spaceId,
  entityId,
});
```

创建姿态响应呼叫数据 :

```ts
const agree = geo.responses.agree({ authorSpaceId, spaceId, entityId });
const disagree = geo.responses.disagree({ authorSpaceId, spaceId, entityId });
const unagree = geo.responses.unagree({ authorSpaceId, spaceId, entityId });
```

创建真实响应调用数据 :

```ts
const verify = geo.responses.verify({ authorSpaceId, spaceId, entityId });
const dispute = geo.responses.dispute({ authorSpaceId, spaceId, entityId });
const unverify = geo.responses.unverify({
  authorSpaceId,
  spaceId,
  entityId,
});
```

用钱包客户端提交任何已返回的交易 :

```ts
await walletClient.sendTransaction({
  to: upvote.to,
  data: upvote.calldata,
});
```

## 附有担保钱包的完整出版流程

此示例使用被赞助者发布编辑到已有个人空间 地理钱包客户端 .

```ts
import { createPublicClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import {
  GeoTestnetConfig,
  Ops,
  createGeoClient,
  createGeoWalletClient,
} from "@geoprotocol/geo-sdk";
import { SpaceRegistryAbi } from "@geoprotocol/geo-sdk/abis";

const privateKey = `0x${privateKeyFromGeoWallet}` as `0x${string}`;
const signer = privateKeyToAccount(privateKey);
const geo = createGeoClient({ network: GeoTestnetConfig });
const walletClient = await createGeoWalletClient({
  signer,
  network: GeoTestnetConfig,
});
const accountAddress = signer.address;

const hasSpace = await geo.personalSpaces.hasSpace({
  address: accountAddress,
});

if (!hasSpace) {
  throw new Error("No personal space found for this account.");
}

const spaceRegistryAddress = GeoTestnetConfig.contracts?.SPACE_REGISTRY_ADDRESS;
const rpcUrl = GeoTestnetConfig.chain?.rpcUrl;
if (!spaceRegistryAddress || !rpcUrl) {
  throw new Error("GeoTestnetConfig is missing registry or RPC configuration.");
}

const publicClient = createPublicClient({
  transport: http(rpcUrl),
});

const spaceIdHex = (await publicClient.readContract({
  address: spaceRegistryAddress,
  abi: SpaceRegistryAbi,
  functionName: "addressToSpaceId",
  args: [accountAddress],
})) as Hex;

const spaceId = spaceIdHex.slice(2, 34).toLowerCase();

const { id: entityId, ops } = Ops.entities.create({
  name: "Test Entity",
  description: "Created via Geo SDK",
});

const tx = await geo.personalSpaces.publishEdit({
  name: "Create Test Entity",
  spaceId,
  author: spaceId,
  ops,
});

const txHash = await walletClient.sendTransaction({
  to: tx.to,
  data: tx.calldata,
});

await publicClient.waitForTransactionReceipt({ hash: txHash });
console.log("Published entity", entityId, "to space", spaceId);
```

## 完整的个人空间创建流程

此示例创建了带有 EOA 钱包的个人空间, 然后发布初始配置 ops 返回 `geo.personalSpaces.create(...)`。 。 。 .

```ts
import { createPublicClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import {
  GeoTestnetConfig,
  createGeoClient,
  createGeoWalletClient,
} from "@geoprotocol/geo-sdk";
import { SpaceRegistryAbi } from "@geoprotocol/geo-sdk/abis";

const privateKey = "0xTODO" as `0x${string}`;
const account = privateKeyToAccount(privateKey);
const geo = createGeoClient({ network: GeoTestnetConfig });

const walletClient = await createGeoWalletClient({
  signer: account,
  network: GeoTestnetConfig,
});

const rpcUrl = GeoTestnetConfig.chain?.rpcUrl;
const spaceRegistryAddress = GeoTestnetConfig.contracts?.SPACE_REGISTRY_ADDRESS;
if (!rpcUrl || !spaceRegistryAddress) {
  throw new Error("GeoTestnetConfig is missing registry or RPC configuration.");
}

const publicClient = createPublicClient({
  transport: http(rpcUrl),
});

const hasSpace = await geo.personalSpaces.hasSpace({
  address: account.address,
});

let spaceIdHex = (await publicClient.readContract({
  address: spaceRegistryAddress,
  abi: SpaceRegistryAbi,
  functionName: "addressToSpaceId",
  args: [account.address],
})) as Hex;

if (!hasSpace) {
  const createSpace = geo.personalSpaces.create({
    name: "Alice",
    accountAddress: account.address,
  });

  const createSpaceHash = await walletClient.sendTransaction({
    account: walletClient.account,
    to: createSpace.to,
    data: createSpace.calldata,
  });

  await publicClient.waitForTransactionReceipt({ hash: createSpaceHash });

  spaceIdHex = (await publicClient.readContract({
    address: spaceRegistryAddress,
    abi: SpaceRegistryAbi,
    functionName: "addressToSpaceId",
    args: [account.address],
  })) as Hex;

  const spaceId = spaceIdHex.slice(2, 34).toLowerCase();
  const profileTx = await geo.personalSpaces.publishEdit({
    name: "Create personal space profile",
    spaceId,
    author: spaceId,
    ops: createSpace.ops,
  });

  const profileHash = await walletClient.sendTransaction({
    account: walletClient.account,
    to: profileTx.to,
    data: profileTx.calldata,
  });

  await publicClient.waitForTransactionReceipt({ hash: profileHash });

  const topicTx = geo.personalSpaces.setTopic({
    spaceId,
    topicId: createSpace.spaceEntityId,
  });

  const topicHash = await walletClient.sendTransaction({
    account: walletClient.account,
    to: topicTx.to,
    data: topicTx.calldata,
  });

  await publicClient.waitForTransactionReceipt({ hash: topicHash });
}

const spaceId = spaceIdHex.slice(2, 34).toLowerCase();
console.log("Personal space ID", spaceId);
```

## 公用事业

### 身份证

实体、财产、关系、空间和提议使用全球独特的身份证。 犬科SDK ID是一个UUID v4,没有破折号.

```ts
import { Id, IdUtils } from "@geoprotocol/geo-sdk";

const generatedId = IdUtils.generate();
const checkedId = Id(generatedId);
const bytes = IdUtils.toBytes(checkedId);
```

### 职位

`Position` 为定单关系和其他定单项目提供分数索引帮助.

```ts
import { Position } from "@geoprotocol/geo-sdk";

const first = Position.generate();
const between = Position.generateBetween(first, null);
const sorted = Position.sort([between, null, first]);
```

### 钱包客户端

`createGeoWalletClient` 是提交 SDK 交易的默认方式. 它默认使用来自网络的Geo赞助交易配置.

```ts
import { GeoTestnetConfig, createGeoWalletClient } from "@geoprotocol/geo-sdk";

const walletClient = await createGeoWalletClient({
  signer,
  network: GeoTestnetConfig,
});
```

小心私钥. 不要让他们接受版本控制.

## 遗产 API

遗留的命名空间仍为兼容性导出, 但新代码更可取 `Ops` 财务报告和审定财务报表 `createGeoClient`。 。 。 .

| 遗产 API | 首选 API |
| --- | --- |
| `Graph.createEntity(...)` | `Ops.entities.create(...)` |
| `Graph.updateEntity(...)` | `Ops.entities.update(...)` |
| `Graph.deleteEntity(...)` | `geo.entities.delete(...)` |
| `Graph.createImage(...)` | `geo.images.create(...)` |
| `Graph.createComment(...)` | `geo.comments.create(...)` 或者说 `Ops.comments.create(...)` 附有答复的上下文 |
| `TextBlock.make(...)` | `Ops.textBlocks.create(...)` |
| `DataBlock.make(...)` | `Ops.dataBlocks.create(...)` |
| `Ipfs.publishEdit(...)` | `geo.personalSpaces.publishEdit(...)` 或者说 `geo.daoSpaces.proposeEdit(...)` |
| `Ipfs.uploadImage(...)` | `geo.storage.uploadImage(...)` |
| `Ipfs.uploadCSV(...)` | `geo.storage.uploadCSV(...)` |
| `personalSpace.*` | `geo.personalSpaces.*` |
| `daoSpace.*` | `geo.daoSpaces.*` |
| 根编码助手 | 在可用的情况下配置客户端交易助手 |

### 遗产 `Graph`

```ts
import { Graph } from "@geoprotocol/geo-sdk";

const { id: propertyId, ops: propertyOps } = Graph.createProperty({
  name: "Website",
  dataType: "TEXT",
});

const { id: typeId, ops: typeOps } = Graph.createType({
  name: "Restaurant",
  properties: [propertyId],
});

const { id: entityId, ops: entityOps } = Graph.createEntity({
  name: "Yum Yum",
  types: [typeId],
  values: [
    {
      property: propertyId,
      type: "text",
      value: "https://example.com",
    },
  ],
});

const { ops: updateOps } = Graph.updateEntity({
  id: entityId,
  name: "Updated name",
});

const { ops: deleteOps } = await Graph.deleteEntity({
  id: entityId,
  spaceId,
  network: "TESTNET",
});
```

遗产关系助手 :

```ts
const { id: relationId, ops: createRelationOps } = Graph.createRelation({
  fromEntity: personId,
  toEntity: restaurantId,
  type: likesPropertyId,
});

const { ops: updateRelationOps } = Graph.updateRelation({
  id: relationId,
  position,
});

const { ops: deleteRelationOps } = Graph.deleteRelation({
  id: relationId,
});
```

遗产图像和评论助手 :

```ts
const image = await Graph.createImage({
  url: "https://example.com/image.png",
  network: "TESTNET",
});

const comment = await Graph.createComment({
  content: "Looks good.",
  replyTo: { entityId, spaceId },
  network: "TESTNET",
});
```

### 遗产 `Ipfs`

```ts
import { Ipfs } from "@geoprotocol/geo-sdk";

const edit = await Ipfs.publishEdit({
  name: "Create entity",
  author: spaceId,
  ops,
  network: "TESTNET",
});

const image = await Ipfs.uploadImage(
  { url: "https://example.com/image.png" },
  "TESTNET",
);

const csvCid = await Ipfs.uploadCSV("name,score\nAlice,10", "TESTNET");
```

### 遗产 `personalSpace`

```ts
import { personalSpace } from "@geoprotocol/geo-sdk";

const hasSpace = await personalSpace.hasSpace({
  address: account.address,
});

const createSpace = personalSpace.createSpace();

const publish = await personalSpace.publishEdit({
  name: "My Edit",
  spaceId,
  author: spaceId,
  ops,
  network: "TESTNET",
});
```

### 遗产 `daoSpace`

```ts
import { daoSpace } from "@geoprotocol/geo-sdk";

const createDao = await daoSpace.createSpace({
  name: "Research DAO",
  author: authorSpaceId,
  initialEditorSpaceIds: [authorSpaceId],
  votingSettings,
  network: "TESTNET",
});

const proposal = await daoSpace.proposeEdit({
  name: "Update entity",
  ops,
  author: authorSpaceId,
  callerSpaceId: authorSpaceId,
  daoSpaceId,
  network: "TESTNET",
});

const vote = daoSpace.voteProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
  versionId: 1,
  vote: "YES",
  network: "TESTNET",
});

const execute = daoSpace.executeProposal({
  authorSpaceId,
  spaceId: daoSpaceId,
  proposalId,
  network: "TESTNET",
});
```

遗产DAO成员帮助者:

```ts
daoSpace.proposeAddMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  newMemberSpaceId,
  network: "TESTNET",
});

daoSpace.proposeRemoveMember({
  authorSpaceId,
  spaceId: daoSpaceId,
  memberToRemoveSpaceId,
  network: "TESTNET",
});

daoSpace.proposeAddEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  newEditorSpaceId,
  network: "TESTNET",
});

daoSpace.proposeRemoveEditor({
  authorSpaceId,
  spaceId: daoSpaceId,
  editorToRemoveSpaceId,
  network: "TESTNET",
});

daoSpace.proposeUpdateVotingSettings({
  authorSpaceId,
  spaceId: daoSpaceId,
  votingSettings,
  network: "TESTNET",
});

daoSpace.proposeRequestMembership({
  authorSpaceId: requesterSpaceId,
  spaceId: daoSpaceId,
  network: "TESTNET",
});
```

### 遗留编码帮助

当需要精确的调用数据原始数据时,低等编码帮助器仍然可用以兼容性:

```ts
import {
  getCreateDaoSpaceCalldata,
  getCreatePersonalSpaceCalldata,
  getProcessGeoProposalArguments,
} from "@geoprotocol/geo-sdk";

const personalSpaceCalldata = getCreatePersonalSpaceCalldata();

const daoSpaceCalldata = getCreateDaoSpaceCalldata({
  votingSettings,
  initialEditorSpaceIds: [authorSpaceId],
  initialMemberSpaceIds: [],
  initialEditsContentUri:
    "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
});

const proposalArgs = getProcessGeoProposalArguments(
  spacePluginAddress,
  "ipfs://bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku",
);
```

## 常见问题

### @geoprotocol/geo-sdk 是什么？

与"图"互动的工具集\.

### 如何安装 @geoprotocol/geo-sdk？

在项目目录运行 npm install @geoprotocol/geo-sdk，或使用 pnpm add / yarn add / bun add。

### @geoprotocol/geo-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @geoprotocol/geo-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @geoprotocol/geo-sdk 可以商用吗？

@geoprotocol/geo-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @geoprotocol/geo-sdk 的下载量有多少？

根据 npm 官方下载统计，@geoprotocol/geo-sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,983 次，日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @geoprotocol/geo-sdk 还在维护吗？

最新版本 0\.20\.6 发布于 2026/11/12（4 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/01/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

