用途：为 macOS 应用加入轻量级运行时遥测，帮助调试行为，同时避免把代码库变成日志垃圾场。核心是使用 Apple 统一日志 API，并在构建/运行后验证事件确实触发。
主要能力与准则：优先使用 OSLog 框架的 Logger 输出结构化日志；为每个功能设定清晰的 subsystem/category 组合，便于运行时过滤；记录有意义的用户与应用生命周期事件，如窗口打开、侧边栏选择变化、菜单命令、菜单栏额外操作、同步/加载里程碑及意外回退路径；info 日志保持简洁稳定，debug 日志用于嘈杂的状态细节；不得记录密钥、认证令牌、个人数据或原始文档内容；仅在测量耗时或性能区间时添加 signpost，默认不要过度埋点。
使用方式：按功能区域或类型创建 Logger，例如 category 使用 Windowing、Commands、MenuBar、Sidebar、Sync、Import。记录动作边界与关键状态转换，每个用户动作优先一行高信号日志。构建并运行应用，可用 build-run-debug 完成构建/运行循环；若存在 script/build_and_run.sh，可用 ./script/build_and_run.sh --telemetry 做实时遥测检查，或用 ./script/build_and_run.sh --logs 查看更广的进程日志。触发应发出遥测的 UI 或命令路径，然后读取运行时日志验证事件是否触发。手动检查可用 Console.app 按进程/subsystem 过滤；终端实时验证可用 log stream --style compact --predicate 'process == "AppName"'，已知 subsystem/category 时用更精确的谓词，如 log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'。
验证清单：改动后应用能构建；相关动作恰好输出一行清晰日志或少量有界序列；日志可按进程、subsystem 或 category 过滤；统一日志中无敏感载荷；结束前移除或降级嘈杂的临时 debug 日志。
限制与护栏：不要用 print 作为 macOS 应用代码的主要遥测机制；不要在每次状态变更周围留下密集的永久 debug 日志；在通过 Console、log stream 或捕获的进程输出完成具体验证前，不要声称事件已正确接线。若调试任务主要是崩溃/回溯分析而非动作遥测，应改用 build-run-debug。