axiom-location

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Location & Maps

位置服务与地图

You MUST use this skill for ANY location services, mapping, geofencing, or Core Location / MapKit work.

任何涉及位置服务、地图绘制、地理围栏或Core Location/MapKit的工作，都必须使用本技能。

Quick Reference

快速参考

Symptom / Task	Reference
Authorization strategy (When In Use vs Always)	See `skills/core-location.md`
Monitoring approach (continuous, significant-change, CLMonitor)	See `skills/core-location.md`
Accuracy selection, background location	See `skills/core-location.md`
CLLocationUpdate, CLMonitor, CLServiceSession APIs	See `skills/core-location-ref.md`
Authorization API patterns, geofencing API	See `skills/core-location-ref.md`
Location updates never arrive	See `skills/core-location-diag.md`
Background location stops working	See `skills/core-location-diag.md`
Authorization always denied, geofence failures	See `skills/core-location-diag.md`
SwiftUI Map, annotations, markers, clustering	See `skills/mapkit.md`
MKMapView vs SwiftUI Map decision	See `skills/mapkit.md`
Search, directions, routing	See `skills/mapkit.md`
MapKit API: Marker, Annotation, MKLocalSearch, MKDirections	See `skills/mapkit-ref.md`
Look Around, MKMapSnapshotter, MKMapItem	See `skills/mapkit-ref.md`
Annotations not appearing, region jumping	See `skills/mapkit-diag.md`
Clustering not working, search failures	See `skills/mapkit-diag.md`
Overlay rendering, user location not showing	See `skills/mapkit-diag.md`

症状/任务	参考文档
授权策略（使用期间 vs 始终允许）	查看 `skills/core-location.md`
监控方式（持续监控、重大变化监控、CLMonitor）	查看 `skills/core-location.md`
精度选择、后台位置服务	查看 `skills/core-location.md`
CLLocationUpdate、CLMonitor、CLServiceSession API	查看 `skills/core-location-ref.md`
授权API模式、地理围栏API	查看 `skills/core-location-ref.md`
位置更新始终无法接收	查看 `skills/core-location-diag.md`
后台位置服务停止工作	查看 `skills/core-location-diag.md`
授权始终被拒绝、地理围栏功能失效	查看 `skills/core-location-diag.md`
SwiftUI Map、标注、标记、聚类	查看 `skills/mapkit.md`
MKMapView与SwiftUI Map的选型决策	查看 `skills/mapkit.md`
搜索、路线规划、路径导航	查看 `skills/mapkit.md`
MapKit API：Marker、Annotation、MKLocalSearch、MKDirections	查看 `skills/mapkit-ref.md`
Look Around、MKMapSnapshotter、MKMapItem	查看 `skills/mapkit-ref.md`
标注不显示、地图区域跳转异常	查看 `skills/mapkit-diag.md`
聚类功能失效、搜索无结果	查看 `skills/mapkit-diag.md`
覆盖层渲染失败、用户位置不显示	查看 `skills/mapkit-diag.md`

Decision Tree

决策树

dot

digraph location {
    start [label="Location / Maps task" shape=ellipse];
    domain [label="Core Location or MapKit?" shape=diamond];
    cl_type [label="Need what?" shape=diamond];
    mk_type [label="Need what?" shape=diamond];

    start -> domain;

    domain -> cl_type [label="Core Location"];
    domain -> mk_type [label="MapKit / Maps"];

    cl_type -> "skills/core-location.md" [label="authorization, monitoring\nstrategy, accuracy,\nbackground location"];
    cl_type -> "skills/core-location-ref.md" [label="API syntax\n(CLLocationUpdate,\nCLMonitor, CLServiceSession)"];
    cl_type -> "skills/core-location-diag.md" [label="something broken\n(no updates, denied,\ngeofence not firing)"];

    mk_type -> "skills/mapkit.md" [label="patterns, decisions\n(SwiftUI Map vs MKMapView,\nannotations, search)"];
    mk_type -> "skills/mapkit-ref.md" [label="API syntax\n(Marker, Annotation,\nMKLocalSearch, MKDirections)"];
    mk_type -> "skills/mapkit-diag.md" [label="something broken\n(annotations missing,\nregion jumping, clustering)"];
}

