ThinkRail 入门与架构实战:用 Git Worktree 隔离 pi Coding Agent,从安装到 Spec 驱动开发

原创2026-10-27 07:07:43725 阅读
文章标签:人工智能代码智能体IDE代码编辑器开发工具桌面应用前端后端插件系统

ThinkRail 入门与架构实战:用 Git Worktree 隔离 pi Coding Agent,从安装到 Spec 驱动开发

ThinkRail 是一个面向 Pi Coding Agent 的 agentic IDE:它不做第二个 agent 运行时,而是把 pi 放在进程内运行,再叠一层可视化的 IDE 外壳,让命令行里的 agent 工作流变得可浏览、可审阅、可隔离。本文以官方发布公告为骨架,完整保留其安装步骤与功能路线,并结合仓库源码说明这些能力在实现层面究竟如何落地——包括 worktree 隔离的真实目录规则、Spec 图的 spec_* 工具集、三层架构的边界约定,以及代码评审锚点的重新定位算法。

一、为什么需要“给 pi 加一层 IDE”

ThinkRail 的定位来自一个明确的取舍:Pi 的强大之处在于极简且可扩展——它是一个最小化的 harness,允许你自定义扩展与技能,并把工作环境调整到完全贴合自己的需要。但这份自由度有代价:新用户需要花大量时间学习如何驾驭 Pi,即便是熟练用户,也会觉得围绕 agent 的那部分工作在终端里显得笨拙。

ThinkRail 的思路是在不牺牲 Pi 深度的前提下降低门槛:它在 Pi 之上提供一层可视化界面,帮助用户快速上手并进入产出状态,同时保留 Pi 的全部可扩展性;此外,它与 Git 和 GitHub 的集成让多人实时协作更顺畅。

仓库中的 goal-and-requirements.md 把这个定位拆成了三个具体痛点,恰好解释了公告里那些功能为何存在:

痛点 具体表现 ThinkRail 的应对
并行 agent 相互碰撞 多个 agent 与用户自己的编辑挤在同一个工作区里 每个 workspace 是一个独立的 git worktree,有自己的分支与工作目录
agent 的改动难以审阅 在 CLI 里读 diff、在精确行上评论、再把反馈交回 agent 都很别扭 工作台内的 diff 视图 + 锚定评论,打包成结构化上下文发给聊天
意图会蒸发 一次会话里的决策随会话结束而消失,下一次要么重新推导要么自相矛盾 与代码并存的 spec 图,agent 可读、可搜、可维护

理解这三个痛点很重要,因为后文所有技术细节都是它们的直接产物。

二、安装:桌面应用与命令行两条路径

ThinkRail 有两种可叠加的分发形态:原生桌面安装包,以及自包含的 thinkrail CLI。两者都随发布资产提供 SHA256SUMS 校验文件,详见 README.md。

2.1 桌面应用(稳定版)

按平台下载对应的 thinkrail-desktop-* 资产:

  • macOS — Apple Silicon(.dmg):直接打开 DMG。没有 Intel 桌面构建。
  • Windows — x64(.zip):把整个安装包 ZIP 完整解压,然后在解压目录就地运行安装程序,它需要与同级的 payload 放在一起。
  • Linux — x64(.tar.gz) 与 Linux — ARM64(.tar.gz):解压后运行 ./installer。

Linux 桌面构建的运行前提是 Ubuntu 24.04+ 或任何提供 glibc 2.38 的发行版,并且需要 GTK/WebKitGTK 相关库。仓库 README 给出的完整依赖与安装命令是:

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

这四项依赖在 apps/desktop/SPEC.md 中同样被声明为 Linux 支持下限的一部分:原生 WebKitGTK 路线(不使用 CEF),需要 libgtk-3-0、libwebkit2gtk-4.1-0、libayatana-appindicator3-1、librsvg2-2。

2.2 命令行 host(终端与远程工作流)

