尧图网站建设 
Pilot Shell SessionEnd处理详解会话收尾与Worker清理完整原理【免费下载链接】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 的专业上下文工程框架。它的SessionEnd Hook负责在 Agent 会话结束时完成三件关键事情导出会话记忆、标记会话完结、清理后台 Worker 进程确保每个 AI 会话都能干净落地不丢记忆、不留僵尸进程。这篇文章带你完整拆解它的处理原理。一、SessionEnd Hook 何时触发Pilot Shell 在两个平台的钩子清单中都注册了 SessionEnd 事件Claude Codehooks.jsonCodex CLIcodex_hooks.json两处配置完全一致——通过run_if_licensed.py包装执行 session_end.py并带上一个至关重要的参数--session-end超时 15 秒。这里有一个容易被忽略的细节脚本会先检查--session-end标志没有该标志就直接返回 0不做任何事见 session_end.py#L227-L231。这是为了区分回合结束与会话真正结束——某些 Agent 会在每轮对话结束时也发出类似事件若不加判断就会反复读写 stdin、空转 Worker。二、会话收尾的四步流程SessionEnd 被确认为真结束后主流程session_end.py#L227-L243按顺序执行第 1 步识别真正的会话 ID脚本优先使用钩子载荷里的session_id这是 Console 在会话注册时存下的contentSessionId载荷缺失时再回退到环境变量链CLAUDE_CODE_SESSION_ID→CODEX_THREAD_ID。值得注意的是它刻意不使用PILOT_SESSION_ID——那是 shell 包装层/PID 层的 ID用它去完结请求会永远返回 not_found却看起来一切正常。这个防坑设计值得借鉴。第 2 步清理会话残留物收尾前会删除该会话目录下的原生规格规划文件~/.pilot/sessions/{session_id}/内的 spec planning 标记missing_okTrue保证文件不存在也不报错。第 3 步判断是否还有其它活跃会话这是决定是否停止 Worker 的核心判断实现见 _has_other_active_sessions。它扫描~/.pilot/sessions目录用两套互补策略目录类型判定方式PID 型如12345直接os.kill(pid, 0)探测进程是否存活Agent 原生 UUID 型先扫描ps eww进程列表匹配--session-id、CODEX_THREAD_ID扫描失败时回退到心跳文件context-pct.json的时间戳120 秒内有更新视为活跃第 4 步启动分离式收尾器真正干活的是一个完全脱钩的短命 Python 子进程内联脚本见 session_end.py#L43-L69主脚本 spawn 它后立即返回不阻塞 Agent 退出POST 会话 ID 到 Console 的/api/sessions/complete接口等待响应15 秒超时收到响应后才执行bun ~/.pilot/scripts/worker-service.cjs stop停止后台 Workerworker-service.cjs15 秒超时。如果第 3 步发现还有别的活跃会话则只完结当前会话、不停止 Worker让 Worker 继续服务其它会话。三、为什么先完结、再停止顺序不能颠倒。Console 会等待该会话的记忆导出完成后才对 complete 请求返回确认——也就是说记忆导出的收件人就是正在运行的 Worker 服务。如果一上来就停掉 Worker导出会被截断本次会话积累的记忆就丢了。这也是整条链路最巧妙的一环用 HTTP 响应作为同步屏障把记忆导出完成隐式地编码进了可以停服务的前提里。四、容错设计处处安全默认Pilot Shell 的收尾逻辑贯彻了一个原则——任何异常都不应放大损失收尾失败不停 Workercomplete 请求失败时子进程直接退出Worker 保持运行导出可重试而非丢弃目录扫描出错 认为有活跃会话宁可多留一个 Worker也不误杀别人正在用的服务spawn 失败静默吞掉except OSError: pass钩子本身绝不能影响 Agent 主流程子进程带start_new_sessionTrue 关闭全部句柄父进程退出后收尾器依然可靠跑完。五、上手验证安装 Pilot Shell 后你可以这样观察收尾行为启动一个 Claude Code / Codex 会话ls ~/.pilot/sessions/观察会话目录的生成结束会话后再次查看目录并打开 Console 的 Sessions 页面确认会话状态已变为完结多开两个会话先结束其中一个会发现 Worker 依然存活全部结束后才停止。相关的单元测试位于 test_session_end.py覆盖了 ID 回退链、活跃会话判定、--session-end缺失时零副作用等关键分支。六、核心文件速查文件作用pilot/hooks/session_end.pySessionEnd 主逻辑会话完结 Worker 清理pilot/hooks/hooks.jsonClaude Code 侧 SessionEnd 注册pilot/hooks/codex_hooks.jsonCodex CLI 侧 SessionEnd 注册pilot/hooks/hook-lifecycle.json钩子生命周期矩阵pilot/scripts/worker-service.cjs后台 Worker 服务含 stop 子命令pilot/hooks/tests/test_session_end.py收尾行为单元测试总结Pilot Shell 的 SessionEnd 处理看似只是会话结束跑个脚本实则是时序安全的教科书案例--session-end标志防止误触发、双通道进程探测防止误停 Worker、HTTP 响应作为同步屏障保证记忆导出完整、全程 fire-and-forget 保证不阻塞 Agent。理解了这条链路你就掌握了 Pilot Shell 会话生命周期的最后一块拼图。 提示如需获取完整源码研究实现细节可执行git clone https://gitcode.com/GitHub_Trending/cl/pilot-shell。【免费下载链接】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 SessionEnd处理详解：会话收尾与Worker清理完整原理
Pilot Shell SessionEnd处理详解会话收尾与Worker清理完整原理【免费下载链接】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 的专业上下文工程框架。它的SessionEnd Hook负责在 Agent 会话结束时完成三件关键事情导出会话记忆、标记会话完结、清理后台 Worker 进程确保每个 AI 会话都能干净落地不丢记忆、不留僵尸进程。这篇文章带你完整拆解它的处理原理。一、SessionEnd Hook 何时触发Pilot Shell 在两个平台的钩子清单中都注册了 SessionEnd 事件Claude Codehooks.jsonCodex CLIcodex_hooks.json两处配置完全一致——通过run_if_licensed.py包装执行 session_end.py并带上一个至关重要的参数--session-end超时 15 秒。这里有一个容易被忽略的细节脚本会先检查--session-end标志没有该标志就直接返回 0不做任何事见 session_end.py#L227-L231。这是为了区分回合结束与会话真正结束——某些 Agent 会在每轮对话结束时也发出类似事件若不加判断就会反复读写 stdin、空转 Worker。二、会话收尾的四步流程SessionEnd 被确认为真结束后主流程session_end.py#L227-L243按顺序执行第 1 步识别真正的会话 ID脚本优先使用钩子载荷里的session_id这是 Console 在会话注册时存下的contentSessionId载荷缺失时再回退到环境变量链CLAUDE_CODE_SESSION_ID→CODEX_THREAD_ID。值得注意的是它刻意不使用PILOT_SESSION_ID——那是 shell 包装层/PID 层的 ID用它去完结请求会永远返回 not_found却看起来一切正常。这个防坑设计值得借鉴。第 2 步清理会话残留物收尾前会删除该会话目录下的原生规格规划文件~/.pilot/sessions/{session_id}/内的 spec planning 标记missing_okTrue保证文件不存在也不报错。第 3 步判断是否还有其它活跃会话这是决定是否停止 Worker 的核心判断实现见 _has_other_active_sessions。它扫描~/.pilot/sessions目录用两套互补策略目录类型判定方式PID 型如12345直接os.kill(pid, 0)探测进程是否存活Agent 原生 UUID 型先扫描ps eww进程列表匹配--session-id、CODEX_THREAD_ID扫描失败时回退到心跳文件context-pct.json的时间戳120 秒内有更新视为活跃第 4 步启动分离式收尾器真正干活的是一个完全脱钩的短命 Python 子进程内联脚本见 session_end.py#L43-L69主脚本 spawn 它后立即返回不阻塞 Agent 退出POST 会话 ID 到 Console 的/api/sessions/complete接口等待响应15 秒超时收到响应后才执行bun ~/.pilot/scripts/worker-service.cjs stop停止后台 Workerworker-service.cjs15 秒超时。如果第 3 步发现还有别的活跃会话则只完结当前会话、不停止 Worker让 Worker 继续服务其它会话。三、为什么先完结、再停止顺序不能颠倒。Console 会等待该会话的记忆导出完成后才对 complete 请求返回确认——也就是说记忆导出的收件人就是正在运行的 Worker 服务。如果一上来就停掉 Worker导出会被截断本次会话积累的记忆就丢了。这也是整条链路最巧妙的一环用 HTTP 响应作为同步屏障把记忆导出完成隐式地编码进了可以停服务的前提里。四、容错设计处处安全默认Pilot Shell 的收尾逻辑贯彻了一个原则——任何异常都不应放大损失收尾失败不停 Workercomplete 请求失败时子进程直接退出Worker 保持运行导出可重试而非丢弃目录扫描出错 认为有活跃会话宁可多留一个 Worker也不误杀别人正在用的服务spawn 失败静默吞掉except OSError: pass钩子本身绝不能影响 Agent 主流程子进程带start_new_sessionTrue 关闭全部句柄父进程退出后收尾器依然可靠跑完。五、上手验证安装 Pilot Shell 后你可以这样观察收尾行为启动一个 Claude Code / Codex 会话ls ~/.pilot/sessions/观察会话目录的生成结束会话后再次查看目录并打开 Console 的 Sessions 页面确认会话状态已变为完结多开两个会话先结束其中一个会发现 Worker 依然存活全部结束后才停止。相关的单元测试位于 test_session_end.py覆盖了 ID 回退链、活跃会话判定、--session-end缺失时零副作用等关键分支。六、核心文件速查文件作用pilot/hooks/session_end.pySessionEnd 主逻辑会话完结 Worker 清理pilot/hooks/hooks.jsonClaude Code 侧 SessionEnd 注册pilot/hooks/codex_hooks.jsonCodex CLI 侧 SessionEnd 注册pilot/hooks/hook-lifecycle.json钩子生命周期矩阵pilot/scripts/worker-service.cjs后台 Worker 服务含 stop 子命令pilot/hooks/tests/test_session_end.py收尾行为单元测试总结Pilot Shell 的 SessionEnd 处理看似只是会话结束跑个脚本实则是时序安全的教科书案例--session-end标志防止误触发、双通道进程探测防止误停 Worker、HTTP 响应作为同步屏障保证记忆导出完整、全程 fire-and-forget 保证不阻塞 Agent。理解了这条链路你就掌握了 Pilot Shell 会话生命周期的最后一块拼图。 提示如需获取完整源码研究实现细节可执行git clone https://gitcode.com/GitHub_Trending/cl/pilot-shell。【免费下载链接】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），仅供参考