wuji-cli-user

用户配置是存储在 ~/.wuji/sdk 中、包含单个人校准数据的本地记录。wuji user 用于管理这些配置，并在不同机器间迁移校准包。所有子命令都是本地操作（注册表 + 文件，不连接设备），且支持 --json。

概念说明

• 配置以其名称作为标识——这是用户唯一能看到的标识（不关联 OS 账户；SDK 的内部 ID 不会公开）。
• 校准按配置划分：手部模型按用户 + 手侧划分；触觉校准按设备 SN划分。
• Default 用户无法存储已校准的手部模型。必须先激活一个命名配置，wuji calib hand-model 才会运行。触觉校准与设备相关，即使当前激活的是 Default，也可以存储、检查、导出或导入触觉校准。
• 无状态且仅在本地运行：无持久连接，不涉及设备。

命令

命令	用途
wuji user list	列出配置；当前配置标记为 *，Default 标记为 (hand model not calibratable)，每行显示左手/右手模型的校准状态
wuji user show [name]	显示配置的描述、手部模型（状态/文件/大小/时间）以及触觉校准产物（按 SN 列出）；默认显示当前配置
wuji user create <name> [-d|--description <text>] [--switch]	创建命名配置，可选填写描述（除非指定 --switch，否则不会切换）
wuji user switch [name]	将某个配置设为当前配置；在 Human TTY 中省略名称时会打开配置选择器
wuji user rename <old> <new>	重命名配置；校准数据会随之保留
wuji user delete [name] [--yes]	删除配置及其所有校准数据；在 Human TTY 中省略名称时会打开配置选择器
wuji user export <path> [--force]	将当前配置的校准包导出为 .zip
wuji user import <path> [--preview] [-y|--yes] [--as <name>]	将校准包导入当前配置（或新配置）

在任意子命令后添加 --help 可查看详情。

安全（执行破坏性操作前请阅读）

• delete 不可撤销，并会移除配置文件的所有校准数据。在 Human TTY 中，省略名称会打开选择器，其中不包含 Default，会标记当前配置文件，并默认选择 Cancel operation；选择后，CLI 会打印将要移除的内容，建议使用 wuji user export 进行备份，并询问是否确认，默认选择 No。不要代替用户选择配置文件。除非用户明确授权删除该特定配置文件，否则不要传入 --yes；--yes 要求必须提供名称。不能删除 Default。
• import 会覆盖目标配置文件中的文件。先使用 --preview 预览（或查看交互式 Cliclack 预览），并在继续前转达来源用户、捆绑包版本、内容和任何冲突。在 Human TTY 模式下，使用固定页脚菜单选择覆盖当前配置文件、创建新配置文件或取消；--as <name> 可预先选择创建新配置文件的路径。当捆绑包来自不同用户且目标已有文件时，CLI 会在覆盖前将其备份到 calibration-import-backups/。
• 包含手部模型的捆绑包不能导入 Default：Default 无法存放手部模型文件，因此 CLI 会拒绝导入（退出码为 5），而不是静默丢弃模型后报告成功。请使用 --as <name> 导入到命名配置文件，或先运行 wuji user create <name> --switch。仅包含触觉数据的捆绑包仍可正常导入到 Default。
• 导入不是原子操作。 如果导入中途失败，配置文件可能会同时包含新文件和旧文件。CLI 会说明这一点，指出已创建备份时的备份目录，并告知用户使用 wuji user show <name> 进行验证。请转达此恢复方式，不要盲目重试。
• 非交互模式需要明确同意：在 --json/--jsonl 模式或没有 TTY 时，使用 --preview 查看只读导入预览，或使用 -y/--yes 应用导入；delete 必须同时提供明确的配置文件名称和 --yes。只有在确认用户意图后才能添加确认标志，绝不能默认添加。
• export 绝不会静默覆盖：在 Human TTY 模式下，导出到现有文件时会询问确认，默认选择 No；非交互模式或结构化输出仍需使用 --force。目标为目录且自动生成的名称发生冲突时也适用此规则。导出没有校准数据的配置文件会失败，并提示用户先完成校准，不会写入任何内容。
• Default 受到保护：不能删除或重命名。删除当前配置文件会将当前用户重置为 Default（CLI 会报告此情况）。
• 绝不要代替用户在多个配置文件中进行选择。在 Human TTY 中，不带名称运行 wuji user switch 会打开包含 Default 的选择器，标记当前配置文件，并默认选择 Cancel operation；应让用户自行选择。在 TTY 外，请提供用户明确指定的配置文件名称。如果找不到配置文件名称，请运行 wuji user list，转达可用配置文件，并询问要使用哪一个。

校准工作流

首次使用或默认用户流程：

wuji user create alice -d "Left-hand operator" --switch    # named profile is now current
wuji calib hand-model               # calibration is allowed

如果手部模型校准提示默认用户指引（先执行 create / switch），请创建并切换到命名配置文件，然后重试。触觉校准不需要命名配置文件。开始任一校准工作流前都必须获得确认（请参阅 wuji-cli-calib 技能）。

退出代码和 JSON

代码	含义
0	成功（包括切换到当前配置文件时未执行任何操作）
2	用户名无效
3	用户已存在
4	未找到用户
5	默认用户保护（删除/重命名 Default，或以默认用户身份运行手部模型校准）
6	未找到捆绑文件
7	捆绑文件无效或版本不兼容
8	导出目标已存在（使用 --force）
9	在确认时取消

使用 --json/--jsonl 时，成功会为每条命令输出一个文档；出错时会输出 {"error":{"code":N,"message":...}}。请根据 code（以及进程退出代码）进行分支判断，而不要解析消息文本。

create、switch、rename 和 delete 都会报告 current_user——操作后的活动配置文件，无论该操作是否更改了它。请直接从命令自身的输出中读取，而不要再调用 list --json；该字段始终存在，因此无需判断“该操作是否影响了我”。rename 还会报告 previous_name，以便脚本确认刚刚重命名了哪个配置文件。

示例

wuji user list --json                              # Inspect profiles + calibration state
wuji user create alice --description "Left-hand operator" --switch  # Create and activate a profile
wuji user show --json                              # Current profile's artifacts
wuji user export ./alice.zip                       # Export current profile
wuji user import ./alice.zip --preview             # Inspect a bundle without importing
wuji user import ./alice.zip                       # Preview, then confirm import
wuji user import ./alice.zip --as bob               # Import into a fresh profile