ThinkRail AI 智能体 IDE 快速上手指南

ThinkRail AI 智能体 IDE 快速上手指南

【免费下载链接】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 是围绕 pi 智能体的 AI 智能体 IDE，专治智能体同目录踩踏、会话一关意图就丢。每个智能体拿到独立 worktree 副本，意图留在 SPEC.md。读完，你能跑起它并提交第一个 PR。

一条命令启动 ThinkRail：克隆、安装到亮屏

机器上缺什么？三样，缺一样都跑不起：

• Bun 1.4.4：仓库锁定的包管理器，版本写在根package.json的packageManager字段
• Node.js ≥ 22.19：进程内pi引擎的硬性要求
• 一个已认证的 pi provider：智能体干活要用的模型凭据

齐了就敲这四行：

git clone https://gitcode.com/GitHub_Trending/th/thinkrail cd thinkrail bun install bun run dev

怎么算成功？宿主和 Web 客户端会一起拉起，浏览器自动打开工作台，顶栏右侧出现Connected，Ctrl+C 两者同时退出。想换外壳也行：bun run desktop:dev打包并打开 Electrobun 桌面应用，bun run build:binary构建独立 CLI 二进制。

两点提醒：开发模式不启用应用内更新器，源码检出靠 Git 更新后重建即可；应用在磁盘上的状态（项目、工作区、worktree）统一放在~/.thinkrail。

跑起来之后怎么读架构：一张表看懂前后端分工

看完界面，怎么在脑子里给它建模？把它想成一家店：后台跑pi引擎、管会话和持久化；前台是你能看到的 React 界面；两者之间只传递一份带版本号的合同（类型化协议）；门口还有两个门房（启动器）负责开门，但不开口办事。

三条要点抓住核心：

1. 工作区即 git worktree：每个 project 是一个 git 仓库，每个 workspace 切出独立 worktree，等于给每个智能体单独开一份代码副本，各有自己的分支和目录，存在~/.thinkrail/worktrees下，并行干活互不踩踏。
2. 一个工作区可跑多个并发 pi 会话，各自有独立模型和实时 token/费用读数，运行中还能转向（steer）或排队后续指令。
3. Specs 是事实来源：项目里一棵 SPEC.md 规格树，智能体通过专用 spec_* 工具读写，意图不随会话蒸发。

这条边界是硬规则：apps/web只依赖contracts、locales、ui这类展示层包，永远不碰server，所以 UI 能在没有宿主的情况下独立交付。

布局也是分权的：面板本身不知道自己摆在哪，由 shell 统一排布；中心区可递归分割，侧边和底部按你保存的预设（Balanced、Focus、Review）落位，切换工作区不会乱。完整拓扑与决策清单见 architecture.md。

动代码前，先记住这几条贡献铁律 📌

第一次碰这个仓库，最怕翻车在哪？不在代码，在规矩。动手前过一遍这份清单：

• 规格领先代码：改动动了边界、契约或行为，先更新对应模块的 SPEC.md，再改代码和测试（见 CONTRIBUTING.md）
• 子模块只通过index.ts桶文件对外；兄弟模块跨包导入只走桶，不伸手进内部
• 模块公开面能配测试就配上，边界规则也留测试兜底
• 不用@ts-ignore、as any、biome-ignore把门禁变绿——把报错当设计信号（见 AGENTS.md）
• 风格跟随周边代码，不顺手重构无关代码

每个 package 和重要目录都有自己的 SPEC.md，写清它拥有什么、暴露什么、不许碰什么。先读你要改的那个模块的 SPEC.md，再写第一行代码。

提交 PR 前必过的门禁与端到端验证清单

改了代码，怎么证明自己没改坏？分两步：三道快速门禁 + 端到端套件。这些门禁同时也是 husky pre-commit 钩子，提交前会自动跑。

三条全绿才能往下走：

bun run lint # biome 代码检查 bun run typecheck # 全包 tsc 类型检查 bun run test # 单元测试（根工具 + 各 package）

涉及应用行为，还要过对着真实 UI 的端到端套件：

bunx playwright install chromium # 首次一次性 bun run e2e -- e2e/changes.spec.ts # 聚焦单个 spec 迭代 bun run e2e -- --last-failed # 只重跑失败用例 bun run e2e # 完整无智能体门禁，自动分片

节奏建议：迭代期跑聚焦或 last-failed，改一处验一处；交接前完整跑一次bun run e2e。涉及真实智能体行为的，再跑bun run e2e:full（需要 pi 认证，会消耗真实 token）。

然后按这五步提交：

1. Fork 仓库，从main拉分支
2. 改动保持聚焦，风格对齐周边代码与 AGENTS.md
3. 动了边界或行为，先更新对应 SPEC.md，再改代码和测试
4. 补上或更新测试，跑通上面的门禁
5. 向main开 PR，描述写清what（改了什么）和why（为什么）

提交信息和 PR 描述讲推理，不只讲操作。维护者会 review，可能建议你调整后再合并。

新手导航：想改什么先读哪个文件，外加三个高频坑 🗺️

不知道从哪下手？对着这张表找入口：

最容易翻车的三个全仓不变量：

• 界面文案必须走 i18n key：硬编码进 JSX 的文字会被 lint 直接拒绝，所有用户可见文字都得是packages/locales/en.json里的 key。
• 浏览器端不能 value-importpi：pi 只活在宿主进程里，前端只能从pi-ai/pi-agent-core的包根导入类型。
• 别把 worktree 和主目录搞混：每个 workspace 是独立 worktree，只有 Default 工作区指向项目文件夹本身，其余时间都让智能体在 worktree 里干活。

不用等读懂整个仓库才动手：敲一条bun run dev跑起来，从 packages/locales/en.json 挑一条文案改，再补一个测试，你的第一个 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