# TrailSnap  CLI 安装指南

以下步骤面向 AI Agent，部分步骤需要用户在浏览器中配合完成。

## 环境要求

开始安装之前，请确保环境中已安装：

- Node.js（npm/npx 安装需要）
- Python 3（pip 安装需要）


## 第 1 步 安装

根据环境选择安装方式（选择其中一种即可）：

- Node.js 安装：npm/npx 安装
- Python 安装：pip 安装

### npm/npx 安装

```shell
# 安装 CLI
npm install -g trailsnap-cli

# 安装 CLI SKILL（必需）
npx skills add lc044/trailsnap  -y -g
```

### pip 安装

```shell
# 安装 CLI
pip install trailsnap-cli

# 安装 CLI SKILL（必需）
npx skills add lc044/trailsnap  -y -g
```

## 第 2 步 配置 API URL 和 Agent Token

Agent 需要询问用户 TrailSnap 的访问地址和 `ts_` 开头的只读 Agent Token（如何获取请参考[TrailSnap API 文档](https://trailsnap.cn/docs/guide/settings/tokensetting.html)），收到用户输入后执行。不要把 Token 输出到日志或提交到仓库：

```shell
trailsnap config set --url <url> --token <ts_token>
```

## 第 3 步 验证

```shell
trailsnap photos list --limit 1
```

# TrailSnap CLI 命令说明书

本文档详细说明 TrailSnap CLI 命令行工具的所有可用命令、参数用法、功能描述及使用示例，适用于快速上手操作。命令结构遵循「主命令 + 子命令 + 参数」。

核心说明：所有命令需在终端执行，格式统一为 `trailsnap <command> <subcommand> [options]`。涉及 API 交互的命令（如 photos、locations 等）需先通过 `config set` 配置 API 地址和 Token，否则会直接报错并退出。

# 一、基础命令

## 1.1 help - 显示帮助信息

「功能」：显示所有可用命令、命令结构及各命令的核心参数，快速查阅命令用法。
「格式」：`--help`
「示例」：
```bash
trailsnap --help
```

# 二、配置命令

## 2.1 config set - 配置API URL和Token

「功能」：配置 CLI 使用的 TrailSnap 统一访问地址和 Bearer Token，是所有 API 交互类命令的前置操作。

「格式」：`config set --url API地址 --token API凭证`

「参数说明」：

- `--url`（必填）：TrailSnap 统一访问地址，例如：http://localhost:3180。CLI 会自动使用 `/api`。

- `--token`（必填）：API访问凭证（Bearer Token），用于身份验证，需从后端获取。

「示例」：

```bash
trailsnap config set --url http://localhost:3180 --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

「输出说明」：配置成功后会输出配置文件保存路径（写入同目录 `.env`），例如：`配置已保存到 .../.env`。

# 三、照片管理命令

## 3.1 photos - 照片管理主命令

「功能」：包含照片列表查询、单张照片详情获取等子命令，所有子命令需先完成 API 配置。Agent Token 仅允许只读访问。

### 3.1.1 photos list - 查询照片列表

「功能」：查询照片列表，支持分页与按相册/地点/设备信息过滤。返回结果为简化字段集合。

「格式」：`photos list [--skip N] [--limit N] [--album-id 相册ID] [--city 城市] [--province 省份] [--make 品牌] [--model 型号]`

「参数说明」（支持组合筛选）：

- `--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`：按相机型号过滤，多个型号用逗号分隔

「返回值」：JSON 数组，每项包含 `id`、`filename`、`file_type`、`photo_time`

「示例」：

```bash
trailsnap photos list --limit 20 --city 西安市,上海市
```

### 3.1.2 photos info - 获取单张照片信息

「功能」：获取指定 ID 照片的元数据信息与内容描述信息。

「格式」：`photos info --photo-id 照片ID`

「参数说明」：

- `--photo-id`（必填）：照片唯一ID，可通过photos list命令获取。

「返回值」：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
```

### 3.1.3 photos delete - 删除单张照片（Agent Token 不可用）

「功能」：删除指定 ID 的照片，删除后不可恢复。该命令不接受 `ts_` Agent Token；仅供具有正常用户会话权限的人工操作使用，AI Agent 不应调用。

「格式」：`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]`

「参数说明」：

- `--skip`：跳过 N 个记录（默认 0）
- `--limit`：限制返回 N 个记录（默认 100）

「示例」：

```bash
trailsnap tags list
```

「输出说明」：输出 JSON 数组，每项包含 `id`、`name`（tag_name）、`count`。

# 五、相册管理命令

## 5.1 albums list - 查询相册列表

「功能」：查询相册列表，支持分页。

「格式」：`albums list [--skip N] [--limit N]`

「参数说明」：

- `--skip`：跳过 N 个相册（默认 0）
- `--limit`：限制返回 N 个相册（默认 100）

「输出说明」：输出 JSON 数组，每项包含 `id`、`name`、`count`（num_photos）、`description`、`condition`、`type`。

「示例」：

```bash
trailsnap albums list
```

# 六、位置相关命令

## 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]`

「参数说明」：

- `--level`：分组级别（默认 city，可选：city、province、district、scene）
- `--skip`：跳过 N 个位置（默认 0）
- `--limit`：限制返回 N 个位置（默认 100）
- `--start-date`：可选，开始日期（YYYY-MM-DD）
- `--end-date`：可选，结束日期（YYYY-MM-DD）

「返回值」：JSON 数组，每项包含 `name`、`count`

「示例」：

```bash
trailsnap locations list
```

### 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]`

「参数说明」：

- `--level`：分组级别（默认 city，可选：city、province、district、scene）
- `--skip`：跳过 N 个位置（默认 0）
- `--limit`：限制返回 N 个位置（默认 100）
- `--start-date`：可选，开始日期（YYYY-MM-DD）
- `--end-date`：可选，结束日期（YYYY-MM-DD）

「返回值」：JSON 数组，每项包含 `startDate`、`endDate`、`locationName`、`count`

「示例」：

```bash
trailsnap locations timeline --level city --start-date 2025-01-01 --end-date 2025-06-30
```

# 七、人物识别命令

## 7.1 people list - 查询已识别的人物/面孔

「功能」：查询人物（面部识别身份）列表，支持按类型过滤。

「格式」：`people list [--limit N] [--types named,unnamed,hidden]`

「参数说明」：

- `--limit`：返回的记录数（默认 100）
- `--types`：查询类型，逗号分隔，默认 `named`；可选值：`named`、`unnamed`、`hidden`

「输出说明」：输出 JSON 数组，每项包含 `id`、`name`（identity_name）、`tags`、`description`、`face_count`。

「示例」：

```bash
trailsnap people list
```

# 八、存储文件夹命令

## 8.1 folders list - 查询挂载的存储文件夹列表

「功能」：查询系统中已挂载的存储目录信息。

「格式」：`folders list`

「输出说明」：直接输出后端接口返回的 JSON（字段结构以服务端为准）。

「示例」：

```bash
trailsnap folders list
```

# 九、媒体文件命令

## 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` 查询详细用法，若参数错误，会提示具体错误信息及正确格式。

---
name: "trailsnap-cli"
description: "Query photos, albums, locations, tags, and people from a TrailSnap instance through its command-line client. Use when TrailSnap MCP tools are unavailable and the user asks about their own photo library; Agent Tokens are read-only, so do not use this skill to mutate library data."
---

# TrailSnap CLI 技能

当原生 TrailSnap MCP 工具不可用时，使用 `trailsnap` CLI 查询 TrailSnap；两者同时可用时优先 MCP。

## 功能
1. 根据指定条件（可选过滤参数）查询照片列表。
2. 查询分类标签、相册、位置和人物（面部）信息。
3. 查询某张照片的详细信息。

## 安装

使用以下命令检查是否安装了 `trailsnap` 工具，如果没有安装则可以参考[install.md](install.md)文档进行安装。

```bash
trailsnap -v
```

## 初始配置

首次使用需要配置 API 地址和 `ts_` 开头的只读 Agent Token。用以下命令检查配置：

```bash
trailsnap photos list --limit 1
```

如果收到配置错误，询问用户这两个信息，然后执行；不要把 Token 输出到日志或提交到仓库：
```bash
trailsnap config set --url <API_BASE_URL> --token <YOUR_API_TOKEN>
```

## 使用方法

使用前可以通过 `trailsnap <command> -h` 或 `trailsnap <command> <subcommand> -h` 查看每个命令的详细帮助信息。通常情况下，你需要先根据用户的问题逐步筛选出检索条件（一个简单的[示例](examples/simple.md)），然后查询符合条件的照片列表。

- `locations timeline` 命令能够查到时间和空间上的信息，是一个很好的工具，返回一个足迹时间轴（某一段时间去了那个地方）。
- 除非用户不需要显示照片，否则以合适格式展示照片；使用 `medias get --format url` 获取地址，保留返回值，不要编造路径。
- 在使用之前你需要阅读 [reference.md](reference.md) 文件，了解每个命令的详细参数和选项。
- 如果需要的话，可以参考 [examples/simple.md](examples/simple.md) 文件，了解如何使用该工具。
- Agent Token 仅允许匹配 scope 的读取。不要调用删除、toolbox、任务变更、上传或其他写命令，也不要声称已经修改相册。
- AI 描述、人脸匹配与回忆候选属于推断证据，不应表述为已确认事实。

使用 Python 运行脚本：

```bash
trailsnap <command> <subcommand> [options]
```