简介

ThinkRail 是 JetBrains 开源（Apache-2.0）的 agentic IDE，官网一句话定位是 “the agentic IDE that gets better every time you use it”。它自己不实现 agent，而是把 pi 编码 agent 以库的形式跑在自己进程里，外面包一层真正的 IDE：Monaco 编辑器、文件树、真实 PTY 终端、实时 git diff。它最核心的两个主张是 —— 一个 workspace 就是一个 git worktree（独立分支、独立目录、独立终端和会话，agent 并行干活也不脏你的 main），以及 spec 是唯一事实来源（SPEC.md 图谱放在代码旁边，agent 用专门的工具去读、搜、维护它，意图不会随会话结束而蒸发）。

截至 2026-11-04 我核对官方数据时的状态：仓库 JetBrains/thinkrail 7.5k+ star，最新 stable 是 v0.3.1（2026-11-01 发布），nightly 已经走到 v0.4.0-nightly.4（2026-11-03），内嵌的 pi 引擎固定在 1.5.0。官网顶部的 Docs 目前还是 Coming soon，thinkrail.ai/docs 返回 404 —— 也就是说现阶段唯一可靠的文档是 README、仓库里那些 SPEC.md 和官方博客，本文也完全依据这些一手材料写的。

核心特点与优势：

• 隔离 workspace： 每个工作区是真实的 git worktree，agent 的烂摊子留在自己分支上；PR 被合并/关闭，或者一周没动，它就自动“上架”（Settled shelf），你再进去干活又自动回来。
• agent 旁边还能干活： Monaco 标签页、带 git 标记的文件树、Changes 实时 diff、作用域到当前 worktree 的终端；还能一键把当前 worktree 丢给你本机装好的 IDE 打开。
• 一个输入框找一切： Ctrl/Cmd+K（或双击 Shift）打开命令面板，跨项目搜会话/workspace/项目，执行命令并显示快捷键，直达设置项；什么都不输时列出正在等你的会话。
• spec-first： 内嵌 pi-spec-graph 扩展给 agent 提供 7 个 spec_* 工具，Specs 面板把图谱渲染成树。
• 复用你已有的 pi 资产： 读你的 ~/.pi/agent 配置、provider、模型和历史会话；你为 Claude / Codex / Copilot / Gemini 准备的 Agent Skills 也原地识别。
• 模型自带： JetBrains AI 登录，或走 pi 自己的 auth 接任意 provider，还能连公司网关 / 本地 Ollama、vLLM、LM Studio 这类 OpenAI 兼容服务。ThinkRail 自己没有账号体系。
• 两种形态： 原生桌面 App，或 thinkrail 命令行 —— 后者把同一套 UI 开在浏览器里，可以远程连主机。
• 中文界面： Settings → Language 内置简体中文，另外还有英/日/俄/西。

需要提前知道的（官方自己就写了）：

• 它是 0.x 的 JetBrains InnovationHub 孵化项目，官方博客讲界面时专门加了一句“如果你几个月后读这篇文章，你的体验可能已经不一样了”。
• 官方文档站还没上线，学习材料只有 README + 博客 + 仓库 SPEC。
• 它只是隔离，不是沙箱：agent 在你本机进程里跑真实 shell，而 pi 明确写着它没有内建权限系统，容器 / microVM 要自己配（详见文末“局限”一节）。
• 钱是模型的钱：界面头部实时显示 token 和成本，一个很小的问答 turn 官方示例是 5s · 25.9k tok · $0.17。
• CLI 是单文件二进制，体积很大（Windows 的 thinkrail-windows-x64.exe 241 MB，macOS ARM 217 MB），因为把运行时、UI、扩展全打进去了；桌面安装包反而只有 55–71 MB。
• 官方给的渠道只有 GitHub Releases 和两个安装脚本，README 与官网都没有提到 winget / Scoop / brew，我在 winget 仓库里也没搜到收录（这条时效性强，装之前再以 releases 页确认一次）。

维度	ThinkRail	浏览器 + 裸 pi	Cursor / Claude Code
形态	桌面 App + 浏览器 UI（同一套）	终端起宿主，浏览器连	桌面 IDE / 终端 CLI
引擎	pi（in-process，可换 provider）	pi	内置或绑定特定 agent
隔离	每 workspace 一个 git worktree	靠分支 / 自己开 worktree	靠分支 / 手动 worktree
项目知识	spec 图谱 + spec_* 工具	skills + 你自己的约定	规则文件 / CLAUDE.md
账号	无，只有 JetBrains AI 或你自己的 key	取决于 pi 的 provider	有
开源	Apache-2.0	MIT	未开源
编辑内核	Monaco	无（终端）	VS Code 系

它到底是什么：ThinkRail 和 pi 的分工

这段是理解所有命令含义的前提。官方 README 的 “Under the hood” 把架构说成三环：

• 引擎宿主（Engine host） —— packages/server（+ packages/shared）：一个 Bun.serve 的 HTTP+WS 宿主，每个聊天在进程内跑一个 pi 会话，由 apps/cli 或 apps/desktop 启动。
• 线（The wire） —— packages/contracts：宿主和 UI 之间有类型、有版本号的协议。
• UI 客户端 —— apps/web：React 19 + Zustand + Tailwind v4，独立发布，只依赖 contracts，拨号连任意宿主。

