tres-settings-management

TRES MCP - 组织与平台设置

此技能的工作方式

此技能允许用户查看和修改其 TRES Finance 组织以及各个区块链/交易平台的配置。分为两个层级：

• 组织设置 — 适用于整个组织：成本基础的计算方式、启用的功能、ERP 行为、定价来源、提交计划等。
• 平台设置 — 按平台（如 Ethereum、Arbitrum）应用，也可选择按钱包应用：提交策略、同步日期范围、余额差异、资产筛选等。

---

基本规则

1. 始终先确认组织

开始任何操作前，先确认用户当前连接的是哪个组织：

query { admin { orgName } }

告知用户：“您当前连接的是 {orgName}。”

2. 先读取，再写入

进行任何变更前，务必先获取要修改的设置的当前值。清楚展示变更前后的对比。

3. 变更必须获得明确批准

执行任何变更前，必须：

1. 显示包含 设置、当前值 和 新值 的清晰摘要表
2. 明确询问：“是否要将这些变更应用到 {orgName}？”
3. 仅在用户确认后继续
4. 执行后，展示变更响应中确认的结果

4. 警示高风险变更

将以下设置标记为可能存在危险，并添加警告：

• costBasisStrategy — 在期间中途更改可能导致整个组织重新计算
• disableAutoCommit — 停止所有自动数据处理
• skipCostBasis — 完全禁用成本基础
• commitStrategy: SKIP_ALL — 完全禁用平台的数据处理管道
• enableMultiEntity — 结构性变更，难以撤销
• allowShort — 在成本基础中启用空头头寸

5. 使用架构内省发现字段

不要依赖硬编码的字段列表。使用 MCP introspect 工具动态发现可用字段及其类型：

• introspect("OrganizationSettingsObjectType") — 所有可读取的组织设置
• introspect("setOrganizationSettings") — 所有可写入的组织设置及其说明
• introspect("PlatformSettingsObjectType") — 所有可读取的平台设置
• introspect("setPlatformSettings") — 所有可写入的平台设置及其说明

当用户询问“我可以配置什么？”或需要核实字段名称或枚举值时，先进行内省。

---

设置类别（用户提问笼统时使用）

如果用户只说“给我看看设置”，没有说明具体内容，请提供以下类别及其通俗说明：

类别	控制内容
成本基础	收益/损失的计算方式（FIFO、LIFO 等）、按钱包或按组织计算、减值
提交管道	自动数据处理计划、优先级、卡住检测、同步时段
内部转账	如何检测并匹配组织自有钱包之间的转账
定价	资产价格的来源、稳定币锚定、兑换对齐
ERP 集成	数据如何同步到会计系统（NetSuite、Xero、QuickBooks）
仪表板与功能	启用哪些 UI 功能（数据透视表、归属、支付、多实体）
质押	质押奖励跟踪与头寸管理
对账	跨组织及子系统的对账行为
报告	定期报告的时间、格式和内容
平台采集	启用了哪些区块链/交易平台，以及其同步范围和筛选条件

---

读取组织设置

查询结构

query {
  admin {
    orgName
    organizationSettings {
      # include only the fields relevant to the user's question
    }
  }
}

• 根据身份验证令牌解析组织 — 无需组织 ID
• 不要一次请求所有字段 — 选择与问题相关的类别
• 如有需要，使用 introspect("OrganizationSettingsObjectType") 发现可用字段

嵌套字段（查询时必须展开子字段）

这些字段返回对象/列表，而非标量。务必包含其子字段：

字段	子字段	含义
peggedStableCoinsToFiat	assetName、currency	视为等同于法币的稳定币
pricingApiSourcePerAsset	assetName、pricingApiSource	每种资产的自定义定价来源
netsuiteCurrencySymbolToInternalId	currency、internalId	NetSuite 货币映射
simpleMatchingStrategies	beforeRange、afterRange	对账时间窗口
proofOfFunds	organizationName	资金证明客户端配置

其他管理员字段

admin 查询还会提供：

• orgName — 组织的显示名称
• disabledPlatforms — 汇总列出已完全禁用采集的平台
• auth0Connections — 可用的 SSO 登录方式

---

编写组织设置

Mutation 结构

采用补丁语义——仅包含要更改的字段，其余内容保持不变。

mutation {
  setOrganizationSettings(
    costBasisStrategy: FIFO
  ) {
    organizationSettings {
      costBasisStrategy
    }
  }
}

使用 introspect("setOrganizationSettings") 来发现所有可变字段、字段类型和说明。

更改组织设置的工作流

1. 读取 要更改的设置当前值
2. 向用户展示 更改前后的对照表
3. 如涉及高风险设置，则发出警告
4. 征求批准
5. 执行 mutation
6. 确认 并展示返回的值

---

读取平台设置

Query 结构（顶层查询）

仅返回存在显式覆盖设置的平台/账户。使用全部默认设置的平台不会显示。

query {
  platformSettings(platform: ETHEREUM) {
    results {
      settingsId
      platform
      internalAccountId
      platformSettings {
        commitStrategy
        calculateBalanceDiff
        minLastSyncedAt
        maxToDate
        # add fields as needed — use introspect("PlatformSettingsObjectType") for full list
      }
    }
  }
}

筛选选项

所有参数均为可选——可按需组合：

参数	类型	使用场景
platform	Platform	查看特定链/交易所的设置
internalAccountId	Int	查看特定钱包的设置
settingsId	String	精确匹配存储键
settingsId_Icontains	String	部分匹配（例如，"ethereum" 可匹配 "ethereum_714128"）

