claude-code-tips 实战：用 half-clone Skill 克隆对话后半段，为超长 Claude Code 会话瘦身续命

• AI 技能
• 教程
• 开发工具

本篇指南以本仓库中的half-cloneSkill 为骨架，讲透"只保留当前 Claude Code 会话的后半段、丢弃早前上下文"这一省 token 技巧：从 Skill 定义的标准操作流程，到 half-clone-conversation.sh 的源码级实现细节，再到 check-context.sh 自动触发与 test-half-clone.sh 的完整测试验证。读完你将掌握：如何用一个命令把一条 20 万 token 的长会话裁剪成只含最近一半/四分之一内容的新会话，并立即claude --resume无缝续工。

为什么要 half-clone：长会话的 token 治理

Claude Code 的上下文窗口有限（以当前主流 200k 配置为例），会话越长，历史上下文占用越多，模型性能与响应速度都会随之下滑。官方/compact会压缩会话，但压缩本质是"改写摘要"，会丢失原始措辞与细节；而本仓库提供的 half-clone 思路是确定性的裁剪——把早前的对话记录直接截断丢弃，只保留最近的内容原样搬运，保留完整可用的上下文语义。

这一点在仓库的 README.md Tip 21 中有明确总结：half-clone "reduces token usage while preserving your recent work"，且相比自动压缩，它是确定性的、快速的，保留的是真实消息而不是摘要。作为补充，同目录的 quarter-clone Skill 提供了"只保留最后四分之一"的更激进变体。

half-clone Skill 是什么

skills/half-clone/SKILL.md 是一个 Claude Code Skill，其 front matter 声明为：

• name: half-clone
• description: Clone the later half of the current conversation, discarding earlier context to reduce token usage while preserving recent work.

它的定位是让 Claude 在会话过长时主动发起克隆：复制当前会话的"后半段"到一个全新 session，丢弃早前上下文以降低 token 消耗，同时保住最近的工作成果。该 Skill 本身只是一份"操作说明书"，真正干活的是仓库中的 bash 脚本。

标准操作流程（Skill 定义的 5 步）

按照 SKILL.md 的原始步骤，一个完整的 half-clone 操作如下：

第 1 步：获取当前会话 ID 与项目路径

tail -1 ~/.claude/history.jsonl | jq -r '[.sessionId, .project] | @tsv'

history.jsonl是 Claude Code 本地的会话历史记录文件，最后一行即当前会话条目，jq提取出sessionId与project两个字段（制表符分隔）。

第 2 步：定位 half-clone-conversation.sh 脚本

find ~/.claude -name "half-clone-conversation.sh" 2>/dev/null | sort -V | tail -1

无论脚本是通过 dx 插件安装，还是手动 symlink 到~/.claude/scripts/，都能被找到；sort -V版本排序保证多版本并存时优先选中最新版。

第 3 步：预览会话，校验 session ID

<script-path> --preview <session-id> <project-path>

预览模式会输出会话文件路径、总行数、首条与末条用户消息，用于确认拿到的 session ID 确实对应当前会话。

第 4 步：执行克隆

<script-path> <session-id> <project-path>

注意 SKILL 特别强调：project-path必须来自 history 条目（即第 1 步的输出），而不是当前工作目录。

第 5 步：恢复克隆会话

脚本会打印New session: <id>行。把新 session ID 直接交给用户执行，无需再打开选择器：

claude --resume <new-session-id>

脚本会自动在克隆文件末尾追加一条指向原始会话的引用消息；同时新会话第一条真实用户消息会被打上[HALF-CLONE <timestamp>]标记（形如[HALF-CLONE Jan 7 14:30]），因此claude -r后手动选择标记的会话同样可行。

脚本源码剖析：一个纯 bash 实现的 JSONL 手术

核心实现位于 scripts/half-clone-conversation.sh，约 600 行，零 Python/Node 依赖，兼容 macOS（bash 3.2+）与 Linux。脚本默认以set -euo pipefail严格模式运行，全程通过awk单遍扫描处理会话文件。

命令行参数

half-clone-conversation.sh [--quarter] <session-id> [project-path]

参数解析见脚本 main 段：--preview、--quarter依次处理后，剩余的第一个位置参数必须是 session ID，并校验 UUID 格式（见 L600-L603），不合规则报错退出。

会话文件的定位与"干净用户消息"过滤

脚本先按project-path派生的目录名定位~/.claude/projects/<dirname>/<session-id>.jsonl，找不到时再全目录按文件名搜索（find_conversation_file）。

