# TrailSnap 行影集 documentation

> AI-powered, self-hosted photo library. This index is optimized for AI agents and links directly to Markdown source.

## AI-friendly entry points

- Full documentation: https://trailsnap.cn/llms-full.txt
- Structured index: https://trailsnap.cn/ai-docs.json
- CLI installation prompt: https://trailsnap.cn/install.md

## 中文文档

### AI Agent 文档入口
- [AI Agent 文档入口](https://trailsnap.cn/docs/guide/ai-access.md): 为 AI Agent 提供 llms.txt、结构化索引和 Markdown 原文等稳定、低噪声的官网文档入口。

### 安装部署
- [桌面版内置 AI](https://trailsnap.cn/docs/guide/desktop-ai-extension.md): 行影集桌面版已包含 AI 运行环境，安装和更新只需一次操作。
- [安装指南](https://trailsnap.cn/docs/guide/install.md): 在桌面安装包与 Docker 部署之间选择适合你的 TrailSnap 安装方式。
- [移动 App 使用指南](https://trailsnap.cn/docs/guide/mobile-app.md): 安装 TrailSnap Android App，并连接自己的 TrailSnap 服务器
- [概览](https://trailsnap.cn/docs/guide/overview.md): TrailSnap 是一个智能化的 AI 相册应用，致力于帮助用户轻松记录、整理和回顾自己的出行经历。通过强大的 AI 处理能力，让每一张照片和每一段旅程都成为值得珍藏的记忆。
- [部署前检查](https://trailsnap.cn/docs/guide/preflight.md): 在运行安装脚本前，用这一页确认环境和预期。这样可以避免“容器启动了，但照片无法扫描或手机无法访问”的常见问题。

### Docker 部署
- [飞牛OS（fnOS）部署](https://trailsnap.cn/docs/guide/docker/fnos.md): 本教程用于在飞牛OS（fnOS）上通过 Docker Compose 部署 TrailSnap。不同版本界面可能略有差异，但关键点一致：应用数据持久化、照片目录挂载、端口规划与权限校验。
- [Docker 部署（通用）](https://trailsnap.cn/docs/guide/docker/index.md): 本章面向 NAS/家庭服务器场景：用 Docker Compose 一次性启动 TrailSnap 的前端、后端、数据库与 AI 服务，并把你的照片目录挂载进来。
- [绿联 NAS（UGREEN）部署](https://trailsnap.cn/docs/guide/docker/ugreen.md): 在 UGOS Pro 系统上，推荐使用项目 Docker Compose 快速部署容器，适合需同时管理多个容器的场景，这种方法简化了容器的部署与管理工作。以下是使用 Docker Compose 部署 TrailSnap 的详细步骤。
- [Windows 部署](https://trailsnap.cn/docs/guide/docker/windows.md): Docker Compose已经集成在Docker Desktop中，所以先安装它：
- [极空间部署](https://trailsnap.cn/docs/guide/docker/zspace.md): 本教程基于 TrailSnap 的 Docker Compose 部署方式，适合在极空间设备上部署并长期运行。目标是让 TrailSnap 作为家庭服务稳定运行，同时把照片库挂载到容器中用于扫描与索引。

### 设置指南
- [AI 大模型设置](https://trailsnap.cn/docs/guide/settings/aisetting.md): 本页配置对话与图片理解使用的大模型连接。桌面版已内置 AI 运行环境，识别模型按需下载，参见桌面版内置 AI。
- [设置外部图库](https://trailsnap.cn/docs/guide/settings/directories.md): 添加外部文件夹路径，系统将扫描这些文件夹中的图片。外部文件夹中的图片不会被移动或修改，生成的缩略图将存储在主目录中。
- [设置指南](https://trailsnap.cn/docs/guide/settings/index.md): TrailSnap 提供了丰富的自定义选项，帮助您打造个性化的智能相册。
- [地图设置指南](https://trailsnap.cn/docs/guide/settings/mapsetting.md): TrailSnap 使用地图服务来展示照片的地理位置分布（足迹地图）。为了正常使用地图功能，您需要自行申请并配置地图服务的 API Key。
- [设置访问令牌](https://trailsnap.cn/docs/guide/settings/tokensetting.md): 使用token可以让第三方应用访问TrailSnap的后端API，你可以从TrailSnap后端获取一个Token。

### 使用指南
- [功能清单](https://trailsnap.cn/docs/guide/features.md): 本文档列出 TrailSnap（行影集）的完整功能列表，帮助你快速了解应用的所有能力。
- [TrailSnap 用户指南](https://trailsnap.cn/docs/guide/user.md): 登录后，您将看到系统主页（Dashboard），其中包含了：

### 参考信息
- [更新日志](https://trailsnap.cn/docs/guide/changelog.md): 火车票截图识别更准：支持无「站」字后缀的站名、新增车站和繁简车厢座位，缺车次时自动补充整图识别，日期不再受广告和状态栏干扰。
- [数据、隐私与备份](https://trailsnap.cn/docs/guide/data-safety.md): TrailSnap 是自托管应用：照片、数据库和账号数据保存在你部署的服务器或 NAS 上。项目不会因为你安装了 TrailSnap 而自动接收你的照片；但服务器的实际管理员仍需要负责访问控制、备份和公网安全。
- [识别效果展示](https://trailsnap.cn/docs/guide/demo.md): TrailSnap 搭载了 OCR 引擎，专为火车票识别进行了深度优化。
- [问题反馈](https://trailsnap.cn/docs/guide/feedback.md): 如果你在使用过程中遇到任何问题，或有任何建议，欢迎通过以下方式联系我们。
- [常见问题](https://trailsnap.cn/docs/guide/questions.md): 1. 支持哪些部署方式？

### Agent 集成
- [Claude Code](https://trailsnap.cn/docs/guide/agent/claudecode.md): 参考 Token 设置 获取访问token。
- [Agent Skills](https://trailsnap.cn/docs/guide/agent/index.md): TrailSnap CLI 可以作为 Agent 工具（Skill）被无缝集成到各种 AI 编码助手或 Agent 平台中，例如 Claude Code、OpenClaw / Roo Code 等。通过让 Agent 调用 CLI，AI 能够直接获取、分析和查询您的相册数据，实现基于个人图库的智能问答。
- [配置 TrailSnap MCP](https://trailsnap.cn/docs/guide/agent/mcp.md): 创建最小权限 Agent Token，并通过 Streamable HTTP 将 TrailSnap 的照片搜索、回忆侦探、人物时间线和待确认相册提案接入外部 AI Agent。
- [OpenClaw / Roo Code](https://trailsnap.cn/docs/guide/agent/openclaw.md): OpenClaw / Roo Code 等 IDE Agent 可以调用 TrailSnap CLI 作为 Skill，让 AI 通过 TrailSnap API 查询你的个人相册数据。
- [TrailSnap CLI 工具](https://trailsnap.cn/docs/guide/agent/trailsnap-cli.md): TrailSnap CLI 工具是一个基于TrailSnap API的命令行工具，可以通过命令行管理TrailSnap的相册数据。
- [TrailSnap CLI 安装指南](https://trailsnap.cn/install.md): 以下步骤面向 AI Agent，部分步骤需要用户在浏览器中配合完成。

### 开发者文档
- [AI微服务设计](https://trailsnap.cn/docs/dev/ai_service.md): AI 微服务用于承载 TrailSnap 的 AI 能力（如 OCR、人脸识别、场景分类、图片内容分析等），由后端任务系统按需调用。
- [架构设计文档](https://trailsnap.cn/docs/dev/architecture.md): TrailSnap 采用典型的前后端分离架构，由前端展示层、后端服务层、AI 微服务层和数据存储层组成。
- [后端框架分析文档](https://trailsnap.cn/docs/dev/backend.md): FastAPI（Server）: 高性能异步 Web 框架，提供自动化 OpenAPI 文档 (/docs)。
- [功能设计文档](https://trailsnap.cn/docs/dev/feature-proposals.md): 本文档收录 TrailSnap 待开发功能的设计草案，供社区讨论和贡献参考。
- [前端框架分析文档](https://trailsnap.cn/docs/dev/frontend.md): 项目使用 Vue 3 作为核心框架，采用 Composition API 提供灵活的逻辑复用能力；配合 TypeScript 提供静态类型检查，增强代码健壮性；构建工具为 Vite。
- [TrailSnap 开发者文档](https://trailsnap.cn/docs/dev/guide.md): 本文档旨在为开发者提供 TrailSnap 项目的开发指南，涵盖环境搭建、项目结构、开发流程等内容。
- [任务管理模块设计文档](https://trailsnap.cn/docs/dev/task_manager.md): 任务管理模块采用多级缓冲 + 生产者-消费者（Multi-Level Buffer + Producer-Consumer）模型，以数据库（PostgreSQL）作为持久化后端，以内存优先级队列作为调度中枢，实现了任务生产与消费的彻底解耦。该架构主要包含以下四个核心组件：

## English documentation

### AI Agent access
- [AI Agent Documentation Access](https://trailsnap.cn/en/docs/guide/ai-access.md): Stable, low-noise documentation entry points for AI agents, including llms.txt, a structured index, and Markdown mirrors.

### Installation
- [Built-in desktop AI](https://trailsnap.cn/en/docs/guide/desktop-ai-extension.md): AI is included in the TrailSnap desktop application and updated with it.
- [Installation](https://trailsnap.cn/en/docs/guide/install.md): Choose between TrailSnap desktop installers and a self-hosted Docker deployment.
- [Mobile App Guide](https://trailsnap.cn/en/docs/guide/mobile-app.md): Install the TrailSnap Android app and connect it to your own TrailSnap server
- [Overview 🚀](https://trailsnap.cn/en/docs/guide/overview.md): TrailSnap is an intelligent AI photo album app. It helps you record, organize, and review your travel experiences, turning photos into memories worth cherishing.
- [Pre-deployment checklist](https://trailsnap.cn/en/docs/guide/preflight.md): Use this page before running the installer. It helps avoid the common case where containers start successfully but photos cannot be scanned or a phone cannot reach the server.

### Docker deployment
- [Fnos Deployment](https://trailsnap.cn/en/docs/guide/docker/fnos.md): This tutorial is for deploying TrailSnap on Fnos via Docker Compose. Interfaces may vary slightly between versions, but the key points are consistent: application data persistence, photo directory mounting, port plann...
- [Docker Deployment (Generic)](https://trailsnap.cn/en/docs/guide/docker/index.md): This chapter targets NAS/Home Server scenarios: Start TrailSnap's frontend, backend, database, and AI services at once using Docker Compose, and mount your photo directory.
- [Ugreen NAS Deployment](https://trailsnap.cn/en/docs/guide/docker/ugreen.md): On the UGOS Pro system, it is recommended to use the project Docker Compose to quickly deploy containers, suitable for scenarios where multiple containers need to be managed simultaneously. This method simplifies cont...
- [Step 1: Install Docker Desktop](https://trailsnap.cn/en/docs/guide/docker/windows.md): Docker Compose is already integrated into Docker Desktop, so install it first:
- [Zspace Deployment](https://trailsnap.cn/en/docs/guide/docker/zspace.md): This tutorial is based on TrailSnap's Docker Compose deployment method, suitable for deployment and long-term operation on Zspace devices. The goal is to let TrailSnap run stably as a home service while mounting the p...

### Settings
- [AI / LLM Settings](https://trailsnap.cn/en/docs/guide/settings/aisetting.md): This page configures model connections for chat and image understanding. Desktop AI is included in the application; models are downloaded as needed. See built-in desktop AI.
- [External Libraries](https://trailsnap.cn/en/docs/guide/settings/directories.md): Add external folder paths and the system will scan images in those folders. Images in external folders will not be moved or modified; generated thumbnails will be stored in the main directory.
- [Settings Guide](https://trailsnap.cn/en/docs/guide/settings/index.md): TrailSnap provides rich customization options to help you build a personalized intelligent photo album.
- [Map Settings Guide](https://trailsnap.cn/en/docs/guide/settings/mapsetting.md): TrailSnap uses map services to display the geographical distribution of photos (Footprint Map). In order to use the map function normally, you need to apply for and configure the API Key of the map service yourself.
- [Token Settings](https://trailsnap.cn/en/docs/guide/settings/tokensetting.md): Using a token allows third-party apps (such as TrailSnap CLI or Agent Skills) to access TrailSnap Backend APIs.

### User guide
- [Feature List](https://trailsnap.cn/en/docs/guide/features.md): This document lists the complete feature set of TrailSnap, helping you quickly understand all its capabilities.
- [TrailSnap User Guide](https://trailsnap.cn/en/docs/guide/user.md): Welcome to TrailSnap! This guide covers the main features and how to use them.

### Reference
- [Changelog](https://trailsnap.cn/en/docs/guide/changelog.md): More accurate train-ticket screenshot recognition: station names without the suffix, newly opened stations, and traditional/simplified carriage-seat forms; a missing train number triggers one full-image pass, and date...
- [Data, privacy, and backups](https://trailsnap.cn/en/docs/guide/data-safety.md): TrailSnap is self-hosted: your photos, database, and account data are stored on the server or NAS you operate. Installing TrailSnap does not automatically send photos to the project maintainers, but the person operati...
- [Recognition Demo](https://trailsnap.cn/en/docs/guide/demo.md): TrailSnap is powered by an OCR engine optimized specifically for train ticket recognition.
- [Feedback](https://trailsnap.cn/en/docs/guide/feedback.md): If you encounter any problems during use, or have any suggestions, please feel free to contact us through the following methods.
- [FAQ](https://trailsnap.cn/en/docs/guide/questions.md): 1. What deployment methods are supported?

### Agent integration
- [Claude Code](https://trailsnap.cn/en/docs/guide/agent/claudecode.md): See Token Settings.
- [Agent Skills](https://trailsnap.cn/en/docs/guide/agent/index.md): TrailSnap CLI can be used as an Agent tool (Skill) in different AI coding assistants or Agent platforms, such as Claude Code and OpenClaw / Roo Code. By letting the Agent call the CLI, AI can query and analyze your al...
- [Configure TrailSnap MCP](https://trailsnap.cn/en/docs/guide/agent/mcp.md): Create a least-privilege Agent Token and connect external AI agents to TrailSnap photo search, memory investigation, person timelines, and confirmable album proposals over Streamable HTTP.
- [OpenClaw / Roo Code](https://trailsnap.cn/en/docs/guide/agent/openclaw.md): OpenClaw / Roo Code can call TrailSnap CLI as a Skill, so the Agent can query your personal album data through TrailSnap APIs.
- [TrailSnap CLI](https://trailsnap.cn/en/docs/guide/agent/trailsnap-cli.md): TrailSnap CLI is a command-line tool built on TrailSnap APIs. It can be used directly in your terminal, or as a Skill for Agents.

### Developer documentation
- [AI Service Design](https://trailsnap.cn/en/docs/dev/ai_service.md): The AI service hosts TrailSnap AI capabilities (e.g. OCR, face recognition, scene classification, image analysis). The backend task system calls it when needed.
- [Architecture Design Document](https://trailsnap.cn/en/docs/dev/architecture.md): TrailSnap adopts a typical separated frontend and backend architecture, consisting of a frontend presentation layer, a backend service layer, an AI microservice layer, and a data storage layer.
- [Backend Framework Analysis Document](https://trailsnap.cn/en/docs/dev/backend.md): FastAPI (Server): High-performance asynchronous Web framework, providing automated OpenAPI documentation (/docs).
- [Feature Design Document](https://trailsnap.cn/en/docs/dev/feature-proposals.md): This document collects design drafts for upcoming TrailSnap features, serving as a reference for community discussion and contributions.
- [Frontend Framework Analysis Document](https://trailsnap.cn/en/docs/dev/frontend.md): The project uses Vue 3 (^3.5.13) as the core framework, adopting Composition API to provide flexible logic reuse capabilities; coupled with TypeScript (^5.9.3) to provide static type checking and enhance code robustne...
- [TrailSnap Developer Documentation](https://trailsnap.cn/en/docs/dev/guide.md): This document aims to provide developers with a guide to the TrailSnap project, covering environment setup, project structure, development process, etc.
- [Task Management Module Design](https://trailsnap.cn/en/docs/dev/task_manager.md): The task management module adopts a Multi-Level Buffer + Producer-Consumer model, using PostgreSQL as the persistent backend and in-memory priority queues as the scheduling hub, achieving complete decoupling between t...