react-native-debug-toolkit 3.1.3 → 3.1.5

package/README.md

@@ -1,27 +1,24 @@
 # React Native Debug Toolkit
 
-[中文](README.zh-CN.md)
+![demo](demo.gif)
 
-Dev-only React Native inspector with a local log bridge.
+[中文](README.zh-CN.md)
 
-It shows app logs on device, then can send the same device log stream to a local daemon for browser, curl, scripts, or MCP.
+React Native Debug Toolkit is a dev-only local debugging toolkit for React Native apps.
 
-## Model
+Use it to inspect app logs on device, stream logs to a desktop Web Console, and let AI coding agents read real runtime evidence through HTTP or MCP.
 
 ```text
-RN App logs -> Debug Panel -> local daemon -> Web Console / HTTP / MCP
+RN App -> Debug Panel -> local daemon -> Web Console / HTTP API / MCP
 ```
 
-Captured logs:
-
-- Network
-- Console
-- Navigation
-- Track
-- Zustand
+## What You Get
 
-The CLI daemon persists device logs to `~/.react-native-debug-toolkit/daemon-devices.json`.
-Use `DELETE /devices` to clear stored logs.
+- In-app debug panel with Network, Console, Navigation, Track, Zustand, Environment, and Clipboard logs.
+- Desktop Web Console for simulator and real-device logs.
+- Local HTTP API for curl, scripts, Codex, Claude Code, and other AI agents with shell access.
+- Optional MCP server with `list_app_devices` and `get_app_logs`.
+- Local-first workflow. No cloud service. No AI API call inside the package.
 
 ## Install
 
@@ -29,14 +26,16 @@ Use `DELETE /devices` to clear stored logs.
 npm install react-native-debug-toolkit
 ```
 
-Optional:
+Optional dependencies:
 
 ```bash
 npm install @react-native-clipboard/clipboard
 npm install @react-native-async-storage/async-storage
 ```
 
-## App Usage
+## Quick Start
+
+Wrap your app:
 
 ```tsx
 import { DebugView } from 'react-native-debug-toolkit';
@@ -50,70 +49,54 @@ export function App() {
 }
 ```
 
-Open app in dev mode. Tap `DBG`.
-
-Disable features:
-
-```tsx
-<DebugView features={{ clipboard: false, zustand: false }}>
-  <AppContent />
-</DebugView>
-```
+Run the app in dev mode, then tap `DBG`.
 
-Navigation tracking:
+Start the desktop daemon:
 
-```tsx
-<DebugView navigationRef={navigationRef}>
-  <NavigationContainer ref={navigationRef}>
-    <AppContent />
-  </NavigationContainer>
-</DebugView>
+```bash
+npx debug-toolkit --daemon-only
 ```
 
-Zustand:
+Open the Web Console:
 
-```tsx
-import { zustandLogMiddleware } from 'react-native-debug-toolkit';
+```text
+http://127.0.0.1:3799/console
 ```
 
-Track:
-
-```tsx
-import { addTrackLog } from 'react-native-debug-toolkit';
+In the app, open Debug Panel -> gear -> `Send Once` or `Start Live Sync`.
 
-addTrackLog({ eventName: 'button_click' });
-```
+## Device Setup
 
-## Desktop Logs
+| Runtime | App endpoint |
+| --- | --- |
+| iOS simulator | `http://localhost:3799` |
+| Android emulator | `http://10.0.2.2:3799` |
+| Real device | `http://<mac-ip>:3799` |
 
-Start daemon:
+For a real device, first open this URL in the phone browser:
 
-```bash
-npx debug-toolkit --daemon-only
+```text
+http://<mac-ip>:3799/health
 ```
 
-The default device log store is `~/.react-native-debug-toolkit/daemon-devices.json`.
-Override it with `--store /path/to/devices.json` or `DEBUG_TOOLKIT_DAEMON_STORE`.
+If it does not open, check Mac firewall, Wi-Fi isolation, VPN, local network permission, and cleartext HTTP settings.
 
-Open:
+The daemon stores logs at:
 
 ```text
-http://127.0.0.1:3799/console
+~/.react-native-debug-toolkit/daemon-devices.json
 ```
 
-In app: Debug Panel -> gear -> `Send Once` or `Start Live Sync`.
+Custom store path:
 
-Endpoints:
-
-| Runtime | Endpoint |
-| --- | --- |
-| iOS simulator | `http://localhost:3799` |
-| Android emulator | `http://10.0.2.2:3799` |
-| Real device | `http://<mac-ip>:3799` |
+```bash
+npx debug-toolkit --daemon-only --store /path/to/devices.json
+DEBUG_TOOLKIT_DAEMON_STORE=/path/to/devices.json npx debug-toolkit --daemon-only
+```
 
