调试

开源带来实际优势：代码公开可用，你可以在本地运行，还可以借助编码智能体更快解答疑问并排查代码库中的潜在缺陷。

如果在调试过程中发现文档缺失或不完整，请更新 docs/ 下的英文文档并提交 PR。

在 CI 上捕获线程转储#

当 CLI 间歇性卡顿时，你可以在不终止进程的情况下捕获线程转储。启用信号处理程序并向正在运行的 tuist 进程发送 SIGUSR1。

bash

export TUIST_THREAD_DUMP_SIGNAL=1
export TUIST_THREAD_DUMP_SAMPLE=1 # macOS only, captures all threads via /usr/bin/sample
tuist generate &
TUIST_PID=$!
sleep 600
kill -USR1 "$TUIST_PID"
wait "$TUIST_PID"

如果未设置 TUIST_THREAD_DUMP_SAMPLE，处理程序会打印当前线程堆栈。输出写入 stderr，因此会出现在 CI 日志中。

使用编码智能体#

编码智能体适用于以下场景：

扫描代码库，定位实现某一行为的位置。
在本地复现问题并快速迭代。
追踪输入在 Tuist 中的流转路径，找到根本原因。

提供尽可能最小的复现示例，并将智能体指向具体组件（CLI、服务器、缓存、文档或手册）。范围越聚焦，调试过程就越快、越准确。

常用提示词（FNP）#

项目生成结果不符合预期#

项目生成的结果与预期不符。针对位于 /path/to/project 的项目运行 Tuist CLI，以了解发生这种情况的原因。追踪生成器流水线，并指出负责该输出的代码路径。

生成项目中可复现的缺陷#

这看起来像是生成项目中的缺陷。在 examples/ 下创建一个可复现的项目，参考现有示例。添加一个失败的验收测试，仅选择该测试并通过 xcodebuild 运行，修复问题后重新运行测试以确认通过，然后提交 PR。