CLI-Anything 之 NSLogger 日志命令行工具解析、过滤、导出与实时监听的完整实战指南【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本指南以仓库内 skills/cli-anything-nslogger/SKILL.md 为主线系统讲解cli-anything-nslogger——一个面向 NSLogger 的完整命令行 harness。NSLogger 是 iOS/macOS 应用开发中广泛使用的日志查看器本工具让你不需要打开图形界面即可解析.rawnsloggerdata/.nsloggerdata日志文件、按级别/标签/线程/正则精确过滤、导出为 text/JSON/CSV甚至通过 Bonjour/mDNS 与 TLS 实时接收正在运行的 iOS App 日志。读完本文你将掌握全部命令用法、日志级别体系、消息 JSON 结构、Agent 化工作流--json机器可读输出以及底层 wire-protocol 与监听机制的源码级原理。NSLogger 背景与 CLI harness 的价值NSLogger 是 iOS/macOS 平台上一款高性能日志记录与查看工具App 内集成其客户端后日志以自定义二进制协议实时发送到 macOS 上的 NSLogger.app 桌面端进行浏览、过滤与归档。cli-anything-nslogger的出现是把这类桌面 GUI 才能操作的日志生态原生接入命令行与 AI Agent离线分析直接解析 NSLogger.app 保存的.rawnsloggerdata原始 wire-protocol 抓包与.nsloggerdataNSLogger.app 保存的二进制 plist 归档无需打开 GUI在线监听在 macOS 上发布与 NSLogger.app 一致的 Bonjour 服务_nslogger-ssl._tcpiOS 设备在同一 WiFi 下即可自动发现等价于桌面端实时日志窗口的命令行版Agent 友好每个子命令都支持--json结构化输出AI Agent 可直接消费日志内容做崩溃分析、趋势统计。安装方式见 nslogger/agent-harness/setup.pycd nslogger/agent-harness pip install -e . # 验证安装 cli-anything-nslogger --help入口为 nslogger_cli.py基于 Click 构建的命令组在无子命令时自动进入交互式 REPL。cli-anything-nslogger --version可查看版本。命令总览cli-anything-nslogger提供 10 个核心子命令覆盖日志生命周期中的解析、过滤、导出、统计、监听与交互命令说明generate生成用于测试的样例.rawnsloggerdata文件read解析并显示文件中的消息filter高级过滤级别、标签、线程、正则、序号区间等export导出为 text / JSON / CSVstats汇总统计listen通过 Bonjour 或 TCP/TLS 接收实时 NSLogger 连接repl交互式命令 REPL共享 cli-anything 皮肤tail显示文件末尾 N 条消息clients列出文件中记录的全部客户端连接client_infoblocks以缩进树展示块开始/结束嵌套结构merge按时间戳合并多个 NSLogger 文件其中tail、clients、blocks、merge为文档之外源码中补充的能力见 nslogger_cli.py下文将一并展开。文件格式raw 协议与 plist 归档工具同时支持两种 NSLogger 文件格式README.md 中的文件格式表扩展名说明.rawnsloggerdataNSLogger 原始 wire-protocol 抓包.nsloggerdataNSLogger.app 保存的二进制 plist 归档从 parser.py 可以看出parse_file按扩展名自动分派.rawnsloggerdata走原始协议解析器其余走_parse_nsloggerdata通过 Pythonplistlib读取messages数组并提取 timestamp/tag/level/threadID/message 字段后者失败时还会回退到 raw 解析具备良好的容错性。原始协议解析器parse_raw_file逐条读取4 字节大端长度头 消息体的帧结构parser.py单条消息体由partCount2 字节与多个[partKey][partType][data]分部组成。消息类型常量定义在 message.py0LOG、1BLOCK_START、2BLOCK_END、3CLIENT_INFO、4DISCONNECT、255MARKER。值得留意的是解析器还内置了针对旧测试夹具的向后兼容回退parser.py并对单条损坏消息采用跳过而非整体失败的处理策略。快速上手generate 与 readgenerate — 生成测试样例cli-anything-nslogger generate sample.rawnsloggerdata --count 50--count默认值为 20见 nslogger_cli.py。底层 generate.py 会先写入一条client_info消息标识客户端为 SampleApp 1.0.0 / iOS 17.0 / iPhone15,2随后生成 50 条分布于 Network/UI/Database/Auth/Cache 等标签、覆盖 04 各日志级别的模拟消息时间戳按 0.5 秒间隔递增——非常适合在没有真实日志时体验全部命令。read — 展示消息# 全部消息 cli-anything-nslogger read session.rawnsloggerdata # 仅错误级别 0 cli-anything-nslogger read session.rawnsloggerdata --level 0 # 按标签 文本搜索过滤 cli-anything-nslogger read session.rawnsloggerdata --tag Network --search timeout # 前 20 条并以 JSON 输出 cli-anything-nslogger read session.rawnsloggerdata --limit 20 --jsonread完整支持以下选项源码见 nslogger_cli.py-l, --level显示的最大日志级别0error … 4verbose-t, --tag按标签过滤可重复指定--thread按线程 ID 过滤-s, --search不区分大小写的文本搜索-n, --limit最多显示条数--after/--before时间范围过滤接受HH:MM:SS或YYYY-MM-DDTHH:MM:SS两种格式解析逻辑见_parse_dtnslogger_cli.py纯时间格式会自动补齐为当天 UTC 日期--jsonJSON 数组输出。tail — 查看末尾消息cli-anything-nslogger tail session.rawnsloggerdata --count 20 cli-anything-nslogger tail session.rawnsloggerdata --level 0 --jsontail是read --limit的反向操作取过滤结果的最后 N 条默认 20适合查看崩溃前的收尾日志。filter — 高级过滤filter比read提供更丰富的检索维度# 仅错误与警告级别 ≤ 1 cli-anything-nslogger filter session.rawnsloggerdata --level 1 # 按多个标签过滤取交集 cli-anything-nslogger filter session.rawnsloggerdata --tag Auth --tag Network # 正则搜索 cli-anything-nslogger filter session.rawnsloggerdata --regex (timeout|failed|error) # 按线程过滤 cli-anything-nslogger filter session.rawnsloggerdata --thread main # JSON 输出 cli-anything-nslogger filter session.rawnsloggerdata --level 0 --jsonfilter独有的高级选项nslogger_cli.py--min-level最小日志级别与--level构成区间-r, --regex正文正则搜索编译时带re.IGNORECASE--type按消息类型过滤可选text、image、data、client_info、block_start、block_end--from-seq/--to-seq按序号区间过滤含端点--after/--before时间范围。所有条件在 filter.py 中为与关系逐一判定limit命中即短路适合在大文件上做定向抽取。例如定位某个线程在某个时间段内的正则匹配结果cli-anything-nslogger filter session.rawnsloggerdata \ --thread network-queue --after 10:00:00 --before 10:05:00 \ --regex fail|timeout --jsonexport — 导出为 text / JSON / CSV# JSON 输出到 stdout cli-anything-nslogger export session.rawnsloggerdata --format json # CSV 写入文件 cli-anything-nslogger export session.rawnsloggerdata --format csv --output logs.csv # 先过滤再导出为文本 cli-anything-nslogger export session.rawnsloggerdata --format text --level 1 --tag Networkexport默认格式为text支持--output/-o写入文件默认 stdout且可在导出前组合--level、--tag、--search、--limit预过滤nslogger_cli.py。各格式的序列化实现位于 exporter.pytext逐条调用LogMessage.to_text_line()形如HH:MM:SS.mmm ERROR (main) [Network] Connection timed out after 30sjsonjson.dumps缩进 2 的完整消息字典数组csv按sequence, timestamp, level, level_name, tag, thread_id, type, text固定字段输出extrasactionignore自动丢弃多余字段。CSV 字段与 JSON 结构存在差异CSV 不含 image 尺寸与客户端信息如需完整字段建议使用 JSON 格式CSV 更适合导入表格工具做透视分析。stats — 汇总统计# 人类可读摘要 cli-anything-nslogger stats session.rawnsloggerdata # 供 Agent 消费的 JSON cli-anything-nslogger stats session.rawnsloggerdata --jsonJSON 输出结构与文档一致实现于 stats.py{ total: 342, by_level: {ERROR: 12, WARNING: 34, INFO: 200, DEBUG: 96}, by_tag: {Network: 89, Auth: 45, UI: 120}, by_thread: {main: 200, bg-queue: 142}, by_type: {text: 340, client_info: 1, disconnect: 1}, clients: [MyApp], first_timestamp: 2024-01-01T10:00:0000:00, last_timestamp: 2024-01-01T10:05:3000:00, duration_seconds: 330.0 }源码细节by_tag取出现次数最多的前 20 个by_thread取前 10 个clients为去重排序后的客户端名集合空文件返回{total: 0}。文本模式还额外打印首次/末次消息时间、时长与 Top 标签/线程便于快速浏览。listen — 实时接收 NSLogger 连接listen是整套工具中最接近桌面 NSLogger.app 实时窗口的能力支持 Bonjour 自动发现与直接 TCP/TLS 两种接入方式。# Bonjour 模式与 NSLogger.app GUI 的 Bonjour 行为一致供 iOS 自动发现 cli-anything-nslogger listen --bonjour --name bazinga --debug # 实时镜像到文本文件同时继续打印 stdout cli-anything-nslogger listen --bonjour --name bazinga --output app.log # 以 JSON Lines 写入机器可读日志 cli-anything-nslogger listen --bonjour --name bazinga --output app.jsonl --output-format jsonl # 手动配置客户端的直接 TCP/TLS 模式 cli-anything-nslogger listen --port 50000 --ssl --debug # 监听时只显示错误并以 JSON 流输出 cli-anything-nslogger listen --bonjour --name bazinga --level 0 --json # 一直运行直到 Ctrl-C cli-anything-nslogger listen --bonjour --name bazinga使用原则iOS 应用优先使用 Bonjour 模式因为它与桌面 NSLogger GUI 行为一致——CLI 会发布原生 macOSNetService服务类型_nslogger-ssl._tcp并接收 TLS NSLogger 帧仅当 App 被手动配置了 Mac 主机与端口时才使用直接 TCP/TLS。listen的完整参数nslogger_cli.py参数默认值说明-p, --port50000监听 TCP 端口-t, --timeout无N 秒后自动停止默认运行至 Ctrl-C-l, --level无监听时显示的最大级别-b, --bonjour关通过 Bonjour/mDNS 广播iOS 自动发现无需配置 IP-n, --name系统选择Bonjour 服务名--ssl关直接 TCP 模式启用 SSL/TLSBonjour 模式默认即 SSL--no-ssl关广播/使用旧的纯文本 NSLogger Bonjour 服务--bonjour-modesslssl/raw/autossl 与 NSLogger GUI 默认一致auto 同时发布 rawSSL--bonjour-publishernativeBonjour 发布后端nativeNetService/ dns-sd / zeroconf--advertise-host自动探测使用 zeroconf 发布时对外公布的 IP--filter-clients/--no-filter-clients随名称开启发布filterClients1--name非空时默认开启与 NSLogger GUI 一致-o, --output无将实时日志写入文件同时打印 stdout--output-formattext输出文件格式text或jsonl--append关追加写入而非启动时覆盖输出文件--debug关向 stderr 打印实时帧诊断--json关每条消息以 JSON 输出监听器源码原理listener.py 中的NSLoggerListener承担全部监听逻辑几个值得深入的关键机制TLS 自动协商开启 SSL 时服务端使用openssl动态生成 1 天有效的自签名证书listener.py并将 TLS 固定为 TLSv1.2兼容 iOS 客户端的旧加密套件_classify_connection通过MSG_PEEK探测客户端首个字节是否为 TLS ClientHello0x16 0x03据此在同一端口上智能区分纯文本与 TLS 连接listener.pyBonjour 三重后端nativemacOSFoundation.NetService通过随包编译的 Swift 辅助程序实现最贴近 NSLogger.app 行为、dns-sdmacOS 系统工具、zeroconf纯 Python 进程内发布Ctrl-C 不会遗留子进程后两者作为跨平台回退listener.py原生 NetService 监听在 macOS 上若 Bonjour 只发布单一服务类型会优先使用 Swift 辅助程序NSNetServiceListenForConnections直接持有监听 socketlistener.py并将帧以 base64 JSON 事件回传给 Python 解析多连接并发默认路径下每个客户端连接由独立守护线程处理listener.py--debug模式可打印每帧长度、TLS 握手协议与套件、被丢弃帧的前 32 字节十六进制头部等诊断信息。实时输出格式由 message.py 的to_text_line与to_dict决定文本行形如10:01:23.456 ERROR (main) [Network] Connection timed out after 30sJSONL 则每行一条完整消息 JSON。消息 JSON 结构Agent 模式核心每条消息在--json下的完整结构由LogMessage.to_dict()生成message.py{ sequence: 42, timestamp: 2024-01-01T10:01:2300:00, timestamp_ms: 456, thread_id: main, tag: Network, level: 0, level_name: ERROR, type: text, text: Connection timed out after 30s, image_width: 0, image_height: 0, client_name: MyApp, client_version: 2.1.0, os_name: iOS, os_version: 17.0, machine: iPhone15,2 }字段要点level_name由LEVEL_NAMES映射message.py未知级别回退为LEVEL{n}type由type_name属性推导LOG 消息按是否携带图片/二进制数据分为text/image/data特殊消息类型映射为block_start/block_end/client_info/disconnect/markermessage.pytimestamp为带时区的 ISO 8601 UTC 字符串timestamp_ms为毫秒补充二者共同构成精确时间客户端信息client_name/client_version/os_name/os_version/machine来自 wire-protocol 中的client_info消息可据此区分多设备日志。Log Levels 日志级别表值名称用途0ERROR不可恢复的失败1WARNING可恢复的问题2INFO正常运行信息3DEBUG开发者细节4VERBOSETrace 级噪音源码中 LEVEL_NAMES 还额外定义了5: NOISE即总共支持 05 六级命名。过滤语义为--level N表示显示级别 ≤ N即 N 越大包含越多--min-level N表示显示级别 ≥ N。clients 与 blocks — 客户端清单与块结构# 列出文件记录的全部客户端连接 cli-anything-nslogger clients session.rawnsloggerdata cli-anything-nslogger clients session.rawnsloggerdata --json # 以缩进树展示块开始/结束嵌套 cli-anything-nslogger blocks session.rawnsloggerdata cli-anything-nslogger blocks session.rawnsloggerdata --jsonclients遍历所有client_info消息并输出[时间戳] 客户端名 版本 OS 版本 机型格式实现于 blocks.py可用于确认一次抓包涉及哪些设备blocks依据block_start/block_end消息将日志渲染为缩进树默认每层 2 空格--indent可调还原 NSLogger 的分块日志结构blocks.py。merge — 多文件按时间合并# 合并多个文件按时间戳排序后输出 cli-anything-nslogger merge session_a.rawnsloggerdata session_b.rawnsloggerdata \ --format json --output merged.json # 合并时仅保留错误 cli-anything-nslogger merge a.rawnsloggerdata b.rawnsloggerdata --level 0merge_filesblocks.py加载全部文件后按(timestamp, sequence)排序时间戳缺失的消息排在最前。适用于将同一应用的多次抓包拼接为一条完整时间线。repl — 交互式命令 REPLcli-anything-nslogger repl session.rawnsloggerdata # 或者直接运行 cli-anything-nslogger不带子命令进入 REPLREPL 由 repl_skin.py 的共享皮肤驱动内置命令如下nslogger_cli.pyREPL 命令说明read [FILE]展示解析出的消息filter [FILE] [OPTIONS]按级别/标签/线程/文本/正则/区间过滤tail [FILE]展示文件末尾消息stats [FILE]汇总统计clients [FILE]列出 client_info 记录blocks [FILE]展示块嵌套结构export [FILE] --format json导出为 text/JSON/CSVmerge FILE...按时间戳合并文件generate OUTPUT生成样例 raw NSLogger 文件listen [OPTIONS]监听实时 NSLogger 客户端load FILE设置默认文件current显示当前默认文件help显示帮助quit / exit退出 REPL使用repl session.rawnsloggerdata启动或load FILE设置默认文件后read、filter、stats等文件类命令可省略文件参数nslogger_cli.py 会在参数以-开头或无参数时自动注入当前文件。REPL 内所有子命令均可继续使用--json等标志实现交互探索 机器输出的无缝切换。Agent 工作流实战示例文档给出的崩溃分析工作流可直接落地为一条 Agent 排查链路# 1. 概览一次抓包会话含崩溃前的时长与客户端信息 cli-anything-nslogger stats crash.rawnsloggerdata --json # 2. 找出崩溃前 5 分钟内的全部错误 cli-anything-nslogger filter crash.rawnsloggerdata --level 0 --json # 3. 仅提取网络失败 cli-anything-nslogger filter crash.rawnsloggerdata --tag Network --regex fail|timeout|error --json # 4. 导出完整日志供离线分析 cli-anything-nslogger export crash.rawnsloggerdata --format json --output crash_log.json # 5. 实时监听 iOS App 并保留本地副本 cli-anything-nslogger listen --bonjour --name bazinga --output app.log --debug这套组合覆盖了离线统计 → 定向过滤 → 正则深挖 → 全量导出 → 在线接入的完整闭环Agent 可将每步的 JSON 输出作为结构化上下文stats --json给出会话规模与级别分布filter --json输出精确命中项listen --output file --output-format jsonl则可持续累积实时数据流。测试与验证仓库提供了两层测试保障tests/test_core.py针对解析器、过滤器、统计、导出与消息模型的单元测试test_full_e2e.py端到端测试验证generate → read/filter/export/stats全链路行为详细说明见 tests/TEST.md。可以在nslogger/agent-harness目录下执行python -m pytest cli_anything/nslogger/tests复现验证。这些测试同时佐证了本文涉及的两点实现事实raw 协议解析对旧夹具的兼容回退以及--json输出与LogMessage.to_dict()的一致性。小结cli-anything-nslogger将 NSLogger 的桌面日志生态完整迁移到命令行与 Agent 世界generate提供零成本测试数据read/filter/tail覆盖检索export打通分析管线stats/clients/blocks/merge提供结构化洞察listen实现 Bonjour TLS 的实时接入而repl则把这一切封装成可交互的工作台。其底层对 wire-protocol 的忠实实现parser.py与对 NSLogger.app 行为Bonjour 服务类型、filterClientsTXT 记录、TLSv1.2 协商的对齐使它既能离线深挖.rawnsloggerdata/.nsloggerdata文件也能像官方 GUI 一样实时接收 iOS/macOS 应用日志是移动端问题定位与 AI 辅助调试的实用基础设施。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考