tres-data-collection-commit

Name: tres-data-collection-commit
Author: anthropics

github.com/anthropics数据与数据库4.8k49 次安装2 周前更新

代码仓库

关于 tres-data-collection-commit

用于为已添加到 TRES Finance 组织的钱包触发链上数据采集。它会引导用户选择采集交易与余额或仅刷新余额、指定钱包并确认异步任务。

主要功能

01采集完整交易与余额
02仅刷新余额
03选择全部或指定钱包
04触发任务前确认
05报告结果与 Commit ID

适用场景

01钱包接入时填充历史记录
02刷新指定钱包的余额
03同步新添加的钱包
04验证前获取余额快照

MCP 相关

通过 TRES Finance MCP 工具验证组织、列出钱包，并调用 GraphQL mutation 触发 commit。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/anthropics/claude-plugins-community --skill tres-data-collection-commit

安装后在 Claude Code 中输入/tres-data-collection-commit确认已加载。

详细介绍

Tres Finance — 数据收集（提交）

概述

Commit 是将链上数据导入 Tres Finance 的步骤，适用于已加入组织的钱包。它会为每个钱包运行平台的数据收集流水线，并执行以下其中一项操作：

完整数据收集 — 收集完整的交易历史以及当前余额。用于完整的入驻流程或历史数据回填。
仅收集余额 — 仅收集当前资产余额（不收集交易）。速度快得多；适用于用户只想查看最新快照或准备快速验证余额的情况。

此技能是客户入驻流程的第二步：

上传钱包（tres-wallets-upload）— 在 Tres 中注册钱包。
收集数据（此技能） — 运行 commit，让 Tres 实际获取链上状态。
验证余额（tres-asset-balance-validation）— 将收集到的余额与 DeBank 进行交叉核对。

何时使用

当用户想要执行以下操作时，触发此技能：

运行 commit／触发 commit／启动数据收集
将链上数据收集到 Tres
获取其钱包的余额或交易
同步刚添加的钱包
添加新钱包后刷新 Tres 数据

以下示例表达必须触发此技能：

“运行 commit”／“触发 commit”
“收集我钱包的数据”
“获取所有内容的余额”
“我刚添加了钱包——现在收集数据”
“同步我的钱包”
“开始收集数据”

前提条件

要求	详情
已连接 TRES Finance MCP	必须能够使用 TRES MCP 工具（`get_viewer`、`execute`、`build_query`、`introspect`）
已通过身份验证的组织	`get_viewer` 必须成功并返回 `orgName`
至少有一个已入驻的钱包	如果没有钱包，commit 就没有可收集的内容——请先引导用户使用 `tres-wallets-upload`

流程概览

请按顺序执行以下步骤。不要跳过用户选择步骤——此技能的核心是在触发变更操作之前，了解用户的数据收集意图。

步骤 1 — 确认身份验证

调用 get_viewer，确认用户已通过 Tres 身份验证，并记下 orgName。稍后在确认摘要中提及该名称，让用户知道 commit 将针对哪个组织运行。

如果 get_viewer 失败：告知用户 TRES MCP 尚未连接，并请他们先连接后再继续。

步骤 2 — 询问：收集完整数据还是仅收集余额？

这是此技能的核心选择。请原样询问用户以下问题（如果有 AskUserQuestion 工具，则使用该工具；否则使用纯文本）：

你想收集什么？

完整数据收集 — 收集所有交易和当前余额。速度较慢，但会生成完整账本。用于首次入驻或历史数据回填。

仅收集余额 — 仅收集当前余额，不收集交易。速度快。适用于只想查看最新余额快照的情况（例如，在运行余额验证之前）。

将用户的回答映射到 GraphQL 参数 balancesOnly：

用户选择	`balancesOnly`
完整数据收集	`false`
仅收集余额	`true`

如果用户不确定，首次入驻时建议默认选择完整数据收集（因为跳过交易收集意味着即使 commit 成功，账本仍将为空）。

步骤 3 — 询问：所有钱包，还是指定钱包？

询问用户是要对所有钱包执行提交，还是只对其中一部分执行：

要为哪些钱包收集数据？

所有钱包 — 对组织中的每个钱包执行提交。

