会话交接

会话交接功能允许你在不分叉的前提下，将活跃的 Kaiwu 会话从一台设备迁移到另一台设备。

它的核心承诺十分明确：

• Kaiwu 会话 ID 保持不变
• 会话的当前所有权设备发生变更
• 对话可在目标设备上继续进行

这与以下操作不同：

• 会话分叉与重放：会创建新的分支
• 附加到运行中的会话：在同一台设备的终端中重新打开会话
• 继续会话：说明会话记录的存储位置
• 使用其他 Agent 继续：在当前承载会话的设备上就地切换编程 Agent

从何处发起交接

你可以通过以下入口发起交接：

• 会话顶栏的操作菜单
• 会话详情页

打开对应操作，选择目标设备，确认交接选项后点击确认即可。

交接保留的内容

交接成功后：

• Kaiwu 会话 ID 保持不变
• 会话记录保留在原会话中
• 会话元数据仍然挂载在原会话下
• 目标设备成为当前所有者

对于受支持的提供商，提供商的运行时状态也会随会话一同迁移。目标设备可以直接顺着既有进度继续工作，无需重新发起对话。

交接不支持的操作

会话交接不会自动执行以下操作：

• 在目标设备上登录提供商 CLI
• 合并或覆盖目标工作区（除非你显式启用了工作区传输）
• 让原本不支持的提供商突然具备跨设备恢复能力

如果目标设备无法满足该提供商或运行时的依赖要求，交接将无法完成。

支持的提供商

会话交接能力取决于具体的提供商。

当前支持情况：

会话类型

会话交接支持面向用户的两种会话模式：

• Kaiwu 会话
• 直连会话

详见继续会话。

Kaiwu 会话

对于 Kaiwu 会话，交接会在保留当前 Kaiwu 托管会话的同时，将其活跃所有者迁移至另一台设备。

这是最纯粹的使用场景：

• Kaiwu 会话保持不变
• 所有权转交新设备
• 会话记录与会话 ID 原样保留

直连会话

对于直连会话，交接弹窗会额外提供一个目标模式选项。

你可以选择：

• 保持直连
• 转换为同步模式

如果你希望目标设备继续沿用提供商底层的会话机制，请选择“保持直连”。

如果你想脱离受单机限制的直连模式，改由 Kaiwu 托管后续会话，请选择“转换为同步模式”。

工作区传输

工作区传输是可选功能。

默认情况下，除非你手动开启传输，否则 Kaiwu 不会改动目标工作区。

开启后，交接弹窗允许你配置以下选项：

• 是否传输工作区
• 目标路径已存在时的处理方式
• 忽略文件的处理策略

冲突策略

当前支持的冲突处理选项：

• 创建同级副本
• 替换已有路径

当目标路径已存在时，Replace existing path 必须经过显式确认。

忽略文件

当前支持的忽略文件策略：

• 排除被忽略的文件
• 包含选中的被忽略文件

如果选择“包含选中的被忽略文件”，你可以指定包含规则匹配模式（Glob），例如：

• dist/**
• .env.local

默认安全路径检查

当源路径属于不安全目录时，Kaiwu 会拦截工作区传输，例如：

• 文件系统根目录
• 用户主目录
• 用户主目录简写（~）

遇到这些路径时，交接界面会强制关闭工作区传输，避免复制不安全或范围过大的工作区。

会话交接设置

你可以在此处配置默认的交接行为：

• 设置 -> 会话 -> 会话交接

可配置的默认项包括：

• 是否默认启用工作区传输
• 默认工作区冲突策略
• 默认忽略文件模式
• 忽略文件包含规则匹配模式（Glob）
• 直连会话交接的默认目标模式

即使配置了默认值，你仍可在每次发起交接时单独覆盖这些设置。

相关指引：

• 会话设置

已连接服务与交接

配置“已连接服务”通常是实现跨设备顺畅交接最轻松的方式。

原因在于：

• 凭据保存在你的 Kaiwu 账号中
• 兼容的后端可在另一台设备上复用该凭据
• 无需完全依赖目标设备的本地 CLI 登录状态

在以下场景之间迁移会话时，该功能尤其实用：

• 两台笔记本或台式机
• 宿主机与虚拟机
• 绑定在同一账号下的不同设备宿主

已连接服务并不能取代所有设备本地的认证要求；但只要后端支持，它就是保障跨设备连贯性的首选方案。

相关指引：

• 已连接服务

提供商认证与交接

设备本地的提供商认证依然至关重要。

如果某个提供商或后端依赖本地原生的 CLI 登录状态，目标设备也必须提前就绪。

因此，整体逻辑如下：

• 只要后端能利用 Kaiwu 托管的凭据生成认证状态，已连接服务就能发挥作用
• 对于依赖本地提供商 CLI 的工作流，提供商认证依然必不可少

相关指引：

• 提供商认证

交接期间的界面展示

发起交接后，Kaiwu 会弹出进度弹窗，按顺序执行以下操作：

• 准备目标设备
• 迁移会话状态
• 在目标设备上恢复会话
• 更新会话所有权

交接完成后：

• 该会话在 Kaiwu 中保持原位
• 活跃设备完成切换
• 原所有权设备释放控制权

常见工作流

将活跃会话从一台设备迁移到另一台设备

当你希望在另一台设备上顺畅继续当前对话时，请使用交接功能。

例如：

• 从笔记本电脑切换到台式机
• 从宿主机切换到虚拟机
• 在不同的专属 Kaiwu 宿主环境之间切换

保持直连会话的提供商底座并迁移

如果你仍想保留基于提供商的所有权模式，且该提供商支持直连交接，请选择“保持直连”。

将直连会话转换为 Kaiwu 会话

如果你最初使用的是提供商原生会话，但现在希望由 Kaiwu 来管理会话记录和后续的连贯性，请选择“转换为同步模式”。

迁移会话但不触碰目标工作区

保持工作区传输处于关闭状态。在以下情况下，这是最稳妥的默认选择：

• 目标设备上已经具备正确的文件
• 只需要保持会话连贯，无需拷贝文件
• 源路径范围过大或依赖特定机器环境

排错指南

无法选择目标设备

通常由以下原因之一导致：

• 目标设备处于离线状态
• 目标设备正是当前的所有者
• 该会话所用的提供商或后端不支持交接

工作区传输处于禁用状态

通常意味着：

• 你的默认配置关闭了工作区传输，或者
• Kaiwu 检测到了不安全的源路径，例如 ~ 或文件系统根目录

找不到交接操作入口

以下情况下该操作可能不可用：

• 对应提供商不支持交接
• 会话缺少恢复状态所需的提供商状态信息
• 当前使用的服务器或构建版本禁用了交接功能

相关指引

• 继续会话
• 会话设置
• 已连接服务
• 提供商认证
• 附加到运行中的会话
• 会话分叉与重放
• 使用其他 Agent 继续