Tuya MiniApp Log Reader

Overview

Inspect Tuya miniapp console logs (miniapplog) for troubleshooting, error discovery, and lifecycle/network/socket issue diagnosis.

When to Use

Project root contains project.tuya.json
Need to view, search, or filter miniapp runtime console logs
Diagnosing lifecycle events (onLaunch, onReady), network/socket issues, or framework crashes
Checking log health (stale, incomplete, missing)

When NOT to Use

Not a Tuya miniapp project (no project.tuya.json)
Analyzing build/compile logs (this skill handles runtime console logs only)
Need real-time streaming logs (this skill scans files, not live streams)

CRITICAL: Always Use the Script

NEVER fall back to manually reading, grepping, or parsing miniapplog files. If the script cannot be located after all discovery steps below, inform the user and ask for the installation path — do not silently switch to manual log parsing.

The skill appearing in available_skills means it is installed. A File not found on the fullPath only means the cached path is stale, not that the skill is absent.

Script

Path relative to this SKILL.md: scripts/miniapplog_reader.py

python3 scripts/miniapplog_reader.py <command> [options]

All commands accept --root <project-path> (default .) for Tuya project root.

Session Preference Rule

First search in a session must ask: "Search remote or simulator logs?"
Store user choice in current session memory.
Reuse that choice in later operations unless user explicitly switches source.
Always return source origin in output:
- user_selected
- session_memory
- fallback (auto rule: prefer remote, else simulator)

Incremental Read Rule

After each search or summary, store response latest_timestamp in session memory.
When user asks for "new logs" or "latest logs", pass --since-timestamp <stored_timestamp>.
If no stored timestamp exists, fall back to --since-minutes 30.

Temporary Debug Log Rule

Tuya miniapp logs may lose object/array values when console.log prints raw objects directly.
When agent asks user to add temporary debug logs, require serialization first.
Use safe string output for object/array payloads, for example:
- console.log("[debug] payload=" + JSON.stringify(payload))
- console.log("[debug] list=" + JSON.stringify(list))
If JSON.stringify may fail (e.g. circular refs), use fallback:
- const toText = (v) => { try { return JSON.stringify(v); } catch { return String(v); } };
- console.log("[debug] state=" + toText(state))

Post-Fix Cleanup Rule

When user confirms issue is fixed/resolved, ask: "Issue resolved. Clear the miniapp log file to start fresh?"
If user agrees, run clear --root ..
Never clear logs without explicit confirmation.

Gitignore Rule

On first ensure in a session, also run gitignore-check --root ..
If log file is not ignored, auto-add pattern to .gitignore.
Inform user when patterns are added.

Workflow

Ensure project validity
- Detect project.tuya.json.
- If missing/invalid, stop and return structured warning.
Ensure log path
- If miniapplogpath missing, set to <root-absolute>/miniapplog.
Select source
- Ask user on first search; then reuse session preference.
Run diagnostics first
- Check missing log file, stale timestamp, and incomplete log signals.
Check size and ask before cleanup
- If log size exceeds 10MB, return warning/tip and ask user whether to clear.
- Never auto-rotate or create backups.
Execute task command
- summary, suggest, search, clear, or gitignore-check.
- Prefer narrowed search: run suggest first, then add --contains / --exclude / --level.
Return strict JSON fields
- Include status, source metadata, warnings/tips, and maintenance metadata.

Constraints

Must run in Tuya miniapp project context (project.tuya.json).
Output must be JSON with stable top-level fields.
Default search results are unlimited.
Keep scan streaming-based for log traversal.
If log file missing, guide user to upgrade Tuya IDE.
If stale/incomplete, guide user to rebuild or run remote debugging again.

Command Reference

`ensure`

Validate project.tuya.json and ensure miniapplogpath is configured.

--root (optional, default .): project root path

`summary`

Show source distribution and health diagnostics.

--root (optional, default .): project root path
--source (optional, default auto): remote or simulator; if omitted, fallback chooses remote first
--source-mode (optional, default fallback): user_selected / session_memory / fallback
--stale-minutes (optional, default 30): stale threshold in minutes

`suggest`

Extract high-frequency keywords for the selected source.

--root (optional, default .): project root path
--source (optional, default auto): remote or simulator
--source-mode (optional, default fallback): user_selected / session_memory / fallback
--stale-minutes (optional, default 30): stale threshold in minutes
--top (optional, default 20): number of keywords to return

`search`

Search logs with source/time/text filters.