所以职责边界很清楚：pi 拥有模型、skills、上下文压缩（compaction）、成本统计、会话状态；ThinkRail 拥有 workspace、编辑器、传输线。README 里那句 “它从不在你背后拼 prompt” 就是这个意思 —— 你在 UI 里看到的会话，和 pi CLI 里的会话是同一套 transcript。

桌面 App 和 CLI 的区别只在“怎么开窗”：CLI 把宿主开在本机然后叫浏览器打开 http://localhost:24242，桌面 App 用一个原生 webview 开同一个宿主（打包用的是 Electrobun），生命周期完全一样。它们都用同一个 bootHost()，应用状态都存在 ~/.thinkrail。

顺带说明 pi 这边：@earendil-works/pi-coding-agent 是 MIT 协议的独立 CLI（pi 命令），ThinkRail 把它当库嵌进自己进程，不需要你另外安装 pi，也不需要 PATH 上有 pi（官方的二进制烟测明确要求在“PATH 上没有 pi 可执行文件”的环境下跑通）。但如果本机装过 pi，两边会共用 ~/.pi 隐藏目录，provider 列表、模型、历史会话都能带过去 —— 官方原话是“你之前在 pi 原生 CLI 里干活，可以切到 ThinkRail 而不丢任何工作”，反过来也一样。

下载

所有产物都在 https://github.com/JetBrains/thinkrail/releases，每次发布同时提供 stable / nightly 两条 channel 和 SHA256SUMS 校验文件。官网那个 “Download” 按钮走的是 releases/latest/download/...，也就是永远指向最新 stable。

用途	资产名	平台	v0.3.1 实测大小
桌面 App	thinkrail-desktop-darwin-arm64.dmg	macOS 14+ Apple Silicon	66.6 MB
桌面 App	thinkrail-desktop-darwin-x64.dmg	macOS 14+ Intel	71.4 MB
桌面 App	thinkrail-desktop-windows-x64.zip	Windows x64	55.1 MB
桌面 App	thinkrail-desktop-linux-x64.tar.gz	Linux x64	57.0 MB
桌面 App	thinkrail-desktop-linux-arm64.tar.gz	Linux ARM64	55.4 MB
CLI 单文件	thinkrail-darwin-arm64 / -darwin-x64	macOS	217.6 / 226.1 MB
CLI 单文件	thinkrail-windows-x64.exe	Windows x64	241.2 MB
CLI 单文件	thinkrail-linux-x64 / -linux-arm64	Linux	236.2 MB
校验	SHA256SUMS	全部	极小

nightly 还额外发 canary-<平台>-ThinkRail-<版本>.tar.zst 和同名的 *-update.json（更新器读的清单），那是自动更新流程用的归档，手动下载不用碰，普通用户只需要上面那 10 个。

签名情况官方写得很直白，选平台前要知道：

平台	桌面	CLI
macOS Apple Silicon / Intel	DMG	已签名，但尚未公证（notarized）
Windows x64	已签名的 setup 可执行文件 + App 内每个 exe/DLL	已签名 .exe
Linux x64 / ARM64	setup tarball，未签名	未签名

macOS 上老的 DMG 和你本地自己构建的包可能被 Gatekeeper 拦；Windows on ARM 目前没有原生构建，走的是 x64 模拟。

安装

安装分两条独立路线，装哪个都行，也可以都装（它们共享 ~/.thinkrail 状态）。

前置要求

两条路线都要：

1. git 在 PATH 上 —— README 原话是 thinkrail 需要 PATH 上有 git 和一个有凭据的 model provider；workspace 就是用 git worktree 建的，没有 git 直接开不了工。
2. 一个模型 provider —— 要么 JetBrains AI 账号，要么你自己的 API key / 订阅；不需要额外装 pi。

路线 A：桌面 App（推荐给不想开终端的人）

1. 下载对应平台的 thinkrail-desktop-* 资产，顺手校验一下（把文件名换成你下到的那个）：

   powershell
   # Windows PowerShell：算本地哈希，再和官方那一行对
   Get-FileHash -Algorithm SHA256 .\thinkrail-desktop-windows-x64.zip
   Select-String thinkrail-desktop-windows-x64.zip .\SHA256SUMS
   

   bash
   # macOS
   shasum -a 256 thinkrail-desktop-darwin-arm64.dmg
   grep darwin-arm64.dmg SHA256SUMS
   
   # Linux：SHA256SUMS 里列了整套资产，只校验你手上有的那些
   sha256sum -c --ignore-missing SHA256SUMS
   

   注意别直接 sha256sum -c SHA256SUMS：那个清单包含本次发布的全部资产，没下全的文件会报 MISSED 让结果看起来像失败。

2. macOS：双击 DMG，把 ThinkRail 拖进 Applications。

3. Windows：解压整个 ZIP，然后在原地运行里面的 setup 可执行文件 —— 官方强调不能把 setup 单独拷出来，它要和旁边的 payload 待在一起。

