啄幕鸟，即在手机屏幕上的啄木鸟，专门抓取 App 中的 Bug。啄幕鸟集成了 UI 检查、对象查看、方法监听等多种开发工具，通过拾取 UI 控件、查看对象属性、监听方法调用、App 内抓包等，无需依赖电脑联调，直接获取运行时数据，快速定位 Bug，提高开发效率。啄幕鸟提供了一个插件化的工具平台，简单易用，零侵入、零依赖、易接入、易扩展。

功能简介

1.UI检查：快速查看页面布局、UI控件间距、字体颜色、UI控件类名、对象属性/成员变量、图片 URL 等。
2.JSON 抓包：便捷的 JSON 抓包工具，通过监听系统 json 解析抓包。
3.方法监听：Bug 听诊器，可以监听 App 中任意 OC 方法的调用，输出调用参数、返回值等信息，可以通过屏幕日志输入监听、KVC 取值等命令，支持后台配置命令。
4.po 命令：执行类似 LLDB 的 po 命令，在 App 运行时执行 po 命令，调用任意方法。
5.系统信息：查看各种系统名称、版本、屏幕、UA 等信息，支持外部添加信息。
SandBox：查看沙盒文件，导出文件等。
Bundle：查看、导出 Bundle 目录中的内容。
Crash：查看 Crash 日志，需要先打开一次 Crash 插件以开启 Crash 监控。
Defaults：查看、添加、删除 User Defaults。
清除数据：清除所有沙盒数据、User Default。
触点显示：显示手指触控。
UI 对比：支持将设计图导入到 App 中进行对比，并可画线、标注需修改的地方，方便 UI 走查。
查看图片资源：查看、导出 App 中的资源图片。
CPU：查看 CPU 占用。
内存：查看内存占用。
FPS：查看 App 帧率。
网络流量：查看发送、接收网络流量。

啄幕鸟插件

接入

版本要求

iOS 8.0 及以上。

Pod 接入

pod  'YKWoodpecker'

推荐更新使用最新版本的啄幕鸟，现最新版本：1.2.8。

开始

打开啄幕鸟

#import "YKWoodpecker.h"

   // 方法监听命令配置JSON地址 * 可选，如无单独配置，可使用 https://github.com/ZimWoodpecker/WoodpeckerCmdSource 上的配置
   [YKWoodpeckerManager sharedInstance].cmdSourceUrl = @"https://raw.githubusercontent.com/ZimWoodpecker/WoodpeckerCmdSource/master/cmdSource/default/cmds_cn.json";
   
   // Release 下可开启安全模式，只支持打开安全插件 * 可选
#ifndef DEBUG
   [YKWoodpeckerManager sharedInstance].safePluginMode = YES;
#endif

   // 设置 parseDelegate，可通过 YKWCmdCoreCmdParseDelegate 协议实现自定义命令 * 可选
   [YKWoodpeckerManager sharedInstance].cmdCore.parseDelegate = self;
   
   // 显示啄幕鸟
   [[YKWoodpeckerManager sharedInstance] show];
   
   // 启动时可直接打开某一插件 * 可选
//    [[YKWoodpeckerManager sharedInstance] openPluginNamed:@"xxx"];

更多参见Demo工程。

运行Demo

在clone后，在工程目录执行'pod update'，完成后即可打开demo workspace运行。

安全说明

啄幕鸟不依赖任何第三方库或数据。啄幕鸟代码中没有使用任何+load、+initialize等方法，啄幕鸟入口不显示则不会执行任何代码。如需线上使用啄幕鸟，应保护好开启入口，啄幕鸟支持安全模式，可在Release下开启安全模式，只支持打开安全插件，现有安全插件：UI检查、系统信息、触点显示。扩展插件注册时设置isSafePlugin=YES即可声明为安全插件，详见插件开发。

   // Release 下可开启安全模式，只支持打开安全插件 * 可选
#ifndef DEBUG
   [YKWoodpeckerManager sharedInstance].safePluginMode = YES;
#endif

插件功能介绍

1. UI检查插件

UI检查插件包括控件拾取和测距条两个工具，在屏幕上轻轻一点即可获取布局、颜色、字体、圆角、图片URL等信息。

UI检查插件

1.1 控件拾取

控件拾取根据手指在屏幕上的点击坐标，递归遍历View层级，获取包含触点坐标的最靠前的UI元素，在屏幕上直观显示相关信息，也可帮助了解UI布局、定位UI代码。

