ThinkRail — 产品目标与范围

目标¶

ThinkRail 是一款越用越好用的智能体 IDE。它是一个运行 pi 的轻量宿主，将其桥接到丰富的 UI，将工作隔离到独立的工作区，并通过可演进的规格和可复用的技能为智能体提供持久的项目知识——从而无需终端即可轻松使用智能体工作，同时保持隔离、可审查、以规格为基础：在保持控制力的前提下用智能体构建。

本文档描述产品的现状及其存在原因，并随产品一同变化：新落地的功能会补充在这里，发生变化的决策会重写在这里。它不包含版本或路线图。

问题¶

pi 是一个刻意保持精简、可扩展的 harness。这种灵活性需要付出时间成本：新手需要花很长时间学习如何驱动它，而经验丰富的用户也仍然会觉得终端在处理智能体周边的工作时很笨拙。

• 并行的智能体在同一工作树中相互冲突——彼此之间，以及与用户自己的编辑冲突。
• 从 CLI 审查智能体的变更很困难：阅读 diff、在具体行上评论、并将反馈交还给智能体。
• 意图会蒸发。 聊天中做出的决定随会话结束而消失；下一个会话会重新推导或与之矛盾。

适用人群¶

在真实 git 仓库上使用 pi 构建的人——想要可视化入门途径的新手、希望围绕智能体获得 IDE 体验同时不放弃 pi 深度的老手，以及希望快速推进而不失去对智能体所做内容的控制的智能体优先构建者。

价值¶

• 默认隔离。 ThinkRail 创建的工作区是一个带有独立分支和 cwd 的 git worktree：智能体可并行运行，主分支在用户合并前保持干净。直接在项目文件夹（默认工作区）中工作是一种明确的选择，绝不是默认行为。
• 真正围绕智能体的 IDE。 编辑器、diff、终端和评审集中在一个工作台中，让用户看到并引导智能体的工作，而不是从回滚缓冲区中重建它。
• 规格作为事实来源。 项目的意图存在于代码旁的规格图中，智能体可阅读、搜索并维护该图，因此意图能超越单个会话而存在。
• 完整的 pi，毫无隐藏。 模型、技能、扩展和会话状态仍归 pi 所有；ThinkRail 只是增加一个界面，而非第二个智能体。

原则¶

持久决策，所有功能遵循；[[architecture]] 承载强制执行这些决策的结构。

• pi 是唯一的引擎，且以进程内方式运行——没有第二个运行时（没有 claude-agent-sdk）。pi 拥有模型注册表、system prompt、技能/扩展、压缩、成本和会话状态。
• 通过投喂来影响，绝不通过拼装。 功能只能通过它们提供给 pi 的内容——prompt 上下文、文件、pi 自身的技能/扩展——以及会话启动时的标志来塑造智能体。
• 展示，而非重新计算。 宿主展示 pi 报告的内容，而不是自行推导出副本。
• 用户自己的工具和凭据。 Git、GitHub 和模型访问都通过用户自己的 git、gh、central CLI 以及 pi 的 provider 认证完成；ThinkRail 本身不保存任何账号或令牌。
• 信任是显式的。 克隆的仓库可能注入智能体的内容——其已提交的技能别名、pi 自身的项目资源（.pi/ 设置、扩展、技能、prompt、子代理定义）以及它定义的 MCP 服务器——只有在每次项目授予信任后方可加载；仓库定义的 MCP 服务器还需要逐条目审批，且当条目更改时审批失效。
• 规格优先。 ThinkRail 本身按规格优先构建，并帮助它打开的项目也以同样方式工作。

能力¶

ThinkRail 在产品层面的能力；细节由链接的规格负责。