关键的一步是 filter_clean_user_msgs 这个 awk 过滤器：它只统计顶层"type":"user"或"type":"queue-operation"的消息，并排除三类噪声——tool_result（工具返回，依赖被裁剪的前置tool_use）、isMeta:true（元消息）、以及 "Request interrupted by user"（被打断的消息）。之所以要看顶层 type，是因为 progress/subagent 数据里常嵌套"type":"user"，若误计会把裁剪点算错。这一点被测试 test_progress_with_nested_user_type 专门覆盖：脚本输出Total clean user messages in conversation: 3，而不是 5。

裁剪点的计算

统计出干净的 user 消息总数 N 后（L223-L237）：

skip_clean_count=$((total_clean_user_messages * (KEEP_DENOM - 1) / KEEP_DENOM))

• half 模式KEEP_DENOM=2：跳过前 N/2 条，保留后一半；
• quarter 模式KEEP_DENOM=4：跳过前 3N/4 条，保留后四分之一。

若 N < 2，脚本直接报错退出（"fewer than 2 clean user messages, nothing to half-clone"），对应测试 test_single_message_error。随后用filter_clean_user_msgs -n拿到每条第skip_clean_count + 1个干净 user 消息所在的行号，从而确定从原始文件的哪一行开始保留（L239-L249）。

逐字段重映射：让克隆文件"自洽"

裁剪后直接把 JSONL 行复制过去是不够的，因为每条消息的uuid、parentUuid、messageId、sessionId互相引用。awk 单遍处理做了四件事（L425-L491）：

1. sessionId 替换：所有行中的sessionId统一换成新生成的 UUID；
2. uuid / messageId 重映射：维护uuid_map，旧 UUID 一一映射为新预生成 UUID，保证克隆文件内部引用闭合；预生成的 UUID 由 pre_generate_uuids 批量产出（优先hexdump从/dev/urandom快速生成）；
3. 首消息接驳：文件开头先写入一条合成 user 消息作为 marker（内容形如[HALF-CLONE <ts>] Continued from session <原id>），并把保留部分第一条非tool_result消息的parentUuid指向 marker（L302-L309）。这样claude -r才能在前 16KB 内找到firstPrompt而正常列出会话；
4. 首条真实用户消息打标签：在内容前插入[HALF-CLONE <timestamp>]前缀。

三个避免"恢复即炸"的防御性处理

源码里埋了三处专门针对真实场景的坑，值得重点理解：

• 剥离 thinking 块：strip_thinking 删除消息内容中的{"type":"thinking"...}/redacted_thinking块（含字符串转义的括号匹配）。注释明确说明原因：这类瞬时块在恢复时会导致 API Error 400（"thinking or redacted_thinking blocks in the latest assistant message cannot be modified"）。测试 test_thinking_blocks_stripped 验证克隆后 thinking 块为 0 且 text 块保留。
• 丢弃 session-config 尾行：新版 Claude Code 会在每个会话末尾追加last-prompt、ai-title、mode、permission-mode类型的行（L418-L423）。其中last-prompt携带leafUuid指向会话指针，脚本只重映射uuid/parentUuid/messageId而不动leafUuid，照抄会导致悬空指针、恢复后会话显示为空。测试 test_session_config_lines_stripped 同时验证了末尾引用消息的parentUuid指向克隆文件中真实存在的 uuid。
• 缩放 token 计数：divide_number 将每条保留消息中的input_tokens、cache_read_input_tokens、cache_creation_input_tokens按分母整除（half 除 2、quarter 除 4，见 L481-L484）。测试 test_quarter_token_division 与 test_half_token_division 验证 400→200（half）与 400→100（quarter）的换算。

收尾：引用消息、history 更新与展示文本

克隆完成后（L494-L568）：

• 在文件末尾追加一条isMeta:true的 assistant 消息，父节点指向克隆文件最后一个真实消息 uuid，文本说明"此会话仅含原会话的后半部分，原始会话为<source_session>"——这就是 SKILL.md 所说的"自动追加原始会话引用"；
• touch克隆文件使其在claude -r列表中排到顶部；
• 向~/.claude/history.jsonl追加一条历史记录，display文本取保留部分第一条带内容字段的干净 user 消息（最多 200 字符），并加上[HALF-CLONE <timestamp>]前缀（L520-L552）。测试 test_history_entry 验证 history 增加且带标签。

测试验证：17 个用例如何保障正确性

scripts/test-half-clone.sh 是一个自包含测试套件：它用mktemp创建隔离的假~/.claude目录，用generate_message生成 mock JSONL 会话，再以HOME=$TEST_DIR覆盖的方式运行被测脚本，不触碰真实数据。覆盖点包括：

