ThinkRail：AI 智能体 IDE 五分钟快速上手指南，从本地跑通到提交首个 PR

ThinkRailAI 智能体 IDE 五分钟快速上手指南从本地跑通到提交首个 PR【免费下载链接】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多个 AI 智能体挤在一个目录里互相踩踏、diff 只能滚屏翻、会话一结束项目意图就蒸发——这三个坑正是 ThinkRail AI 智能体 IDE 要解决的。它把 pi coding agent 装进真正的 IDE 工作台用独立的 git worktree 隔离每个智能体让项目意图沉淀成活规格。想体验 agentic IDE或者想参与它的开源贡献这篇指南带你完整走一遍。一、为什么需要隔离的 AI 智能体 IDE智能体写代码的三个坑用命令行跑 AI 编码智能体跑着跑着总会撞上这些问题goal-and-requirements.md 把它们写成了产品要解决的核心矛盾并行智能体互相踩踏多个 agent 在同一个 working tree 里干活彼此冲突还撞上你自己的未提交编辑。ThinkRail 的解法是把每个工作区做成独立的git worktree——自己的分支、自己的目录主分支在你合并前保持干净。CLI 里审查 diff 太累读改动、在精确行上留言、再把反馈交还给 agent在终端里全是手工活。ThinkRail 给了 Monaco 编辑器、文件树实时 git 变更标记以及能锚定在文件和 diff 上、再以结构化上下文发回 chat 的审查评论。意图会蒸发上个会话里聊定的决策下个会话不记得甚至得出相反结论。ThinkRail 让意图住在代码旁边的一棵SPEC.md规格图里agent 用专用spec_*工具读、搜、维护它。二、三步跑起本地 ThinkRail 开发环境最小依赖三样版本要求见 CONTRIBUTING.mdBun 1.4.4——仓库锁定的包管理器兼运行时根 package.json 的packageManager字段写死Node.js ≥ 22.19——进程内pi引擎的硬性要求一个已认证的piprovider——真要驱动智能体干活时需要模型凭据。克隆并安装依赖git clone https://gitcode.com/GitHub_Trending/th/thinkrail cd thinkrail bun install然后一条命令同时拉起宿主和 Web 客户端bun run dev 启动后你会看到完整工作台左侧 Projects 面板列出已打开的 git 仓库中间是pi会话的流式输出和工具调用步骤右侧是 Specs 规格树和 Changes 改动列表中间编辑区还能自由分割。CtrlC会把宿主和客户端一起停掉。三、三个高频场景worktree 工作区、活规格、diff 审查场景一把并行任务切进 git worktree 工作区。操作打开一个 git 仓库作为 project从它切出 workspace。每个 workspace 都是一个独立git worktree各带分支和目录你可以同时挂多个并发pi会话互不干扰。你会看到顶栏实时显示当前分支相对origin和 PR 的状态publish、push、开 PR 都是一键操作——PR 描述可以直接由 agent 根据计划和提交草稿。跑完或闲置的工作区会自动沉到每个项目专属的 shelf 上你再碰它时立刻回来。场景二让 Specs 记住项目意图。操作从右侧边缘工具栏打开 Specs 工具agent 会在会话中通过spec_*工具搜索、导航并更新规格图。你会看到规格以树形呈现选中哪份就在编辑器里渲染哪份。下一个会话开始时之前聊定的设计决策还在树上——意图不再随会话消失。场景三审查并交付 agent 的改动。操作在 Files 树的 Changed 视图或 diff 里浏览 agent 的改动在精确行上锚定审查评论一键把这些评论作为结构化上下文发进某个 chat。共享 TODO 计划里每个完成的步骤还能单独提交、单独审查。你会看到diff 与 chat 并排评论变成 agent 能直接消化的上下文顶栏 Open PR 会通过你自己的gh推送分支并打开 PR全程不存任何令牌。四、三环架构骨架拆解一张表看懂宿主、线缆与 UI理解 ThinkRail 源码记住三个环就够了完整定义见 architecture.mdpi引擎进程内跑在宿主里UI 独立打包两者之间只有那根线缆——类型化、带版本号的协议。模块职责入口路径引擎宿主Bun.serveHTTPWS 宿主进程内运行pi会话管持久化与协议端点packages/server/SPEC.md线缆 The wire宿主与 UI 之间唯一的耦合类型 极小纯运行时packages/contracts/SPEC.mdUI 客户端React 19 Zustand Tailwind v4独立交付的移动端优先客户端apps/web/SPEC.md薄启动器apps/cli开浏览器、apps/desktop开原生窗口都内嵌同一个宿主库apps/cli/SPEC.md两条硬边界碰了会被自动检查拦下apps/web只能依赖contracts、locales、ui等展示层包永远不碰server——保证 UI 能在没有宿主的情况下独立交付浏览器打包代码永远不能 value-importpi只能从pi-ai/pi-agent-core根导入类型。边界不是口头约定scripts/check-module-boundaries.ts 等检查脚本在 pre-commit 和 CI 里守着模块依赖面。五、开 PR 前先过门禁检查命令与贡献清单快速门禁三条也是 husky pre-commit 钩子bun run lint # biome 代码检查 bun run typecheck # 全包 tsc 类型检查 bun run test # 单元测试涉及应用行为时还有对着真实 UI 的端到端套件。迭代时用聚焦或 last-failed 跑交接前完整跑一次bunx playwright install chromium # 一次性 bun run e2e -- e2e/changes.spec.ts # 聚焦单个 spec 迭代 bun run e2e -- --last-failed # 只重跑失败用例各运行模式、隔离与凭证细节都写在 e2e/SPEC.md。贡献清单Fork 仓库从main拉分支改了边界或行为先更新对应的SPEC.md——这个项目是 spec-first规格领先于代码再改代码和测试保持改动聚焦风格跟随周边代码与 AGENTS.md 的全仓约定跑通门禁后向main开 PR写清楚what改了什么与why为什么。六、新手避坑速查这些错法一犯就被门禁打回硬编码界面文案会被 lint 拒绝面向用户的文本必须是 packages/locales/en.json 里的 keyJSX 里写死文字过不去门禁想贡献翻译就从这份文件抄起。别用ts-ignore、as any把门禁变绿仓库明确把它当设计信号压制必须先征得显式批准。依赖版本必须精确锁死不允许^、~等浮动范围跨包依赖统一锁在根目录workspaces.catalogbun run check:deps会拒收。别从 web 代码伸手去 serverUI 面板只管展示与 store布局由 shell 负责跨模块导入只走index.ts桶文件。想改智能体技能/工作流先读 packages/pi-thinkrail-workflow/SPEC.md注意e2e:full会花真实 provider token别在迭代中途顺手跑全套。结语ThinkRail 把 AI 智能体装进隔离的 IDE 工作台worktree 管住边界Specs 留住意图线缆守住架构。最低门槛的动手建议bun run dev跑起来挑一个SPEC.md读十分钟再从一条 i18n 文案或一个边界测试开出你的第一个 PR。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考