设置与项目覆盖¶

在 Web 和桌面端，设置页面顶部的“正在应用设置到 …”这句话会决定更改应用于哪个项目和环境。仅包含设备偏好设置的页面（如“外观”）不显示此句。它们会从所有项目和所有环境开始，并在你在类别间移动或搜索设置时保持选中状态。

保存在此设备上的偏好设置（如外观、确认和浏览器配置文件）始终显示并忽略此选择。其他所有内容都存储在服务器上。选择一个环境来编辑其设置，或保持所有环境以一次编辑所有已连接的环境。离线环境会保留其当前值；这是批量编辑，而非同步的全局默认值。

选择一个项目，即可在选定环境中对该项目进行设置覆盖。每个服务器行标题旁的图层图标会显示值的来源：内置默认值、环境或项目覆盖。点击该图标可在所有选定环境上查看该链。覆盖项可以重置以重新继承。当选中项目时，无法由项目覆盖的设置会以只读方式显示。

当所选环境的值不一致时，控件会显示混合而非某个值，图层图标会变为琥珀色。选择某个值会将其应用到所有选定环境。

更改环境值绝不会动到项目自身的覆盖。当项目覆盖了你正在编辑的设置时，图层图标会对其进行计数，链中会列出每个项目及其值：点击某个项目即可跳转到它，或点击全部重置让这些项目重新跟随环境。

提供商和诊断信息按机器区分：它们一次只显示一个环境，在你选择另一个之前显示主环境。其他所有设置都会扩展到你选择的目标。

当选中项目时，设置 → 提供商中的提供商开关可以仅针对该项目打开或关闭，无论方向如何：机器上关闭的提供商可以在某个项目中使用，而到处都开启的提供商也可以被排除在另一个项目之外。该项目的模型选择器会跟随此开关，并且在该项目上，任何新的回合都不能在被它关闭的提供商上启动，包括排队中的消息和来自委派任务的后续操作。开关翻转时已在运行的回合会继续运行完毕。委派任务的结果仍会到达其父线程，父线程会在下一次回合时看到它。重置会让该项目回到机器的设置。所有其他提供商设置仍按机器保留。

在移动端，打开设置并使用其标题栏中的筛选器来选择已连接的环境和项目。该筛选器在服务器设置页面中仍然可用。选择所有项目时，服务器设置页面（如线程、源代码管理和工作树）会编辑所选环境的默认值。选择某个项目则会在所选环境上编辑其覆盖。在页面中使用使用默认值可移除该页面的项目覆盖。打开设置 → 项目，可在其选中的已连接检出之间重命名项目，并查看这些检出的位置。当选中项目时，环境范围的设置保持只读。当所选目标不一致时，控件会显示混合，直到你选择一个值。外观、键盘和其他仅限手机设置会忽略此筛选器。

固定与归档项目¶

固定项目在项目选择器中排在前面：新建线程时的项目选择器、新线程列表、命令面板、侧边栏项目筛选器以及移动端。在常规侧边栏中，固定项目会获得顶部文件夹，即使没有活动线程。在这些列表中的任意一行上可固定或取消固定项目，或在高亮行上按线程固定快捷键（默认 mod+shift+p）。命令面板中的固定项目以及设置 → 项目也可以。列表在打开期间会保持顺序，因此新固定的项目会在下次打开时上移。

在设置 → 项目中归档你已完成的项目。它会从项目选择器中移出。其线程、设置和文件保持原样，已归档项目仍会显示在设置项目列表中，并标记为已归档。在那里选择一个项目并选择取消归档即可将其恢复。在移动端，两者都在设置 → 项目 → 组织中。

要在多台机器上固定或归档一个项目，必须让所有机器都已连接。

工作树分支名称¶

