调试

开放是一个实际的优势：代码可用，你可以本地运行它，并且可以使用编程智能体更快地回答问题并调试代码库中潜在的 bug。

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

在 CI 上捕获线程转储

当 CLI 间歇性挂起时，你可以捕获线程转储而无需停止进程。启用信号处理器并向正在运行的 tuist 进程发送 SIGUSR1。

export TUIST_THREAD_DUMP_SIGNAL=1
export TUIST_THREAD_DUMP_SAMPLE=1 # 仅 macOS，通过 /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，了解为什么会发生这种情况。追踪生成器管道并指出负责该输出的代码路径。

生成项目中的可复现 bug

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