如果你更偏好命令行,CLI/浏览器 host 依然可用,其安装、channel 与更新选项记录在 README 的安装章节中。安装脚本位于仓库根目录的 install.sh 与 install.ps1。

macOS / Linux / WSL:

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

Windows(PowerShell):

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

安装器会做三件事:下载对应平台的二进制、校验其 SHA-256、把 thinkrail 放进 PATH。从 install.sh 的实现看,二进制最终落在 <prefix>/bin/thinkrail,--prefix 默认是 ~/.local:

# install.sh 头部声明支持的选项
--channel stable|nightly   # 默认 stable
--version X.Y.Z|X.Y.Z-nightly.N|latest   # 默认 latest
--prefix DIR               # 默认 ~/.local
--no-modify-path           # 不修改 shell rc 文件,只打印 PATH 建议

通过 curl ... | bash 传参需要 -s -- 分隔,例如固定到 nightly 通道:

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

Windows 侧对应的参数是环境变量(THINKRAIL_CHANNEL、THINKRAIL_VERSION、THINKRAIL_PREFIX、THINKRAIL_NO_MODIFY_PATH):

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

安装完成后直接运行 thinkrail,可选择性附带一个 Git 仓库路径作为项目打开:

thinkrail ~/code/my-repo

运行前提是 PATH 上有 git,并且已经配置了模型 provider——可以在应用内用 JetBrains AI 登录,或使用你自己的 provider 凭据。thinkrail --help 列出全部参数,thinkrail --version 打印构建版本。

2.3 CLI 参数与环境变量的完整对照

公告只用一句话带过 CLI 的可用性,实际上 apps/cli/src/args.ts 中的 USAGE 才是权威清单:

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]
参数 作用 默认值 / 说明
--port <n> 监听端口 默认 24242;被占用时会向上扫描到第一个空闲端口
--host <h> 绑定地址 默认 localhost
--no-open 不自动打开浏览器 适用于无头或远程主机
--no-analytics 本次运行关闭“额外用量数据”共享 基础事件仍会发送;持久偏好位于 Settings → Privacy
--verbose 调试级日志 终端输出 + ~/.thinkrail/logs 下的轮转日志
-v, --version 打印版本后退出
-h, --help 打印帮助后退出
project-dir 启动时作为项目打开的 Git 仓库 可选,仅接受一个位置参数

环境变量同样被支持,规则是参数 > 环境变量 > 默认值:THINKRAIL_PORT、THINKRAIL_HOST、THINKRAIL_STATIC_DIR(覆盖 host 提供的已构建 Web 应用目录)、THINKRAIL_NO_ANALYTICS、THINKRAIL_LOG_LEVEL(debug|info|warn|error)。

有一个容易忽略的细节:--no-analytics 只影响“额外用量数据”,两种写法都不会关闭基础事件,帮助文本对此是明确披露的,而不是承诺零分析流量。另外 THINKRAIL_NO_ANALYTICS 在 CLI 参数解析中故意不被读取,由 host 的分析模块作为唯一读取方,这样包括 packages/server/src/dev.ts 在内的每个入口都会一致生效——这一设计在 apps/cli/SPEC.md 中被显式记录。

2.4 更新与卸载

已安装的 stable/nightly CLI host 会周期性地在 Settings → Updates 中提供 Run Update,后台执行本机的 thinkrail update;打包的桌面构建则在后台检查更新,并提供 Download → Preparing update → Install & Restart 三步,在你选择 Install & Restart 之前不会应用任何东西。

thinkrail update      # 重跑当前通道的安装器并替换 <prefix>/bin/thinkrail
thinkrail uninstall   # 移除可执行文件、安装器写入的 PATH 条目与安装元数据

uninstall 默认保留 ~/.thinkrail 应用状态(可用 --remove-data 删除,-y 跳过确认)。这个默认值并非随意:该目录里存放着 workspace 的 git worktree,可能还有未提交的工作。