控件拾取功能

◆ 单击拾取当前点击的view，双击可跳过当前view，以拾取下层view，以防止view被同级view挡住拾取不到。
◆ 三个手指同时点击可切换拾取模式，只拾取响应链上的view，以防止屏幕上盖了一层view，影响拾取。
◆ 拾取后用线条和标注显示被拾取view的大小、位置，或与之前选中view的间距，简单直观，无需计算。
◆ 控件拾取信息区显示控件的类名、大小、透明度、圆角、hidden、文本、字体、颜色、图片尺寸、图片URL等信息，方便地获取运行时数据。
◆ 信息区提供父层按钮，点击拾取superview，层层拾取，即可了解UI布局，并根据view类名快速定位代码。
◆ 信息区根据选中元素的不同，提供文本、图片等按钮，以复制文本，查看、导出图片。
◆ 单击信息区可打开分享面板导出信息。
◆ 双击信息区可查看对象全部属性、成员变量。

UI检查-拾取控件

控件拾取功能扩展

可以通过系统通知获得拾取到的控件并在信息区域显示自定义信息，格式如下：

extern NSString *const YKWPluginSendMessageNotification;       /**< 插件发送信息通知 = @"YKWPluginSendMessageNotification" > */
extern NSString *const YKWPluginReceiveMessageNotification;    /**< 插件接收信息通知 = @"YKWPluginReceiveMessageNotification" > */
/*
控件拾取插件：
   发送格式：
   notification.object = @"ProbePluginNotification";
   notification.userInfo[@"view"] = 拾取到的UIView;
   接收格式：
   notification.object = @"ProbePluginNotification";
   notification.userInfo[@"msg"] = 需要显示的信息;
*/

1.2 对象查看

App中所有的对象通过继承、代理、属性等关系，可以看作一个或多个连通图，从一个对象开始，可以查看到连通图里任一个对象的属性、成员变量，获取运行时数据，以定位问题。

对象查看功能

◆ 双击控件拾取的信息区即可打开对象查看，对象查看会显示拾取对象的属性、成员变量列表。
◆ 一个对象的属性、成员变量一般声明在不同的类中，一个列表只显示对象在某一类中声明的属性、成员变量，点击superclass即可查看父类中的声明。
◆ 在属性、成员变量列表中单击查看下一对象，双击打印对象description。
◆ KVC取值：在日志控制台中输入 k key.path 格式即可对最右侧列表对象KVC取值，如输入 k layer.cornerRadius 即可读取圆角大小。
◆ 点击“屏显控件”可将UIView及其子类对象在控件拾取中显示。
◆ 可在对象查看中使用po命令，详见po命令介绍。

查看对象全部属性

1.3 测距条

对于某些不能通过控件拾取查看的大小间距，如行间距等，啄幕鸟提供了测距条工具，在屏幕上添加大小、位置可控的View作为标尺测量间距。

测距条功能

◆ 点击“+”添加一个测距条，可添加任意多个测距条。
◆ 双击一个测距条可以将其删除。
◆ 单击一个测距条可将其选中，以改变其位置大小。
◆ 可在输入框按宽高输入测距条大小。
◆ 可通过按钮控制测距条的位置大小，按钮支持长按。
◆ 点击“Dp”可改变控制精度为dp或像素。

UI检查-测距条

2 JSON抓包插件

JSON抓包插件通过监听[NSJSONSerialization JSONObjectWithData:options:error:]方法抓取数据，对于不使用此方法解析的JSON则无法抓包。

JSON抓包功能

◆ 打开插件自动开始监听JSON解析，提取数据。 ◆ 可能会提取多条数据，可以通过数据长度来区分。 ◆ 点击可查看、搜索提取到的JSON数据。 ◆ 长按数据可以通过Airdrop等方式分享JSON数据。

3 方法监听插件

3.1 屏幕日志

为方便各插件在App内显示日志、接收用户输入，啄幕鸟中添加了屏幕日志模块。

屏幕日志功能

◆ 可拖动空白区域调整屏幕日志的位置，拖动“◢”按钮调整界面大小。
◆ 日志颜色可自定义，以便区分日志类型。
◆ 屏幕日志支持正则表达式和目标字符串过滤不想要的日志，正则表达式过滤只会显示正则匹配到的日志，目标字符串会过滤掉不包含目标字符串的日志。
◆ 屏幕日志支持日志搜索，点击ⓢ按钮可以打开/关闭日志搜索框，搜索支持正则表达式。
◆ 日志可以通过分享面板导出。
◆ 屏幕日志支持界面扩展，可在屏幕日志下方添加自定义View，展示自定义功能，自定义View会随屏幕日志移动及改变宽度。