4. Linux：解开 tarball，运行里面的 installer；桌面构建需要 glibc 2.38+ 加 GTK 3、WebKitGTK 4.1、Ayatana AppIndicator 3、librsvg 2，Ubuntu 24.04 或更新版本先补依赖：

   bash
   sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2
   

装好后的自动更新在 Settings → Updates：Download → Preparing update → Install & Restart，在你点 Install & Restart 之前什么都不会落地；重启后它会告诉你更新有没有成功，失败会说明原因并提供重试。注意官方留了一个坑：更新器只在安装包带着合法的 HTTPS feed 身份时才出现，早于这个身份的安装需要先手动重装一次。

路线 B：CLI（thinkrail 命令，开浏览器 UI）

macOS / Linux，以及 Windows 上的 Git Bash / WSL：

bash
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash

Windows PowerShell：

powershell
irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex

Windows CMD：

cmd
powershell -c "irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex"

安装脚本做的事：探测平台 → 从 GitHub Releases 拉对应单文件二进制 → 校验 SHA-256 → 放到 <prefix>/bin/ → 把目录写进 PATH。默认 prefix 是 ~/.local（Windows 是 %USERPROFILE%\.local），也就是最终得到 ~/.local/bin/thinkrail 或 %USERPROFILE%\.local\bin\thinkrail.exe。

验证：

bash
thinkrail --version   # 打印内置的版本号
thinkrail --help      # 打印完整用法

如果 --version 正常但直接敲 thinkrail 报 command not found，是 PATH 还没进当前会话：脚本改的是 shell rc 文件（Windows 改的是注册表里的用户 PATH），必须新开一个终端（Windows 有时要重开整个资源管理器会话甚至重新登录）才生效，这不是安装失败。

安装脚本的可选项

install.sh 的参数要写在 -s -- 后面：

bash
# nightly 通道
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly

# 钉住某个 stable 版本（钉的版本必须属于所选 channel）
curl -fsSL .../install.sh | bash -s -- --channel stable --version 0.1.2

# 钉一个 nightly 版本
curl -fsSL .../install.sh | bash -s -- --channel nightly --version 0.2.0-nightly.10

# 装到别处，且不动我的 rc 文件
curl -fsSL .../install.sh | bash -s -- --prefix ~/tools --no-modify-path

install.ps1 用 irm … | iex 管道执行时传不了参数，所以选项走环境变量；把脚本存到本地再跑就能直接用 -Channel / -Version / -Prefix / -NoModifyPath：

powershell
$env:THINKRAIL_CHANNEL='nightly'; irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex

cmd
set "THINKRAIL_CHANNEL=stable" && set "THINKRAIL_VERSION=0.1.2" && powershell -c "irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex"

手动安装（不想跑别人的脚本）

从 releases 页下二进制 + SHA256SUMS 自己校验、自己放。要让自更新生效，必须把它重命名成 thinkrail（Windows 是 thinkrail.exe）并放到 <prefix>/bin/thinkrail[.exe]；保持发布时的原始文件名（比如 thinkrail-linux-x64）或放在别处的，官方明确说是“必须手动替换，或者用脚本重装”，thinkrail update 会拒绝并给你手动指引。

第一次启动：接上模型

thinkrail 裸跑（或点桌面图标）会打开浏览器 UI。首次运行向导带你做两件事：接 provider、选项目。也可以先点右上角齿轮进 Settings → Providers 配好再选项目。

能接的东西（官方 README 列的）：

• JetBrains AI —— 在 App 里直接登录。
• 任意 provider —— 走 pi 自己的 auth（API key、订阅、环境变量 key 都算，模型选择器第二行会用图标区分：钥匙 = API key、∞ = 订阅、{ } = 环境变量 key、JCP 标签 = JetBrains AI 代理），并按 token 计价时显示 $in / $out per M。
• 自己的模型服务器 —— Settings → Providers → Custom servers，任何 OpenAI 兼容服务都行：LiteLLM、sglang、vLLM、Ollama、LM Studio、llama.cpp。Find models 会列出服务端提供的模型和它上报的上下文与能力；这个服务器会被写进 pi 的 models.json，所以它的模型在聊天选择器和 pi CLI 里同时出现。

provider 凭据、模型目录都在 pi 那边（~/.pi/agent）。想换一份配置（比如个人用的 ~/.pi/agent-personal）或给 agent/终端/MCP 传额外环境变量，在 Settings → Environment 里设，下次启动生效；启动时用命令行临时给的环境变量（PI_CODING_AGENT_DIR=… thinkrail）优先级更高。

没有现成仓库也没关系：Start a new project 会在 ~/thinkrail 下建一个空 git 仓库；Add project → Clone repository… 输入 Git URL 就能克隆并打开，可以选父目录和文件夹名、可以限制 history depth、可以中途取消，已存在的目标目录绝不会被覆盖。GitHub 之类的站点复用你本机已有的 git 凭据和 SSH key。

使用：项目 → workspace → 会话

官方主推的工作法（也是它跟别的 agent IDE 最不一样的地方）：

