GSD SDK Prompt Caching 最佳实践为 Agent 工作流系统提示词配置 1 小时缓存 TTL【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读本指南针对基于 GSDGet Shit DoneSDK 构建 Agent 应用时的高频成本优化问题——GSD 工作流的系统提示词executor 提示词、planner 上下文、验证规则体量大且跨请求稳定每次 API 调用都重复处理会造成大量浪费。读完本文你将掌握为什么 GSD 工作流应使用 1 小时而非默认 5 分钟的缓存 TTL、如何用cache_control为系统提示词启用缓存、缓存命中的成本回收临界点以及session-runner.ts中systemPrompt.append字段与 Claude API 直接调用之间的集成改造方式。GSD SDK 的会话编排session-runner.ts面向的是执行计划 → 验证 → 人工审查 → 进入下一阶段的多轮长流程。这类应用的系统提示词与普通对话场景有本质差异体量大、内容稳定、但请求之间有较长的暂停间隔。Prompt Caching 正是为这种模式设计的——让稳定的系统提示词在 TTL 窗口内免于重复计费处理。一、推荐做法系统提示词启用 1 小时缓存 TTL在通过 Claude API 直接构建请求时为承载 GSD 工作流指令的系统提示词块附加cache_control并指定 1 小时 TTLconst response await client.messages.create({ model: claude-sonnet-4-20250514, system: [ { type: text, text: executorPrompt, // GSD 工作流指令 —— 体量大、跨请求稳定 cache_control: { type: ephemeral, ttl: 1h }, }, ], messages, });要点拆解type: text系统提示词必须作为文本块传递才能挂载缓存控制标记cache_control.type: ephemeral使用 Anthropic 的临时缓存语义即 Prompt Caching缓存随 TTL 过期不持久化到磁盘ttl: 1h显式声明 1 小时存活期。这是与默认 5 分钟 TTL 的关键差异详见下一节缓存对象只对跨请求不变的 GSD 工作流内容开缓存用户/任务相关的动态内容绝不入缓存见第四节。二、为什么是 1 小时而不是默认的 5 分钟2.1 GSD 工作流的人为暂停会击穿默认 TTLGSD 的工作流是阶段化的一个 phase 执行完毕后会停下来进行人工审查——讨论结果、检查验证输出、决策下一步走向。这段暂停可能远超 5 分钟5 分钟 TTL一旦暂停期间缓存过期下一次请求就不得不对系统提示词做完整重处理full re-processing缓存收益归零1 小时 TTL覆盖绝大多数人为审查暂停窗口下一次请求仍能命中缓存。2.2 1 小时 TTL 的成本账采用 1 小时 TTL 并非没有代价SDK 文档给出了明确的量化权衡维度说明缓存未命中时的写入成本2x 写入成本对比 5 分钟 TTL 的 1.25x 写入成本盈亏平衡点每小时 3 次缓存命中即可覆盖额外写入开销之后净省钱GSD 实际使用模式单个 phase 执行每小时产生数十次请求远超盈亏平衡点缓存刷新机制每次缓存命中都会免费重置 TTL活跃会话全程保持缓存温热从源码结构看这一结论与 GSD 的会话模型高度吻合runPlanSession在单次执行中会进行最多 50 轮maxTurns默认值见 session-runner.ts的 agent 循环而每个 phase steprunPhaseStepSession也是一次独立 query 调用。一次 phase 执行 数十次 API 请求共享同一份系统提示词正是 1 小时 TTL 最理想的适用场景。三、哪些 Prompt 应该缓存并非所有提示词都值得缓存。缓存的唯一标准是内容是否跨请求稳定。原文档给出的决策表如下Prompt是否缓存原因Executor 系统提示词✅ 是体量大约 10K tokens同一 phase 内跨任务完全一致Planner 系统提示词✅ 是体量大规划会话内保持稳定Verifier 系统提示词✅ 是体量大验证会话内保持稳定用户/任务特定内容❌ 否每次请求都会变化3.1 Executor 提示词为什么大且稳定——源码验证从 prompt-builder.ts 的buildExecutorPrompt实现可以看到executor 提示词由多个固定区块拼接而成Role来自gsd-executor.md的role角色指令块Objective计划目标Plan Infophase / plan / type 元数据Context Files上下文文件引用清单Tasks任务列表每个任务含 Files、Read first、Action、Verify、Done when、Acceptance criteria 等结构化字段Must-Haves不变量、必需产物、关键链路CompletionSUMMARY.md 生成与提交流程说明。这些区块在同一个 phase 的所有任务之间逐字节相同且与用户消息query()的prompt参数仅一句Execute this plan: ...严格分离——这正是缓存收益的根基。提示词中唯一变化的部分任务详情也是由系统侧稳定生成同一 phase 内不随请求漂移。四、SDK 集成点session-runner.ts中的systemPrompt.append4.1 Agent SDK 路径下的现状在 GSD SDK 内部会话是通过anthropic-ai/claude-agent-sdk的query()辅助函数发起的此时系统提示词以预设结构传入// runPlanSession / runPhaseStepSession 中的系统提示词形态 systemPrompt: { type: preset, preset: claude_code, append: executorPrompt, // -- 这就是需要缓存的内容 }对应实现见 session-runner.tsrunPlanSession与 session-runner.tsrunPhaseStepSession两者都把 executor/phase 提示词写入systemPrompt.append而用户可见的prompt只保留一句短指令。4.2 直接调用 Claude API 时的转换当你在query()辅助函数之外直接调用 Claude API例如自建 HTTP 客户端或非 Agent SDK 运行时需要把上述结构转换为带缓存控制标记的system数组// 直接调用 API 时转换为 system: [ { type: text, text: executorPrompt, cache_control: { type: ephemeral, ttl: 1h }, }, ]转换规则非常简单systemPrompt.append的内容原样搬进system[].text并附加cache_control。如果系统提示词由多个来源组成例如 preset 基础提示词 append 的工作流指令建议只对 append 的 GSD 工作流内容单独开缓存块避免把频繁变化的部分裹进缓存块导致频繁失效。4.3 一个值得警惕的回归陷阱提示词重复注入缓存优化的前提是提示词只出现一次。GSD SDK 的测试套件 session-runner.test.ts 专门锁定了一个回归#2194runPhaseStepSession曾把完整提示词同时当作 user message 和systemPrompt.append传入导致每个 phase step 的 token 成本翻倍。回归测试断言完整提示词必须出现在systemPrompt.append中这是它的正确位置user-visibleprompt必须只是一句短指令不得与完整提示词重复。这个测试对任何要在 GSD SDK 之上叠加缓存层的开发者都有直接警示排查缓存收益前先确认提示词没有被重复注入——重复注入会让缓存命中率统计失真也让成本模型见 2.2 节完全失效。五、如何观测缓存是否生效5.1 从会话结果读取缓存用量query()流处理结束后extractUsage会从 SDK result 消息中提取四项 token 统计session-runner.tsexport interface SessionUsage { inputTokens: number; // 普通输入 token outputTokens: number; // 输出 token cacheReadInputTokens: number; // 命中缓存读入的 token几乎免费 cacheCreationInputTokens: number; // 写入缓存消耗的 token成本放大倍数所在 }类型定义见 types.ts。验证缓存生效的判定标准cacheCreationInputTokens 0本次请求写入了缓存对应 2x 或 1.25x 写入成本cacheReadInputTokens 0本次请求命中了缓存对应大幅折扣的读取成本理想模式首次请求只有 creation后续请求只有 read——说明 TTL 窗口内缓存持续温热。5.2 结合成本事件做全流程观测PlanResult中的totalCostUsd与usage会通过事件流以GSDCostUpdateEvent形式广播session-runner.tsevent-stream负责在流处理过程中把 SDK 消息映射为领域事件。因此你可以在不修改 SDK 的前提下用事件流回调对每个 phase step 的cacheReadInputTokens / cacheCreationInputTokens做累计统计量化 1 小时 TTL 在真实 GSD 工作流中的实际命中率。六、落地检查清单基于以上全部内容为你的 GSD 应用启用 Prompt Caching 时建议按此清单核对缓存块只覆盖系统提示词executor / planner / verifier 提示词入缓存用户消息与任务特定内容绝不入缓存TTL 显式声明为 1 小时cache_control: { type: ephemeral, ttl: 1h }不要依赖 5 分钟默认值保持提示词逐字节稳定任何动态拼接时间戳、随机 ID、可变指令都会破坏缓存前缀匹配导致命中率归零确认提示词无重复注入参考 session-runner.test.ts 的断言模式保证完整提示词只出现在systemPrompt.append或直接调用时的system[].text用cacheReadInputTokens验证命中跑一个多 step 的 phase确认首个请求之后cacheReadInputTokens持续为正。按此配置后一个每小时产生数十次请求的 GSD phase 执行其系统提示词处理成本将从每次全量计费降为每小时约 2x 写入 数十次近乎免费的缓存读取在跨阶段人工审查暂停后也无需重新处理这正是 1 小时 TTL 相对默认 5 分钟方案的核心价值所在。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GSD SDK Prompt Caching 最佳实践：为 Agent 工作流系统提示词配置 1 小时缓存 TTL
GSD SDK Prompt Caching 最佳实践为 Agent 工作流系统提示词配置 1 小时缓存 TTL【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读本指南针对基于 GSDGet Shit DoneSDK 构建 Agent 应用时的高频成本优化问题——GSD 工作流的系统提示词executor 提示词、planner 上下文、验证规则体量大且跨请求稳定每次 API 调用都重复处理会造成大量浪费。读完本文你将掌握为什么 GSD 工作流应使用 1 小时而非默认 5 分钟的缓存 TTL、如何用cache_control为系统提示词启用缓存、缓存命中的成本回收临界点以及session-runner.ts中systemPrompt.append字段与 Claude API 直接调用之间的集成改造方式。GSD SDK 的会话编排session-runner.ts面向的是执行计划 → 验证 → 人工审查 → 进入下一阶段的多轮长流程。这类应用的系统提示词与普通对话场景有本质差异体量大、内容稳定、但请求之间有较长的暂停间隔。Prompt Caching 正是为这种模式设计的——让稳定的系统提示词在 TTL 窗口内免于重复计费处理。一、推荐做法系统提示词启用 1 小时缓存 TTL在通过 Claude API 直接构建请求时为承载 GSD 工作流指令的系统提示词块附加cache_control并指定 1 小时 TTLconst response await client.messages.create({ model: claude-sonnet-4-20250514, system: [ { type: text, text: executorPrompt, // GSD 工作流指令 —— 体量大、跨请求稳定 cache_control: { type: ephemeral, ttl: 1h }, }, ], messages, });要点拆解type: text系统提示词必须作为文本块传递才能挂载缓存控制标记cache_control.type: ephemeral使用 Anthropic 的临时缓存语义即 Prompt Caching缓存随 TTL 过期不持久化到磁盘ttl: 1h显式声明 1 小时存活期。这是与默认 5 分钟 TTL 的关键差异详见下一节缓存对象只对跨请求不变的 GSD 工作流内容开缓存用户/任务相关的动态内容绝不入缓存见第四节。二、为什么是 1 小时而不是默认的 5 分钟2.1 GSD 工作流的人为暂停会击穿默认 TTLGSD 的工作流是阶段化的一个 phase 执行完毕后会停下来进行人工审查——讨论结果、检查验证输出、决策下一步走向。这段暂停可能远超 5 分钟5 分钟 TTL一旦暂停期间缓存过期下一次请求就不得不对系统提示词做完整重处理full re-processing缓存收益归零1 小时 TTL覆盖绝大多数人为审查暂停窗口下一次请求仍能命中缓存。2.2 1 小时 TTL 的成本账采用 1 小时 TTL 并非没有代价SDK 文档给出了明确的量化权衡维度说明缓存未命中时的写入成本2x 写入成本对比 5 分钟 TTL 的 1.25x 写入成本盈亏平衡点每小时 3 次缓存命中即可覆盖额外写入开销之后净省钱GSD 实际使用模式单个 phase 执行每小时产生数十次请求远超盈亏平衡点缓存刷新机制每次缓存命中都会免费重置 TTL活跃会话全程保持缓存温热从源码结构看这一结论与 GSD 的会话模型高度吻合runPlanSession在单次执行中会进行最多 50 轮maxTurns默认值见 session-runner.ts的 agent 循环而每个 phase steprunPhaseStepSession也是一次独立 query 调用。一次 phase 执行 数十次 API 请求共享同一份系统提示词正是 1 小时 TTL 最理想的适用场景。三、哪些 Prompt 应该缓存并非所有提示词都值得缓存。缓存的唯一标准是内容是否跨请求稳定。原文档给出的决策表如下Prompt是否缓存原因Executor 系统提示词✅ 是体量大约 10K tokens同一 phase 内跨任务完全一致Planner 系统提示词✅ 是体量大规划会话内保持稳定Verifier 系统提示词✅ 是体量大验证会话内保持稳定用户/任务特定内容❌ 否每次请求都会变化3.1 Executor 提示词为什么大且稳定——源码验证从 prompt-builder.ts 的buildExecutorPrompt实现可以看到executor 提示词由多个固定区块拼接而成Role来自gsd-executor.md的role角色指令块Objective计划目标Plan Infophase / plan / type 元数据Context Files上下文文件引用清单Tasks任务列表每个任务含 Files、Read first、Action、Verify、Done when、Acceptance criteria 等结构化字段Must-Haves不变量、必需产物、关键链路CompletionSUMMARY.md 生成与提交流程说明。这些区块在同一个 phase 的所有任务之间逐字节相同且与用户消息query()的prompt参数仅一句Execute this plan: ...严格分离——这正是缓存收益的根基。提示词中唯一变化的部分任务详情也是由系统侧稳定生成同一 phase 内不随请求漂移。四、SDK 集成点session-runner.ts中的systemPrompt.append4.1 Agent SDK 路径下的现状在 GSD SDK 内部会话是通过anthropic-ai/claude-agent-sdk的query()辅助函数发起的此时系统提示词以预设结构传入// runPlanSession / runPhaseStepSession 中的系统提示词形态 systemPrompt: { type: preset, preset: claude_code, append: executorPrompt, // -- 这就是需要缓存的内容 }对应实现见 session-runner.tsrunPlanSession与 session-runner.tsrunPhaseStepSession两者都把 executor/phase 提示词写入systemPrompt.append而用户可见的prompt只保留一句短指令。4.2 直接调用 Claude API 时的转换当你在query()辅助函数之外直接调用 Claude API例如自建 HTTP 客户端或非 Agent SDK 运行时需要把上述结构转换为带缓存控制标记的system数组// 直接调用 API 时转换为 system: [ { type: text, text: executorPrompt, cache_control: { type: ephemeral, ttl: 1h }, }, ]转换规则非常简单systemPrompt.append的内容原样搬进system[].text并附加cache_control。如果系统提示词由多个来源组成例如 preset 基础提示词 append 的工作流指令建议只对 append 的 GSD 工作流内容单独开缓存块避免把频繁变化的部分裹进缓存块导致频繁失效。4.3 一个值得警惕的回归陷阱提示词重复注入缓存优化的前提是提示词只出现一次。GSD SDK 的测试套件 session-runner.test.ts 专门锁定了一个回归#2194runPhaseStepSession曾把完整提示词同时当作 user message 和systemPrompt.append传入导致每个 phase step 的 token 成本翻倍。回归测试断言完整提示词必须出现在systemPrompt.append中这是它的正确位置user-visibleprompt必须只是一句短指令不得与完整提示词重复。这个测试对任何要在 GSD SDK 之上叠加缓存层的开发者都有直接警示排查缓存收益前先确认提示词没有被重复注入——重复注入会让缓存命中率统计失真也让成本模型见 2.2 节完全失效。五、如何观测缓存是否生效5.1 从会话结果读取缓存用量query()流处理结束后extractUsage会从 SDK result 消息中提取四项 token 统计session-runner.tsexport interface SessionUsage { inputTokens: number; // 普通输入 token outputTokens: number; // 输出 token cacheReadInputTokens: number; // 命中缓存读入的 token几乎免费 cacheCreationInputTokens: number; // 写入缓存消耗的 token成本放大倍数所在 }类型定义见 types.ts。验证缓存生效的判定标准cacheCreationInputTokens 0本次请求写入了缓存对应 2x 或 1.25x 写入成本cacheReadInputTokens 0本次请求命中了缓存对应大幅折扣的读取成本理想模式首次请求只有 creation后续请求只有 read——说明 TTL 窗口内缓存持续温热。5.2 结合成本事件做全流程观测PlanResult中的totalCostUsd与usage会通过事件流以GSDCostUpdateEvent形式广播session-runner.tsevent-stream负责在流处理过程中把 SDK 消息映射为领域事件。因此你可以在不修改 SDK 的前提下用事件流回调对每个 phase step 的cacheReadInputTokens / cacheCreationInputTokens做累计统计量化 1 小时 TTL 在真实 GSD 工作流中的实际命中率。六、落地检查清单基于以上全部内容为你的 GSD 应用启用 Prompt Caching 时建议按此清单核对缓存块只覆盖系统提示词executor / planner / verifier 提示词入缓存用户消息与任务特定内容绝不入缓存TTL 显式声明为 1 小时cache_control: { type: ephemeral, ttl: 1h }不要依赖 5 分钟默认值保持提示词逐字节稳定任何动态拼接时间戳、随机 ID、可变指令都会破坏缓存前缀匹配导致命中率归零确认提示词无重复注入参考 session-runner.test.ts 的断言模式保证完整提示词只出现在systemPrompt.append或直接调用时的system[].text用cacheReadInputTokens验证命中跑一个多 step 的 phase确认首个请求之后cacheReadInputTokens持续为正。按此配置后一个每小时产生数十次请求的 GSD phase 执行其系统提示词处理成本将从每次全量计费降为每小时约 2x 写入 数十次近乎免费的缓存读取在跨阶段人工审查暂停后也无需重新处理这正是 1 小时 TTL 相对默认 5 分钟方案的核心价值所在。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考