一、添加外部文件夹到 Xcode
目标 ：将外部工程 AgentHarness 关联到当前 Xcode 工程，仅作为导航引用，不参与编译和打包。
操作步骤
- 在 Xcode 左侧 Project Navigator 中，右键点击目标位置（如 TechEDUiOS 根组）
- 选择 "Add Files to 'TechEDUiOS'..."
- 在弹出的文件选择器中，导航到目标文件夹： /Users/edu/Desktop/Code/AgentHarness/V2.1.8/AgentHarness
- 配置以下选项：
选项 选择 说明 Action Reference files in place 不拷贝文件，仅引用原始路径 Added folders Create folder references 蓝色文件夹，不参与编译 Add to targets 全部取消勾选 不关联任何 Target - 点击 Add 完成
效果
- Xcode Navigator 中出现蓝色文件夹图标
- 可浏览和编辑，但不出现在 Compile Sources / Copy Bundle Resources 中
- .app 和 .ipa 中不会包含
二、创建软链接（使 Trae 编辑器可见）
背景
Xcode 的 Folder Reference 是外部路径引用，文件未拷贝到项目目录，Trae 的文件树只能看到项目磁盘目录内的内容，因此需要创建软链接。
操作命令
cd /Users/edu/Desktop/Code/ios-mobile
ln -s /Users/edu/Desktop/Code/AgentHarness/V2.1.8/
AgentHarness ./AgentHarness
更新 .gitignore
在 .gitignore 末尾追加：
## AgentHarness symlink (external reference, not part
of project source)
AgentHarness
避免 Git 追踪这个外部软链接。
效果
- Trae 文件树中出现 AgentHarness 目录
- Xcode 引用和 Trae 浏览互不影响
- 编译和打包不受任何影响（三重保障：Folder Reference + 不勾选 Target + CocoaPods 未引入）
三、删除软链接
当不再需要该外部目录关联时：
删除软链接
rm /Users/edu/Desktop/Code/ios-mobile/AgentHarness
``` ⚠️ 此操作仅删除软链接本身， 原始文件毫发无损 。
### 清理 Xcode 引用
在 Xcode 的 Project Navigator 中找到蓝色文件夹 V2.1.8 ，选中按 Delete ，选择 "Remove Reference" （仅移除引用，不删除文件）。
### 清理 .gitignore（可选）
删除 .gitignore 中此前添加的 AgentHarness 条目，或保留均可。
## 四、原理总结
概念 图标 参与编译 参与打包 Group（黄色文件夹） 🟡 取决于是否勾选 Target 取决于 Build Phase Folder Reference（蓝色文件夹） 🔵 ❌ 不参与 ❌ 不参与 软链接（Symlink） 🔗 ❌ 仅文件系统层面 ❌
核心原则：Xcode 只编译和打包 明确出现在 Target Build Phase 中的文件，Folder Reference 不属于任何 Build Phase，软链接更是 Xcode 不感知的文件系统概念，两者都不会对产物产生任何影响。
