Agent长程任务的上下文保护：Context Guard开源

AI Agent正在改变任务的基本单位。过去，我们更常把一次模型调用理解为一次问答或一处局部修改；现在，以Codex为代表的Agent开始接手持续数小时、数天甚至更久的任务，调用工具、组织多个Agent，用户也会在执行中不断补充要求。OpenAI对Codex app的介绍将其描述为从定点修改走向覆盖设计、实现、交付和维护的长程协作。

在长程动态任务中，最近受到关注的循环工程（Loop Engineering）体现了一种持续迭代的工作方式：Agent执行一轮，检查结果，接收修订，再继续下一轮。Codex的agent loop负责协调用户、模型和工具。

当任务进入这种循环，正确性面临的主要问题也随之变化。我们不能只问模型这一轮做得怎么样，还要确保两件事：

1. 任务契约保持稳定：用户确认过的目标、限制、验收标准和后续修订，不能在上下文压缩或任务恢复后被静默改写；
2. 完成结论能够回到证据：每条仍然有效的要求都应有对应的成功证据，未核实、等待授权或尚未完成的事项不能被包装成整体完成。

目标并不是让Agent记住所有历史，也不是建立另一套计划和调度系统，而是在长程循环中保住决定结果是否正确的少量状态：现在真正有效的要求是什么，哪些要求已经验证，哪些仍需继续处理。

为此，我实现并开源了Context Guard。它是一个面向Codex的本地正确性旁路，通过生命周期Hooks在本机维护一份私有、可校验的需求与证据账本。

Context Guard的实际作用，可以通过以下这个日常的行程规划任务示例说明。用户一开始只说：

我想下周从武汉出发前往北京旅游一周，请帮我规划行程。

Codex开始查询交通、住宿和景点后，用户又陆续补充：自己会和母亲两人出行，母亲膝盖不太好，每天不能安排太多步行；往返只坐高铁；两人总预算不超过8000元；周三15:00—19:00必须去海淀见朋友；想参观故宫，但所有需要预约的项目都要先核对官方信息，不能把待确认的票源写成已经订好。

随着Codex查询车次、比较酒店、核对预约规则和调整每天的路线，对话会越来越长。如果此时发生上下文压缩，摘要可能还记得“正在规划武汉到北京的七日游”，却漏掉母亲不宜长时间步行，或者把周三下午重新排给其他景点。它也可能查到一条过期攻略，就把尚未核实的开放时间和票务状态写进最终方案。

模型并没有完全忘记任务。它还记得要去哪里，却遗漏了决定行程能否执行的少量约束。

1. 它具体解决什么问题？

仍以刚才的北京行程为例。Context Guard关注的不是完整对话，而是逐步形成的任务契约：

[ ] 下周从武汉往返北京，共七天 [ ] 自己和母亲两人出行，总预算不超过8000元 [ ] 往返只坐高铁，不安排飞机 [ ] 母亲膝盖不适：减少步行，不连续安排高强度景点 [ ] 周三15:00—19:00在海淀见朋友，该时段不可调整 [ ] 希望参观故宫 [ ] 预约、开放时间、票价和交通信息以当前官方来源为准 [ ] 尚未核实或尚未预约的项目必须明确标为待确认

Codex仍然负责搜索信息、比较方案、安排路线、计算预算和组织Subagent。Context Guard只记录与正确性直接相关的内容：用户提出了哪些要求，后续补充或修改了什么，工具返回了哪些可用证据，以及当前是否还有未完成项。

发生/compact或任务恢复后，这份清单会重新进入上下文。假设Codex已经排好了七天路线，也算出了预算，但周三下午仍被安排了景点，或者“故宫预约信息需经官方来源核验”这一要求仍未绑定成功证据，Context Guard就不会接受“行程已经规划完成”的结论。Codex需要继续调整冲突时段，并把未核实内容标为待确认。

这里的完成证据也很直观：七天行程表需要逐日满足强度和时间约束；预算表的总额不能超过上限；车次、开放时间和预约要求需要附上查询日期与来源；尚未完成的预约不能写成已经成功。