三、第一次启动:从选择仓库到发出第一条指令

启动桌面应用后,选择一个 Git 仓库。如果用的是 CLI,运行 thinkrail,浏览器会打开一个新标签页,提示你打开第一个本地项目。

公告在这里强调了一个与隔离有关的关键约定:每个工作会话都在独立的分支上进行,只有在工作完成并经过审阅之后,才会合并回原仓库。结合源码来看,这句话有精确的边界:由 ThinkRail 创建的 workspace 是真正的 git worktree,而“直接在项目文件夹里干活”是显式的 Default workspace,永远不会是默认行为。

在打开项目之前,可以点击右上角的齿轮图标进入 Settings 面板,配置 LLM provider、界面外观以及其他设置。设置完成后返回主界面,打开项目,点击左侧面板中的项目条目并展开它,选择 "Default" 进入默认 workspace。随后你可以:

  • 与你选择的 AI agent 开始一段新对话;
  • 浏览项目文件;
  • 审阅 AI agent 所做的任何改动;
  • 使用界面内的 CLI 窗口来构建和测试项目。

最后一个能力并非模拟终端:apps/web 的终端面板由 @xterm/xterm 驱动,对接 host 侧由 bun-pty 提供的真实 PTY(见 architecture.md 中关于终端的技术决策),因此 vim、htop、lazygit 这类交互程序可以正常工作。

四、四大特性路线:公告承诺与源码实现对照

公告预告了四个重点方向。它们不是空头支票,仓库里都有对应的实现与规格文档。

4.1 Worktrees:每个 workspace 都是真实工作树

每个 workspace 都是真正的 Git worktree:自己的分支、自己的工作目录。这意味着并行运行多个 agent 时,每个都留在自己的分支上,主分支在你决定“合并”之前保持干净。

这句话在 packages/server/src/workspaces/workspaces.ts 的 createWorkspace 中逐条落实:

  1. 命名决定分支:传入名称时,branchSlug() 会把它转成小写、非字母数字替换为 -、截断到 60 字符(MAX_BRANCH_SLUG),空结果回退为 workspace;未传名称时使用 workspace-1、workspace-2 这样的递增名。
  2. 名称冲突自动去重:uniqueBranch() 会检查分支是否已存在、以及 ~/.thinkrail/worktrees/<project-slug>/<branch> 目录是否已存在,冲突则追加 -2、-3。
  3. 基线分支可指定,也可推导:未指定 baseRef 时读取当前 HEAD 的缩写引用;随后 assertSafeRef() 做引用安全性校验,必要时先对远端执行 fetch,再以远端跟踪引用作为起点。
  4. 落盘方式就是 git 原生能力:
const worktreePath = join(dataDir(), "worktrees", project.slug, branch);
mkdirSync(dirname(worktreePath), { recursive: true });
const added = git(project.path, [
  "worktree", "add", worktreePath, "-b", branch,
  "--no-track", "--end-of-options", remoteBase ?? baseBranch,
]);

也就是说,目录布局固定为 ~/.thinkrail/worktrees/<project>/<branch>,--no-track 避免新分支自动跟随上游,--end-of-options 防止分支名被误解析为选项。

两种刻意保留的例外。 architecture.md 的决策 6 明确记录:每个项目恰好有一个内置的 Default workspace(kind: "default"),其 cwd 就是项目文件夹本身(git 的主工作树),不可删除、不可重命名,且必须由用户在 Welcome 分支中显式进入;此外用户可以就地挂接一个已存在的 worktree(kind: "external"),ThinkRail 可以忘记它,但绝不会改写它。这两种记录都标记为用户所有,不会被 ThinkRail 重命名或回收——renameWorkspace 对 default 直接抛错,对 external 也抛错,forgetWorkspace 同样拒绝 default,理由很实在:删除默认 workspace 会把项目文件夹交给归档清退逻辑的 rm -rf 兜底路径。

