ThinkRail 产品目标与范围详解：围绕 pi 构建的 Agentic 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编码 agent 包进一个真正的 IDE 里用 git worktree 隔离并行工作、用可维护的 spec 图谱承载项目意图、用「只暴露不重算」的宿主桥接 pi 的全部状态。本文以仓库根目录的 goal-and-requirements.md 为主线逐节拆解这份产品目标与范围文档的定义并用源码、契约与规格文件为每一条主张补上实现证据帮助你既看懂「产品为什么这样设计」也能定位到「代码里在哪兑现」。一、这份文档是什么以及它为什么不是路线图goal-and-requirements.md 的 frontmatter 就把自己的定位写死了id: goal-and-requirements type: goal-and-requirements status: active title: ThinkRail — product goal and scope covers: [product-goal, product-audience, product-principles, product-capabilities, product-non-goals, engine-decision] tags: [product, scope]covers字段列出了它负责的六个主题产品目标、目标用户、产品原则、产品能力、非目标、引擎决策。文档正文明确写道「This document describes the product as it is and why it exists, and changes with it: a capability that lands is added here, a decision that changes is rewritten here.It holds no versions or roadmap.」——它描述的是当下事实与理由不承载版本号和路线图。能力落地就增补决策变更就改写。这一点决定了阅读方式。仓库根目录的 AGENTS.md 给出一份「按比例读取上下文」的规则文档负责回答的问题goal-and-requirements.md产品目标、原则、能力、非目标architecture.md系统拓扑、跨模块决策、全仓不变量pi-compatibility.mdpi 升级与宿主适配、移除门槛各模块SPEC.md该模块边界、公共接口、允许/禁止依赖也就是说产品意图在本文件结构约束在架构文件实现细节在下沉规格。文档里大量出现[[submodule-server-workspaces]]这类双链含义是「细节由那份 spec 拥有」。本文在引用时已把它们映射为仓库相对路径。二、Goal一句话里藏着四个机制原文档的目标段落只有一句话但信息密度很高ThinkRail is the agentic IDE that gets better every time you use it. It is a thin host that runspiand bridges it to a rich UI, isolates work into separate workspaces, and gives the agent durable project knowledge through living specs and reusable skills — so agent work is approachable without a terminal and stays isolated, reviewable, and grounded in specs: building with agents without losing control.把它拆开是四个可验证的机制thin host薄宿主宿主只做进程内引擎托管、状态持久化与线协议服务不做第二个 agent 循环。architecture.md 用「三个环」定义这件事。isolates work into separate workspaces工作区隔离工作区是 git worktree有自己的分支与 cwd。durable project knowledge耐久项目知识living specs 可复用 skills二者都由pi直接读写。reviewable / grounded可评审、有据可依评审面与 spec 共同构成「人还能控制」的抓手。「gets better every time you use it」不是营销口号而是与 spec-first 联动的机制描述项目意图写在代码旁边的 spec 图谱里agent 读它、搜它、维护它于是下一轮会话不必重新推导原文档 Problem 一节的 Intent evaporates。三、Problem三个痛点三种代码级解法原文档把痛点归为三条每一条在仓库里都有对称的实现3.1 并行 agent 在同一工作树里相撞Parallel agents collidein one working tree — with each other and with the users own edits.解法是默认隔离。packages/server/src/workspaces/SPEC.md 规定工作区是数据目录下dataDir/worktrees/project-slug/branch的git worktreecreateWorkspace使用git worktree add -b分支创建并且强制--no-track。后者的理由写在 spec 里若基线是远程跟踪分支git 的autoSetupMerge默认会把上游设成基线分支导致工作区终端里的git push/git pull指向错误目标。新分支的上游属于用户首次 push 时自己设定不属于工具。3.2 CLI 里评审 agent 改动很笨拙Agent changes are hard to reviewfrom a CLI: reading diffs, commenting on exact lines, and handing that feedback back to the agent.解法是把评审做成宿主侧一等公民。packages/server/src/reviews/SPEC.md 描述每个工作区有一份开放的 Review评论锚定在文件与 diff 上可以在不启动 agent 的情况下收集然后以结构化上下文包的形式发送到一个或多个 chat锚点重定位与包渲染都由宿主负责。行锚通过contracts的ReviewSelectorlineRange/textQuote/structural如json-pointer、table-cell、ipynb-cell/region几何表达见 architecture.md 决策 19。3.3 意图会蒸发Intent evaporates.Decisions made in a chat end with the session; the next one re-derives or contradicts them.解法是 spec 图谱packages/spec-graph/SPEC.md 提供spec_*工具集与配套 skillagent 用它读取、检索、维护SPEC.md之间的连接图。宿主侧读模型见 packages/server/src/spec/SPEC.md。四、Who its for三类用户一条共同的底线原文档点了三类人想在真实 git 仓库上与pi协作的新手需要可视化入口、不想放弃 pi 深度的老手需要在 agent 周围有 IDE、以及agent-first 构建者要快但不能失去对 agent 行为的掌控。这条描述对应一个产品判断功能不是给「不需要 agent 的人」或者「不需要 IDE 的人」做的。它因此也解释了两处看起来「反直觉」的设计选择——Default 工作区把「直接在项目目录里干活」保留为显式选择给被 worktree 模型绕晕的人一个锚而 MCP 与仓库资源默认关闭直到用户授权给不想被克隆仓库注入代码的人一条边界。五、Value四条支柱及其源码落点原文档的 Value 部分有四条是全文的技术核心。5.1 Isolation by defaultA workspace ThinkRail creates is a git worktree with its own branch and cwd: agents run in parallel and the main branch stays clean until the user merges. Working directly in the project folder (the Default workspace) is an explicit choice, never the default.契约里的Workspace结构把这件事落到了字段级见 packages/contracts/src/domain.tsexport interface Workspace { id: string; projectId: string; kind?: default | external; name: string; branch: string; worktreePath: string; baseBranch: string; diffBase?: string; renamed?: boolean; initialTerminalPending?: true; diffStats?: DiffStats; skillOverrides?: Recordstring, on | off; subagentsOverride?: SubagentOverride; subagentMaxConcurrentOverride?: number; lastActiveAt?: number; settledOverride?: SettledOverride; settledAt?: number; review?: OpenBranchReview; }几个关键语义均可回溯到 packages/server/src/workspaces/SPEC.mdkind标记两类「用户所有」工作区。default每个项目恰好一个内建 Default 工作区worktreePath就是项目文件夹本身git 的 main working tree不可删除、不可重命名只能从项目 Welcome 页显式「Work in project folder」进入。external用户显式就地附加的既有 worktreeThinkRail 可以「忘记」它但永不修改它。baseBranch与diffBase是两个字段不是两个名字。baseBranch是创建溯源分支从哪切出来之后不再移动diffBase是「评审以何为基准」可以重指向。合并它们会让重指向后的证据撒谎。name与branch解耦。名称是人类可读标签保留大小写与标点可以是任意文字分支是 kebab slug自动命名workspace-N时二者相同。工作区目录永不搬家。用set_title带来的分支重命名走git branch -m但 worktree 目录保持原路径——因为 pi 按该 cwd 精确索引会话与终端标签页。Default 工作区的「零写入」纪律值得单列listWorkspaces会确保Default 存在这是文档中明确承认的一处 CQS 例外查询会写应用注册表并发出生命周期事件但只写数据目录下的workspaces.json绝不写入用户仓库ensureWorkspaceScratchDir只在会话真正创建时调用在 Default 工作区里它拒绝符号链接路径分量、.gitignore用独占创建且只在文件不存在时写——因为它面对的是仓库可控的内容。5.2 A real IDE around the agentEditor, diffs, terminals, and review in one workbench, so the user sees and steers the agents work instead of reconstructing it from a scrollback.结构上是「三个环」见 architecture.md引擎宿主packages/serverpackages/shared由apps/cli或apps/desktop以本地宿主模式启动拥有pi、会话状态、持久化并提供线端点。线协议the wirepackages/contracts类型 无依赖运行时是客户端与宿主之间的唯一耦合。UI 客户端apps/webmobile-first 的 React 客户端可独立作为静态资源发布。解析这条依赖图的一行就够apps/web ── depends on ─▶ packages/contracts, packages/locales, packages/ui, packages/extension-api/web, packages/resource-renderers, thinkrail-extensions/*/web永远不依赖server或shared。这条规则由bun run check:boundaries强制scripts/check-module-boundaries.ts。终端的选择也有明确取舍浏览器终端是xterm/xterm DOM 渲染器不是addon-webgl理由与替换门槛写在 architecture.md 决策 11。5.3 Specs as ground truthThe projects intent lives in a spec graph beside the code that the agent reads, searches, and maintains, so intent survives the session.agent 面对的是一组以spec_为前缀的工具注册入口见 packages/spec-graph/tools/index.tsexport function registerSpecTools(pi: ExtensionAPI): void { registerSpecGrep(pi); registerSpecGet(pi); registerSpecGraph(pi); registerSpecCreate(pi); registerSpecUpdate(pi); registerSpecDelete(pi); registerSpecValidate(pi); }对应工具名分别为spec_grep、spec_get、spec_graph、spec_create、spec_update、spec_delete、spec_validate见各文件内的name:声明例如 packages/spec-graph/tools/grep.ts。UI 侧另有一个只读的 Specs 工具把图谱渲染成树。工作区里还有一个易被忽略的约定每个工作区有一个短暂的临时目录WORKSPACE_CONTEXT_DIR定义为.thinkrail/context见 packages/shared/src/paths.ts内含一条自忽略的*.gitignore零 git 足迹。它是任务草稿与工作文件的落脚点仍可被 spec 工具扫描到。注意别与全局数据目录~/.thinkrail混淆——前者在仓库内且不入库后者是应用状态。5.4 All of pi, nothing hiddenModels, skills, extensions, and session state stay pis; ThinkRail adds a surface, not a second agent.三条不变量支撑这条价值architecture.mdagent 进程内运行没有崩溃隔离会话调用要包错误处理并把错误转发出去一个致命故障会带走整个宿主。这是与「子进程 RPC 模式」对比后被接受的代价。pi拥有状态并发出真相宿主通过读方法暴露pi 的状态不重算把 pi 的事件作为增量转发。客户端先 hydrate 再 stream见决策 8architecture.md客户端从不依赖「见证过事件」来得知领域状态——连上时先project.list/workspace.list/session.list/session.getMessages读再订阅pi.event。这也解释了AppConfig里为什么有一长串「以 pi 为常量」的配置项而不是宿主自造的副本packages/contracts/src/domain.tsdefaultModel、defaultEffort、reviewModel、recentModels、subagentMaxConcurrent、disabledExtensions、locale……它们要么直接喂给 pi要么只影响宿主呈现。六、Principles六条耐久决策原文档的 Principles 一节自称「Durable decisions every feature follows」并指向 architecture.md 承载强制执行结构。六条逐条对应实现原则原文要点实现体现pi 是唯一引擎进程内运行无第二运行时无claude-agent-sdkcreateAgentSessionpackages/server/src/agent/agentSessionManager.ts通过「喂」影响而非「拼装」功能只通过 prompt 上下文、文件、pi 自身 skills/extensions 与会话启动 flag 影响 agent例workflow 规则注入systemPromptOptions.sections暴露不重算宿主展示 pi 报告的内容token/成本、agent_settled转换、模型目录用户自己的工具与凭据git / GitHub / 模型访问走用户的git、gh、centralCLI 与 pi 的 provider auth无内置账号Open PR 走gh并有 compare URL 回退信任必须显式克隆仓库可注入的东西按项目授予后才加载仓库定义的 MCP server 还需逐条审批setProjectTrustmcpApprovals指纹spec-firstThinkRail 自身以 spec 先行也帮助打开的项目这样工作每模块SPEC.mdcheck:spec-surface6.1 「喂进去」而不是「组装」一个具体例子packages/pi-thinkrail-workflow/index.ts 全文很短却精准示范了这条原则export const WORKFLOW_SECTION pi-thinkrail-workflow; export const WORKFLOW_RULE [ At the start of a new piece of work, read the choosing-a-workflow skill before any other tool call for project onboarding, PR lifecycle work (including checking a PRs CI), or any change to what the product does — a feature, a behavior change, or a bug fix, however small., Non-PR questions, explanations, and checks, and edits that change no behavior (typos, documentation or configuration only, mechanical refactors), proceed directly without loading or announcing a workflow., Continue work already routed to a workflow without routing it again., ].join(\n); const factory: ExtensionFactory (pi: ExtensionAPI) { pi.on(before_agent_start, (event) { event.systemPromptOptions.sections[WORKFLOW_SECTION] WORKFLOW_RULE; }); };它没有自建路由逻辑、没有旁路分类器、没有第二套 prompt 组装器——只是把一段文本放进 pi 的 system prompt 分节让 pi 自己的加载机制去决策。这就是「Influence by feeding, never by assembling」。6.2 信任是显式的两级授权原文档把可被克隆仓库注入的东西列得很具体仓库提交的 skill 别名、pi 自己的项目资源.pi/下的 settings、extensions、skills、prompts、subagent definitions、以及它定义的 MCP servers。实现上这是两级授权packages/server/src/projects/projects.tsexport function setProjectTrust( id: string, trusted: boolean, acknowledgedSkills?: string[], options: { resources?: boolean } {}, ): Project { const projects getProjects(); const project projects.find((p) p.id id); if (!project) throw new Error(Unknown project: ${id}); project.trusted trusted; if (!trusted) project.piResourceTrust untrusted; else if (options.resources true) project.piResourceTrust granted; if (acknowledgedSkills ! undefined) project.acknowledgedSkills acknowledgedSkills; saveProjects(projects); emit(project); return project; }要点两个授权分开trusted管 skill 别名piResourceTrust管 pi 的.pi/资源其中包含可执行代码extensions 与 settings 包因此只有明确点名它们的界面才能申请。trusted: false一并撤销两个授权trusted: true只在resources: true时提升 pi 级信任。没有祖父条款记录若早于该字段出现按 untrusted 处理。MCP 另算仓库定义的 server 需要逐条审批审批以「整个原始条目的指纹」为凭据approveProjectMcpServer(id, name, fingerprint)条目一改指纹就失配审批自动失效。指纹覆盖整个条目对象、忽略无关键顺序、但保留toolExposure顺序语义见 packages/server/src/agent/mcp/config.test.ts。「Always allow」的工具授权存在项目记录里不在仓库里因此不可能随仓库「预授权」发出。七、Capabilities能力清单与代码路径原文档的 Capabilities 是「产品级」描述每条都指向细化的 spec。下面按主题归类并给出可查的相对路径。7.1 两个启动器一个应用桌面原生应用与thinkrailCLI 打开同一个 UI都嵌入同一个宿主状态位于~/.thinkrail。CLI 的流程见 apps/cli/SPEC.md解析 argv/env → 解析静态目录THINKRAIL_STATIC_DIR或随二进制发布的构建产物→bootHost({ portMode: free, resolveShellEnv: true })→ 打印启动标记与端点并打开浏览器--no-open可关→ SIGINT/SIGTERM 走共享的幂等server.shutdown()。数据目录的解析在 packages/server/src/persistence/persistence.tsreturn resolve(process.env.THINKRAIL_DATA_DIR ?? join(homedir(), .thinkrail));即THINKRAIL_DATA_DIR可覆盖且相对路径会被 resolve 成绝对路径架构决策 22 要求目录身份统一为宿主解析后的拼写。7.2 Projects → workspacesgit 仓库即项目工作区是 worktree外加内建 Default 与就地附加的既有 worktree。相关规格packages/server/src/projects/SPEC.md、packages/server/src/workspaces/SPEC.md。线方法在 packages/contracts/src/wsProtocol.tsproject.open/workspace.create/workspace.listExisting/workspace.openExisting…。一个值得注意的守恒律projects spec一个 cwd 只有一个 ThinkRail 身份。openProject会把「已被某个工作区当作worktreePath」的根以ALREADY_OPEN拒绝——因为 pi 按目录索引会话第二个身份会把那个工作区的 chat 当成自己的并在任一方归档时被清除。7.3 Workbench工作台可拆分布局文件、diff、文档、chat、终端侧栏与底栏工具面板可移动布局是每个窗口本地的。apps/web/src/shell/layout/SPEC.md 与架构决策 5、9 定义了WorkbenchFrame一个窗口一份、无资源绑定、可持久化与WorkspaceViewState每个工作区一份的分工布局不下线只有领域状态过线。7.4 Chats会话每个工作区可并发多个pi会话各有模型、pi 报告的 token/成本、运行中的 steer 与 follow-up、skill 与 prompt-template 自动补全、历史搜索。规格apps/web/src/chat/SPEC.md、packages/server/src/agent/SPEC.md。会话语义里有一条容易踩坑的规则AGENTS.mdprompt()在流式过程中会抛错应当使用steer()/followUp()自动工作结束于agent_settled而不是agent_end——重试、压缩、恢复、排队的续跑都可能发生在一次尝试级的agent_end之后。7.5 既有 skills 被就地复用为其他编码 agent 保留的可移植 Agent Skills 被原地读取pi仍是解析器与运行时。这意味着 ThinkRail 不复制一份 skill 目录也不自建 skill 格式。7.6 带逐步评审的 Plan共享 TODO plan 由 agent 推进、用户可编辑每一步完成时如果改动可证明只属于该步就单独提交commit并可交由独立评审者评审。规格packages/pi-todos/SPEC.md、packages/server/src/todos/SPEC.md、packages/server/src/host/planReview.SPEC.md。工具面见 packages/pi-todos/tools 下的name:声明todo_write、todo_add、todo_update、todo_list、todo_remove、todo_promote、todo_plan_summary。评审者为什么是委派的子会话而不是第二个可见 chatplanReview spec 给了完整复盘可见会话需要一套「会话是否停下」的监控settle tee、审查者→worker 注册表、终止分类器、按 settle 推进的队列约 400 行而委派子会话把完成变成 promise 的 resolve、失败变成 reject恢复面收敛成一次catch。7.7 Subagents子代理把工作委派到隔离的子会话前台、并行或后台。规格packages/pi-subagents/SPEC.md可移植核心在 packages/pi-delegation/SPEC.md。工具面为Agent与get_subagent_result见 packages/pi-subagents/src/extension.ts 与同文件 #L303。并发上限可以在两个层级设置全局AppConfig.subagentMaxConcurrent以及工作区级subagentMaxConcurrentOverridepackages/contracts/src/domain.ts工作区模块只校验取值并持久化不解析生效策略——策略由宿主跨模块组合。7.8 Review评审在文件与 diff 上留锚定评论不启动 agent 也能收集作为结构化上下文发给能解决它们的 chat这是本地评审不是 forge 集成。规格packages/server/src/reviews/SPEC.md。线方法review.get/review.commentAdd/review.commentUpdate/review.commentDelete/review.fileDone/review.sendComment/review.sendBatch/review.close其中review.close就是 Clear先把非草稿记录归档为关闭快照再用一份新的开放评审替换活动快照客户端只会收敛到新快照。7.9 Open PR推送工作区分支并通过用户自己的gh打开或更新 GitHub PRgh/GitHub 不可用时回退到预填 compare URLGitLab 回退到预填的新 MR 页。顶栏的 Remote 与 Pull request 段始终显示分支的「下一步」publish、push、sync、按 plan 描述的 open PR、commits、模板或 agent 草稿。PR 打开后还能看到 checks 与 review decision并支持 mark ready、merge、把失败检查或已分叉分支交给 agent 处理、reopen、删除远端分支。关键的确定性设计宿主侧 push 开/更新 PR不存 token、不走 provider REST APIarchitecture.md。分支状态的字段形状见 packages/contracts/src/domain.ts 的BranchStatuspublished、pushesElsewhere、ahead/behind、aheadOfBase、onBase、review。其中onBase表示「分支就是它自己的基线Default 停在默认分支」此时无法从它开 PR。7.10 Specsspec_*工具 只读 Specs 树。见本文 5.3 与 packages/spec-graph/SPEC.md、packages/server/src/spec/SPEC.md。7.11 Workflows工作流技能内置工作流技能覆盖项目搭建、设计头脑风暴、交付 PR。技能目录见 packages/pi-thinkrail-workflow/skillschoosing-a-workflow、setting-up-a-project、starting-a-new-project、importing-a-codebase、brainstorming、writing-specs、shipping-a-pr、asking-user-questions、writing-workflow-skills。路由由始终在线的规则段落完成见 6.1且规则明确「不改变行为的编辑直接进行不加载也不宣告工作流」。7.12 Providers提供方应用内登录与 API key 走 pi 自己的 authJetBrains AI 走用户的centralCLI。规格packages/server/src/auth/SPEC.md 与 central-integration.md。Cross-module 的生命周期归属由架构决策 13 指定architecture.md。7.13 Agent tools网页研究与内联可视化网页研究加上聊天内联的图、选项对比与文件预览。当 agent 提出 UI 改动时用同一套渲染器与评审评论展示渲染后的前后对比 mockup——评审面与 diff 评审共用一套机制。相关规格apps/web/src/chat/tools/web/SPEC.md、thinkrail-extensions/visualize/SPEC.md。扩展的组合方式是静态的服务端注册表 packages/server/src/extensions/registry.ts 与 web 注册表 apps/web/src/extensions/registry.tsSDK 是packages/extension-api类型 define*与packages/ui。可见性由 Settings → Extensions 的开关控制全局AppConfig.disabledExtensions经宿主注入的 resolver 到达agent在每次 loader重加载时过滤工厂并通过 pi 的 active-tool API 让已禁用的扩展工具从活动会话中撤下web 渲染器仍保持注册以便历史 transcript 继续渲染architecture.md。7.14 MCP servers读取用户的mcp.json可从 Settings 管理并在每个 chat 中与后台命令、子代理并列显示。对可能改变数据的调用在 chat 内、调用前确认受信任的工具可按项目「Always allow」。行为细节在 packages/server/src/agent/mcp/SPEC.md 与 apps/web/src/chat/tools/mcp/SPEC.md。7.15 工作区之外在已安装的编辑器/IDE 中打开 worktree以及让应用自身保持最新。规格packages/server/src/editors/SPEC.md、apps/web/src/updates/SPEC.md、apps/desktop/src/updates/SPEC.md。7.16 界面语言UI 跟随系统语言或用户选择英文内置用户可在~/.thinkrail/locales放一个扁平 JSON 文件新增或覆盖语言保存即生效。agent 与工具输出永不翻译。实现上packages/locales的en.json是唯一英文真源所有面向用户的字符串必须是键如settings.language.title由单一 i18next 实例渲染thinkrail/locales/react硬编码 JSX 文本与文本属性aria-label、title、placeholder、alt、label会被 lint 门禁拦下architecture.md 决策 23。宿主侧读取与校验在 packages/server/src/locales/SPEC.md只读全局数据目录绝不读工作区防止克隆仓库改写 UI扫描*.json单文件 2 MB、最多 64 个文件逐字符串回退顺序为「本地精确 → 内置精确 → 内置基语言 → 英文」。7.17 品牌ThinkRail 绿色强调色深色主题上偏亮、浅色主题上加深以保证两种都通过 AA、Darcula 系深色背景、Orbitron 用于品牌展示位、Geist 与 JetBrains Mono 用于 UI 与代码。相关路径apps/web/src/themes、apps/web/scripts/typography.ts。样式生成物有门禁bun run colors:check、bun run spacing:check、bun run typography:check。八、Non-goals被「决定」排除的两件事原文档对 Non-goals 的措辞非常克制且这一节的边界语义比内容更重要Only these are excluded by decision. Anything neither listed above nor excluded here is open, not forbidden.即「只有这两条是被决定排除的既没列在能力里、也没列在这里的是开放的不是禁止的」。两条是第二个 agent 运行时或任何宿主侧 agent 循环与 prompt 组装见 Principles。这条在架构中以不变量形式重复agent 进程内运行earendil-works/pi-coding-agent只在服务端浏览器打包代码永不 value-importpi只能从pi-ai/pi-agent-core根做类型导入类型导入在构建时被擦除使 bundle 不含 provider。ThinkRail 账号或登录 UI。谁能访问一个宿主由网络决定——Tailscale ACL 与设备身份。架构决策 7 表述为「Auth is external」应用只携带owner字段architecture.md。九、这份文档如何与代码一起演进goal-and-requirements 自称随产品变化改写这需要工程机制支撑否则必然腐化。仓库里有三层保障第一层文档分层与双链。产品意图本文件→ 架构决策 → 模块SPEC.md。covers、parent、depends-on、references等 frontmatter 字段把文档连成图spec_*工具让 agent 能检索这张图。第二层边界与接口的可执行门禁。根 package.json 里可直接运行bun run check:boundaries # 模块边界含 web 不得依赖 server/shared bun run check:spec-surface # 已登记的 spec/barrel 公共面 bun run check:seams # 二进制接缝 bun run check:deps # 精确版本与 catalog 漂移 bun run check:i18n # 硬编码 UI 文案 bun run check:compiler # React Compiler 逃逸基线 bun run lint # biome bun run typecheck其中check:deps对应架构决策 10所有依赖精确固定禁止^、~、、、.x、*跨切依赖pi、TypeScript、typebox、Bun types在根workspaces.catalog固定一次并通过catalog:引用。这条规则的动机在文档里写得很坦率pi每天出破坏性版本浮动的 range 就是一根带电的线。执行者是 scripts/check-catalog.tspre-commit CI。豁免只有两类peerDependencies扩展包故意声明*依赖由宿主提供与本地协议workspace:/link:/file:。第三层AGENTS.md的维护纪律。例如改动移动或模糊了边界先改拥有该边界的 spec新增/删除/重命名用户可见能力或改动安装与分析行为时同步复核 README.md 中对应的主张。十、按文档落地从零验证这套描述以下是只读的验证路径不修改仓库任何内容。安装并运行用户视角# macOS / LinuxWindows 可用 Git Bash curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash # Windowscmd / PowerShell powershell -c irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex # 打开一个 git 仓库作为项目 thinkrail ~/code/my-repoCLI 需要 PATH 上有git和一个模型提供方应用内 JetBrains AI 登录或使用自己的 provider 凭据。thinkrail --help列出参数thinkrail --version打印构建版本。桌面版与 CLI 是两种可叠加的形态两者都携带SHA256SUMS发布Linux 桌面需要 glibc 2.38 与 GTK 3、WebKitGTK 4.1、Ayatana AppIndicator 3、librsvg 2。开发与验证贡献者视角bun run dev # 启动开发环境 bun run test # 单元测试根 scripts turbo run test bun run e2e # 无 agent 的浏览器全量套件 bun run e2e:full # 真实 provider token 的 live 套件先征得同意运行环境基线Bun1.4.4根packageManager固定CI 读取它而不是在 workflow YAML 里再写一份、TypeScript strict、React 19 Zustand Tailwind v4、进程内piNode 22.19。把文档读完的最短路径goal-and-requirements.md —— 产品目标与范围本文主体。architecture.md —— 拓扑、23 条决策、全仓不变量。按能力跳转packages/server/src/workspaces/SPEC.md隔离、packages/spec-graph/SPEC.mdspec 图谱、packages/server/src/reviews/SPEC.md评审、packages/pi-subagents/SPEC.md委派、apps/web/src/shell/layout/SPEC.md工作台。契约对照packages/contracts/src/domain.ts 与 packages/contracts/src/wsProtocol.ts —— 想知道「宿主到底能说什么」这里是唯一答案。十一、小结这份文档真正约束的是什么把 goal-and-requirements.md 读薄它其实只在约束三件事引擎只有一个进程内的pi因此所有功能都必须通过「喂」与「暴露」来实现不能自建循环、不能自算状态。隔离是默认worktree 分支 cwd因此「在项目目录直接干」必须是一个显式的、可命名的例外而不是滑落成的默认。意图要活过会话spec 图谱 可复用 skills因此文档、决策与不变量必须能被 agent 检索与维护——这正是这份文件自己采用 frontmatter 双链 分层 spec 的原因。其余的能力清单两个启动器、工作台、chat、plan、subagent、review、Open PR、MCP、语言、品牌都是这三条约束在具体界面上的投影而 Non-goals 只有两条且文档明确声明「未列出即开放」。对想评估或参与这个项目的工程师来说这是一份可以逐条对照源码验证的范围声明而不是一份宣传材料。赞分享【免费下载链接】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点击查看免费下载相关推荐agentic-awesome-skills 的 clean-code-guard命名与函数的十六条铁律实战指南agentic awesome skills 的 clean code guard命名与函数的十六条铁律实战指南 本指南以 clean code guardAI 技能AI 插件人工智能MooTool Next Compose 独立产品线开发指南面向 Cursor 的目标范围、架构边界与分阶段路线图MooTool Next Compose 独立产品线开发指南面向 Cursor 的目标范围、架构边界与分阶段路线图 本文以 MooTool 仓库中 next开发工具桌面应用MCP 服务OPA 管理 API 与架构构建围绕 Open Policy Agent 的统一策略控制平面OPA 管理 API 与架构构建围绕 Open Policy Agent 的统一策略控制平面 导读 本文是 OPAOpen Policy Agent管理能策略引擎认证鉴权后端云原生上一篇用ACE-Step 1.5生成你的第一首歌Gradio界面新手入门一步步指南下一篇SpinKit-ObjC完全指南UIKit中15种加载动画的终极实现方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考