@windypro-rourou/dsh-logcat 0.2.0

package/README.md

@@ -0,0 +1,55 @@
+# dsh-logcat
+
+DSH Web GUI 的安卓实机调试面板（类似 Android Studio 的 Logcat 视图）。
+
+## 功能
+
+- **自动连接**：探测本机 adb（`ANDROID_HOME` / `ANDROID_SDK_ROOT` / 默认 `%LOCALAPPDATA%\Android\Sdk` / PATH），
+  每 2 秒轮询 `adb devices -l`；检测到处于调试模式的设备**自动附加 logcat 流**（`-v threadtime`），无需打开面板。
+- **实时日志**：WebSocket 推送，每设备保留最近 2000 行环形缓冲；断线自动重连（指数退避）。
+- **Logcat 面板**（侧边栏「Logcat」入口）：
+  - 设备下拉（显示型号/序列号/状态，记住上次选择）
+  - 级别过滤（V/D/I/W/E/F 单选，颜色与 Android Studio 一致）
+  - 关键词过滤、暂停/继续（暂停时缓冲，恢复自动回放）、清空、复制、导出 .txt
+  - 窗口化渲染 + 自动滚动（滚动手动上翻时自动停用）
+  - 未授权设备提示「请在手机上点击允许 USB 调试」
+- **Agent 工具**：`logcat_recent`（读取某设备最近 N 条日志，支持级别/关键词过滤）。
+- **附加能力**：`POST /api/dsh-logcat/exec` 可对设备执行 `adb shell` 命令（UI 后续版本可扩展）。
+
+## 安装
+
+```bash
+# 方式一（推荐，npm 安装）：
+dsh plugin --profile web add @windypro-rourou/dsh-logcat
+
+# 方式二（源码本地链接，实时生效无需重启）：把插件链进 web profile，
+# 并在 ~/.dsh/profiles/web/cordis.patch.yml 增加一行：
+pnpm --dir "%USERPROFILE%\.dsh\profiles\web" add link:F:\dsh-logcat
+#   然后在 profile 的 cordis.patch.yml 追加：
+#   - insert:
+#       - id: logcat
+#         name: '@windypro-rourou/dsh-logcat'
+# 该 patch 文件会被运行中的 GUI 热监听；若未生效，重启 GUI 即可。
+
+# 方式三（bundle 层，README 原始流程，适合全新 profile；与方式二互斥，勿混用）：
+dsh plugin --profile web add link:<本目录绝对路径>
+# 之后需要重启 GUI（dsh web）才会装载。
+```
+
+> 注意：以上方式都会在 profile 树中插入同一行 `logcat`，不要同时使用，否则下次
+> 启动会因重复插件 id 而失败。
+
+依赖解析：`ws` / `react` / `react-dom` / `@deepseek-ai/*` 通过本目录 `node_modules` 下的 junction 指向宿主
+实际加载的物理包（保证单例）。若宿主依赖升级，请同步更新 junction 目标。
+
+## 限制
+
+- 需要设备开启 USB 调试并在手机上授权本机（`unauthorized` 状态会提示）。
+- logcat 输出可能含敏感信息；`/api/dsh-logcat/*` 路由仅允许 loopback 访问。
+- `adb shell` 命令消耗真实设备资源，先确认再执行。
+
+## 文件
+
+- `lib/index.js` — 宿主端：adb 引擎、轮询、logcat 子进程、路由、WebSocket、agent 工具。
+- `lib/client.js` — 浏览器端：侧边栏入口 + Logcat 面板（React，无构建步骤）。
+- `cordis.patch.yml` — profile bundle patch（自动应用）。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-logcat bundle patch: inserts the logcat plugin row into the web
+# profile roster. Applied as a profile bundle layer over dsh-base; the row is
+# a bare plugin by package name — the node half (exports ".") runs in the
+# host process (adb engine, /api/dsh-logcat routes, WebSocket stream, agent
+# tools), and the `dsh.client` declaration in package.json makes the browser
+# half (exports "./client", served at /plugins/logcat/client.js) load in the
+# web GUI.
+- insert:
+    - id: logcat
+      name: '@linxin666/dsh-logcat'

package/lib/client.js