生命周期与"归架"。 README 提到完成与休眠的 workspace 会自己落到每个项目的架子上:当它们的 PR 合并或关闭时,或经过一段安静时间后;一旦你重新在其中工作,它们又会回来。这件事在实现上是客户端推导而非 host 存储的布尔值:

  • host 只记录事实:lastActiveAt、settledOverride / settledAt,以及 PR 的 review 快照;
  • 客户端 apps/web/src/store/selectors.ts 中的 selectWorkspaceSettledReason 按优先级判断:正在运行或有待处理关注的 workspace 永不归架 → 用户手动 settled → 用户手动 active → PR 已合并/已关闭且此后无新活动 → 空闲超过 settleIdleDays 天;
  • settleIdleDays 的取值范围与默认值定义在 packages/contracts/src/domain.ts:最小 1 天、最大 365 天、默认 7 天,null 表示 Never。设置面板提供 1 / 3 / 7 / 14 天 / Never 五档。
  • 为了不让流式 agent 每个 token 都重写 workspaces.json,recordWorkspaceActivity 把写入合并到每分钟最多一次,但“清除手动归架标记”和“PR 刚合并时的新活动”这两种情况永不被合并丢弃。

4.2 Specification-driven development:让 spec 成为思维护栏

创建一组描述项目是什么、并相互引用的文档(即 "spec graph"),让 agent 把它们当作文档、准则与思考的护栏。

这是 ThinkRail 最具差异化的部分,实现在 packages/spec-graph 这个可移植的 pi 包中。它向每个会话注入三样东西:一个技能、七个 spec_* 工具、以及一条项目级的 before_agent_start 规则。

什么样的文件才算 spec? 规则极其克制:只要 frontmatter 同时带有 id 和 type,它就是 spec。技能文档 packages/spec-graph/skills/spec-graph/SKILL.md 给出了完整 schema:

  • 必填:id(唯一 slug)、type、title;
  • 可选:status(draft → active,以及 stale、done、deprecated)、parent(单链接)、depends-on / references / implements(链接列表)、covers、tags;
  • 类型体系:goal-and-requirements(图的根)、architecture-design(全局拓扑与横切决策)、module-design、submodule-design、task-spec(临时工作文档,落地后删除)。

七个工具的分工(职责清晰到几乎不会误用):

工具 类别 作用
spec_grep 读 在 spec 内容中搜索,可用元数据收窄范围
spec_get 读 返回节点的 frontmatter、已解析的链接与路径,不含正文
spec_graph 读 返回有界切片:子树、祖先或邻居,可指定深度
spec_create 管理 新建 spec,并脚手架化 frontmatter 与标题
spec_update 管理 只改 frontmatter,按原字段顺序就地重写,保留注释与嵌套字段
spec_delete 管理 删除 spec
spec_validate 管理 报告悬空链接、重复 id、父级环

一个值得强调的边界:这些工具从不编辑正文。散文用 pi 原生的 read / write / edit 来写,spec 工具只负责结构与元数据。spec_update 的"就地"性质也不是修辞——它只重写 frontmatter 块(并沿用该块原本的换行符),正文每一个字节都不动。

派生读索引。 文件系统是唯一真相,工具读到的模型是内存中、只读、按需重新校验的派生结构。每次读取都会重跑 glob(忽略 node_modules、.git、dist、build,以及 .claude、.superpowers、.gsd、.mockups、.playwright-mcp 这些其他助手留下的目录——它们的计划文件也可能带 spec 形状的 frontmatter),并用 (mtimeMs, size) 重新校验每个文件:未变的复用缓存解析,变更/新增的重新解析,消失的驱逐,只有 spec 集合真的变了才重建图。每个 cwd 复用一个 SpecIndex,所以 agent 的连续调用能吃到缓存收益。