text
~/code/my-repo                       ← project（任何本地 git 仓库）
└─ ~/.thinkrail/worktrees/
   ├─ workspace-1   ⎇ feature/auth      agent A 在写
   ├─ workspace-2   ⎇ fix/flaky-test    agent B 在修
   └─ workspace-3   ⎇ spike/ideas       你自己玩

1. 打开项目：选一个本地 git 仓库。
2. 决定在哪儿干活：直接在项目文件夹里干活是明示有风险的官方选项 —— 官方博客原话是所有改动立刻打到当前分支，未保存的改动可能被 agent 抹掉，多个 agent 会互相踩。正经用法是点 Start building / New workspace，选基分支 + 写描述；这个描述同时是 workspace 的人类可读名字和给 agent 的初始 prompt（官方提醒 agent 之后可能为了简洁把名字改掉）。
3. 干活：workspace 目录出现在 ~/.thinkrail/worktrees/<project-name>/workspace-1。此时你用别的 IDE 打开项目原始目录，看到的仍是改动前的版本 —— 这就是隔离的效果。
4. 并行：同一个基分支可以再切第二个 workspace 给另一个任务，两边互不阻塞，不用等。
5. review：Changes 面板看整个分支或最后一个 turn 的 diff（0.2.0 起叫 “Review turn”），可以在文件和 diff 上留锚定的 review comment，把它们作为结构化上下文丢回给聊天。
6. 收口：顶部状态栏显示当前分支相对 origin 和它的 PR 状态，下一步一键可达：publish / push / 从 plan、commits、PR 模板或 agent 写的草稿生成 PR 描述。PR 打开后能看到 CI 检查和 review 结论，能 mark ready、把失败的检查或分叉的分支丢给 agent 修、按仓库上次用的方式合并、reopen、删远端分支（这些依赖本机的 gh，Settings → Integrations 里检查它是否已登录）。
7. 不用管清理：PR 合并或关闭、或者一周没动，workspace 自动上 Settled shelf；再进去干活就自动回来（超时时长在 Settings → Workspaces 调）。

界面 16 个区域

官方 10-28 的 GUI 导览文里逐个截图介绍了这些位置，对照着找不难：

• 聊天区：① 聊天标签（改过文件的 turn 结尾有 Review turn 按钮）② 只读文件标签 ③ 聊天历史弹窗 ④ “在此组新开终端” ⑤ token 用量条（输入/输出/缓存读写/成本/上下文占用）⑥ Resources 弹窗（后台命令、子 agent、本会话的 MCP 服务器）⑦ Skills 弹窗（按会话开关，磁盘变了能 Reload）⑧ 模型选择器（含 reasoning effort 滑块）。
• 工作区：⑨ 终端面板 ⑩ Projects 面板（含 Settled shelf）⑪ 顶栏（项目/ workspace / 分支 / 远端 / PR）⑫ Specs 面板 ⑬ Files 面板（All / Changed 两个视图）⑭ Changes 面板 ⑮ Review 面板 ⑯ TODO 列表 + 完整 Plan 页。
• 设置：Models、Providers、MCP servers、Prompt templates、Environment、Chat、Appearance、Language、Layout（Balanced / Focus / Review 三种预设）、Terminal、Workspaces、Integrations、Extensions、Notifications、Privacy、Feedback。

快捷键

Mod 指 macOS 的 ⌘、其他平台的 Ctrl。以下是从官方命令契约和快捷键实现里核对出来的：

键	作用	说明
Mod+K	打开命令面板	也可双击 Shift；空输入时列出等你的会话
Mod+N	新建 workspace	在浏览器里跑时显示为 Mod+Alt+N（避开浏览器占用）
Mod+B	切换左侧栏	Projects / 工具轨
Mod+J	切换右侧栏	需要已激活 workspace
Mod+Shift+J	切换底部面板	终端区
Ctrl+R	搜索聊天历史	写死是 Ctrl，macOS 上也不是 ⌘
Mod+,	打开设置	原生菜单里的项
Ctrl+W / Ctrl+F4	关闭标签	桌面端；终端获得焦点时改用 Ctrl+F4
Ctrl+Q	退出	Linux 桌面
输入框内	@ 引用文件、/ 触发命令、Enter 发送	官方输入框占位符原文

主题、扩展、MCP 服务器的开关不能在命令面板里直接翻 —— 面板只会帮你打开对应的设置页。

各个命令的含义

thinkrail 的完整用法

下面这段是 thinkrail --help 打印的原文（apps/cli/src/args.ts 里的 USAGE 常量，我按官方源码逐字核对）：

text
Usage: thinkrail [options] [project-dir]
       thinkrail update [--channel stable|nightly] [--version X.Y.Z|X.Y.Z-nightly.N|latest]
       thinkrail uninstall [--remove-data|--keep-data] [-y]

Boots the ThinkRail engine host in-process and opens the browser to the app.
The `update` subcommand re-downloads + installs the latest build for your channel;
`uninstall` removes ThinkRail from this machine (your ~/.thinkrail app state is kept
unless you ask for it to go). Both take `--help`.