系统信息插件中直接使用了屏幕日志显示信息

3.2 方法监听

方法监听利用OC的运行时机制，Hook被监听方法，输出方法调用参数、返回值、调用栈等信息，动态获取运行时数据，辅助调试。监听网络方法即可实现App内抓包功能。

方法监听功能

◆ 使用命令行交互，扩展性强，功能多样。
◆ 支持后台配置命令，方便快速输入命令。
◆ 可监听实例方法、类方法，支持同时监听多个对象、多个方法。
◆ 通过屏幕日志输出监听到参数、返回值，以JSON格式化显示。
◆ 可保存监听到对象、返回值，可使用命令对其KVC取值。
◆ 可保存监听到方法的调用栈，可使用相关命令查看。

方法监听

3.3 方法监听命令

方法监听需要输入类名、方法名、keypath等参数，因此使用命令行交互，扩展性好，配合命令配置，输入也相对方便。

命令简介

◆ 命令使用统一的格式：<命令名缩写><空格><命名参数><空格><命名参数>，例如监听命令 L className methodName，KVC取值命令 k keyPath，调用栈查看命令k callStack。
◆ 命令名缩写不区分大小写，便于输入。
◆ 命令可通過后台配置实现一键输入，多条命令以分号分隔。
◆ 命令支持扩展。

命令说明

查看输入历史

命令格式： h/H
输入h或H后按回车键，会显示输入历史记录；输入记录前的数字后按回车键，可实现快速输入命令；也可在任何状态下输入1后按回车键，快速输入上次输入的命令。

输入历史命令

方法监听

添加实例方法监听命令格式： l/L ClassName Method:Name
按照上述格式输入后回车，将会Hook相应类的类方法或实例方法，并显示监听成功。下次对应方法被调用时，将按照OC语法格式显示方法调用时传入的参数及返回值的描述。
注意，方法监听可能存在风险。例如，同时监听子类和父类的同名方法可能导致崩溃；监听基础类的常用方法也可能导致崩溃，例如监听UIView的setFrame:方法时，由于显示日志也需要调用setFrame:方法，可能会形成循环调用；监听调用频繁的方法会产生大量日志，可能造成程序卡死等。暂未对此功能做限制，因此，使用方法监听功能可能会导致App变得不稳定，应谨慎使用。

点击AF请求按钮后，监听到NSJSONSerialization方法被调用，显示日志

查看正在监听的方法列表命令： l/L
可同时添加多个方法监听，输入l或L可显示所有正在监听的类及方法名。

清除所有监听命令格式： l/L clr
按照上述格式输入会移除所有方法监听。（clr：clear的缩写）

查看监听到的对象

查看监听到的对象命令格式： k/K
方法监听命令会将监听到的对象参数保存在一个数组中（非对象参数不保存），每次监听到某个方法调用都会更新数组，输入k或K后按回车键，可查看数组内容。数组中第一个对象为self，即被监听类的实例，之后按参数传递顺序排列，如有返回对象则保存在最后。
输入k callStack可以查看监听到的调用栈。

对监听到第N个对象KeyPath取值： k/K N Key.Path
可以对监听到的对象进行KeyPath取值，例如监听到UIView addSubview:方法后（当然不建议监听这个方法），监听数组会存放对应的(superview，subview)，输入k 2 layer.cornerRadius可读取subview的圆角大小。

监听到AFJSONResponseSerializer相关方法后，输入"k 2 URL"读取参数列表第二个对象的URL属性，获取URL。输入"k"即可查看监听到的参数、返回值列表。

添加监听后命令

添加监听后命令格式：p/P
监听后命令会在监听到任意方法调用之后执行，目前仅支持k命令，例如输入"p k"添加监听后命令k后，每次监听到方法调用都会执行k命令输出监听到的参数和返回值。

目标字符串日志过滤

添加目标字符串命令格式：f/F ToFindString
目标字符串：可以在日志控制台添加目标字符串，添加后，只会输出包含目标字符串的日志，其他日志会显示<日志不包含目标字符串>，用于过滤日志（基本信息输出不过滤）。