-Real device rule: phone browser must open `http://<mac-ip>:3799/health`. If not, check firewall, Wi-Fi isolation, VPN, and cleartext HTTP.
+## Read Logs With HTTP
 
-## HTTP
+HTTP is the best path when your AI agent or script has shell access.
 
 ```bash
 BASE=http://127.0.0.1:3799
@@ -124,10 +107,11 @@ curl "$BASE/devices/latest"
 
 DEVICE_ID=$(curl -s "$BASE/devices" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log((JSON.parse(s).devices||[])[0]?.deviceId||''))")
 
-curl "$BASE/devices/$DEVICE_ID"
 curl "$BASE/devices/$DEVICE_ID/logs?limit=100"
 curl "$BASE/devices/$DEVICE_ID/logs?type=network&failedOnly=true&limit=50"
 curl "$BASE/devices/$DEVICE_ID/logs?type=console&limit=100"
+curl "$BASE/devices/$DEVICE_ID/logs?entryId=<entryId>"
+curl "$BASE/devices/$DEVICE_ID/logs?limit=100&includeBodies=true"
 curl -X DELETE "$BASE/devices"
 ```
 
@@ -140,13 +124,13 @@ POST   /ingest
 GET    /devices
 GET    /devices/latest
 GET    /devices/:deviceId
-GET    /devices/:deviceId/logs
+GET    /devices/:deviceId/logs?type=&limit=&failedOnly=&includeBodies=&entryId=
 DELETE /devices
 GET    /events
 GET    /console
 ```
 
-## MCP
+## Use MCP
 
 ```bash
 claude mcp add debug-toolkit -- npx debug-toolkit
@@ -157,7 +141,41 @@ Tools:
 - `list_app_devices`
 - `get_app_logs`
 
-Use curl when shell is available.
+`get_app_logs` excludes bodies by default to reduce tokens. Set `includeBodies=true` or pass `entryId` to fetch one full log entry.
+
+## App Options
+
+Disable features:
+
+```tsx
+<DebugView features={{ clipboard: false, zustand: false }}>
+  <AppContent />
+</DebugView>
+```
+
+Navigation tracking:
+
+```tsx
+<DebugView navigationRef={navigationRef}>
+  <NavigationContainer ref={navigationRef}>
+    <AppContent />
+  </NavigationContainer>
+</DebugView>
+```
+
+Zustand:
+
+```tsx
+import { zustandLogMiddleware } from 'react-native-debug-toolkit';
+```
+
+Track:
+
+```tsx
+import { addTrackLog } from 'react-native-debug-toolkit';
+
+addTrackLog({ eventName: 'button_click' });
+```
 
 ## Exports
 
@@ -173,11 +191,11 @@ Use curl when shell is available.
 - `autoDetectDaemonIp`
 - feature factories and types
 
-## Boundaries
+## Limits
 
 - Dev tool, not production monitoring.
 - Local daemon, not cloud replay.
-- Network logs are observed traffic, not auth/token analysis.
+- Network capture observes traffic; it does not analyze auth, tokens, or business errors.
 - No default redaction.
 - Not a React Native DevTools replacement.
 

package/README.zh-CN.md

@@ -1,27 +1,24 @@
 # React Native Debug Toolkit
 
-[English](README.md)
+![demo](demo.gif)
 
-React Native 开发期调试面板 + 本地日志桥。
+[English](README.md)
 
-它能在 App 内看日志，也能把同一台设备的日志流发到本机 daemon，供浏览器、curl、脚本、MCP 读取。
+React Native Debug Toolkit 是 React Native 开发期本地调试工具。
 
-## 模型
+它可以在 App 内查看日志，把模拟器或真机日志同步到桌面 Web Console，也可以让 AI 编程工具通过 HTTP 或 MCP 直接读取真实运行日志。
 
 ```text
-RN App logs -> Debug Panel -> local daemon -> Web Console / HTTP / MCP
+RN App -> Debug Panel -> local daemon -> Web Console / HTTP API / MCP
 ```
 
-采集：
-
-- Network
-- Console
-- Navigation
-- Track
-- Zustand
+## 能做什么
 
-CLI daemon 默认把设备日志持久化到 `~/.react-native-debug-toolkit/daemon-devices.json`。
-用 `DELETE /devices` 清空已存日志。
+- App 内调试面板：Network、Console、Navigation、Track、Zustand、Environment、Clipboard。
+- 桌面 Web Console：查看模拟器和真机日志。
+- 本地 HTTP API：给 curl、脚本、Codex、Claude Code、其他有 shell 的 AI 读取。
+- 可选 MCP：提供 `list_app_devices` 和 `get_app_logs`。
+- 本地优先：不接云服务，包内不调用 AI API。
 
 ## 安装
 
