T3 Code 卡在 Preparing workspace：先查准备脚本、Shell 和已保存的 Action
新建 T3 Code Worktree 一直等待时，按 Git 创建、准备命令、完成状态和配置来源排查，核对 t3.json 导入、同步 Action 与实际执行目录。
新建 T3 Code 线程后，一直显示 Preparing workspace，Agent 迟迟不开始。先打开准备脚本的终端，确认它正在下载依赖、等你输入，还是已经报错回到提示符。这个状态可能停在不同阶段，单看加载动画判断不了原因。
先找实际执行的命令和输出，再核对目录、Shell 与已保存的 Action。 改了仓库里的 t3.json 后，也要确认当前项目、当前机器上的 Action 是否采用了新内容。
本文按 2026 年 11 月 9 日查阅的 T3 Code v0.1.7 正式版说明；当天 latest stable 仍为此版本。文中提供一个只读诊断 Action，帮助缩小问题，不把未合并建议当作通用修复。
先看卡在创建目录，还是运行准备命令
| 看到的线索 | 先查什么 | 下一步 |
|---|---|---|
git worktree add、分支已存在或检出失败 | 目标分支、现有 Worktree、起始提交 | 检查 Git 状态与目录，不先改模型 |
| 准备终端持续输出安装或下载日志 | 依赖源、网络、是否等待交互 | 找最后一条有效输出与实际运行进程 |
| Shell 已报语法错误，但界面仍等待 | 命令是否适合实际 Shell、完成状态是否返回 | 保留原始报错，先修命令解析 |
| 文件已修改，终端仍执行旧命令 | 当前项目和环境保存的 Action | 对照并更新已保存内容 |
如果还不确定线程使用哪份代码，先读 T3 Code 的线程与 Worktree 检查。这篇继续处理“目录已分开，准备阶段为什么仍过不去”。
也有与 Shell 不同的报告。Issue #26577描述一次 nightly 版本中分支冲突被很晚才显示的情况，作者没有给出确定复现步骤，并注明由 AI Agent 基于历史记录整理。它不能证明普遍存在同一种等待问题，但提醒我们不要把所有 Preparing workspace 都归为安装慢或 Shell 出错。
Shell 能解析命令，与 T3 能收到结束状态，要分别检查
Issue #32556提供了一个具体例子：v0.1.7、macOS、fish 4.3.2 下，准备 Action 使用了 fish 无法解析的 Bash 写法，例如 ${VAR:-fallback}。作者报告，终端已经提示语法错误，线程仍等在准备阶段。
这里至少有两件事：
- 项目命令本身要适合实际 Shell。 Bash 的变量展开不能直接当作 fish 或 Nushell 语法。你平时在某个终端里运行成功，不代表 T3 启动的终端使用同样的解释器和环境。
- 同步准备还需要把结束状态交回 T3。 v0.1.7 的准备脚本实现会根据 Shell 包一层命令，并读取带退出码的完成标记。命令未正常解析时，不能只凭终端看起来空闲就断定这一步已经被 T3 识别为结束。
Issue #24423则涉及 Nushell。作者后来修正了“必然是语法错误”的早期说法：在所测版本中，有时命令执行了，但完成标记携带的是字面量 $?，而非数字退出码。11 月 2 日的回复提供了本地补丁与验证记录；截至本文查阅日，Issue 仍为 Open，不能据此认定正式版已经修好。
因此，把项目命令改成 bash -c '...' 或 sh ...，可以帮助明确子命令的解释器，却不一定改变 T3 在外层终端生成的完成包装。尤其遇到 Nushell 相关报告时，不要把“脚本能单独执行”直接写成“线程准备已经恢复”。
本文核对了正式版源码中的包装选择和退出码文本，并在本地执行了 POSIX 包装的成功、失败例子；没有安装 fish、Nushell，也没有启动 T3 客户端复现这两条完整故障。
改了 t3.json，为什么还执行旧命令
T3 Code 的项目设置说明将 Actions 放在项目设置下，支持从 t3.json 导入。文档也说明，设置有项目与环境的作用范围；多台机器选在一起时，修改可能作用于多个目标，离线环境则保留原值。
排查时先选中出问题的项目和环境，再到 Settings → Projects 查看实际 Action：
- 命令是否和当前
t3.json的scripts项相同。 - 需要准备时运行的项，是否启用了
runOnWorktreeCreate。 - 同步等待设置是否符合预期；是否还保留另一条旧的准备 Action。
#32556 的作者报告，修改仓库文件后，已导入的 Action 仍保存旧命令。其绕过方法是重新导入或编辑保存的 Action。本文没有独立复现这种漂移，因此建议先对照两份内容；需要重新导入时，先保留现有 Action 的自定义内容，核对导入后的列表，不把“导入”当作持续同步承诺。
另外，正式版脚本选择实现取第一个 runOnWorktreeCreate 为真的脚本。排查时保留一个清楚的准备入口，必须顺序完成的步骤由这个入口组织，不能假定多条准备 Action 会依次运行。
项目工作区等可由 t3.json 声明的设置，文档给出的来源顺序是项目覆盖、环境设置、仓库文件、内置默认。Actions 则要额外查看保存的列表，不能只用这条顺序猜当前运行了哪段命令。
用一个只读 Action 缩小范围
下面示例用于 macOS／Linux、已安装 Git 和 Node、存在 sh 的环境。它不安装依赖、不写项目文件，只输出当前目录、分支、文件状态和 Node 位置。诊断通过只说明这些检查能完成，不代表项目依赖已经准备好。
在示例仓库添加 scripts/check-worktree.sh：
#!/bin/sh
set -eu
printf 'setup cwd: %s\n' "$(pwd)"
git rev-parse --show-toplevel
git branch --show-current
git status --short
command -v node
node --version
在 t3.json 中合入下面的 scripts 项，保留项目已有的其他配置：
{
"$schema": "https://t3.codes/schema/t3.json",
"scripts": [
{
"name": "Check workspace",
"command": "sh scripts/check-worktree.sh",
"icon": "configure",
"runOnWorktreeCreate": true,
"async": false
}
]
}
让该脚本与配置进入你准备作为起点的提交。新 Worktree 不会自动带上主目录里尚未提交、未跟踪的脚本；若任务依赖未发布提交，确认起始分支包含它们。
随后在出问题的项目与环境检查或导入 Action，先在预期工作目录单独运行：
sh scripts/check-worktree.sh
应看到自己的 Worktree 路径、任务分支和 Node 版本。路径包含空格时也要核对结果。若找不到脚本，先检查起点和实际目录；若找不到 Node，先修这台机器上该终端能取得的工具路径。
该示例通过后，再用一个小任务验证 T3 能否完成准备并启动 Agent。若独立运行成功、T3 仍等待，就保留两边的输出，继续查外层 Shell 与完成状态，不要马上换模型。
async: false 应放什么命令
v0.1.7 的配置定义说明，准备脚本的 async 默认是 true，Agent 可以与脚本同时开始；设成 false 则等待脚本退出。
示例显式使用 false，让准备检查先结束。真实项目需要 Agent 启动前安装好依赖、生成文件或完成迁移时，应让准备命令有明确的成功和失败出口。不要把会长期运行的开发服务器放进同步准备里，否则等待它退出可能正是配置要求的行为。
反过来，只为消掉加载状态就改成 async: true，可能让 Agent 在依赖还没准备好时开始。应按项目先后关系决定，而不是用它掩盖未知失败。规则文件与操作脚本的分工可参考 AGENTS.md 与 Skills。
恢复之前，留够这些记录
停止等待或重新尝试之前，保存：
- T3 版本、运行机器和实际终端 Shell；不要只用另一个终端的
$SHELL变量代替核对。 - Worktree 路径、分支、HEAD 和
git status --short，确认没有归属不明的改动。 - 当前环境保存的 Action、仓库文件中的对应项，以及终端最后的完整错误。
- 是命令没开始、仍在运行、已报错，还是命令执行完但界面没有前进。
T3 的终端历史文档说明，服务端历史最多保留 5,000 行与 8 MiB，先达到哪个就按哪个淘汰旧内容。长时间重试可能挤掉真正的第一条错误，应及时保存必要片段；对外分享前删除密钥、私有路径和下载链接。
如果准备脚本有迁移、拷贝或其他写入，先判断上次执行到了哪一步，再重跑。不要直接删 Worktree、恢复全部文件或让多个任务同时重新准备。先在小任务上验证“目录正确、准备退出、Agent 开始”，再恢复正式工作。
准备完成后若才出现模型接口报错，转到接入基础核对实际协议与地址；对费用或缺失记录有疑问，再按 T3 Code 用量核对检查。Preparing workspace 本身不足以判断是否已经调用模型或发生费用。
