Metadata-Version: 2.4
Name: jishu-hub
Version: 0.2.4
Summary: jishu Hub CLI for secure dataset and label transfer
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: cryptography>=42

# jishu-hub

安全传输 CLI：在**已授权设备**上上传/下载数据集、标注数据，以及拉取评测报告。

---

## 在其他机器上的使用流程

每台新机器都要由根超管批准一次。密钥在本机生成，**不能**把旧机器的 `~/.jishu` 整包拷过去当「换机」。

### 0. 目标机取机器码 → 根超管录入

无一次性注册码。设备准入由超管按「用户 + 机器码」批准。

1. 在**目标机器**安装 CLI 后执行：

```bash
jishu device-code
```

将 64 位机器码发给管理员（工单 / 消息）。

2. 根超管在 **后台管理 → 用户列表** 点「录入机器」：粘贴机器码、选填备注 → 批准。
3. 管理员告知 **Hub 网关地址**（侧信道，勿写入公开文档）。

设备与批准吊销在 **后台管理 → 设备/Hub**。

### 1. 目标机器：环境

- Python ≥ 3.10
- 能访问 Hub 网关（HTTPS；生产环境通常要求客户端证书 / mTLS，由网关终止）
- 安装 CLI：

```bash
pip install jishu-hub

# 开发安装
# pip install -e /path/to/data_management/cli
```

可选：固定网关环境变量：

```bash
export JISHU_API_URL="https://<hub-host>"   # Linux/macOS
# Windows PowerShell: $env:JISHU_API_URL="https://<hub-host>"
```

### 2. 登录（首次自动激活本机）

管理员已录入本机机器码后：

```bash
jishu login --gateway https://<hub-host> --username <平台用户名>
# 会提示密码；首次会自动 claim 设备证书，之后只需 login
```

成功后本机会生成：

| 位置 | 内容 |
|---|---|
| `~/.jishu/`（或 `JISHU_HOME`） | 网关、device_id、证书指纹等 |
| 本机密钥材料 | 私钥 + 设备证书（私钥不出机） |

验证：

```bash
jishu --version
jishu whoami
```

### 3. 常用命令

```bash
# 上传到已有版本
jishu dataset upload ./my_data --id <dataset-id> --version <ver>

# 可选：写入版本下子目录（--dir 后为相对路径）
jishu dataset upload ./my_data --id <dataset-id> --version <ver> --dir <subdir>

# 版本尚不存在时需加 --create
jishu dataset upload ./my_data --id <dataset-id> --version <ver> --create

# 整版本下载
jishu dataset download --id <dataset-id> --version <ver> --out ./download

# 只下载指定文件（逗号分隔相对路径）
jishu dataset download --id <dataset-id> --version <ver> --file path/a.jpg,path/b.jpg --out ./download

jishu label upload <标注目录> --project <id>
jishu eval reports list
```

`--file` 与 `--paths` 同义。

上传/下载权限由平台账号 ACL 决定，与网页一致。

### 4. 换机 / 吊销

- 换机：新机 `device-code` → 超管重新录入 → 新机 `login`
- 吊销：超管在 **设备/Hub** 吊销批准或设备后，该机无法再 login / 传输