Authorization strategy, monitoring approach, accuracy? →
```
skills/core-location.md
```
1a. Need specific API syntax (CLLocationUpdate, CLMonitor, CLServiceSession)? →
```
skills/core-location-ref.md
```
1b. Location not working? →
```
skills/core-location-diag.md
```
Adding a map, annotations, search, directions? →
```
skills/mapkit.md
```
2a. Need specific MapKit API syntax (Marker, MKLocalSearch, MKDirections)? →
```
skills/mapkit-ref.md
```
2b. Map display broken? →
```
skills/mapkit-diag.md
```
Location draining battery? → See axiom-performance (skills/energy.md)
Background task scheduling for location? → See axiom-integration
Privacy manifest for location? → See axiom-integration

dot

digraph location {
    start [label="Location / Maps task" shape=ellipse];
    domain [label="Core Location or MapKit?" shape=diamond];
    cl_type [label="Need what?" shape=diamond];
    mk_type [label="Need what?" shape=diamond];

    start -> domain;

    domain -> cl_type [label="Core Location"];
    domain -> mk_type [label="MapKit / Maps"];

    cl_type -> "skills/core-location.md" [label="authorization, monitoring\nstrategy, accuracy,\nbackground location"];
    cl_type -> "skills/core-location-ref.md" [label="API syntax\n(CLLocationUpdate,\nCLMonitor, CLServiceSession)"];
    cl_type -> "skills/core-location-diag.md" [label="something broken\n(no updates, denied,\ngeofence not firing)"];

    mk_type -> "skills/mapkit.md" [label="patterns, decisions\n(SwiftUI Map vs MKMapView,\nannotations, search)"];
    mk_type -> "skills/mapkit-ref.md" [label="API syntax\n(Marker, Annotation,\nMKLocalSearch, MKDirections)"];
    mk_type -> "skills/mapkit-diag.md" [label="something broken\n(annotations missing,\nregion jumping, clustering)"];
}

授权策略、监控方式、精度设置？→
```
skills/core-location.md
```
1a. 需要特定API语法（CLLocationUpdate、CLMonitor、CLServiceSession）？→
```
skills/core-location-ref.md
```
1b. 位置服务无法正常工作？→
```
skills/core-location-diag.md
```
添加地图、标注、搜索、路线规划？→
```
skills/mapkit.md
```
2a. 需要特定MapKit API语法（Marker、MKLocalSearch、MKDirections）？→
```
skills/mapkit-ref.md
```
2b. 地图显示异常？→
```
skills/mapkit-diag.md
```
位置服务消耗电量过高？→ 参考性能准则（skills/energy.md）
为位置服务调度后台任务？→ 参考集成准则
位置服务隐私清单？→ 参考集成准则

Conflict Resolution

冲突解决

location vs axiom-performance: When location is draining battery:

Try location FIRST — Excessive accuracy or continuous updates are the #1 cause.
```
skills/core-location.md
```
covers accuracy selection and monitoring strategy.
Only use axiom-performance if location settings are already correct — Profile after ruling out obvious over-tracking.

location vs axiom-integration: When implementing background location:

Background location configuration (Info.plist, capabilities, CLServiceSession) → use location
BGTaskScheduler for periodic location processing → use axiom-integration

location vs axiom-data: When storing or syncing location data:

Getting location updates, geofencing → use location
Persisting location history, CloudKit sync → use axiom-data

location vs axiom-build: When location permissions fail in simulator:

Authorization dialogs, Info.plist keys → use location (
```
skills/core-location-diag.md
```
)
Simulator GPS simulation,
```
simctl location
```
→ use axiom-build

location vs axiom-performance：当位置服务消耗电量过高时：

优先使用location技能 — 过高的精度设置或持续更新是首要原因。
```
skills/core-location.md
```
涵盖了精度选择和监控策略内容。
仅当位置设置已正确配置时，再使用axiom-performance — 在排除明显的过度追踪问题后，再进行性能分析。

