T3 Code 项目设置指南环境 × 项目两级作用域、覆盖链与自动拉取【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文围绕 T3 Code 的“设置Settings”模块展开讲解其以环境Environment和项目Project为两轴的作用域模型如何在多个连接环境上批量修改配置、如何为单个项目覆盖默认值、如何通过层级图标追踪配置来源以及 Source Control 中自动拉取Automatically pull的触发条件。读完本文你将掌握 T3 Code 配置继承与覆盖的完整规则并能结合仓库源码定位每条设置背后实际的存储与同步逻辑。设置面包屑两个轴决定“改给谁”T3 Code 设置页的顶部面包屑结构为Settings / 分类 / 环境 / 项目其中环境与项目两个末级面包屑crumb决定了当前修改作用于谁。两者默认停留在All environments所有环境与All projects所有项目并且在切换分类或搜索设置时保持选中状态不会丢失当前的作用域上下文。只选中环境All projects当前修改会应用到所选环境上的所有项目再选中某个项目修改就变成该项目在所选环境上的项目覆盖project override。从源码看这一交互由 SettingsBreadcrumb.tsx 实现环境轴使用ALL_ENVIRONMENTS_VALUE作为“所有环境”的哨兵值项目轴使用ALL_PROJECTS_VALUE作为“所有项目”的哨兵值SettingsBreadcrumb.tsx#L164-L233。注释还点明了一个关键规则同一个项目在不同环境上是同一个项目因此环境面包屑单独决定了项目覆盖写入到哪个环境SettingsBreadcrumb.tsx#L54-L60。本地偏好与服务器设置的分界设置按存储位置分成两类保存在本机的偏好如外观 appearance、确认弹窗 confirmations、浏览器配置文件 browser profiles始终显示在当前值不受环境/项目选择影响其余所有设置都存储在服务器上因此需要选择作用域。针对服务器存储的设置你可以选择单个环境只编辑该环境的配置保持All environments一次批量编辑所有已连接环境的配置。注意离线环境保持其当前值不变——这是批量编辑不是“同步的全局默认值”。换句话说批量编辑是每个环境各自写一份新值未来新连接的环境并不会自动继承这次修改。项目覆盖、层级链与 Mixed 状态为某个项目设置覆盖值后该环境上的该设置将优先使用项目覆盖值。每行服务器设置标题旁会出现一个图层图标layers icon点击后可以查看该设置在所有选中环境上的“取值链”链条共三层内置默认值built-in default环境值environment项目覆盖project override。判断逻辑如下当所选环境的值不一致时控件不显示具体值而是显示Mixed且图层图标变为琥珀色。此时选择一个值会把它应用到每一个选中的环境项目中不能被覆盖的设置在选中项目时以只读read-only状态显示修改环境值永远不会触碰项目自己的覆盖。当你编辑的设置恰好被某些项目覆盖时图层图标会显示覆盖项目数量取值链中会逐个列出每个项目的值点击项目可直接跳转或使用Reset all让这些项目重新跟随环境值单个项目覆盖可通过Reset恢复为继承inherit环境值。这一“Mixed”交互在 UI 层有直接对应实现ProjectDefaultsSettings.tsx 通过useScopedSettingsMixed为defaultModelSelection、defaultRuntimeMode、defaultThreadEnvMode、enableAgentBrowserAccess、defaultAutoPull、pullRequestMergeMethod等设置计算混合状态并显示 “Mixed” 标签ProjectDefaultsSettings.tsx#L70-L76ScopedSwitch.tsx 则把同一套混合判定复用到开关类控件上。可以推断useScopedSettingsMixed的作用是当所选多个环境对该设置的值不一致时返回 true从而驱动 UI 呈现 Mixed 而非单一值。按机器的设置例外Providers提供商与 Diagnostics诊断是按机器per machine的设置它们同一时刻只展示一个环境默认展示主环境primary直到你手动切换不参与上述的多环境批量扩散其余所有设置才“扇出fans out”到当前的选择。默认值与继承各设置分类的职责选中不同面包屑时同一行编辑控件操作的对象会切换分类职责与作用域的关系General新线程new threads使用的模型model与工作区workspace同一切面既可编辑环境默认值也可编辑项目覆盖Integrations控制 agent 的浏览器访问agent browser access浏览器访问变更在 agent 会话下次启动时生效Source Control自动拉取Automatically pull、默认 PR 合并方式default pull request merge method、文本生成text generation同一切面既编辑环境默认值也可编辑项目覆盖Project选中项目时才出现项目的名称、图标、操作actions、检出版本checkouts与移除操作属于项目编辑会在每个选中环境上创建该项目自己的操作列表Reset 则回到环境共享列表工作区模式下的 t3.json在 workspace 模式下当项目没有覆盖时项目根目录的t3.json偏好preference生效——即t3.json是低于环境值、高于内置默认值的一层来源。t3.json的加载由服务端的 T3ProjectFileLoader.ts 完成该 Effect 服务专门加载仓库中检入的t3.json并解码其测试 T3ProjectFileLoader.test.ts 覆盖了“有效文件可加载、文件缺失返回 none”两类情况。t3.json项目的声明式配置仓库根目录的 t3.json 是该项目自身的声明式配置包含两个主要区域iconPath指向一个图片路径作为项目图标的来源T3 Code 桌面版与 Web 端均可识别scripts项目操作actions列表每个操作含name、command、icon并可通过runOnWorktreeCreate标记在创建 worktree 时自动运行。当前仓库的 t3.json 就定义了两个 Setup Worktree 脚本Unix 与 Windows 各一个用于把项目根目录的.env以符号链接方式同步到每个新 worktree并预热 Web 依赖缓存{ $schema: https://t3.codes/schema/t3.json, iconPath: assets/dev/blueprint-web-apple-touch-180.png, scripts: [ { name: Setup Worktree, command: vp i ln -sf $T3CODE_PROJECT_ROOT/.env .env ..., icon: configure, runOnWorktreeCreate: true } ] }这些操作可以在设置页的 Project 分类中导入import从而免去手工逐条录入。图标解析方面ProjectFaviconResolver.ts 的测试ProjectFaviconResolver.test.ts明确了几条规则t3.json中的iconPath优先于仓库内约定俗成的图标文件位置若iconPath指向的文件不存在则回退到约定位置非法的t3.json无法解析为 JSON会被忽略指向工作区根目录之外如../secret.svg的iconPath不会被解析防止路径逃逸。项目图标Project icons选中项目后进入Project分类即可修改图标支持三种来源图标icon内置图标集Emoji图片image可选用项目内的图片文件。选择结果会应用到项目组project group下的每一个 checkout并同步显示在已连接客户端上。若想恢复自动识别选择AutomaticT3 Code 会重新检测图标例如重新读取t3.json的iconPath或约定位置。保持默认分支最新Automatically pull在Source Control中开启Automatically pull自动拉取可以让默认分支default branch的 checkout 始终保持与其配置的上游upstream一致。该设置同样遵循两级作用域选中环境时设置的是默认值选中项目时则成为项目覆盖。T3 Code 执行自动拉取的前提非常严格只有在全部满足时才会拉取可以fast-forward快进checkout 没有已更改文件changed filescheckout 没有未跟踪文件untracked filescheckout 没有本地提交local commits。同时会跳过以下情况checkout 当前位于其他分支checkout 没有配置 upstream。如果 checkout 存在本地工作local work需要你自己先解决提交、暂存或清理自动拉取才能恢复。该设置在服务端有完整的持久化与启动链路可以作为验证依据数据库迁移 045_ProjectionProjectsAutoPull.ts 为项目投影表新增auto_pull列INTEGER NOT NULL DEFAULT 0项目投影持久化层 ProjectionProjects.ts 负责读写该字段服务器启动阶段在projects.auto-pull阶段调用syncAutoPullProjects同步该设置serverRuntimeStartup.ts#L830-L886投影快照查询层 ProjectionSnapshotQuery.ts 将auto_pull列映射为autoPull字段其相关测试 decider.projectThreadEnvMode.test.ts 验证了autoPull通过事件meta.update传播进读模型并持久化的完整链路。从上述链路可以看出自动拉取不是一个前端定时器的装饰性功能而是从设置写入、投影持久化到服务器启动恢复的端到端能力。小结一条配置的完整旅程把上面各部分串起来一条“项目级覆盖”设置从写入到生效的旅程是在设置页通过环境与项目两个面包屑确定作用域SettingsBreadcrumb.tsxUI 通过useScopedSettingsMixed判断多环境取值是否一致不一致则显示Mixed与琥珀色图层图标ProjectDefaultsSettings.tsx服务器端将设置写入项目投影auto_pull、scripts_json等列见 ProjectionProjects.ts 与迁移脚本服务器重启时在projects.auto-pull启动阶段恢复设置serverRuntimeStartup.ts#L830-L886取值时按“内置默认值 → 环境值 → 项目覆盖含t3.json偏好”的链条解析图层图标展示来源Reset / Reset all 恢复继承。理解这套“环境 × 项目”的两轴模型是高效管理多环境、多仓库工作区配置的前提既能避免在每台机器上重复手工配置也能为单个项目精准定制行为而不污染其他项目。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考