Appearance
功能规格说明：SDK 用量追踪与回调系统
创建日期：2025-11-11
澄清
2025-11-11 会议
- 问：用量数据的存储机制 → 答：将用量数据作为元数据存储在每个助手消息的会话中
- 问：回调数据范围 → 答：回调接收包含所有会话用量数据的 Usage[] 数组
- 问：失败操作的处理 → 答：失败操作不进行用量追踪（未消耗 AI 服务）
- 问：回调错误处理策略 → 答：记录回调错误并继续正常 SDK 操作，不中断
- 问：用量数据格式结构 → 答：使用 openai Usage 类型，usages: Usage[]
- 问：实现方法 → 答：复用当前回调系统，在 Message 类型中添加 usage 字段，保存到会话文件
用户场景与测试 （必填）
用户故事：实时用量监控（优先级：P1）
SDK 用户需要实时监控 AI 服务用量（token、成本、API 调用），以便在应用程序进行代理调用和消息压缩请求时追踪成本、实施用量限制并提供用户反馈。
为什么是这个优先级：提供即时价值的核心功能 - 在生产应用中实现成本监控和用户体验改善。
独立测试：可以通过注册回调函数并进行单次代理调用来完整测试，验证回调接收准确的用量数据并提供即时成本追踪价值。
验收场景：
- 假设 开发者注册了 onUsagesChange 回调，当 其应用程序通过 callAgent() 进行代理调用，则 回调被触发，接收包含所有会话用量数据的 Usage[] 数组
- 假设 开发者注册了 onUsagesChange 回调，当 其应用程序通过 compressMessages() 压缩消息，则 回调被触发，接收包含所有操作的更新 Usage[] 数组
- 假设 连续进行多次代理调用，当 每次调用完成，则 回调接收包含会话中所有操作用量数据的 Usage[] 数组
用户故事：用量数据检索（优先级：P2）
SDK 用户需要随时以编程方式检索当前用量统计，无需等待回调触发。这支持仪表板显示、定期报告和与外部监控系统集成。
为什么是这个优先级：对于需要按需用量数据进行报告的应用至关重要，但次于提供即时运营价值的实时通知。
独立测试：可以通过进行多次代理调用，然后调用 public get usages() 方法并验证返回准确的累计统计来完整测试。
验收场景：
- 假设 多次代理操作已完成，当 开发者调用
public get usages()方法，则 返回包含当前用量统计和操作元数据的 Usage[] 数组 - 假设 未执行任何操作，当 开发者调用
public get usages()，则 返回空 Usage[] 数组 - 假设 混合了代理调用和消息压缩操作，当 调用
public get usages()，则 返回 Usage[] 数组，每种操作类型有单独的 Usage 对象
用户故事：消息级用量记录（优先级：P3）
SDK 用户需要嵌入在会话助手消息中的用量数据，以便每个 AI 操作的成本和 token 消耗可追溯到特定交互。这支持详细的对话分析、按交互计费以及对话流程中的历史用量审查。
为什么是这个优先级：对详细分析和审计追踪很重要，但可以在核心实时追踪功能工作后实现。
独立测试：可以通过执行代理操作，然后检查会话消息以验证用量元数据是否正确附加到每个助手响应来完整测试。
验收场景：
- 假设 代理调用操作完成，当 检查会话中的结果助手消息，则 消息包含用量元数据，包括该特定操作消耗的 token
- 假设 发生消息压缩操作，当 操作完成，则 压缩的用量数据与相应的消息上下文一起记录
- 假设 会话中发生多次操作，当 审查会话历史，则 每个助手消息都有自己的用量元数据，允许按交互追踪成本
用户故事：CLI 退出 Token 摘要（优先级：P2）
CLI 用户需要在 CLI 应用退出时查看按模型分类的总 token 用量摘要。这使他们能够了解会话的成本影响、追踪预算消耗，并就未来使用模式做出明智决策。
为什么是这个优先级：为 CLI 用户提供有价值的成本可见性，无需实现回调，但次于核心追踪功能。
独立测试：可以通过使用不同模型运行 CLI 操作，然后验证退出摘要显示按模型名称分组的准确 token 总量来完整测试。
验收场景：
- 假设 CLI 会话中使用不同模型的代理调用，当 CLI 正常退出，则 console.log 显示每个模型消耗的总 token
- 假设 CLI 会话中混合了代理调用和压缩操作，当 CLI 退出，则 摘要显示代理模型和快速模型用量的单独 token 总量
- 假设 CLI 会话中无 AI 操作，当 CLI 退出，则 不显示 token 摘要或显示零用量
- 假设 CLI 会话因错误退出，当 进程终止，则 仍在退出前显示 token 摘要
边界情况
- 当 onUsagesChange 回调抛出错误或失败时会怎样？（错误被记录，SDK 继续正常操作不中断）
- 当 API 调用失败或中止时系统如何处理用量追踪？（失败操作不进行用量追踪，因为未消耗 AI 服务）
- 会话消息存储满或写保护时会怎样？
- 用量追踪在并发代理操作下的行为如何？
- 长时间运行的会话中用量数据变得非常大时会怎样？