指定钱包 — 仅为我选择的钱包收集数据。

如果用户选择所有钱包：将 internalAccountIds = null（在 mutation 变量中省略该字段，或传入 null）。

如果用户选择指定钱包：

从 Tres 获取钱包列表，让用户从实际选项中选择：

query ListWalletsForCommit {
  internalAccount {
    totalCount
    results {
      id
      name
      identifier
      parentPlatform
    }
  }
}

将钱包以带编号的纯文本列表展示（名称 + 短地址 + 平台）。如果钱包超过约 25 个，展示前 25 个，并告知用户可以回复钱包名称、地址或 ID 来缩小范围。
允许用户以自然对话的方式回复（例如，“三个 Ethereum 钱包”、“Treasury Hot and Cold Storage”、“ID 123、456、789”等）。将其回复解析为一组内部账户 id 值。绝不要在名称尚未解析的情况下调用 mutation——务必先解析为 ID。
如果无法有把握地解析用户所说的钱包，请让用户澄清，不要猜测。

步骤 4 — 执行 mutation 前进行确认

用简短的纯文本总结即将执行的操作，并询问用户是否明确确认。例如：

About to trigger a Commit in Tres Finance:

  Org:       Acme Labs
  Mode:      Full data collection (transactions + balances)
  Wallets:   All wallets in the org

Shall I run it now?

或者，对于指定范围的操作：

About to trigger a Commit in Tres Finance:

  Org:       Acme Labs
  Mode:      Balances only
  Wallets:   3 selected
             - Treasury Hot (0x1887...3Cdd, ETHEREUM)
             - Cold Storage (bc1q...xyz, BITCOIN)
             - Ops Main (0x89Ba...92a8, POLYGON)

Shall I run it now?

等待肯定答复（yes、confirm、go ahead）。其他任何答复都视为“暂不执行”，并询问用户想要更改什么。

步骤 5 — 触发提交

通过 TRES MCP execute 工具运行 triggerCommit mutation：

mutation TriggerCommit(
  $balancesOnly: Boolean
  $internalAccountIds: [ID]
) {
  triggerCommit(
    balancesOnly: $balancesOnly
    internalAccountIds: $internalAccountIds
  ) {
    status
    message
    commitId
  }
}

变量映射：

变量	值
`balancesOnly`	来自步骤 2 的 `true`（仅余额）或 `false`（完整数据）
`internalAccountIds`	所有钱包时为 `null`，或步骤 3 中的钱包 ID 数组

除非用户明确要求指定日期范围或重试特定提交，否则不要传入 fromDate、toDate 或 commitId——引导流程应让 Tres 选择默认值。

所有变量键都必须使用 camelCase（例如 balancesOnly、 internalAccountIds）。TRES GraphQL API 会拒绝 snake_case。

步骤 6 — 报告结果

mutation 会返回三个字段：

status — 一个 Boolean。true = 提交已被接受并加入队列； false = 触发操作本身失败。
message — 简短的易读字符串（例如，"Commit triggered"）。按原样展示。
commitId — 此次运行对应的 UUID；展示给用户，以便之后引用此任务（也便于你将其传递给未来的状态检查工具）。

当 status == true 时，向用户展示的响应示例：

✅ Commit triggered successfully.

  Status:    true
  Message:   Commit triggered
  Commit ID: c93a6d31-2f98-4eae-859f-80b010048fbd

Data collection is now running in the background. You will typically see
balances appear within a few minutes; full data collection can take longer
depending on history length and the number of wallets.

如果 status == false，则视为失败：按原样展示 message，并为用户提供后续选项：重新运行提交、检查钱包配置，或在错误信息不明确时联系支持团队。

步骤 7 — 指引用户进行下一步引导

作为回复的最后部分（成功或错误报告之后），提醒用户 Commit 是引导流程的第 2 步，下一步是验证余额。措辞应清楚表明这是建议，而不是自动执行的操作：

**引导流程的下一步：**提交完成当前余额收集后，下一步是对照 DeBank 验证这些余额。只需说 “validate my balances”，我就会为你运行 Balance Validation 技能。

不要自动触发验证技能——用户必须主动选择，因为提交会异步运行，数据可能不会立即就绪。