--root (optional, default .): project root path
--source (optional, default auto): remote or simulator
--source-mode (optional, default fallback): user_selected / session_memory / fallback
--contains (optional, repeatable): include filter, AND logic (all values must match)
--contains-any (optional, repeatable): include filter, OR logic (at least one value must match; combinable with --contains)
--exclude (optional, repeatable): exclude filter, OR logic (any value excludes entry)
--level (optional): log / info / warn / error / debug / startGroupCollapsed / endGroup
--since-minutes (optional): keep entries newer than N minutes
--since-timestamp (optional): ISO8601 timestamp, takes priority over --since-minutes
--limit (optional, default unlimited): max retained matches (keeps most recent N)
--stale-minutes (optional, default 30): stale threshold in minutes

`clear`

Truncate log file content to empty.

--root (optional, default .): project root path

`gitignore-check`

Ensure log file is excluded from version control.

--root (optional, default .): project root path

Output Schema

Common fields (by command):

status: OK | NOT_TUYA_PROJECT | PROJECT_JSON_INVALID | LOG_FILE_MISSING | MINIAPPLOGPATH_OK | MINIAPPLOGPATH_ADDED | INVALID_SINCE_TIMESTAMP
project_file: absolute project config path
miniapplogpath: resolved log path
selected_source: remote|simulator (for source-aware commands)
source_preference_origin: user_selected|session_memory|fallback
warnings: string[]
tips: string[]
maintenance:
- size_bytes: number|null
- size_limit_mb: number
- exceeds_size_limit: boolean
- action_required: ASK_CLEAR_CONFIRMATION|null

Command-specific fields:

summary: total_lines, valid_lines, remote_lines, simulator_lines, latest_timestamp, stale_minutes
suggest: keywords[], latest_timestamp, stale_minutes
search: total_lines, matched_lines, latest_timestamp, stale_minutes, matches[]
clear: cleared_bytes
gitignore-check: gitignore_path, patterns_checked, patterns_added, already_present

Command Examples

python3 scripts/miniapplog_reader.py ensure --root .
python3 scripts/miniapplog_reader.py summary --root . --source remote --source-mode user_selected
python3 scripts/miniapplog_reader.py suggest --root . --source remote --source-mode session_memory --top 20
python3 scripts/miniapplog_reader.py search --root . --source remote --source-mode session_memory --contains onLaunch --contains error --since-minutes 30
python3 scripts/miniapplog_reader.py search --root . --source remote --source-mode session_memory --contains-any network --contains-any socket --since-minutes 60
python3 scripts/miniapplog_reader.py search --root . --source remote --source-mode session_memory --since-timestamp "2026-03-02T10:00:00Z" --contains error
python3 scripts/miniapplog_reader.py clear --root .
python3 scripts/miniapplog_reader.py gitignore-check --root .

Additional Resources

Log format and field reference: references/log-format.md
Search keyword guide and sequence: references/search-keywords.md

Search Filtering Strategy

Always run suggest before search to discover relevant keywords. Avoid unfiltered search on large logs.

Recommended sequence:

summary — validate source and log freshness.
suggest --top 20 — discover high-frequency keywords as candidate filters.
search — combine filters based on the scenario below.

Filter types

Filter	Logic	Use when
`--contains a --contains b`	AND — all must match	Narrowing: need both "error" AND "network"
`--contains-any a --contains-any b`	OR — at least one	Broadening: need "network" OR "socket"
`--exclude x --exclude y`	OR — any excludes	Noise removal: drop Redux actions, framework internals
`--level error`	Exact type match	Only show entries of a specific log level
Combined	AND + OR + exclude	`--contains error --contains-any network --contains-any socket --exclude "%c action"`

Common filtering patterns

Scenario	Command
Lifecycle issue	`search --contains onLaunch --contains onReady`
Network / socket	`search --contains-any network --contains-any socket --contains-any connected`
Error + framework	`search --contains error --contains framework`
Redux noise cleanup	`search --contains error --exclude "%c action" --exclude "prev state"`
Recent errors only	`search --level error --since-minutes 30`
Structured payload	Print `JSON.stringify(payload)` first, then search with stable keys from the stringified JSON

Quick Scenarios

"Check latest miniapp logs" → summary
"Find error logs in last 30 minutes" → search --level error --since-minutes 30
"Find network or socket issues" → search --contains-any network --contains-any socket
"Show onLaunch logs" → search --contains onLaunch
"Suggest top keywords" → suggest --top 20
"Read new logs since last check" → search --since-timestamp <stored_timestamp>
"Clear log file after fix" → clear
"Make sure logs are not tracked by git" → gitignore-check

Common Mistakes

Falling back to manual grep/read of miniapplog instead of using the bundled script.
Running search without ensure first.
Skipping source confirmation (remote vs simulator) in first search.
Running broad unfiltered search on large logs; use suggest then add --contains / --exclude.
Ignoring warnings and tips fields in JSON output.

tuya-miniapplog-reader