Pilot Shell 上下文监控完全指南context_monitor 接近压缩时的预警机制【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shellPilot Shell为 Claude Code 和 OpenAI Codex 提供了生产级的上下文工程能力其中最实用的功能之一就是context_monitor 上下文监控它会在会话即将触发自动压缩auto-compact前提前向 Agent 发出预警帮你避免上下文被截断时丢失关键工作记忆。本文带你完整读懂这套压缩预警机制的原理、触发条件与配合链路。一、什么是上下文压缩为什么需要提前预警Claude Code 的上下文窗口是有限的常见为 200K部分模型支持 1M。当对话与工具输出不断累积、接近窗口上限时运行时会自动执行上下文压缩compaction——把较早的对话内容总结裁剪以腾出空间。压缩本身是好事但它有一个代价早期的决策、约束、审批记录可能被摘要化甚至丢失如果 Agent 正在执行一个多步骤任务突然的压缩可能造成失忆需要重新确认状态。因此Pilot Shell 的 context_monitor.py 选择在压缩真正发生之前介入当上下文使用率达到 90% 时向 Agent 悄悄发出一次提醒让模型有机会主动把重要状态固化到计划或任务文件中。二、监控如何接入一个 PostToolUse 钩子 context_monitor 通过 Claude Code 的钩子系统注册。在 hooks.json 中它挂在PostToolUse事件上匹配器为*所有工具调用每当你使用一次工具钩子就跑一次匹配器必须是*而不是具体工具名列表——因为遗漏 MCP 工具会导致监控漏看规划阶段的调用复用已有钩子进程几乎零额外开销。安装后它会自动写入~/.claude/settings.json你无需手动配置。官方对钩子管线的完整说明见 features/hooks.md。三、90% 阈值预警何时触发⚠️核心逻辑在 run_context_monitor 中阈值常量定义在 context_monitor.py#L28低于 90%静默通过仅刷新会话缓存不输出任何提示达到 90% 及以上发出一次提醒例如Context at 91%. Auto-compact approaching; work can continue normally.——告知 Agent压缩即将发生但工作可以照常继续每会话只提醒一次通过shown_autocompact_warn标志位去重避免刷屏。若后续使用率回落到 90% 以下例如手动/compact后标志重置下次接近阈值会再次提醒。阈值为什么是 90% 而不是 80%Pilot 在 context-optimization.md 中给出了压缩预算公式为压缩过程预留33,000 token缓冲即 200K 窗口下约 83.5%、1M 窗口下约 96.7% 是真实的压缩触发点。90% 这个预警点恰好落在两者之间既留足了反应时间又不会过早打扰。节流设计不刷屏也绝不误判_is_throttled 实现了双重保护场景行为距上次检查不足 30 秒且使用率低于 90%跳过本次采样节流使用率接近或达到 90%永不节流保证预警一次不漏这样既控制了对会话缓存的读取频率又确保接近压缩这一关键时刻的监控绝对灵敏。四、预警如何送达静默的 additionalContext 这是很多用户最关心的细节context_monitor 的提醒不会打印在终端里。它通过post_tool_use_context见 _lib/util.py#L740构造如下 JSON 负载additionalContext提醒文案注入给 Agent 作为私有操作上下文suppressOutput抑制终端输出用户侧完全无感。换句话说这是一条只说给模型听的悄悄话。模型收到后会更倾向于把关键决策写入计划文件、收尾当前小任务、避免在压缩点中途执行高风险操作。所有多条通知会合并为单个 JSON 输出_emit防止两次 print 拼出非法 JSON 导致整个负载被丢弃——这种细节正是生产级钩子的可靠性保障。五、数据从哪来statusline 缓存与 Codex 降级路径 context_monitor 获取上下文百分比有两条路径见 _resolve_context首选statusline 缓存。Claude Code 的状态行格式化器会写入~/.pilot/sessions/会话ID/context-pct.json包含百分比与窗口大小缓存超过 60 秒视为过期自动作废降级Codex 会话转录。若提供了transcript_path则从转录文件末尾 4MB 中反向查找最新的token_count事件用最近一次模型调用的输入 token 数 ÷ 窗口计算压力——注意它刻意不采用累计消耗量因为那不代表真实上下文占用。窗口大小由 _get_max_context_tokens 自动探测从 statusline 缓存读取模型真实窗口读不到时回退 200K。状态行的实现细节可参考 features/statusline.md。六、压缩发生时完整的保护链路 context_monitor 只负责预警真正的压缩保护由三个钩子接力完成见 hooks.json 与 hooks.md 的 PreCompact 一节阶段钩子职责压缩前90%context_monitor.py静默提醒 Agent主动固化状态压缩前pre_compact.py捕获活动计划路径、状态、任务列表与压缩指令保存至 Pilot 会话存储压缩后post_compact_restore.py在会话恢复时重新注入计划与任务状态三者配合后即使上下文被大幅压缩/spec工作流的计划与任务上下文依然能起死回生。整个压缩行为在 Console 中也有迹可循七、快速自检清单 ✅想确认监控在你机器上正常工作可以按这张清单逐条核对查看~/.claude/settings.json确认PostToolUse中存在 matcher 为*的context_monitor.py条目长会话中留意~/.pilot/sessions/会话ID/下的context-pct.jsonts时间戳应持续刷新当 statusline 颜色变为红色≥90%时Agent 应能感知到压缩临近提示——用户侧无输出是正常现象单元测试位于 tests/test_context_monitor.py覆盖了阈值边界、节流、缓存写入与独立执行四类行为可作为行为基准参考。八、常见问题 FAQ Q为什么不直接把提醒打印到终端A终端提醒会打断用户节奏且 Agent 看不到。静默注入给模型才能让模型自己调整策略收尾任务、固化状态这正是上下文工程的精髓。Q1M 窗口的模型还会触发 90% 预警吗A会。百分比是相对实际窗口计算的窗口自动探测后阈值逻辑完全一致。Q预警发出后 Agent 应该做什么APilot 的提示明确写着work can continue normally——无需中断但模型应优先把关键决策写入计划文件为接下来的压缩做好快照。小结context_monitor 用一个钩子 一个缓存 一条静默消息的极简组合解决了长会话中最隐蔽的风险——上下文悄悄逼近压缩点。配合 pre_compact / post_compact_restore 的完整生命周期保护Pilot Shell 让你的 AI 会话在压缩前后都保持记忆连贯。如果你经常在 Claude Code 中跑长任务这套机制值得成为你的默认配置。【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pilot Shell 上下文监控完全指南：context_monitor 接近压缩时的预警机制
Pilot Shell 上下文监控完全指南context_monitor 接近压缩时的预警机制【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shellPilot Shell为 Claude Code 和 OpenAI Codex 提供了生产级的上下文工程能力其中最实用的功能之一就是context_monitor 上下文监控它会在会话即将触发自动压缩auto-compact前提前向 Agent 发出预警帮你避免上下文被截断时丢失关键工作记忆。本文带你完整读懂这套压缩预警机制的原理、触发条件与配合链路。一、什么是上下文压缩为什么需要提前预警Claude Code 的上下文窗口是有限的常见为 200K部分模型支持 1M。当对话与工具输出不断累积、接近窗口上限时运行时会自动执行上下文压缩compaction——把较早的对话内容总结裁剪以腾出空间。压缩本身是好事但它有一个代价早期的决策、约束、审批记录可能被摘要化甚至丢失如果 Agent 正在执行一个多步骤任务突然的压缩可能造成失忆需要重新确认状态。因此Pilot Shell 的 context_monitor.py 选择在压缩真正发生之前介入当上下文使用率达到 90% 时向 Agent 悄悄发出一次提醒让模型有机会主动把重要状态固化到计划或任务文件中。二、监控如何接入一个 PostToolUse 钩子 context_monitor 通过 Claude Code 的钩子系统注册。在 hooks.json 中它挂在PostToolUse事件上匹配器为*所有工具调用每当你使用一次工具钩子就跑一次匹配器必须是*而不是具体工具名列表——因为遗漏 MCP 工具会导致监控漏看规划阶段的调用复用已有钩子进程几乎零额外开销。安装后它会自动写入~/.claude/settings.json你无需手动配置。官方对钩子管线的完整说明见 features/hooks.md。三、90% 阈值预警何时触发⚠️核心逻辑在 run_context_monitor 中阈值常量定义在 context_monitor.py#L28低于 90%静默通过仅刷新会话缓存不输出任何提示达到 90% 及以上发出一次提醒例如Context at 91%. Auto-compact approaching; work can continue normally.——告知 Agent压缩即将发生但工作可以照常继续每会话只提醒一次通过shown_autocompact_warn标志位去重避免刷屏。若后续使用率回落到 90% 以下例如手动/compact后标志重置下次接近阈值会再次提醒。阈值为什么是 90% 而不是 80%Pilot 在 context-optimization.md 中给出了压缩预算公式为压缩过程预留33,000 token缓冲即 200K 窗口下约 83.5%、1M 窗口下约 96.7% 是真实的压缩触发点。90% 这个预警点恰好落在两者之间既留足了反应时间又不会过早打扰。节流设计不刷屏也绝不误判_is_throttled 实现了双重保护场景行为距上次检查不足 30 秒且使用率低于 90%跳过本次采样节流使用率接近或达到 90%永不节流保证预警一次不漏这样既控制了对会话缓存的读取频率又确保接近压缩这一关键时刻的监控绝对灵敏。四、预警如何送达静默的 additionalContext 这是很多用户最关心的细节context_monitor 的提醒不会打印在终端里。它通过post_tool_use_context见 _lib/util.py#L740构造如下 JSON 负载additionalContext提醒文案注入给 Agent 作为私有操作上下文suppressOutput抑制终端输出用户侧完全无感。换句话说这是一条只说给模型听的悄悄话。模型收到后会更倾向于把关键决策写入计划文件、收尾当前小任务、避免在压缩点中途执行高风险操作。所有多条通知会合并为单个 JSON 输出_emit防止两次 print 拼出非法 JSON 导致整个负载被丢弃——这种细节正是生产级钩子的可靠性保障。五、数据从哪来statusline 缓存与 Codex 降级路径 context_monitor 获取上下文百分比有两条路径见 _resolve_context首选statusline 缓存。Claude Code 的状态行格式化器会写入~/.pilot/sessions/会话ID/context-pct.json包含百分比与窗口大小缓存超过 60 秒视为过期自动作废降级Codex 会话转录。若提供了transcript_path则从转录文件末尾 4MB 中反向查找最新的token_count事件用最近一次模型调用的输入 token 数 ÷ 窗口计算压力——注意它刻意不采用累计消耗量因为那不代表真实上下文占用。窗口大小由 _get_max_context_tokens 自动探测从 statusline 缓存读取模型真实窗口读不到时回退 200K。状态行的实现细节可参考 features/statusline.md。六、压缩发生时完整的保护链路 context_monitor 只负责预警真正的压缩保护由三个钩子接力完成见 hooks.json 与 hooks.md 的 PreCompact 一节阶段钩子职责压缩前90%context_monitor.py静默提醒 Agent主动固化状态压缩前pre_compact.py捕获活动计划路径、状态、任务列表与压缩指令保存至 Pilot 会话存储压缩后post_compact_restore.py在会话恢复时重新注入计划与任务状态三者配合后即使上下文被大幅压缩/spec工作流的计划与任务上下文依然能起死回生。整个压缩行为在 Console 中也有迹可循七、快速自检清单 ✅想确认监控在你机器上正常工作可以按这张清单逐条核对查看~/.claude/settings.json确认PostToolUse中存在 matcher 为*的context_monitor.py条目长会话中留意~/.pilot/sessions/会话ID/下的context-pct.jsonts时间戳应持续刷新当 statusline 颜色变为红色≥90%时Agent 应能感知到压缩临近提示——用户侧无输出是正常现象单元测试位于 tests/test_context_monitor.py覆盖了阈值边界、节流、缓存写入与独立执行四类行为可作为行为基准参考。八、常见问题 FAQ Q为什么不直接把提醒打印到终端A终端提醒会打断用户节奏且 Agent 看不到。静默注入给模型才能让模型自己调整策略收尾任务、固化状态这正是上下文工程的精髓。Q1M 窗口的模型还会触发 90% 预警吗A会。百分比是相对实际窗口计算的窗口自动探测后阈值逻辑完全一致。Q预警发出后 Agent 应该做什么APilot 的提示明确写着work can continue normally——无需中断但模型应优先把关键决策写入计划文件为接下来的压缩做好快照。小结context_monitor 用一个钩子 一个缓存 一条静默消息的极简组合解决了长会话中最隐蔽的风险——上下文悄悄逼近压缩点。配合 pre_compact / post_compact_restore 的完整生命周期保护Pilot Shell 让你的 AI 会话在压缩前后都保持记忆连贯。如果你经常在 Claude Code 中跑长任务这套机制值得成为你的默认配置。【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考