@windypro-rourou/dsh-logcat 0.6.1 → 0.6.3

package/README.en.md

@@ -0,0 +1,89 @@
+# dsh-logcat
+
+An Android real-device debugging workbench for the DSH Web GUI (an Android Studio-style Logcat view).
+
+[中文](README.md) | **English**
+
+## Features
+
+- **Auto-connect**: probes adb on this machine (`ANDROID_HOME` / `ANDROID_SDK_ROOT` / default `%LOCALAPPDATA%\Android\Sdk` / PATH /
+  `~/.dsh/adb`), polls `adb devices -l` every 2s; devices in debug mode get a logcat stream **attached automatically** (`-v threadtime`) — no need to open the panel first.
+- **One-click adb install**: when adb is missing, the panel's status bar shows a "One-click install adb" button — it downloads platform-tools from the USTC mirror (Google official fallback), unpacks them to `~/.dsh/adb` and connects automatically (~10MB).
+- **Live logs**: WebSocket push, 2000-line ring buffer per device; automatic reconnect with exponential backoff.
+- **Logcat panel** (sidebar "Logcat" entry, right-side drawer, **draggable width that is remembered**):
+  - Device dropdown (model / serial / state, remembers the last selection)
+  - Severity filter (V/D/I/W/E/F single-select, Android Studio colors)
+  - Keyword filter (**space-separated keywords = any-match**) and a **test package input** (Enter to set; synced with the agent's `logcat_set_package`; shown live in the status bar)
+  - **Screenshot button**: one-click device screen capture and PNG download (`exec-out screencap`)
+  - **Crash highlighting**: FATAL EXCEPTION / ANR lines highlighted in red
+  - **History button**: loads on-disk persisted logs (survives GUI restarts; merged with the live buffer and deduped by timestamp)
+  - **Crash auto-snapshots**: on a FATAL EXCEPTION / ANR in the stream, a screenshot + log context are saved to `~/.dsh/logcat/crashes`; the panel shows a banner and you can inspect the screenshot/log in the "Crash" dialog
+  - **Events view**: one-click live `logcat -b events` stream (app start/crash/lifecycle events)
+  - **WiFi wireless debugging wizard**: IP/port/pairing-code in, `adb pair` + `adb connect` out — ditch the cable (Android 11+)
+  - **Install APK button**: local file picker installs an APK to the current device (streamed upload, 1GB cap)
+  - **Quick device keys**: Home / Back / Recents / Wake / Power / Volume ± with one click
+  - **Performance sparklines**: CPU / memory / battery sampled every 2s with trend charts in the status bar
+  - **Live screen casting + remote control**: the "Screen" tab streams the device display (~1fps over WS binary frames); **click = tap, drag = swipe**, a text input sends keystrokes straight to the phone, quick keys included, one-click download of the current frame — no need to pick up the phone
+  - **Reverse-engineering workbench** (Log / Screen / RE tabs): process list → memory hex/string search → match addresses → click to dump 256B
+  - Pause/resume (pause buffers new lines, resume replays them), clear, copy, export .txt
+  - Windowed rendering + auto-scroll (pauses while you scroll up manually)
+  - Unauthorized-device hint ("allow USB debugging on the phone")
+- **Agent tools** (30 in total, all exposed to the agent and announced in its system prompt):
+  - Device: `logcat_devices` (list devices), `device_info` (model/version/SDK/resolution/memory/battery), `device_stats` (CPU/memory/battery samples), `app_info` (installed version name / versionCode / APK path)
+  - Screen / multimodal: `screen_capture` (screenshot saved locally + embedded as an image block so a multimodal model can see it and fix bugs with `input_*`)
+  - Execution: `adb_exec` (shell), `adb_install` (install a local APK), `adb_pull` (pull files), `app_launch` (start an app / specific Activity), `app_stop` (force-stop; destructive — confirm first)
+  - Input: `input_tap` / `input_swipe` / `input_text` / `input_keyevent` (real-device UI automation), `ui_dump` (UI hierarchy XML), `activity_current` (current foreground Activity)
+  - Logs: `logcat_recent` (filter by package/severity/keyword), `logcat_history` (disk history backfill), `logcat_crash` (crash/ANR blocks with context), `logcat_events` (events buffer), `crash_sessions` (crash snapshot history), `logcat_set_package` (lock the package under test)
+  - Reverse engineering / memory: `proc_list` (process list), `proc_maps` (memory maps + module bases), `proc_status` (process state / memory summary), `proc_smaps` (top Pss regions), `mem_dump` (read memory at an address as hex), `mem_search` (search memory for hex/string patterns), `frida_server` (deploy/start/stop frida-server), `frida_script` (generate hook/trace/scan/bypass/dump script templates)
+- **Real-device debugging workflow**: while building an Android app, the agent's announcement dynamically lists connected devices (serial + model) and the current test package. After confirming with the user: `adb_install` to deploy → `adb_exec`/`app_launch` to start → `logcat_set_package` to lock → `logcat_recent` / `logcat_crash` for crashes → `ui_dump` + `input_*` for UI automation → `adb_pull` for artifacts. A closed loop on real hardware.
+- **Reverse-engineering workflow**: `proc_list` to find the process → `proc_maps` for module bases → `mem_dump` at a target address / `mem_search` for signatures → `proc_smaps` for memory detail → `frida_script` + `frida_server` for dynamic instrumentation. Reading another app's memory/maps needs root or a debuggable app (run-as); tools return clear errors otherwise.
+- **Extra routes**: `POST /api/dsh-logcat/exec` (shell), `POST /api/dsh-logcat/package` (set package), `GET /api/dsh-logcat/screenshot`, `POST /api/dsh-logcat/install-adb`, `GET /api/dsh-logcat/history`, `GET /api/dsh-logcat/crashes` + `GET /api/dsh-logcat/crash-file`, `POST /api/dsh-logcat/install-apk`, `POST /api/dsh-logcat/keyevent`, `POST /api/dsh-logcat/wifi-connect` / `wifi-disconnect`, `GET /api/dsh-logcat/processes`, `POST /api/dsh-logcat/mem-search`, `GET /api/dsh-logcat/mem-dump`.
+- **On-disk data**: logs are written per device per day to `~/.dsh/logcat/logs/<serial>/logcat-MM-DD.log` (raw threadtime lines); crash snapshots live in `~/.dsh/logcat/crashes/<serial>/<timestamp>-<FATAL|ANR>/` (`screenshot.png` + `crash.log` + `meta.json`).
+
+## Installation
+
+```bash
+# Recommended (npm install):
+dsh plugin --profile web add @windypro-rourou/dsh-logcat
+
+# Update to the latest (no auto-update; older installs show a version hint in the panel/agent prompt):
+dsh plugin --profile web update                # latest within the current major
+# or force: dsh plugin --profile web add @windypro-rourou/dsh-logcat@latest
+# restart the GUI (dsh web) afterwards
+
+# Optional preview channel (frequent small iterations, may be unstable):
+dsh plugin --profile web add @windypro-rourou/dsh-logcat@preview
+```
+
+## Release policy (main / latest first)
+
+- **`main` branch + npm `latest` tag**: stable releases — the main update channel. Features ship to main/latest as soon as a batch is ready.
+- **`preview` branch + npm `preview` tag**: optional early-access channel (frequent small iterations). If there are no experimental features since the last stable release, the preview tag simply stays at an older preview version — ignore it.
+- The version self-check notifies per channel only (stable users see `latest`, preview users see `preview`; no cross-talk).
+
+For development you can also link the source directly into the web profile and append the patch row in `~/.dsh/profiles/web/cordis.patch.yml`:
+
+```bash
+pnpm --dir "%USERPROFILE%\.dsh\profiles\web" add link:<this-directory>
+# then add to ~/.dsh/profiles/web/cordis.patch.yml:
+#   - insert:
+#       - id: logcat
+#         name: '@windypro-rourou/dsh-logcat'
+# The patch file is hot-watched by a running GUI; restart it if it does not take effect.
+```
+
+> Note: every method inserts the same `logcat` row into the profile tree — never use two of them at once, or the next boot fails on a duplicate plugin id.
+
+Dependency resolution: `ws` / `react` / `react-dom` / `@deepseek-ai/*` resolve through junctions in this directory's `node_modules` pointing at the host's actually-loaded packages (single instance). Re-point the junctions when the host upgrades its dependencies.
+
+## Limitations
+
+- The device must have USB debugging enabled and be authorized on this machine (`unauthorized` state is surfaced).
+- logcat output may contain sensitive information; `/api/dsh-logcat/*` routes are loopback-only.
+- `adb shell` commands consume real device resources — confirm before running destructive ones.
+
+## Files
+
+- `lib/index.js` — host half: adb engine, polling, logcat child processes, routes, WebSocket, agent tools.
+- `lib/client.js` — browser half: sidebar entry + Logcat panel (React, no build step).
+- `cordis.patch.yml` — profile bundle patch (applied automatically).

package/README.md

@@ -2,6 +2,8 @@
 
 DSH Web GUI 的安卓实机调试面板（类似 Android Studio 的 Logcat 视图）。
 
+[中文](README.md) | [English](README.en.md)
+
 ## 功能
 
 - **自动连接**：探测本机 adb（`ANDROID_HOME` / `ANDROID_SDK_ROOT` / 默认 `%LOCALAPPDATA%\Android\Sdk` / PATH /

package/lib/client.js

@@ -133,6 +133,8 @@ window.__ModuleLoader__.load({
 .lc-re-row[data-on] { background: light-dark(rgba(66,133,244,.12), rgba(66,133,244,.2)); }
 .lc-re-dump { flex: 1; overflow: auto; padding: 8px 10px; font-family: Consolas, "Cascadia Mono", monospace; font-size: 11px; line-height: 16px; white-space: pre-wrap; word-break: break-all; }
 .lc-re-err { padding: 8px 10px; color: #ef5350; font-size: 12px; white-space: pre-wrap; }
+.lc-re-man { display: flex; gap: 6px; padding: 6px 10px; align-items: center; flex-wrap: wrap; }
+.lc-re-man input { background: light-dark(rgba(0,0,0,.05), rgba(255,255,255,.08)); border: 1px solid light-dark(rgba(0,0,0,.16), rgba(255,255,255,.2)); border-radius: 7px; color: inherit; font: inherit; font-size: 12px; padding: 4px 8px; }
 .lc-screen { position: absolute; inset: 0; display: flex; flex-direction: column; }
 .lc-screen-bar { display: flex; gap: 6px; padding: 6px 12px; border-bottom: 1px solid light-dark(rgba(0,0,0,.08), rgba(255,255,255,.1)); flex: none; align-items: center; flex-wrap: wrap; font-size: 11px; }
 .lc-screen-bar input { background: light-dark(rgba(0,0,0,.05), rgba(255,255,255,.08)); border: 1px solid light-dark(rgba(0,0,0,.16), rgba(255,255,255,.2)); border-radius: 7px; color: inherit; font: inherit; font-size: 12px; padding: 4px 8px; }
@@ -226,6 +228,10 @@ window.__ModuleLoader__.load({
 			const [reDump, setReDump] = useState("");
 			const [reDumpAddr, setReDumpAddr] = useState("");
 			const [reError, setReError] = useState("");
+			const [reMaps, setReMaps] = useState([]);
+			const [reMapError, setReMapError] = useState("");
+			const [reManualAddr, setReManualAddr] = useState("");
+			const [reDumpLen, setReDumpLen] = useState(256);
 			const [spark, setSpark] = useState({ cpu: [], mem: [], bat: [] });
 			const [screenImg, setScreenImg] = useState(null);
 			const [screenText, setScreenText] = useState("");
@@ -727,20 +733,57 @@ window.__ModuleLoader__.load({
 					.finally(() => setReSearching(false));
 			};
 
-			const reDumpAt = (addr) => {
-				const hexAddr = addr.startsWith("0x") ? addr : "0x" + addr.toString(16);
+			// od hex text -> aligned hex + ASCII columns for readability.
+			const formatHexDump = (text) => {
+				if (text === "") return "";
+				if (/DSH_MEM_FAIL|Permission denied|No such file/i.test(text)) return text;
+				const out = [];
+				for (const line of text.split(/\r?\n/)) {
+					const m = /^([0-9a-f]+):\s+(.*)$/.exec(line.trim());
+					if (m === null) { out.push(line); continue; }
+					const bytes = (m[2].match(/[0-9a-f]{2}/gi) ?? []).map((b) => Number.parseInt(b, 16));
+					const ascii = bytes.map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : ".")).join("");
+					out.push(m[1].padStart(7, "0") + "  " + m[2].padEnd(48) + "  |" + ascii + "|");
+				}
+				return out.join("\n");
+			};
+
+			const reDumpAt = (addr, len) => {
+				const hexAddr = typeof addr === "string" && addr.startsWith("0x") ? addr : "0x" + addr.toString(16);
+				const length = Math.min(Math.max(Number(len ?? 256) || 256, 1), 65536);
 				setReDumpAddr(hexAddr);
 				setReDump("读取中…");
 				setReError("");
-				fetch(API_BASE + "/mem-dump?serial=" + encodeURIComponent(serial) + "&pid=" + rePid + "&address=" + encodeURIComponent(hexAddr) + "&length=256")
+				fetch(API_BASE + "/mem-dump?serial=" + encodeURIComponent(serial) + "&pid=" + rePid + "&address=" + encodeURIComponent(hexAddr) + "&length=" + length)
 					.then((res) => res.json())
 					.then((body) => {
 						if (body?.error) { setReError(body.error); setReDump(""); return; }
-						setReDump(body?.hex ?? "");
+						setReDump(formatHexDump(body?.hex ?? ""));
 					})
 					.catch(() => { setReDump(""); setReError("转储失败"); });
 			};
 
+			// Load the selected process's memory-mapped modules (/proc/<pid>/maps).
+			const reFetchMaps = (pid) => {
+				const target = Number.isInteger(pid) ? pid : rePid;
+				if (!Number.isInteger(target) || target <= 0) return;
+				setReMaps([]);
+				setReMapError("");
+				fetch(API_BASE + "/maps?serial=" + encodeURIComponent(serial) + "&pid=" + target)
+					.then((res) => res.json())
+					.then((body) => {
+						if (body?.error) { setReMapError(body.error); setReMaps([]); return; }
+						setReMaps(body?.modules ?? []);
+					})
+					.catch(() => setReMapError("模块列表加载失败"));
+			};
+
+			const manualDump = () => {
+				const addr = reManualAddr.trim().replace(/^0x/i, "");
+				if (addr === "" || !/^[0-9a-fA-F]+$/.test(addr)) { setReError("地址格式：0x7a0000 或 7a0000"); return; }
+				reDumpAt("0x" + addr.toLowerCase(), reDumpLen);
+			};
+
 			// Live screen stream: on while the 屏幕 tab is open, the panel is open, and a device is selected.
 			useEffect(() => {
 				const prev = prevSerialRef.current;
@@ -1025,16 +1068,32 @@ window.__ModuleLoader__.load({
 										rePids.length === 0
 											? h("div", { className: "lc-re-row", title: "点击「进程」或等待自动加载" }, "(尚未加载 — 点击「进程」刷新)")
 											: rePids.map((p) =>
-											h("div", { key: p.pid, className: "lc-re-row", "data-on": rePid === p.pid ? "" : undefined, title: (p.user ?? "") + " " + p.name, onClick: () => { setRePid(p.pid); setReResults([]); setReDump(""); setReError(""); } },
+											h("div", { key: p.pid, className: "lc-re-row", "data-on": rePid === p.pid ? "" : undefined, title: (p.user ?? "") + " " + p.name, onClick: () => { setRePid(p.pid); setReResults([]); setReDump(""); setReError(""); reFetchMaps(p.pid); } },
 												p.pid + "  " + p.name)))),
 								h("div", { className: "lc-re-col2" },
+									h("div", { className: "lc-re-head" }, "模块 / so 库 (" + reMaps.length + ") — 点击转储基址"),
+									h("div", { className: "lc-re-list" },
+										reMapError !== ""
+											? h("div", { className: "lc-re-row" }, reMapError)
+											: reMaps.length === 0
+												? h("div", { className: "lc-re-row" }, "(无模块 — 普通设备无法读取其他应用 maps，需 root)")
+												: reMaps.map((mo) =>
+													h("div", { key: mo.path, className: "lc-re-row", title: mo.path + " [" + mo.perms + "]", onClick: () => reDumpAt(mo.base, 256) },
+														(mo.path.split("/").pop() ?? mo.path) + "  @" + mo.base + "  " + mo.perms))),
 									h("div", { className: "lc-re-head" }, "匹配地址（点击转储 256B）" + (reResults.length > 0 ? " · " + reResults.length : "")),
 									h("div", { className: "lc-re-list" },
 										reResults.map((o) =>
 											h("div", { key: o, className: "lc-re-row", "data-on": reDumpAddr === "0x" + o.toString(16) ? "" : undefined, title: "0x" + o.toString(16), onClick: () => reDumpAt(o) },
 												"0x" + o.toString(16)))),
+									h("div", { className: "lc-re-head" }, "手动转储"),
+									h("div", { className: "lc-re-man" },
+										h("input", { placeholder: "地址 0x7a0000…", value: reManualAddr, onChange: (e) => setReManualAddr(e.target.value), onKeyDown: (e) => { if (e.key === "Enter") manualDump(); }, style: { flex: 1, minWidth: 120 } }),
+										h("select", { className: "lc-select", value: String(reDumpLen), onChange: (e) => setReDumpLen(Number(e.target.value)) },
+											[128, 256, 1024, 4096].map((n) => h("option", { key: n, value: String(n) }, n + "B"))),
+										h("button", { type: "button", className: "lc-btn", onClick: manualDump }, "转储"),
+									),
 									reDump !== ""
-										? h("div", { className: "lc-re-head" }, "转储 " + reDumpAddr)
+										? h("div", { className: "lc-re-head" }, "转储 " + reDumpAddr + " · " + reDumpLen + "B")
 										: null,
 									reDump !== "" ? h("div", { className: "lc-re-dump" }, reDump) : null,
 									reError !== "" ? h("div", { className: "lc-re-err" }, reError) : null,

package/lib/index.js

@@ -1275,6 +1275,26 @@ function makeRoutes(engine) {
         }
       },
     },
+    {
+      kind: 'exact',
+      path: API_BASE + '/maps',
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) { writeJson(res, 403, { error: 'forbidden: loopback-only' }); return }
+        if ((req.method ?? 'GET') !== 'GET') { writeJson(res, 405, { error: 'method not allowed' }); return }
+        if (engine.adb === null) { writeJson(res, 500, { error: 'adb not found' }); return }
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const serial = url.searchParams.get('serial') ?? ''
+        const pid = Number(url.searchParams.get('pid'))
+        if (serial === '' || !engine.devices.has(serial) || !Number.isInteger(pid) || pid <= 0) {
+          writeJson(res, 400, { error: 'serial + valid pid required' }); return
+        }
+        try {
+          writeJson(res, 200, { pid, modules: await listModules(engine, serial, pid) })
+        } catch (error) {
+          writeJson(res, 200, { pid, modules: [], error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
   ]
 
   const upgrade = {
@@ -1966,6 +1986,26 @@ function procListTool(engine) {
   })
 }
 
+/** Read /proc/<pid>/maps and return unique file-backed module mappings (base/end/perms/path). Throws on permission failure. */
+export async function listModules(engine, serial, pid) {
+  const result = await runAdbFull(engine.adb, ['-s', serial, 'shell', `cat /proc/${pid}/maps 2>&1`], 20000)
+  if (!result.ok || result.stderr.includes('Permission denied') || /Permission denied|No such file/.test(result.stdout)) {
+    throw new Error(`cannot read /proc/${pid}/maps (need root, or a debuggable app via run-as); output: ${(result.stdout || result.stderr).slice(0, 200)}`)
+  }
+  const seen = new Set()
+  const modules = []
+  for (const line of (result.stdout ?? '').split(/\r?\n/)) {
+    const m = /^([0-9a-f]+)-([0-9a-f]+)\s+([rwxps-]{4})\s+[0-9a-f]+\s+\S+\s+\d+\s+(.+)$/.exec(line)
+    if (m === null) continue
+    const path = m[4]
+    if (!path.startsWith('/')) continue
+    if (seen.has(path)) continue
+    seen.add(path)
+    modules.push({ base: m[1], end: m[2], perms: m[3], path })
+  }
+  return modules
+}
+
 /** The proc_maps agent tool: memory maps + module bases (reverse engineering core). */
 function procMapsTool(engine) {
   return defineTool({
@@ -2013,22 +2053,12 @@ function procMapsTool(engine) {
       const serial = typeof args.serial === 'string' && args.serial !== '' ? args.serial : devices[0]?.serial ?? ''
       const pid = Number(args.pid)
       if (serial === '' || engine.adb === null || !Number.isInteger(pid) || pid <= 0) return { pid: 0, modules: [], error: 'a valid pid is required' }
-      const result = await runAdbFull(engine.adb, ['-s', serial, 'shell', `cat /proc/${pid}/maps 2>&1`], 20000)
-      if (!result.ok || result.stderr.includes('Permission denied') || /Permission denied|No such file/.test(result.stdout)) {
-        return { pid, modules: [], error: `cannot read /proc/${pid}/maps (need root, or a debuggable app via run-as); output: ${(result.stdout || result.stderr).slice(0, 200)}` }
-      }
-      const seen = new Set()
-      const modules = []
-      for (const line of (result.stdout ?? '').split(/\r?\n/)) {
-        const m = /^([0-9a-f]+)-([0-9a-f]+)\s+([rwxps-]{4})\s+[0-9a-f]+\s+\S+\s+\d+\s+(.+)$/.exec(line)
-        if (m === null) continue
-        const path = m[4]
-        if (!path.startsWith('/')) continue
-        if (seen.has(path)) continue
-        seen.add(path)
-        modules.push({ base: m[1], end: m[2], perms: m[3], path })
+      try {
+        const modules = await listModules(engine, serial, pid)
+        return { pid, modules }
+      } catch (error) {
+        return { pid, modules: [], error: error instanceof Error ? error.message : String(error) }
       }
-      return { pid, modules }
     },
   })
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@windypro-rourou/dsh-logcat",
   "description": "Android Logcat viewer for the dsh web GUI: auto-connects to any adb device in debug mode, live logcat stream with level/keyword filters, pause/clear/export, plus agent tools (logcat_recent). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules copy, no dsh source changes.",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "packageManager": "pnpm@11.22.0",
   "engines": {
@@ -38,7 +38,8 @@
   "files": [
     "lib/**/*.js",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ],
   "license": "Apache-2.0",
   "repository": {