Codex 长任务守护者为选定的 Git workspace 提供会话隔离的持久状态、自动上下文压缩恢复、重要工具结果固化、显式跨会话接力、语义检查点和基于证据的完成门禁。它只作用于安装它的仓库，不修改 ~/.codex，也不会影响其他 workspace。
当前版本：0.5.0。
一个 Codex 任务（聊天）应当对应一个连贯工作目标。聊天很长时，Codex 会自动压缩早期上下文；Guardian 为同一个任务保留经过签名的高价值状态，使压缩后的模型能够继续原来的下一步，而不必重新猜测历史。
同一 workspace 可以同时打开多个 Codex 任务。Guardian 使用 Codex Hook 提供的 session_id 派生不透明会话键，因此每个任务都有独立状态：一个任务的工具活动、压缩、停止和完成门禁都不能影响另一个任务。
Guardian 保存四类内容：
journal.jsonl：可追溯的操作和状态变化；state.json：目标、完成定义、事实、证据、决策、排除项、风险和计划；activity.json：工具结果的序号、类型、长度、结果指纹和安全退出状态回执，不保存原始结果；NEXT.md与RECOVERY.md：精确下一步和压缩后恢复导航。
聊天记录仍是工作记忆；签名状态只保存精炼、可验证的连续性信息；Git、文件、测试和外部系统始终是最终证据。Guardian 不保存隐藏思维链、原始敏感工具输出或原始 session_id。
前提：Git、Codex，以及系统中可用的 python3。Guardian 只使用 Python 标准库，不要求安装第三方依赖。
进入要启用 Guardian 的 Git 仓库，然后执行：
GUARDIAN_INSTALL_DIR="$(mktemp -d)"
git clone --depth 1 --branch v0.5.0 https://github.com/aihuangjun/codex-long-task-guardian.git "$GUARDIAN_INSTALL_DIR"
python3 "$GUARDIAN_INSTALL_DIR/install.py" --workspace .安装器会合并而不是覆盖已有的 AGENTS.md 和 .codex/hooks.json。它不会自动生成或修改项目自己的 README.md。
安装后把以下共享集成文件提交到当前仓库：
AGENTS.md
.agents/skills/long-task-state/
.codex/hooks.json
.codex/long-task-guardian/
以下运行时内容只留在当前 checkout，不应提交：
.long-task-guardian/ # 按会话隔离的任务状态
<git-dir>/long-task-guardian/signing.key # workspace 本地签名密钥
<git-dir>/long-task-guardian/hook-health.json
<git-dir>/long-task-guardian/handoffs/ # 签名 handoff 记录；不包含一次性内部标记的明文
.long-task-guardian/ 会写入 .git/info/exclude，不会修改共享 .gitignore。
- 用 Codex 打开这个 workspace；
- 审查
.codex/hooks.json中的六个项目 Hook； - 确认版本标记为
0.5.0，命令都指向当前仓库的.codex/long-task-guardian/hooks/guardian_hook.py； - 信任项目 Hook 后重新打开一个 Codex 任务；
- 运行诊断：
python3 .codex/long-task-guardian/scripts/long_task.py doctor信任前，doctor 会返回 warn，不会把“配置文件存在”误报成“Hook 已运行”。收到可信 SessionStart 回执后，健康安装应返回 pass。
普通短任务无需任何额外操作。对于长任务，只需自然语言说明这是长任务；项目规则和 long-task-state 技能会要求 Agent 在实质性修改前初始化当前会话状态。可信 PreToolUse Hook 会为纯 Guardian CLI 调用自动注入当前会话键，用户不需要管理任务绑定。
- 一个独立结果新建一个 Codex 任务；
- 相同问题继续使用原任务；
- 对进入通用
PostToolUse的工具调用，Guardian 生成不含原始输出的结果回执；重要结果立即用capture-result固化； - 长任务在重要证据、决策、阶段或下一步变化时建立语义检查点；
- 自动压缩后继续原任务，Guardian 会自动加载同一个会话的签名状态；
- 新建的 Codex 任务默认从空状态开始；用户明确要求“写一份 handoff”时才生成交接单；
SessionEnd只记录边界，不代表任务完成，也不会删除状态。
状态目录形态：
.long-task-guardian/
└── sessions/
└── <opaque-session-key>/
├── state.json
├── journal.jsonl
├── activity.json
├── pending-commit.json # 仅在一次提交尚未完全落盘时短暂存在
├── STATE.md
├── NEXT.md
└── RECOVERY.md
任务名称和 task-id 只是方便阅读的元数据，不承担路由作用。
PostToolUse 会向 Agent 注入一个工具结果回执，例如序号、工具名、结果指纹和安全退出状态。若结果改变了文件、测试、外部状态、事实、判断、风险或下一步，Agent 应按回执顺序立即执行：
python3 .codex/long-task-guardian/scripts/long_task.py capture-result \
--source-sequence 12 \
--action "运行完整回归测试" \
--outcome "全部测试通过" \
--impact "当前实现未发现回归" \
--evidence "python3 -m unittest discover -s tests -q；退出码 0"Guardian 把精炼结论和安全证据引用写入签名状态与日志；原始命令输出、提示词、凭据和隐藏思维链不会落盘。Stop 会阻止带着未固化工具活动结束；complete 也不会再把待处理回执顺带标记为已覆盖。如果 PostToolUse 自身无法保存回执，Hook 会显示错误并写入覆盖缺口，直到 Agent 根据真实文件、Git、测试或外部状态建立完整 checkpoint。
Hosted WebSearch 和少数专用工具路径可能不会进入通用 Tool Hook。使用这些工具得到会影响结论的重要结果后，应直接用 checkpoint 固化动作、证据、状态变化和下一步，不能把“没有收到回执”理解为“没有新状态”。
自动压缩、关闭后重开原任务都不需要 handoff。只有准备换一个 Codex 会话继续同一目标时，直接在旧会话说：
写一份 handoff，我要新开会话继续。
Guardian 会先确认重要结果都已固化，然后返回一份可直接复制的交接单，例如：
# Handoff 交接单
任务：继续完善长任务插件
下一步：运行最终验证
完成条件：全部检查通过
HANDOFF: ltgh1-...
在同一 checkout 中新建一个空白 Codex 会话，把整份交接单粘贴进去即可。新会话会自动识别 HANDOFF: 行并恢复任务；成功后旧会话转为只读。同一份 handoff 只能成功使用一次，默认七天有效，也不会写入仓库文件。Guardian 不根据父任务、时间或目录自动猜测继承关系。
固定检出 v0.5.0，然后执行：
python3 /path/to/codex-long-task-guardian/install.py \
--workspace /path/to/workspace \
--upgrade升级器会备份并替换 Guardian 管理的运行时和技能，合并项目 Hook 与 AGENTS.md。0.3.x/0.4.x 的会话状态和活动记录保持兼容；新增事务文件只在中断恢复时出现。--check 会逐文件比较运行时和技能，并比较完整 Hook 组语义，不再只检查版本号或命令路径。升级器不会擅自把旧的 workspace 全局活动任务分配给某个新会话。
若 SessionStart 或 doctor 检测到 0.2.x 活动状态，只有确认“当前 Codex 任务就是原来的工作目标”时，才在该任务中执行一次：
python3 .codex/long-task-guardian/scripts/long_task.py migrate-legacy迁移后，旧 active.json 和 tasks/ 保持原样用于审计；新的工作从 sessions/<opaque-session-key>/ 继续。另一个 Codex 任务不能再次导入同一份旧状态。
正常 git clone 或 git pull 会带上全部共享集成文件，不需要机器全局安装。新电脑只需：
- 用 Codex 打开仓库；
- 重新审查并信任该电脑上的项目 Hook；
- 重新打开任务；
- 运行
doctor。
每个 checkout/worktree 都会生成独立本机密钥。签名密钥和 .long-task-guardian/ 状态不进入 Git，因此仅克隆仓库不会迁移旧电脑的本地任务状态。需要跨电脑延续正在进行的任务时，应先设计明确、安全的状态导出流程，而不是提交本地密钥或运行时状态。
python3 /path/to/codex-long-task-guardian/install.py \
--workspace /path/to/workspace \
--uninstall卸载会移除仓库中的 Guardian 运行时、技能、托管规则和 Guardian Hook，但保留本地状态、签名密钥和备份，便于审计或重新安装。
python3 -m unittest discover -s tests -q
/usr/bin/python3 -m unittest discover -s tests -q
python3 -m compileall -q install.py template详细资料：
许可证：MIT。法律效力以标准英文版 LICENSE 为准；LICENSE.zh-CN 仅供中文阅读参考。安装模板中保留相同许可证副本。