规则如何进入系统提示。 两个扩展采用同一套机制:在 before_agent_start 里修改 systemPromptOptions.sections 中自己名下的那一节,然后返回空。这样 pi 只对那一节打补丁,而不是强制整个提示词——后者会让 provider 的提示缓存整体失效。这也是它没有写成 promptGuidelines 条目的原因:那会把多行规则压扁进共享的 rules 列表。标签名使用包名(pi-spec-graph、pi-thinkrail-workflow),因为可移植包不应携带宿主品牌。

只读的 Specs 视图。 工作台右侧的 Specs 工具把图渲染成树,它并不通过 agent,而是由 packages/server/src/spec/ 直接 value-import pi-spec-graph/core(一个不含 pi 依赖的读模型),复用同一套 is-a-spec 规则、同一个解析器、同一个"读时重新校验"的索引。

配套的工作流系统在 packages/pi-thinkrail-workflow,它随包提供了 choosing-a-workflow(根路由)、setting-up-a-project、importing-a-codebase、starting-a-new-project、brainstorming、writing-specs、shipping-a-pr、asking-user-questions、writing-workflow-skills 等技能。与 pi-spec-graph 不同,它不宣称能在原生 pi 下运行——它的技能内容假定宿主提供 ask_user_question 工具,而该工具只存在于 ThinkRail 中。

4.3 GUI for Pi:三层架构与"不组装提示词"原则

ThinkRail 包裹 Pi coding agent,用清晰的 AI 聊天窗口、Monaco 标签页,以及可视化的设置与模型管理来增强它。

界面之下的结构在 architecture.md 中被定义为三个环:

引擎宿主  packages/server + packages/shared   Bun.serve 的 HTTP+WS host,每个聊天一个进程内 pi 会话
   ↑
通信线缆  packages/contracts                   唯一耦合:类型 + 极小的无依赖运行时
   ↑
UI 客户端 apps/web                              React 19 + Zustand + Tailwind v4,独立发布

三个关键约束解释了这套拆分的价值:

  1. UI 不认识 pi。 不变量明确写着:浏览器打包代码绝不可以值导入 pi,只能从 pi-ai / pi-agent-core 包根做类型导入(类型导入在构建时被擦除,从而让 bundle 保持 provider 无关)。@earendil-works/pi-coding-agent 是服务端专属,永远不进入 contracts / web。
  2. 启动器是薄的,host 是库。 apps/cli 与 apps/desktop 都以进程内方式嵌入共享的启动路径:CLI 打开浏览器,桌面打开原生系统 webview,两者都不拥有引擎逻辑,也不互相拉起。桌面端绑定回环端口 0,用实际端口构成窗口 origin,于是打包的 web/dist、/ws、/files 与 SPA fallback 保持同源,Web 客户端因此没有任何 desktop 分支。
  3. 先水合,再流式。 客户端从不依赖"亲眼见过事件"来知道领域状态:连接时先读当前状态(project.list、workspace.list、session.list、session.getMessages),然后订阅实时增量(pi.event)。所以刷新页面、开第二个标签页、用手机连上来、乃至 host 重启,都能重建同样的项目、workspace、会话与转录。

还有一条原则值得单独点出,因为它解释了"GUI for Pi"为何不跑偏:影响靠喂入,绝不靠组装。pi 拥有模型注册表、系统提示、技能/扩展、压缩、成本与会话状态;ThinkRail 只通过喂给 pi 的内容(提示上下文、文件、pi 自己的技能/扩展)以及会话启动时的标志来施加影响,不在背后拼装提示词。这也是"没有 ThinkRail 账号"的技术根源——provider 凭据走 pi 自己的认证,GitHub 操作走用户自己的 gh。

4.4 Code reviews:锚定评论与结构化投递

在 CLI 里审阅 agent 的改动一直很麻烦。ThinkRail 想解决这个问题。

