tres-export-3rd-party-contacts

TRES Finance — 将第三方地址导出为联系人工作簿

目标

使用 accountTxsSummary 查询，从用户的 TRES 环境中获取所有未识别的外部地址（数据源与 TRES 界面中的“未识别地址”标签页相同），对地址去重、补充活动数据，并生成包含两个工作表的 XLSX 工作簿：

1. 联系人 — 与 TRES 联系人模板匹配、可直接导入的工作表。用户在此填写名称和标签，然后将此工作表导回 TRES。
2. 地址详情 — 补充数据（网络、交易数量、法币交易额），帮助用户判断每个地址属于谁。

此工作流可帮助用户快速建立地址簿：Claude 会提取、去重并补充未识别地址的信息，用户只需为地址添加标签。

MCP 服务

所有 GraphQL 调用都使用 user-tres-finance MCP 服务（execute 工具）。

工作流

第 1 步 — 身份验证

调用 get_viewer（不带参数）以确认会话处于活动状态，并记录组织名称。

第 2 步 — 获取未识别地址

使用带有 identificationState: "UNIDENTIFIED" 的 accountTxsSummary 查询——这是 TRES 界面在 Accounts 下的“未识别地址”标签页使用的同一查询。此查询已排除组织自己的钱包，只返回尚未命名的外部交易对手地址。

query UnidentifiedAddresses($limit: Int, $offset: Int, $identificationState: String, $excludeInternalAccounts: Boolean, $fiatCurrency: String) {
  accountTxsSummary(
    limit: $limit
    offset: $offset
    identificationState: $identificationState
    excludeInternalAccounts: $excludeInternalAccounts
    fiatCurrency: $fiatCurrency
  ) {
    totalCount
    results {
      accountIdentifier
      displayName
      inflowTxCount
      outflowTxCount
      inflowFiatValue
      outflowFiatValue
    }
  }
}

变量：

{
  "limit": 500,
  "offset": 0,
  "identificationState": "UNIDENTIFIED",
  "excludeInternalAccounts": true,
  "fiatCurrency": "usd"
}

分页获取所有结果（每次将 offset 增加 500，直到收集完 totalCount 中的所有条目）。

第 3 步 — 去重并检测网络

accountTxsSummary 查询可能会多次返回同一个地址（例如，同一个 EVM 地址的大小写形式不同，或发送方和接收方上下文的单独行）。按小写形式的 accountIdentifier 去重：

• 构建一个以 accountIdentifier.lower() 为键的字典
• 对每个地址，保留首次出现时的原始大小写，并累加流入与流出的交易总数及法币金额
• 跳过 accountIdentifier 为空或为 null 的地址

按法币交易总额（流入 + 流出）降序排列去重后的地址，让活动最频繁的交易对手排在前面——通常用户会优先为这些地址添加标签。

网络检测： API 不会返回网络字段，因此请根据地址格式推断网络。使用以下规则：

地址模式	网络
以 0x 开头（42 个字符，十六进制）	EVM
以 KT1 开头	Tezos（合约）
以 tz1、tz2、tz3 开头	Tezos
以 T 开头（34 个字符，base58）	Tron
以 bc1、1 或 3 开头（25–62 个字符）	Bitcoin
以 r 开头（25–35 个字符）	XRP Ledger
以 cosmos1 开头	Cosmos
以 osmo1 开头	Osmosis
以 terra1 开头	Terra
以 addr1 或 stake1 开头	Cardano
以 bnb1 开头	BNB Beacon Chain
以 G 开头（56 个字符）	Stellar
以 D、A、L、M 或 ltc1 开头（26–35 个字符）	Litecoin/Dogecoin（最佳猜测）
均不符合	未知

这是尽力而为的启发式规则——尤其是 EVM 地址，可能属于 Ethereum、Polygon、Arbitrum、Base、Avalanche、BSC 或任何其他兼容 EVM 的链。由于单凭地址无法区分其所属链，因此有意使用宽泛的“EVM”标签。

第 4 步 — 构建 XLSX 工作簿

使用 Python 和 openpyxl==3.1.5。如果尚未安装，请停止并显示：

"openpyxl is not installed. Please run: python3 -m venv .venv && .venv/bin/pip install openpyxl==3.1.5"

标签页 1："Contacts"（可直接导入）

此工作表与 TRES 联系人导入模板完全一致：

Contact Name	Contact Address	Contact Tag
(blank)	0xABC...	(blank)

• Contact Name：留空（由用户填写）
• Contact Address：地址标识符（保留原始大小写）
• Contact Tag：留空（由用户填写）
• 按法币总额降序排序（顺序与 Address details 相同）

标签页 2："Address details"（补充信息）

Contact Address	Network	Inflow Txs	Outflow Txs	Inflow USD	Outflow USD	Total USD
0xABC...	EVM	142	38	1,240,500	890,200	2,130,700
KT1Xyz...	Tezos (contract)	6	0	40,144,631	0	40,144,631
TBmxn...	Tron	23	5	340,100	52,000	392,100

• 地址顺序与 Contacts 标签页相同（按 Total USD 降序排序）
• Network：根据地址格式推断（见步骤 3）
• Inflow Txs / Outflow Txs：来自 accountTxsSummary 结果
• Inflow USD / Outflow USD：来自 accountTxsSummary 的法币金额
• Total USD：流入与流出法币金额之和

格式指南

• 所有标签页的标题行均加粗
• 自动调整列宽，便于阅读
• USD 列设置为数字格式（单元格中不加 $ 前缀，使用 Excel 数字格式）
• 文件打开时应将 "Contacts" 标签页设为第一个/活动标签页，因为用户将在此页进行操作

步骤 5 — 保存并呈现

将 XLSX 保存到 outputs 目录。使用描述性文件名，例如 tres_3rd_party_contacts_<org_name>_<date>.xlsx（将空格和特殊字符替换为下划线）。

向用户提供文件，并附上简要摘要：

• 找到的唯一未识别地址数量
• 涉及这些地址的交易总数
• XLSX 文件链接

然后说明各标签页的用途：

此工作簿包含 2 个标签页：

1. Contacts — 这是可直接导入的工作表。请为每个你认识的地址填写 Contact Name，并可选填 Contact Tag（例如 Exchange、Vendor、Treasury）。完成后，使用 contacts import skill 将此工作表上传回 TRES。

2. Address details — 参考标签页，展示检测到的网络以及每个地址的活动统计数据（流入/流出交易数和 USD 金额）。可用它来确定优先标记哪些地址——交易额最高的交易对手排在最前面。网络列可帮助判断地址所属的链。

边缘情况

• 未找到未识别地址：如果结果集为空，请告知用户——这可能意味着所有交易对手地址都已在联系人列表中。
• 大小写混合的地址：EVM 地址可能采用不同的校验和格式。去重时始终转换为小写进行比较，但输出时保留原始大小写。
• 零地址/销毁地址：如果输出中出现 0x0000000000000000000000000000000000000000，请将其包含在内——用户可能仍想将其标记为 "Burn Address" 或类似名称。
• 未知网络：如果地址与任何已知格式都不匹配，将 Network 设为 "Unknown"。不要跳过该地址——它仍是有效的交易对手地址。