link-cli

设置 Link CLI

根据用户的预期用途设置并验证 Link CLI。完成设置后，使用专用技能处理支付或财务洞察相关工作。

1. 确定用途

仅当用户意图明确时，才推断其用途：

• Agent 支付：购买、付款、结账或获取支付凭证。
• 财务洞察：读取交易、余额、已关联账户或消费模式。
• 两者：启用支付和财务洞察。

如果用途不明确，先展示两者，并明确建议将其作为默认选项，然后再安装、验证身份或选择权限：

How do you plan on using Link?
1. (Recommended) Both: agent payments and financial insights
2. Agent payments only
3. Financial insights only

如果用户要求采用默认选项、接受该建议或没有偏好，请选择两者。否则，在用户选择或以其他方式明确意图之前，不要继续。

2. 首先检查身份验证状态

确定用途后，将运行 auth status 作为第一条 Link CLI 命令。在运行 auth login、auth upgrade 或任何支付或财务数据命令之前，务必先执行此操作：

link-cli auth status --format json

如果无法使用 link-cli，请运行 npm install -g @stripe/link-cli 安装，然后运行状态命令。也可以在所有命令中将 link-cli 替换为 npx @stripe/link-cli@latest。

常用命令/选项

• 列出所有命令：link-cli --llms
• 列出所有带参数的命令：link-cli --llms-full
• 使用 --schema 获取命令的确切架构。例如，link-cli auth login --schema
• 多步骤命令会返回一个 _next 操作。例如，验证身份时会返回必须运行以完成流程的 _next.command。
• 默认情况下，所有输出均为 toon 格式。传入 --format [json|md|yaml] 可更改输出格式。
• 有些命令会返回验证或审批 URL。必须清楚地向用户展示这些 URL，以便用户进行操作。
• 使用 --auth <path> 标志将身份验证凭证存储在指定文件中，而非默认位置。auth login 会写入该文件；其他所有命令都会从该文件读取。示例：link-cli auth login --auth credentials.json --format json

建议：运行 link-cli --llms 以了解所有可用命令。--llms-full 的输出是参数名称、类型和有效值的权威参考。在调用命令之前传入 --schema，以了解其参数和限制。

如果存在，请检查 scope 和 authorization_details，确认所选用途所需的访问权限。源操作会显示在 type: "source" 的授权详情中。如果响应包含 update 字段，请运行其 update_command，然后再次检查状态。

• 如果当前没有有效会话，请使用 auth login。
• 如果当前会话已具备所需访问权限，请勿启动新的授权流程。
• 不要仅为添加访问权限而退出登录。除非用户明确要求改为更窄的访问权限，否则应保留已有的更广泛访问权限。

如果用户已通过身份验证，但你需要更广泛的访问权限（额外的 scope、--source-actions 或 --authorization-detail），请使用 auth upgrade，而非 auth login。它接受相同的标志，但不会因“已登录”而停止，而是将你请求的权限与当前的 scope/authorization_details 合并，并启动针对权限并集的新审批流程，因此不会丢弃已有访问权限。先检查 auth status，以了解当前已授予的权限。在用户批准新权限之前，当前会话会继续有效；因此，即使用户放弃升级，现有会话也仍可使用。

令牌端点可能不会返回 scope 或 authorization_details，而由环境提供的访问令牌也可能不包含授权元数据。不要声称存在响应中未报告的权限。如果无法验证已存储会话的授权范围，请使用 auth upgrade 申请所需访问权限。未经用户同意，不要替换由环境提供的会话。

3. 为用例申请访问权限

使用以下访问权限映射：

用例	权限范围	来源操作
仅 Agent 付款	userinfo:read payment_methods.agentic	无
仅财务洞察	userinfo:read	请求的洞察所需的操作
两者皆选	userinfo:read payment_methods.agentic	请求的洞察所需的操作

将财务洞察需求映射到来源操作：

目标洞察	来源操作
通过 Link 处理的交易	read_link_transactions
从已连接银行导入的交易	read_external_transactions
账户余额	read_balances
已连接来源的详情和描述	read_source_details

仅申请完成明确指定任务所需的操作。如果用户要求一般性地设置财务洞察，请申请全部四项。对于两者皆选，将 Agent 付款权限范围与适用的来源操作结合起来。

根据状态结果使用 login 或 upgrade，为 Agent 或应用指定清晰的名称，并使用映射中的权限范围：

link-cli auth login \
  --client-name "<your-agent-name>" \
  --scope "<selected-scopes>" \
  --format json

将 <your-agent-name> 替换为你的 Agent 或应用名称（例如，"Personal Assistant"、"Shopping Bot"）。用户批准连接时，此名称会显示在其 Link 应用中。请使用清晰、唯一且易于识别的名称。

扩大现有会话的权限范围时，将 login 改为 upgrade。对于财务洞察，每项所需操作都添加一个 --source-actions <action> 标志。不要将占位符原样传入。

4. 完成用户批准

授权流程分为多个步骤：

1. 向用户清楚地展示返回的 verification_url 和短语。
2. 立即运行返回的 _next.command 以轮询批准状态；不要等用户再次回复后才开始轮询。
3. 仅当结果报告认证成功且已授予所需权限时，才继续操作。

如果已知用户的电子邮件地址，可将其作为经过 URL 编码的 fromEmail 查询参数添加到任意 app.link.com 验证或操作 URL 中，以节省用户时间；保留现有查询参数。

响应中包含一个 _next 命令——运行该命令并持续轮询，直到完成认证。如果你的环境无法在单独的轮询命令阻塞 I/O 时转发验证码，请改用内联轮询：在初始 auth login 或 auth upgrade 命令中添加 --interval 5 --timeout 300。这样会立即返回验证码，随后在同一命令中继续轮询。

用户通过 Link 完成认证之前，不要继续操作。

如果用户拒绝批准、批准过期或轮询超时，请报告相应结果。未经用户指示，不要反复创建新的授权流程。切勿泄露访问令牌、刷新令牌或认证文件内容。

5. 转交给对应的用例技能

仅完成认证并不代表已获准进行单笔购买，也无法回答财务数据问题。

• 对于购买和付款凭证，请使用 create-payment-credential 技能。
• 对于交易、余额、来源和摘要，请使用 financial-insights 技能。
• 对于同时选择两者的用户，后续每项任务都加载对应的下游技能。