在设置 → 工作树 → 工作树分支命名中，选择一个静态前缀、模型选择的语义前缀（如 feat/ 或 fix/），或用于完整名称的自定义指令。静态前缀默认为 t3/；尾部斜杠可选，空前缀则不会添加任何内容。静态前缀中的无效字符会被替换为连字符。自定义指令会附加到命名提示中，并可指定问题 ID、命名空间和大小写。

这些设置适用于自动命名的新工作树分支。选择项目可覆盖其环境默认值。工作树目录会保留其原始名称。如果生成失败，或自定义名称无效或已被占用，则会保留临时分支名称。

移动端定时任务¶

打开设置 → 定时任务，可在已连接的环境中创建定时任务或管理现有任务。使用设置筛选器按环境或项目缩小列表范围。每个任务在你选择的环境上运行，并使用该环境的项目、模型和工作区设置。固定时间计划使用该环境的时区，可能与手机时区不同。选择一次可在你自己的时区的某个日期和时间运行一次任务。如果届时环境处于离线状态，则任务会在其恢复后运行。

在目标位置下，选择运行结果的去处。每次运行新建线程会保持每次运行相互独立。两个单线程选项会在首次运行时启动一个线程，并将后续运行发布到该线程：其中一个会继续同一对话，另一个则会在每次运行时启动一个不查看先前运行的新会话，因此线程保持可读，而代理的上下文不会增长。要移动单线程任务，可在目标位置下选择其项目中的另一个线程。将此类任务移动到另一个项目后，会在下次运行时在那里启动一个新线程。

删除线程也会删除发布到该线程的任务。每次运行都开启新线程的任务在之前的线程被删除后依然存在。

你可以从列表中编辑、暂停、恢复、立即运行或删除任务。Webhook 任务只会在其 URL 被调用时运行，因此无法立即运行。离开已编辑的表单时，系统会询问是否放弃未保存的更改。

Webhook 自动化¶

在设置 → 计划任务中，选择按 Webhook作为任务的计划，以便在其他服务调用其 URL 时运行该任务，例如 GitHub 收到新拉取请求或 CI 作业失败时。公共 URL 需要由 T3 Connect 管理的隧道；保存任务后，从编辑器中复制其 URL。如果没有隧道，编辑器只显示 URL 的路径。轮换会替换 URL，旧的 URL 将停止工作。

提示词决定智能体能看到什么。占位符从请求中提取值：{{body.path}} 用于 JSON 或表单字段，{{headers.name}}、{{query.name}}、{{body}} 用于原始请求体，{{request}} 用于所有内容。例如，Review this PR: {{body.pull_request.html_url}} 只发送拉取请求链接。没有值的占位符会保持为空。

每个值都以 <webhook-data-…> 标签包裹并标记为不受信任的请求数据，再传递给智能体。这有助于智能体将其与你的指令区分开来，但并不保证智能体不会按照文本内容行事。在值内部，每个 $、其他货币符号和 @，以及位于独立单词开头的 /，其后都会被添加一个不可见字符，因此 $skill、@file 和 /command 之类的提及不会生效。从值中复制的文本（如电子邮件地址或命令）也会携带该字符。没有签名时，任何拥有 URL 的人都可以用任意内容启动一次运行。签名只能证明请求来自哪个服务：GitHub 的 payload 仍然可能携带任何 GitHub 用户编写的文本。

对于 GitHub，请开启要求签名，保留标头 x-hub-signature-256、十六进制编码和 sha256= 前缀，并在仓库的 webhook 设置中输入相同的密钥，内容类型为 application/json。没有有效签名的请求将被拒绝。请在桌面端或网页端进行设置；移动端会保留现有的签名检查，但无法开启新的签名检查。

若要只对某些请求运行，请添加过滤器。每个过滤器测试一个类似占位符命名的值（不带花括号），例如 headers.x-github-event 等于 pull_request，或 body.action 是 opened, reopened 之一。只有当所有过滤器都匹配时任务才会运行；其他请求会正常响应，并记录为已过滤，同时标注第一个未通过的过滤器，且不会启动任何任务。值以文本形式比较，值为对象或列表时只能通过存在检查。是其中之一的值用逗号分隔；值不能包含逗号，也不能以空格开头或结尾。