@@ -29,14 +26,16 @@ CLI daemon 默认把设备日志持久化到 `~/.react-native-debug-toolkit/daem
 npm install react-native-debug-toolkit
 ```
 
-可选：
+可选依赖：
 
 ```bash
 npm install @react-native-clipboard/clipboard
 npm install @react-native-async-storage/async-storage
 ```
 
-## App 接入
+## 快速开始
+
+包住你的 App：
 
 ```tsx
 import { DebugView } from 'react-native-debug-toolkit';
@@ -50,70 +49,54 @@ export function App() {
 }
 ```
 
-开发模式打开 App。点击 `DBG`。
-
-禁用功能：
-
-```tsx
-<DebugView features={{ clipboard: false, zustand: false }}>
-  <AppContent />
-</DebugView>
-```
+开发模式打开 App，点击 `DBG`。
 
-导航追踪：
+启动桌面 daemon：
 
-```tsx
-<DebugView navigationRef={navigationRef}>
-  <NavigationContainer ref={navigationRef}>
-    <AppContent />
-  </NavigationContainer>
-</DebugView>
+```bash
+npx debug-toolkit --daemon-only
 ```
 
-Zustand：
+打开 Web Console：
 
-```tsx
-import { zustandLogMiddleware } from 'react-native-debug-toolkit';
+```text
+http://127.0.0.1:3799/console
 ```
 
-Track：
-
-```tsx
-import { addTrackLog } from 'react-native-debug-toolkit';
+App 内打开 Debug Panel -> 齿轮 -> `Send Once` 或 `Start Live Sync`。
 
-addTrackLog({ eventName: 'button_click' });
-```
+## 设备连接
 
-## Desktop Logs
+| 运行时 | App endpoint |
+| --- | --- |
+| iOS simulator | `http://localhost:3799` |
+| Android emulator | `http://10.0.2.2:3799` |
+| 真机 | `http://<mac-ip>:3799` |
 
-启动 daemon：
+真机先用手机浏览器打开：
 
-```bash
-npx debug-toolkit --daemon-only
+```text
+http://<mac-ip>:3799/health
 ```
 
-默认设备日志存储文件：`~/.react-native-debug-toolkit/daemon-devices.json`。
-可用 `--store /path/to/devices.json` 或 `DEBUG_TOOLKIT_DAEMON_STORE` 覆盖。
+打不开就检查 Mac 防火墙、Wi-Fi 隔离、VPN、本地网络权限、明文 HTTP 配置。
 
-打开：
+daemon 默认日志文件：
 
 ```text
-http://127.0.0.1:3799/console
+~/.react-native-debug-toolkit/daemon-devices.json
 ```
 
-App 内：Debug Panel -> 齿轮 -> `Send Once` 或 `Start Live Sync`。
+自定义存储路径：
 
-Endpoint：
-
-| 运行时 | Endpoint |
-| --- | --- |
-| iOS simulator | `http://localhost:3799` |
-| Android emulator | `http://10.0.2.2:3799` |
-| 真机 | `http://<mac-ip>:3799` |
+```bash
+npx debug-toolkit --daemon-only --store /path/to/devices.json
+DEBUG_TOOLKIT_DAEMON_STORE=/path/to/devices.json npx debug-toolkit --daemon-only
+```
 
-真机规则：手机浏览器必须能打开 `http://<mac-ip>:3799/health`。打不开就查防火墙、Wi-Fi 隔离、VPN、明文 HTTP。
+## 用 HTTP 读取日志
 
-## HTTP
+AI 或脚本有 shell 时，优先用 HTTP。
 
 ```bash
 BASE=http://127.0.0.1:3799
@@ -124,10 +107,11 @@ curl "$BASE/devices/latest"
 
 DEVICE_ID=$(curl -s "$BASE/devices" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log((JSON.parse(s).devices||[])[0]?.deviceId||''))")
 
-curl "$BASE/devices/$DEVICE_ID"
 curl "$BASE/devices/$DEVICE_ID/logs?limit=100"
 curl "$BASE/devices/$DEVICE_ID/logs?type=network&failedOnly=true&limit=50"
 curl "$BASE/devices/$DEVICE_ID/logs?type=console&limit=100"
+curl "$BASE/devices/$DEVICE_ID/logs?entryId=<entryId>"
+curl "$BASE/devices/$DEVICE_ID/logs?limit=100&includeBodies=true"
 curl -X DELETE "$BASE/devices"
 ```
 
@@ -140,13 +124,13 @@ POST   /ingest
 GET    /devices
 GET    /devices/latest
 GET    /devices/:deviceId
-GET    /devices/:deviceId/logs
+GET    /devices/:deviceId/logs?type=&limit=&failedOnly=&includeBodies=&entryId=
 DELETE /devices
 GET    /events
 GET    /console
 ```
 
-## MCP
+## 使用 MCP
 
 ```bash
 claude mcp add debug-toolkit -- npx debug-toolkit
