tres-wallets-upload

TRES Wallet Upload Skill

将链上钱包和交易所账户接入 Tres Finance，并进行验证、预览和确认。

---

⚠️ 执行规则 — 开始前请阅读： 此技能是一份严格按顺序执行的检查清单。你必须严格按照所列顺序完成每一步，不得跳过、合并或调换步骤。进入下一步前，请确认当前步骤已全部完成。涉及 API 调用的步骤（获取架构、检查现有钱包、批量变更）均为必需步骤；绝不能为了节省时间或因为结果看起来显而易见而跳过。如果你发现自己正要跳过某一步，请停下来并先执行该步骤。

---

步骤 0 — 询问钱包类型

在执行任何其他操作之前，使用 ask_user_input_v0 询问用户想添加哪种钱包：

question: "What would you like to add to Tres?"
options:
  - "On-Chain Wallets (Ethereum, Solana, Bitcoin, etc.)"
  - "Exchange Accounts (Binance, Coinbase, Kraken, etc.)"
type: single_select

• 如果用户选择 链上钱包 → 进入 [链上流程]（步骤 OC-1）
• 如果用户选择 交易所账户 → 进入 [交易所流程]（步骤 EX-1）

---

---

链上流程

---

步骤 OC-1 — 询问输入方式

使用 ask_user_input_v0 询问用户想如何提供链上钱包：

question: "How would you like to add your wallets?"
options:
  - "Upload a file (CSV or Excel)"
  - "Enter manually in a table"
type: single_select

等待用户回复，然后进入步骤 OC-2 中对应的选项。

---

步骤 OC-2 — 收集钱包数据

选项 A：上传文件

如果用户选择“上传文件”（或直接上传 CSV 或 Excel 文件）：

• 使用 pandas / openpyxl 从 /mnt/user-data/uploads/ 读取文件
• 预期列（可灵活处理）：name、address（或 identifier）、network（或 platform）、tags（可选）、description（可选）
• 规范化列标题（不区分大小写、去除空格、接受别名）
• 解析为钱包字典列表，然后进入步骤 OC-3

选项 B：手动填写（对话方式）

如果用户选择“在表格中手动填写”：

• 不要渲染 HTML 组件。 而是要求用户以纯文本提供钱包信息，每行一个，格式如下：

  Name | Address | Network | Tags (optional)
  

  示例：

  Treasury Hot | 0xABCD...1234 | ETHEREUM | defi,treasury
  Cold Storage | bc1q...xyz | BITCOIN |
  

• 用户粘贴钱包信息后，将各行解析为钱包字典列表，然后进入步骤 OC-4。
• 如果用户不确定网络名称，告诉他们尽量填写，并说明你会将其模糊匹配到正确的 ParentPlatform 值。

---

步骤 OC-3 — 从架构获取实时平台列表

始终从 TRES MCP 架构中实时获取 ParentPlatform 枚举值，绝不要对其进行硬编码。使用：

# Via TRES MCP introspect tool:
introspect("ParentPlatform")

这会返回有效枚举值的完整列表，用于网络下拉菜单和验证。

区分交易所与链上钱包

若要筛选出仅包含链上平台的 ParentPlatform 列表，请排除与已知交易所／托管方匹配的值。受支持交易所的权威实时列表将在交易所流程（步骤 EX-1）中获取。作为链上筛选的本地启发式规则，请排除以下值：