Options:
  --port <n>     Listen port (default 24242; falls back to a free port if taken).
  --host <h>     Bind host (default localhost).
  --no-open      Don't open the browser (e.g. headless / remote host).
  --no-analytics Disable additional usage analytics this run.
                 The saved sharing preference lives in Settings → Privacy.
  --verbose      Debug-level logging (terminal + the rotated log files under
                 ~/.thinkrail/logs).
  -v, --version  Print the version and exit.
  -h, --help     Show this help.

Arguments:
  project-dir    A git repo to open as a project on launch (optional).

Env:
  THINKRAIL_PORT / THINKRAIL_HOST   Defaults for --port / --host.
  THINKRAIL_STATIC_DIR                 Override the built web app served by the host.
  THINKRAIL_NO_ANALYTICS               Same as --no-analytics (any non-empty value; read by the host).
  THINKRAIL_LOG_LEVEL                  Log level: debug|info|warn|error (default info; read by the host).

逐条解释：

命令 / 参数	含义与注意点
thinkrail	在当前进程内启动引擎宿主，解析一个可用端口，然后打开浏览器。没给 project-dir 就进欢迎页让你选项目。
thinkrail ~/code/my-repo	唯一的位置参数：启动时把这个 git 仓库作为项目打开（best-effort，路径不合法不会让启动失败）。给第二个位置参数会直接报 Unexpected argument。
--port <n>	监听端口，默认 24242。被占用时不是报错而是向上扫描第一个空闲端口（Bun 的 Bun.serve 不会把 EADDRINUSE 暴露出来，官方是靠探测找的），最终以实际解析到的端口开浏览器。只接受 0–65535 的整数，否则 Invalid --port。
--host <h>	绑定地址，默认 localhost。改成对外地址 + --no-open 就能“本机跑宿主、别的机器用浏览器连”，官方把浏览器称作 first-class client 而不是退路。
--no-open	不自动开浏览器（headless / 远程宿主场景）。同时会关掉一次性安装归因，不消耗那次机会。
--no-analytics	只关掉本次运行的“额外使用数据”分享，基础事件仍然上报 —— 官方 help 文案特意这么写，不承诺零遥测。持久开关在 Settings → Privacy。
--verbose	debug 级日志，同时打到终端和 ~/.thinkrail/logs 下的滚动日志文件。
-v / --version	打印构建时烧进去的版本号并退出。
-h / --help	打印上面的用法并退出。
update	子命令，见下一节。
uninstall	子命令，见下一节。
未知选项	以 - 开头又不在上面的表里的一律 Unknown option，不会静默忽略。

两个子命令是位置参数第一位才成立的（args.ts 里的 parseSubcommand 只认 ["update","uninstall"]），它们在解析启动参数之前就被拦截，因此不会启动宿主 —— 官方特意解释过：卸载如果先启动宿主，会把临时资产缓存目录重新创建出来。所以 thinkrail update --port 1 这种写法没有意义。

thinkrail update

bash
thinkrail update                                  # 按当前安装通道升到最新
thinkrail update --channel nightly
thinkrail update --channel stable --version 0.1.2

它不是“自己下载自己”，而是重新调用官方的安装脚本（macOS/Linux 用 install.sh，Windows 用 install.ps1），把下载 → 校验 → 替换 → PATH 的逻辑收敛在安装脚本这一个地方。要点：

• 通道/前缀的判断顺序：显式 --channel > 本次安装的元数据 > 二进制里烧进去的通道。安装元数据在 ~/.config/thinkrail/install.json。
• 只认自己那套 <prefix>/bin/thinkrail[.exe] 布局；手动乱放的文件会拒绝自更新并打印手动指引。
• Windows 上替换正在运行的 exe 靠的是“改名让位”（Windows 不许删除正在运行的镜像，但允许改名），旧的 thinkrail.exe.<随机>.old 下次安装时清扫。
• 更新器还会周期性提醒：编译版二进制在宿主就绪后立刻查一次、之后每 6 小时查一次（stable 读 releases/latest，nightly 从 releases?per_page=20 里挑第一个 vX.Y.Z-nightly.N），只有严格更新才在 Settings → Updates 里给一个 Run Update。点它等于异步跑本机的 thinkrail update，浏览器不能挑命令/路径/通道/版本/URL；成功也要你手动重启宿主，不会打断你正在跑的活。同一次运行里成功执行后会锁定，不会连着再装第二个版本。

thinkrail uninstall

bash
thinkrail uninstall              # 交互：问你要不要删数据，再最终确认
thinkrail uninstall -y           # 两个问题都跳过
thinkrail uninstall --remove-data  # 连 ~/.thinkrail 一起删
thinkrail uninstall --keep-data    # 明确保留数据

它删的是：可执行文件、安装脚本自己加的那条 PATH、install.json、二进制的临时缓存目录。默认保留 ~/.thinkrail 应用状态 —— 因为里面装着你所有 workspace 的 git worktree 和其中未提交的活儿。~/.pi 永远不碰，官方的说法是“那不是我们的”。另外几条实现细节挺实在：