@@ -157,7 +141,41 @@ claude mcp add debug-toolkit -- npx debug-toolkit
 - `list_app_devices`
 - `get_app_logs`
 
-有 shell 时优先 curl。
+`get_app_logs` 默认不返回 body，减少 token。设置 `includeBodies=true` 或传 `entryId` 可读取单条完整日志。
+
+## App 配置
+
+禁用功能：
+
+```tsx
+<DebugView features={{ clipboard: false, zustand: false }}>
+  <AppContent />
+</DebugView>
+```
+
+导航追踪：
+
+```tsx
+<DebugView navigationRef={navigationRef}>
+  <NavigationContainer ref={navigationRef}>
+    <AppContent />
+  </NavigationContainer>
+</DebugView>
+```
+
+Zustand：
+
+```tsx
+import { zustandLogMiddleware } from 'react-native-debug-toolkit';
+```
+
+Track：
+
+```tsx
+import { addTrackLog } from 'react-native-debug-toolkit';
+
+addTrackLog({ eventName: 'button_click' });
+```
 
 ## 导出
 
@@ -177,7 +195,7 @@ claude mcp add debug-toolkit -- npx debug-toolkit
 
 - 开发工具，不是生产监控。
 - 本地 daemon，不是云 replay。
-- Network 日志只是监测流量，不做 auth/token 分析。
+- Network 只观察流量，不自动分析 auth、token、业务错误。
 - 不默认脱敏。
 - 不替代 React Native DevTools。
 

package/bin/debug-toolkit.js

@@ -6,6 +6,7 @@ const {
   DAEMON_NAME,
   DEFAULT_HOST,
   DEFAULT_PORT,
+  getDefaultDeviceStorePath,
   getLanIPs,
 } = require('../node/daemon/src/constants');
 const { createDaemonServer } = require('../node/daemon/src/server');
@@ -25,7 +26,7 @@ function hasHelpFlag(args) {
 
 function printHelp() {
   process.stderr.write(
-    'Usage: debug-toolkit [--host 0.0.0.0] [--port 3799] [--token dev-token] [--daemon-only]\n'
+    'Usage: debug-toolkit [--host 0.0.0.0] [--port 3799] [--token dev-token] [--store ~/.react-native-debug-toolkit/daemon-devices.json] [--daemon-only]\n'
   + '\n'
   + 'Starts the debug toolkit: daemon (HTTP + Web Console) and MCP stdio server.\n'
   + '\n'
@@ -33,6 +34,7 @@ function printHelp() {
   + '  --host <addr>   Host to bind (default: 0.0.0.0)\n'
     + '  --port <port>   Port to bind (default: 3799)\n'
   + '  --token <str>   Auth token for daemon endpoints\n'
+  + '  --store <path>  Device log store path\n'
   + '  --daemon-only   Start only the HTTP daemon and Web Console\n'
   + '  -h, --help      Show this help\n',
   );
@@ -58,6 +60,11 @@ async function main() {
   const host = readOption(args, '--host', process.env.DEBUG_TOOLKIT_DAEMON_HOST || DEFAULT_HOST);
   const port = Number(readOption(args, '--port', process.env.DEBUG_TOOLKIT_DAEMON_PORT || DEFAULT_PORT));
   const token = readOption(args, '--token', process.env.DEBUG_TOOLKIT_DAEMON_TOKEN || '');
+  const deviceStorePath = readOption(
+    args,
+    '--store',
+    process.env.DEBUG_TOOLKIT_DAEMON_STORE || getDefaultDeviceStorePath(),
+  );
   const daemonOnly = hasDaemonOnlyFlag(args);
 
   if (!Number.isFinite(port) || port <= 0) {
@@ -67,7 +74,7 @@ async function main() {
   }
 
   // Start daemon HTTP server in-process
-  const { server } = createDaemonServer({ token });
+  const { server } = createDaemonServer({ token, deviceStorePath });
 
   server.on('error', (error) => {
     process.stderr.write(`${DAEMON_NAME} failed to start: ${error.message}\n`);
@@ -79,6 +86,7 @@ async function main() {
       const consolePath = token ? `/console?token=${encodeURIComponent(token)}` : '/console';
       process.stderr.write(`${DAEMON_NAME} listening on http://${host}:${port}\n`);
       process.stderr.write(`Web Console: ${getLocalOrigin(host, port)}${consolePath}\n`);
+      process.stderr.write(`Device store: ${deviceStorePath}\n`);
       const lanIPs = getLanIPs();
       if (lanIPs.length > 0) {
         process.stderr.write(`LAN IPs: ${lanIPs.join(', ')}\n`);