因此，它解决的不是“让摘要写得更长”，而是避免任务契约在摘要中被悄悄改写。

2. 它如何与Codex配合？

Context Guard没有重新实现Codex已有的Plan、Goal、compaction、subagents、worktrees或memories。下面这张图概括了Context Guard保护的工作路径：

未完成项不会被压成一个模糊的“未完成”状态。user_wait表示下一步需要用户输入、确认或授权；external_wait表示需要等待外部系统或人员；deferred表示事项被明确推迟或不在当前范围内。兼容保留的continue只作为提示：Agent应在给出终态回复之前通过工具调用继续工作，而不是在本轮已经结束后重新强制开启一轮。整体完成仍然只能由全部有效要求通过验证后得出。

这里有四个我比较看重的设计。

2.1 已经结束的一轮，不会被重新拉回循环

Context Guard把两个问题分开处理：“整个任务是否已经完成”和“Agent是否还应在这一轮继续工作”。如果下一步需要用户操作、需要等待外部结果，或者已经明确留到以后，Agent可以正常停下来，同时保留所有未完成事项。如果Agent还有工作，应当在给出终态回复前继续调用工具，而不是在本轮已经结束后重新强制开启一轮。系统不会仅凭一句自然语言推测，就把已经结束的回复重新拉回循环。

插件也会区分真正的控制命令，以及只是在文档或搜索文本中出现的同名文字，从而减少误触发。发生升级或恢复时，它会保留已经记录的任务要求、验收条件和证据，只丢弃过时且尚未完成的控制动作。

安装过程也遵循同一原则：已经被运行中任务使用的版本化缓存不会被静默覆盖。如果缓存与可信备份不一致，Context Guard只会从经过验证的副本修复；无法确认时就安全停止，而不是猜测性修改。

2.2 后续修订不会覆盖历史

长任务很少从开始到结束都保持同一组要求。用户可能补充限制，也可能明确用新要求替代旧要求。Context Guard会记录这条修订关系，而不是直接重写旧记录。

这样做的好处是，压缩恢复后仍然能够回答两个不同的问题：最初提出了什么，以及现在真正有效的要求是什么。遇到含义不明确的否定或替代关系时，插件会保留原要求并等待确认，不会自行猜测。

2.3 查到信息，不代表要求已经满足

搜索工具成功打开一个网页，只能证明查询执行成功，不能证明页面来自官方、信息仍然有效，或者预约已经完成。预算计算没有报错，也不代表其中已经包含市内交通和其他必要支出。

Context Guard优先使用结构化状态、退出码和明确的完成标记。含糊输出会被记为unknown，不能直接支持完成结论。在这个例子中，行程表、预算汇总和带查询日期的官方来源可以分别作为证据；一个普通搜索结果不能自动替代它们。

当验证义务能够被确定性构造时，Context Guard还会把证据绑定到具体的需求或验收项、对象、文件或UI表面、视觉输入或结果回读，以及用户要求的完整范围。针对错误对象、错误表面或不完整子集的成功命令，不能关闭该事项。无法可靠确定这些边界时，系统会显式记录legacy_fallback，而不是把它当作已经完成语义证明。

这仍不意味着插件能够理解所有证据的语义。对受约束事项，它只核对可确定的绑定和范围；对不支持的情形，legacy_fallback保留兼容的来源与执行结果门禁。它不能证明证据在逻辑上一定充分，不能解释任意像素，也不能确认来源的官方性。最终的验证设计仍然由Codex和用户负责。

2.4 Subagent有明确来源，但不能改变根任务

在多Agent任务中，Subagent收到的是有界委托，而不是新的用户授权。Context Guard记录Agent的开始、结束、结果和来源，但Subagent不能创建、取消或替代根任务需求。

这可以避免一个常见混淆：局部任务已经完成，不等于整个任务已经完成；Subagent提出的建议，也不等于用户修改了原始要求。

3. 为什么强调私有状态？

需求账本可能包含尚未公开的行程、代码路径、文档要求或其他任务背景，因此它不应该进入项目Git历史。

