夜雨聆风昨天，一条推文在 iOS 开发者圈炸了。
Antoine v.d. SwiftLee——一个教 15 万开发者写 Swift 的荷兰人——发了 4 行字：「I just released a new Agent Skill for iOS Development」。62K 浏览，615 收藏。
他到底发了什么？一个 7 年前就在用的诊断库，突然加了一个「Agent Skill」。
这件事值得拆开看。
Diagnostics 是什么
做过 iOS 开发的人都经历过这个场景：用户发邮件说「app 崩了」，你问他设备型号、系统版本、操作步骤，来回 5 封邮件，最终发现是 iOS 16.2 的一个已知 bug。
Diagnostics 就是为了解决这个问题。它是一个 Swift 库，一行代码生成一份完整的诊断报告——设备信息、系统日志、app 元数据、自定义日志——用户直接作为邮件附件发给你的支持团队。
想象一下这个对比：
→ 传统方式：用户描述问题 → 支持团队问细节 → 开发复现 → 定位问题。耗时 3-5 天，5-10 封邮件
→ 用 Diagnostics：用户点击「发送诊断」→ agent 3 秒解析 JSON → 自动定位问题。耗时 10 秒，0 封邮件
这个库从 2019 年 WeTransfer 的一个 hackathon 项目起步，现在被 RocketSim、Helm for App Store Connect 等产品在用。MIT 协议，SPM / Carthage / 手动三种安装方式，跨平台支持 iOS、iPadOS 和 macOS。
核心功能包括：集成 MFMailComposeViewController 一键发送、按 session 分的系统日志、DiagnosticsReportFilter 过滤敏感数据、DiagnosticsLogger 自定义日志、目录树报告（DirectoryTreesReporter）。
为什么这个库能活 7 年
iOS 开发工具的生命周期通常很短——Apple 每年 WWDC 发布新 API，很多第三方库就死了。Diagnostics 能活 7 年，原因很简单：它解决的是一个 Apple 永远不会解决的问题。
Apple 提供 Crashlytics、Firebase Crash Reporting，但这些是「崩溃监控」，不是「用户主动诊断」。用户遇到「app 变慢」「某个功能不正常但没崩溃」这类问题时，崩溃监控工具抓不到。Diagnostics 解决的是「非崩溃类问题」的诊断。
这是它的护城河：不是跟 Apple 竞争，而是补 Apple 没做的部分。
v7.0 到底改了什么
之前的版本，报告是一个 HTML 文件。人打开浏览器能看，但 AI agent 打开就懵了——HTML 是给人渲染的，不是给机器解析的。
v7.0 的核心变化：报告仍然是单个 HTML 附件，但内嵌了一份结构化 JSON。
这段 JSON 藏在 HTML 的一个 script 标签里，包含报告元数据、agent hints、结构化 chapters、session 元数据、日志事件（debug/system/error/crash 级别）。
这意味着什么？你的 AI agent——Claude、Cursor、或者任何支持 Agent Skill 的工具——拿到这份报告后，不需要渲染 HTML，直接解析 JSON 就能定位问题。日志级别、session 元数据、agent hints，全是结构化字段，不需要任何 HTML 解析器。
如果你的工作流完全消费 JSON，甚至可以跳过 HTML，直接生成纯 JSON 报告：
let report = await DiagnosticsReporter.create(format: .json)
浏览器视图仍然从 JSON 生成，向后兼容 legacyHTML，老用户升级无感。
Agent Skill：一行命令装好
v7.0 还带了一个可安装的 Agent Skill：
npx skills add https://github.com/AvdLee/Diagnostics --skill diagnostics-report-analyzer-skill
装完之后，你的 AI 编码助手就知道怎么分析 Diagnostics 报告了。它知道 JSON 的 schema，知道哪些字段优先看，知道怎么从 crash log 反推问题根因。
支持 Claude、Cursor、OpenAI 兼容工具。
这不是「把文档喂给 GPT」的粗糙做法。这是一个专门设计给 agent 消费的结构化数据 + 专门设计给 agent 使用的分析技能。两件事合在一起，才是「Agent-friendly」的完整含义。
实际使用场景
假设你收到一份用户发来的诊断报告，里面有 500 行日志。传统做法：打开 HTML，搜索「error」，逐行看，耗时 30 分钟。
用 Agent Skill：把报告拖给 Claude，说「分析这份报告，找出最可能的崩溃原因」。Claude 直接解析 JSON，3 秒后告诉你：「发现 3 个 error 级别日志，都在 session20260708142300，错误类型是 NSInternalInconsistencyException，最可能的原因是 UITableView 数据源不一致。建议检查 numberOfRowsInSection 和 cellForRowAt 的数据同步。」
这就是 Agent Skill 的价值：不是替代开发者，而是把「30 分钟人工排查」变成「3 秒自动定位」。
Smart Insights：不只是记录，还能预警
Diagnostics 还有一个容易被忽略的功能：Smart Insights。
它会自动分析你的报告，给出类似这样的提示：
→ 「⚠️ 用户存储空间不足」
→ 「✅ 用户使用的是最新版本」
→ 「⚠️ 发现本地化相关错误」
这些 insight 是插件化的，你可以写自己的 provider，根据报告内容生成任何自定义警告。比如检测到某个特定 error 出现 3 次以上，自动标记为「高优先级」。
底层实现很简单：SmartInsightsProviding 协议接收一个 DiagnosticsChapter，返回一组 SmartInsightProviding。你可以用 html.errorLogs、.debugLogs、.systemLogs 快速访问特定日志。
UpdateAvailableInsight 用 bundle identifier 从 App Store 拉最新版本，DeviceStorageInsight 检测设备存储。你可以扩展这套机制，加入业务相关的检查——比如检测到用户 3 天没登录，自动标记为「流失风险」。
为什么 Smart Insights 比日志更重要
日志是「发生了什么」，Smart Insights 是「这意味着什么」。
用户发来 500 行日志，你看到「Error: network timeout」，然后呢？你需要自己判断：是用户网络问题，还是服务端问题？是偶发，还是系统性故障？
Smart Insights 帮你做这个判断。它不是简单地把日志展示给你，而是分析日志、给出结论、提供行动建议。这就是「被动记录」和「主动预警」的区别。
v7.0 的 Agent Skill 把这个能力又往前推了一步：agent 不仅能看 Smart Insights，还能自己分析原始日志、生成新的 insight。这是「工具内置智能」和「agent 增强智能」的结合。
对 iOS 开发者意味着什么
这件事的意义不只是「多了一个库的更新」。它代表了一个趋势：iOS 开发工具正在从「人读」转向「agent 读」。
以前的诊断报告，设计目标是让支持团队的人打开浏览器看懂。现在的诊断报告，设计目标是让 AI agent 解析 JSON 直接定位问题。
对你的实际影响：
→ 用户反馈的处理速度会快 10 倍（agent 秒级分析 vs 人工小时级排查）
→ 支持成本会大幅下降（agent 自动分类 + 路由 + 初步诊断）
→ 你的 app 需要「agent-ready」的诊断输出（结构化 JSON，不是 HTML）
想想看：用户发一封邮件，你的 agent 3 秒内解析完 JSON，自动判断是「存储空间不足」还是「网络超时」，然后路由给对应的支持文档或人工处理。整个流程从「5 封邮件来回」变成「1 封邮件 + 3 秒自动诊断」。
更深层的变化：开发者的角色在变
以前开发者是「问题排查者」，现在开发者是「agent 训练者」。你不再需要亲自看每一份诊断报告，而是训练 agent 看报告、分类问题、给出建议。
这意味着你的技能树要加一项：设计 agent-friendly 的数据结构。不是「我的代码能跑」，而是「我的输出能被 agent 消费」。
Diagnostics v7.0 就是一个例子：它的核心创新不是「生成诊断报告」（这个功能 7 年前就有），而是「让报告能被 agent 直接消费」（内嵌 JSON + Agent Skill）。
一个判断：Agent Skill 会成为标配吗
我的判断是：6 个月内，主流 iOS 开发工具都会带 Agent Skill。
理由很简单：
→ Claude、Cursor、Codex 都在推 skill/plugin 生态
→ 开发者已经习惯「装一个 skill 就能用」的体验
→ 工具作者发现：写一个 skill 的成本（几百行 markdown + JSON schema）远低于写文档，但效果好在 agent 真的能「用」
Diagnostics 是第一批吃螃蟹的。它证明了一件事：你的工具如果有结构化输出 + 一个 agent skill，就能无缝接入 AI 工作流。
对比一下传统做法：写一份 50 页的 PDF 文档，用户打开、搜索、复制粘贴给 GPT。新做法：工具直接输出 JSON，agent 直接解析、直接分析、直接给出建议。中间没有任何人工环节。
工程考古：Diagnostics 7 年迭代的关键节点
这个库从 2019 年 WeTransfer hackathon 起步，到现在 v7.0 经历了几个关键转折点：
→ v1.0（2019）：基础 HTML 报告，集成 MFMailComposeViewController。解决了「用户怎么把诊断信息发给我」的问题
→ v3.0（2021）：加入 DiagnosticsReportFilter，解决「敏感数据泄露」问题。企业用户开始大规模采用
→ v5.0（2023）：Smart Insights 插件化，DeviceStorageInsight、UpdateAvailableInsight 内置。从「被动记录」转向「主动预警」
→ v7.0（2026）：Agent-friendly JSON + Agent Skill。从「人读」转向「agent 读」
每个版本解决一个核心痛点，不贪多。这是小工具长成大生态的典型路径。
HTML 报告 vs JSON 报告：为什么 agent 读不了 HTML
HTML 是给浏览器渲染的，不是给机器解析的。一个 HTML 报告里，「设备型号」可能在第 3 个 div 的第 2 个 span 里，class 名是 diagnostics-item-value。agent 要解析这个，需要：
加载 HTML 解析器 理解 DOM 结构 用 CSS selector 定位元素 提取文本内容
而 JSON 报告里，「设备型号」就是 metadata.device_model。agent 直接读字段，不需要任何解析器。
这就是为什么 v7.0 要内嵌 JSON：让 agent 能直接消费数据，而不是先「看懂」HTML。
相关工具对比
iOS 诊断领域还有几个选择：
→ Bugsnag / Sentry：云端服务，实时崩溃监控。适合大型团队，但有隐私合规问题
→ Firebase Crashlytics：Google 生态，免费但锁定 Google 服务
→ Diagnostics：本地生成报告，用户主动发送。适合注重隐私、不想依赖云服务的团队
Diagnostics 的优势是「用户主动发送」，数据不经过第三方。劣势是没有实时监控，只能等用户发邮件。v7.0 的 Agent Skill 让「用户主动发送」这个模式变得更高效：agent 秒级分析，不需要人工排查。
3 条行动建议
→ 今天：去 GitHub 看 Diagnostics 的 README，理解 JSON schema 的设计思路。重点看 agent_hints 字段，这是给 agent 的「导航地图」
→ 本周：如果你的 app 有诊断/日志功能，考虑加一个 JSON 输出模式。不需要重写，只需要在现有 HTML 报告里嵌入一个 script 标签
→ 本月：为你的工具写一个 Agent Skill（几百行 markdown，成本极低，收益极高）。参考 Diagnostics 的 skill 结构：schema 说明 + 字段优先级 + 常见问题诊断规则
把重复的诊断分析交给 agent，把判断和决策留给自己。
如何评估你的工具是否 agent-ready
问自己 3 个问题：
→ 你的工具输出是结构化数据（JSON/XML）还是非结构化数据（HTML/PDF/纯文本）？
→ 你的文档是「给人看的教程」还是「给 agent 用的 schema + 示例」？
→ 你的工具有没有可安装的 skill/plugin，让 agent 知道怎么用？
如果 3 个问题的答案都是「否」，你的工具还不是 agent-ready。Diagnostics v7.0 给出了一个参考答案：保持原有输出（HTML），新增结构化输出（JSON），再写一个 Agent Skill。成本不高，但能让你的工具接入 AI 工作流。
一个更大的趋势：开发工具正在「双轨化」
以前的开发工具只有一种输出：给人看的。现在的开发工具需要两种输出：给人看的 + 给 agent 读的。
Diagnostics v7.0 的 HTML 报告是给人看的，JSON 报告是给 agent 读的。Agent Skill 是告诉 agent「怎么读」。
这不是 Diagnostics 一个工具的选择，而是整个开发工具生态的趋势。6 个月内，你会看到越来越多工具加入「agent-friendly」模式。早加入的工具，会率先接入 AI 工作流，获得先发优势。
如果你也在做 iOS 开发工具，或者对 AI agent 接入开发工作流感兴趣，转发给那个天天被用户 bug 报告折磨的同事。收藏起来，下次给你的 app 加诊断功能时翻。关注我，不错过下一个「工具 × agent」的实战案例。
P.S. Antoine 每天在 swiftlee.com 写 iOS 开发笔记，想持续 follow 可以去 @twannl。这个 Diagnostics 库已经迭代 7 年，从 WeTransfer hackathon 到现在的 Agent Skill，是一个「小工具长成大生态」的活样本。
