用途 handoff 是 codemap 中的多智能体交接功能,目标是在不同 AI 编程代理之间传递工作上下文,避免换代理或新开会话时重复梳理项目状态。适用于 Claude、Codex、Cursor 等代理之间的切换。
主要能力 交接产物分为几层:Prefix 为稳定上下文,包括配置的项目文件数量、hub 摘要,变化较少;Delta 为动态信息,包括改动文件、风险文件、最近编辑事件和后续步骤;此外包含确定性哈希,用于跨代理的缓存校验。
使用方式 构建交接: codemap handoff . 生成并保存完整产物; codemap handoff --json . 输出机器可读格式供其他工具使用; codemap handoff --prefix . 仅生成稳定上下文(hub、配置的文件数量); codemap handoff --delta . 仅生成近期工作(改动文件、风险、事件)。
消费交接: codemap handoff --latest . 读取最近保存的产物; codemap handoff --detail file.go . 针对单个文件懒加载完整上下文。 基于工具的消费可通过 MCP 工具 get_handoff 获得相同能力。前缀文件数量与基于大小的交接预算会遵循当前 .codemap/config.json 的过滤配置,即使 watch 状态跟踪的工作集更广。
适用场景 从 Claude 切换到 Codex(或反向);在同一分支上开启新的 Claude 会话;上下文窗口接近满时压缩并恢复;把工作交给队友的 AI 会话。
产物与限制 产物写入每用户状态目录,不写入仓库;codemap doctor 会在 state dir 行打印其路径。文件包括 handoff.latest.json(完整产物,全部层)、handoff.prefix.json(稳定前缀快照)、handoff.delta.json(动态增量快照)、handoff.metrics.log(仅追加的指标流)。