financial-insights

财务洞察

使用此技能回答有关用户通过 Link 连接的财务数据的问题，包括：

• 最近的交易
• 消费模式
• 账户余额
• 已关联的钱包来源
• 根据用户财务数据生成的基本摘要
• 有关购买模式和偏好的可用预计算洞察

所有命令均为只读。它们不会转移资金、发起付款、修改账户或泄露付款凭据。

安全与隐私

在用户通过所需的来源操作完成身份验证之前，不要检索财务数据。

只检索回答用户请求所需的数据。默认情况下，不要运行所有列表命令。

不要泄露敏感标识符、访问令牌、凭据或支付工具详细信息。仅以回答用户问题所需的粒度总结财务信息。

如果用户请求会转移资金的操作，请参阅 skills/create-payment-credential/SKILL.md。

身份验证

检索财务数据之前，请检查用户是否已通过身份验证，以及当前会话是否具有所需的来源操作。

link-cli auth status --format json

如果响应中存在 authorization_details，请检查其中 type: "source" 且包含所需操作的条目。如果令牌端点未返回授权详情，或身份验证使用 LINK_ACCESS_TOKEN，则可能缺少此字段；在这种情况下，只运行最低限度的数据命令，并按照下文所述处理权限错误。

如果用户尚未通过身份验证，请发起登录，并且只请求访问所需数据的来源操作。如果用户已通过身份验证，但缺少一个或多个所需的来源操作，请使用 auth upgrade，而不是 auth login。auth upgrade 会保留当前会话，让用户批准额外访问权限，并且仅在批准成功后才替换当前会话。

如果访问令牌权限不足以检索列表中的某项洞察，insights 命令会指出这一点。需要更多访问权限时，它会提供 authorization_remediation，其中说明所需的作用域，并提供 authorization_details。如果已设置 LINK_ACCESS_TOKEN，请说明缺少的访问权限，但不要尝试通过 CLI 升级访问权限。否则，请升级以获取所需访问权限，或跳过使用 insights。

使用最低限度的所需来源操作：

• 通过 Link 处理的交易：read_link_transactions
• 从银行连接导入的交易：read_external_transactions
• 账户余额：read_balances
• 数据来源详情和描述：read_source_details。此操作用途广泛，例如，如果你需要将某笔交易或余额与特定账户名称对应，就会用到它。
• 预计算汇总：上述所有操作。

如果用户的问题需要多种数据类型，请一并请求所有相关操作。

如果此技能支持购买，且用户未指定商家，请在登录前确认所需的 Link 能力。如果购买模式洞察可能有帮助，请在一次登录中同时请求交易访问权限和支付作用域。当前热门品牌洞察可使用授予 read_link_transactions 或 read_external_transactions 的来源；同时请求两者即可涵盖这两种来源。如果用户已通过身份验证，请查询 insights list-available-types，并仅请求其报告的缺失访问权限。

需要所有财务数据类型的新登录示例：

link-cli auth login \
  --client-name "<your-agent-name>" \
  --source-actions read_link_transactions \
  --source-actions read_balances \
  --source-actions read_external_transactions \
  --source-actions read_source_details \
  --format json

为现有会话添加余额访问权限的示例：

link-cli auth upgrade \
  --client-name "<your-agent-name>" \
  --source-actions read_balances \
  --format json

将 <your-agent-name> 替换为清晰的 Agent 或应用名称。向用户展示返回的 verification_url，然后遵循响应的 _next 指示，或使用以下命令轮询：

link-cli auth status --interval 5 --max-attempts 60 --format json

身份验证或访问权限升级成功之前，不要继续操作。如果批准已过期、被拒绝或超时，请报告结果，而不要反复发起新的授权流程。

选择合适的命令

使用能回答用户问题的最小命令集。

用户询问	命令
可用的消费模式洞察及其访问要求	link-cli insights list-available-types
某项特定的可用洞察或观察到的购物偏好	link-cli insights list
最近的购买、商家、支出、交易历史、收入、存款、订阅	link-cli transactions list
当前可用余额、账户余额、现金状况	link-cli balances list
已连接的账户、卡片、银行、钱包来源及来源元数据	link-cli sources list

示例：

• “我通常在哪些品牌购物？” → 发现可用的洞察类型，然后获取相关洞察。
• “从我常去的商店买面粉。” → 使用相关的可用洞察辅助选择商家；将结果视为线索，而非确定的偏好。
• “我上个月在餐馆花了多少钱？” → 仅使用交易数据。
• “我当前的支票账户余额是多少？” → 仅使用余额数据。
• “连接了哪些账户？” → 仅使用来源数据。
• “总结我的现金状况和近期支出。” → 使用余额数据和交易数据。

输出格式

使用 JSON 输出便于 Agent 读取的结构化结果。

