用途
immich-photo-manager 是一个非官方的社区插件，用于通过 AI 助手管理自托管的 Immich 照片库。当照片库规模超出人工整理能力时，它让 AI 助手直接访问 Immich 实例，通过自然对话完成搜索、整理、去重和相册策展。它通过 Immich 的公开 API 与服务器通信，支持 Claude、Gemma 或任何兼容 MCP（Model Context Protocol）的客户端。
主要能力
- AI 搜索：基于 CLIP 的自然语言照片搜索，例如“海滩日落”“生日蛋糕”。
- 地理相册：结合 GPS、CLIP 视觉搜索和时间匹配，按地点创建相册。
- 元数据修复：修正正午/午夜时间戳、从相邻照片推断缺失 GPS、校正时区偏移。
- 库清理：通过多信号分析检测截图、重复项和低质量图片；近似重复和连拍可堆叠在最佳照片之后，而非直接删除，且可逆。
- 重复检测：使用感知哈希进行跨来源分析，可发现 Apple Photos、Google Photos 等导入的重新编码副本。
- 批量旋转：一次旋转整个相册或选定内容（90°/180°/270°），非破坏性，可累积，一键还原。
- PDF 报告：将相册或选定内容导出为带元数据、视频帧和 AI 说明文字的 PDF，在本地生成；相册布局可为每个选定的视频时刻提供整页及独立说明，封面/索引/地点页面可选。
- 视频帧：从任意片段中按均匀间隔截取帧，或按片段（start/end）截取，最小间隔可到每秒一帧，供 AI 描述视频内容。
- 人物与面孔管理：列出、搜索、合并和组织已识别的人物；重新分配误识别的面孔；查看面孔缩略图。
- 回收站与资产生命周期：安全删除到回收站、永久删除、从回收站恢复。
- 库健康：一条命令获取资产清单、元数据质量、存储分布和建议。
- 标签与组织：创建、应用和管理标签；批量添加或移除标签。
- 服务器感知：一次调用报告 Immich 版本、已启用的功能（OCR、智能搜索、面孔、地图）及该主版本的已知行为。
- 照片内文字：OCR 查找照片中的文字（票据、路牌），explore、city 和 suggestion 调用返回过滤器所需的准确拼写。
- 日期视图：按月分桶、显示空档和繁忙日期的日历热力图，以及 Immich 的“历史上的今天”回忆。
- 双向分享：合作伙伴库（Immich 家庭分享）以及共享相册上的评论和点赞。
- 原始文件导出：将相册或选定内容打包为一个 zip 下载到本地，下载前报告大小。
- 跨会话笔记：在每个资产上存储判定和操作，下次清理可跳过已审查内容。
- Docker 运行：多架构镜像，通过 HTTP 在 8626 端口提供 MCP 服务，支持两种协议时代，同样 94 个工具。
- 交互式画廊：自包含 HTML 页面，内嵌缩略图，3 种主题、4 种视图模式，以及用于批量操作的 Cowork Actions Panel。
使用方式
前置条件：运行中的 Immich 实例（自托管，v1.90+）、Immich API 密钥、Python 3.10+ 与 pip。
安装（Claude Code 插件）：安装后会提示服务器 URL 和 API 密钥未设置。可在会话内通过 /plugin 对话框输入（密钥存入系统安全存储），或在 shell 中通过 --config immich_base_url=... --config immich_api_key=... 传入。重启 Claude Code 后，可通过引导式设置或一行命令连接 Immich，凭据会被保存供后续会话使用。
更新插件：一行命令更新，无需重装，然后重启 Claude Code。拉取新版本后需重新运行 pip3 install -r src/requirements.txt。
其他 MCP 客户端：可直接使用 uvx 运行包入口点。默认使用 MCP stdio 传输；设置 MCP_TRANSPORT=http 可作为 Streamable HTTP 服务运行。
Docker：镜像在 GitHub Container Registry 上提供（amd64 + arm64），通过 HTTP 在 8626 端口提供 MCP 服务。将 Streamable HTTP 客户端指向 http://localhost:8626/mcp。健康检查在 /health。写入文件的工具会将文件放在 /data，需挂载卷。
Claude Desktop（macOS）：应用看不到 shell 的 PATH，需在“command”中写入 uvx 的完整路径。先在终端运行一次 uvx immich-photo-manager --help 完成首次下载，然后退出并重新打开 Claude Desktop。
适用场景
- 照片库规模庞大、人工整理困难，希望通过自然语言批量创建相册、搜索照片。
- 需要清理重复照片、截图和低质量图片，同时保留可逆操作。
- 需要修复时间戳、GPS 等元数据问题。
- 需要生成 PDF 相册、视频帧说明或交互式 HTML 画廊。
- 需要管理人物面孔、标签、分享链接和回收站。
限制与注意事项
- 该插件为非官方社区项目，与 Immich 或 FUTO 无关联、赞助或背书关系。
- 插件进程在本地运行，仅与用户配置的 Immich 通信；但助手读取的内容（文件名、日期、EXIF、相册列表，以及请求查看图片时的缩略图，默认 250px，按需 1440px 预览）会发送给所使用的模型。原始文件从不获取。使用本地模型（LM Studio、Ollama）时数据不会离开网络。
- PDF 报告写入本地磁盘，除非传入 return_base64=true，否则不会发送到任何地方。
- 当资产带有 GPS 时，Places 页面会从 tile.openstreetmap.org 加载地图瓦片，这是服务器自身唯一的第三方调用；传入 map=false 可跳过。
- 画廊页面不加载外部资源；旅行地图从 unpkg.com 加载 Leaflet 及其两个插件，并从 OpenStreetMap 加载瓦片。
- 凭据在插件配置对话框中输入时保存在系统安全存储；在对话中提供时会经过模型，并保存在两个仅用户可读的文件中。
- create_shared_link 创建的链接任何持有 URL 的人均可打开。
- delete_assets 将资产移入回收站，restore_assets 可撤销；force=true 才会永久删除，empty_trash 也是永久操作。清理和去重技能会先展示结果并等待确认。
- 插件不会更改 Claude 的权限设置。
- 一次只能连接一个 Immich 实例。
- 已在 Immich 2.7.5 和 3.1.0 上实测，每次推送运行 364 个单元测试。