ANCHORAGE, AQUANOW, ASCENDEX, B2C2, BACKPACK, BINANCE_EXCHANGE, BINANCE_EXCHANGE_TR,
BITCOIN_SUISSE, BITFINEX, BITGET, BITGO, BITMEX, BITSO, BITSTAMP, BITVAVO, BREX,
BTC_MARKETS, BTCTURK, BULLISH, BYBIT, CEFFU, CIRCLE, COBO, COINBASE, COINBASE_COMMERCE,
COINBASE_EXCHANGE, COINBASE_INTERNATIONAL, COINBASE_PRIME, COINEX, COPPER, CRYPTOCOM,
CRYPTOCOM_EXCHANGE, CUSTOMERS_BANK, DERIBIT, EQUALSMONEY, FALCONX, FIDELITY,
FIFTH_THIRD_BANK, FIREBLOCKS, FORDEFI_UTXO, FTX, FTXUS, GATEIO, GEMINI, HITBTC, HTX,
KRAKEN, KRAKEN_CUSTODY, KRAKEN_FUTURES, KUCOIN, LAYERONE, LEDGER_ENTERPRISE, LMAX,
LUKKA, M2, MERCADO, MERCURY, MERCURY_TREASURY, MEOW, MEOW_TREASURY, MESH_PAYMENTS,
MORGAN_STANLEY, NONCO, OKX, PAXFUL, PARADEX, QONTO, QREDO, REVOLUT_FR, REVOLUT_UK,
SVB_GO, SVB_ONLINE, SYGNUM, TALOS, VERTEX, WHITEBIT, WINTERMUTE, WISE_US,
BANK_HAPOALIM_BIZ, BANK_HAPOALIM_INTERNATIONAL, BANK_OF_AMERICA,
BANQUE_POPULAIRE_RIVES_DE_PARIS, CHASE, CHECKOUT

不在此列表中的任何平台都视为需要标准区块链地址的链上钱包。

---

步骤 OC-4 — 验证钱包

运行以下所有检查。逐行收集错误；不要提前中止。

必填字段检查

字段	规则
name	非空字符串
identifier	非空字符串
parentPlatform	必须是有效的 ParentPlatform 枚举值（来自实时架构）

网络名称规范化

如果 CSV 中的网络名称使用小写或大小写混合形式（例如 tezos、Ethereum），请将其转换为大写，并模糊匹配最接近的有效 ParentPlatform 枚举值。在预览中显示警告横幅，说明进行了规范化并请用户确认。

按网络进行地址格式验证（仅链上）

对链上钱包应用这些正则规则。交易所钱包跳过此验证。

网络	规则
ETHEREUM、BNB、POLYGON、AVALANCHE_*、ARBITRUM、OPTIMISM、BASE、FANTOM、MOONBEAM 及其他 EVM 链	^0x[0-9a-fA-F]{40}$
BITCOIN	P2PKH 1...、P2SH 3... 或 Bech32 bc1...——25–62 个字符
SOLANA	Base58，32–44 个字符：^[1-9A-HJ-NP-Za-km-z]{32,44}$
TRON	^T[1-9A-HJ-NP-Za-km-z]{33}$
TEZOS	^tz[123][1-9A-HJ-NP-Za-km-z]{33}$
SUI、APTOS	^0x[0-9a-fA-F]{62,64}$
STELLAR	以 G 开头，共 56 个字符
RIPPLE	以 r 开头，25–34 个字符
CARDANO	以 addr1 开头，长度 > 50
NEAR	以 .near 结尾，或为 64 位十六进制
TON	以 EQ 或 UQ 开头，共 48 个字符
ALGORAND	58 位大写 Base32

网络与地址不匹配检测

标记明显不匹配的情况（例如，SOLANA 网络使用 0x... 地址，或 ETHEREUM 网络使用 Bitcoin 地址）。

重复项检测

批次内重复项： 标记具有相同 (identifier, parentPlatform) 对的行。将两行都标记为错误。

与 Tres 中现有钱包比对（批次 ≤ 200 个钱包）：

{
  internalAccount(identifier_In: ["addr1", "addr2", ...]) {
    results { id name identifier parentPlatform }
  }
}

构建查找键：key = identifier.toLowerCase() + "|" + parentPlatform.toUpperCase()

• 匹配 → 标记为 ⚠️ warning（黄色）：“Exists (ID: XXXXX)”——API 会更新，而不是重复添加
• 摘要栏必须显示：X new | Y already exist | Z errors

对于超过 200 个钱包的批次：跳过 API 检查，并在预览中显示提示。

---

步骤 OC-5 — 显示文本预览

🚫 硬性门槛： 在步骤 OC-4（验证）和现有钱包 Tres API 检查都完全完成之前，不要呈现此预览。未经 API 检查就显示预览，违反了此技能的要求。

不要呈现 HTML 小组件。 应改用纯文本 Markdown 表格展示钱包数据，供用户检查：

| # | Name | Address | Network | Tags | Status |
|---|------|---------|---------|------|--------|
| 1 | Treasury Hot | 0xABCD...1234 | ETHEREUM | defi | ✅ New |
| 2 | Cold Wallet | bc1q...xyz | BITCOIN | | ⚠️ Exists (ID: 12345) |
| 3 | Bad Wallet | invalid-addr | SOLANA | | ❌ Invalid address |

