AgentSkillsCN

homescout-ingest

利用CLI工具（如jq/rg/awk）分析Homescout的输出目录（current.json、history/*.jsonl(.gz)、speedtests.jsonl、speedtests/*.jsonl(.gz)），解答关于设备存在、断网情况、扫描统计，或测速趋势等问题。当代理需要摄入Homescout的输出数据时，尤其是来自远程/Tailscale/Taildrive的输出路径时，此功能尤为适用。

SKILL.md
--- frontmatter
name: homescout-ingest
description: Analyze Homescout output directories (current.json, history/*.jsonl(.gz), speedtests.jsonl, speedtests/*.jsonl(.gz)) with CLI tools like jq/rg/awk to answer questions about device presence, outages, scan stats, or speedtest trends. Use when an agent needs to ingest Homescout outputs, especially from remote/Tailscale/Taildrive output paths.

Homescout Ingest

Overview

Ingest Homescout output artifacts and answer analysis questions using command-line tools without changing the underlying data. Focus on JSON and JSONL files, including gzip-compressed history and speedtest archives.

Workflow

  1. •Locate the output directory.
    • •Use the user-provided path or look up output_dir in the Homescout config.
    • •Treat the directory as read-only.
  2. •Identify the available files.
    • •current.json for the latest snapshot.
    • •history/YYYY-MM-DD.jsonl (or .jsonl.gz) for scan history.
    • •speedtests.jsonl plus speedtests/YYYY-MM-DD.jsonl (or .jsonl.gz) for speedtest history.
  3. •Choose the correct data source for the question.
    • •"Right now" questions: current.json.
    • •"Over time" device or scan questions: history/*.jsonl(.gz).
    • •Speedtest trends or degradations: speedtests*.jsonl(.gz).
  4. •Parse with jq and standard CLI tools.
    • •Use jq for JSON/JSONL, rg for filtering text, and gzip -cd for .gz files.
  5. •Summarize results with timestamps and counts.
    • •Include UTC timestamps and the file range you used.

Quick Commands

  • •Inspect latest snapshot metadata:
    • •jq '.metadata' current.json
  • •List devices currently offline:
    • •jq -r '.devices[] | select(.status=="offline") | [.ip,.hostname,.last_seen] | @tsv' current.json
  • •Count devices by status:
    • •jq -r '.devices[].status' current.json | sort | uniq -c
  • •Pull scan duration and average response time:
    • •jq '.metadata.scan_duration_ms, .stats.avg_response_time_ms' current.json
  • •Read history JSONL (plain):
    • •jq -r '.metadata.timestamp' history/2026-02-04.jsonl
  • •Read history JSONL (gzipped):
    • •gzip -cd history/2026-02-04.jsonl.gz | jq -r '.metadata.timestamp'
  • •Inspect speedtests:
    • •jq -r '[.timestamp,.download_mbps,.upload_mbps,.latency_ms,.degraded] | @tsv' speedtests.jsonl

Analysis Recipes

  • •Find new devices in a specific day:
    • •jq -r 'select(.stats.new_devices_this_scan > 0) | [.metadata.timestamp,.stats.new_devices_this_scan] | @tsv' history/2026-02-04.jsonl
  • •Detect devices that went offline since last scan:
    • •Compare current.json with the last history entry for status changes.
  • •Track a specific MAC or IP across history:
    • •rg -n '"mac":"AA:BB:CC' history/2026-02-*.jsonl
    • •For gzipped files: gzip -cd history/2026-02-04.jsonl.gz | rg -n '"mac":"AA:BB:CC'
  • •Identify slow responders in current scan:
    • •jq -r '.devices[] | select(.response_time_ms >= 200) | [.ip,.response_time_ms] | @tsv' current.json
  • •Summarize speedtest degradations:
    • •jq -r 'select(.degraded==true) | [.timestamp,.download_mbps,.upload_mbps] | @tsv' speedtests.jsonl

Schema Reference

  • •Read references/output_schema.md for the snapshot, device, and speedtest field definitions.

Guardrails

  • •Do not modify or delete output files unless explicitly requested.
  • •Handle .jsonl.gz with gzip -cd to avoid altering archives.
  • •Treat timestamps as UTC and preserve them in summaries.