search-macos26-docs

搜索 macOS 26 文档

使用本地 Xcode macOS SDK 作为 macOS 26 API 的事实依据。当任务询问当前 SDK 提供哪些功能、SwiftUI/AppKit 符号如何声明、符号的可用性，或 macOS 26 是否存在某个 API 时，请优先使用此技能，而非网页搜索。

快速开始

构建或刷新缓存的符号图：

python3 "$HOME/.codex/skills/search-macos26-docs/scripts/build_cache.py"

搜索 SwiftUI、SwiftUICore 和 AppKit 符号文档：

python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py glass button style
python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py window toolbar --macos26
python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py NSHostingScene --module SwiftUI --module AppKit --limit 12

使用附带精确 SDK 源代码片段的方式探查符号或概念：

python3 "$HOME/.codex/skills/search-macos26-docs/scripts/probe_symbol.py" ZoomNavigationTransition --module SwiftUI
python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py" MTKView --module MetalKit --verify-interfaces --limit 12

先发现 SDK 模块，再决定搜索位置：

python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py" --find-module metal
python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py" --list-modules

搜索脚本首次运行时会自动构建默认缓存。如果 Xcode 更新，或搜索结果看起来过时，请在 build_cache.py 中使用 --force。

工作流

1. 使用 xcrun --sdk macosx --show-sdk-path 确定当前 SDK。
2. 使用 scripts/search_symbols.py 搜索说明文档、符号名称、声明和可用性。此脚本会读取本地 SDK 中缓存的 swift-symbolgraph-extract 输出。
3. 如果需要精确的编译器声明、重载、下划线开头的符号、生成的属性或平台可用性，请添加 --verify-interfaces，或使用 scripts/probe_symbol.py。验证过程会搜索 .swiftinterface、标头和 apinotes，并报告源代码片段及诊断信息。
4. 使用 --find-module PATTERN 或 --list-modules 发现候选 SDK 模块，然后通过显式的 --module 值重新运行。
5. 将发现的内容作为本地 SDK 事实引用。如果在符号图中找不到某个符号，请在断定其不存在前，检查 --verify-interfaces 的 sourceOnlyMatches。

接口检查

Swift 接口展现的是 API 表面，并非完整文档。不过，对于精确签名和属性，它们仍是最佳的备用资料：

SDK_PATH=$(xcrun --sdk macosx --show-sdk-path)
SWIFTUI="$SDK_PATH/System/Library/Frameworks/SwiftUI.framework/Modules/SwiftUI.swiftmodule/arm64e-apple-macos.swiftinterface"
SWIFTUICORE="$SDK_PATH/System/Library/Frameworks/SwiftUICore.framework/Modules/SwiftUICore.swiftmodule/arm64e-apple-macos.swiftinterface"
APPKIT="$SDK_PATH/System/Library/Frameworks/AppKit.framework/Modules/AppKit.swiftmodule/arm64e-apple-macos.swiftinterface"

rg -n "GlassButtonStyle|WindowResizability|NSHostingScene|toolbar" "$SWIFTUI" "$SWIFTUICORE" "$APPKIT"
sed -n '1200,1235p' "$SWIFTUI"

使用接口 grep 查找：

• 重载集合和泛型约束
• @available、弃用和重命名消息
• 在 SDK 中可见、与内部声明相关的下划线开头声明
• 符号图中缺少说明文档的声明
• 通过精确接口文本更容易确认的 AppKit 声明

符号图缓存

缓存默认位于：

${CODEX_MACOS26_DOCS_CACHE:-$HOME/.cache/codex/search-macos26-docs}/<sdk-name>/<target>/<module>/

默认模块为 SwiftUI、SwiftUICore 和 AppKit。需要时添加更多模块：

python3 "$HOME/.codex/skills/search-macos26-docs/scripts/build_cache.py --module UniformTypeIdentifiers
python3 "$HOME/.codex/skills/search-macos26-docs/scripts/search_symbols.py pasteboard --module AppKit

实用选项：

• build_cache.py --list 会打印缓存位置和 SDK 详情，但不提取内容。
• build_cache.py --force 会删除并重建所选模块的缓存。
• search_symbols.py --json 会输出机器可读的结果。
• search_symbols.py --verify-interfaces 会将匹配的 .swiftinterface、标头或 apinotes 片段及诊断信息附加到显示的结果中。
• probe_symbol.py QUERY ... 是对符号进行完整文档验证探查（不去重）的简写。
• search_symbols.py --find-module PATTERN 会列出名称与子字符串匹配的 SDK 模块。
• search_symbols.py --list-modules 会列出辅助工具可见的 SDK 框架模块。
• search_symbols.py --kind "Instance Method" 会按结果种类缩小范围。
• search_symbols.py --macos26 会筛选 macOS 26 或更高版本引入的符号。
• search_symbols.py --introduced macOS:26 会按显式的可用性域和主版本号筛选。
• search_symbols.py --no-doc 会隐藏文档片段，使输出更精简。
• search_symbols.py --no-dedupe 会保留重复的扩展结果，以便查看每个具体接收者。
• search_symbols.py --source-limit 8 --source-context-lines 6 会调整已验证的源代码片段。

测试

修改辅助脚本后，运行端到端测试。这些测试使用实际安装的 SDK，并验证符号图搜索、仅源代码验证、模块发现和显式模块深入查询：

python3 "$HOME/.codex/skills/search-macos26-docs/tests/test_search_symbols_e2e.py"

解释规则

• 将符号图文档视为提取自本地 Apple SDK 的元数据，而非生成的猜测。
• 将 .swiftinterface 视为面向编译器的声明来源。
• 对于由 Objective-C 支持的框架，将头文件和 apinotes 视为首要备用来源。
• 当符号图与经验证的 SDK 源码不一致时，以经验证的 SDK 源码为准，并报告差异。
• 不要假定 Apple Developer 公共网页包含 macOS 26 beta／新 SDK API 的完整或最新信息。
• 如果某个模块的符号图提取失败，请改为在 $SDK_PATH/System/Library/Frameworks 和 $SDK_PATH/System/Library/PrivateFrameworks 下的框架接口中使用 rg 搜索。
• 需要精确性时，请报告当前 SDK 的基本名称、目标三元组和模块。