Metadata-Version: 2.4
Name: artdam-cli
Version: 0.3.4
Summary: ArtDAM 数字资产管理平台命令行工具
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# artdam-cli

ArtDAM 数字资产管理平台命令行工具，支持所有主流 AI Agent工具接入

## 安装

```bash
uv tool install artdam-cli
```

## 更新

```bash
uv tool install artdam-cli@latest
```

## 快速开始

```bash
# 登录（首次使用，浏览器 SSO 授权）
artdam login

# 搜索资产
artdam search "关键词" --project 1

# 查看资产详情
artdam get 123

# 下载资产
artdam download 123 --out ./downloads
```

## 命令说明

### 查询命令（viewer 及以上）

#### `artdam login`

登录 ArtDAM，保存 token 到本地 `~/.artdam/config.json`。

```bash
artdam login
```

#### `artdam search`

搜索资产，返回匹配列表。默认只取首页（`--limit` 条）；加 `--all` 自动翻页取全部结果
（Agent 场景推荐，避免结果被截断）。`--all` 最多返回 1000 条，超出会提示用更精确的关键词或
`--ext` / `--folder` 收窄，避免在几万条资产上卡死。

```bash
artdam search "头盔" --project 1
artdam search "头盔" --project 1 --limit 50
artdam search "头盔" --project 1 --all          # 自动翻页，取全部匹配
artdam search "头盔" --project 1 --all --json   # 全量 JSON 输出（AI Agent 用）
artdam search "头盔" --project 1 --ext jpg       # 按扩展名过滤
artdam search "头盔" --project 1 --ext jpg,png   # 多个扩展名
artdam search "头盔" --project 1 --folder 10
```

| 参数 | 说明 |
|---|---|
| `KEYWORD` | 搜索关键词 |
| `-p, --project` | 项目 ID（必填） |
| `-n, --limit` | 返回数量上限，默认 20（不与 `--all` 共用） |
| `--all` | 自动翻页取全部匹配结果（最多 1000 条） |
| `-e, --ext` | 按文件扩展名过滤，逗号分隔，如 `jpg,png` |
| `--folder` | 限定文件夹 ID |
| `--json` | 输出原始 JSON |

#### `artdam get`

查看单个资产详情（含预览链接）。

```bash
artdam get 123
artdam get 123 --json   # 输出原始 JSON（AI Agent 用）
```

#### `artdam download`

下载资产文件到本地。

```bash
artdam download 123
artdam download 123 --out ./downloads
```

#### `artdam tags`

列出项目标签。

```bash
artdam tags --project 1
artdam tags --project 1 --search "角色"
artdam tags --project 1 --json
```

#### `artdam folders`

查看文件夹结构。

```bash
artdam folders --project 1
artdam folders --project 1 --json
```

### 资产管理（member 及以上）

#### `artdam upload`

上传文件到指定项目和文件夹。采用分块上传，支持大文件（最大 10GB），带进度条；
上传前按内容计算 SHA-256，库中已有相同文件则**秒传**（直接复用，不重复传输）。
单个分块遇到网络抖动（超时 / 5xx）会自动重试，中断时清理服务端会话。

```bash
artdam upload ./image.jpg --project 1
artdam upload ./image.jpg --project 1 --folder 10
artdam upload ./big_scene.zip --project 1   # 大文件分块 + 进度条
```

#### `artdam update`

更新资产信息（可同时传多个选项）。

```bash
artdam update 123 --name "新文件名"
artdam update 123 --description "新描述"
artdam update 123 --folder 10
```

#### `artdam delete`

软删除资产（可通过 `restore` 恢复）。

```bash
artdam delete 123
```

#### `artdam restore`

恢复已删除的资产。

```bash
artdam restore 123
```

### 标签管理（member 及以上）

```bash
# 给资产添加标签
artdam tag add 123 5

# 从资产移除标签
artdam tag remove 123 5

# 创建新标签
artdam tag create "标签名" --project 1
```

### 文件夹管理（member 及以上）

```bash
# 创建文件夹
artdam folder create "文件夹名" --project 1
artdam folder create "子文件夹" --project 1 --parent 10

# 删除文件夹
artdam folder delete 10
```

### 互动操作（member 及以上）

```bash
# 评论
artdam comment 123 "评论内容"

# 评分（1-5 星）
artdam rate 123 4

# 收藏 / 取消收藏
artdam favorite 123
artdam favorite 123 --remove
```

## AI Agent 使用指南

所有查询命令支持 `--json` 输出原始 JSON，适合 Agent 解析：

```bash
artdam search "安妮" --project 1 --json
artdam get 123 --json
artdam tags --project 1 --json
artdam folders --project 1 --json
```

### 典型 Agent 工作流

```bash
# 1. 登录（浏览器 SSO 授权）
artdam login

# 2. 搜索 → 确认 → 下载
artdam search "头盔" --project 1 --json
artdam get 50707 --json
artdam download 50707 --out ./assets

# 3. 搜索 → 批量打标签
artdam search "安妮" --project 1 --json
artdam tag add 50707 5
artdam tag add 50708 5

# 4. 上传并更新描述
artdam upload ./new_asset.jpg --project 1 --folder 10
artdam update <asset_id> --description "AI 生成的场景描述"
```

## 注意事项

- `--project` 参数为**数字 ID**，不是项目名称
- `--json` 返回原始 JSON，适合程序解析
- token 保存在 `~/.artdam/config.json`，登录一次长期有效
- `artdam delete` 是软删除，可用 `artdam restore` 恢复

## 配置文件

登录信息保存在 `~/.artdam/config.json`：

```json
{
  "base_url": "https://artdam.xindong.com",
  "token": "eyJ..."
}
```