• Unix 上它往 rc 文件里写的是自识别区块（# >>> thinkrail PATH >>> … # <<< thinkrail PATH <<<），卸载只删这个区块；如果区块没有结束标记，它宁可不动也不截断文件。fish 的 conf.d 文件如果只有这一段才删整个文件。
• Windows 上注册表里的 PATH 条目没有任何标记，所以安装时会记下“这条到底是不是我加的”（path_entry_added），只有确认是自己加的才删；用 -NoModifyPath 装的、装之前就已经存在的、Git Bash 里跑 install.sh 装的，都不会被误删，它反而告诉你该去哪个目录检查。
• 没有 TTY 又没有 --yes 时直接拒绝执行，不猜。
• 每一项操作报 removed / kept / not found / failed，只要有 failed 就退出码 1。

环境变量总表

变量	谁读	含义
THINKRAIL_PORT / THINKRAIL_HOST	CLI	--port / --host 的默认值，优先级 命令行 > 环境变量 > 内置默认
THINKRAIL_STATIC_DIR	宿主	覆盖宿主所服务的 Web UI 目录（源码开发/换前端时用）
THINKRAIL_NO_ANALYTICS	宿主	等价于 --no-analytics，任意非空值生效；基础事件不受影响
THINKRAIL_LOG_LEVEL	宿主	debug|info|warn|error，默认 info
THINKRAIL_CHANNEL / THINKRAIL_VERSION / THINKRAIL_PREFIX / THINKRAIL_NO_MODIFY_PATH	安装脚本	Windows 上代替命令行参数的那组开关
THINKRAIL_REPO	安装脚本	换仓库（fork / 测试用），默认 JetBrains/thinkrail
THINKRAIL_INSTALL_SCRIPT_URL / THINKRAIL_INSTALL_PS1_URL	thinkrail update	覆盖安装脚本地址（测试 / fork）
PI_CODING_AGENT_DIR	pi	换 pi 的配置目录；GUI 里的等价入口是 Settings → Environment

应用内的斜杠命令

输入框里敲 / 会弹命令列表。这里要分清来源，因为ThinkRail 只加了两条，其余是 pi 的：

