identity

Identity 技能

使用 identity-registry 合约提供 ERC-8004 链上 Agent 身份操作。读取操作（get、get-metadata、get-last-id）无需钱包。写入操作（register、set-uri、set-metadata、set-approval、set-wallet、unset-wallet、transfer）需要已解锁的钱包。

用法

bun run identity/identity.ts <subcommand> [options]

子命令

register

使用 ERC-8004 identity registry 在链上注册新的 Agent 身份。返回交易 ID。查看交易结果以获取分配的 Agent ID。需要已解锁的钱包。

bun run identity/identity.ts register [--uri <uri>] [--metadata <json>] [--fee <fee>] [--sponsored]

选项：

• --uri（可选）— 指向 Agent 元数据的 URI（IPFS、HTTP 等）
• --metadata（可选）— {"key": "...", "value": "<hex>"} 键值对组成的 JSON 数组（值为十六进制编码的缓冲区）
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易形式提交

输出：

{
  "success": true,
  "txid": "0xabc...",
  "message": "Identity registration transaction submitted. Check transaction result to get your agent ID.",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xabc..."
}

get

从 ERC-8004 identity registry 获取 Agent 身份信息。返回所有者地址、URI，以及已设置的钱包。

bun run identity/identity.ts get --agent-id <id>

选项：

• --agent-id（必填）— 要查询的 Agent ID（非负整数）

输出：

{
  "success": true,
  "agentId": 42,
  "owner": "SP1...",
  "uri": "ipfs://...",
  "wallet": "SP2...",
  "network": "mainnet"
}

set-uri

更新 Agent 身份的 URI。调用者必须是 Agent 所有者或经批准的操作员。需要已解锁的钱包。

bun run identity/identity.ts set-uri --agent-id <id> --uri <uri> [--fee <fee>] [--sponsored]

选项：

• --agent-id（必填）— 要更新的 Agent ID（非负整数）
• --uri（必填）— 指向 Agent 元数据的新 URI（IPFS、HTTP 等）
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易形式提交

输出：

{
  "success": true,
  "txid": "0xdef...",
  "message": "Identity URI update transaction submitted.",
  "agentId": 42,
  "uri": "ipfs://newuri...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xdef..."
}

set-metadata

为 Agent 身份设置一组元数据键值对。值必须是十六进制编码的缓冲区（最多 512 字节）。键 agentWallet 为保留键，合约会拒绝该键。调用者必须是 Agent 所有者或经批准的操作员。需要已解锁的钱包。

bun run identity/identity.ts set-metadata --agent-id <id> --key <key> --value <hex> [--fee <fee>] [--sponsored]

选项：

• --agent-id（必填）— 要更新的 Agent ID（非负整数）
• --key（必填）— 元数据键（字符串）
• --value（必填）— 以十六进制编码缓冲区表示的元数据值（例如，616c696365 表示 "alice"）
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易形式提交

输出：

{
  "success": true,
  "txid": "0xghi...",
  "message": "Metadata set transaction submitted.",
  "agentId": 42,
  "key": "name",
  "valueHex": "616c696365",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xghi..."
}

set-approval

为 Agent 身份批准或撤销操作员。经批准的操作员可代表所有者更新 URI、元数据和钱包。只有 NFT 所有者可以调用。需要已解锁的钱包。

bun run identity/identity.ts set-approval --agent-id <id> --operator <address> [--approved] [--fee <fee>] [--sponsored]

选项：

• --agent-id（必填）— 要更新的 Agent ID（非负整数）
• --operator（必填）— 要批准或撤销其权限的操作员 Stacks 地址
• --approved（标志）— 授予权限（省略则撤销权限）
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易形式提交

输出：

{
  "success": true,
  "txid": "0xjkl...",
  "message": "Operator SP3... approved for agent 42.",
  "agentId": 42,
  "operator": "SP3...",
  "approved": true,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xjkl..."
}

set-wallet

将身份的 Agent 钱包设置为 tx-sender（当前钱包地址）。此操作会将当前 Stacks 地址关联到 Agent ID，无需单独签名。调用者必须是 Agent 所有者或经批准的操作员。需要已解锁的钱包。

bun run identity/identity.ts set-wallet --agent-id <id> [--fee <fee>] [--sponsored]

选项：

• --agent-id（必填）— 要更新的 Agent ID（非负整数）
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易形式提交

输出：

{
  "success": true,
  "txid": "0xmno...",
  "message": "Agent wallet set to tx-sender (SP1...) for agent 42.",
  "agentId": 42,
  "wallet": "SP1...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xmno..."
}

unset-wallet

移除 Agent 身份关联的 Agent 钱包。调用者必须是 Agent 所有者或经批准的操作员。需要已解锁的钱包。

bun run identity/identity.ts unset-wallet --agent-id <id> [--fee <fee>] [--sponsored]

选项：

• --agent-id（必填）— 要更新的 Agent ID（非负整数）
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易形式提交

输出：

{
  "success": true,
  "txid": "0xpqr...",
  "message": "Agent wallet cleared for agent 42.",
  "agentId": 42,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xpqr..."
}

transfer

将 Agent 身份 NFT 转移给新所有者。当前钱包（tx-sender）必须是当前所有者。转移会自动清除 Agent 钱包关联。需要已解锁的钱包。

bun run identity/identity.ts transfer --agent-id <id> --recipient <address> [--fee <fee>] [--sponsored]

选项：

• --agent-id（必需）— 要转移的 Agent ID（代币 ID，非负整数）
• --recipient（必需）— 新所有者的 Stacks 地址
• --fee（可选）— 费用预设（low、medium、high）或 micro-STX 金额
• --sponsored（标志）— 以赞助交易的方式提交

输出：

{
  "success": true,
  "txid": "0xstu...",
  "message": "Identity NFT transfer submitted for agent 42.",
  "agentId": 42,
  "sender": "SP1...",
  "recipient": "SP4...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/0xstu..."
}

get-metadata

按键从 ERC-8004 身份注册表中读取元数据值。以十六进制字符串形式返回原始缓冲区值。无需钱包。

bun run identity/identity.ts get-metadata --agent-id <id> --key <key>

选项：

• --agent-id（必需）— 要查询的 Agent ID（非负整数）
• --key（必需）— 要读取的元数据键

输出：

{
  "success": true,
  "agentId": 42,
  "key": "name",
  "valueHex": "616c696365",
  "network": "mainnet"
}

get-last-id

获取 ERC-8004 身份注册表中最近铸造的 Agent ID。如果尚未注册任何 Agent，则返回 null。无需钱包。

bun run identity/identity.ts get-last-id

输出：

{
  "success": true,
  "lastAgentId": 99,
  "network": "mainnet"
}

说明

• 读取操作（get、get-metadata、get-last-id）无需钱包即可使用
• 写入操作需要已解锁的钱包（bun run wallet/wallet.ts unlock）
• Agent ID 由合约在注册时分配 — 请查看交易结果以查找分配给你的 ID
• 操作员授权允许委托地址更新 Agent 的 URI、元数据和钱包
• 转移会自动清除 Agent 钱包关联；如有需要，请在转移后使用 set-wallet
• agentWallet 键为保留键 — 请改用 set-wallet / unset-wallet 子命令