mcpField
S
setup-auto-handoff

setup-auto-handoff

github.com/dyritsAgent 工作流037 次安装今天更新
代码仓库

关于 setup-auto-handoff

setup-auto-handoff 是面向 Claude Code 的技能，要求先有近期交接文件才允许压缩上下文。它通过 PreCompact 钩子执行，并说明 OpenCode 和 Codex 基于会话记录的替代方式。

主要功能

  1. 01缺少近期交接文件时阻止压缩
  2. 02调用 hand-off 技能
  3. 03提供配置与验证步骤
  4. 04说明 OpenCode 和 Codex 的替代方式

适用场景

  1. 01在 Claude Code 压缩前保留上下文
  2. 02配置并测试 PreCompact 钩子
  3. 03在 OpenCode 或 Codex 中处理交接

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dyrits/skills --skill setup-auto-handoff

安装后在 Claude Code 中输入/setup-auto-handoff确认已加载。

附带文件agents/openai.yamlscripts/precompact-handoff-gate.sh

详细介绍

设置自动交接

限制上下文压缩：当 Claude Code 即将压缩上下文（自动或手动）时，PreCompact 钩子会阻止操作，除非最近 5 分钟内已将交接记录写入 .agents/handoffs/。阻止原因会提示 Agent 先运行 hand-off 技能；交接记录写入后，下一次压缩尝试即可通过。

调用：hand-off。如果未安装所调用的技能，请告知用户其名称和安装命令 npx skills@latest add Dyrits/SKILLS --skill=<name>，然后根据该技能声明的意图执行相应步骤，并在没有该技能的情况下报告步骤已完成。

各环境中的支持情况

  • Claude Code：完全支持（PreCompact 钩子）。这是本设置的主要工作方式。
  • OpenCode / Codex：没有压缩前钩子。备用方式是使用它们持久化的对话记录（codex resume、OpenCode 会话存储），并由用户养成在阶段交界处运行 hand-off 的习惯。请如实告知用户；不要假装此功能已覆盖。

步骤

1. 复制钩子脚本

附带的脚本位于 scripts/precompact-handoff-gate.sh

将其复制到 .claude/hooks/precompact-handoff-gate.sh，并赋予可执行权限（chmod +x）。

阻止消息会调用 hand-off，因此该技能必须出现在技能列表中，才能让检查顺利通过。如果未安装，请建议先安装；消息中的备用方案（直接写入交接文件）仍可让压缩继续进行。

2. 注册钩子

在 .claude/settings.json（项目级作用域；钩子无法设置更窄的作用域）中，将以下内容合并到现有的 hooks 对象中：

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/precompact-handoff-gate.sh"
          }
        ]
      }
    ]
  }
}

不要覆盖其他钩子；请合并数组。

3. 验证
  • .claude/hooks/precompact-handoff-gate.sh 文件存在且可执行
  • .claude/settings.json 可解析（jq . .claude/settings.json），并包含 PreCompact 条目
  • 模拟没有新交接记录时的自动压缩：
echo '{"trigger":"auto"}' | .claude/hooks/precompact-handoff-gate.sh; echo "exit: $?"

预期标准输出中会有 decision: block 的 JSON，退出代码为 0。

  • 模拟存在新交接记录时的情况：
mkdir -p .agents/handoffs && touch .agents/handoffs/test.md
echo '{"trigger":"auto"}' | .claude/hooks/precompact-handoff-gate.sh; echo "exit: $?"
rm .agents/handoffs/test.md

预期输出为空，退出代码为 0。

4. 向用户说明工作流程

达到上下文限制时：自动压缩触发，钩子根据提示阻止操作，Agent 运行 hand-off（在 .agents/handoffs/ 中生成一个新文件），随后重试压缩并通过。如果确实不希望压缩，用户可以从 .claude/settings.json 中移除该钩子。手动执行 /compact 也会受到同样的限制；/clear 不受影响（这是另一种事件）。

注意事项

  • 5 分钟的新鲜度窗口可防止一小时前的旧交接记录通过检查。可编辑脚本中的 FRESH_WINDOW_MINUTES 进行调整。
  • 如果 .agents/handoffs/ 不存在，检查会创建该目录，因此第一次被阻止的压缩也会是第一次交接。
  • 钩子需要 PATH 中有 jq；如果未安装，请检查并告知用户。

评论

支持 Markdown