若要抑制重复投递，请设置重复请求键模板，例如 {{headers.delivery-id}}。每个任务在七天内会忽略相同的键。若要合并突发请求，请设置合并键，例如 {{body.id}}，以及一个 10–3600 秒的时间窗口（默认 120 秒）。当第一次投递的窗口关闭时，一次运行会使用最新的请求体、标头和查询参数；之后的请求不会延长窗口。挂起的窗口在服务器重启后仍然保留。键必须包含请求占位符；如果任何占位符缺失或渲染结果为空，则跳过该键的规则。清除模板即可关闭去重。

重复和合并的日志条目共享每个任务每分钟 10 条的限制。额外的投递会被接受但不记录日志，合并投递始终替换已保存的 payload。合并更新计入单独的每分钟 60 次验证限制；超过该限制会收到 HTTP 429。

在桌面端和网页端，从任务的菜单中选择投递，即可查看最近的请求以及每次请求生成的提示词。

如果环境处于离线状态，发送方会收到错误，且不会有任何任务运行；待环境恢复后，从发送方重新投递，例如 GitHub 的最近投递。若要改为让 T3 Connect 保留请求，请在设置 → 共享与访问中开启离线时保留 webhook。T3 Connect 随后会将发送到 T3 Connect URL 的请求存储最多 24 小时，并在环境恢复后投递。如果你不希望请求体存储在机器之外，请保持关闭。若要跳过等待过久的请求，请在任务上设置跳过早于的请求。

默认值与继承¶

线程类别包含新线程的模型和工作区。浏览器控制智能体的浏览器访问权限。源代码控制包含自动拉取、默认拉取请求合并方式和文本生成。根据项目面包屑中当前选中的项目，相同的行可以编辑环境默认值或项目覆盖值。

代码下的项目类别包含项目的名称、图标、操作、检出和移除。操作属于项目：编辑它们会在每个选定的环境中创建项目自己的列表，重置则恢复为环境的共享列表。项目的 t3.json 操作可以在此处导入。

仓库也可以在 t3.json 中声明的设置（例如新线程的工作区）按以下顺序解析：项目覆盖值，然后是环境设置，再是 t3.json，最后是内置默认值。将设置保留为继承，以让下一级决定。浏览器访问的更改会在智能体会话下次启动时生效。

新建 worktree 会递归初始化 git 子模块。如果因为仓库声明了许多嵌套子模块而导致此步骤缓慢，请在设置 → Worktrees 的高级选项下将子模块设置为仅顶层（在该处选择项目以覆盖设置），以在仓库自身声明的子模块处停止，或设置为跳过以留给设置脚本处理。它的解析顺序与工作区默认值相同：当项目和环境都处于继承状态时，正在检出的分支的 t3.json 中的 "worktreeSubmodules" 值会生效。

Worktree 位置¶

新的 worktree 位于 T3 主目录的 worktrees 文件夹中。要将它们放在其他位置（例如另一个驱动器），请将设置 → Worktrees → Worktree 位置设置为绝对路径，如 D:\worktrees 或 ~/worktrees。该设置为每台机器单独生效。现有的 worktree 保持原位，清理操作会同时覆盖默认文件夹和自定义文件夹。

在 macOS 上快速工作树检出¶

快速工作树检出是一项测试版功能。请在每台 Mac 上通过 设置 → 实验室 → 快速工作树检出 开启。开启后，T3 Code 会在 T3 主目录的 caches 文件夹中保留每个仓库最近几次的检出。新的工作树会通过 APFS 写时复制从其中一个检出克隆而来，这比逐文件写入大约快两倍，并且也能让工作树中的首次 git status 更快。关闭该功能会删除缓存。