• 双启动器，同一个应用——一个原生桌面应用和一个在浏览器中打开相同 UI 的 thinkrail CLI，两者都嵌入同一个宿主；状态存放在 ~/.thinkrail 下（[[module-desktop]]、[[module-cli]]）。
• 项目 → 工作区——git 仓库是一个项目；工作区是一个 git worktree，外加内置的默认工作区（即项目文件夹本身）和原地附加的现有 worktree（[[submodule-server-workspaces]]）。
• 工作台——文件、diff、文档、聊天和终端的可拆分布局，带有可移动的侧边和底部工具面板，且每个窗口保持独立（[[submodule-web-shell-layout]]）。
• 聊天——每个工作区可运行并发的 pi 会话，每个会话有自己的模型、pi 报告的 token/成本、运行中途的引导和追问、技能与 prompt 模板自动补全，以及历史搜索（[[submodule-web-chat]]、[[submodule-server-agent]]）。
• 复用现有技能——为其他编码智能体保留的可移植 Agent Skills 可在原位置读取；pi 仍然是解析器和运行时（[[submodule-server-agent]]）。
• 带逐步审查的计划——智能体执行、用户编辑的共享 TODO 计划；当某一步骤的变更可证明属于该步骤时，该步骤完成即单独提交，并可由独立评审者审查（[[module-pi-todos]]、[[submodule-server-todos]]、[[submodule-server-host-plan-review]]）。
• 子代理——委托给隔离的子会话，可前台、并行或后台运行（[[module-pi-subagents]]）。
• 评审——在文件和 diff 上锚定评论，无需启动智能体即可收集，并以结构化上下文发送给能够解决这些评论的聊天；这是本地评审，而非代码托管平台集成（[[submodule-server-reviews]]）。
• 发起 PR——推送工作区分支，并通过用户自己的 gh 打开或更新其 GitHub PR；若无法使用，则回退到预填好的 compare URL（GitLab：预填好的 new-MR 页面）。可从计划中发起，也可直接从顶栏发起，其 Remote 和 Pull request 区段始终显示该分支的下一步——发布、推送、同步、打开一个由计划、提交、模板或智能体草稿描述的 PR——对于已打开的 GitHub PR，还显示其检查和评审决策，并提供标记就绪、合并、修复失败的检查或让智能体整合已分叉的分支、重新打开、删除远程分支等操作（[[submodule-server-pr]]、[[submodule-web-shell-location-bar]]）。
• 规格——智能体通过 spec_* 工具搜索、导航和维护规格图；只读的 Specs 工具将其渲染为树（[[module-spec-graph]]、[[submodule-server-spec]]）。
• 工作流——内置的工作流技能，用于项目初始化、设计头脑风暴和发布 PR（[[module-thinkrail-workflow]]）。
• 提供商——通过 pi 的认证进行应用内登录和管理 API 密钥，并通过用户自己的 central CLI 使用 JetBrains AI（[[submodule-server-auth]]、[[central-integration]]）。
• Pi 配置——用户自己的 pi 配置文件夹，或其他文件夹（个人设置 vs 工作设置），外加额外的环境变量；在设置中选择，并在下次启动时应用到整个宿主；每个宿主一套配置，而非每个项目一套（[[submodule-server-environment]]）。
• 智能体工具——网络研究，以及聊天中的内联图表、对比和文件预览；提议的 UI 变更会通过与 diff 评审相同的渲染器和评审评论，显示为渲染后的前/后对比原型（[[submodule-web-chat-tools-web]]、[[module-ext-visualize]]）。
• MCP 服务器——pi 内置的 MCP，从用户的 mcp.json 读取，可在设置中管理，并在每个聊天中显示在后台命令和子代理旁边；在聊天中、调用时、以及可能更改数据的调用之前进行确认，并可为用户信任的工具提供每项目“始终允许”（[[submodule-server-agent]]、[[submodule-web-panels]]）。
• 围绕工作区——在已安装的编辑器或 IDE 中打开 worktree，并让应用本身保持最新（[[submodule-server-editors]]、[[submodule-web-updates]]）。
• 界面语言——UI 跟随系统语言或用户选择；内置英文和一组翻译（未翻译的字符串会显示为英文），用户可以通过 ~/.thinkrail/locales 下的扁平 JSON 文件添加或覆盖一种语言，保存后即时生效。智能体和工具的输出绝不翻译（[[module-locales]]、[[submodule-web-i18n]]）。
• 品牌——ThinkRail 绿色强调色（在暗色主题上明亮，在亮色主题上加深，从而在两者上都满足 AA 对比度）、Darcula 系列暗色背景、用于品牌展示角色的 Orbitron，以及用于 UI 和代码的 Geist 与 JetBrains Mono（[[submodule-web-themes]]、[[web-typography]]）。

非目标¶

只有这些是经过决策排除的。任何既未在上面列出也未在此处排除的内容都是开放的，而非禁止的。

• 第二个代理运行时，或任何主机端代理循环或提示词组装（参见Principles）。
• ThinkRail 账户或登录UI。 谁能访问主机由网络决定——Tailscale ACLs 和设备身份（[[architecture]]）。