packages/server/src/reviews/SPEC.md 描述的机制比"能看 diff"复杂得多,核心是四件事:锚点、重定位、投递、闭环。

锚点(anchor)不是行号,而是一条有序的回退链。 ReviewAnchor = path + side + contentHash + 有序 selectors:

  • lineRange:整型、1 起始、非倒置的行范围;
  • textQuote:带 exact / prefix / suffix 的文本引用;
  • structural:scheme + ref 的文档节点定位(如 json-pointer、table-cell、ipynb-cell);
  • region:归一化到 0..1 的几何区域,用于图片、SVG 这类没有文本的资源。

contentHash 是资源字节的 SHA-256。这里有一个容易被忽视的判断:文本侧与纯字节侧走不同路径——文本侧由 lineRange 派生 textQuote,纯字节侧只哈希字节并原样保留渲染器给出的选择器,因为没有文本可引用。

文件在评论下方变化时如何重定位。 每次快照读取和每次发送前都会重跑 reanchorWorkspace:

  1. contentHash 未变 → anchored;
  2. 否则用 textQuote.exact(以 prefix/suffix 消歧)搜索 → 恰好一个匹配时更新 lineRange,状态记为 moved,并静默重钉。moved 是粘性的:重钉会刷新锚点的 contentHash,若不特殊处理,下一趟就会看到哈希匹配而把状态悄悄降级回 anchored,从而丢掉"曾漂移过"这个事实;
  3. 无匹配、匹配有歧义或文件消失 → outdated,但评论保留创建时的快照,因此仍然可读、可发送(投递包会标注其已过期);
  4. 对纯字节资源或没有文本引用的渲染器:有位置的锚点(任何 lineRange / structural / region)判为 outdated——重新定位需要证据,而一张变了像素的图片并不提供证据;整文件锚点(没有选择器,即 file 类评论)则留在 moved 并刷新哈希,因为这条意见针对的是文件而非文件中的某个位置。

side: "base" 的锚点永不重定位:它的 baseRef 被钉死为一个完整 commit oid,所指向的 blob 不可变,本就没有漂移可言;而且拿它去对 worktree 重定位,恰恰是"分侧捕获"要防止的那种重新指向。

投递包是结构化的 XML 式消息。 发送流程是:重定位 → 渲染投递包 → 创建会话(或跟进到客户端指定的最近打开聊天 / 该 key 已钉住的聊天,必要时从磁盘重新挂载)→ markSent → 触发提示词。投递包里每条评论都带稳定 id、片段与周围上下文;对于用几何或文档节点而非行号定位的评论,用 <locator> 行描述区域几何或 <scheme> <ref> 节点,因为根本没有行跨度可引用。每条评论还带 anchor-kind(region / structural / line / file),让 agent 把几何当作几何来读。