Context Guard的公开仓库只包含插件代码、Hooks、Schema、文档和测试。实际运行数据写入Codex管理的PLUGIN_DATA，默认只保留在本机。插件不保存chain-of-thought，不复制完整transcript，也不会主动发起网络请求。

用户可以显式执行context-guard export或rollover生成脱敏handoff或有界successor pack。导出过程会省略常见凭据、认证头、URL查询参数、原始提示文件和插件私有路径。不过，自动脱敏不能替代人工检查；任何准备分享的交接文件仍应在发送前复核。

4. 安装与第一次验证

项目要求Python 3.10或更高版本，当前验证的Codex CLI最低基线为0.146.0。

macOS和Linux可以运行：

gitclone https://github.com/GreenLv/codex-context-guard.gitcdcodex-context-guard python3 scripts/manage_plugin.py--apply

Windows可以运行：

py-3.10 scripts\manage_plugin.py--apply

安装完成后需要启动一个新的Codex任务，并在/hooks中检查八类Hook定义。只有确认命令与仓库内容一致后，才应选择信任；插件安装不会自动绕过Hook信任。

然后输入：

$context-guard

再执行：

context-guard status context-guard diagnose

如果想验证完整恢复链，可以创建一个包含多条要求和禁止事项的任务，执行/compact，再检查continuation是否恢复了相同的有效要求。

完整安装、升级和卸载说明可参见项目的中文README。

5. 哪些任务值得使用？

Context Guard更适合持续时间较长、要求可能变化，而且需要用工具结果证明完成状态的任务。例如：

• 规划复杂行程，中途增加预算、同行人员、固定时间或交通限制；
• 编写或修改文档，需要保留模板、术语、数字和禁止改动范围；
• 重构代码，同时保持现有接口、数据格式或兼容行为；
• 运行实验或批量处理文件，不能把部分成功当成整体完成；
• 使用多个Subagent，需要区分根任务授权和局部委托；
• 将任务交给后续执行者，但不希望复制完整会话记录。

如果只是一次对话内完成的小修改，通常没有必要启用完整保护。

Context Guard会向受保护任务注入提示和恢复上下文。在一组经过匿名化的5个已完成、工具调用较多的0.6.1桌面任务中，把插件触发的状态核对计入后，加权观测值约为1.5%，单任务约为0.2%–2.1%。对相似长任务，可以把约1%–2%作为量级参考，而不是固定保证值；token占比也不等同于费用占比。

6. 当前验证状态与边界

项目目前具有限定的macOS和Windows原生验收。Linux只声明源码CI，不宣称原生桌面安装或Hook行为。精确的平台范围与本地验收证据分别见兼容性说明和本地验收记录。

Context Guard也不是语义正确性证明器、安全沙箱、云同步服务、完整会话备份或第二套Agent调度系统。它的Proof protocol只执行可确定构造的验证义务，不解释任意自然语言或像素，也不确认来源是否官方。它只保护任务契约、修订关系、有限计划镜像、来源明确的Agent结果和完成证据。

我希望这个项目保持克制。先把需求不静默丢失、修订可追踪、无证据不宣告完成、私有状态不进入Git这几件事做扎实，再根据可复现的问题决定后续功能。

已发布版本及其精确验收记录可以从GitHub Releases查看。

Context Guard也已被awesome-codex-plugins收录到Development & Workflow分类。

7. 总结

Context Guard的核心思路并不复杂：

不依赖压缩后的摘要猜测任务要求，而是在本机维护一份私有、可校验的需求与证据账本；压缩恢复后重新核对有效要求，再决定任务能否完成。

如果你也在使用Codex处理长任务，遇到过要求在压缩后漂移、局部测试通过却提前收尾，或者多Agent协作中权限边界不清的问题，欢迎试用：

GitHub：GreenLv/codex-context-guard
最新版本：GitHub Releases

如果这个项目对你有帮助，欢迎点一个Star、提交Issue，或者分享你遇到的长任务上下文失败案例。相比简单增加功能，真实、可复现的问题更有助于确定项目下一步应该解决什么。