【免费下载链接】thinkrailVibe code with pi in a lightweight, real IDE that customises itself around the way you work — The Vibe You Need项目地址https://gitcode.com/GitHub_Trending/th/thinkrail点击查看免费下载本文以 ThinkRail 官方博客《ThinkRail Workspaces》为主线讲清一个核心问题在 IDE 里让 AI Agent 直接改代码时如何避免它动到你正在编辑的工作区。文章会覆盖隔离 workspace 的创建流程、目录结构与命名规则、背后的git worktree调用链、多任务并行策略、合并与开 PR 的收尾方式以及删除回收时的安全边界并结合仓库源码给出可验证的实现细节。起点项目文件夹与隔离 workspace 是两种不同的风险模型在 ThinkRail 中启动一个项目时你有两个选择直接工作在项目文件夹或者创建一个新的 workspace隔离工作区。直接工作在项目文件夹意味着所有改动会立刻作用于当前 git 分支。这条路最直接但也最不安全原因在原文中讲得很明确未保存的改动可能被 AI Agent 移除。Agent 在同一个工作目录里执行文件操作与命令你尚未提交、甚至尚未保存的内容与它共享同一个物理目录。已保存已提交的改动仍可能被覆盖只要 Agent 拥有执行某些 git 操作的权限。多 Agent 并行时会互相妨碍。即便你在项目文件夹里同时开多个 Agent它们仍然共享同一个工作区和同一个分支。workspace 正是同时针对这三个问题的解法。它把 Agent 的工作目录搬到一个独立的git worktree中配一条独立分支从而让你的检出和Agent 的检出在文件系统层面就是两份东西。维度项目文件夹Default workspace隔离 workspace工作目录项目根目录本身git 主工作树~/.thinkrail/worktrees/project-slug/branch分支当前检出的分支从你选定的基线切出的新分支改动影响范围立刻影响当前分支与你正在编辑的文件只存在于独立 worktree 与独立分支并行能力多 Agent 共享同一目录易冲突每个 workspace 独立目录可并发能否删除不能非可删除、非可改名可以删除时只回收 worktree适用场景快速试验、单人小改动让 Agent 承担完整任务、多任务并行关键规则在 packages/contracts/src/domain.ts 的Workspace类型中就有体现记录里同时存在branchgit 分支与worktreePath实际工作目录并用可选的kind: default | external标记两类用户自有的例外。创建隔离 workspaceStart building 的完整流程原文描述的入口是点击Start building按钮。在仓库实现中可以对应到两个层次入口卡片层Welcome 面板把两种模式做成可见的并列选择——Start building隔离 worktree与 Work in project folderDefault workspace见 apps/web/src/panels/SPEC.md。对话框层NewWorkspaceDialog用一个target: worktree | default的切换控件承载两种目标标签分别为 Isolated workspace 与 Project folder文案定义在 packages/locales/en.json。在新建窗口中你需要做三件事选择 workspace 的 git 分支。对话框中的BranchPicker会列出本地与远端分支并在你选中远端分支时在后台预取它git.prefetch从而把网络等待挪出创建的关键路径见 apps/web/src/panels/NewWorkspaceDialog.tsx。填写描述。这段描述承担双重职责既是人类可读的 workspace 名称也是发给 AI Agent 的初始 prompt。确认创建。创建成功后界面立刻为该 workspace 开一个新 chat 并启动 AgentAgent 会马上开始处理这个任务。原文特别提示Agent 之后可能会为了简洁而重命名 workspace。这一点在源码里是有明确设计的renameWorkspace会写入规范化的显示名并打上renamed: true而set_title这类自动命名只在目标尚未命名时生效因此任何手动名称始终优先第一个名字即为最终名字见 architecture.md。分支名与显示名是两套标识很多 worktree 工具会把目录名和分支名绑死ThinkRail 则显式解耦显示名name保留大小写与标点最长 60 字符由toDisplayName处理。分支名branch由显示名转成 ASCII kebab slug最长 60 字符并通过branchSlug清洗若清洗后为空则回退为workspace。自动命名当你没有提供名字时使用workspace-1、workspace-2…… 作为分支名与显示名。重名处理同时检查git ref 与 worktree 目录两处命中时追加-2、-3等后缀见 packages/server/src/workspaces/workspaces.ts。这一设计解决了原文没有展开、但在实际使用中很常见的两个坑归档后分支仍然存在以及改名后旧目录仍被占用。隔离的实现一次git worktree add背后的调用链原文给出的关键事实是ThinkRail 使用git worktree功能来创建和管理隔离环境更新后的代码位于~/.thinkrail下的独立 worktree 目录例如~/.thinkrail/worktrees/project-name/workspace-1。服务端实现集中在 packages/server/src/workspaces/workspaces.ts 的createWorkspace(projectId, name?, baseRef?)可以拆成六个阶段1解析基线与分支名。指定baseRef就用它否则读取仓库当前的rev-parse --abbrev-ref HEAD。任何进入 git 参数的 ref 都会先经过assertSafeRef校验防止来自不可信仓库的选项形状分支名被当作命令行参数。2远端引用缺失时的兜底 fetch。只有当基线是远端跟踪分支、且本地不存在该 ref 时才联网抓取并且以 ref 是否存在作为判定依据而不是 fetch 的退出码——裁剪过的 refspec 可以让 fetch 成功返回却不产生目标 ref。失败时抛出的错误区分两种情况Could not fetch base: git 的 stderr Could not fetch base: remote does not map it into refs/remotes — check remote.name.fetch3计算 worktree 路径。目录规则是dataDir()/worktrees/project.slug/branch精确对应原文的~/.thinkrail/worktrees/project-name/workspace-1。4执行 worktree 创建。实际命令形如git worktree add ~/.thinkrail/worktrees/project-slug/branch \ -b branch --no-track --end-of-options full-base-ref三个细节值得单独说明--no-track避免新分支把远端跟踪基线设成自己的 upstream。否则 workspace 终端里的git push/git pull会指向基线分支而不是你的新分支按仓库设计upstream 应由用户在首次推送时自己设置。完整 ref 名探针与worktree add使用同一个全名如refs/remotes/origin/main而不是origin/main这种简写防止本地恰好存在同名分支时被 git 二次消歧成错误对象。--end-of-options与--把 ref 与路径同选项分隔开属于全仓库统一的防御式调用风格。5写入记录并初始化目录。生成的Workspace记录包含id、projectId、name、branch、worktreePath、baseBranch、initialTerminalPending: true、lastActiveAt若用户提供了名字则追加renamed: true。随后调用ensureWorkspaceScratchDir最后持久化并发出created生命周期事件。6首个终端的持久握手。initialTerminalPending是一个预留标记host 幂等地为 workspace 预留一个确定性的终端标签页成功后调用completeInitialTerminalReservation清除标记。这样即使预留失败重启或后续创建流程也能补偿见 packages/server/src/host/initialTerminal.ts。数据目录可以被覆盖dataDir()的实现是resolve(process.env.THINKRAIL_DATA_DIR ?? join(homedir(), .thinkrail))见 packages/server/src/persistence/persistence.ts。也就是说默认所有托管 worktree 都在~/.thinkrail/worktrees下设置THINKRAIL_DATA_DIR可以把它整体搬走开发与端到端测试就依赖这一点做隔离该路径始终被解析为绝对路径——因为相对路径会在不同调用点相对不同 cwd 解析导致托管 worktree 落到两个地方。隔离带来的副作用worktree 内的.thinkrail/context新建的 worktree 里会多出一个目录路径约定来自 packages/shared/src/paths.ts.thinkrail/context/ # 临时文档与工作文件的存放处 .thinkrail/context/todos/ # 待办数据ensureWorkspaceScratchDir会创建这些目录并写入一个内容为*的.gitignore使整个目录对 git 零足迹——Agent 在这里放任务规格、草稿、PR 正文等临时文件既不会污染提交又能被 spec 相关工具扫描到。原文没有点名这个目录但它正是Agent 在隔离 workspace 内自由写文件却不影响提交的重要配套。实现里还有三处防御值得在做安全评估时留意见 packages/server/src/workspaces/workspaces.tsworkspace 根目录不存在时直接抛错不会把一个被外部删除的 worktree 悄悄复活成空的非 git 目录逐级用lstat检查路径分量拒绝符号链接避免恶意检出把写入重定向到工作区之外.gitignore以wx独占创建写入且仅在文件不存在时写——因为这条路径也可能落在用户自己的仓库里已有文件属于用户。同时推进多个任务为什么要从同一分支起多个 workspace原文的场景非常具体当一个 Agent 在处理复杂任务时你可以从同一分支再创建一个 workspace把另一个任务交给第二个 Agent。例如一个 Agent 实现不改变应用行为的改动另一个 Agent 更新项目规格文档——这两个任务互不干扰。能这样做的根本原因是每次createWorkspace都会拿到独立的目录 独立的分支目录不同所以文件写入不冲突Agent A 的npm install、构建产物、临时文件不会影响 Agent B分支不同所以提交历史不交叉git status、diff 统计、代码评审都按 workspace 维度计算因此不需要等第一个任务完成两者可以并发执行。配合静置货架settled shelf机制长时间不动的 workspace 会自动从活跃列表沉到每个项目的货架上当你重新进入时又会回来见 README.md。这让开很多 workspace 并行不会把左侧导航撑爆。需要强调的是并行是目录级隔离不是仓库级隔离。多个 worktree 共享同一份.git对象库与 ref 命名空间所以分支名冲突、同一分支被多处检出的限制依然由 git 本身决定——这也是uniqueBranch要在创建阶段就避开 ref 冲突的原因。收尾合并、推送与开 PR任务完成后改动需要回到父分支。原文给出了两条路径如果 workspace 是从主分支切出来的可以让 AI Agent 直接创建 Pull Request——there is a skill for that指的就是随包分发的shipping-a-pr工作流技能见 packages/pi-thinkrail-workflow/skills/shipping-a-pr/SKILL.md。该技能把 PR 生命周期拆成六个阶段并按提问类型路由到对应文档诉求阶段文档默认模式工作已完成创建 PRcreating.mdsnapshot让 PR 与基线同步 / 解决冲突syncing.mdsnapshot更新 PR 标题或描述body.mdsnapshot补充或刷新 PR 截图screenshots.mdsnapshot一次性汇报检查状态 / 合并状态checks.mdsnapshot监控 CI、定位并修复失败检查checks.mdwait处理评审意见review-comments.mdsnapshot它还有两条与 workspace 强相关的约定工作文件位置pr-body.md与pr-shots/都放在 workspace 内被 git 忽略的.thinkrail/context/下PR 正文始终通过--body-file传入而不是内联snapshot 与 wait 两种完成模式默认只取一次新鲜的检查与合并状态快照就停止只有明确要求等到绿或监控 CI才进入轮询模式避免一次普通推送把流程升级为无休止的等待。如果 workspace 是从特性分支切出来的可以让 Agent 把改动推送到该分支或者你自己在终端里执行。Workspace.baseBranch记录的是创建来源不会再变而 diff 到底和谁比较由独立的diffBase决定见 packages/server/src/git/diffScope.tsexport function diffBaseRef(ws: PickWorkspace, baseBranch | diffBase): string { return ws.diffBase ?? ws.baseBranch; }这个区分很关键把出处和比较基准合成一个字段会导致重新指向比较基准后界面上来自某分支的说明开始说谎。默认的 diff 采用 merge-base 语义所以基线分支上的新提交不会虚增你的改动行数workspace 列表里的/-徽标与 Changes 面板用的是同一套范围计算。删除与回收先摘记录再后台清理删除 workspace 并不是一次同步的rm -rf。从源码看它是快慢分离的两段式export function forgetWorkspace(id: string): Workspace | null { const all loadWorkspaces(); const ws all.find((w) w.id id); if (!ws) return null; if (ws.kind default) throw new Error(The Default workspace cannot be removed); saveWorkspaces(all.filter((w) w.id ! id)); observedActivityAt.delete(id); observedHeadSha.delete(id); emit({ kind: removed, projectId: ws.projectId, id: ws.id }); return ws; } export function reclaimWorktree(ws: Workspace): void { if (ws.kind default || ws.kind external) return; const project loadProjects().find((p) p.id ws.projectId); if (!project) return; if (resolve(ws.worktreePath) resolve(project.path)) return; const removed git(project.path, [worktree, remove, --force, ws.worktreePath]); if (!removed.ok) { rmSync(ws.worktreePath, { recursive: true, force: true }); git(project.path, [worktree, prune]); } }forgetWorkspace只删持久化记录因此从workspace.list里立刻消失UI 响应很快reclaimWorktree才是慢的那一半git worktree remove --force失败时退化为rmSyncgit worktree prune。它保留分支所以你的提交不会随 workspace 一起消失。host 侧的workspace.remove处理器把这条链路串起来先同步摘掉记录再依次清理 spec 索引、评审缓存、变更记录、轮次记录、文件监听和终端最后把archiveTeardown清理会话、落定变更产物、回收 worktree丢到后台执行见 packages/server/src/host/handlers.ts 与 #L614-L627。因为分支被保留、目录可能仍被占用创建时的分支去重必须同时考虑两者端到端测试专门覆盖了这个回归场景creates, removes, and re-creates worktree workspaces (no branch collision)见 e2e/workspaces.spec.ts。两类用户自有工作区Default 与已存在的 worktree原文的对比只提了项目文件夹和新 workspace实现上还有第三个入口附着attach一个已存在的 worktree。三者都由kind区分1托管 workspace无kind字段由createWorkspace创建位于数据目录下可改名、可删除、可回收。2Default workspacekind: default每个项目恰好一个worktreePath就是项目目录本身git 的主工作树。它由listWorkspaces惰性补齐返回值固定排在最前。两条强制约束写在服务端而不是仅靠 UI 隐藏forgetWorkspace对kind: default抛错——否则归档的rm -rf兜底会把用户的项目目录交给删除逻辑renameWorkspace对kind: default抛错——否则会执行git branch -m改掉用户真实分支。该记录还带renamed: true作为双保险让自动命名永远不会碰它。同时它的branch/baseBranch会按文件夹真相在列表时刷新所以你在终端里git switch之后侧栏与顶栏会收敛到新分支而不是停留在旧值。3外部 worktreekind: external用户在项目菜单中显式附着的既有 worktree记录在它原来的位置ThinkRail 只使用其 cwd从不创建、改名或回收它。候选列表由git worktree list --porcelain -z异步解析并过滤掉项目目录本身、prunable的注册项、以及已经被其它项目或 workspace 表示的路径。附着时的校验很严格路径必须确实是本项目注册的 worktree处于detached HEAD的 worktree 会被拒绝提示先建分支若该路径已被另一个 ThinkRail 项目占用则报错。相关实现见 packages/server/src/workspaces/workspaces.ts行为在 e2e/workspaces.spec.ts 中有两个对应测试opens and safely forgets an existing user-owned worktree 与 an attached worktree cannot also be opened as a project。前者在附着前后逐字节比对git status --porcelainv1 -z、当前分支、HEAD 与 worktree 注册表用来证明附着不会动你的检出包括已暂存、未暂存与未跟踪文件都被保留。实践建议与已知边界结合原文与实现可以给出几条可操作的建议让 Agent 在托管 workspace 里干重活。它带来的最大收益不是多一个分支而是你正在编辑的目录不会被它写。按任务而不是按文件切分并行 workspace。原文的例子一个改行为、一个改规格成立的前提是两者改动的文件集基本不重叠共享.git意味着它们仍会争用分支名与 ref。给 workspace 一个像样的描述。它同时是显示名与初始 prompt描述含糊会让 Agent 的首轮推理也含糊但也不用纠结最终命名Agent 之后可以改名。不要指望删除 workspace 会删掉分支。reclaimWorktree只移除 worktree分支保留要真正清理分支需要自己执行git branch -d。远端分支基线可能需要网络。首次从远端分支创建时若本地没有对应跟踪 ref会走一次兜底 fetch离线或远端无响应时会明确报错而不是静默切到别的提交。注意--no-track的语义。新 workspace 分支默认没有 upstream首次git push需要显式-u这是刻意设计而非缺陷。改动范围与基线要分开看。想知道这个 workspace 相对基线改了多少看diffBase默认等于创建时的baseBranch驱动的 diff 统计想知道它从哪儿来看不会被改写的baseBranch。延伸阅读从哪些文件继续深入创建、附着、改名、回收的完整契约packages/server/src/workspaces/SPEC.md创建工作区与 Default 补齐的实现packages/server/src/workspaces/workspaces.ts数据目录与持久化packages/server/src/persistence/persistence.tsWebSocket 方法入口与后台回收packages/server/src/host/handlers.ts新建对话框与分支预取apps/web/src/panels/NewWorkspaceDialog.tsx既有 worktree 附着对话框apps/web/src/panels/ExistingWorktreeDialog.tsx架构决策Workspaces are git worktreesarchitecture.mddiff 范围与基线解析packages/server/src/git/diffScope.ts端到端行为验证e2e/workspaces.spec.ts开 PR 的工作流技能packages/pi-thinkrail-workflow/skills/shipping-a-pr/SKILL.md如果你只想记住一句话ThinkRail 的 workspace 不是另一个窗口而是一次真实的git worktree add——独立目录、独立分支、独立 diff改动只有在你明确要求时才回到父分支。理解了这一点隔离、并行与收尾的每个行为都能在源码里找到对应的那一行。赞分享【免费下载链接】thinkrailVibe code with pi in a lightweight, real IDE that customises itself around the way you work — The Vibe You Need项目地址https://gitcode.com/GitHub_Trending/th/thinkrail点击查看免费下载相关推荐ThinkRail 工作区隔离实战git worktree 让多个 AI Agent 并行不冲突ThinkRail 工作区隔离实战git worktree 让多个 AI Agent 并行不冲突 ThinkRail 是一款围绕 pi 编码 Agent 打造OpenCrabs 多 Agent 编排实战用 spawn_agent 并行分发任务git worktree 隔离原理一次讲清OpenCrabs 多 Agent 编排实战用 spawn_agent 并行分发任务git worktree 隔离原理一次讲清 OpenCrabs 是一个ThinkRail workspaces 模块深度解析用 git worktree 构建可隔离、可归档的开发锚点ThinkRail workspaces 模块深度解析用 git worktree 构建可隔离、可归档的开发锚点 在 ThinkRail 中工作区wor上一篇从 PyTorch 迁移到 Apache MXNetGluon API 逐项对照实战指南下一篇Egg 框架 Cluster Client 深入解析基于 Leader/Follower 模型的多进程客户端封装实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考