wuji-cli-logs

心智模型

• 日志是本地文本文件，由 Wuji SDK、Studio、stderr 捕获和 CLI 自身写入，存储在 ~/.wuji/logs/ 下。CLI 会发现并处理这些文件，并将自身的操作记录写为 cli_*.jsonl。
• 文本来源：sdk_*.log、studio_*.log、stderr_*.log 和 cli_<date>.jsonl——CLI 对其运行命令的记录（命令行、退出代码、耗时、错误）。wuji sub 和 wuji completions 不会写入操作记录。设备通信转储（device_*.bin）默认排除，需通过 --with-dump 启用。wuji logs export 默认打包 sdk、studio、stderr 和 cli；传入 --source 可缩小范围。运行 wuji doctor 也会将其报告记录在操作日志中，因此默认打包内容包含检查结果。导出时，操作日志和其他文本日志一样会进行脱敏；本地文件则保持原样写入，因此诊断时可以直接读取。
• 导出会生成一个 ZIP 文件，其中包含选定的日志文件、主机快照（host_snapshot.json）、doctor 诊断结果（doctor_diagnosis.json——与 wuji doctor --json 使用相同的封装格式，包含主机环境检查和各设备结果，均位于 checks 下）、设备快照和闪存历史记录（找到设备时为 devices/<sn>_<ts>_device.json / _flash.jsonl）、匹配的手部模型校准录制文件，以及清单（manifest.json）。即使未找到日志文件，也会包含快照和诊断结果。
• 校准录制会自动收集：将 ~/.wuji/calibration/recordings/ 中与相同的本地日期范围（含首尾日期）有交集的运行记录复制到 calibration-recordings/<run_id>/ 下。对于没有 ended_at 的部分或旧版运行记录，会按其本地 started_at 日期作为单个时间点进行筛选。
• 录制清单兼容性：新的手部模型运行使用 schema_version: 2 和 calibration_type: "hand_model"；导出也接受旧版 schema 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）不会脱敏，并会原样包含在内——诊断内容涵盖软件版本、操作系统、网络接口数量、设备发现情况和逐设备检查（不包含主机名 / 机器 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，即可查看详细帮助和所有可用选项。