镜像空间

通过镜像空间隔离文件副本和执行环境，同时复用主空间的成员、任务和业务配置

镜像空间

镜像空间用于给同一个项目准备多个独立的文件副本和执行环境。它不是一个新的项目，而是主空间的执行副本：成员、任务、任务配置等项目身份仍由主空间统一管理；文件目录、Git 状态、执行模式和运行环境由每个空间独立维护。

典型使用场景：

给不同 Bot 准备独立代码目录，避免多个任务同时修改同一个工作区。
在云端 Sandbox 和本地 Local Agent 之间准备不同执行环境。
在执行高风险任务前创建一个独立副本，完成后再按需同步文件。

主空间与镜像空间

一个镜像组由一个主空间和多个镜像空间组成。

主空间：项目身份中心，承载成员权限、任务、Bot 绑定、共享知识库引用和默认入口。
镜像空间：执行副本，承载独立文件目录、Git 工作区、Sandbox 或 Local Agent 运行环境。

用户进入镜像空间时，看到的是同一个项目下的另一个工作副本。权限判断仍使用主空间成员权限，但文件、对话运行环境和执行日志使用当前镜像空间。

共享与独立

共享的数据

这些数据只维护一份，归主空间管理。用户从镜像空间访问时，系统会解析到主空间：

类型	说明
成员与权限	团队成员、部门权限、成员角色共享；镜像空间不维护单独成员列表。
任务数据	任务、评论、状态、变更历史共享；在镜像空间创建或更新任务，仍写入主空间任务数据。
任务配置	任务类型、优先级、标签、自定义字段、任务视图共享；镜像空间不能单独维护一套任务配置。
任务附件	附件写入主空间附件存储；从镜像空间上传任务附件时也归主空间。
共享知识库	共享知识库引用和授权共享；镜像空间不会复制共享知识库内容。
快捷命令与业务入口	项目级快捷命令、知识视图、业务入口等项目身份配置共享。
Bot 参与项目的关系	Bot 可绑定主空间或同组镜像空间，但任务归属和候选范围按主空间项目统一计算。

独立的数据

这些数据按主空间和每个镜像空间分别维护：

类型	说明
文件目录	每个空间有自己的工作区目录；文件增删改不会自动同步到其他空间。
Git 工作区	未提交改动、Git index、当前 checkout 状态等互相独立。
执行模式	镜像创建时选择云端模式或本地模式，创建后不能切换。
本地执行配置	`localAgentHostId`、`localPath` 只属于对应本地镜像空间。
Sandbox / Local Agent 运行态	会话、进程、执行日志、运行环境按实际执行空间隔离。
对话落点	对话可以落在主空间或某个镜像空间；文件上下文和 runtime 使用对话所在空间。
文件 watcher 与同步状态	文件监听、强制同步源/目标状态按空间独立。

创建镜像

在工作空间设置中打开「镜像空间」页签，点击「创建镜像」。

创建前需要满足：

主空间必须配置远程 Git 仓库和主分支。
创建者需要具备主空间管理权限。
本地模式需要可用的 Local Agent Host。

创建时需要填写：

名称：用于在列表和切换入口展示。
标识符：用于生成镜像空间 slug。
执行模式：云端模式或本地模式，创建后不可切换。
任务路由：可以禁止 Bot 任务自动路由到该镜像。

云端模式会从主空间 Git 仓库 clone 初始化文件目录。

本地模式需要选择 Local Agent Host 和本地目录，并可选择是否 clone：

执行 clone：系统会先清空选择的本地目录，再从主空间 Git 仓库 clone。
跳过 clone：系统只绑定该目录，不清空目录、不执行 clone，目录内容由用户自行准备。

初始化命令

如果仓库中存在 .knodo/settings.json，可以声明镜像 clone 后的初始化命令：

{
  "schemaVersion": 1,
  "replicaClone": {
    "initCommand": "bash .knodo/init.sh"
  }
}

初始化命令由项目用户维护，适合处理老项目 clone 后还需要安装依赖、拉取子仓库或准备环境的场景。执行前需要确认命令风险。

默认空间

镜像组可以设置默认聊天空间。

默认聊天空间用于控制从主空间入口创建新对话时优先进入哪个空间。

如果没有设置默认聊天空间，新对话仍进入主空间。从镜像空间页面进入对话时，对话使用当前镜像空间。修改默认聊天空间只影响新建对话，历史对话不会迁移。

对话规则

普通 Web 对话的落点规则：

从主空间进入，且设置了默认聊天空间：新对话进入默认聊天空间。
从主空间进入，未设置默认聊天空间：新对话进入主空间。
从镜像空间进入：新对话进入当前镜像空间。

对话所在空间决定文件上下文、Sandbox 或 Local Agent runtime。任务、共享知识库、快捷命令等项目配置仍使用主空间。

任务与 Bot 执行

任务始终归主空间统一管理。无论用户在主空间还是镜像空间创建、查看、更新任务，读写的都是同一份主空间任务数据。

Bot 执行任务时会区分两个空间：

源空间：任务所属主空间。
执行空间：实际运行 Bot、修改文件和产生日志的主空间或镜像空间。

执行空间选择规则：

用户显式选择执行空间时，使用用户选择的空间。
未显式选择时，系统会在同组可用镜像中选择。
如果没有可用镜像，回退到主空间。

同一个执行空间同一时间只能运行一个 Bot 任务，避免多个任务互相覆盖文件改动。普通对话仍可进入该空间。

开启 taskRoutingDisabled 后，该空间不会被 Bot 任务自动路由；已有任务不受影响。

文件强制同步

主空间和镜像空间支持手动强制文件一致同步。同步不会自动触发，必须由用户点击并确认风险。

支持方向：

主空间覆盖镜像。
镜像覆盖主空间。

同步范围：

除共享知识库相关路径外，同步全部目录和文件。
嵌套 Git 仓库、额外 clone 的仓库、未提交文件都会作为普通文件同步。
删除动作会传播到目标空间，使目标最终与源空间一致。

共享知识库处理规则：

不复制共享知识库内容。
不复制跨组织共享库代理内容。
不跟随共享知识库软链接目标。
如果存在共享知识库引用，只保留引用或按现有引用机制重建。

执行同步前，请确认目标空间没有需要保留的未提交改动或本地文件。

删除镜像

删除镜像空间只删除或归档该执行副本，不会删除主空间业务数据。

删除规则：

不能通过镜像删除主空间。
存在运行中的 Bot 任务或同步任务时不能删除。
删除会清理默认聊天空间指针。
删除不会删除主空间成员、任务、共享知识库引用等项目数据。
本地模式镜像删除时，默认只解除系统绑定，不删除用户机器上的 localPath。

使用建议

把主空间作为项目真实入口，维护成员、任务、配置和共享知识库。
给长期运行或高风险 Bot 准备独立镜像空间。
本地模式执行 clone 前确认目录可以被清空；不确定时选择跳过 clone。
在执行文件强制同步前，先检查目标空间是否有未提交改动。
如需从云端切换到本地，或从本地切换到云端，请新建镜像空间。