重要说明

异步执行。 triggerCommit 会将任务加入队列；不会阻塞等待任务完成。返回的 commitId 可供用户（或其他技能）稍后检查状态。
仅刷新余额 ≠ 不写入数据。 即使处于仅刷新余额模式，Tres 也会更新每个钱包的余额快照。它只是跳过交易摄取。
尚未上传钱包？ 如果用户在添加任何钱包前触发此技能，internalAccount 会返回 totalCount: 0。告知用户需要先添加钱包（指向 tres-wallets-upload），然后停止。
部分失败。 部分钱包的提交可能成功，而其他钱包则失败。顶层的 status 和 message 提供摘要；更详细的诊断信息位于 TRES UI 的 Data Collection 日志中。
幂等性。 对同一个钱包重新运行提交是安全的 — Tres 会根据链上标识符对交易去重。

错误处理

情况	响应
`get_viewer` 失败	告知用户 TRES MCP 未连接；停止。
`internalAccount.totalCount == 0`	告知用户没有可提交的钱包；指向 `tres-wallets-upload` 技能；停止。
Mutation 返回非成功的 `status`	显示原始的 `status` 和 `message`；询问用户是要重试还是调查问题。
用户提供的无法解析的钱包名称	请用户澄清，而不是猜测；绝不将未解析的名称发送给 mutation。
用户要求指定日期范围	接受 ISO 8601 UTC 格式的 `fromDate` / `toDate` 并原样传递；触发前在摘要中确认日期范围。
用户要求取消正在运行的提交	此技能不支持此操作。说明存在 `killCommits`，并提出转交给其他技能或 TRES UI 处理。

示例

示例 1 — 首次接入，所有钱包，完整数据：

User: I just uploaded my wallets. Collect the data.

Claude: [runs get_viewer → "Acme Labs"]
        What do you want to collect?
          1. Full data collection (transactions + balances)
          2. Balances only

User: Full.

Claude: Which wallets?
          1. All wallets
          2. Specific wallets

User: All.

Claude: About to trigger a Commit in Tres Finance:
          Org:     Acme Labs
          Mode:    Full data collection
          Wallets: All wallets in the org
        Shall I run it now?

User: Yes.

Claude: [runs triggerCommit(balancesOnly: false)]
        ✅ Commit triggered successfully.
          Status:    SUCCESS
          Message:   Commit enqueued for 12 wallets.
          Commit ID: 9f2e5c4a-...
        Next step: once collection finishes, run balance validation.

未来改进（v1 中尚未实现）：

一种自然的后续改进是在此技能中选择性地等待提交完成（轮询 internalAccount.status，直到每个目标钱包都恢复为 READY，且 lastSyncedAt 晚于触发时间），然后通知用户可以安全地运行余额验证技能。目前的 v1 设计有意在触发后立即退出 — 完整数据提交可能耗时很长，长时间同步轮询会让聊天体验很糟糕。另一项配套措施是在 tres-asset-balance-validation 中添加防护（在提交进行期间拒绝运行或发出警告），以补足这项设计。

示例 2 — 快速刷新两个钱包的余额：

User: Can you just pull balances for my Ethereum treasury wallets?

Claude: [runs get_viewer]
        What do you want to collect?
          1. Full data collection
          2. Balances only  ← fits "just pull balances"

User: Balances only.

Claude: Which wallets?
          1. All wallets
          2. Specific wallets

User: Specific — Treasury Hot and Treasury Cold.

Claude: [queries internalAccount, resolves the two wallets by name]
        About to trigger a Commit in Tres Finance:
          Mode:    Balances only
          Wallets: 2 selected
                   - Treasury Hot (0x1887...3Cdd, ETHEREUM)
                   - Treasury Cold (0x89Ba...92a8, ETHEREUM)
        Shall I run it now?

User: Go.

Claude: [runs triggerCommit(balancesOnly: true, internalAccountIds: [...])]
        ✅ Commit triggered. Commit ID: ...

支持 Markdown

登录后评论

基本信息

作者: anthropics
仓库: anthropics/claude-plugins-community
分类: 数据与数据库
安装次数: 49
GitHub Stars: 4,789

报告问题