wuji-cli-logs

メンタルモデル

• ログはローカルのテキストファイルです。Wuji SDK、Studio、stderr キャプチャ、CLI 自体が ~/.wuji/logs/ に書き込みます。CLI はこれらのファイルを検出して処理し、自身の操作記録を cli_*.jsonl として書き込みます。
• テキストソース：sdk_*.log、studio_*.log、stderr_*.log、および cli_<date>.jsonl です。cli_<date>.jsonl は CLI が実行したコマンドの記録（コマンドライン、終了コード、実行時間、エラー）です。wuji sub と wuji completions は操作記録を書き込みません。デバイス通信ダンプ（device_*.bin）はデフォルトで除外され、--with-dump を指定した場合にのみ含まれます。wuji logs export はデフォルトで sdk、studio、stderr、cli をまとめます。対象を絞るには --source を指定してください。wuji doctor の実行結果も操作ログに記録されるため、デフォルトのバンドルには診断結果が含まれます。操作ログはほかのテキストログと同様にエクスポート時に秘匿化されます。ローカルファイル自体は書き込まれたままなので、診断時に直接読み取ることができます。
• エクスポートでは、選択したログファイル、ホストのスナップショット（host_snapshot.json）、doctor の診断結果（doctor_diagnosis.json。wuji doctor --json と同じ形式で、ホスト環境のチェックとデバイスごとの結果がすべて checks に含まれます）、デバイスのスナップショットとフラッシュ履歴（デバイスが検出された場合は devices/<sn>_<ts>_device.json／_flash.jsonl）、該当するハンドモデルのキャリブレーション記録、マニフェスト（manifest.json）を含む単一の ZIP が生成されます。ログファイルが見つからない場合でも、スナップショットと診断結果は含まれます。
• キャリブレーション記録は自動的に含まれます：~/.wuji/calibration/recordings/ にある、同じ包含的なローカル日付範囲と重なる実行記録は、calibration-recordings/<run_id>/ の下にコピーされます。ended_at がない部分的な記録やレガシー記録は、ローカルの started_at の日付における単一時点として扱われ、絞り込まれます。
• 記録マニフェストの互換性：新しいハンドモデルの実行では schema_version: 2 と calibration_type: "hand_model" が使用されます。エクスポートではレガシーのスキーマ 1／"ik" の実行記録も受け付け、すべてのソースマニフェストを変更せずに保持します。
• 秘匿化は多層構造です：認証情報（JWT、Bearer Token、API Key、Token、License、Password、AWS Key）は常に秘匿化されます。個人情報（ユーザー名、ユーザーパス、ホスト名、SSID、IPv4、MAC）はデフォルトで秘匿化されますが、--no-redact で無効にできます（内部ビルドのみ）。キャリブレーションの .mcap ファイルには生の動作データが含まれるため、秘匿化されることはありません。
• 終了コード：0 = 成功、1 = いずれかの処理に失敗（デバイス診断、ログのエクスポート、キャリブレーション記録、デバイスのスナップショット／フラッシュ収集の失敗を含む）。復旧可能な項目はバンドルのマニフェストに記載されたままになります。

サブコマンド

サブコマンド	目的
wuji logs path	ログディレクトリのパスを表示します
wuji logs list	利用可能なログファイルをサイズと日付とともに一覧表示します
wuji logs export	ログ、キャリブレーション記録、スナップショット、診断結果を ZIP バンドルにエクスポートします
wuji logs dump	デバイス側の診断スナップショットとフラッシュ履歴を収集します（Wuji Hand 2）

よくある使い方

# Locate the log directory
wuji logs path

# List recent log files
wuji logs list
wuji logs list --days 7
wuji logs list --source sdk,studio --days 3
wuji logs list --source cli --days 1        # CLI operation records

# Export a default bundle (last 1 day: sdk / studio / stderr / cli logs and matching calibration runs)
wuji logs export
wuji logs export --days 7
wuji logs export --source sdk --days 3
wuji logs export --source cli --days 1      # only the CLI operation records

# Include device communication dumps
wuji logs export --with-dump

