@windypro-rourou/dsh-logcat 0.5.0-preview.2 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +94 -94
- package/lib/client.js +836 -768
- package/lib/index.js +2026 -1976
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,94 +1,94 @@
|
|
|
1
|
-
# dsh-logcat
|
|
2
|
-
|
|
3
|
-
DSH Web GUI 的安卓实机调试面板（类似 Android Studio 的 Logcat 视图）。
|
|
4
|
-
|
|
5
|
-
## 功能
|
|
6
|
-
|
|
7
|
-
- **自动连接**：探测本机 adb（`ANDROID_HOME` / `ANDROID_SDK_ROOT` / 默认 `%LOCALAPPDATA%\Android\Sdk` / PATH /
|
|
8
|
-
`~/.dsh/adb`），每 2 秒轮询 `adb devices -l`；检测到处于调试模式的设备**自动附加 logcat 流**（`-v threadtime`），无需打开面板。
|
|
9
|
-
- **一键安装 adb**：未找到 adb 时，面板状态栏显示「一键安装 adb」按钮 —— 从 USTC 镜像（Google 官方兜底）
|
|
10
|
-
下载 platform-tools 解压到 `~/.dsh/adb` 并自动接入，开箱即用（约 10MB）。
|
|
11
|
-
- **实时日志**：WebSocket 推送，每设备保留最近 2000 行环形缓冲；断线自动重连（指数退避）。
|
|
12
|
-
- **Logcat 面板**（侧边栏「Logcat」入口，右侧抽屉，**宽度可拖拽调整并记忆**）：
|
|
13
|
-
- 设备下拉（显示型号/序列号/状态，记住上次选择）
|
|
14
|
-
- 级别过滤（V/D/I/W/E/F 单选，颜色与 Android Studio 一致）
|
|
15
|
-
- 关键词过滤、**测试包名输入框**（回车设置，与 agent 的 `logcat_set_package` 互通，状态栏实时显示）
|
|
16
|
-
- **截图按钮**：一键截取真机屏幕并下载 PNG（`exec-out screencap`）
|
|
17
|
-
- **崩溃高亮**：FATAL EXCEPTION / ANR 行红色高亮，一眼定位崩溃
|
|
18
|
-
- 暂停/继续（暂停时缓冲，恢复自动回放）、清空、复制、导出 .txt
|
|
19
|
-
- 窗口化渲染 + 自动滚动（滚动手动上翻时自动停用）
|
|
20
|
-
- 未授权设备提示「请在手机上点击允许 USB 调试」
|
|
21
|
-
- **Agent 工具**（共 21 个，全部对 agent 开放，前置提示中已明示可调用）：
|
|
22
|
-
- 设备：`logcat_devices`（列出设备）、`device_info`（型号/版本/SDK/分辨率/内存/电量）、`device_stats`（CPU/内存/电量实时采样）
|
|
23
|
-
- 执行：`adb_exec`（shell）、`adb_install`（本地 APK 装真机）、`adb_pull`（拉文件）
|
|
24
|
-
- 输入：`input_tap` / `input_swipe` / `input_text`（真机 UI 自动化）、`ui_dump`（界面层级 XML）
|
|
25
|
-
- 日志：`logcat_recent`（按包名/级别/关键词过滤）、`logcat_crash`（崩溃/ANR 自动捕获 + 上下文）、
|
|
26
|
-
`logcat_set_package`（锁定当前测试包名）
|
|
27
|
-
- 逆向/内存：`proc_list`（进程列表）、`proc_maps`（内存映射 + so 模块基址）、`proc_status`（进程状态/内存摘要）、
|
|
28
|
-
`proc_smaps`（smaps 明细，Pss Top 区域）、`mem_dump`（指定地址读内存 hex）、
|
|
29
|
-
`mem_search`（内存搜 hex 模式/字符串）、`frida_server`（frida-server 部署/启停）、
|
|
30
|
-
`frida_script`（hook/trace/scan/bypass/dump 常用脚本模板生成）
|
|
31
|
-
- **实机调试工作流**：构建安卓应用时，agent 的通告会动态列出当前已连接设备（serial + 型号）与当前测试包名，
|
|
32
|
-
可先向用户确认后：`adb_install` 部署 APK → `adb_exec` 启动 → `logcat_set_package` 锁包 →
|
|
33
|
-
`logcat_recent` / `logcat_crash` 看崩溃 → `ui_dump` + `input_*` 做界面自动化 → `adb_pull` 取证，闭环真机调试。
|
|
34
|
-
- **逆向工作流**：`proc_list` 定位进程 → `proc_maps` 拿模块基址 → `mem_dump` 读目标地址 / `mem_search` 搜特征模式 →
|
|
35
|
-
`proc_smaps` 看内存占用明细 → `frida_script` 生成脚本 + `frida_server` 起 frida 做动态插桩。
|
|
36
|
-
读其他应用内存/maps 需要 root 或 debuggable 应用（run-as），工具会给出明确提示。
|
|
37
|
-
- **附加能力**：`POST /api/dsh-logcat/exec` 执行 shell、`POST /api/dsh-logcat/package` 设置包名、
|
|
38
|
-
`GET /api/dsh-logcat/screenshot` 截屏、`POST /api/dsh-logcat/install-adb` 一键装 adb。
|
|
39
|
-
|
|
40
|
-
## 安装
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
# 方式一（推荐，npm 安装）：
|
|
44
|
-
dsh plugin --profile web add @windypro-rourou/dsh-logcat
|
|
45
|
-
|
|
46
|
-
# 更新到最新版（不会自动更新；装旧版时面板/agent 通告会提示有新版本）：
|
|
47
|
-
dsh plugin --profile web update # 升到当前 major 内最新
|
|
48
|
-
# 或强制最新：dsh plugin --profile web add @windypro-rourou/dsh-logcat@latest
|
|
49
|
-
# 更新后重启 GUI（dsh web）生效
|
|
50
|
-
|
|
51
|
-
# 尝鲜 preview 版（日常迭代高频更新，可能不稳定）：
|
|
52
|
-
dsh plugin --profile web add @windypro-rourou/dsh-logcat@preview
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
## 发布策略（main / preview 双通道）
|
|
56
|
-
|
|
57
|
-
- **`main` 分支 + npm `latest` 标签**：稳定正式版，**低频发布**，每次至少凑够 3-4 个功能再发，
|
|
58
|
-
避免频繁更新提醒打扰用户。
|
|
59
|
-
- **`preview` 分支 + npm `preview` 标签**：日常迭代，有啥更啥（高频），供尝鲜用户测试；
|
|
60
|
-
凑够足够功能后合并回 `main` 批量发布正式版。
|
|
61
|
-
- 版本自检会按安装通道提示（正式版用户只看 `latest`，preview 用户只看 `preview`，互不打扰）。
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
# 方式二（源码本地链接，实时生效无需重启）：把插件链进 web profile，
|
|
65
|
-
# 并在 ~/.dsh/profiles/web/cordis.patch.yml 增加一行：
|
|
66
|
-
pnpm --dir "%USERPROFILE%\.dsh\profiles\web" add link:F:\dsh-logcat
|
|
67
|
-
# 然后在 profile 的 cordis.patch.yml 追加：
|
|
68
|
-
# - insert:
|
|
69
|
-
# - id: logcat
|
|
70
|
-
# name: '@windypro-rourou/dsh-logcat'
|
|
71
|
-
# 该 patch 文件会被运行中的 GUI 热监听；若未生效，重启 GUI 即可。
|
|
72
|
-
|
|
73
|
-
# 方式三（bundle 层，README 原始流程，适合全新 profile；与方式二互斥，勿混用）：
|
|
74
|
-
dsh plugin --profile web add link:<本目录绝对路径>
|
|
75
|
-
# 之后需要重启 GUI（dsh web）才会装载。
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
> 注意：以上方式都会在 profile 树中插入同一行 `logcat`，不要同时使用，否则下次
|
|
79
|
-
> 启动会因重复插件 id 而失败。
|
|
80
|
-
|
|
81
|
-
依赖解析：`ws` / `react` / `react-dom` / `@deepseek-ai/*` 通过本目录 `node_modules` 下的 junction 指向宿主
|
|
82
|
-
实际加载的物理包（保证单例）。若宿主依赖升级，请同步更新 junction 目标。
|
|
83
|
-
|
|
84
|
-
## 限制
|
|
85
|
-
|
|
86
|
-
- 需要设备开启 USB 调试并在手机上授权本机（`unauthorized` 状态会提示）。
|
|
87
|
-
- logcat 输出可能含敏感信息；`/api/dsh-logcat/*` 路由仅允许 loopback 访问。
|
|
88
|
-
- `adb shell` 命令消耗真实设备资源，先确认再执行。
|
|
89
|
-
|
|
90
|
-
## 文件
|
|
91
|
-
|
|
92
|
-
- `lib/index.js` — 宿主端：adb 引擎、轮询、logcat 子进程、路由、WebSocket、agent 工具。
|
|
93
|
-
- `lib/client.js` — 浏览器端：侧边栏入口 + Logcat 面板（React，无构建步骤）。
|
|
94
|
-
- `cordis.patch.yml` — profile bundle patch（自动应用）。
|
|
1
|
+
# dsh-logcat
|
|
2
|
+
|
|
3
|
+
DSH Web GUI 的安卓实机调试面板（类似 Android Studio 的 Logcat 视图）。
|
|
4
|
+
|
|
5
|
+
## 功能
|
|
6
|
+
|
|
7
|
+
- **自动连接**：探测本机 adb（`ANDROID_HOME` / `ANDROID_SDK_ROOT` / 默认 `%LOCALAPPDATA%\Android\Sdk` / PATH /
|
|
8
|
+
`~/.dsh/adb`），每 2 秒轮询 `adb devices -l`；检测到处于调试模式的设备**自动附加 logcat 流**（`-v threadtime`），无需打开面板。
|
|
9
|
+
- **一键安装 adb**：未找到 adb 时，面板状态栏显示「一键安装 adb」按钮 —— 从 USTC 镜像（Google 官方兜底）
|
|
10
|
+
下载 platform-tools 解压到 `~/.dsh/adb` 并自动接入，开箱即用（约 10MB）。
|
|
11
|
+
- **实时日志**：WebSocket 推送，每设备保留最近 2000 行环形缓冲；断线自动重连（指数退避）。
|
|
12
|
+
- **Logcat 面板**（侧边栏「Logcat」入口，右侧抽屉，**宽度可拖拽调整并记忆**）：
|
|
13
|
+
- 设备下拉（显示型号/序列号/状态，记住上次选择）
|
|
14
|
+
- 级别过滤（V/D/I/W/E/F 单选，颜色与 Android Studio 一致）
|
|
15
|
+
- 关键词过滤、**测试包名输入框**（回车设置，与 agent 的 `logcat_set_package` 互通，状态栏实时显示）
|
|
16
|
+
- **截图按钮**：一键截取真机屏幕并下载 PNG（`exec-out screencap`）
|
|
17
|
+
- **崩溃高亮**：FATAL EXCEPTION / ANR 行红色高亮，一眼定位崩溃
|
|
18
|
+
- 暂停/继续（暂停时缓冲，恢复自动回放）、清空、复制、导出 .txt
|
|
19
|
+
- 窗口化渲染 + 自动滚动（滚动手动上翻时自动停用）
|
|
20
|
+
- 未授权设备提示「请在手机上点击允许 USB 调试」
|
|
21
|
+
- **Agent 工具**（共 21 个，全部对 agent 开放，前置提示中已明示可调用）：
|
|
22
|
+
- 设备：`logcat_devices`（列出设备）、`device_info`（型号/版本/SDK/分辨率/内存/电量）、`device_stats`（CPU/内存/电量实时采样）
|
|
23
|
+
- 执行：`adb_exec`（shell）、`adb_install`（本地 APK 装真机）、`adb_pull`（拉文件）
|
|
24
|
+
- 输入：`input_tap` / `input_swipe` / `input_text`（真机 UI 自动化）、`ui_dump`（界面层级 XML）
|
|
25
|
+
- 日志：`logcat_recent`（按包名/级别/关键词过滤）、`logcat_crash`（崩溃/ANR 自动捕获 + 上下文）、
|
|
26
|
+
`logcat_set_package`（锁定当前测试包名）
|
|
27
|
+
- 逆向/内存：`proc_list`（进程列表）、`proc_maps`（内存映射 + so 模块基址）、`proc_status`（进程状态/内存摘要）、
|
|
28
|
+
`proc_smaps`（smaps 明细，Pss Top 区域）、`mem_dump`（指定地址读内存 hex）、
|
|
29
|
+
`mem_search`（内存搜 hex 模式/字符串）、`frida_server`（frida-server 部署/启停）、
|
|
30
|
+
`frida_script`（hook/trace/scan/bypass/dump 常用脚本模板生成）
|
|
31
|
+
- **实机调试工作流**：构建安卓应用时，agent 的通告会动态列出当前已连接设备（serial + 型号）与当前测试包名，
|
|
32
|
+
可先向用户确认后：`adb_install` 部署 APK → `adb_exec` 启动 → `logcat_set_package` 锁包 →
|
|
33
|
+
`logcat_recent` / `logcat_crash` 看崩溃 → `ui_dump` + `input_*` 做界面自动化 → `adb_pull` 取证，闭环真机调试。
|
|
34
|
+
- **逆向工作流**：`proc_list` 定位进程 → `proc_maps` 拿模块基址 → `mem_dump` 读目标地址 / `mem_search` 搜特征模式 →
|
|
35
|
+
`proc_smaps` 看内存占用明细 → `frida_script` 生成脚本 + `frida_server` 起 frida 做动态插桩。
|
|
36
|
+
读其他应用内存/maps 需要 root 或 debuggable 应用（run-as），工具会给出明确提示。
|
|
37
|
+
- **附加能力**：`POST /api/dsh-logcat/exec` 执行 shell、`POST /api/dsh-logcat/package` 设置包名、
|
|
38
|
+
`GET /api/dsh-logcat/screenshot` 截屏、`POST /api/dsh-logcat/install-adb` 一键装 adb。
|
|
39
|
+
|
|
40
|
+
## 安装
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# 方式一（推荐，npm 安装）：
|
|
44
|
+
dsh plugin --profile web add @windypro-rourou/dsh-logcat
|
|
45
|
+
|
|
46
|
+
# 更新到最新版（不会自动更新；装旧版时面板/agent 通告会提示有新版本）：
|
|
47
|
+
dsh plugin --profile web update # 升到当前 major 内最新
|
|
48
|
+
# 或强制最新：dsh plugin --profile web add @windypro-rourou/dsh-logcat@latest
|
|
49
|
+
# 更新后重启 GUI（dsh web）生效
|
|
50
|
+
|
|
51
|
+
# 尝鲜 preview 版（日常迭代高频更新，可能不稳定）：
|
|
52
|
+
dsh plugin --profile web add @windypro-rourou/dsh-logcat@preview
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## 发布策略（main / preview 双通道）
|
|
56
|
+
|
|
57
|
+
- **`main` 分支 + npm `latest` 标签**：稳定正式版，**低频发布**，每次至少凑够 3-4 个功能再发，
|
|
58
|
+
避免频繁更新提醒打扰用户。
|
|
59
|
+
- **`preview` 分支 + npm `preview` 标签**：日常迭代，有啥更啥（高频），供尝鲜用户测试；
|
|
60
|
+
凑够足够功能后合并回 `main` 批量发布正式版。
|
|
61
|
+
- 版本自检会按安装通道提示（正式版用户只看 `latest`，preview 用户只看 `preview`，互不打扰）。
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# 方式二（源码本地链接，实时生效无需重启）：把插件链进 web profile，
|
|
65
|
+
# 并在 ~/.dsh/profiles/web/cordis.patch.yml 增加一行：
|
|
66
|
+
pnpm --dir "%USERPROFILE%\.dsh\profiles\web" add link:F:\dsh-logcat
|
|
67
|
+
# 然后在 profile 的 cordis.patch.yml 追加：
|
|
68
|
+
# - insert:
|
|
69
|
+
# - id: logcat
|
|
70
|
+
# name: '@windypro-rourou/dsh-logcat'
|
|
71
|
+
# 该 patch 文件会被运行中的 GUI 热监听；若未生效，重启 GUI 即可。
|
|
72
|
+
|
|
73
|
+
# 方式三（bundle 层，README 原始流程，适合全新 profile；与方式二互斥，勿混用）：
|
|
74
|
+
dsh plugin --profile web add link:<本目录绝对路径>
|
|
75
|
+
# 之后需要重启 GUI（dsh web）才会装载。
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
> 注意：以上方式都会在 profile 树中插入同一行 `logcat`，不要同时使用，否则下次
|
|
79
|
+
> 启动会因重复插件 id 而失败。
|
|
80
|
+
|
|
81
|
+
依赖解析：`ws` / `react` / `react-dom` / `@deepseek-ai/*` 通过本目录 `node_modules` 下的 junction 指向宿主
|
|
82
|
+
实际加载的物理包（保证单例）。若宿主依赖升级，请同步更新 junction 目标。
|
|
83
|
+
|
|
84
|
+
## 限制
|
|
85
|
+
|
|
86
|
+
- 需要设备开启 USB 调试并在手机上授权本机（`unauthorized` 状态会提示）。
|
|
87
|
+
- logcat 输出可能含敏感信息；`/api/dsh-logcat/*` 路由仅允许 loopback 访问。
|
|
88
|
+
- `adb shell` 命令消耗真实设备资源，先确认再执行。
|
|
89
|
+
|
|
90
|
+
## 文件
|
|
91
|
+
|
|
92
|
+
- `lib/index.js` — 宿主端：adb 引擎、轮询、logcat 子进程、路由、WebSocket、agent 工具。
|
|
93
|
+
- `lib/client.js` — 浏览器端：侧边栏入口 + Logcat 面板（React，无构建步骤）。
|
|
94
|
+
- `cordis.patch.yml` — profile bundle patch（自动应用）。
|