执行"f {"命令，添加"{"为目标字符串，因为只有返回值包含目标字符串"{"，所以只显示了返回值的日志，其他日志被过滤。

查看目标字符串列表：f/F
可以添加多条目标字符串，一条日志必须包含列表中所有目标字符串才会被显示，输入f或F可以查看当前目标字符串列表。

清空目标字符串列表：f/F clr

正则表达式日志过滤

添加过滤正则表达式：r/R RegExpression
正则表达式过滤：添加过滤正则后，只会输出正则匹配到的字符串，其他日志会显示<日志不匹配正则>，用于过滤日志（基本信息输出不过滤）。

执行"r ("cmdName" : ".+")"命令，添加"("cmdName" : ".+")"为过滤正则，则只会显示正则匹配出的日志。

查看正则列表：r/R
可以添加多个正则表达式，每一个匹配都会输出，输入r或R可以查看当前正则列表。

清空过滤正则列表：r/R clr

3.4 自定义命令

方法监听支持命令扩展，可以通过 YKWCmdCoreCmdParseDelegate 协议获取命令并解析执行自定义操作。

#import "YKWoodpecker.h"
// 设置命令解析代理
[YKWoodpeckerManager sharedInstance].cmdCore.parseDelegate = self;
#pragma mark - YKWCmdCoreCmdParseDelegate // 实现命令解析协议，

