> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 日志导出

> 用 wuji logs 一键导出日志支持包发给支持人员，快速定位设备问题

设备行为异常需要技术支持时，用 `wuji logs export` 把主机上的 Wuji 日志与诊断信息打包成一个 ZIP 支持包，直接发给支持人员。

## 导出并发送支持包

```bash theme={null}
wuji logs export                     # 导出最近 1 天日志
wuji logs export --days 7            # 覆盖最近 7 天
wuji logs export -o support.zip      # 指定输出文件
```

默认在当前目录生成带时间戳的 `wuji-logs-*.zip`。将其与问题描述（现象、发生时间和设备序列号）一并发送给支持人员。

| 参数 | 说明 |
| - | - |
| `--days <N>` | 导出最近 N 天的日志，默认 1 |
| `--source <来源>` | 按来源筛选文本日志，可选 `sdk`、`studio`、`stderr`，逗号分隔，默认全部 |
| `--with-dump` | 附带 `device_*.bin` 设备通信 dump 文件（二进制原文） |
| `-o, --output <路径>` | 输出文件路径 |

支持包内容包括：

* **文本日志**：选定范围内的软件日志
* **主机与设备诊断**：主机快照、健康诊断结果，以及设备诊断快照与 Flash 历史（按设备序列号区分）
* **手部模型标定录制**：同一日期范围内的标定录制数据
* **manifest.json**：本次导出的文件清单与摘要

以上内容都默认包含，不需要额外参数。

`wuji logs export` 支持导出采用当前格式或历史格式的手部模型标定录制，并原样保留每次录制的 `manifest.json` 文件。

打包前自动对文本日志脱敏用户名、主机名等个人信息，设备序列号与固件版本保留，便于支持人员定位问题。`--with-dump` 附带的通信 dump 与设备侧诊断数据按原样打包。标定录制的 `.mcap` 是原始动作数据。

范围内没有日志文件时导出仍会完成，摘要显示 `Logs: skipped (no log files exported)`。如果设备诊断、日志导出、标定录制导出、设备快照或 Flash 日志采集失败，命令会尽可能生成支持包，返回退出码 1，并在摘要中标记各项失败。

## 采集设备诊断快照

仅需设备侧诊断数据而无需导出完整支持包时，使用 `wuji logs dump`。命令当前支持 Wuji Hand 2，后续会扩展到更多设备类型。采集内容包括设备身份、故障与状态、母线电压与温度、通信诊断以及 Flash KV 历史：

```bash theme={null}
wuji logs dump                       # 扫描并采集全部设备
wuji logs dump --sn <SN>             # 只采集指定设备
wuji logs dump -o /tmp/dump          # 指定输出目录
```

| 参数 | 说明 |
| - | - |
| `--sn <SN>` | 按序列号指定设备 |
| `--address <地址>` | 按地址指定设备 |
| `--handedness <left\|right>` | 按左右手指定设备 |
| `-o, --output <目录>` | 输出目录路径 |

每台设备产出 `<sn>_<时间戳>_device.json`（快照）与 `<sn>_<时间戳>_flash.jsonl`（Flash 历史）。单个字段采集失败不中断整体流程，失败原因记入快照的 `failures` 列表。未安装或离线的触觉模组会被跳过，不计入失败。在线触觉模组的型号查询失败会计入失败项。任一设备失败、快照含字段采集失败或未生成 Flash 历史时，命令以退出码 1 结束。未扫描到任何设备时命令报错退出。扫描模式下遇到不支持 dump 的设备类型记为跳过，不计入失败，显式指定这类设备则记为失败。

## 查看日志目录

```bash theme={null}
wuji logs path
```

显示日志目录路径，默认为 `~/.wuji/logs`，SDK 等组件的运行日志都存放在该目录。

## 列出日志文件

```bash theme={null}
wuji logs list                       # 列出全部日志文件
wuji logs list --days 7              # 只看最近 7 天
wuji logs list --source sdk,studio   # 按来源筛选
```

| 参数 | 说明 |
| - | - |
| `--days <N>` | 只列最近 N 天的日志，默认全部时间范围 |
| `--source <来源>` | 按来源筛选，取值同 `wuji logs export` |

## 结构化输出

四个子命令都支持全局参数 `--json`（格式化 JSON）与 `--jsonl`（每行一条紧凑 JSON），便于脚本解析。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.