审计并渐进启用 Xcode 安全构建设置（编译器警告…

当需要为 Xcode 项目做安全加固、审计构建配置的安全态势、启用静态分析与更严格的编译期诊断时使用。

适用场景

解决思路

1. 优先使用 Xcode 专用工具：用 XcodeGlob 做文件发现（禁止用 find）、XcodeGrep 做内容搜索（禁止用 grep/rg）、XcodeRead 读文件（禁止用 cat/Read）、XcodeLS 列目录（禁止用 ls）；仅对 Xcode 工具无法完成的操作（如 plutil 编辑 plist、git 操作）才回退到 Bash。
2. 不要用 ls 去“验证”项目结构：项目根目录、项目名、活动 scheme 已在系统提示上下文中，直接使用。
3. XcodeGlob 返回 0 个 .xcodeproj 匹配不是失败：.xcodeproj/.xcworkspace 不被索引为项目内文件，改用系统上下文中的项目名，不要回退到 ls/find。
4. 路径转换：XcodeGlob 返回项目组织相对路径，优先用 XcodeRead/XcodeUpdate 处理；若被拒绝（如 .entitlements 等 plist 无法通过项目路径访问），用系统上下文中的项目根目录拼成文件系统绝对路径，再用 Read/Edit，不要用 find 查找磁盘路径。
5. 开始前先向用户打印工作流计划（Phase 1 分析项目与现有设置、Phase 2 应用设置含 Step 1 Enhanced Security 与 Step 2 基础 Clang 安全警告、Phase 3 询问被禁用的设置、Phase 4 验证已应用设置、Phase 5 报告并更新决策文档、Phase 6 可选后续步骤），并调用 TaskCreate 创建同样的任务项。
6. 进入每个阶段或子步骤时打印一行 “▶ Phase N: …” 并把任务置为 in_progress；完成时打印一行 “✓ Phase N: …”（可附简要结果）并置为 completed；Phase 6 初始为单个任务，用户选择某项后续步骤时打印 “▶ Phase 6 / <name>” 与 “✓ Phase 6 / <name>” 并创建/更新对应子任务。
7. Phase 1（静默收集事实，无用户交互）：用 XcodeGlob/Glob 查找 .xcodeproj 或 .xcworkspace；查找已有决策文档（**/xcode-security-settings.md），若找到则读取并提取语言与所有既往设置决策及其状态和理由。
8. Phase 1：通过 XcodeGlob/Glob 检测语言——**/*.c 为 C、**/*.cpp、**/*.cxx、**/*.cc 为 C++、**/*.m 为 Objective-C、**/*.mm 为 Objective-C++、**/*.swift 为 Swift。
9. Phase 1：枚举各 target 及其 entitlements 文件——记录每个 target 的 product type、平台（通过 SDKROOT / SUPPORTED_PLATFORMS），并把 CODE_SIGN_ENTITLEMENTS 解析为磁盘上的 .entitlements 路径（按配置区分，若不同）；使用 GetTargetBuildSettings 时参考 references/reading-build-settings.md 的输出 schema 与大结果处理配方。
10. Phase 2 应用设置前先检查现有安全设置：在 pbxproj 和 xcconfig 文件中 grep 目录（references/settings-and-entitlements-catalog.md）里的设置，只应用尚未设置的；若全部已启用则告知用户并停止。
11. 应用构建设置的方式：项目用 .xcconfig 文件则直接编辑 xcconfig（支持项目级和 target 级）；项目仅用 .pbxproj 则用 UpdateTargetBuildSetting 设 target 级、UpdateProjectBuildSetting 设项目级；混合时若 target 有 .xcconfig 就编辑它，否则用 Xcode 构建设置工具；绝不引入新的配置方式。
12. 尽量用项目级设置（减少重复），项目不用 xcconfig 时回退到 UpdateTargetBuildSetting 设 target 级。
13. 例外：ENABLE_ENHANCED_SECURITY 必须在项目级设置——用 xcconfig 就写在 xcconfig，否则用 UpdateProjectBuildSetting。
14. Phase 2 Step 1：从 Phase 1 的 target 映射中跳过 product type 不在 references/enhanced-security.md “Supported Product Types” 列表中的 target，剩下的为“受支持 target”；注意 DriverKit target 仅支持构建设置，跳过其 entitlement 变更。
15. Phase 2 Step 1：审计每个受支持 target——收集 ENABLE_ENHANCED_SECURITY 和 ENABLE_POINTER_AUTHENTICATION 的值（先看 target 级，再看项目级继承）；对非 DriverKit target 读取 entitlements 文件并收集 com.apple.security.hardened-process* 下的所有键（含已弃用键）；对照 references/enhanced-security.md Part B 的必需键与默认开启键，把每个 target 归为：Up-to-date（无需处理）、Partial（ENABLE_ENHANCED_SECURITY 为 YES 但缺默认开启子选项、或含已弃用键、或版本为 "1"/存在已弃用版本键）、Off（ENABLE_ENHANCED_SECURITY 缺失）、No entitlements file（受支持但尚无 .entitlements 文件，用户确认应用后创建）。
16. 重要：若项目有任何非源码形式的二进制依赖（frameworks、xcframeworks、Swift Packages），不要启用 pointer authentication；列出这些依赖并建议用户联系依赖供应商获取同时包含 arm64 和 arm64e 的 Universal binary。
17. Phase 2 Step 1：为每个 Partial 或 Off 的受支持 target 按此顺序构建变更集（省略空段）——新增 entitlements：缺失的必需键（com.apple.security.hardened-process、...enhanced-security-version-string = "2"）和缺失的默认开启子选项（hardened-heap、dyld-ro、platform-restrictions-string = "2"）；移除 entitlements：已弃用键（...platform-restrictions、...enhanced-security-version）；更新 entitlements：版本字符串 "1" → "2"（若存在）。
18. 若受支持 target 没有 .entitlements 文件，把创建该文件并在变更集中接好 CODE_SIGN_ENTITLEMENTS。
19. 构建设置：按上述“应用构建设置的方式”执行；项目用 xcconfig 就在其中项目级设 ENABLE_ENHANCED_SECURITY = YES，否则用 UpdateProjectBuildSetting。
20. 由于项目级 ENABLE_ENHANCED_SECURITY = YES 会把 ENABLE_POINTER_AUTHENTICATION = YES 级联到每个 target，需预先在每个平台不支持 arm64e 的 target 上写入 target 级 ENABLE_POINTER_AUTHENTICATION = NO 覆盖（通过 SDKROOT / SUPPORTED_PLATFORMS 判断）；若该 target 已有显式 target 级值则跳过。
21. 不要自动启用默认关闭的子选项（MTE 系列）；报告其状态并在后续步骤中提供启用选项。
22. Phase 2 Step 1：若所有受支持 target 都已是最新，用一行报告并直接进入 Step 2（基础 Clang 安全警告），无可应用项时不要询问应用确认；否则打印拟启用 Enhanced Security 的 target 列表。
23. 随后用简短摘要说明启用 Enhanced Security 的好处（以其提供的安全防护和可能需要的代码改动来表述），再用 AskUserQuestion 询问一次：“Apply the Enhanced Security changes above?”，选项为 “Apply all”、“Apply to a subset (choose targets)”、“Skip Enhanced Security”。
24. Phase 2 Step 1 应用：通过 UpdateTargetBuildSetting 在非 arm64e 平台 target 上设置 target 级 ENABLE_POINTER_AUTHENTICATION = NO（用户已有显式 target 级值的跳过）；直接编辑各 target 现有 .entitlements plist——原子地添加必需键与默认开启键、移除已弃用键、把版本字符串 "1" 迁移为 "2"；对没有 .entitlements 文件的 target 创建文件并把 CODE_SIGN_ENTITLEMENTS 指向它。
25. Phase 2 Step 1 报告：“Enabled Enhanced Security on N target(s). Removed M deprecated entitlement(s). Upgraded version string to 2 on K target(s). Added arm64e override on T non-arm64e-platform target(s).”
26. Phase 2 Step 1 硬件内存标记：仅支持 SUPPORTED_PLATFORMS（或 SDKROOT）为 macosx、iphoneos/iphonesimulator 或 xros/xrsimulator 的 target（硬件需 M5 级及以后的 Apple 芯片；tvOS、watchOS、DriverKit 不支持）；若未应用 Enhanced Security 或无修改过的 target 匹配这些平台则跳过；否则用 AskUserQuestion 询问是否启用 com.apple.security.hardened-process.checked-allocations，若同意则读 references/hardware-memory-tagging.md 并应用。
27. Phase 2 Step 2 基础 Clang 安全警告：对含 C、C++、Objective-C、Objective-C++ 的代码库无需询问直接应用；纯 Swift 代码库跳过此步；跳过已启用的设置；除特别注明外以下设置均适用于 C/C++/ObjC/ObjC++：GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR、GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE、CLANG_WARN_IMPLICIT_FALLTHROUGH = YES、GCC_WARN_64_TO_32_BIT_CONVERSION = YES、GCC_TREAT_IMPLICIT_FUNCTION_DECLARATIONS_AS_ERRORS = YES（仅 C/ObjC/ObjC++）、CLANG_ANALYZER_SECURITY_FLOATLOOPCOUNTER = YES、CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND = YES、CLANG_ANALYZER_SECURITY_INSECUREAPI_STRCPY = YES；简要报告：“Enabled additional compiler warnings.”
28. Phase 3：在 pbxproj 和 xcconfig 中 grep references/settings-and-entitlements-catalog.md 里被显式设为 NO 的构建设置；排除平台不支持 arm64e 的 target 上的 ENABLE_POINTER_AUTHENTICATION = NO（本技能自己设置的），但 arm64e 能力 target 上的该设置要标记出来询问；若无其他被禁用设置则跳过本阶段；只考虑与 Phase 1 检测到的语言相关的设置（见目录的 Scope 列）。
29. Phase 3：对每个被禁用设置，检查决策文档中是否已有状态为 Disabled 且带理由的条目——若有，在报告中注明并继续（该理由记录了可日后复审的既往决策）；若无，用 AskUserQuestion 询问用户原因（如：“I found CLANG_ANALYZER_SECURITY_INSECUREAPI_RAND explicitly set to NO with no explanation. Is there a reason for this?”）；用户给出理由则接受并把理由记入决策文档，无理由则建议重新启用；此流程同样适用于本技能通常会启用的任何设置（如 ENABLE_ENHANCED_SECURITY）被显式设为 NO 的情况。
30. Phase 4：对 Phase 2 中修改过的每个 target，用 GetTargetBuildSettings 验证每个已应用的构建设置以期望值出现；若缺失或值异常，在报告中标记为当前 Xcode 版本可能不支持；参考 references/reading-build-settings.md 的输出 schema 与大结果处理配方。
31. Phase 5：产出精简摘要——1) Enabled：列出已启用的项目级设置；2) Enhanced Security per target：每个受支持 target 一行，含 target 名、最终状态（up-to-date / applied / skipped-by-user）和简要增量（新增的 entitlements、移除的已弃用键、版本升级、是否创建了 entitlements 文件），因 product type 不受支持而跳过的 target 汇总为一行；3) Already active：列出已正确配置的设置；4) Inquired：发现被禁用及询问结果。
32. Phase 5：读取 references/decision-document.md 并按其创建或更新决策文档。
33. Phase 6：按顺序逐个提供以下可选后续步骤，每个都是独立的 yes/no 问题，不要合并为单个多选提示（推荐采用顺序和基于语言组合的决策矩阵见 references/adoption-strategy.md）：1) 用 AskUserQuestion 询问“There are additional diagnostic settings that could find more issues but may also produce false positives. Want to enable them?”，同意则读 references/additional-settings.md 并执行；2) 边界安全编程模型（仅当存在 C 或 C++ 代码时）——C 项目问是否采用 ENABLE_C_BOUNDS_SAFETY（基于注解的 C 边界安全编程模型，调用 Xcode 的 bounds-safety 技能开始），C++ 项目问是否采用 ENABLE_CPLUSPLUS_BOUNDS_SAFE_BUFFERS（启用 C++ 边界安全缓冲区模式，调用 Xcode 的 bounds-safety 技能开始）。
34. 面向用户的交互准则：回复保持精简、句子简短；用户提问尽量少——两个固定问题（Enhanced Security 应用确认、硬件内存标记提议），其他为情境性问题（仅在显式 = NO 且无文档理由时询问被故意禁用的设置、仅首次创建时询问决策文档位置）；报告进度（“Enabling...”、“Evaluating...”、“Keeping/Reverting...”）；用 AskUserQuestion 询问被禁用设置、Enhanced Security 应用确认（含“apply to a subset”）以及决策文档位置（仅首次创建）；提问时提供用户回答所需的上下文（例如先描述安全防护的好处，以其提供的防护而非启用方式来表述）；列出 Xcode 构建设置时用项目符号列表，不要用逗号分隔。
35. 当 GetTargetBuildSettings 因 token 限制把输出写入保存文件时，参考 references/reading-build-settings.md 的 schema 和过滤脚本（scripts/filter_build_settings.py），不要线性读取该保存文件。

适用边界 · 注意事项

• 网络层安全（TLS/ATS）、代码签名、隐私 API 相关的问题不在本技能范围内。
• 纯 Swift 代码库跳过基础 Clang 安全警告步骤。
• 项目存在非源码形式的二进制依赖（frameworks、xcframeworks、Swift Packages）时不要启用 pointer authentication。