> ## 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 user 管理用户 Profile 并在机器间迁移标定数据

用户 Profile 是某个人标定数据的本地档案。SDK 按 Profile 隔离手部模型标定与触觉模型，因此同一只手套可为每个人保存各自的标定，也能把标定在机器之间迁移。`wuji user` 管理这些 Profile。Profile 以**用户名**为标识。所有子命令都是 `~/.wuji/sdk` 下的本地操作，**不连接设备**。全部子命令支持 `--json`。

## 标定中的 Profile 作用

手部模型标定会写入按 Profile 隔离的 URDF。默认用户无法执行手部模型标定：需先新建并切换到命名 Profile，再运行标定。触觉标定按设备归属，不受此限制。

```bash theme={null}
wuji user create alice --switch   # 新建并立即切换
wuji calib hand-model              # 此时才允许标定
```

## 管理 Profile

```bash theme={null}
wuji user list                    # 列出 Profile，'*' 标记当前
wuji user create alice -d "备注"   # 新建（-d 加描述，不加 --switch 则不切换）
wuji user switch [alice]          # 切换 Profile，或打开终端选择器
wuji user rename alice alice2     # 重命名，标定数据跟随
wuji user delete [alice]          # 选择并删除 Profile 及其全部数据（先确认）
wuji user show [alice]            # 查看某 Profile 的标定（缺省当前）
```

用户名为 1–32 个字母/数字/下划线/连字符，且不得以连字符开头。`list` 用 `*` 标记当前 Profile，把 `Default` 标为「不可标定」，并显示各命名 Profile 的左右手标定状态。`show` 列出左右手手部模型（状态/文件/大小/时间）与按设备 SN 分组的触觉模型。模型文件不全的设备会标出缺失文件，与从未标定的设备区分开。

终端中执行不带名称的 `switch` 会打开 Profile 选择器。不带名称的 `delete` 会打开删除选择器，排除 `Default`、标记当前 Profile，并默认停在 **Cancel operation**。选中 Profile 后，命令会列出待删除内容、提示可先用 `wuji user export` 备份，并在默认选择 **No** 的确认步骤等待操作。非终端环境删除时必须同时提供明确的 Profile 名称和 `--yes`。`Default` 不可删除或重命名。删除当前用户后，当前 Profile 回退为 `Default`。

## 在机器间迁移标定

标定数据——按 Profile 隔离的手部模型 URDF，加上每只手套的触觉模型、触觉参数与最近一次完整触觉 run——打包为单个 `.zip`。

### 导出

```bash theme={null}
wuji user export ./alice.zip      # 写出 .zip
wuji user export ./out-dir/       # 已存在的目录内自动命名 calib_bundle_<name>_<ts>.zip
wuji user export ./alice.zip --force   # 覆盖已存在文件
```

导出始终作用于**当前**用户。目标为目录时，该目录必须已存在，否则返回退出码 1。终端中导出到已有文件时，命令会请求确认，并默认选择 **No**。结构化输出或重定向输出需使用 `--force` 才能覆盖文件。如果当前 Profile 没有标定产物，命令不会生成空 bundle，而是提示先完成标定并返回退出码 1。命名 Profile 可运行 [`wuji calib hand-model`](/docs/wuji-cli/hand-model-calibration) 生成标定产物。`Default` 无法执行手部模型标定，需先新建并切换到命名 Profile，或执行设备级[触觉标定](/docs/wuji-cli/tactile-calibration)。

触觉模型由 `contact.safetensors`、`contact.npz`、`contact.json` 三个文件组成，缺任一文件即不完整，不会打进 bundle。导出清单会把这类模型标为 `skipped` 并列出缺失文件，而不是静默丢弃。当前 Profile 只有不完整的触觉模型时，报错会点名设备 SN 与缺失文件，并引导对这些设备重新运行 [`wuji calib tactile`](/docs/wuji-cli/tactile-calibration)，同样返回退出码 1。

### 导入

```bash theme={null}
wuji user import ./alice.zip --preview             # 仅查看，不改动
wuji user import ./alice.zip                        # 预览后确认
wuji user import ./alice.zip --yes                  # 跳过确认导入
wuji user import ./alice.zip --as bob               # 导入到新建 Profile
```

