copilot-sdk 会话 AI Credits 预算控制实战sessionLimits 配置与预算耗尽事件全解析【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk本指南系统讲解 GitHub Copilot SDK本仓库中会话预算Session limits机制的完整用法如何通过sessionLimits/session_limits为 Copilot 会话设置 AI Credits 软上限如何订阅预算相关事件实时感知预算变化以及当预算耗尽进入exhausted-budget流程时如何响应用户决策。读完本文你将掌握在 TypeScript、Python、Go、.NET、Java、Rust 六种语言中配置与观测会话预算的完整实战方案并能结合本仓库源码理解其底层实现原理。Session limits为 Copilot 会话设定 AI Credits 预算Session limits 允许应用为一次 Copilot 会话设定一个 AI Credits 预算。它通过sessionLimitsPython 中为session_limits在创建会话或恢复会话时传入为当前计费窗口accounting window设置一个软上限soft cap。这里的软上限是理解该机制的关键用量检查发生在模型调用返回之后因此单次响应可能超过配置值运行时才会在阻止下一次模型调用之前完成检查。换言之maxAiCredits不是对单次响应的硬性截断而是对会话累计消耗的预算闸门——一旦检查发现累计 AI Credits 已超过上限下一次模型调用将被阻止并转入预算耗尽流程详见下文事件部分。SDK 会在创建或恢复会话时把这个值透传给 Copilot CLIruntime。从源码看各语言 SDK 都维护着一个SessionLimitsConfig类型其唯一字段即maxAiCredits。例如 Go 侧定义于 go/rpc/zrpc.go// Optional session limits. type SessionLimitsConfig struct { // Maximum AI Credits allowed across the sessions current accounting window. MaxAiCredits *float64 json:maxAiCredits,omitempty }值得注意该类型在 Go 中被标记为Experimental实验性 API可能变更或移除TypeScript 侧生成类型中的注释同样将其描述为 Optional session limits见 nodejs/src/generated/session-events.ts。使用时应关注后续版本演进。配置会话预算六语言示例以下分别给出六种语言在创建会话与恢复会话时配置预算的完整示例。所有示例均以maxAiCredits 30作为演示值。TypeScriptconst session await client.createSession({ onPermissionRequest: approveAll, sessionLimits: { maxAiCredits: 30, }, }); const resumed await client.resumeSession(session.sessionId, { onPermissionRequest: approveAll, sessionLimits: { maxAiCredits: 30, }, });Pythonsession await client.create_session( on_permission_requestPermissionHandler.approve_all, session_limits{ max_ai_credits: 30, }, ) resumed await client.resume_session( session.session_id, on_permission_requestPermissionHandler.approve_all, session_limits{ max_ai_credits: 30, }, )Python 侧session_limits是一个字典mappingSDK 在发送给运行时前会将其转换为线上wire格式。在 python/copilot/client.py 中可以看到这一转换逻辑def _session_limits_to_wire(config: Mapping[str, Any]) - dict[str, Any]: Convert a SessionLimitsConfig mapping to wire format. wire: dict[str, Any] {} if max_ai_credits in config: wire[maxAiCredits] config[max_ai_credits] return wire即 Python 的max_ai_credits会映射为 JSON-RPC 线上的maxAiCredits字段camelCase与其他语言保持一致。Gosession, err : client.CreateSession(ctx, copilot.SessionConfig{ OnPermissionRequest: copilot.PermissionHandler.ApproveAll, SessionLimits: rpc.SessionLimitsConfig{ MaxAiCredits: copilot.Float64(30), }, }) resumed, err : client.ResumeSession(ctx, session.SessionID, copilot.ResumeSessionConfig{ OnPermissionRequest: copilot.PermissionHandler.ApproveAll, SessionLimits: rpc.SessionLimitsConfig{ MaxAiCredits: copilot.Float64(30), }, })Go 中MaxAiCredits是指针类型*float64因此需要借助copilot.Float64(30)这类辅助函数取地址线上 JSON 字段带omitempty未设置时不会出现在请求中。.NETvar session await client.CreateSessionAsync(new SessionConfig { OnPermissionRequest PermissionHandler.ApproveAll, SessionLimits new SessionLimitsConfig { MaxAiCredits 30, }, }); var resumed await client.ResumeSessionAsync(session.SessionId, new ResumeSessionConfig { OnPermissionRequest PermissionHandler.ApproveAll, SessionLimits new SessionLimitsConfig { MaxAiCredits 30, }, });JavaCopilotSession session client .createSession(new SessionConfig() .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) .setSessionLimits(new SessionLimitsConfig(30.0))) .get(); CopilotSession resumed client .resumeSession(session.getSessionId(), new ResumeSessionConfig() .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) .setSessionLimits(new SessionLimitsConfig(30.0))) .get();Java 中通过setSessionLimits(new SessionLimitsConfig(30.0))链式配置注意其构造参数为double类型。Rustlet limits SessionLimitsConfig { max_ai_credits: Some(30.0), }; let session client .create_session( SessionConfig::default() .approve_all_permissions() .with_session_limits(limits.clone()), ) .await?; let resumed client .resume_session( ResumeSessionConfig::new(session.id().clone()) .approve_all_permissions() .with_session_limits(limits), ) .await?;Rust 采用 builder 风格SessionConfig::default()后通过.approve_all_permissions()与.with_session_limits(limits)链式组装max_ai_credits为Optionf64。观测预算事件应用可以订阅会话事件session events在软上限变化或会话进入预算耗尽流程时更新 UI。下表汇总了四类与预算直接相关的事件类型、触发时机与关键字段事件类型触发时机关键字段session.session_limits_changed会话的生效限制发生变化。sessionLimits为null表示当前没有任何限制生效sessionLimits.maxAiCredits?session.usage_checkpoint运行时记录持久化的累计用量用于恢复resume与记账totalNanoAiu,totalPremiumRequests?session_limits_exhausted.requested会话进入预算耗尽流程需要用户做出决策后才能继续requestId,maxAiCredits,usedAiCreditssession_limits_exhausted.completed预算耗尽的提示已被解决requestId,response.action,response.additionalAiCredits?,response.maxAiCredits?使用生成的事件类型做类型收窄应使用你所选 SDK 语言对应的生成事件类型。以 TypeScript 为例session.on回调中按event.type收窄类型session.on((event) { if (event.type session_limits_exhausted.requested) { showBudgetDialog({ requestId: event.data.requestId, maxAiCredits: event.data.maxAiCredits, usedAiCredits: event.data.usedAiCredits, }); } });源码视角事件载荷与决策语义从生成的事件类型源码可以进一步理解各事件的载荷结构session.session_limits_changed载荷SessionLimitsChangedData仅包含一个字段sessionLimits: SessionLimitsConfig | nullNull clears the limits——当限制被清除时该字段为null见 nodejs/src/generated/session-events.ts。因此应用侧可用null判断当前是否处于无预算限制状态。session_limits_exhausted.requested载荷包含requestId用于后续通过session.ui.handlePendingSessionLimitsExhausted响应、maxAiCredits当前计费窗口配置的上限与usedAiCredits当前计费窗口已消耗的 AI Credits。该事件是瞬态ephemeral事件不写入持久化事件日志见 nodejs/src/generated/session-events.ts。session_limits_exhausted.completed载荷中的response即SessionLimitsExhaustedResponse其action类型为SessionLimitsExhaustedResponseAction源码中定义了四种取值见 nodejs/src/generated/session-events.tsaction语义add在现有上限基础上增加指定数量的 AI Credits配合additionalAiCredits使用set设定一个全新的绝对上限值配合maxAiCredits使用unset移除当前会话限制cancel保持限制不变并取消被阻止的模型请求这也意味着应用完全可以通过编程方式代用户决定预算耗尽后的走向续费add、重设set、解除unset或取消本次请求cancel。响应通道在 nodejs/src/generated/rpc.ts 中可以看到对应 RPC 方法handlePendingSessionLimitsExhausted通过session.ui.handlePendingSessionLimitsExhausted请求携带{ sessionId, requestId, response }提交用户的决策结果。这正是session_limits_exhausted.requested事件中requestId的用途——用它把决策回传给运行时解除阻塞。session.usage_checkpoint提供持久化的累计用量快照totalNanoAiu、totalPremiumRequests等用于恢复会话后重建累计记账数据是预算计算在 resume 场景下保持一致性的基础。这也解释了为什么恢复会话resumeSession同样需要也可以传入sessionLimits——恢复后的会话仍需明确预算策略。实战建议与注意事项软上限的语义maxAiCredits是软上限而非硬上限单次响应可能略微超出预算检查发生在模型调用返回之后、下一次模型调用被阻止之前。若需要严格成本控制建议在session_limits_exhausted.requested事件中默认返回cancel并在 UI 中展示消耗数据usedAiCredits/maxAiCredits由用户决策。恢复会话时重新声明预算预算属于会话配置的一部分resumeSession时可重新传入sessionLimits调整策略包括以较低/较高上限恢复。同时通过session.session_limits_changed事件可确认恢复后实际生效的限制。结合usage.usage_checkpoint做记账若你的应用需要展示会话累计消耗可订阅session.usage_checkpoint获取持久化累计用量它与会话预算的计费窗口相互配合可避免仅凭内存状态在会话重启后丢失账目。配合用量与计费文档阅读本仓库还提供 Usage and Billing 指南讲解读取 token 数、上下文窗口利用率、AI 信用成本与账户配额将预算事件与用量数据结合可构建完整的成本观测面板。会话限制与 Session Persistence跨重启恢复会话配合使用时预算策略可在恢复时重新声明。API 稳定性Go 侧SessionLimitsConfig标注为实验性 API可能在未来版本变更或移除生产环境接入时应关注 SDK 升级日志CHANGELOG.md并对session_limits_exhausted.*事件的处理逻辑做向后兼容设计。小结Session limits 为 Copilot 会话提供了一套以 AI Credits 为单位的预算治理机制创建/恢复会话时通过sessionLimits.maxAiCredits声明软上限运行时在模型调用边界检查累计用量预算耗尽时通过session_limits_exhausted.requested/.completed事件与应用交互最终由应用或用户以add/set/unset/cancel四种决策解除阻塞。配合session.session_limits_changed与session.usage_checkpoint事件应用可以构建完整的预算观测与干预闭环。【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考