@@ -0,0 +1,598 @@
+/**
+ * dsh-logcat — browser half. Runs inside the dsh web GUI.
+ *
+ * Renders an Android-Studio-style Logcat panel:
+ *   - sidebar entry row toggling the panel (DOM-level injection, self-healing),
+ *   - device dropdown (auto-picks the first attached device / remembers the
+ *     last choice), live severity + keyword filters, pause/resume, clear,
+ *     copy / export .txt, auto-scroll with stick-to-bottom,
+ *   - windowed rendering so a 2000-line buffer stays smooth,
+ *   - WebSocket stream with automatic reconnect.
+ *
+ * Bundle format: `window.__ModuleLoader__.load({id, factory})` (lazy CJS) —
+ * the only client bundle format the web shell materializes.
+ */
+window.__ModuleLoader__.load({
+	id: "@linxin666/dsh-logcat",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+
+		const { createElement: h, useEffect, useMemo, useRef, useState } = require("react");
+		const { createRoot } = require("react-dom/client");
+
+		//#region styles
+		const STYLE = `
+[data-dsh-logcat-entry] {
+  display: flex; align-items: center; gap: 8px; width: 100%;
+  padding: 9px 12px; margin: 2px 0; border: 0; border-radius: 8px;
+  background: transparent; color: inherit; font: inherit; cursor: pointer;
+  text-align: left;
+}
+[data-dsh-logcat-entry]:hover { background: rgba(128,128,128,.14); }
+[data-dsh-logcat-entry][data-active] { background: rgba(128,128,128,.22); }
+[data-dsh-logcat-entry] .lc-entry-icon { display: inline-flex; align-items: center; justify-content: center; width: 16px; height: 16px; flex: none; }
+[data-dsh-logcat-entry] .lc-entry-label { font-size: 13px; line-height: 1.2; opacity: .92; }
+.dsh-logcat-view { position: fixed; top: 0; right: 0; bottom: 0; width: min(620px, 94vw); display: flex; flex-direction: column; background: var(--lc-bg, #ffffff); border-left: 1px solid rgba(128,128,128,.3); box-shadow: -10px 0 28px rgba(0,0,0,.18); z-index: 9999; }
+.dsh-logcat-view[hidden] { display: none !important; }
+.lc-panel { display: flex; flex-direction: column; height: 100%; min-height: 0; font-family: -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif; }
+.lc-header { display: flex; align-items: center; gap: 8px; padding: 8px 12px; border-bottom: 1px solid rgba(128,128,128,.25); flex: none; }
+.lc-back { border: 0; background: transparent; color: inherit; font: inherit; cursor: pointer; display: flex; align-items: center; gap: 4px; padding: 4px 8px; border-radius: 6px; font-size: 13px; }
+.lc-back:hover { background: rgba(128,128,128,.14); }
+.lc-title { font-size: 15px; font-weight: 600; margin: 0; }
+.lc-dot { width: 8px; height: 8px; border-radius: 50%; flex: none; }
+.lc-dot.on { background: #4caf50; }
+.lc-dot.off { background: #9e9e9e; }
+.lc-dot.warn { background: #ff9800; }
+.lc-toolbar { display: flex; align-items: center; gap: 6px; padding: 6px 12px; border-bottom: 1px solid rgba(128,128,128,.25); flex: none; flex-wrap: wrap; }
+.lc-select, .lc-search { background: rgba(128,128,128,.08); border: 1px solid rgba(128,128,128,.3); border-radius: 6px; color: inherit; font: inherit; font-size: 12px; padding: 4px 8px; }
+.lc-select:focus, .lc-search:focus { outline: 1px solid rgba(128,128,128,.5); }
+.lc-search { flex: 1; min-width: 120px; max-width: 320px; }
+.lc-levels { display: flex; gap: 2px; }
+.lc-level { border: 1px solid transparent; background: transparent; color: inherit; font: inherit; font-size: 12px; font-weight: 600; width: 24px; height: 24px; border-radius: 5px; cursor: pointer; }
+.lc-level:hover { background: rgba(128,128,128,.12); }
+.lc-level[data-on] { background: rgba(128,128,128,.22); border-color: rgba(128,128,128,.4); }
+.lc-level.v { color: #9e9e9e; } .lc-level.d { color: #4fc3f7; } .lc-level.i { color: #4caf50; }
+.lc-level.w { color: #fbc02d; } .lc-level.e { color: #ef5350; } .lc-level.f { color: #ab47bc; }
+.lc-btn { border: 1px solid rgba(128,128,128,.3); background: transparent; color: inherit; font: inherit; font-size: 12px; padding: 4px 10px; border-radius: 6px; cursor: pointer; }
+.lc-btn:hover { background: rgba(128,128,128,.12); }
+.lc-btn[data-on] { background: rgba(128,128,128,.22); }
+.lc-body { flex: 1; min-height: 0; position: relative; overflow: hidden; }
+.lc-log { position: absolute; inset: 0; overflow: auto; font-family: Consolas, "Cascadia Mono", "Courier New", monospace; font-size: 12px; line-height: 20px; }
+.lc-log-inner { position: relative; }
+.lc-line { position: absolute; left: 0; right: 0; padding: 0 12px; white-space: pre; overflow: hidden; text-overflow: ellipsis; cursor: default; }
+.lc-line:hover { background: rgba(128,128,128,.12); }
+.lc-line .ts { color: var(--lc-dim, #9e9e9e); margin-right: 8px; }
+.lc-line .pid { color: var(--lc-dim, #9e9e9e); margin-right: 6px; }
+.lc-line .lv { display: inline-block; width: 14px; text-align: center; font-weight: 700; margin-right: 6px; }
+.lc-line .lv.V { color: #9e9e9e; } .lc-line .lv.D { color: #4fc3f7; } .lc-line .lv.I { color: #4caf50; }
+.lc-line .lv.W { color: #fbc02d; } .lc-line .lv.E { color: #ef5350; } .lc-line .lv.F { color: #ab47bc; }
+.lc-line .tag { color: #29b6f6; margin-right: 8px; }
+.lc-line.cont .msg { padding-left: 44px; color: var(--lc-dim, #9e9e9e); }
+.lc-empty { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; color: var(--lc-dim, #9e9e9e); font-size: 13px; }
+.lc-status { display: flex; align-items: center; gap: 14px; padding: 4px 12px; border-top: 1px solid rgba(128,128,128,.25); flex: none; font-size: 11px; color: var(--lc-dim, #9e9e9e); }
+.lc-status b { font-weight: 600; color: inherit; }
+`;
+		//#endregion
+
+		//#region panel state
+		/** The panel state owner the sidebar entry toggles and the view renders from. */
+		class PanelController {
+			constructor() {
+				this.panelOpen = false;
+				this.listeners = new Set();
+			}
+			getSnapshot() { return { panelOpen: this.panelOpen }; }
+			subscribe(fn) { this.listeners.add(fn); return () => { this.listeners.delete(fn); }; }
+			open() { if (this.panelOpen) return; this.panelOpen = true; this.notify(); }
+			close() { if (!this.panelOpen) return; this.panelOpen = false; this.notify(); }
+			toggle() { if (this.panelOpen) this.close(); else this.open(); }
+			notify() { for (const fn of [...this.listeners]) fn(); }
+		}
+		//#endregion
+
+		//#region ws + data
+		const API_BASE = "/api/dsh-logcat";
+		const LEVELS = ["V", "D", "I", "W", "E", "F"];
+		const LEVEL_TITLES = { V: "详细", D: "调试", I: "信息", W: "警告", E: "错误", F: "致命" };
+
+		/** The Logcat panel view. */
+		function LogcatPanel({ controller }) {
+			const [adbPath, setAdbPath] = useState("");
+			const [adbReady, setAdbReady] = useState(false);
+			const [devices, setDevices] = useState([]);
+			const [streaming, setStreaming] = useState([]);
+			const [serial, setSerial] = useState(() => { try { return localStorage.getItem("dsh-logcat-serial") ?? ""; } catch { return ""; } });
+			const [entries, setEntries] = useState([]);
+			const [connected, setConnected] = useState(false);
+			const [paused, setPaused] = useState(false);
+			const [level, setLevel] = useState("");
+			const [keyword, setKeyword] = useState("");
+			const [autoScroll, setAutoScroll] = useState(true);
+			const [scrollTop, setScrollTop] = useState(0);
+
+			const wsRef = useRef(null);
+			const entriesRef = useRef([]);
+			const devicesRef = useRef([]);
+			const serialRef = useRef(serial);
+			const pausedRef = useRef(paused);
+			const pendingRef = useRef([]);
+			const bodyRef = useRef(null);
+			const autoScrollRef = useRef(autoScroll);
+			const applyFrameRef = useRef(null);
+
+			useEffect(() => { serialRef.current = serial; }, [serial]);
+			useEffect(() => { pausedRef.current = paused; }, [paused]);
+			useEffect(() => { autoScrollRef.current = autoScroll; }, [autoScroll]);
+
+			const pickSerial = (next) => {
+				try { localStorage.setItem("dsh-logcat-serial", next); } catch { /* private mode */ }
+				serialRef.current = next;
+				setSerial(next);
+				entriesRef.current = [];
+				setEntries([]);
+				requestReplay(next);
+			};
+
+			const requestReplay = (target) => {
+				const ws = wsRef.current;
+				if (ws !== null && ws.readyState === WebSocket.OPEN) {
+					ws.send(JSON.stringify({ type: "replay", serial: target }));
+				}
+			};
+
+			const scrollToBottom = () => {
+				const body = bodyRef.current;
+				if (body !== null) body.scrollTop = body.scrollHeight;
+			};
+
+			const appendEntries = (incoming) => {
+				const next = entriesRef.current.concat(incoming);
+				if (next.length > 2000) next.splice(0, next.length - 2000);
+				entriesRef.current = next;
+				setEntries(next);
+				if (autoScrollRef.current) requestAnimationFrame(() => scrollToBottom());
+			};
+
+			const applyFrame = (frame) => {
+				if (frame.type === "ready") {
+					setAdbPath(frame.adbPath ?? "");
+					setAdbReady(frame.adbPath != null && frame.adbPath !== "");
+					setStreaming(frame.streaming ?? []);
+					setDevices(frame.devices ?? []);
+					devicesRef.current = frame.devices ?? [];
+					if (serialRef.current === "" || !(frame.devices ?? []).some((d) => d.serial === serialRef.current)) {
+						const first = (frame.devices ?? []).find((d) => d.state === "device");
+						if (first !== undefined) pickSerial(first.serial);
+					}
+				} else if (frame.type === "devices") {
+					setDevices(frame.devices ?? []);
+					devicesRef.current = frame.devices ?? [];
+					if (serialRef.current === "" || !(frame.devices ?? []).some((d) => d.serial === serialRef.current)) {
+						const first = (frame.devices ?? []).find((d) => d.state === "device");
+						if (first !== undefined) pickSerial(first.serial);
+					}
+				} else if (frame.type === "history") {
+					if (frame.serial === serialRef.current) {
+						entriesRef.current = frame.entries ?? [];
+						setEntries(entriesRef.current);
+						requestAnimationFrame(() => { if (autoScrollRef.current) scrollToBottom(); });
+					}
+				} else if (frame.type === "line") {
+					if (pausedRef.current) {
+						pendingRef.current.push(frame);
+						if (pendingRef.current.length > 800) pendingRef.current.splice(0, pendingRef.current.length - 800);
+						return;
+					}
+					if (frame.serial !== serialRef.current) return;
+					appendEntries([frame.entry]);
+				} else if (frame.type === "device-state") {
+					setDevices(devicesRef.current.map((d) => d.serial === frame.serial ? { ...d, state: frame.state } : d));
+				}
+			};
+			applyFrameRef.current = applyFrame;
+
+			// WebSocket lifecycle (created once; handlers read latest state through refs).
+			useEffect(() => {
+				let closed = false;
+				let socket = null;
+				let retry = 0;
+				const connect = () => {
+					if (closed) return;
+					const scheme = window.location.protocol === "https:" ? "wss" : "ws";
+					socket = new WebSocket(scheme + "://" + window.location.host + API_BASE + "/stream");
+					wsRef.current = socket;
+					socket.onopen = () => {
+						retry = 0;
+						setConnected(true);
+						const target = serialRef.current;
+						if (target !== "") socket.send(JSON.stringify({ type: "replay", serial: target }));
+					};
+					socket.onmessage = (event) => {
+						let frame;
+						try { frame = JSON.parse(event.data); } catch { return; }
+						applyFrameRef.current(frame);
+					};
+					socket.onclose = () => {
+						wsRef.current = null;
+						setConnected(false);
+						if (closed) return;
+						retry = Math.min(retry + 1, 10);
+						setTimeout(connect, 800 * retry);
+					};
+					socket.onerror = () => { try { socket.close(); } catch { /* closed */ } };
+				};
+				connect();
+				return () => {
+					closed = true;
+					try { socket?.close(); } catch { /* closed */ }
+				};
+			}, []);
+
+			// Initial status fetch (panel may open long after the plugin loaded).
+			useEffect(() => {
+				fetch(API_BASE + "/status")
+					.then((res) => res.json())
+					.then((body) => {
+						setAdbPath(body.adbPath ?? "");
+						setAdbReady(body.ready === true);
+						setDevices(body.devices ?? []);
+						setStreaming(body.streaming ?? []);
+						devicesRef.current = body.devices ?? [];
+						if (serialRef.current === "" || !(body.devices ?? []).some((d) => d.serial === serialRef.current)) {
+							const first = (body.devices ?? []).find((d) => d.state === "device");
+							if (first !== undefined) pickSerial(first.serial);
+						}
+					})
+					.catch(() => { /* host not up yet */ });
+			}, []);
+
+			const filtered = useMemo(() => {
+				const needle = keyword.trim().toLowerCase();
+				return entries.filter((e) => {
+					if (level !== "" && e.level !== "" && e.level !== level) return false;
+					if (needle === "") return true;
+					return e.raw.toLowerCase().includes(needle);
+				});
+			}, [entries, level, keyword]);
+
+			const togglePause = () => {
+				const next = !paused;
+				setPaused(next);
+				if (!next && pendingRef.current.length > 0) {
+					const replay = pendingRef.current.filter((f) => f.serial === serialRef.current);
+					pendingRef.current = [];
+					if (replay.length > 0) appendEntries(replay.map((f) => f.entry));
+				}
+			};
+
+			const clearLog = () => {
+				entriesRef.current = [];
+				setEntries([]);
+			};
+
+			const exportLog = () => {
+				const text = filtered.map((e) => e.raw).join("\n");
+				const blob = new Blob([text], { type: "text/plain;charset=utf-8" });
+				const a = document.createElement("a");
+				a.href = URL.createObjectURL(blob);
+				a.download = "logcat-" + (serial || "all") + "-" + new Date().toISOString().replace(/[:.]/g, "-") + ".txt";
+				document.body.appendChild(a);
+				a.click();
+				a.remove();
+				setTimeout(() => URL.revokeObjectURL(a.href), 5000);
+			};
+
+			const copyLog = () => {
+				const text = filtered.map((e) => e.raw).join("\n");
+				if (navigator.clipboard !== undefined) {
+					navigator.clipboard.writeText(text).catch(() => { /* denied */ });
+				}
+			};
+
+			const device = devices.find((d) => d.serial === serial);
+			const deviceState = device?.state ?? "";
+			const live = connected && serial !== "" && streaming.includes(serial);
+
+			return h("div", { className: "lc-panel" },
+				h("div", { className: "lc-header" },
+					h("button", { type: "button", className: "lc-back", onClick: () => controller.close() },
+						h("span", { "aria-hidden": true }, "‹"),
+						h("span", null, "关闭"),
+					),
+					h("h2", { className: "lc-title" }, "Logcat"),
+					h("span", { className: "lc-dot " + (live ? "on" : connected ? "warn" : "off") }),
+					h("span", { style: { fontSize: 12, color: "var(--lc-dim, #9e9e9e)" } },
+						live ? "实机日志流中" : connected ? "未选设备" : "未连接"),
+					h("select", {
+						className: "lc-select",
+						value: serial,
+						onChange: (e) => pickSerial(e.target.value),
+						title: "选择设备",
+					},
+						devices.length === 0
+							? h("option", { value: "" }, "无设备 — 请连接并开启 USB 调试")
+							: devices.map((d) =>
+								h("option", { key: d.serial, value: d.serial },
+									(d.model !== "" ? d.model + " · " : "") + d.serial + " [" + d.state + "]"))),
+				),
+				h("div", { className: "lc-toolbar" },
+					h("div", { className: "lc-levels", role: "group", "aria-label": "日志级别" },
+						h("button", {
+							type: "button",
+							className: "lc-level i",
+							"data-on": level === "" ? "" : undefined,
+							title: "全部级别",
+							onClick: () => setLevel(""),
+						}, "A"),
+						LEVELS.map((lv) =>
+							h("button", {
+								type: "button",
+								key: lv,
+								className: "lc-level " + lv.toLowerCase(),
+								"data-on": level === lv ? "" : undefined,
+								title: LEVEL_TITLES[lv],
+								onClick: () => setLevel(level === lv ? "" : lv),
+							}, lv))),
+					h("input", {
+						className: "lc-search",
+						type: "search",
+						placeholder: "关键词过滤…",
+						value: keyword,
+						onChange: (e) => setKeyword(e.target.value),
+					}),
+					h("button", { type: "button", className: "lc-btn", "data-on": paused ? "" : undefined, onClick: togglePause },
+						paused ? "继续" : "暂停"),
+					h("button", { type: "button", className: "lc-btn", onClick: clearLog }, "清空"),
+					h("button", { type: "button", className: "lc-btn", onClick: copyLog }, "复制"),
+					h("button", { type: "button", className: "lc-btn", onClick: exportLog }, "导出"),
+					h("button", {
+						type: "button",
+						className: "lc-btn",
+						"data-on": autoScroll ? "" : undefined,
+						title: "新日志自动滚到底部",
+						onClick: () => setAutoScroll(!autoScroll),
+					}, "自动滚动"),
+				),
+				h("div", { className: "lc-body", ref: bodyRef },
+					filtered.length === 0
+						? h("div", { className: "lc-empty" }, paused ? "已暂停（" + entries.length + " 条已缓冲）" : "暂无日志")
+						: h(VirtualLog, { entries: filtered, scrollTop, onScrollTop: setScrollTop, bodyRef }),
+				),
+				h("div", { className: "lc-status" },
+					h("span", null, h("b", null, adbReady ? "adb 就绪" : "未找到 adb"), " · " + (adbPath || "—")),
+					h("span", null, "设备 " + devices.length + " · 在线 " + devices.filter((d) => d.state === "device").length),
+					h("span", null, "显示 " + filtered.length + " / 缓冲 " + entries.length + " 行"),
+					deviceState === "unauthorized"
+						? h("span", { style: { color: "#ef5350" } }, "⚠ 设备未授权 — 请在手机上点击“允许 USB 调试”")
+						: null,
+				),
+			);
+		}
+
+		/** Windowed log list: fixed 20px rows, only the visible slice is rendered. */
+		function VirtualLog({ entries, scrollTop, onScrollTop, bodyRef }) {
+			const ROW = 20;
+			const height = useRef(0);
+			const [viewport, setViewport] = useState({ top: 0, bottom: 100 });
+
+			useEffect(() => {
+				const body = bodyRef.current;
+				if (body === null) return;
+				const measure = () => {
+					height.current = body.clientHeight;
+					const top = Math.max(0, Math.floor(scrollTop / ROW) - 8);
+					const bottom = Math.min(entries.length, Math.ceil((scrollTop + height.current) / ROW) + 8);
+					setViewport({ top, bottom });
+				};
+				measure();
+				if (typeof ResizeObserver !== "undefined") {
+					const observer = new ResizeObserver(measure);
+					observer.observe(body);
+					return () => observer.disconnect();
+				}
+				return undefined;
+			}, [entries.length]);
+
+			useEffect(() => {
+				const top = Math.max(0, Math.floor(scrollTop / ROW) - 8);
+				const bottom = Math.min(entries.length, Math.ceil((scrollTop + (height.current || 400)) / ROW) + 8);
+				setViewport({ top, bottom });
+			}, [scrollTop, entries.length]);
+
+			const rows = [];
+			for (let i = viewport.top; i < viewport.bottom && i < entries.length; i++) {
+				const e = entries[i];
+				const level = e.level !== "" ? e.level : " ";
+				rows.push(
+					h("div", {
+						key: i,
+						className: "lc-line" + (e.cont === true ? " cont" : ""),
+						style: { top: i * ROW },
+						title: e.raw,
+					},
+						e.ts !== "" ? h("span", { className: "ts" }, e.ts) : null,
+						e.pid > 0 ? h("span", { className: "pid" }, e.pid + "-" + e.tid) : null,
+						e.level !== "" ? h("span", { className: "lv " + level }, level) : null,
+						e.tag !== "" ? h("span", { className: "tag" }, e.tag) : null,
+						h("span", { className: "msg" }, e.msg !== "" ? e.msg : e.raw),
+					),
+				);
+			}
+
+			return h("div",
+				{
+					className: "lc-log",
+					ref: bodyRef,
+					onScroll: (e) => { onScrollTop(e.target.scrollTop); },
+				},
+				h("div", { className: "lc-log-inner", style: { height: entries.length * ROW } }, rows),
+			);
+		}
+		//#endregion
+
+		//#region DOM mounts
+		const ICON = '<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.2" aria-hidden="true"><rect x="3" y="1.5" width="10" height="13" rx="2"/><path d="M6.5 4.5h3M6.5 7h3M6.5 9.5h1.5" stroke-linecap="round"/><circle cx="8" cy="12" r="0.9" fill="currentColor" stroke="none"/></svg>';
+
+		function sidebarRoot() {
+			const column = document.querySelector('[data-pane="sidebar"], [class*="sidebarCol"]');
+			if (column === null) return undefined;
+			const logoOwner = column.querySelector('[class*="logoRow"]')?.parentElement;
+			return logoOwner ?? (column.firstElementChild ?? undefined);
+		}
+
+		function newSessionButton(root) {
+			const nested = root.querySelector('button[class*="newSession"]');
+			if (nested !== null) return nested;
+			for (const child of root.children) {
+				if (child.tagName === "BUTTON") return child;
+			}
+			return undefined;
+		}
+
+		function createEntry(controller) {
+			const entry = document.createElement("button");
+			entry.type = "button";
+			entry.dataset.dshLogcatEntry = "";
+			entry.setAttribute("aria-label", "Logcat 实机调试");
+			entry.setAttribute("title", "Logcat 实机调试（自动连接 adb 设备）");
+			entry.innerHTML = '<span class="lc-entry-icon">' + ICON + '</span><span class="lc-entry-label">Logcat</span>';
+			entry.addEventListener("click", () => { controller.toggle(); });
+			return entry;
+		}
+
+		function placeEntry(root, entry) {
+			const button = newSessionButton(root);
+			if (button === undefined) return false;
+			if (entry.parentElement !== root) {
+				const row = button.closest('[class*="logoRow"]');
+				const base = (row !== null && row.parentElement === root) ? row : button;
+				const family = Array.from(root.children).filter(
+					(el) => el instanceof HTMLElement && el.matches("[data-dsh-taskboard-entry], [data-dsh-ssh-entry], [data-dsh-logcat-entry]"),
+				);
+				const anchor = family.length > 0 ? family[family.length - 1].nextElementSibling : base.nextElementSibling;
+				root.insertBefore(entry, anchor);
+			}
+			return true;
+		}
+
+		function mountSidebarEntry(controller) {
+			const entry = createEntry(controller);
+			let root;
+			let placed = false;
+			let rootObserver;
+
+			const tryPlace = () => {
+				if (root !== undefined && !root.isConnected) {
+					rootObserver?.disconnect();
+					root = undefined;
+					placed = false;
+				}
+				if (placed) {
+					if (document.body.contains(entry)) return;
+					rootObserver?.disconnect();
+					root = undefined;
+					placed = false;
+				}
+				root ??= sidebarRoot();
+				if (root === undefined) return;
+				placed = placeEntry(root, entry);
+				if (placed) {
+					rootObserver = new MutationObserver(() => {
+						if (root === undefined || !root.isConnected) { placed = false; tryPlace(); return; }
+						if (!root.contains(entry)) placed = placeEntry(root, entry);
+					});
+					rootObserver.observe(root, { childList: true, subtree: true });
+				}
+			};
+
+			const waitObserver = new MutationObserver(() => { tryPlace(); });
+			waitObserver.observe(document.body, { childList: true, subtree: true });
+
+			const syncActive = () => {
+				if (controller.getSnapshot().panelOpen) entry.dataset.active = "true";
+				else delete entry.dataset.active;
+			};
+			const unsubscribe = controller.subscribe(syncActive);
+			syncActive();
+			tryPlace();
+
+			return () => {
+				waitObserver.disconnect();
+				rootObserver?.disconnect();
+				unsubscribe();
+				entry.remove();
+			};
+		}
+
+		function mountPanel(controller) {
+			let root;
+			let container;
+
+			const ensure = () => {
+				if (container !== undefined && container.isConnected) return;
+				root?.unmount();
+				root = undefined;
+				container?.remove();
+				container = document.createElement("div");
+				container.dataset.dshLogcatView = "";
+				container.className = "dsh-logcat-view";
+				container.hidden = true; // side-drawer: hidden until the sidebar entry is clicked
+				document.body.appendChild(container);
+				root = createRoot(container);
+				root.render(h(LogcatPanel, { controller }));
+			};
+
+			// The drawer lives on <body>, which never gets rebuilt — mount once.
+			ensure();
+
+			const applyOpen = () => {
+				if (container !== undefined) container.hidden = !controller.getSnapshot().panelOpen;
+			};
+			const unsubscribe = controller.subscribe(applyOpen);
+			applyOpen();
+
+			return () => {
+				unsubscribe();
+				root?.unmount();
+				root = undefined;
+				container?.remove();
+				container = undefined;
+			};
+		}
+		//#endregion
+
+		//#region entry
+		/** Required services (fiber inject waiting — the runtime must be up first). */
+		const inject = ["slots"];
+
+		/**
+		 * Mount the Logcat panel.
+		 * @param ctx - client root context.
+		 */
+		function apply(ctx) {
+			const style = document.createElement("style");
+			style.textContent = STYLE;
+			style.dataset.dshLogcatStyle = "";
+			document.head.appendChild(style);
+
+			const controller = new PanelController();
+			const disposers = [];
+			try {
+				disposers.push(mountSidebarEntry(controller));
+				disposers.push(mountPanel(controller));
+			} catch (error) {
+				console.warn("[dsh-logcat] mount failed:", error);
+			}
+			ctx.effect(() => () => {
+				for (const dispose of disposers.splice(0)) dispose();
+				style.remove();
+			}, "dsh-logcat: ui mounts");
+		}
+		//#endregion
+
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,591 @@
+/**
+ * dsh-logcat — host half.
+ *
+ * Mounts an adb-backed Android Logcat engine:
+ *   - probes the adb binary (ANDROID_HOME / SDK defaults / PATH),
+ *   - keeps `adb devices` under a 2s poll and AUTO-ATTACHES a `logcat -v
+ *     threadtime` stream to every device in debug mode (no GUI needed),
+ *   - keeps a per-device ring buffer (2000 lines) and broadcasts new lines
+ *     over a WebSocket to every subscribed browser panel,
+ *   - exposes /api/dsh-logcat/{status,exec} routes plus the stream upgrade,
+ *   - registers the logcat_recent agent tool and a system-prompt section.
+ *
+ * The browser half (./client) renders the Logcat panel in the web GUI.
+ * Everything rides official NPM SDK packages — no dsh source changes.
+ */
+
+import { spawn, execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { WebSocket, WebSocketServer } from 'ws'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+/** Stable cordis plugin name. */
+export const name = 'logcat'
+
+/** Services required before the logcat surfaces can mount. */
+export const inject = ['webServer', 'tools', 'systemPrompt']
+
+/** Services this plugin provides on ctx (ctx.logcat). */
+export const provide = ['logcat']
+
+/** Order of the announcement section within the tool-guidance band. */
+const SECTION_ORDER = 152
+
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export const LOGCAT_GUIDANCE =
+  '本机已安装 dsh-logcat 插件（DSH Web GUI 的安卓实机调试面板）：侧边栏「Logcat」入口；自动探测本机 adb（ANDROID_HOME / 默认 SDK 路径），对处于调试模式的已连接设备自动附加 logcat 流（threadtime 格式，每设备保留最近 2000 行环形缓冲）；Web 面板支持设备切换、级别/关键词过滤、暂停/清空/导出；agent 可用 logcat_recent 工具读取最近日志。限制：需设备开启 USB 调试并授权本机；logcat 输出可能含敏感信息；执行 adb 命令消耗真实设备资源，先确认再操作。用户提到「Logcat / 安卓日志 / 实机调试 / adb 日志」时即指本插件，请据此协作。'
+
+/** ---------------------------------------------------------------- adb */
+
+/** Candidate adb.exe locations, in probe order. */
+function adbCandidates() {
+  const list = []
+  const envs = [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]
+  for (const root of envs) {
+    if (root) list.push(join(root, 'platform-tools', 'adb.exe'), join(root, 'platform-tools', 'adb'))
+  }
+  const sdk = join(homedir(), 'AppData', 'Local', 'Android', 'Sdk')
+  list.push(join(sdk, 'platform-tools', 'adb.exe'))
+  list.push(join(sdk, 'platform-tools', 'adb'))
+  return list
+}
+
+/** Run one short adb command, returning stdout (or null on failure). */
+function runAdb(adb, args, timeoutMs = 8000) {
+  return new Promise((resolve) => {
+    try {
+      execFile(adb, args, { timeout: timeoutMs, windowsHide: true }, (error, stdout) => {
+        if (error) resolve(null)
+        else resolve(String(stdout))
+      })
+    } catch {
+      // spawn itself threw (EPERM/EACCES/ENOENT at spawn time) — degrade, never crash.
+      resolve(null)
+    }
+  })
+}
+
+/** Run one adb command and return { ok, code, stdout, stderr }. */
+function runAdbFull(adb, args, timeoutMs = 15000) {
+  return new Promise((resolve) => {
+    try {
+      execFile(adb, args, { timeout: timeoutMs, windowsHide: true, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error) {
+          const code = typeof error.code === 'number' ? error.code : null
+          const timedOut = error.killed === true || error.signal === 'SIGTERM'
+          resolve({ ok: false, code, timedOut, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+        } else {
+          resolve({ ok: true, code: 0, timedOut: false, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+        }
+      })
+    } catch {
+      resolve({ ok: false, code: null, timedOut: false, stdout: '', stderr: '' })
+    }
+  })
+}
+
+/** threadtime line: "08-18 14:23:45.678  1234  5678 I Tag    : message" */
+const THREADTIME_RE = /^(\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+([^:]*?)\s*:\s?(.*)$/
+
+/** Parse one logcat line into an entry (null when not parseable). */
+function parseLogcatLine(raw) {
+  const match = THREADTIME_RE.exec(raw)
+  if (match === null) return null
+  return {
+    ts: match[1],
+    pid: Number.parseInt(match[2], 10),
+    tid: Number.parseInt(match[3], 10),
+    level: match[4],
+    tag: match[5].trim(),
+    msg: match[6],
+    raw,
+    cont: false,
+  }
+}
+
+/** Parse `adb devices -l` output into serial -> { state, model } map. */
+function parseDevices(output) {
+  const devices = new Map()
+  const lines = String(output ?? '').split(/\r?\n/)
+  for (const line of lines) {
+    const parts = line.split(/\s+/)
+    if (parts.length < 2 || parts[0] === 'List' || parts[0] === '*') continue
+    const serial = parts[0]
+    const state = parts[1]
+    let model = ''
+    for (const field of parts.slice(2)) {
+      if (field.startsWith('model:')) model = field.slice('model:'.length)
+    }
+    devices.set(serial, { serial, state, model })
+  }
+  return devices
+}
+
+/** ------------------------------------------------------------ engine */
+
+/** One attached logcat stream (per device). */
+class DeviceStream {
+  constructor(adb, serial, onLine, onExit) {
+    this.adb = adb
+    this.serial = serial
+    this.onLine = onLine
+    this.onExit = onExit
+    this.child = null
+    this.restartTimer = null
+    this.stopped = false
+    this.starts = 0
+  }
+
+  start() {
+    if (this.stopped || this.child !== null) return
+    this.starts += 1
+    let child
+    try {
+      child = spawn(this.adb, ['-s', this.serial, 'logcat', '-v', 'threadtime'], {
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+    } catch {
+      // spawn threw synchronously (e.g. adb binary vanished / blocked) — back off and retry.
+      if (!this.stopped) this.restartTimer = setTimeout(() => this.start(), 5000)
+      return
+    }
+    this.child = child
+    child.stderr.on('data', () => { /* adb warnings ignored */ })
+    createInterface({ input: child.stdout }).on('line', (line) => {
+      this.onLine(String(line))
+    })
+    child.on('exit', (code) => {
+      this.child = null
+      if (this.stopped) return
+      // Auto-restart with backoff (adb occasionally drops the stream).
+      this.restartTimer = setTimeout(() => this.start(), 2500)
+      this.onExit(code)
+    })
+    child.on('error', () => {
+      this.child = null
+      if (this.stopped) return
+      this.restartTimer = setTimeout(() => this.start(), 5000)
+    })
+  }
+
+  stop() {
+    this.stopped = true
+    if (this.restartTimer !== null) clearTimeout(this.restartTimer)
+    this.restartTimer = null
+    if (this.child !== null) {
+      try { this.child.kill() } catch { /* gone */ }
+      this.child = null
+    }
+  }
+}
+
+/** The adb engine: device poll, per-device ring buffers, ws fan-out. */
+class AdbEngine {
+  constructor() {
+    this.adb = null
+    this.adbVersion = null
+    this.devices = new Map()      // serial -> { serial, state, model }
+    this.buffers = new Map()      // serial -> ring buffer array
+    this.streams = new Map()      // serial -> DeviceStream
+    this.clients = new Set()      // WebSocket panels
+    this.timer = null
+    this.polling = false
+    this.BUFFER_CAP = 2000
+  }
+
+  /** Probe and warm the adb server. Returns true when usable. */
+  async init() {
+    for (const candidate of adbCandidates()) {
+      if (!existsSync(candidate)) continue
+      const version = await runAdb(candidate, ['version'])
+      if (version !== null && version.includes('Android Debug Bridge')) {
+        this.adb = candidate
+        this.adbVersion = version.split(/\r?\n/)[0] ?? ''
+        break
+      }
+    }
+    if (this.adb === null) {
+      // Last resort: adb on PATH.
+      const version = await runAdb('adb', ['version'])
+      if (version !== null && version.includes('Android Debug Bridge')) {
+        this.adb = 'adb'
+        this.adbVersion = version.split(/\r?\n/)[0] ?? ''
+      }
+    }
+    if (this.adb === null) return false
+    await runAdb(this.adb, ['start-server'], 15000)
+    return true
+  }
+
+  startPolling() {
+    if (this.timer !== null) return
+    this.timer = setInterval(() => { void this.poll() }, 2000)
+    void this.poll()
+  }
+
+  stopPolling() {
+    if (this.timer !== null) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+    for (const stream of this.streams.values()) stream.stop()
+    this.streams.clear()
+  }
+
+  dispose() {
+    this.stopPolling()
+    for (const ws of this.clients) {
+      try { ws.close(1001, 'plugin disposed') } catch { /* closed */ }
+    }
+    this.clients.clear()
+  }
+
+  async poll() {
+    if (this.polling) return
+    this.polling = true
+    try {
+      const output = await runAdb(this.adb, ['devices', '-l'], 8000)
+      if (output === null) return
+      const next = parseDevices(output)
+      const changed = this.syncDevices(next)
+      if (changed) this.broadcast({ type: 'devices', devices: this.deviceList() })
+    } finally {
+      this.polling = false
+    }
+  }
+
+  /** Sync device map with a fresh poll; attach/detach streams. Returns true when the list changed. */
+  syncDevices(next) {
+    let changed = false
+    // Detach disappeared devices.
+    for (const serial of [...this.devices.keys()]) {
+      if (!next.has(serial)) {
+        this.devices.delete(serial)
+        this.buffers.delete(serial)
+        const stream = this.streams.get(serial)
+        if (stream !== undefined) {
+          stream.stop()
+          this.streams.delete(serial)
+        }
+        changed = true
+      }
+    }
+    // Attach new devices / update state.
+    for (const [serial, info] of next) {
+      const prev = this.devices.get(serial)
+      if (prev === undefined || prev.state !== info.state || prev.model !== info.model) changed = true
+      this.devices.set(serial, info)
+      if (info.state === 'device' && !this.streams.has(serial)) {
+        const stream = new DeviceStream(
+          this.adb,
+          serial,
+          (line) => this.pushLine(serial, line),
+          () => { /* restart handled inside the stream */ },
+        )
+        this.streams.set(serial, stream)
+        stream.start()
+      } else if (info.state !== 'device' && this.streams.has(serial)) {
+        const stream = this.streams.get(serial)
+        stream.stop()
+        this.streams.delete(serial)
+        this.broadcast({ type: 'device-state', serial, state: info.state })
+      }
+    }
+    return changed
+  }
+
+  /** Push one raw line into the device ring buffer and fan out. */
+  pushLine(serial, raw) {
+    const entry = parseLogcatLine(raw) ?? { ts: '', pid: 0, tid: 0, level: '', tag: '', msg: raw, raw, cont: true }
+    let buffer = this.buffers.get(serial)
+    if (buffer === undefined) {
+      buffer = []
+      this.buffers.set(serial, buffer)
+    }
+    buffer.push(entry)
+    if (buffer.length > this.BUFFER_CAP) buffer.splice(0, buffer.length - this.BUFFER_CAP)
+    this.broadcast({ type: 'line', serial, entry })
+  }
+
+  /** Snapshot of the device list (for routes and the browser). */
+  deviceList() {
+    return [...this.devices.values()]
+  }
+
+  /** Recent buffered entries of a device, newest-last. */
+  recent(serial, lines = 200, level = '', filter = '') {
+    const buffer = this.buffers.get(serial) ?? []
+    const needle = filter.trim().toLowerCase()
+    const picked = buffer.filter((entry) => {
+      if (level !== '' && entry.level !== '' && entry.level !== level) return false
+      if (needle === '') return true
+      return entry.raw.toLowerCase().includes(needle)
+    })
+    return picked.slice(-lines)
+  }
+
+  /** Broadcast one frame to every open panel socket. */
+  broadcast(frame) {
+    const payload = JSON.stringify(frame)
+    for (const ws of this.clients) {
+      if (ws.readyState !== WebSocket.OPEN) continue
+      if (ws.bufferedAmount > 1024 * 1024) continue // slow client: drop rather than stall
+      try { ws.send(payload) } catch { /* closed */ }
+    }
+  }
+}
+
+/** -------------------------------------------------------------- routes */
+
+const API_BASE = '/api/dsh-logcat'
+
+function isLoopbackRequest(req) {
+  const address = req.socket?.remoteAddress ?? ''
+  const host = req.headers?.host ?? ''
+  const okAddress = address === '::1' || address === '127.0.0.1' || address.startsWith('::ffff:127.') || address.startsWith('127.')
+  if (!okAddress) return false
+  let hostUrl
+  try { hostUrl = new URL('http://' + host) } catch { return false }
+  if (hostUrl.hostname !== 'localhost' && !hostUrl.hostname.startsWith('127.')) return false
+  return true
+}
+
+function writeJson(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' })
+  res.end(JSON.stringify(body))
+}
+
+/** The one WebSocket server for logcat fan-out. */
+const streamWss = new WebSocketServer({ noServer: true })
+
+/** Build every /api/dsh-logcat route plus the stream upgrade. */
+function makeRoutes(engine) {
+  const routes = [
+    {
+      kind: 'exact',
+      path: API_BASE + '/status',
+      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 }
+        writeJson(res, 200, {
+          adbPath: engine.adb,
+          adbVersion: engine.adbVersion,
+          ready: engine.adb !== null,
+          devices: engine.deviceList(),
+          streaming: [...engine.streams.keys()],
+        })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/exec',
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) { writeJson(res, 403, { error: 'forbidden: loopback-only' }); return }
+        if ((req.method ?? 'GET') !== 'POST') { writeJson(res, 405, { error: 'method not allowed' }); return }
+        const chunks = []
+        let size = 0
+        for await (const chunk of req) {
+          size += chunk.length
+          if (size > 64 * 1024) { writeJson(res, 413, { error: 'body too large' }); return }
+          chunks.push(chunk)
+        }
+        let body = {}
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { /* fallthrough */ }
+        const serial = typeof body.serial === 'string' ? body.serial : ''
+        const command = typeof body.command === 'string' ? body.command : ''
+        if (engine.adb === null) { writeJson(res, 500, { error: 'adb not found' }); return }
+        if (serial === '' || command === '') { writeJson(res, 400, { error: 'serial and command are required' }); return }
+        const timeoutMs = typeof body.timeoutMs === 'number' ? body.timeoutMs : 15000
+        try {
+          const result = await runAdbFull(engine.adb, ['-s', serial, 'shell', command], timeoutMs)
+          writeJson(res, 200, result)
+        } catch (error) {
+          writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+  ]
+
+  const upgrade = {
+    path: API_BASE + '/stream',
+    handler: (req, socket, head) => {
+      if (!isLoopbackRequest(req)) {
+        socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+        socket.destroy()
+        return
+      }
+      streamWss.handleUpgrade(req, socket, head, (ws) => {
+        engine.clients.add(ws)
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const serial = url.searchParams.get('serial') ?? ''
+        // Send the current snapshot, then a history replay for the requested
+        // device (or the first attached one), then live lines keep flowing.
+        ws.send(JSON.stringify({
+          type: 'ready',
+          adbPath: engine.adb,
+          devices: engine.deviceList(),
+          streaming: [...engine.streams.keys()],
+        }))
+        const target = serial !== '' && engine.devices.has(serial)
+          ? serial
+          : engine.devices.get([...engine.devices.keys()][0])?.serial ?? ''
+        if (target !== '') {
+          ws.send(JSON.stringify({ type: 'history', serial: target, entries: engine.recent(target, 500) }))
+        }
+        // Client-driven replay (device switch, pause resume).
+        ws.on('message', (data) => {
+          let frame
+          try { frame = JSON.parse(String(data)) } catch { return }
+          if (frame?.type === 'replay' && typeof frame.serial === 'string') {
+            const entries = engine.devices.has(frame.serial) ? engine.recent(frame.serial, 500) : []
+            ws.send(JSON.stringify({ type: 'history', serial: frame.serial, entries }))
+          }
+        })
+        ws.on('close', () => { engine.clients.delete(ws) })
+        ws.on('error', () => { engine.clients.delete(ws) })
+      })
+    },
+  }
+
+  return { routes, upgrade }
+}
+
+/** The logcat_recent agent tool. */
+function logcatRecentTool(engine) {
+  return defineTool({
+    name: 'logcat_recent',
+    description: 'Read recent Android logcat entries from an attached adb device (dsh-logcat plugin). ' +
+      'Triggers: check android logcat, read device logs, debug the app on the phone, view crash logs.',
+    parameters: {
+      serial: { type: 'string', description: 'Device serial from logcat_devices (optional; defaults to the first attached device).' },
+      lines: { type: 'integer', description: 'Max entries to return (default 200, max 2000).' },
+      level: { type: 'string', enum: ['V', 'D', 'I', 'W', 'E', 'F'], description: 'Minimum severity filter (V=verbose … F=fatal).' },
+      filter: { type: 'string', description: 'Substring to filter the raw line (case-insensitive).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          entries: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                ts: { type: 'string', required: true },
+                pid: { type: 'integer', required: true },
+                tid: { type: 'integer', required: true },
+                level: { type: 'string', required: true },
+                tag: { type: 'string', required: true },
+                msg: { type: 'string', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const entries = value?.entries ?? []
+        if (entries.length === 0) return [{ type: 'text', text: '(no logcat entries)' }]
+        const levels = ['V', 'D', 'I', 'W', 'E', 'F']
+        const lines = entries.map((e) => {
+          const level = e.level !== '' ? e.level : '?'
+          const min = levels.indexOf(level)
+          const shown = min >= 2 ? level : (min >= 0 ? '·' : ' ')
+          return `${e.ts} ${String(e.pid).padStart(5)} ${String(e.tid).padStart(5)} ${shown} ${e.tag.padEnd(16)} : ${e.msg}`
+        })
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const devices = engine.deviceList()
+      const serial = typeof args.serial === 'string' && args.serial !== '' ? args.serial : devices[0]?.serial ?? ''
+      if (serial === '') return { entries: [] }
+      const lines = Math.min(Math.max(Number(args.lines ?? 200) || 200, 1), 2000)
+      const level = typeof args.level === 'string' ? args.level : ''
+      const filter = typeof args.filter === 'string' ? args.filter : ''
+      return { entries: engine.recent(serial, lines, level, filter) }
+    },
+  })
+}
+
+/** ------------------------------------------------------------------ */
+
+/** Mount the adb engine, routes, tool, and announcement. */
+export function apply(ctx, config) {
+  const resolve = () => ({
+    enabled: config?.enabled ?? true,
+    announceToAgent: config?.announceToAgent ?? true,
+  })
+
+  const engine = new AdbEngine()
+  // Observable handle for diagnostics and self-checks. Real cordis contexts
+  // reject bare property assignment ("cannot set property without provide"),
+  // so publish through ctx.provide when available and fall back to direct
+  // assignment for the plain-object stub used by selfcheck.mjs.
+  const logcatHandle = {
+    engine,
+    status: () => ({
+      adbPath: engine.adb,
+      adbVersion: engine.adbVersion,
+      ready: engine.adb !== null,
+      devices: engine.deviceList(),
+      streaming: [...engine.streams.keys()],
+      bufferSizes: Object.fromEntries([...engine.buffers.entries()].map(([s, b]) => [s, b.length])),
+    }),
+  }
+  if (typeof ctx.provide === 'function') ctx.provide('logcat', logcatHandle)
+  else ctx.logcat = logcatHandle
+  let inited = false
+  const initOnce = () => {
+    if (inited) return
+    inited = true
+    void engine.init().then((ok) => {
+      if (ok) engine.startPolling()
+    })
+  }
+
+  const { routes, upgrade } = makeRoutes(engine)
+  let disposeRoutes
+  let disposeTools
+  let disposeSection
+
+  const sync = () => {
+    const value = resolve()
+    if (disposeSection !== undefined) { disposeSection(); disposeSection = undefined }
+    if (disposeRoutes !== undefined) { disposeRoutes(); disposeRoutes = undefined }
+    if (disposeTools !== undefined) { disposeTools(); disposeTools = undefined }
+    if (!value.enabled) return
+    if (value.announceToAgent) {
+      disposeSection = ctx.systemPrompt.section({
+        name: 'plugin:dsh-logcat',
+        order: SECTION_ORDER,
+        text: LOGCAT_GUIDANCE,
+      })
+    }
+    disposeRoutes = ctx.effect(() => {
+      const disposers = routes.map((route) => ctx.webServer.register(route))
+      const upgradeDisposer = ctx.webServer.registerUpgrade(upgrade)
+      return () => {
+        for (const dispose of disposers) dispose()
+        upgradeDisposer()
+      }
+    }, 'dsh-logcat: routes')
+    disposeTools = ctx.effect(() => {
+      const disposers = [logcatRecentTool(engine)].map((tool) => ctx.tools.register(tool))
+      return () => { for (const dispose of disposers) dispose() }
+    }, 'dsh-logcat: tools')
+    initOnce()
+  }
+
+  ctx.effect(() => () => {
+    engine.dispose()
+  }, 'dsh-logcat: engine')
+
+  sync()
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "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.2.0",
+  "type": "module",
+  "packageManager": "pnpm@11.22.0",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib/**/*.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhu1090093659/dsh-web-ui.git"
+  }
+}