• 显示摘要行：X new | Y already exist | Z errors
• 在表格下方列出所有错误，并注明行号和描述：

  Errors:
  - Row 3 (Bad Wallet): Invalid SOLANA address format
  

• 如果存在错误，告知用户修正数据后重新粘贴，再继续操作
• 如果只有警告（现有钱包），询问：“准备上传了吗？现有钱包将会更新。输入 yes 确认。”
• 如果所有行都有效，询问：“准备将 N 个钱包上传到 Tres Finance 了吗？输入 yes 确认。”

用户确认后 → 继续执行步骤 OC-6。

---

步骤 OC-6 — 最终确认

当 Claude 收到 TRES_WALLET_UPLOAD_CONFIRMED: 时：

1. 解析 JSON 载荷
2. 提供纯文本摘要：

   About to upload N wallets to Tres Finance:
   - 3 ETHEREUM wallets
   - 2 SOLANA wallets
   - 1 TEZOS wallet (will update existing)
   
   Shall I proceed?
   

3. 等待用户明确确认（“yes”“confirm”或“go ahead”）

---

步骤 OC-7 — 执行批量上传

通过 TRES MCP 调用 updateBatchInternalAccounts：

mutation UpdateBatchInternalAccounts($internalAccounts: [InternalAccountInput]) {
  updateBatchInternalAccounts(internalAccounts: $internalAccounts) {
    internalAccounts {
      id
      name
      identifier
      parentPlatform
      status
    }
    validationResults {
      iaIdentifier
      validationResult {
        issueType
        errorMessage
      }
    }
  }
}

每个钱包的变量：

{
  "name": "Treasury Hot",
  "identifier": "0xABCD...",
  "parentPlatform": "ETHEREUM",
  "tags": ["defi", "treasury"],
  "enforceCollectTransactions": true
}

注意：链上钱包不包含 platformKeys。

分批处理

如果批次超过 100 个钱包，则拆分为每批 50 个，并按顺序调用。

结果处理

• 解析 validationResults——向用户说明任何 issueType / errorMessage
• 显示成功数量及任何失败项
• 对于失败项，提供仅重试失败钱包的选项

---

---

交易所流程

---

步骤 EX-1 — 介绍与指南

向用户显示集成指南链接：

连接交易所之前，请先查看 Tres Finance 交易所集成指南： 👉 https://help.tres.finance/article/integrating-your-exchange-accounts-with-tres-finance

然后从 TRES MCP 获取实时验证的交易所列表——切勿硬编码：

query GetAllValidatedExchanges {
  ledgerFilters {
    allValidatedExchanges {
      id
      displayName
    }
  }
}

此操作会返回受支持交易所的权威列表（撰写本文时为 47 个，但始终应获取实时列表）。按 displayName 进行 A-Z 排序。使用 ask_user_input_v0 或在 show_widget 表单中以内置 <select> 下拉菜单呈现，参照 Tres UI，并在标签旁显示“Connection Guidelines ↗”链接。

---

步骤 EX-2 — 获取所选交易所的必填字段

用户选择交易所后，获取其凭据字段。将 id 值（小写）用作 exchangeName：

query ExchangeRequiredFields {
  exchangeRequiredFields {
    requiredFields(exchangeName: "<exchange_id_lowercase>") {
      name
      type
      description
      mapping
    }
  }
}

重要： 跳过 mapping 以 https:// 开头的字段——这些是集成指南链接，不是凭据输入项。将它们显示为可点击链接。

存储其余字段。每个字段包含：

• name — 凭据字段键
• description — 向用户显示的易读标签
• mapping — 构建 platformKeys 时使用的键（例如 platform_keys.api_key）
• type — 用于确定输入类型

---

步骤 EX-3 — 收集交易所凭据（对话式）

不要渲染 HTML 小组件。 请改用纯对话步骤向用户询问凭据。

首先，显示集成指南链接：

📖 连接前，请先查看指南：https://help.tres.finance/article/integrating-your-exchange-accounts-with-tres-finance

然后逐一询问字段（也可以在单个提示词中一次询问所有字段），并清楚列出所需信息：