link-cli insights list-available-types --format json
link-cli insights list --insight <insight_id> --format json
link-cli transactions list --format json
link-cli balances list --format json
link-cli sources list --format json

默认的 toon 格式面向人类。每当需要解析、筛选、汇总或总结结果时，优先使用 --format json。

所有端点中的货币金额均为该货币最小单位的整数（例如，152340 = 1,523.40 美元）。使用能识别货币的格式化工具格式化金额，并依据货币的 ISO 4217 次级单位指数；不要假设所有货币都保留两位小数，也不要总是除以 100。

根据字段解释正负号。只有 transactions.amount 使用负数表示资金流出账户，使用正数表示资金流入账户。不要将交易的正负号语义应用于余额字段；应根据余额类型解释 current、cash.available 和 credit.used。

洞察

当预计算洞察的描述与用户的问题相符时，使用这些洞察。先查找 ID 和访问要求，不要计算所有洞察：

link-cli insights list-available-types --format json

响应包含 data 条目，其中有 id、description，以及可选的 authorization_remediation，还包含 has_more。当 has_more 为 true 时，使用 --starting-after <last_id> 继续查询。即使当前会话没有访问其数据所需的权限，洞察也可能会列出。如果需要某项洞察，对于由 CLI 管理的会话，请使用报告的补救措施和 auth upgrade；对于 LINK_ACCESS_TOKEN，请遵循上文的环境令牌规则。将缺失的 scope 值作为一个以空格分隔的 --scope 参数传入；对于来源中的 authorization_details 条目，将列出的每项操作分别作为一个 --source-actions 标志传入。不要猜测洞察 ID，也不要假设每项列出的洞察都有适用于此用户的数据。

仅检索相关 ID（多个 ID 时重复使用 --insight），或者当用户需要所有可用洞察时省略筛选条件：

link-cli insights list --insight <insight_id> --format json

两个命令都支持用于分页的 --limit（1–100）和 --starting-after。每一页都包含 data 和 has_more；使用最后一项的 id 作为下一个游标，并保持筛选条件不变。如果 has_more 为 true，但未返回可用游标，则停止。

每项检索到的洞察都有一个 status：

• ready：使用其 data 条目，并在回答时注明 as_of（Unix 秒）。number_of_items 值包含 number_of_items.label 和 number_of_items.count。
• pending：计算尚未完成；建议稍后再检查。
• no_data：检查 error_code、error_message 和 authorization_remediation。对于 missing_permissions，遵循上述身份验证指南；否则，说明数据不可用。在购买流程中，如果无法访问数据或用户拒绝分享数据，则在不使用该洞察的情况下继续。

未来的响应中可能会出现其他值类型或状态。保留其 JSON，不要臆造含义。将购买模式结果视为观察到的历史记录，而非对用户偏好的确切判断。只有当可用洞察无法回答问题且需要交易级别的详细信息时，才使用原始交易记录。

来源（概念）

来源是连接到用户 Link 钱包的金融账户，例如银行账户、信用卡、储蓄账户等。每个来源都有唯一的 id（例如 csmrpd_abc123），其他端点可能会将其作为 source_id 暴露出来：

• 在 transactions list 中，source_id 表示某笔交易所属的账户。
• 在 balances list 中，每个余额条目都包含一个用于标识账户的 source_id。
• 在 sources list 中，会返回完整的来源元数据（名称、金融机构、类型、状态）。

使用 source_id 关联不同命令中的数据，例如查找特定账户的交易，或将余额与其来源类型匹配。不要根据描述猜测将 source_id 为 null 的交易归属到某个来源。

交易

使用交易数据回答有关支出、收入、商户、类别、定期付款、存款或账户活动的问题。

link-cli transactions list --format json

常用选项：

link-cli transactions list --format json --start-date 2025-01-01 --end-date 2025-01-31
link-cli transactions list --format json --category groceries
link-cli transactions list --format json --origin external_connection
link-cli transactions list --format json --source <source_id> --source <source_id>

标志	说明
--start-date	仅包含此日期当天或之后的交易（YYYY-MM-DD）。
--end-date	仅包含此日期当天或之前的交易（YYYY-MM-DD）。
--category	按类别筛选。
--origin	按来源筛选：link 或 external_connection。
--source	按来源 ID 筛选（可重复使用）。

有关通用列表控制选项，请参阅分页。

响应字段

字段	说明
amount	负数 = 资金流出账户（借记／购买），正数 = 资金流入账户（贷记／存款）。
origin	external_connection（来自已关联的银行账户／卡片）或 link（Link 原生交易）。
category	未分类时可能为 null。
status	API 提供的状态字符串。不要假设状态值只有一组固定范围；已观察到的值包括 succeeded。只有在已知某个状态的含义时，才对该状态进行解释或筛选。