导入作用于**当前**用户，或用 `--as <name>` 导入到新建 Profile。导入到新 Profile 成功后，该 Profile 自动成为当前用户。终端流程先预览来源用户、bundle 内容和冲突。当前 Profile 存在标定产物冲突且未指定 `--as` 时，可选择覆盖当前 Profile、新建 Profile 或取消。其他情况下，确认目标 Profile 后开始导入。结构化输出或重定向输出需用 `--preview` 只读检查，或用 `--yes` 确认写入。`Default` 无法接收包含手部模型的 bundle。请指定 `--as <name>`，或先创建并切换到命名 Profile 再导入。导入的手部模型会在线热加载，无需重连手套。导入的触觉模型在对应手套已连接时自动重新加载，否则在下次连接时加载。当 bundle 来自不同用户且目标已有标定产物时，原产物会先备份到 `calibration-import-backups/` 再覆盖。空 Profile 不会产生空备份目录。备份会保留到手动删除。

预览与导入清单会如实列出被跳过的触觉模型及原因：bundle 内的模型文件不全、bundle 未携带该设备的模型，或 bundle 带了模型文件但 manifest 未声明。manifest 未声明的产物不会被安装，清单会把它们列出来，不再静默丢弃。

## 自动化调用

`--json` 每条命令输出一个文档，错误输出 `{"error":{"code":…,"message":…}}`。非交互导入使用 `--preview` 只读检查，或使用 `--yes` 确认写入。非交互删除需同时提供明确的 Profile 名称和 `--yes`，不支持 `--preview`。

`create`、`switch`、`rename`、`delete` 的 `--json` 输出固定带 `current_user` 字段，写明命令跑完后当前用的是哪个 Profile，脚本不用再跑一次 `user list` 确认。`rename` 另返回 `previous_name`（改名前的用户名）与 `name`（新名）：

```bash theme={null}
$ wuji user rename alice alice2 --json
{
  "action": "renamed",
  "name": "alice2",
  "previous_name": "alice",
  "current_user": "alice2"
}
```

`show --json` 为不完整的触觉模型输出 `missing_model_files`（缺失文件名列表）。`export`、`import`、`import --preview` 清单里被跳过的组件行带 `reason` 与可选的 `detail`，`detail` 补充缺失文件名等说明。触觉模型的 `reason` 取值：导出清单只出现 `incomplete_model`（模型文件不全），导入与预览清单还可能出现 `not_in_bundle`（bundle 未携带模型）与 `not_declared_in_manifest`（manifest 未声明）。

手部模型组件还可能出现以下 `reason`：

* `legacy_hand_model_ignored`：bundle manifest 版本 `1` 或 `2` 中按设备保存的手部模型不会安装到用户 Profile
* `default_user_hand_model_disabled`：目标为无法保存手部模型的 `Default`

如果 bundle 包含按用户和左右手分别保存的手部模型，且导入目标为 `Default`，CLI 会在写入数据前返回退出码 `5`。

```json theme={null}
// show --json：不完整触觉模型的条目（tactile 数组内）
{
  "sn": "<SN>",
  "calibrated": false,
  "missing_model_files": ["contact.npz", "contact.json"]
}
```

```json theme={null}
// export/import/preview 清单：被跳过的组件行
{
  "name": "tactile.model",
  "device_sn": "<SN>",
  "state": "skipped",
  "reason": "incomplete_model",
  "detail": "missing contact.npz, contact.json"
}
```

退出码细分：

| 退出码（`error.code`） | 含义 |
| - | - |
| 0 | 成功（含切换到当前用户的幂等操作） |
| 1 | 其他运行时错误，包括导出无标定产物的 Profile |
| 2 | 用户名非法 |
| 3 | 用户已存在 |
| 4 | 用户不存在 |
| 5 | Default 保护（删/改 Default、默认用户手部模型标定，或向 Default 导入含手部模型的 bundle） |
| 6 | bundle 文件不存在 |
| 7 | bundle 非法或版本不兼容 |
| 8 | 导出目标已存在（需 `--force`） |
| 9 | 确认时取消 |


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