To connect <Exchange Name>, I need the following:

**Account Name** (required) — a friendly name for this account in Tres
**API Key** (required)
**API Secret** (required, will be stored securely)
**Tags** (optional) — comma-separated tags

Please provide these values. Keep API secrets private — do not share them in public channels.

• 对于 field.name 包含 "secret"、"private"、"signing" 或 "passphrase" 的字段，请注明这些信息将被安全存储
• 对于可选字段（例如 OKX 子账户），请明确标注为 (optional)
• 跳过 mapping 以 https:// 开头的字段——改为将其显示为链接

必须确认的事项（继续前以是/否问题询问）

接受凭据前，询问：

1. “您确认 API 密钥具有只读权限吗？（是/否）”
2. “您同意 Tres Finance 服务条款吗？（是/否）”

只有在两项都确认后才能继续。

收集完所有凭据和确认信息后，按队列格式存储，并继续步骤 EX-4。

---

步骤 EX-4 — 累积交易所账户

收集完某个交易所的凭据后：

1. 解析账户数据并存储到待处理队列中
2. 确认：✅ <accountName> (<exchange>) 已添加到队列
3. 以简短列表显示当前队列：

   Queued accounts:
   1. My Binance Account (BINANCE_EXCHANGE)
   

4. 询问：“您想添加另一个交易所，还是继续上传？”

如果用户想添加另一个交易所 → 返回步骤 EX-1（保留队列中的账户）。 如果用户想继续 → 前往步骤 EX-5。

---

步骤 EX-5 — 最终审核与确认

以纯文本总结所有排队的账户：

Ready to connect the following exchange accounts to Tres Finance:

1. My Binance Account (BINANCE_EXCHANGE)
2. Kraken Main (KRAKEN)

Shall I proceed?

等待用户明确确认（例如“是”“确认”“继续”等）。

---

步骤 EX-6 — 执行交易所账户创建

通过 TRES MCP 调用 updateBatchInternalAccounts，处理所有排队的账户：

mutation UpdateBatchInternalAccounts($internalAccounts: [InternalAccountInput]) {
  updateBatchInternalAccounts(internalAccounts: $internalAccounts) {
    internalAccounts {
      id
      name
      identifier
      parentPlatform
      status
    }
    validationResults {
      iaIdentifier
      validationResult {
        issueType
        errorMessage
      }
    }
  }
}

每个交易所账户的变量：

{
  "name": "<accountName>",
  "identifier": "<accountName>",
  "parentPlatform": "<EXCHANGE_ID_UPPERCASE>",
  "tags": ["<tag1>"],
  "enforceCollectTransactions": true,
  "platformKeys": "{\"api_key\": \"...\", \"api_secret\": \"...\"}"
}

重要：

• identifier = 账户名称（交易所账户不使用区块链地址）
• platformKeys = JSON 字符串（不是对象），由表单中收集的 field.mapping → 值键值对构建
• parentPlatform = 交易所 id 转为大写（例如 binance_exchange → BINANCE_EXCHANGE）
• 尽可能在一次批量调用中处理所有账户

结果处理

• 按账户显示成功或失败
• 对失败情况显示 issueType 和 errorMessage
• 提供重试失败账户的选项

错误消息与恢复

情况	处理方法
CSV 中没有 address 列	请用户指定哪一列包含钱包地址
未知网络名称	模糊匹配最接近的 ParentPlatform 枚举值，显示警告横幅，并请用户确认
地址格式无效	在预览中标记为错误；用户必须在上传前修正或移除该行
批次中有重复项	将两行都标记为错误；用户必须移除或修正其中一行
钱包已存在于 Tres 中	标记为 ⚠️ 警告（黄色）；继续操作——API 将更新该钱包
没有文件，也没有手动输入钱包	提示用户上传文件或使用手动表格
批次中有超过 200 个钱包	跳过现有钱包 API 检查；显示提示说明
MCP 修改操作返回错误	显示每个钱包对应的错误；提供重试选项
交易所凭证被拒绝	显示验证错误，并提示用户重新输入凭证
exchangeRequiredFields 返回空值	告知用户该交易所可能需要手动设置；提供指南链接
allValidatedExchanges 返回空值	改为告知用户并提供 https://help.tres.finance 链接