用 Link CLI 读取用户财务数据回答消费…

当需要基于用户已连接的 Link 财务数据回答消费、余额、交易、账户来源或购物偏好问题时使用。

适用场景

解决思路

1. 在获取财务数据前，先运行 `link-cli auth status --format json` 检查用户是否已认证以及当前会话是否具备所需的 source actions。
2. 检查响应中的 `authorization_details`，查找 `type: "source"` 且包含所需 action 的条目；若该字段缺失（token 端点未返回或通过 `LINK_ACCESS_TOKEN` 认证），只运行最小的数据命令，并按权限错误处理。
3. 若用户未认证，发起只请求所需 source actions 的登录；若已认证但缺少部分 source actions，使用 `auth upgrade` 而非 `auth login`，以保留当前会话并在批准后替换。
4. 按最小必要原则请求 source actions：Link 交易用 `read_link_transactions`，银行导入交易用 `read_external_transactions`，余额用 `read_balances`，数据源详情用 `read_source_details`。
5. 若问题需要多种数据类型，一次性请求所有相关 actions；与购买流程配合时，先确定所有需要的 Link 能力并在一次登录中请求；偏好选商户需同时请求 `read_link_transactions` 和 `read_external_transactions`。
6. 新登录示例：`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`。
7. 为已有会话添加权限示例：`link-cli auth upgrade --client-name "<your-agent-name>" --source-actions read_balances --format json`。
8. 将返回的 `verification_url` 呈现给用户，然后按响应的 `_next` 指示操作，或用 `link-cli auth status --interval 5 --max-attempts 60 --format json` 轮询。
9. 在认证或权限升级成功前不要继续；若批准过期、被拒绝或超时，报告该结果，不要反复发起新的授权流程。
10. 按问题选择最小命令集：偏好类用 `link-cli summaries list`，交易类用 `link-cli transactions list`，余额类用 `link-cli balances list`，来源类用 `link-cli sources list`。
11. 始终使用 `--format json` 获取结构化输出以便解析、过滤、聚合或汇总；默认 `toon` 格式面向人类。
12. 金额为货币最小单位的整数（如 `152340` = $1,523.40 USD），使用基于 ISO 4217 小数位指数的货币感知格式化器，不要假设所有货币都是两位小数或除以 100。
13. 符号语义按字段区分：只有 `transactions.amount` 用负数表示资金流出、正数表示流入；不要将交易符号语义套用到余额字段，`current`、`cash.available`、`credit.used` 按余额类型解释。
14. 使用 summaries 时先运行 `link-cli summaries list --format json` 发现 ID 和描述，不要猜测 summary ID；后续可用重复的 `--summary <summary_id>` 只取选定摘要，省略 `--summary` 则包含全部。
15. 使用 summaries 时：将每个摘要的描述和条目与用户请求匹配，不要假设每个消费者都有所有偏好摘要类型；只使用 status 为 `ready` 的结果，`pending` 说明尚未就绪可稍后再查，`no_data` 说明无数据。
16. 呈现摘要洞察时提及 `as_of` 日期，并将其描述为基于汇总财务数据的观察偏好，而非对消费者的确定性陈述。
17. 优先用 summaries 回答常见偏好问题；仅当用户需要交易级细节、自定义时间范围或摘要不提供的聚合时才用 `transactions list`。
18. 用 `source_id` 跨命令关联数据（如查找某账户的交易或将余额匹配到来源类型）；不要根据描述猜测将 `source_id` 为 null 的交易归入某个来源。
19. 使用 transactions 时可用选项：`--start-date`、`--end-date`（YYYY-MM-DD）、`--category`、`--origin`（`link` 或 `external_connection`）、`--source`（可重复）。
20. 交易汇总时：计算总额前统一规范化符号，区分借记与贷记，仅在相关时按商户、类别、账户、货币或时间段分组，并说明答案是否基于有限的检索窗口。
21. 使用 balances 时可用 `--source <source_id>`（可重复）过滤；`type` 为 `cash`（银行/储蓄）或 `credit`（信用卡/信用额度）决定存在哪个子对象。
22. 余额汇总时：保留货币，除非用户明确要求且有汇率数据，否则不要跨货币相加；默认用 `current` 字段作为余额定义，除非问题需要考虑待处理交易；若返回多个来源，按账户/来源分别汇总。
23. 使用 sources 时运行 `link-cli sources list --format json`；响应字段包括 `id`、`name`、`type`、`capabilities`、`external_connection.status`、`granted_actions`。
24. 来源汇总时只包含回答所需的非敏感元数据，避免暴露完整账号、凭据、令牌或支付工具详情，优先使用机构、账户类型、来源状态和最后更新时间等标签。
25. 分页时所有列表命令支持 `--limit`（1-100，多页时优先用 100）、`--starting-after`、`--ending-before`（用于反向导航而非正常前向收集）。
26. 当 `has_more` 为 `true` 时从 `data` 最后一项推导下一页游标：`transactions list` 用最后交易的 `id`，`balances list` 用最后余额的 `source_id`，`sources list` 用最后来源的 `id`。
27. 跨页保持所有过滤条件一致，只改变 `--starting-after`；当 `has_more` 为 false 或缺失，或已检索到足够数据时停止；若 `has_more` 为 true 但 `data` 为空或所需游标为 null/缺失，停止并报告无法继续分页。
28. 除非用户请求需要完整有界结果（如指定时间范围的总额），否则不要穷尽分页。
29. 回答时：先给出直接答案，说明相关时间范围和数据来源，注明限制（如部分分页、缺失类别、待处理交易、不支持的货币），避免倾倒原始记录和对象 ID，优先给出简洁的汇总、总额和显著模式。
30. 错误处理：认证失败时请用户重新认证；命令无数据时说明该范围内无匹配的 Link 财务数据；CLI 返回缺少权限或 source actions 时只请求具体缺失的 action，已认证会话用 `auth upgrade`、未认证用 `auth login`，等待批准后重试一次数据命令；数据不完整或分页时明确说明答案基于目前已检索的数据。
31. 遵守护栏：不移动资金、不发起支付、不修改财务来源、不检索无关财务数据、不请求超出所需的 source actions、不暴露凭据/令牌/完整支付详情、不将不确定的推导洞察呈现为确定性结论；只使用只读命令、检索前先认证、请求最小必要 source actions、用 `--format json` 解析、只检索所需数据、清晰汇总并注明限制。

适用边界 · 注意事项

• 用户已指定具体商户（如“从 Costco 订面粉”）时，应尊重指定商户，不要使用本技能做偏好选择。
• 用户要求移动资金或发起支付时，应改用 `skills/create-payment-credential/SKILL.md`。
• 用户未通过所需 source actions 认证前，不要检索财务数据。