# Write the ZIP to a specific path
wuji logs export -o /tmp/support-bundle.zip

# Collect a device-side diagnostic snapshot + flash history (Wuji Hand 2)
wuji logs dump                          # scan all devices
wuji logs dump --sn <SN>                # single device
wuji logs dump --sn <SN> -o /tmp/dump   # write to a directory

# JSON / JSONL output for scripting
wuji logs export --json
wuji logs export --jsonl
wuji logs list --json
wuji logs list --jsonl
wuji logs path --json
wuji logs dump --json
wuji logs dump --jsonl

デフォルトの ZIP ファイル名

-o を指定しない場合、ZIP はカレントディレクトリに次の名前で書き込まれます。

wuji-logs-{env_id}-{timestamp}.zip

env_id はマシン ID の SHA-256 の先頭 6 文字です。timestamp は YYYYMMDD-HHMMSS です。

マスキングの概要

レイヤー	マスキングされるもの	無効にできるか
🔴 認証情報	JWT、Bearer Token、API Key、Token、License、Password、AWS Key	できません
🟡 プライベートなテキストデータ	ユーザー名、ユーザーパス、ホスト名、SSID、IPv4、MAC	--no-redact で可能（内部ビルドのみ）
🟢 保持されるメタデータ	デバイスの SN、ファームウェアのバージョン、タイムスタンプ、エラースタック	常に保持されます
⚠️ キャリブレーションの動き	なし。.mcap ファイルには未加工の手の動きのデータが含まれます	該当しません

マスキングは ZIP 内のテキストログファイルに適用されます。バイナリダンプ（device_*.bin）はマスキングされません。ホストの host_snapshot.json では、ホスト名、マシン ID、MAC アドレスがマスキングされます。doctor_diagnosis.json と、デバイスから積極的に収集されるデバイス側のデータ（devices/*_device.json、devices/*_flash.jsonl）はマスキングされず、そのまま含まれます。診断の対象はソフトウェアのバージョン、OS、ネットワークインターフェイス数、デバイスの検出、およびデバイスごとのチェック（ホスト名／マシン ID／MAC は含まれません）であり、デバイスデータはホストのプライベートデータではないためです。キャリブレーションの .mcap ファイルにも未加工の動きのデータが含まれ、マスキングされません。共有する前にバンドルを確認してください。

一般的なワークフロー

# 1. Check what logs are available
wuji logs list --days 3

# 2. Export a support bundle with today's logs
wuji logs export -o ~/Desktop/support.zip

# 3. Inspect the bundle contents
unzip -l ~/Desktop/support.zip
# Expected structure:
#   manifest.json
#   host_snapshot.json
#   doctor_diagnosis.json
#   logs/YYYY-MM-DD/sdk_*.log
#   logs/YYYY-MM-DD/studio_*.log
#   logs/YYYY-MM-DD/stderr_*.log
#   logs/YYYY-MM-DD/cli_*.jsonl     (CLI operation records, included by default)
#   devices/<sn>_<ts>_device.json   (device diagnostic snapshot, when devices found)
#   devices/<sn>_<ts>_flash.jsonl   (device flash history, when devices found)
#   calibration-recordings/<run_id>/manifest.json
#   calibration-recordings/<run_id>/full.mcap
#   calibration-recordings/<run_id>/steps/*.mcap  (completed steps only)

よくあるエラー

症状	意味と対処
failed to scan log directory	ログディレクトリが存在しないか、アクセスできません。CLI はスナップショットと診断を含むバンドルを引き続き作成します。
failed to create zip bundle	出力先のパスに書き込みできないか、ディスクの空き容量がありません。権限と空き容量を確認してください。
バンドルが 300 MB を超える	警告が表示されます。--days で日付範囲を絞るか、ダンプを除外してください。
診断に skipped (no device found) と表示される	Wuji デバイスが検出されませんでした。エクスポートは、利用可能なデータを使って続行されます。

詳細なヘルプと利用可能なすべてのオプションを確認するには、wuji logs の任意のサブコマンドの後に --help を追加してください。