仓库的首次检出会使用 Git 的正常检出流程，并填充缓存。这需要 Git 2.42 或更高版本。对于位于与 T3 主目录不同驱动器上的工作树、稀疏检出、属性使用过滤器（如 Git LFS）的仓库，以及检出设置发生变化的仓库，也会使用 Git 的正常检出。

存储清理¶

打开 设置 → 工作树 → 清理，即可在一台机器或所有已连接环境中启用自动清理。策略默认关闭，并会在服务器启动时、策略变更时以及每小时运行一次。离线机器会保留其现有策略。

选择项目以将 自动工作树清理 设置为 继承、关闭 或 自定义。继承会遵循每台机器的规则；关闭会保留该项目的所有工作树，直到你手动移除它们。自定义会将单独的工作树规则应用于所选项目或检出。浏览器捕获和日志保留仍然按机器全局生效。

工作树可以在达到指定的非活动天数后、当对话完结后、合并后，或者当它们除了默认分支外没有其他提交时被移除。将完结保留期设置为 0 天，可在对话完结后的下一次清理时移除工作树。在没有远程仓库的仓库中，未更改工作树清理会与项目工作区中检出的分支进行比较；如果该检出处于分离 HEAD 状态，则工作树会被保留。只有由 T3 管理的工作树才符合条件。活动会话和共享工作树会阻止移除。保留有本地更改的工作树 默认为 未提交的更改，这会保护已跟踪的编辑和未跟踪的文件，但会删除被忽略的文件，例如 .env 和构建输出。任何本地文件 还会保护除 node_modules 之外的被忽略文件。已编辑的已跟踪文件 仅保护已跟踪的编辑，并允许删除未跟踪和被忽略的文件。分支和对话历史会保留；开始另一轮对话会重新创建检出。合并清理需要合并的 PR 其提交已包含在远程默认分支中。在 GitHub 上，如果 PR 针对的是默认分支，且工作树仍停留在该 PR 的最新提交，那么压缩合并或变基合并也算数。

启用 删除已删除对话对应的工作树 可在其最后一个对话被删除后移除安全的工作树，包括已归档的对话以及先前删除操作遗留的工作树。服务器会等待会话和终端停止，并在重启后重试被跳过的工作树。当此策略关闭时，现有的手动删除工作树提示仍然可用。

选择 立即删除 可立即运行已启用的规则。最新结果会显示哪些工作树被移除或保留及其原因，以及任何失败情况。结果还会列出工作树文件夹中没有对话使用的文件夹及其大小；清理永远不会移除它们，因此如果你需要，可以手动删除。

浏览器捕获和轮转日志有独立的保留期。过期的捕获链接将失效。当前日志、消息附件和浏览器配置文件会被保留。

项目图标¶

选择项目并打开“项目”，即可选择图标、表情符号、字母组合或图片。该选择适用于项目组中的每一个检出，并会显示在已连接的客户端上。选择 自动 可让 T3 Code 重新检测图标。

在图标选择器中选择 字母组合，可设置一两个字母或数字以及一种颜色。

当找不到图片时，Web 和桌面端会显示一个双字符字母组合，其颜色来自图标调色板，并根据保存的项目名称生成。例如，Nebula 变为 NA，Silver Orchard 变为 SO，M7 Forge 变为 M7。

保持默认分支为最新¶

在“源代码管理”中，启用 自动拉取，以保持默认分支检出与其配置的上游同步更新。选择一个环境来设置默认值，或选择一个项目来覆盖默认设置。在移动端，使用 设置 → 源代码管理 更改所选环境的默认设置或项目覆盖。

T3 Code 仅在能够快进，且检出没有已更改文件、未跟踪文件或本地提交时才会拉取。它会跳过位于其他分支或没有上游的检出。如果检出有本地更改，请先自行解决，然后自动拉取才能恢复。