这里有一个安全细节:每个动态属性和 locator 值都做实体转义(& < > ",CR/LF 转数字引用),因为仓库路径或渲染器的节点引用是不可信文本,否则可能闭合标签、伪造一条用户从未写过的评论;而片段、上下文与正文保持原样,因为它们正是 agent 需要逐字阅读的内容。

响应是分离触发的。 提示词在会话存在的那一刻就以 detached 方式发出,处理器立即返回,客户端能马上打开聊天——如果等待 ack,每次发送都要静默熬过 pi 的 10 秒接受窗口。而 markSent 必须在锁内、在轮次被确认接受之前完成,否则并发发送会分叉出两个聊天。若轮次在真正开始前被拒绝(模型不对、key 缺失或过期),评论会被 rollbackSend 回滚为 draft:agent 从未收到的评审应保持可重试,而不是搁浅在 sent 状态、发送/编辑/删除动作全都没了。

闭环工具 resolve_comment。 它是一个 agent 模块的自定义工具,注册在每个会话上,但执行被委托回评审模块。它是会话绑定的:只解析 status === "sent" 且 sessionId 等于调用者的评论——也就是真正收到该评论的那个聊天。draft 评论无条件不可通过此工具解析,这既防止"用户还没发出去的草稿被 agent 自行解决",也防止评审 agent 提交一个发现后立刻自己清掉它。

PR 侧同样由 host 确定性驱动。 packages/server/src/pr/SPEC.md 描述了 pr.open 的路径:assertSafeRef 校验分支 → 推送 origin → 通过用户自己的 gh 打开或更新 PR,PR 正文从会话的 TODO 计划渲染(摘要、带 sha 与验证的步骤、评审轨迹),并额外包含 ## Committed outside the plan 一节来交代不属于任何步骤的分支提交。按钮从不经过 agent——这是一个刻意的可靠性选择;PR 模板发现读的是 worktree 而非 forge,覆盖 .github/、根目录、docs/ 下的 pull_request_template.md(大小写不敏感)以及 .github/PULL_REQUEST_TEMPLATE/*.md。

五、平台支持与已知限制

公告的宣传语气容易被误读成"全平台全功能",实际的支持矩阵是明确且有边界的(见 README.md):

平台 桌面 CLI
macOS Apple Silicon DMG 已签名二进制
macOS Intel 无 Electrobun 构建 无预构建,需从源码构建
Windows x64 已签名的 setup 可执行文件与应用二进制 已签名 .exe
Linux x64 / ARM64 setup tarball,未签名 未签名

签名策略也值得如实说明:JetBrains 为 Windows CLI、桌面 setup 可执行文件,以及桌面应用安装的每个可执行文件与 DLL 签名;macOS CLI 已签名但尚未公证。签名并公证的桌面 DMG 依赖 JetBrains 内部服务流水线,较早发布的 DMG 与本地构建的包可能仍未签名并被 Gatekeeper 拦截;Linux 产物不签名。

另外两条限制来自实现而非营销:

  • 桌面 profile 目前只有本地 host。 后续的"共享客户端"profile 才可能连接已存在的 host;手机通过 Tailscale 访问选定的 host。
  • 多个 host 共用一个数据目录时不做跨进程一致性保证。 每个启动器绑定自己的回环端口,各自初始化进程内服务;如果多个 host 指向同一可变的 ~/.thinkrail,持久化与事件流并不协调,并发修改可能相互覆盖。

六、本地试用与参与方式

公告邀请用户先跑起来、再反馈。落到可执行的步骤,从源码运行需要:Bun 1.4.4(固定的包管理器与运行时)、Node.js ≥ 22.19(进程内 pi 引擎要求),以及一个已认证的 pi provider。

git clone https://github.com/JetBrains/thinkrail.git
cd thinkrail
bun install
bun run dev                          # host + web 客户端同时启动,Ctrl+C 一起停止

其他常用入口:

bun run --filter @thinkrail/cli dev  # 浏览器启动器
bun run build:binary                 # 独立的 CLI 产物(单文件可执行)
bun run desktop:dev                  # 打包并打开 Electrobun 应用
bun run desktop:build                # 只打包,不打开

值得留意的是项目自身的工作方式与它倡导的方法一致——spec-first:每个模块旁边都有一份 SPEC.md,任何移动边界、契约或决策的改动都必须在同一次变更里更新 spec。本文引用的 architecture.md 的 23 条决策与 packages/*/SPEC.md 就是这套方法的产物;spec_validate 会检查悬空链接、重复 id 与父级环,让这张图不至于腐化。

如果只想快速体验而不想读架构,最短路径就是三步:安装桌面应用或 CLI → 在 Settings 里配置 provider → 打开一个 Git 仓库,从 Default workspace 之外新建一个 workspace,把任务交给 agent,然后在 diff 视图里留下几条锚定评论,看它们如何被打包成结构化上下文送回聊天。这基本上就是 ThinkRail 想解决的三个痛点的完整闭环。

登录后查看全文
thinkrail