location vs axiom-integration：当实现后台位置服务时：

后台位置服务配置（Info.plist、功能权限、CLServiceSession）→ 使用location技能
用于周期性位置处理的BGTaskScheduler → 使用axiom-integration

location vs axiom-data：当存储或同步位置数据时：

获取位置更新、地理围栏功能 → 使用location技能
持久化位置历史、CloudKit同步 → 使用axiom-data

location vs axiom-build：当位置权限在模拟器中失效时：

授权弹窗、Info.plist键配置 → 使用location技能（
```
skills/core-location-diag.md
```
）
模拟器GPS模拟、
```
simctl location
```
命令 → 使用axiom-build

Critical Patterns

关键模式

Core Location (

skills/core-location.md

Authorization escalation strategy (When In Use first, Always later)
Monitoring decision tree (continuous vs significant-change vs CLMonitor)
Accuracy selection with battery impact
Background location configuration
Anti-patterns with time costs (premature Always authorization, unnecessary continuous updates)

Core Location API (

skills/core-location-ref.md

CLLocationUpdate AsyncSequence (iOS 17+)
CLMonitor condition-based geofencing (iOS 17+)
CLServiceSession declarative authorization (iOS 18+)
Authorization API patterns, background mode configuration

Core Location Diagnostics (

skills/core-location-diag.md

Location updates never arrive
Background location stops working
Authorization always denied
Geofence events not triggering
Location accuracy unexpectedly poor

MapKit (

skills/mapkit.md

SwiftUI Map vs MKMapView decision tree
Annotation patterns (Marker, custom Annotation)
Search (MKLocalSearch, autocomplete)
Directions and routing
Anti-patterns (annotations in view body, no view reuse, setRegion loops)

MapKit API (

skills/mapkit-ref.md

SwiftUI Map API (MapCameraPosition, content builders, controls)
MKMapView delegate patterns
MKLocalSearch, MKDirections
Look Around, MKMapSnapshotter
Clustering configuration

MapKit Diagnostics (

skills/mapkit-diag.md

Annotations not appearing (lat/lng swapped, missing delegate)
Map region jumping/looping (updateUIView guard)
Clustering not working (missing clusteringIdentifier)
Search returning no results (resultTypes, region bias)
Overlay rendering failures

Core Location（

skills/core-location.md

）：

授权升级策略（先申请使用期间授权，后续再申请始终允许）
监控方式决策树（持续监控vs重大变化监控vs CLMonitor）
兼顾电池消耗的精度选择
后台位置服务配置
耗时的反模式（提前申请始终允许授权、不必要的持续更新）

Core Location API（

skills/core-location-ref.md

）：

CLLocationUpdate异步序列（iOS 17+）
基于条件的CLMonitor地理围栏（iOS 17+）
声明式授权的CLServiceSession（iOS 18+）
授权API模式、后台模式配置

Core Location 诊断（

skills/core-location-diag.md

）：

位置更新始终无法接收
后台位置服务停止工作
授权始终被拒绝
地理围栏事件未触发
位置精度意外偏低

MapKit（

skills/mapkit.md

）：

SwiftUI Map与MKMapView的选型决策树
标注模式（Marker、自定义Annotation）
搜索功能（MKLocalSearch、自动补全）
路线规划与导航
反模式（在视图体中直接声明标注、未复用视图、setRegion循环调用）

MapKit API（

skills/mapkit-ref.md

）：

SwiftUI Map API（MapCameraPosition、内容构建器、控件）
MKMapView代理模式
MKLocalSearch、MKDirections
Look Around、MKMapSnapshotter
聚类配置

MapKit 诊断（

skills/mapkit-diag.md

）：

标注不显示（经纬度颠倒、缺失代理）
地图区域跳转/循环（updateUIView中的判断遗漏）
聚类功能失效（缺失clusteringIdentifier）
搜索无结果（resultTypes、区域偏好设置问题）
覆盖层渲染失败

Anti-Rationalization

常见误区纠正

Thought	Reality
"Just request Always authorization upfront"	30-60% denial rate. Request When In Use first, escalate later. `skills/core-location.md` covers the strategy.
"Continuous updates are fine for my use case"	Continuous updates drain battery even when the app doesn't need sub-second location. Use significant-change or CLMonitor.
"I'll use MKMapView, it's more flexible"	SwiftUI Map covers most use cases since iOS 17. MKMapView means UIViewRepresentable boilerplate. `skills/mapkit.md` has the decision tree.
"Annotations in the view body is fine for a few items"	Annotations recreate on every view update. Even 50 items cause hitches. Move to model with `@State` or `@Observable` .
"I know how geofencing works"	CLMonitor (iOS 17+) replaces legacy region monitoring with conditions. The API changed significantly.
"Background location just needs the capability"	It needs Info.plist keys, capability, CLServiceSession (iOS 18+), AND correct authorization level. Missing any one silently fails.
"I'll handle location errors later"	Authorization denial is not an error — it's the default state. Handle it from the start.

错误想法	实际情况
"直接申请始终允许的位置授权"	拒绝率达30-60%。应先申请使用期间授权，后续再升级。 `skills/core-location.md` 涵盖了该策略。
"我的场景适合使用持续更新"	持续更新会在应用不需要亚秒级位置时仍消耗大量电量。应使用重大变化更新或CLMonitor。
"我要用MKMapView，它更灵活"	自iOS 17起，SwiftUI Map已覆盖大多数使用场景。使用MKMapView需要编写UIViewRepresentable模板代码。 `skills/mapkit.md` 中有选型决策树。
"少量标注直接放在视图体里没问题"	标注会在每次视图更新时重建，即使50个标注也会导致卡顿。应将标注移至使用 `@State` 或 `@Observable` 的模型中。
"我懂地理围栏的实现方式"	CLMonitor（iOS 17+）已取代旧版区域监控，采用条件式实现，API发生了重大变化。
"后台位置服务只需开启功能权限即可"	它需要配置Info.plist键、功能权限、CLServiceSession（iOS 18+），以及正确的授权级别。缺少任何一项都会导致静默失败。
"位置服务的错误处理可以后续再做"	授权被拒绝不是异常情况——这是默认状态。应从项目初期就处理该场景。

Example Invocations

示例调用场景

User: "How do I request location permissions?" → Read:

skills/core-location.md

User: "What's the CLLocationUpdate API?" → Read:

skills/core-location-ref.md

User: "My location updates never arrive" → Read:

skills/core-location-diag.md

User: "How do I add a map with pins?" → Read:

skills/mapkit.md

User: "What's the SwiftUI Map API?" → Read:

skills/mapkit-ref.md

User: "My annotations aren't showing on the map" → Read:

skills/mapkit-diag.md

User: "How do I implement geofencing?" → Read:

skills/core-location.md

then

skills/core-location-ref.md

User: "Location is draining battery" → Read:

skills/core-location.md

, then See axiom-performance (skills/energy.md)

User: "How do I add search to my map?" → Read:

skills/mapkit.md

then

skills/mapkit-ref.md

用户："如何申请位置权限？" → 阅读：

skills/core-location.md

用户："CLLocationUpdate API是什么？" → 阅读：

skills/core-location-ref.md

用户："我的位置更新始终无法接收" → 阅读：

skills/core-location-diag.md

用户："如何在地图上添加大头针标注？" → 阅读：

skills/mapkit.md

用户："SwiftUI Map API有哪些内容？" → 阅读：

skills/mapkit-ref.md

用户："我的标注没有显示在地图上" → 阅读：

skills/mapkit-diag.md

用户："如何实现地理围栏功能？" → 阅读：

skills/core-location.md

然后

skills/core-location-ref.md

用户："位置服务消耗电量过高" → 阅读：

skills/core-location.md

，然后参考性能准则（skills/energy.md）

用户："如何为地图添加搜索功能？" → 阅读：

skills/mapkit.md

然后

skills/mapkit-ref.md