(BOOL)cmdCore:(YKWCmdCore *)core shouldParseCmd:(NSString *)cmdStr { // 判断是否为自定义命令 if ([cmdStr hasPrefix:@"MyCmd"]) { // 处理自定义命令 // ------- // 显示日志 [[YKWoodpeckerManager sharedInstance].screenLog log:@"Calling my cmd"]; return NO; } return YES; }

3.5 后台命令配置

后台命令配置将显示在屏幕日志下方，方便命令输入，使用以下格式的JSON提供命令配置。

命令配置JSON格式

可以在啄幕鸟初始化时指定配置JSON的获取地址，否则使用默认配置。建议在 https://github.com/ZimWoodpecker/WoodpeckerCmdSource 工程中建立配置，方便命令共享。

4 po命令插件

po命令是iOS开发中最常用的Debug命令，啄屏鸟让您在App运行时随时随地执行po命令，随时随地Debug。

po命令功能

◆ 输入h可查看输入历史记录。
◆ 其他功能几乎与LLDB po命令相同。
◆ 输入po [N ...]即可对列表中第N个对象执行po命令。

po命令

⚠当前po命令仅支持入参为int、long、BOOL、float、double、NSString、NSNumber，返回值为空、int、long、BOOL、float、double、id类型的方法，且参数不超过3个，嵌套不超过两层调用，po命令还在进一步优化中，欢迎共建，敬请期待。

5 系统信息插件

系统信息插件可以方便地查看系统、版本、用户代理等信息。

系统信息插件

系统信息插件功能扩展

可以通过通知添加自定义信息显示，格式如下：

extern NSString *const YKWPluginSendMessageNotification;       /**< 插件发送信息通知 = @"YKWPluginSendMessageNotification" > */
extern NSString *const YKWPluginReceiveMessageNotification;    /**< 插件接收信息通知 = @"YKWPluginReceiveMessageNotification" > */
/*
系统信息插件：
   发送格式：
   notification.object = @"SysInfoNotification";
   接收格式：
   notification.object = @"SysInfoNotification";
   notification.userInfo[@"msg"] = 需要显示的信息;
*/

6 SandBox插件、Bundle插件

SandBox插件用于查看App沙盒文件，Bundle插件用于查看Bundle目录，支持打开文本、图片类文件，或通过AirDrop等方式导出文件。

7 Crash插件

查看crash日志需要在crash插件中预先开启crash监控，crash发生后可再次打开查看crash日志，还可以通过AirDrop等方式分享日志。

8 Defaults插件

Defaults插件支持搜索、查看、删除User Defaults，新增、修改字符串类型或数字类型的User Defaults。

9 清除数据插件

清除数据插件会将App沙盒目录下各文件夹清空，清除所有相关数据以及user defaults。

10 触点显示插件

打开触点插件将交换UIWindow的sendEvent:方法，在每个点击位置显示水波动画，便于录屏等场景显示触点。

11 UI对比插件

UI对比可以从不内置相册中导入设计图片，以与App进行设计还原度比较。

UI对比功能

◆ 点击“+”按钮导入图片，支持多张，可移动。若图片大小与屏幕相同，则图片不可移动。
◆ 点击图片可选择，滑动滑块可调整图片透明度。
◆ 点击“-”按钮删除图片。
◆ 点击“✎”按钮打开/关闭画线功能。
◆ 点击“↺”按钮撤销一次画线。

UI对比插件

12 查看图片资源插件

查看App中所有内置图片，Assets图片经过加密压缩，暂不支持查看。

13 性能插件

性能插件主要有CPU、内存、FPS和网络流量插件，可实时查看App的相关性能。

插件开发

插件协议

啄幕鸟采用插件式开发，所有插件必须遵循YKWPluginProtocol协议，实现runWithParameters方法，点击插件时将执行此方法启动插件。不会强制校验是否遵循YKWPluginProtocol，只要实现协议方法即可。

#import "YKWPluginProtocol.h"

@protocol YKWPluginProtocol <NSObject>

- (void)runWithParameters:(NSDictionary *)paraDic;

@end

内部插件

内部插件将随啄幕鸟开源，新插件需要实现YKWPluginProtocol协议中的方法，并在plist文件中添加相关插件信息，测试无bug后即可通过pull request合并到项目中。

外部插件

可以在啄幕鸟中使用任何符合插件协议的第三方类作为插件打开，使用以下方法注册插件：

#import "YKWoodpecker.h"

/**
注册插件

@param parasDic 格式参见 YKWPluginModel
@{
@"isSafePlugin" : @(NO),
@"pluginName" : @"",
@"pluginIconName" : @"",
@"pluginCharIconText" : @"",
@"pluginCharIconColorHex" : @"",
@"pluginCategoryName" : @"",
@"pluginClassName" : @"",
@"pluginParameters" : @{}
}
@param position 插件显示位置，0...N-1, -1显示在最后

*/
- (void)registerPluginWithParameters:(NSDictionary *)parasDic atIndex:(NSInteger)position;
- (void)registerPluginWithParameters:(NSDictionary *)parasDic;
- (void)registerPluginCategory:(NSString *)pluginCategoryName atIndex:(NSInteger)index;

建议使用pluginCharIconText指定一个字符作为插件图标，以节省包大小。

// Demo for registering a plugin
[[YKWoodpeckerManager sharedInstance] registerPluginWithParameters:@{@"pluginName" : @"XXX",
                                                                    @"isSafePlugin" : @(NO),
                                                                    @"pluginInfo" : @"by user_XX",
                                                                    @"pluginCharIconText" : @"x",
                                                                    @"pluginCategoryName" : @"自定义",
                                                                    @"pluginClassName" : @"ClassName"}];

可以使用registerPluginCategory:atIndex:方法添加工具类别，并自定义显示位置。

 /**
Register a plugin category or change the position of a plugin category.

@param pluginCategoryName Plugin category name.
@param index Position to show the category, 0...N-1, or -1 for the last.
*/
- (void)registerPluginCategory:(NSString *)pluginCategoryName atIndex:(NSInteger)index;

安全插件

在安全模式下只能打开安全插件，注册安全插件时需设置isSafePlugin=YES。

YKWoodpecker 1.2.9

YKWoodpecker 1.2.9

YKWoodpecker 1.2.9

功能简介

接入

版本要求

Pod 接入

开始

打开啄幕鸟

运行Demo

安全说明

插件功能介绍

1. UI检查插件

1.1 控件拾取

控件拾取功能

控件拾取功能扩展

1.2 对象查看

对象查看功能

1.3 测距条

测距条功能

2 JSON抓包插件

JSON抓包功能

3 方法监听插件

3.1 屏幕日志

屏幕日志功能

3.2 方法监听

方法监听功能

3.3 方法监听命令

命令简介

命令说明

查看输入历史

方法监听

查看监听到的对象

添加监听后命令

目标字符串日志过滤

正则表达式日志过滤

3.4 自定义命令

3.5 后台命令配置

4 po命令插件

po命令功能

5 系统信息插件

系统信息插件功能扩展

6 SandBox插件、Bundle插件

7 Crash插件

8 Defaults插件

9 清除数据插件

10 触点显示插件

11 UI对比插件

UI对比功能

12 查看图片资源插件

13 性能插件

插件开发

插件协议

内部插件

外部插件

安全插件

作者

贡献者

许可证

架构