trailsnap-cli 0.3.8__tar.gz → 0.3.10__tar.gz

trailsnap_cli-0.3.10/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: trailsnap-cli
+Version: 0.3.10
+Summary: TrailSnap Command Line Interface
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# TrailSnap CLI 命令说明书
+
+本文档详细说明 TrailSnap CLI 命令行工具的所有可用命令、参数用法、功能描述及使用示例，适用于快速上手操作。命令结构遵循「主命令 + 子命令 + 参数」。
+
+核心说明：所有命令需在终端执行，格式统一为 `trailsnap <command> <subcommand> [options]`。涉及 API 交互的命令（如 photos、locations 等）需先通过 `config set` 配置 API 地址和 Token，否则会直接报错并退出。
+
+## 输出格式参数
+
+所有支持数据输出的命令均支持 `--format` 参数，可选值：
+
+- `--format json`（默认）：完整 JSON 响应
+- `--format pretty`：人性化格式输出，树状结构展示
+- `--format table`：易读表格格式
+- `--format ndjson`：换行分隔 JSON（适合管道处理）
+- `--format csv`：逗号分隔值（适合导入 Excel）
+
+# 一、基础命令
+
+## 1.1 help - 显示帮助信息
+
+「功能」：显示所有可用命令、命令结构及各命令的核心参数，快速查阅命令用法。
+「格式」：`--help`
+「示例」：
+```bash
+trailsnap --help
+```
+
+# 二、配置命令
+
+## 2.1 config set - 配置API URL和Token
+
+「功能」：配置CLI工具与后端API的连接信息，包括API基础地址和Bearer凭证Token，是所有API交互类命令的前置操作。
+
+「格式」：`config set --url API地址 --token API凭证`
+
+「参数说明」：
+
+- `--url`（必填）：API基础地址，格式为http/https开头，例如：http://localhost:8000
+
+- `--token`（必填）：API访问凭证（Bearer Token），用于身份验证，需从后端获取。
+
+「示例」：
+
+```bash
+trailsnap config set --url http://localhost:8000 --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+「输出说明」：配置成功后会输出配置文件保存路径（写入同目录 `.env`），例如：`配置已保存到 .../.env`。
+
+# 三、照片管理命令
+
+## 3.1 photos - 照片管理主命令
+
+「功能」：包含照片列表查询、单张照片详情获取、照片删除三个核心子命令，所有子命令需先完成API配置。
+
+### 3.1.1 photos list - 查询照片列表
+
+「功能」：查询照片列表，支持分页与按相册/地点/设备信息过滤。返回结果为简化字段集合。
+
+「格式」：`photos list [--skip N] [--limit N] [--album-id 相册ID] [--city 城市] [--province 省份] [--make 品牌] [--model 型号] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」（支持组合筛选）：
+
+- `--skip`：跳过 N 张照片（默认 0）
+- `--limit`：限制返回 N 张照片（默认 10）
+- `--order_by`：排序字段，默认按值得回忆评分排序，可选值：quality_score（画面质量评分）,memory_score（值得回忆评分）,photo_time（拍摄时间）
+- `--image-type`：按图片类型过滤照片，多个类型用逗号分隔，可选值：Camera（手机或相机拍摄）、Screenshot（截图）、Other（未知的其他类型）
+- `--start-time`：按开始时间过滤照片，格式为 YYYY-MM-DD HH:MM:SS
+- `--end-time`：按结束时间过滤照片，格式为 YYYY-MM-DD HH:MM:SS
+- `--album-id`：按相册 ID 过滤，多个 ID 用逗号分隔
+- `--people-id`：按人物 ID 过滤，多个 ID 用逗号分隔
+- `--tag-id`：按标签 ID 过滤，多个 ID 用逗号分隔
+- `--city`：按城市过滤，多个城市用逗号分隔（全称）
+- `--province`：按省份过滤，多个省份用逗号分隔（全称）
+- `--scene`：按景区过滤，多个景区用逗号分隔
+- `--make`：按相机品牌过滤，多个品牌用逗号分隔
+- `--model`：按相机型号过滤，多个型号用逗号分隔
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 数组，每项包含 `id`、`filename`、`file_type`、`photo_time`
+
+「示例」：
+
+```bash
+trailsnap photos list --limit 20 --city 西安市,上海市
+trailsnap photos list --limit 20 --format pretty
+```
+
+### 3.1.2 photos info - 获取单张照片信息
+
+「功能」：获取指定 ID 照片的元数据信息与内容描述信息。
+
+「格式」：`photos info --photo-id 照片ID [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--photo-id`（必填）：照片唯一ID，可通过photos list命令获取。
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 对象，包含：
+
+- `address`：照片详细拍摄地址（精确到街道）
+- `albums`：所属相册信息
+- `tags`：标签信息
+- `faces_identities`：人物（面部识别身份）信息
+- `description`：照片内容描述信息
+  - `description`：照片画面描述（若无则为空字符串）
+  - `memory_score`：照片值得回忆分数（0-100，100为值得回忆）
+  - `quality_score`：照片质量分数（0-100，100为最高质量）
+  - `narrative`：照片一句话文案（若无则为空字符串）
+
+「示例」：
+
+```bash
+trailsnap photos info --photo-id 10001
+trailsnap photos info --photo-id 10001 --format pretty
+```
+
+### 3.1.3 photos delete - 删除单张照片
+
+「功能」：删除指定ID的照片，删除后不可恢复（需谨慎操作）。
+
+「格式」：`photos delete --photo-id 照片ID`
+
+「参数说明」：
+
+- `--photo-id`（必填）：需删除的照片唯一ID。
+
+「示例」：
+
+```bash
+trailsnap photos delete --photo-id 10001
+```
+
+「输出说明」：删除成功提示 `照片 <photo-id> 删除成功`，失败提示 `照片删除失败或不存在`。
+
+# 四、分类标签命令
+
+## 4.1 tags list - 查询分类标签
+
+「功能」：查询分类标签列表，支持分页。
+
+「格式」：`tags list [--skip N] [--limit N] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--skip`：跳过 N 个记录（默认 0）
+- `--limit`：限制返回 N 个记录（默认 100）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「示例」：
+
+```bash
+trailsnap tags list
+trailsnap tags list --format table
+```
+
+「输出说明」：输出 JSON 数组，每项包含 `id`、`name`（tag_name）、`count`。
+
+# 五、相册管理命令
+
+## 5.1 albums list - 查询相册列表
+
+「功能」：查询相册列表，支持分页。
+
+「格式」：`albums list [--skip N] [--limit N] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--skip`：跳过 N 个相册（默认 0）
+- `--limit`：限制返回 N 个相册（默认 100）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「输出说明」：输出 JSON 数组，每项包含 `id`、`name`、`count`（num_photos）、`description`、`condition`、`type`。
+
+「示例」：
+
+```bash
+trailsnap albums list
+trailsnap albums list --format pretty
+```
+
+# 六、位置相关命令
+
+## 6.1 locations - 位置查询主命令
+
+「功能」：包含位置分布查询、足迹时间轴查询两个子命令，基于照片的GPS信息统计。
+
+### 6.1.1 locations list - 查询位置分布
+
+「功能」：查询位置分布，不含时间信息（地点名、照片数量）。支持按层级分组与日期范围过滤。
+
+「格式」：`locations list [--level city|province|district|scene] [--skip N] [--limit N] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--level`：分组级别（默认 city，可选：city、province、district、scene）
+- `--skip`：跳过 N 个位置（默认 0）
+- `--limit`：限制返回 N 个位置（默认 100）
+- `--start-date`：可选，开始日期（YYYY-MM-DD）
+- `--end-date`：可选，结束日期（YYYY-MM-DD）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 数组，每项包含 `name`、`count`
+
+「示例」：
+
+```bash
+trailsnap locations list
+trailsnap locations list --format table
+```
+
+### 6.1.2 locations timeline - 查询足迹时间轴
+
+「功能」：查询足迹时间轴列表，按时间段和地点分组（开始日期、结束日期、地点名、照片数量）。支持按层级分组与日期范围过滤。
+
+「格式」：`locations timeline [--level city|province|district|scene] [--skip N] [--limit N] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--level`：分组级别（默认 city，可选：city、province、district、scene）
+- `--skip`：跳过 N 个位置（默认 0）
+- `--limit`：限制返回 N 个位置（默认 100）
+- `--start-date`：可选，开始日期（YYYY-MM-DD）
+- `--end-date`：可选，结束日期（YYYY-MM-DD）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 数组，每项包含 `startDate`、`endDate`、`locationName`、`count`
+
+「示例」：
+
+```bash
+trailsnap locations timeline --level city --start-date 2025-01-01 --end-date 2025-06-30
+trailsnap locations timeline --format csv
+```
+
+# 七、人物识别命令
+
+## 7.1 people list - 查询已识别的人物/面孔
+
+「功能」：查询人物（面部识别身份）列表，支持按类型过滤。
+
+「格式」：`people list [--limit N] [--types named,unnamed,hidden] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--limit`：返回的记录数（默认 100）
+- `--types`：查询类型，逗号分隔，默认 `named`；可选值：`named`、`unnamed`、`hidden`
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「输出说明」：输出 JSON 数组，每项包含 `id`、`name`（identity_name）、`tags`、`description`、`face_count`。
+
+「示例」：
+
+```bash
+trailsnap people list
+trailsnap people list --format ndjson
+```
+
+# 八、存储文件夹命令
+
+## 8.1 folders list - 查询挂载的存储文件夹列表
+
+「功能」：查询系统中已挂载的存储目录信息。
+
+「格式」：`folders list [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「输出说明」：直接输出后端接口返回的 JSON（字段结构以服务端为准）。
+
+「示例」：
+
+```bash
+trailsnap folders list
+trailsnap folders list --format pretty
+```
+
+# 九、媒体文件命令
+
+## 9.1 medias get - 获取照片的媒体文件或URL
+
+「功能」：获取指定照片的媒体内容/访问地址，支持输出 URL、base64、或保存到本地文件。
+
+「格式」：`medias get [--photo-id 照片ID] [--size small|medium|large] [--format url|base64|file] [--output 文件路径]`
+
+「参数说明」：
+
+- `--photo-id`：照片 ID（默认 100）
+- `--size`：照片质量/尺寸（默认 medium，可选：small、medium、large）
+- `--format`：输出格式（默认 url（可以把链接插入到HTML页面或者markdown文件），可选：url、base64、file）
+- `--output`：输出文件路径（仅当 `--format file` 时必填）
+
+「示例」：
+
+```bash
+# 输出 URL（large 输出原图URL，small/medium 输出缩略图URL）
+trailsnap medias get --photo-id 10001 --format url --size large
+
+# base64 输出（缩略图base64编码）
+trailsnap medias get --photo-id 10001 --format base64 --size medium
+
+# 保存到本地文件
+trailsnap medias get --photo-id 10001 --format file --output .\photo_10001.jpg
+```
+
+# 十、注意事项
+
+- 所有涉及 API 交互的命令（photos、locations、people 等），必须先执行 `config set` 配置 API URL 和 Token，否则会提示 `错误: API URL 和 Token 未配置，请先运行 'config' 命令。` 并退出。
+
+- 所有命令可通过 `--help` 查询详细用法，若参数错误，会提示具体错误信息及正确格式。

trailsnap_cli-0.3.10/README.md

@@ -0,0 +1,313 @@
+# TrailSnap CLI 命令说明书
+
+本文档详细说明 TrailSnap CLI 命令行工具的所有可用命令、参数用法、功能描述及使用示例，适用于快速上手操作。命令结构遵循「主命令 + 子命令 + 参数」。
+
+核心说明：所有命令需在终端执行，格式统一为 `trailsnap <command> <subcommand> [options]`。涉及 API 交互的命令（如 photos、locations 等）需先通过 `config set` 配置 API 地址和 Token，否则会直接报错并退出。
+
+## 输出格式参数
+
+所有支持数据输出的命令均支持 `--format` 参数，可选值：
+
+- `--format json`（默认）：完整 JSON 响应
+- `--format pretty`：人性化格式输出，树状结构展示
+- `--format table`：易读表格格式
+- `--format ndjson`：换行分隔 JSON（适合管道处理）
+- `--format csv`：逗号分隔值（适合导入 Excel）
+
+# 一、基础命令
+
+## 1.1 help - 显示帮助信息
+
+「功能」：显示所有可用命令、命令结构及各命令的核心参数，快速查阅命令用法。
+「格式」：`--help`
+「示例」：
+```bash
+trailsnap --help
+```
+
+# 二、配置命令
+
+## 2.1 config set - 配置API URL和Token
+
+「功能」：配置CLI工具与后端API的连接信息，包括API基础地址和Bearer凭证Token，是所有API交互类命令的前置操作。
+
+「格式」：`config set --url API地址 --token API凭证`
+
+「参数说明」：
+
+- `--url`（必填）：API基础地址，格式为http/https开头，例如：http://localhost:8000
+
+- `--token`（必填）：API访问凭证（Bearer Token），用于身份验证，需从后端获取。
+
+「示例」：
+
+```bash
+trailsnap config set --url http://localhost:8000 --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+「输出说明」：配置成功后会输出配置文件保存路径（写入同目录 `.env`），例如：`配置已保存到 .../.env`。
+
+# 三、照片管理命令
+
+## 3.1 photos - 照片管理主命令
+
+「功能」：包含照片列表查询、单张照片详情获取、照片删除三个核心子命令，所有子命令需先完成API配置。
+
+### 3.1.1 photos list - 查询照片列表
+
+「功能」：查询照片列表，支持分页与按相册/地点/设备信息过滤。返回结果为简化字段集合。
+
+「格式」：`photos list [--skip N] [--limit N] [--album-id 相册ID] [--city 城市] [--province 省份] [--make 品牌] [--model 型号] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」（支持组合筛选）：
+
+- `--skip`：跳过 N 张照片（默认 0）
+- `--limit`：限制返回 N 张照片（默认 10）
+- `--order_by`：排序字段，默认按值得回忆评分排序，可选值：quality_score（画面质量评分）,memory_score（值得回忆评分）,photo_time（拍摄时间）
+- `--image-type`：按图片类型过滤照片，多个类型用逗号分隔，可选值：Camera（手机或相机拍摄）、Screenshot（截图）、Other（未知的其他类型）
+- `--start-time`：按开始时间过滤照片，格式为 YYYY-MM-DD HH:MM:SS
+- `--end-time`：按结束时间过滤照片，格式为 YYYY-MM-DD HH:MM:SS
+- `--album-id`：按相册 ID 过滤，多个 ID 用逗号分隔
+- `--people-id`：按人物 ID 过滤，多个 ID 用逗号分隔
+- `--tag-id`：按标签 ID 过滤，多个 ID 用逗号分隔
+- `--city`：按城市过滤，多个城市用逗号分隔（全称）
+- `--province`：按省份过滤，多个省份用逗号分隔（全称）
+- `--scene`：按景区过滤，多个景区用逗号分隔
+- `--make`：按相机品牌过滤，多个品牌用逗号分隔
+- `--model`：按相机型号过滤，多个型号用逗号分隔
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 数组，每项包含 `id`、`filename`、`file_type`、`photo_time`
+
+「示例」：
+
+```bash
+trailsnap photos list --limit 20 --city 西安市,上海市
+trailsnap photos list --limit 20 --format pretty
+```
+
+### 3.1.2 photos info - 获取单张照片信息
+
+「功能」：获取指定 ID 照片的元数据信息与内容描述信息。
+
+「格式」：`photos info --photo-id 照片ID [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--photo-id`（必填）：照片唯一ID，可通过photos list命令获取。
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 对象，包含：
+
+- `address`：照片详细拍摄地址（精确到街道）
+- `albums`：所属相册信息
+- `tags`：标签信息
+- `faces_identities`：人物（面部识别身份）信息
+- `description`：照片内容描述信息
+  - `description`：照片画面描述（若无则为空字符串）
+  - `memory_score`：照片值得回忆分数（0-100，100为值得回忆）
+  - `quality_score`：照片质量分数（0-100，100为最高质量）
+  - `narrative`：照片一句话文案（若无则为空字符串）
+
+「示例」：
+
+```bash
+trailsnap photos info --photo-id 10001
+trailsnap photos info --photo-id 10001 --format pretty
+```
+
+### 3.1.3 photos delete - 删除单张照片
+
+「功能」：删除指定ID的照片，删除后不可恢复（需谨慎操作）。
+
+「格式」：`photos delete --photo-id 照片ID`
+
+「参数说明」：
+
+- `--photo-id`（必填）：需删除的照片唯一ID。
+
+「示例」：
+
+```bash
+trailsnap photos delete --photo-id 10001
+```
+
+「输出说明」：删除成功提示 `照片 <photo-id> 删除成功`，失败提示 `照片删除失败或不存在`。
+
+# 四、分类标签命令
+
+## 4.1 tags list - 查询分类标签
+
+「功能」：查询分类标签列表，支持分页。
+
+「格式」：`tags list [--skip N] [--limit N] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--skip`：跳过 N 个记录（默认 0）
+- `--limit`：限制返回 N 个记录（默认 100）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「示例」：
+
+```bash
+trailsnap tags list
+trailsnap tags list --format table
+```
+
+「输出说明」：输出 JSON 数组，每项包含 `id`、`name`（tag_name）、`count`。
+
+# 五、相册管理命令
+
+## 5.1 albums list - 查询相册列表
+
+「功能」：查询相册列表，支持分页。
+
+「格式」：`albums list [--skip N] [--limit N] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--skip`：跳过 N 个相册（默认 0）
+- `--limit`：限制返回 N 个相册（默认 100）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「输出说明」：输出 JSON 数组，每项包含 `id`、`name`、`count`（num_photos）、`description`、`condition`、`type`。
+
+「示例」：
+
+```bash
+trailsnap albums list
+trailsnap albums list --format pretty
+```
+
+# 六、位置相关命令
+
+## 6.1 locations - 位置查询主命令
+
+「功能」：包含位置分布查询、足迹时间轴查询两个子命令，基于照片的GPS信息统计。
+
+### 6.1.1 locations list - 查询位置分布
+
+「功能」：查询位置分布，不含时间信息（地点名、照片数量）。支持按层级分组与日期范围过滤。
+
+「格式」：`locations list [--level city|province|district|scene] [--skip N] [--limit N] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--level`：分组级别（默认 city，可选：city、province、district、scene）
+- `--skip`：跳过 N 个位置（默认 0）
+- `--limit`：限制返回 N 个位置（默认 100）
+- `--start-date`：可选，开始日期（YYYY-MM-DD）
+- `--end-date`：可选，结束日期（YYYY-MM-DD）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 数组，每项包含 `name`、`count`
+
+「示例」：
+
+```bash
+trailsnap locations list
+trailsnap locations list --format table
+```
+
+### 6.1.2 locations timeline - 查询足迹时间轴
+
+「功能」：查询足迹时间轴列表，按时间段和地点分组（开始日期、结束日期、地点名、照片数量）。支持按层级分组与日期范围过滤。
+
+「格式」：`locations timeline [--level city|province|district|scene] [--skip N] [--limit N] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--level`：分组级别（默认 city，可选：city、province、district、scene）
+- `--skip`：跳过 N 个位置（默认 0）
+- `--limit`：限制返回 N 个位置（默认 100）
+- `--start-date`：可选，开始日期（YYYY-MM-DD）
+- `--end-date`：可选，结束日期（YYYY-MM-DD）
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「返回值」：JSON 数组，每项包含 `startDate`、`endDate`、`locationName`、`count`
+
+「示例」：
+
+```bash
+trailsnap locations timeline --level city --start-date 2025-01-01 --end-date 2025-06-30
+trailsnap locations timeline --format csv
+```
+
+# 七、人物识别命令
+
+## 7.1 people list - 查询已识别的人物/面孔
+
+「功能」：查询人物（面部识别身份）列表，支持按类型过滤。
+
+「格式」：`people list [--limit N] [--types named,unnamed,hidden] [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--limit`：返回的记录数（默认 100）
+- `--types`：查询类型，逗号分隔，默认 `named`；可选值：`named`、`unnamed`、`hidden`
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「输出说明」：输出 JSON 数组，每项包含 `id`、`name`（identity_name）、`tags`、`description`、`face_count`。
+
+「示例」：
+
+```bash
+trailsnap people list
+trailsnap people list --format ndjson
+```
+
+# 八、存储文件夹命令
+
+## 8.1 folders list - 查询挂载的存储文件夹列表
+
+「功能」：查询系统中已挂载的存储目录信息。
+
+「格式」：`folders list [--format json|pretty|table|ndjson|csv]`
+
+「参数说明」：
+
+- `--format`：输出格式（默认 json，可选：json、pretty、table、ndjson、csv）
+
+「输出说明」：直接输出后端接口返回的 JSON（字段结构以服务端为准）。
+
+「示例」：
+
+```bash
+trailsnap folders list
+trailsnap folders list --format pretty
+```
+
+# 九、媒体文件命令
+
+## 9.1 medias get - 获取照片的媒体文件或URL
+
+「功能」：获取指定照片的媒体内容/访问地址，支持输出 URL、base64、或保存到本地文件。
+
+「格式」：`medias get [--photo-id 照片ID] [--size small|medium|large] [--format url|base64|file] [--output 文件路径]`
+
+「参数说明」：
+
+- `--photo-id`：照片 ID（默认 100）
+- `--size`：照片质量/尺寸（默认 medium，可选：small、medium、large）
+- `--format`：输出格式（默认 url（可以把链接插入到HTML页面或者markdown文件），可选：url、base64、file）
+- `--output`：输出文件路径（仅当 `--format file` 时必填）
+
+「示例」：
+
+```bash
+# 输出 URL（large 输出原图URL，small/medium 输出缩略图URL）
+trailsnap medias get --photo-id 10001 --format url --size large
+
+# base64 输出（缩略图base64编码）
+trailsnap medias get --photo-id 10001 --format base64 --size medium
+
+# 保存到本地文件
+trailsnap medias get --photo-id 10001 --format file --output .\photo_10001.jpg
+```
+
+# 十、注意事项
+
+- 所有涉及 API 交互的命令（photos、locations、people 等），必须先执行 `config set` 配置 API URL 和 Token，否则会提示 `错误: API URL 和 Token 未配置，请先运行 'config' 命令。` 并退出。
+
+- 所有命令可通过 `--help` 查询详细用法，若参数错误，会提示具体错误信息及正确格式。

{trailsnap_cli-0.3.8 → trailsnap_cli-0.3.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trailsnap-cli"
-version = "0.3.8"
+version = "0.3.10"
 description = "TrailSnap Command Line Interface"
 readme = "README.md"
 requires-python = ">=3.9"

{trailsnap_cli-0.3.8 → trailsnap_cli-0.3.10}/trailsnap/cli.py

@@ -6,8 +6,9 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from commands import config, photos, tags, albums, locations, people, folders, medias
+from output import set_formatter, OutputFormatter
 
-VERSION = "0.3.8"
+VERSION = "0.3.10"
 
 def main():
     if hasattr(sys.stdout, "reconfigure"):
@@ -20,6 +21,13 @@ def main():
     subparsers.required = True
 
     parser.add_argument("-v", "--version", action="version", version=VERSION)
+    parser.add_argument(
+        "--format",
+        type=str,
+        default="json",
+        choices=OutputFormatter.SUPPORTED_FORMATS,
+        help="输出格式: json (完整JSON，默认), pretty (人性化), table (表格), ndjson (换行分隔JSON), csv (逗号分隔值)"
+    )
 
     # 注册各个子命令
     config.setup_parser(subparsers)
@@ -33,6 +41,9 @@ def main():
 
     args = parser.parse_args()
 
+    # 设置全局输出格式
+    set_formatter(args.format)
+
     # 执行对应的命令处理函数
     if hasattr(args, "func"):
         args.func(args)