• 无参数 → 所有已存储的平台设置
• 仅 platform → 该平台的全平台设置及所有逐钱包覆盖设置
• platform + internalAccountId → 仅逐钱包覆盖设置
• 仅 internalAccountId → 该钱包的所有平台设置

快速检查：哪些平台已禁用？

query { admin { disabledPlatforms } }

---

编写平台设置

Mutation 结构

补丁语义——仅合并包含的字段。保留现有值。

mutation {
  setPlatformSettings(
    platform: ARBITRUM
    internalAccountId: 714128    # omit for platform-wide
    commitStrategy: FULL
    minLastSyncedAt: "2025-01-01T00:00:00+00:00"
  ) {
    settingsId
    platformSettings {
      commitStrategy
      minLastSyncedAt
    }
  }
}

使用 introspect("setPlatformSettings") 来发现所有可用参数。

关键参数

• platform（必填）— 目标区块链或交易所
• internalAccountId（可选）— 指定特定钱包的范围。若要设置全平台范围，请省略
• DateTime 值必须采用带时区的 ISO 8601 格式："2025-01-01T00:00:00+00:00"

余额汇总（余额差异）

要为特定资产启用基于余额差异的活动跟踪：

mutation {
  setPlatformSettings(
    platform: ARBITRUM
    internalAccountId: 714128
    balanceRollupSettings: {
      assetIdentifiers: ["native"]
      interval: DAILY
    }
  ) {
    settingsId
    platformSettings {
      balanceRollupSettings { assetIdentifiers interval }
    }
  }
}

assetIdentifiers 可以是链的原生资产 "native"，也可以是代币合约地址。

---

启用/禁用平台

简单启用/禁用时，请使用 setPlatformCollectionStatus（不要使用 setPlatformSettings）。

mutation {
  setPlatformCollectionStatus(
    platformCollectionStatuses: [
      { platform: ARBITRUM, enabled: true }
      { platform: POLYGON, enabled: false }
    ]
  ) {
    success
  }
}

• enabled: true → 在提交中采集该平台（FULL）
• enabled: false → 完全跳过该平台（SKIP_ALL）

支持批量操作——一次调用即可操作多个平台。

---

将钱包地址解析为内部账户 ID

用户提供钱包地址时，请查询其内部账户 ID：

query {
  internalAccount(identifier: "0x1887fa9edadeab7562b01cc3f4fa246ace2c3cdd") {
    results {
      id
      name
      identifier
      parentPlatform
    }
  }
}

在平台设置 mutation 中，将返回的 id 用作 internalAccountId。

注意：parentPlatform 表示顶层链族（例如，ethereum 涵盖 Ethereum、Arbitrum、Polygon 等）。同一个位于 ethereum 父平台上的钱包地址，可以针对每个 L2 设置特定平台的设置。

---

常见工作流

“将成本基准方法改为 LIFO”

1. 查询当前值：admin { organizationSettings { costBasisStrategy } }
2. 显示：“当前：FIFO → 新值：LIFO”
3. 警告：“更改成本基准方法将触发重新计算，并影响所有历史盈亏计算。”
4. 请求批准
5. 执行：setOrganizationSettings(costBasisStrategy: LIFO)

“启用 Arbitrum”

1. 查询已禁用的平台：admin { disabledPlatforms } — 确认列表中包含 ARBITRUM
2. 显示：“ARBITRUM：已禁用 → 已启用”
3. 请求批准
4. 执行：setPlatformCollectionStatus(platformCollectionStatuses: [{platform: ARBITRUM, enabled: true}])

“设置 Polygon 上钱包 X 的同步起始日期”

1. 解析钱包：internalAccount(identifier: "0x...") → 获取 id
2. 读取当前值：platformSettings(platform: POLYGON, internalAccountId: {id}) → 获取 minLastSyncedAt
3. 显示：“POLYGON 上的钱包 {name}：minLastSyncedAt：1970-01-01 → 2025-01-01”
4. 请求批准
5. 执行：setPlatformSettings(platform: POLYGON, internalAccountId: {id}, minLastSyncedAt: "2025-01-01T00:00:00+00:00")

“为特定钱包的原生资产添加余额差异”

1. 解析钱包：internalAccount(identifier: "0x...") → 获取 id
2. 读取当前值：platformSettings(platform: ETHEREUM, internalAccountId: {id})
3. 显示：“正在为钱包 {name} / ETHEREUM 的原生资产添加余额汇总（DAILY 间隔）”
4. 请求批准
5. 执行：setPlatformSettings(platform: ETHEREUM, internalAccountId: {id}, balanceRollupSettings: {assetIdentifiers: ["native"], interval: DAILY})

“显示已禁用的平台”

1. 执行：admin { disabledPlatforms }
2. 如果结果较多，按链族分组并以清晰的列表呈现

“配置了什么定价来源？”

1. 执行：admin { organizationSettings { pricingApiSource peggedStableCoinsToFiat { assetName currency } pricingApiSourcePerAsset { assetName pricingApiSource } } }
2. 呈现：默认来源 + 各资产覆盖项 + 锚定法币的稳定币

---

错误处理

错误	含义	解决方法
403 / 权限被拒绝	用户缺少 admin:* 权限	联系组织管理员授予访问权限
platformSettings 返回结果为空	没有自定义覆盖项 — 平台使用默认值	这是正常情况；说明将应用默认值
“在组织中不存在”	在此组织中找不到内部账户 ID	验证钱包地址并重新解析
无效的枚举值	设置值错误	对枚举类型使用 introspect，以显示有效选项
DateTime 解析错误	格式错误	必须使用带时区的 ISO 8601 格式：“"2025-01-01T00:00:00+00:00"”