• 裁剪数量：偶数/奇数消息、最小 4 条、少于 2 条报错（test_even_messages、test_odd_messages、test_minimum_messages、test_single_message_error）；
• 结构正确性：首消息parentUuid:null、[HALF-CLONE]标签存在、sessionId 全部重映射（test_parent_uuid_nullified、test_half_clone_tag、test_session_id_remapped）；
• 重复克隆：对已带标签的会话再 half-clone，新标签叠加而不覆盖，两个标签共存（test_double_tagging）；
• 防御性处理：thinking 块剥离、嵌套 type 不计入、session-config 尾行丢弃（见上文）；
• quarter 模式：保留数量、[QUARTER-CLONE]标签、token 除以 4、最小会话仍可用（test_quarter_eight_messages、test_quarter_tag、test_quarter_token_division、test_quarter_minimum_messages）。

运行方式：

bash scripts/test-half-clone.sh

全部通过时输出All tests passed!。

三种安装方式

• 手动 symlink：按 README.md Tip 21 的说明，把脚本与两个 skill 软链到~/.claude对应目录：

ln -s /path/to/this/repo/scripts/half-clone-conversation.sh ~/.claude/scripts/half-clone-conversation.sh ln -s /path/to/this/repo/skills/half-clone ~/.claude/skills/half-clone ln -s /path/to/this/repo/skills/quarter-clone ~/.claude/skills/quarter-clone

• dx 插件：本仓库同时是名为dx的 Claude Code 插件，安装后即可用/dx:half-clone、/dx:quarter-clone，无需手动 symlink：

claude plugin marketplace add ykdojo/claude-code-tips claude plugin install dx@ykdojo

• 快速安装脚本：scripts/setup.sh 会询问跳过项，其中第 5 项会向~/.claude/settings.json追加Read(~/.claude)权限（jq '.permissions.allow = (.permissions.allow // []) + ["Read(~/.claude)"]'），专门服务于 half-clone 读取会话历史。

推荐配置：权限与自动触发

权限：half-clone 脚本需要读取~/.claude（会话文件与 history）。为避免在任意项目中反复触发权限弹窗，在~/.claude/settings.json的全局设置中加入：

{ "permissions": { "allow": ["Read(~/.claude)"] } }

自动触发：scripts/check-context.sh 是一个 Stop hook：每次 Claude 响应结束后读取 transcript，按input_tokens + cache_read_input_tokens + cache_creation_input_tokens计算上下文占用，超过 85%（阈值max_context=200000）时返回{"decision":"block",...}，阻止 Claude 停止并指示它运行/half-clone，让新 agent 在只含后半段的新会话中继续。安装方式：

cp /path/to/this/repo/scripts/check-context.sh ~/.claude/scripts/check-context.sh chmod +x ~/.claude/scripts/check-context.sh

并在~/.claude/settings.json注册 hook：

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "~/.claude/scripts/check-context.sh" } ] } ] } }

使用前提（README.md 中的说明）：需在/config中关闭 Auto-compact，否则 Claude Code 可能在 hook 触发前就先压缩上下文；hook 用stop_hook_active标志防止自身无限循环。相比自动压缩，half-clone 的确定性、无损性是核心优势。

与 fork、quarter-clone 的分工

如果只是想从某一点尝试不同路线而不丢掉原线程，应使用 Claude Code 原生 fork（/branch、claude -c --fork-session）；而 half-clone/quarter-clone 解决的是长度问题——会话太长、上下文告急时，裁剪掉早前内容换取可用空间。当"连一半都嫌多"时，用--quarter或/dx:quarter-clone保留最后四分之一。三者组合（fork 换思路 + half-clone 保空间）可以应对绝大多数长会话场景。

小结

half-clone 的本质是一台"确定性 JSONL 手术台"：按干净用户消息数计算裁剪点，用 UUID 重映射保持内部引用闭合，用 marker 消息接驳让claude -r可识别，再剥离 thinking 块、丢弃 session-config 尾行、缩放 token 计数以规避恢复时的已知错误。配合 Skill 的 5 步标准流程、check-context hook 的自动触发，以及 17 个隔离测试用例的保障，它成为长会话 token 治理中一个可靠、可复现、无损于近期工作的实用方案。后续深入阅读可继续查看 half-clone-conversation.sh、test-half-clone.sh、quarter-clone Skill、check-context.sh 与 README.md 的 Tip 21 部分。

• AI 技能
• 教程
• 开发工具