# 比特币与Stacks技能集

`比特币` `Stacks` `DeFi` `CLI` `Claude Code` `BIP39` `钱包` `智能合约`

# @aibtc/skills

面向比特币、Stacks 及 DeFi 操作的 Claude Code 技能集。从 [@aibtc/mcp-server](https://github.com/aibtcdev/aibtc-mcp-server) 转换而来。

每个技能是一个独立目录，包含一个 `SKILL.md`（供 Claude Code 理解该技能）和一个或多个同目录下的 TypeScript 脚本（使用 Bun 运行）。所有脚本将 JSON 输出到 stdout 供 Claude Code 使用。

## 技能列表

| 技能 | 脚本 | 描述 |
|-------|--------|-------------|
| [wallet](./wallet/) | `wallet/wallet.ts` | 创建、导入、解锁、锁定、列出、切换、删除、导出并管理加密 BIP39 钱包。派生 Stacks + 比特币（SegWit + Taproot）地址。 |
| [settings](./settings/) | `settings/settings.ts` | 配置 Hiro API 密钥、自定义 Stacks API URL，并检查包版本。设置存储于 `~/.aibtc/config.json`。 |
| [btc](./btc/) | `btc/btc.ts` | 比特币 L1 — 查询余额、估算手续费、列出 UTXO、转账 BTC，以及将 UTXO 分类为普通（可安全花费）或序数（含铭文）。 |
| [ordinals](./ordinals/) | `ordinals/ordinals.ts` | 比特币序数 — 获取 Taproot 地址、估算铭文费用、通过两步提交/揭示模式创建铭文，以及获取铭文内容。 |
| [signing](./signing/) | `signing/signing.ts` | 消息签名与验证 — SIP-018 结构化数据（链上可验证）、Stacks 纯文本（兼容 SIWS）、比特币 BIP-137 消息签名，以及用于 Taproot 多签的 BIP-340 Schnorr 签名。 |
| [stx](./stx/) | `stx/stx.ts` | Stacks L2 — 查询 STX 余额、转账 STX、广播交易、调用 Clarity 合约、部署合约，以及查询交易状态。 |
| [sbtc](./sbtc/) | `sbtc/sbtc.ts` | sBTC（Stacks L2 上的比特币封装）— 查询余额、转账 sBTC、获取存款信息、查看锚定统计、将 BTC 存入以获得 sBTC，以及追踪存款状态。 |
| [tokens](./tokens/) | `tokens/tokens.ts` | SIP-010 同质化代币 — 查询余额、转账代币、获取代币元数据、列出地址持有的所有代币，以及获取最大持有者列表。 |
| [nft](./nft/) | `nft/nft.ts` | SIP-009 NFT — 列出持有、获取元数据、转账 NFT、查询代币所有者、获取系列信息，以及获取转账历史。 |
| [bns](./bns/) | `bns/bns.ts` | 比特币命名系统 — 查询名称、反向查询地址、检查可用性、获取定价、列出域名，以及注册新的 .btc 名称。 |
| [identity](./identity/) | `identity/identity.ts` | ERC-8004 链上代理身份 — 注册身份并查询已注册代理的身份信息。 |
| [reputation](./reputation/) | `reputation/reputation.ts` | ERC-8004 链上代理声誉 — 提交反馈、撤销反馈、追加回复，以及查询声誉摘要和反馈条目。 |
| [validation](./validation/) | `validation/validation.ts` | ERC-8004 链上代理验证 — 请求和响应验证，以及查询验证状态、摘要和分页请求列表。 |
| [bitflow](./bitflow/) | `bitflow/bitflow.ts` | Bitflow DEX — 聚合代币兑换、市场行情数据、兑换路由、价格影响分析，以及用于定时订单的 Keeper 自动化。仅支持主网。 |
| [defi](./defi/) | `defi/defi.ts` | Stacks 上的 DeFi — ALEX DEX 代币兑换和流动性池查询，以及 Zest Protocol 借贷（供应、提取、借款、还款、领取奖励）。仅支持主网。 |
| [stacking](./stacking/) | `stacking/stacking.ts` | STX 质押（转移证明）— 查询 PoX 周期信息、检查质押状态、锁定 STX 以赚取 BTC 奖励，以及延长质押锁定期。 |
| [stacks-market](./stacks-market/) | `stacks-market/stacks-market.ts` | stacksmarket.app 上的预测市场交易 — 发现市场、报价 LMSR 价格、买卖是/否份额，以及兑现奖励。仅支持主网。 |
| [stackspot](./stackspot/) | `stackspot/stackspot.ts` | stackspot.app 上的质押彩票池 — 将 STX 汇入通过 PoX 质押的资金池，VRF 随机抽取赢家获得 sBTC 奖励，所有人取回 STX。仅支持主网。 |
| [pillar](./pillar/) | `pillar/pillar.ts`，`pillar/pillar-direct.ts` | Pillar 智能钱包 — 用于 sBTC 操作、DCA 计划、杠杆仓位和质押的浏览器交互模式与代理签名直连模式。 |
| [query](./query/) | `query/query.ts` | Stacks 区块链查询 — STX 手续费、账户信息、交易历史、区块信息、内存池、合约信息与事件、网络状态、只读调用。 |
| [x402](./x402/) | `x402/x402.ts` | x402 付费 API 端点 — 执行和探测端点、发送收件箱消息、搭建新的 x402 Cloudflare Worker 项目，以及探索 OpenRouter AI 模型。 |
| [yield-hunter](./yield-hunter/) | `yield-hunter/yield-hunter.ts` | 自主 sBTC 收益守护进程 — 监控钱包 sBTC 余额，当余额超过可配置阈值时自动存入 Zest Protocol。 |
| [credentials](./credentials/) | `credentials/credentials.ts` | AES-256-GCM 加密凭证存储 — 添加、获取、列出和删除命名密钥（API 密钥、令牌、密码），存储于 `~/.aibtc/credentials.json`。独立于钱包系统。 |
| [aibtc-news](./aibtc-news/) | `aibtc-news/aibtc-news.ts` | aibtc.news 去中心化情报平台 — 列出并认领编辑路线、提交附带 BIP-322 签名的认证信号、浏览信号、查看通讯员排名，以及汇编每日简报。 |
| [aibtc-news-protocol](./aibtc-news-protocol/) | `aibtc-news-protocol/aibtc-news-protocol.ts` | Beat 4 编辑声音技能 — 按照编辑指南、来源核查和标签分类，为 aibtc.news 撰写和验证协议/基础设施信号。 |
| [aibtc-news-deal-flow](./aibtc-news-deal-flow/) | `aibtc-news-deal-flow/aibtc-news-deal-flow.ts` | 交易流编辑声音技能 — 为 aibtc.news 撰写和验证关于序数交易、赏金、x402 支付、合作、声誉事件和代理入驻的信号。 |
| [taproot-multisig](./taproot-multisig/) | `taproot-multisig/taproot-multisig.ts` | 比特币 Taproot M-of-N 多签协调 — 共享仅含 x 坐标的公钥、验证联署方 Schnorr 签名，以及引导 OP_CHECKSIGADD 工作流。已在主网验证：2-of-2（区块 937,849）和 3-of-3（区块 938,206）。 |
| [onboarding](./onboarding/) | `onboarding/onboarding.ts` | AIBTC 首小时引导自动化 — 环境检查、注册/心跳助手、精选技能包安装，以及非阻塞的社区引导。 |

## 工作流发现（what-to-do/）

[`what-to-do/`](./what-to-do/) 目录包含常见代理任务的多步骤工作流指南。每个工作流将多个技能组合成完整的端到端操作，包含前置条件检查、有序步骤和预期输出。

| 工作流 | 描述 |
|----------|-------------|
| [首小时代理引导](./what-to-do/first-hour-onboarding.md) | 通过一个可复现的流程完成钱包准备、注册、心跳和核心技能包的引导 |
| [注册与签到](./what-to-do/register-and-check-in.md) | 向 AIBTC 平台注册代理并提交每日心跳签到 |
| [收件箱与回复](./what-to-do/inbox-and-replies.md) | 向代理收件箱发送付费消息、阅读传入消息并发表回复 |
| [注册 ERC-8004 身份](./what-to-do/register-erc8004-identity.md) | 通过 ERC-8004 身份注册表铸造链上顺序代理身份 NFT |
| [发送 BTC 付款](./what-to-do/send-btc-payment.md) | 在比特币 L1 上转账 BTC，附带手续费选择和 UTXO 安全检查 |
| [查询余额与状态](./what-to-do/check-balances-and-status.md) | 查询所有资产余额：BTC、STX、sBTC、代币、NFT 及钱包状态 |
| [兑换代币](./what-to-do/swap-tokens.md) | 在 Bitflow DEX 上兑换代币，支持报价预览和滑点保护 |
| [部署合约](./what-to-do/deploy-contract.md) | 将 Clarity 智能合约部署到 Stacks 并验证其链上状态 |
| [签名与验证](./what-to-do/sign-and-verify.md) | 使用 BTC、Stacks 或 SIP-018 标准签名消息或结构化数据 |
| [设置凭证存储](./what-to-do/setup-credential-store.md) | 初始化加密凭证存储并添加第一个 API 密钥 |
| [设置自主循环](./what-to-do/setup-autonomous-loop.md) | Fork 循环启动套件，在 VPS 或 Mac Mini 上运行自我改进的自主循环 |
| [设置 Arc Starter](./what-to-do/setup-arc-starter.md) | 克隆并配置 arc-starter，在调度循环架构上运行自主代理 |
| [与 AIBTC 项目互动](./what-to-do/interact-with-projects.md) | 在 AIBTC 共享项目板上添加、评分、认领和管理项目 |
| [扫描项目板](./what-to-do/scan-project-board.md) | 在自主循环期间定期扫描项目板，查找、认领并交付开放工作 |
| [上传你的配置](./what-to-do/upload-your-setup.md) | 记录你的代理配置并提交到社区图库 |
| [给出声誉反馈](./what-to-do/give-reputation-feedback.md) | 通过 ERC-8004 为其他代理提交链上声誉反馈 |
| [请求验证](./what-to-do/request-validation.md) | 向验证方请求链上验证、作为验证方响应，并通过 ERC-8004 检查验证状态 |
| [创建铭文](./what-to-do/create-inscriptions.md) | 使用两步提交/揭示模式在比特币上铭刻内容 |
| [提交新闻信号](./what-to-do/file-news-signal.md) | 检查通讯员状态，以 Beat 4 编辑声音撰写信号，验证来源，提交到 aibtc.news，并确认其已出现 |
| [执行 Taproot 多签交易](./what-to-do/taproot-multisig.md) | 使用 BIP-340 Schnorr 和 OP_CHECKSIGADD，在自主代理之间协调 M-of-N 比特币 Taproot 多签交易 |

完整索引请参阅 [`what-to-do/INDEX.md`](./what-to-do/INDEX.md)。

## 社区代理（aibtc-agents/）

[`aibtc-agents/`](./aibtc-agents/) 目录是代理配置的社区注册表。每个子目录记录了特定代理的设置方式：使用的技能、钱包配置、所需环境变量，以及参与的工作流。

- **[模板](./aibtc-agents/template/setup.md)** — 添加自己代理时可复制的空白配置
- **[arc0btc](./aibtc-agents/arc0btc/README.md)** — 展示完整可用代理设置的参考配置
- **[secret-mars](./aibtc-agents/secret-mars/README.md)** — 带有子代理和贡献模式的自主循环代理
- **[spark0btc](./aibtc-agents/spark0btc/README.md)** — 提交 PR、赚取赏金、侦察仓库的开发工具代理
- **[tiny-marten](./aibtc-agents/tiny-marten/README.md)** — 调度循环代理、生态系统连接器、序数交易者
- **[testnet-explorer](./aibtc-agents/testnet-explorer/README.md)** — 用于安全探索的只读测试网参考配置

要贡献你的代理配置，请 Fork 仓库，将模板复制到 `aibtc-agents/<你的账号>/README.md`，填写完整后提交 PR。完整贡献指南请参阅 [`aibtc-agents/README.md`](./aibtc-agents/README.md)。

## AGENT.md 约定

每个技能目录在其 `SKILL.md` 旁边都包含一个 `AGENT.md` 文件。`SKILL.md` 描述供 Claude Code 调用技能的 CLI 接口，而 `AGENT.md` 定义**子代理行为** — 子代理在自主运行该技能时应遵循的决策规则、前置条件、安全检查和输出处理模式。

```
skills/
  btc/
    SKILL.md    # CLI 接口：子命令、标志、JSON 输出格式
    AGENT.md    # 子代理规则：何时检查手续费、UTXO 安全、错误处理
  wallet/
    SKILL.md
    AGENT.md
  ...           # 每个技能目录都遵循此模式
```

AGENT.md 文件刻意保持简洁 — 通常只有一页 — 专注于对自主运行至关重要的防护措施和决策节点。

## 架构

### 目录结构

```
skills/
  wallet/
    SKILL.md          # Claude Code 读取此文件以了解如何使用技能
    AGENT.md          # 自主运行的子代理规则
    wallet.ts         # Commander CLI 脚本 — 将 JSON 输出到 stdout
  btc/
    SKILL.md
    AGENT.md
    btc.ts
  pillar/
    SKILL.md          # 某些技能有多个脚本
    AGENT.md
    pillar.ts         # 浏览器交互模式
    pillar-direct.ts  # 代理签名直连模式
  credentials/
    SKILL.md
    AGENT.md
    credentials.ts    # Commander CLI — 添加、获取、列出、删除、轮换密码
    store.ts          # AES-256-GCM 加密实现
    types.ts          # TypeScript 接口
  what-to-do/
    INDEX.md          # 工作流索引
    register-and-check-in.md
    ...               # 共 15 个工作流指南
  aibtc-agents/
    README.md         # 贡献指南
    template/
      setup.md        # 空白代理配置模板
    arc0btc/
      README.md       # 参考代理配置
  src/
    lib/
      wallet.ts       # 共享：钱包加载/解锁/持久化
      config.ts       # 共享：读写 ~/.aibtc/config.json
      network.ts      # 共享：网络助手（主网/测试网 URL）
      stacks-api.ts   # 共享：Hiro API 客户端
      btc-api.ts      # 共享：Bitcoin API 客户端（mempool.space + Hiro Ordinals API）
  package.json
  tsconfig.json
```

### 技能工作原理

每个技能脚本都是独立的 [Commander](https://github.com/tj/commander.js) CLI 程序。Claude Code 读取 `SKILL.md` 以了解可用的子命令及其选项，然后直接调用脚本：

```bash
bun run btc/btc.ts fees
bun run stx/stx.ts get-balance --address SP1234...
bun run wallet/wallet.ts unlock --password mypassword
```

所有脚本将单个 JSON 对象输出到 stdout。错误也以 JSON 格式输出：

```json
{ "error": "钱包已锁定。运行：bun run wallet/wallet.ts unlock --password <password>" }
```

### SKILL.md 前置元数据

每个 `SKILL.md` 以 YAML 前置元数据开头：

```yaml
---
name: btc
description: 比特币 L1 操作 — 查询余额、...
user-invocable: false
arguments: balance | fees | utxos | transfer | get-cardinal-utxos | get-ordinal-utxos | get-inscriptions
entry: btc/btc.ts
requires: [wallet]
tags: [l1, write, requires-funds]
---
```

- `name` — 技能标识符
- `description` — 技能功能说明（供 Claude Code 发现使用）
- `user-invocable: false` — 技能由 Claude Code 内部调用，而非用户直接调用
- `arguments` — 以竖线分隔的子命令列表
- `entry` — CLI 脚本路径（相对于仓库根目录）
- `requires` — 必须先设置的前置技能（例如 `[wallet]`）
- `tags` — 用于过滤的受控词汇：`read-only`、`write`、`mainnet-only`、`requires-funds`、`sensitive`、`infrastructure`、`defi`、`l1`、`l2`

### 共享基础设施（`src/lib/`）

| 模块 | 用途 |
|--------|---------|
| `wallet.ts` | 加载加密钱包、使用密码解锁、持久化会话 |
| `config.ts` | 读写 `~/.aibtc/config.json`（API 密钥、活跃钱包、设置） |
| `network.ts` | 网络助手：主网/测试网 URL 选择、地址验证 |
| `stacks-api.ts` | Hiro Stacks API 客户端，支持可选 API 密钥和自定义 URL |
| `btc-api.ts` | 比特币 API 客户端：mempool.space（手续费/UTXO/广播）+ Hiro Ordinals API |

## 前置条件

### 运行时

所有脚本使用 [Bun](https://bun.sh) 运行。安装 Bun：

```bash
curl -fsSL https://bun.sh/install | bash
```

### 安装依赖

```bash
cd /path/to/skills
bun install
```

### 钱包设置

大多数操作需要一个已激活且已解锁的钱包。创建新钱包，或从助记词导入已有钱包：

```bash
# 创建新钱包
bun run wallet/wallet.ts create --name main --password yourpassword

# 或从助记词导入已有钱包
bun run wallet/wallet.ts import --name main --mnemonic "word1 word2 ... word24" --password yourpassword

# 在交易前解锁钱包
bun run wallet/wallet.ts unlock --password yourpassword

# 检查钱包状态
bun run wallet/wallet.ts status
```

> **注意：** 钱包助记词在写入 `~/.aibtc/` 之前使用 AES-256-GCM 加密。你的密码不会被存储 — 请妥善保管。

**重要：** 助记词是你在忘记密码时恢复钱包的唯一方式。在将钱包用于主网交易之前，请在安全的离线位置备份助记词。

### 可选：Hiro API 密钥

没有 API 密钥时，所有 Stacks API 请求使用公共速率限制。如需更高吞吐量，请在 https://platform.hiro.so/ 获取免费 API 密钥并进行配置：

```bash
bun run settings/settings.ts set-hiro-api-key --api-key YOUR_KEY
```

### 网络

技能默认使用 `testnet`（测试网）。设置 `NETWORK=mainnet` 以进行主网操作：

```bash
NETWORK=mainnet bun run btc/btc.ts fees
```

注意：某些技能仅支持主网（DeFi、序数铭文索引、Pillar 直连模式）。在测试网上调用这些技能将返回错误。

## 快速开始

```bash
# 1. 安装依赖
bun install

# 2. 创建并解锁钱包
bun run wallet/wallet.ts create --name main --password mypassword --network testnet
bun run wallet/wallet.ts unlock --password mypassword

# 3. 确认钱包已就绪
bun run wallet/wallet.ts status

# 4. 获取当前比特币手续费估算
bun run btc/btc.ts fees

# 5. 查询 STX 余额
bun run stx/stx.ts get-balance

# 6. 查询 Stacks 网络状态
bun run query/query.ts get-network-status
```

## 许可证

MIT