汇总交易时：

• 在计算总额前统一正负号。
• 尽可能区分借记和贷记。
• 仅在相关时按商户、类别、账户、币种或时间段分组。
• 如果答案基于有限的检索时间范围，请予以说明。

余额

使用余额回答当前账户余额或可用资金相关的问题。

link-cli balances list --format json
link-cli balances list --format json --source <source_id>

标志	说明
--source	按来源 ID 筛选（可重复指定）。

有关通用列表控制项，请参阅分页。

响应字段

字段	说明
type	cash（银行／储蓄）或 credit（信用卡／信用额度）。此字段决定包含哪个子对象。
current	待处理交易发生前的余额。与可用资金不同。
cash.available	将币种代码映射到可用资金的对象（当前余额减去待处理的流出资金，再加上待处理的流入资金）。仅当 type 为 cash 时存在。
credit.used	将币种代码映射到已用信用额度的对象。仅当 type 为 credit 时存在。
as_of	余额上次更新的时间；数据可能已过时数小时或数天。

汇总余额时：

• 保留币种。
• 除非用户明确要求且有可用汇率数据，否则不要将不同币种的余额相加。
• 默认使用 current 字段表示余额，除非用户的问题要求考虑待处理交易。
• 如果返回多个来源，请按账户／来源进行汇总。

来源

使用来源回答已连接钱包来源、已关联账户或可用金融数据来源相关的问题。有关通用列表控制项，请参阅分页。

link-cli sources list --format json

响应字段

字段	说明
id	唯一来源标识符（与其他端点中的 source_id 相同）。
name	来源的显示名称。
type	来源类型（例如 card、bank_account）。
capabilities	指示可用数据的对象。每个键（例如 balances、transactions）都映射到一个带有 status 字段的对象（例如 eligible）。
external_connection.status	与外部机构的连接状态。
granted_actions	用户已授权此来源执行的操作列表。

汇总来源时：

• 仅包含回答所需的非敏感元数据。
• 避免暴露完整账号、凭据、令牌或支付工具详情。
• 在可用时，优先使用机构、账户类型、来源状态和上次更新时间等标签。

分页

所有三个列表命令都支持相同的分页标志：

标志	说明
--limit	每页的最大结果数（1-100）。可能需要多页时，优先使用 100。
--starting-after	使用游标值获取下一页。
--ending-before	使用游标值获取上一页。用于反向浏览，不用于常规的向前检索。

JSON 响应包含一个 data 数组，也可能包含 has_more。响应不会提供单独的下一页游标字段。当 has_more 为 true 时，从 data 中的最后一项推导下一页游标：

命令	下一页游标
transactions list	最后一笔交易的 id。
balances list	最后一笔余额的 source_id。
sources list	最后一个来源的 id。

例如：

link-cli transactions list --format json --limit 100 --starting-after <last_transaction_id>

在所有页面中保持筛选条件一致，只更改 --starting-after。当 has_more 为 false 或缺失时停止；如果是非穷尽式查询，也可在获取到足够数据后停止。如果 has_more 为 true，但 data 为空，或所需游标为 null 或缺失，则停止并说明分页无法继续。

除非用户的请求需要完整的限定结果（例如指定时间范围内的总额），否则不要穷尽所有分页。

回答用户的问题

回答时：

• 先给出直接答案。
• 说明相关的时间范围和数据来源。
• 指出任何限制，例如分页不完整、缺少类别、待处理交易或不支持的货币。
• 除非用户要求，否则不要倾倒原始记录和对象 ID。
• 优先提供简洁的摘要、总额和显著趋势。

回答风格示例：

You spent $342.18 on restaurants across 12 transactions in July. The largest restaurant transaction was $86.40 at Example Bistro on July 18. This is based on the transactions returned for your connected Link sources.

错误处理

如果身份验证失败，请让用户重新进行身份验证。

如果命令没有返回数据，请说明请求范围内没有可用的匹配 Link 财务数据。

如果 CLI 返回的错误表明缺少权限或来源操作权限，只请求具体缺少的权限。如果会话已通过身份验证，则使用 auth upgrade；如果尚未通过身份验证，则使用 auth login，然后等待批准，再重试一次数据命令。

如果数据不完整或经过分页，请明确说明答案基于目前已检索到的数据。

防护措施

不要：

• 转移资金。
• 发起付款。
• 修改财务来源。
• 检索无关的财务数据。
• 请求超出所需范围的来源操作权限。
• 泄露凭据、令牌或完整付款详情。
• 将不确定的推导性见解表述为确定结论。

应当：

• 使用只读命令。
• 检索数据前先进行身份验证。
• 只请求最低限度的来源操作权限。
• 使用 --format json 进行解析。
• 只检索所需数据。
• 清晰地总结并说明限制。