# OMX 数据上传说明（给 Agent 读）

你在帮同事把数据上传到公司的阿里云 OSS（深圳，桶 `omx4dvdata`，根目录 `omniphysx/`）。上传必须通过本站的命令行工具 `omx_upload.py` 完成：文件直接传到 OSS，站上会自动记下谁、何时、传了什么、大小、sha256 和备注。

- 站点：https://omx-oss.pages.dev（人也可以在网页上浏览、上传、查记录）
- 工具下载：https://omx-oss.pages.dev/agent/omx_upload.py（只依赖 Python 3.8+ 标准库）

## 准备

1. 下载工具：`curl -fsSLO https://omx-oss.pages.dev/agent/omx_upload.py`
2. 令牌：每位同事有自己的个人令牌（形如 `omx_…`，向管理员要）。通过环境变量 `OMX_OSS_TOKEN` 提供。
   - **不要**把令牌写进代码、提交到 git、贴进聊天或打印到输出里。
   - 如果环境变量里没有令牌，停下来请同事自己设置，不要猜，也不要去别处找。
3. 用 `python3 omx_upload.py whoami` 确认登录的是这位同事本人。

## 上传流程（每次都按顺序做）

1. **弄清楚要传什么**：本地路径、传到哪个云端目录、这批数据是什么（用于 `--note`）。有任何一项不确定，先问同事。
2. **看一眼云端目录**：`python3 omx_upload.py ls <目录>`，确认目标位置对、不会跟已有数据混在一起。
3. **先做 dry-run**：`python3 omx_upload.py upload <本地路径> <云端目录> --dry-run`。把计划（文件数、总大小、目标路径）展示给同事，**得到同意再正式上传**。
4. **正式上传**：`python3 omx_upload.py upload <本地路径> <云端目录> --note "<说明>" [--batch <批次名>]`
5. **核对**：命令最后打印「完成：{'done': N}」。再用 `python3 omx_upload.py records --mine --days 1` 确认记录都是 `done`。
6. **向同事汇报**：传了多少文件、多大、云端目录、有没有跳过或失败。失败的原样报告错误信息，不要隐瞒或自行改路径重试。

## 规则

- **目录命名**：只能用英文字母、数字、`.` `_` `-` 和 `/`，不能有中文和空格。建议格式 `<数据或项目英文名>_<YYYYMMDD>/...`，例如 `hand_grasp_test_20261109/session01/`。不要往别人已有的数据集目录里塞文件，除非同事明确要求。
- **不会覆盖**：云端已有同名文件时，服务端直接拒绝，工具会报 `exists`。这时如实告诉同事，**不要**改名绕过。只有同事确认这是另一份数据时，才换一个新目录上传。
- **不能删除**：本工具和网页都没有删除功能。传错了要告诉同事，由管理员处理。
- **`--note` 必填**：写清楚是什么数据、怎么来的、给谁用，例如「11-09 手部抓取测试 3 段，Rig 218 采集，给标注组」。
- **不要上传**：密钥、令牌、`.env`、个人隐私资料、与工作无关的文件。目录里以 `.` 开头的隐藏文件会被自动跳过。
- 大文件会自动分块并行上传，单块失败会自动重试。整份失败时工具会取消这次上传，并在记录里标成 `aborted`。网络恢复后重新运行同一条命令即可，已经成功的文件会报 `exists`（内容相同），可以忽略。
- 每次运行会在当前目录追加一份本地明细 `omx_upload_log.jsonl`。

## 其他命令

- 列目录：`python3 omx_upload.py ls hand_grasp_test_20261109/`
- 查记录：`python3 omx_upload.py records --days 7`（加 `--mine` 只看自己的）
- 生成下载链接（最长 7 天）：`python3 omx_upload.py link <云端文件路径> --days 7`。链接拿到就能下载，只发给需要的人。