命令	归属	含义
/compact [说明]	标 Pi/built-in（浏览器端注入的原生命令）	压缩上下文。只识别裸 /compact 或 /compact + 说明文字，近似写法一律当普通消息发。提交时会绕过乐观回显，把队列里排着的消息收回输入框（图片和草稿都保留）。
/name <标题>	标 Pi/built-in	给当前会话改名，走 session.rename，不会变成一条发给 agent 的消息。
/model [查询]	pi 的	在输入框里打 /model 不是发消息，而是带着已有文字打开模型选择器；如果结尾那个词是选中模型支持的档位（如 opus high），会预选该档位。
/mcp	pi 的	MCP 服务器的状态与登录，官方明确“/mcp 仍然是 pi 的”，ThinkRail 只负责多会话 GUI 需要补的部分（比如把可能改数据的调用拦下来在聊天里问你）。
/模板名 参数	你或仓库定义的 prompt 模板	模板放在 .pi/prompts/*.md（本仓库自带 commit、explain、rename、review、tests 五个）或通过 Settings → Prompt templates 建，可分全局/项目作用域；输入后展开成模板正文再发送。
skill 命令	pi 的 skills	来自 skills 的命令在列表里带命名空间，不会和上面这些撞名。

重名保护的方向是固定的：原生的 compact、name 优先于同名的扩展或模板；官方还专门说明这是为了跟 pi 自己的规则对齐。

spec_*：agent 维护规格图谱的 7 个工具

由内置的 pi-spec-graph 扩展提供，packages/spec-graph/tools/SPEC.md 里逐个写着：

工具	含义
spec_grep	在 spec 集合里做全文搜索，按 0 起始的匹配偏移分页，同时给出条数和字节上限
spec_get	按 id 取某条 spec 的内容
spec_graph	遍历图谱，可选方向（SLICE_DIRECTIONS）和边类型（LINK_KINDS）
spec_create	新建 spec 文件，写入标准 YAML 头和标题骨架
spec_update	只改 YAML 头里的字段（frontmatter-only），永不把某个文件“降级为非 spec”，也不会清空或重命名 id
spec_delete	删除 spec 文件
spec_validate	校验结构与引用

配套知识（官方博客 9-15 那篇）：

• 每条 spec 的 YAML 头里 id / type / title 必填；type 取 goal-and-requirements / architecture-design / module-design / submodule-design / task-spec；status 取 draft / active / stale / done / deprecated；再用 parent、depends-on、tags 把关系连起来。
• SPEC.md 放在它描述的代码旁边，一个 spec 对应一个真实模块。官方给 AGENTS.md 的建议写法核心是两句：先读 spec 再读代码，以及代码与 spec 冲突时要在同一次改动里把 spec 改掉，绝不静默分叉（Never diverge silently）。
• 这么组织的目的很功利：agent 只读离它正在改的代码最近的那份 spec，上下文不会爆炸，关键信息不会被淹没。Specs 面板（右侧栏）把这张图渲染成可折叠的树，点开即在中间面板只读展示。

其他内置 agent 工具

聊天里那些可折叠的卡片背后是这些能力：pi 自带的 read / write / edit / bash；宿主补的 resolve_comment（回应 review 批注）和 request_review（派一个只读的 review 子 agent 出结论）；todo_* 五个（对应 Plan/TODO 面板）；pi-subagents 的 Agent（派子 agent，Resources 弹窗能看和停）；pi-background-commands（后台命令）；pi-web-access 的搜索/抓取；mcp__*（MCP 工具，调用前若服务器没标只读就会在聊天里问你）。

把 ThinkRail 的扩展装进终端版 pi

官方把两个交互工具单独发布成了普通 pi 包，所以终端里的 pi 也能用：

bash
pi install npm:@thinkrail/pi-ask-user-question   # agent 在聊天里问你结构化选择题
pi install npm:@thinkrail/pi-visualize           # agent 在聊天里画流程图/方案对比/前后 mockup

反过来，Settings → Extensions 里可以直接按来源安装任意 pi 包（npm、git、本地目录），可以只装给某个人某个仓库，界面会告诉你每个包加了什么，并能细到开关包里的某个扩展、某些 skill 或 pi 的内建工具；开着的会话要等它这一轮结束才会接手改动。

需要知道的兼容性限制（官方博客列的三条）：ThinkRail 跑的是它自己内嵌的 pi，可能和你本机的 pi 版本不同，个别 skill/扩展会因此不正常；改 pi 终端界面的扩展（比如 pi 主题）在 ThinkRail 里无效，但加工具、事件钩子、斜杠命令、简单对话框的扩展可以用；两个扩展注册同名工具时 pi 会都加载并报告冲突，由加载顺序决定谁生效。

从源码跑（开发命令）

需要 Bun 1.4.4（官方 packageManager 钉的版本）和 Node.js ≥ 22.19（in-process 的 pi 引擎要求），以及一个已认证的 pi provider：

bash
git clone https://github.com/JetBrains/thinkrail.git
cd thinkrail
bun install
bun run dev                           # 宿主 + Web 客户端一起起，Ctrl+C 全停

bun run --filter @thinkrail/cli dev   # 只跑浏览器启动器
bun run build:binary                  # 编译单文件 CLI 产物
bun run desktop:dev                   # 打包并打开 Electrobun 桌面 App
bun run desktop:build                 # 只打包不打开

仓库里还能看到 bun run smoke:binary（构建后启动产物做烟测）、bun run e2e:binary（整套无 agent 的 e2e 跑在产物上）、bun run check:seams（检查 pi 升级有没有引入新的、打包器看不见的动态 import）。更多检查项和端到端套件在 CONTRIBUTING.md。

隐私与遥测

这块官方写得比多数产品细，值得单独看：

• 基础使用事件常开：启动、创建会话、发送消息、连接 provider，绑一个随机安装 ID。官方承诺其中绝不含 prompt、代码、文件、凭据或账号身份。
• 错误报告总是发送（为了修崩溃）：只有错误类型/代码和 ThinkRail 自己代码里的位置，不含错误消息、文件路径、名称、URL 和你项目/扩展里的任何内容。
• “额外使用数据”是可选的：首次运行向导会问，开关在 Settings → Privacy；命令行层面 thinkrail --no-analytics 或 THINKRAIL_NO_ANALYTICS=1 只对那一次运行生效。开着它时，打包版可能一次性在浏览器打开官方博客做安装归因（只有你在网站上接受过营销 cookie 或当地不需要同意时才做），关联 30 天后过期。
• 问卷与遥测分开：Settings → Feedback 里主动提交才会发出你的回答，同样只绑随机安装 ID。
• 分析用的是 PostHog（产品和官网都用），隐私政策在 posthog.com/privacy；要删除你的问卷回答，发邮件到 info@thinkrail.ai。
• ThinkRail 自己没有账号，JetBrains AI 之外的凭据都留在 pi 里。

它现在的问题：一些诚实的评价

官方文档之外，我看了 HN 上两条讨论帖（50219186、50233294，合计 200 多条评论）和 README 的自述，把值得提前知道的负面声音整理如下，都注明是社区观点而非事实：

• 没有权限系统，只有 worktree 隔离：这点必须说清楚 —— ThinkRail 侧只有“每个 workspace 一个 worktree”这一层文件隔离，外加 UI 层的 MCP 写操作确认；而引擎侧 pi 的 README 明确写着 “Pi does not include a built-in permission system”，它以启动它的用户和进程权限运行，文件系统、进程、网络、凭据一律不设限。要边界就得自己按 pi 的 containerization 文档做，官方列了三种：Gondolin 扩展（pi 和 provider 凭据留在宿主，把内建工具和 ! 命令路由进本地 micro-VM）、整个 pi 跑在本地 Docker 里、或 OpenShell 策略沙箱。ThinkRail 把 pi 嵌在自己进程里，所以这几条得由你自己想办法。 这也是我建议永远用 workspace、而不是直接在项目文件夹里干活的原因。
• README 和 SPEC 的 AI 味：有人直言 “what you get” 那一长串 bullet 读起来很累，甚至质疑那些极其详尽的 SPEC.md 是不是 LLM 生成的。这条见仁见智，但它确实说明：别把 README 当入门教程，那几篇博客比 README 好读。
• 和 JetBrains Air 定位重叠？：HN 上有人直接问 “JetBrains 不是刚发了 Air 吗，这两个 premise 基本一样，策略是什么”。官方文档里没有回答这个问题，我能确认的只有：ThinkRail 是 Apache-2.0 开源、以 pi 为引擎、没有自己的账号体系。选哪个前你自己权衡。
• 企业用户的老问题：企业订阅往往没法直接给这类工具用，只能走 API，成本可能高一个量级。ThinkRail 的缓解办法是 Custom servers 接公司网关。
• 对 Web GUI / Bun 的偏好争议：有长期 JetBrains IDE 用户认为用 Monaco 而不是自家内核是退步，也有人说“Bun 我从我所有系统里清掉了”。这是技术选型口味问题 —— 但请注意它的实际后果：Bun 版本会直接影响能否从源码构建。
• 文档缺失是硬伤：Docs 站 Coming soon，thinkrail.ai/docs 404，出问题只能翻 README、博客、SPEC 和 Discord。
• 变化极快：GUI 那篇官方博文写的是 0.3.0 nightly 的界面，并明说几个月后就不一样了。本文所有命令我尽量按源码核对，但界面按钮名称请以你装上的版本为准。

反过来说，社区里认同的声音也很集中：把 agent 放在 worktree 里、把 spec 当作一等公民、给 agent 包一层真正的 diff review 界面，恰好是当前 CLI-only agent 工作流最缺的三件事。

常见故障对照

现象	原因	处理
装完敲 thinkrail 是 command not found	PATH 改在 rc 文件 / 注册表里，当前会话没重载	新开一个终端；还不行就检查 ~/.local/bin（Windows：%USERPROFILE%\.local\bin）是否在 PATH 里，或用 --prefix 装到已在 PATH 的目录
Windows 上 irm … | iex 报错、脚本被拦	执行策略 / 用错了 shell 语法	cmd 里要写成 powershell -c "irm … | iex"；PowerShell 里直接 irm … | iex
启动后浏览器没打开或打不开	端口 / 无浏览器环境	thinkrail --verbose 看解析到的 URL；headless 用 --no-open，自己拨 http://localhost:24242（被占时端口会自动向上漂）
打开项目失败、报找不到 git	git 不在 PATH	装 Git for Windows（含 git），确认 git --version 能跑
模型选择器空的 / 无法发送	没接 provider	Settings → Providers 登录 JetBrains AI 或填 key；自定义服务走 Custom servers + Find models
macOS 打开提示无法验证	CLI 已签名未公证，Linux/老 DMG 未签名	按系统设置里“仍要打开”操作；优先用带签名的最新 releases 资产
Linux 装完起不来	缺原生库	sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2，并确认 glibc ≥ 2.38（Ubuntu 24.04+）
Settings → Updates 里看不到更新按钮	安装包没有合法的 HTTPS feed 身份（早期安装）	手动重新装一次；CLI 侧确认二进制在 <prefix>/bin/thinkrail 且文件名正确
thinkrail update 拒绝执行并打印手动命令	二进制不在官方布局里，或元数据缺失/与本机安装无关	按提示的位置重装；Windows 上如果连 PowerShell 都找不到，它会给你对应 shell 的手动命令
卸载后 ~/.thinkrail 还在	默认保留（里面有你的 worktree 和未提交改动）	确认不需要后跑 thinkrail uninstall --remove-data
agent 在跑但看不到它的改动	你开的是项目文件夹而不是 workspace 的 worktree	切到对应 workspace；或用“在已安装 IDE 中打开 worktree”
怀疑界面行为不对想报 issue	——	--verbose 复现，取 ~/.thinkrail/logs，到 GitHub Issues；注意错误报告本身是常开的

参考与延伸

• 官网（特性演示即产品）：https://thinkrail.ai/
• 仓库 / README / Releases：https://github.com/JetBrains/thinkrail
• 官方博客：thinkrail.ai/blog —— 建议顺序 Introducing ThinkRail（08-19）→ Workspaces（09-03）→ Spec Graph（09-15）→ Pi Skills & Desktop Apps（10-01）→ 0.2.0 Review the Turn（10-18）→ GUI overview（10-28）
• 引擎 pi：https://pi.dev/，@earendil-works/pi-coding-agent（MIT）
• Discord：https://thinkrail.ai/discord
• 关于 SDD 的理论文章（官方博客引用）：Deepak Babu Piskala, Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants, https://arxiv.org/html/2602.00180v1

关于本文的核对口径：文中的版本号、资产名与大小、安装/卸载/更新命令、--help 全文、默认端口、快捷键、spec_* 工具清单、遥测范围，都是 2026-11-04 直接读 JetBrains/thinkrail 仓库的 README.md、install.sh、install.ps1、apps/cli/src/args.ts、apps/cli/SPEC.md、apps/web/src/commands/SPEC.md、apps/web/src/shell/useGlobalHotkeys.ts、packages/spec-graph/tools/SPEC.md、官方 6 篇博客和 GitHub Releases API 得到的；HN 评论来自 hn.algolia.com 对应对话串。我没有在本机安装并执行过这些命令，因此命令的行为描述属于“源码与文档已核对”，不属于“本机实测”。