sophhub 0.4.19 → 0.4.21

package/skills/image-classify/src/SKILL.md

@@ -1,368 +1,368 @@
----
-name: image-classify
-description: 照片分类器。通过人脸识别对照片进行分类、搜索和管理。当用户说「用照片分类器查找/搜索 xxx」「对 xx 文件夹进行分类」「添加 xx 到照片分类器」「从照片分类器删除 xx」时使用。
----
-
-# 📸 照片分类器
-
-基于人脸 embedding 相似度的照片分类系统。支持注册用户人脸、按用户搜索照片、一键全量分类、删除用户；搜索/分类结束后**生成下载链接**（`pack`）即完成结果导出。
-
-## Processing Mode
-
-**STRICT SERIAL PROCESSING ONLY** — 单次顺序执行，不拆分子任务、不并行。
-
-**子会话（耗时任务）**：`search`、`quick-search`、`classify` 在**独立子会话**中执行。**子命令结束（成功或失败）后，须立即关闭并删除该子会话**，不得保留空壳会话。后续步骤——向用户展示结果表格、执行 `pack`——一律在**当前主会话**中完成。
-
-## Prerequisites
-
-- Python 3.10+、uv
-- 依赖：`requests`, `opencv-python`, `numpy`, `sophnet_tools`（项目内置）
-- 配置文件：`{baseDir}/references/config.json`
-- 若使用 **DM 自动推送**（注册时 `--friend-id`、一键 `classify` 后推送结果），需本机存在有效 JWT：`/home/node/.openclaw/jwt.json`（与 `send_dm_message.py` 一致）
-
-## 核心概念
-
-- **`{baseDir}`**：本 skill 根目录，即 `skills/image-classify`，调用时替换为实际绝对路径。
-- **配置文件**：`{baseDir}/references/config.json`，存储所有注册用户的名称、照片路径、人脸 embedding 向量，以及可选 **DM 绑定**：`friendId`（好友 userId）、`friendLabel`（可选展示名）。旧字段 `xia_you_hao` / `xia_you_label` 仍可被脚本读取。
-- **脚本入口**：`{baseDir}/scripts/face_search.py`，通过 `uv run` 以子命令方式调用。
-- **所有命令输出均为 JSON 格式**，方便解析结果。
-
-## 通用调用格式
-
-```bash
-uv run {baseDir}/scripts/face_search.py [-c CONFIG_PATH] <command> [args...]
-```
-
-`-c` / `--config` 可选，指定配置文件路径，默认为 `references/config.json`（相对于执行目录）。建议始终传入绝对路径 `{baseDir}/references/config.json`。
-
-## 可用命令一览
-
-| 命令 | 用途 | 示例 |
-|------|------|------|
-| `check <name>` | 检查用户名是否已注册 | `check 张三` |
-| `add <name> <image> [--friend-id ID] [--friend-label 名]` | 注册新用户；可选 `friendId` 与 `friendLabel`（括号内提示用） | `add 张三 /path/photo.jpg --friend-label 小李 --friend-id 23725` |
-| `replace <name> <image>` | 替换用户照片（删除旧照片） | `replace 张三 /path/new.jpg` |
-| `append <name> <image>` | 为已有用户追加一张照片 | `append 张三 /path/extra.jpg` |
-| `rename <old> <new>` | 修改用户名 | `rename 张三 李三` |
-| `delete <name>` | 删除用户 | `delete 张三` |
-| `search <name> <dir>` | 在目录中搜索某用户的相似人脸 | `search 张三 /home/photos` |
-| `quick-search <image> <dir>` | 直接用照片搜索相似人脸（不注册） | `quick-search /tmp/face.jpg /home/photos` |
-| `classify <dir>` | 一键分类：遍历所有用户搜索全部照片 | `classify /home/photos` |
-| `copy <target> [--name N]` | （可选）将搜索结果复制到本地文件夹 | `copy /output --name 张三` |
-| `pack [--name N] [--timeout T]` | 压缩结果为 zip 并上传获取下载链接 | `pack --timeout 120` |
-| `upload <file> [--timeout T]` | 上传文件获取 URL | `upload /path/file.zip` |
-| `init-today-folder` | 创建并返回待搜索目录当天子目录 | `init-today-folder` |
-| `upload-image <file...>` | 将一张或多张图片串行剪切到待搜索目录 `images/当天日期(YYYYMMDD)` | `upload-image /tmp/a.jpg /tmp/b.jpg` |
-| `list-date-folders` | 列出待搜索根目录 `images` 下全部 `YYYYMMDD` 子文件夹（新→旧），供未指定目录时选择 | `list-date-folders` |
-
-> ⚠️ 注意：如果用户发送的图片格式为 `![image](xxx.jpg)`，需要先执行 `upload` 命令将其转换为 URL 格式后再处理。
-
-## Usage
-
-根据用户意图匹配以下操作流程：
-
-### 未指定搜索目录时（`search` / `quick-search` / `classify` 共用）
-
-待搜索根目录由脚本内 `get_images_path()` 解析（通常为仓库上级 `images`）。其下按日期命名的子目录（`YYYYMMDD`）为可选搜索范围。
-
-若用户**未说明**搜索目录（或只说「默认目录」「最近上传的」等），**不要猜测路径**，先执行：
-
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json list-date-folders
-```
-
-输出 JSON 字段说明：
-- `folders`：全部合法日期文件夹，`{ "name": "20260410", "path": "/绝对路径/20260410" }`，已按日期**从新到旧**排序
-- `preview` / `preview_n`：默认只向用户展示**最近 `preview_n` 个（默认 3 个）**即可
-- `total`：总数；若大于 `preview_n`，用户可说「更多」「全部」「列出全部」——此时用 Markdown 列出剩余项（**只展示 `name`**，不罗列每条 `path`），再请用户回复**序号**或**日期名（YYYYMMDD）**；用户若粘贴目录路径则按路径解析
-
-选定目录后，将解析出的**绝对路径**作为 `<dir>` 传入 `search` / `quick-search` / `classify`。
-
-若 `folders` 为空，提示用户在 `images` 下先上传或创建日期目录（可用 `init-today-folder`、`upload-image`），或**手动提供**任意搜索目录路径。
-
-**向用户展示候选目录时（示例模版）** — 用 Markdown 呈现，**只展示日期文件夹名**，不要把磁盘绝对路径列给用户：
-
-- 📅📂 **最近可用的日期文件夹（任选其一）**
-  - 1️⃣ 📁 `20260410`
-
-  - 2️⃣ 📁 `20260409`
-
-  - 3️⃣ 📁 `20260408`
-- 💬 请回复**序号**或**日期名**；需要查看更多请说「更多」。内部调用命令时仍使用 JSON 里的 `path` 字段。✨
-
-### 1. 添加/注册用户
-
-**触发词**：「添加 xxx 到照片分类器」「注册 xxx」「把这张照片记为 xxx」
-
-**流程**：
-
-1. 获取用户提供的**用户名**、**照片路径**，以及是否绑定 **DM 接收方**（均可选）。用户常以自然语言写出类似：**虾友：xxx，ID:23725**（虾友即 DM 对象；**23725** 即 `friendId`）。解析规则：**xxx** → `--friend-label`；**23725** → `--friend-id`（正整数，与 `send_dm_message.py` 的 `--user-id` / 接口 `userId` 一致）。可只填 `friendId`、不填展示名。
-2. 检查用户名是否已存在：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "张三"
-```
-输出：`{"exists": true/false, "name": "张三"}`
-
-3. **如果不存在** → 注册新用户（无虾友号）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json add "张三" "/path/to/photo.jpg"
-```
-若用户提供了 `friendId`，追加 `--friend-id <正整数>`；若有展示名，追加 `--friend-label "xxx"`（注意转义或引号，避免 shell 拆词）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json add "张三" "/path/to/photo.jpg" --friend-label "小李" --friend-id 23725
-```
-输出：`{"success": true/false, "message": "...", "name": "张三", "image_url": "https://...", "friendId": 23725, "friendLabel": "小李"}`（`friendId` / `friendLabel` 仅在实际传入时出现）
-   - `success: true` → 提示：`🎉✨ **注册成功** · xxx`，并使用返回的 `image_url` 展示照片：`![image](image_url)`；若返回含 `friendId` / `friendLabel`，可顺带一句已绑定 DM（不必冗长）
-   - `success: false` → 提示：`❌🙈 照片中未发现有效的人脸信息，注册失败！`
-
-4. **如果已存在** → 提示用户选择操作：
-   ```
-   ⚡👤 用户名已存在，请选择操作：
-   1️⃣ 🔄 更新照片（替换主照片）
-   2️⃣ ✏️ 重新命名
-   3️⃣ ➕ 同时保留多张照片
-   ```
-   - **更新照片**：
-   ```bash
-   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json replace "张三" "/path/to/new.jpg"
-   ```
-     输出包含 `image_url` 字段。
-     - 成功：`✅🔄 **照片已更新** · xxx`，使用 `image_url` 展示照片：`![image](image_url)`
-     - 失败：`❌🙈 照片中未发现有效的人脸信息，更新失败！`
-   - **重新命名**：
-   ```bash
-   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json rename "张三" "李三"
-   ```
-     - 提示：`✏️📛 **用户名已更新** · xxx → yyy`
-   - **保留多张**：
-   ```bash
-   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json append "张三" "/path/to/extra.jpg"
-   ```
-     输出包含 `image_url` 字段。
-     - 成功：`✅➕ **新照片已追加** · xxx`，使用 `image_url` 展示照片：`![image](image_url)`
-     - 失败：`❌🙈 照片中未发现有效的人脸信息，添加失败！`
-
-### 2. 搜索用户照片
-
-**触发词**：「用照片分类器在 yy 文件夹下查找 xxx」「搜索 xxx 的照片」
-
-**流程**：
-
-1. 从用户表述中提取**用户名**和**搜索目录**。若**未指定搜索目录**，先按上文「未指定搜索目录时」列出最近 3 个日期文件夹供选择（支持「更多」展示全部），得到 `<dir>` 后再继续。
-2. 检查用户名是否存在（`check` 命令），不存在则提示：`❌🔍 **未找到该用户** · 请确认姓名后重试`
-3. 使用**子会话**执行搜索（可能耗时较长）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json search "张三" "<dir>"
-```
-（`<dir>` 为用户指定路径，或从 `list-date-folders` 选中的 `path`。）**命令返回后立刻关闭并删除该子会话。**
-输出：
-```json
-{"name": "张三", "count": 3, "results": [{"image_path": "...", "face_index": 0, "similarity": 0.85}, ...]}
-```
-4. 将结果通知到当前会话，以表格形式展示：
-   ```
-   🔎✨ **人脸搜索结果** · 👤 <用户名>
-   ───────────────────────
-   ```
-   | 🖼️ 照片路径 | 📊 相似度 |
-   |:----:|:----:|
-   | /path/to/photo.jpg | 0.85 |
-5. 展示结果后按「结果导出」执行 `pack` 生成下载链接（见 §6）；`pack` 返回后若含 `dm_lines`（向虾友推送**下载链接**的状态），须在链接展示之后**再**逐行展示（可与搜索结果本身区分开）。
-
-### 3. 直接搜索（不注册）
-
-**触发词**：「用这张照片搜索 yy 文件夹」「直接用照片查找」「不注册直接搜」
-
-**流程**：
-
-1. 获取用户提供的**照片路径**和**搜索目录**。若**未指定搜索目录**，先按「未指定搜索目录时」列出最近 3 个日期文件夹供选择（支持「更多」），得到 `<dir>` 后再继续。
-2. 使用**子会话**执行搜索（先提取人脸 embedding，再匹配，可能耗时较长）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json quick-search "/path/to/face.jpg" "<dir>"
-```
-**命令返回后立刻关闭并删除该子会话。**
-输出：
-```json
-{"success": true/false, "count": 3, "results": [...], "message": "..."}
-```
-   - `success: false` → 表示照片中未检测到有效人脸，提示：`❌🙈 **未检测到人脸** · 无法搜索`
-3. 将结果通知到当前会话，以表格形式展示：
-   ```
-   🪪🖼️ **直接搜索**（未注册）· 已用查询图匹配
-   ───────────────────────
-   ```
-   | 🖼️ 照片路径 | 📊 相似度 |
-   |:----:|:----:|
-   | /path/to/photo.jpg | 0.85 |
-4. 展示结果后按「结果导出」执行 `pack` 生成下载链接（见 §6）；`pack` 返回后若含 `dm_lines`，须在链接展示之后**再**逐行展示。
-
-### 4. 一键分类
-
-**触发词**：「用照片分类器对 xx 文件夹进行分类」「一键分类」「对这些照片按人分类」
-
-**流程**：
-
-1. 从用户表述中提取**搜索目录**。若**未指定搜索目录**，先按「未指定搜索目录时」列出最近 3 个日期文件夹供选择（支持「更多」），得到 `<dir>` 后再继续。
-2. 使用**子会话**执行分类（可能耗时较长）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json classify "<dir>"
-```
-**命令返回后立刻关闭并删除该子会话。**
-输出（节选）：
-```json
-{
-  "user_count": 2,
-  "users": {"张三": {"count": 3, "results": [...]}, "李四": {"count": 1, "results": [...]}},
-  "dm": {"张三": {"success": true, "friendId": 23725, "friendLabel": "小李"}},
-  "dm_lines": ["✅ 💌 已向虾友「小李」发送成功", "📭 「李四」暂未绑定虾友，跳过私信"]
-}
-```
-   - `dm`：仅当配置里**至少有一位用户**登记了 `friendId` 时出现；脚本在分类结束后**自动调用** `{baseDir}/scripts/send_dm_message.py`（`--user-id` = `friendId`），将**该用户本轮分类结果摘要**发出。失败时含 `"success": false` 与 `detail`。
-   - `dm_lines`：**只要本轮参与分类的用户数 ≥1 即出现**（与是否有人绑定 `friendId` 无关）。为**最终提示专用**短句数组，顺序与本轮 `users` 中用户顺序一致。句式固定：
-     - 已绑定且发送成功：`✅ 💌 已向虾友「xxx」发送成功` — **xxx** 优先为配置中的 `friendLabel`，否则为 `friendId` 数字字符串。
-     - 已绑定且发送失败：`❌ 💢 虾友「xxx」发送失败：<原因>`（原因取自 `dm` 中对应用户的 `detail`）。
-     - 未绑定 `friendId`：`📭 「<本地用户名>」暂未绑定虾友，跳过私信`。
-   - `user_count: 0` → 提示：`❌👥 **暂无注册用户** · 请先注册人脸后再分类`
-3. 将结果通知到当前会话，对每个用户分别展示：
-   ```
-   🗂️✨ **一键分类完成** · 共 👥 N 位注册用户参与匹配
-   ───────────────────────
-   ```
-   对每个有匹配结果的用户：
-   ```
-   👤✅ **张三** · 📸 匹配 M 张
-   ```
-   | 🖼️ 照片路径 | 📊 相似度 |
-   |:----:|:----:|
-   | /path/to/photo.jpg | 0.85 |
-
-   无匹配结果的用户：
-   ```
-   👤💤 **王五** · 本轮暂无匹配
-   ```
-4. **分类摘要 DM（必须在表格之后、`pack` 之前展示）**：若 `classify` 的 JSON 含 `dm_lines`（本轮**分类结果摘要**的私信状态），在分类表格**之后**单独加一块，**逐行原样**展示。示例：
-   ```
-   📬 **虾友发送状态（分类摘要）**
-   ✅ 💌 已向虾友「小李」发送成功
-   📭 「李四」暂未绑定虾友，跳过私信
-   ```
-   无 `dm_lines` 时（仅 `user_count: 0` 等异常）跳过本块。
-5. 展示结果后按「结果导出」执行 `pack` 生成下载链接（见 §6）。**`pack` 成功后还会自动向对应 `friendId` 私信「打包下载链接」**；若 `pack` 的 JSON 另含 `dm_lines`（**下载链接**的私信状态），须在下载链接展示之后**再**逐行展示，可与上一步标题区分，例如「下载链接私信状态」。
-
-### 5. 删除用户
-
-**触发词**：「删除照片分类器中 xxx 的信息」「把 xxx 从照片分类器移除」
-
-**流程**：
-
-1. 从用户表述中提取**用户名**
-2. 检查用户名是否存在（`check` 命令），不存在则提示：`❌🔍 **未找到该用户** · 请确认姓名后重试`
-3. 提示确认：`⚠️🗑️ **确认删除用户 xxx？** · 此操作不可撤销`
-   - 用户确认 →
-   ```bash
-   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json delete "张三"
-   ```
-   提示：`🗑️✨ **用户已删除** · xxx`
-   - 用户取消 → 提示：`↩️👋 **已取消删除**`
-
-### 6. 结果导出（搜索/分类完成后）
-
-搜索或分类完成后，结果已保存在 `config.json` 中。展示匹配结果表格（分类场景下若已有「分类摘要」`dm_lines`，须先展示完毕）后，**不要先弹出与导出无关的菜单**，直接执行 **`pack`** 生成下载链接（压缩包可能较大，超时默认 120 秒）。
-
-**`pack` 成功后，脚本会自动调用** `{baseDir}/scripts/send_dm_message.py`，向**已绑定 `friendId` 的注册用户**私信发送**对应用户的打包下载链接**；正文模板为：先提示「「用户名」的照片已为您送达」，再附 URL，并提醒 **24 小时内下载**、逾期链接可能失效。无 `friendId` 的用户条目会体现在返回的 `dm_lines` 里（`📭 「xxx」暂未绑定虾友，跳过私信`）。**仅 `quick-search` 结果、无注册用户名时**，无法绑定虾友，不会发链接私信。
-
-- **单用户 `search`**（指定 `--name`）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json pack --name "张三" --timeout 120
-```
-输出（节选）：`{"success": true, "url": "https://...", "zip_path": "/tmp/.../search_results.zip", "dm": {...}, "dm_lines": [...]}`（有 `friendId` 时含 `dm` / `dm_lines`）  
-成功提示：`📦🔗 **下载链接已就绪** ✨` → `<url>` → 若有 `dm_lines`，再展示「下载链接私信状态」块。
-
-- **`quick-search`（直接搜索）**：结果存于 `quick_search_result`，执行 **不带 `--name`** 的 `pack`（与仅含直接搜索结果时一致）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json pack --timeout 120
-```
-成功提示：`📦🔗 **下载链接已就绪** ✨` → `<url>`（通常**无**虾友私信，因无注册用户上下文）
-
-- **一键 `classify`**（不指定 `--name`，**每位用户单独打包**）：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json pack --timeout 120
-```
-输出示例（节选）：
-```json
-{
-  "success": true,
-  "user_urls": {"张三": "https://...", "李四": "https://..."},
-  "errors": null,
-  "dm": {"张三": {"success": true, "friendId": 23725, "friendLabel": "小李", "url": "https://..."}},
-  "dm_lines": ["✅ 💌 已向虾友「小李」发送成功", "📭 「李四」暂未绑定虾友，跳过私信"]
-}
-```
-成功提示：先逐用户展示链接，例如：
-```
-📦✨ **各用户独立下载包**
-───────────────────────
-👤 张三 📎 <url>
-👤 李四 📎 <url>
-```
-再展示 `dm_lines`（下载链接私信状态）。  
-部分失败：列出已成功链接，并对失败用户提示：`⚠️❌ **<用户名>** · 下载包生成失败：<原因>`；`dm_lines` 中亦会有对应失败说明。全部失败：`❌📦 下载链接全部失败`。
-
-`pack` 完成后，**结果导出即结束**。若用户另行要求把文件复制到本地目录，可再使用命令表中的 `copy`（非本 skill 默认流程）。
-
-### 7. 上传图片到待搜索目录
-
-**触发词**：「上传这张图片到待搜索目录」「上传这些图片到待搜索目录」「上传这些照片」「把图片放到今天目录供搜索」「把图片移到待搜索目录」
-
-**流程**：
-
-1. 获取用户提供的**图片路径**（支持单张或多张）
-2. 直接执行：
-```bash
-uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json upload-image "/path/to/a.jpg" "/path/to/b.jpg"
-```
-3. 单张时输出：`{"success": true/false, "folder_path": "/abs/path/to/images/YYYYMMDD", "file_path": "/abs/path/to/images/YYYYMMDD/a.jpg", "failed": []}`
-4. 多张时输出：`{"success": true/false, "folder_path": "/abs/path/to/images/YYYYMMDD", "uploaded": [...], "failed": [...]}`
-5. 成功后提示：`✅📤 **已放入待搜索目录** → <folder_path> ✨`；如果有失败文件，提示：`⚠️ 部分失败：` 并列出项。
-
-## Example Workflow
-
-- 用户：「把这张照片添加为张三」
-  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "张三"`
-  2. 不存在 → `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json add "张三" "/path/to/photo.jpg"`
-  3. 提示：`🎉✨ **注册成功** · 张三`
-
-- 用户：「用照片分类器在 /home/photos 下查找张三」
-  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "张三"` → 存在
-  2. 子会话执行 `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json search "张三" "/home/photos"`
-  3. 展示结果表格 → `pack --name "张三" --timeout 120` 生成下载链接（见 §6）→ 若有 `dm_lines`，展示下载链接私信状态
-
-- 用户：「用这张照片在 /home/photos 里找找有没有类似的」
-  1. 子会话执行 `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json quick-search "/tmp/face.jpg" "/home/photos"`
-  2. 成功 → 展示表格 → `pack --timeout 120`（不带 `--name`）；失败 → 提示未检测到有效人脸
-
-- 用户：「用照片分类器对 /home/album 进行分类」
-  1. 子会话执行 `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json classify "/home/album"`
-  2. 展示各用户结果（及分类摘要 `dm_lines` 若有）→ `pack --timeout 120`（多用户各一链接，见 §6）→ 展示链接及 **`pack` 返回的 `dm_lines`**（下载链接私信状态）
-
-- 用户：「删除照片分类器中李四的信息」
-  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "李四"` → 存在
-  2. 提示确认 → 用户确认 → `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json delete "李四"`
-  3. 提示：`🗑️✨ **用户已删除** · 李四`
-
-- 用户：「把这些图片放到待搜索目录」
-  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json upload-image "/tmp/a.jpg" "/tmp/b.jpg"`
-  2. 全部成功后提示：`✅📤 **已放入待搜索目录** → <folder_path> ✨`
-
-## Notes
-
-- 建议始终通过 `-c` 传入 `{baseDir}/references/config.json` 的绝对路径，避免相对路径导致找不到配置文件。
-- `search`、`quick-search` 和 `classify` 可能耗时较长（取决于搜索目录中的图片数量），应在**子会话**中执行；**结束后立即关闭并删除该子会话**，再将结果展示与 `pack` 放在**主会话**中完成。
-- `images/` 目录用于存放待搜索图片；`upload-image` 内部会创建当天目录并串行逐张处理图片。
-- 搜索过程中会在图片所在目录下创建 `.embedding` 隐藏目录缓存 embedding 结果，后续搜索同一目录会自动跳过已处理的图片。
-- `pack` 与 `copy` 均依赖 `config.json` 中保存的搜索结果（`search_result` 或 `quick_search_result` 等），须先执行 `search`、`classify` 或 `quick-search`。默认流程只需 **`pack`**；`copy` 为可选，由用户另行提出时再执行。
-- **`classify`** 会向 `friendId` 发**分类结果摘要**；**`pack`** 会向 `friendId` 发**打包下载链接**（两次私信、用途不同）；若只需其一，可后续再改脚本或配置（当前实现为两者都发）。
-- `pack` 的压缩文件存放在系统临时目录中，上传完成后可忽略清理。上传超时默认 120 秒，文件特别大时可通过 `--timeout` 增大。
-- `config.json` 中的 `query_threshold`（默认 0.7）控制人脸检测置信度阈值，`search_similarity_threshold`（默认 0.3）控制搜索匹配的最低相似度。
-- `{baseDir}` 指本 skill 根目录（如 `skills/image-classify`），调用时替换为实际绝对路径。
-- `friendId`（虾友号）与可选 `friendLabel` 写在用户条目下；**注册时**通过 `add ... --friend-id` / `--friend-label` 写入。后续若需修改可编辑 `config.json`（本 skill 未单独提供改绑子命令）。旧键名仍兼容读取。
+---
+name: image-classify
+description: 照片分类器。通过人脸识别对照片进行分类、搜索和管理。当用户说「用照片分类器查找/搜索 xxx」「对 xx 文件夹进行分类」「添加 xx 到照片分类器」「从照片分类器删除 xx」时使用。
+---
+
+# 📸 照片分类器
+
+基于人脸 embedding 相似度的照片分类系统。支持注册用户人脸、按用户搜索照片、一键全量分类、删除用户；搜索/分类结束后**生成下载链接**（`pack`）即完成结果导出。
+
+## Processing Mode
+
+**STRICT SERIAL PROCESSING ONLY** — 单次顺序执行，不拆分子任务、不并行。
+
+**子会话（耗时任务）**：`search`、`quick-search`、`classify` 在**独立子会话**中执行。**子命令结束（成功或失败）后，须立即关闭并删除该子会话**，不得保留空壳会话。后续步骤——向用户展示结果表格、执行 `pack`——一律在**当前主会话**中完成。
+
+## Prerequisites
+
+- Python 3.10+、uv
+- 依赖：`requests`, `opencv-python`, `numpy`, `sophnet_tools`（项目内置）
+- 配置文件：`{baseDir}/references/config.json`
+- 若使用 **DM 自动推送**（注册时 `--friend-id`、一键 `classify` 后推送结果），需本机存在有效 JWT：`/home/node/.openclaw/jwt.json`（与 `send_dm_message.py` 一致）
+
+## 核心概念
+
+- **`{baseDir}`**：本 skill 根目录，即 `skills/image-classify`，调用时替换为实际绝对路径。
+- **配置文件**：`{baseDir}/references/config.json`，存储所有注册用户的名称、照片路径、人脸 embedding 向量，以及可选 **DM 绑定**：`friendId`（好友 userId）、`friendLabel`（可选展示名）。旧字段 `xia_you_hao` / `xia_you_label` 仍可被脚本读取。
+- **脚本入口**：`{baseDir}/scripts/face_search.py`，通过 `uv run` 以子命令方式调用。
+- **所有命令输出均为 JSON 格式**，方便解析结果。
+
+## 通用调用格式
+
+```bash
+uv run {baseDir}/scripts/face_search.py [-c CONFIG_PATH] <command> [args...]
+```
+
+`-c` / `--config` 可选，指定配置文件路径，默认为 `references/config.json`（相对于执行目录）。建议始终传入绝对路径 `{baseDir}/references/config.json`。
+
+## 可用命令一览
+
+| 命令 | 用途 | 示例 |
+|------|------|------|
+| `check <name>` | 检查用户名是否已注册 | `check 张三` |
+| `add <name> <image> [--friend-id ID] [--friend-label 名]` | 注册新用户；可选 `friendId` 与 `friendLabel`（括号内提示用） | `add 张三 /path/photo.jpg --friend-label 小李 --friend-id 23725` |
+| `replace <name> <image>` | 替换用户照片（删除旧照片） | `replace 张三 /path/new.jpg` |
+| `append <name> <image>` | 为已有用户追加一张照片 | `append 张三 /path/extra.jpg` |
+| `rename <old> <new>` | 修改用户名 | `rename 张三 李三` |
+| `delete <name>` | 删除用户 | `delete 张三` |
+| `search <name> <dir>` | 在目录中搜索某用户的相似人脸 | `search 张三 /home/photos` |
+| `quick-search <image> <dir>` | 直接用照片搜索相似人脸（不注册） | `quick-search /tmp/face.jpg /home/photos` |
+| `classify <dir>` | 一键分类：遍历所有用户搜索全部照片 | `classify /home/photos` |
+| `copy <target> [--name N]` | （可选）将搜索结果复制到本地文件夹 | `copy /output --name 张三` |
+| `pack [--name N] [--timeout T]` | 压缩结果为 zip 并上传获取下载链接 | `pack --timeout 120` |
+| `upload <file> [--timeout T]` | 上传文件获取 URL | `upload /path/file.zip` |
+| `init-today-folder` | 创建并返回待搜索目录当天子目录 | `init-today-folder` |
+| `upload-image <file...>` | 将一张或多张图片串行剪切到待搜索目录 `images/当天日期(YYYYMMDD)` | `upload-image /tmp/a.jpg /tmp/b.jpg` |
+| `list-date-folders` | 列出待搜索根目录 `images` 下全部 `YYYYMMDD` 子文件夹（新→旧），供未指定目录时选择 | `list-date-folders` |
+
+> ⚠️ 注意：如果用户发送的图片格式为 `![image](xxx.jpg)`，需要先执行 `upload` 命令将其转换为 URL 格式后再处理。
+
+## Usage
+
+根据用户意图匹配以下操作流程：
+
+### 未指定搜索目录时（`search` / `quick-search` / `classify` 共用）
+
+待搜索根目录由脚本内 `get_images_path()` 解析（通常为仓库上级 `images`）。其下按日期命名的子目录（`YYYYMMDD`）为可选搜索范围。
+
+若用户**未说明**搜索目录（或只说「默认目录」「最近上传的」等），**不要猜测路径**，先执行：
+
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json list-date-folders
+```
+
+输出 JSON 字段说明：
+- `folders`：全部合法日期文件夹，`{ "name": "20260410", "path": "/绝对路径/20260410" }`，已按日期**从新到旧**排序
+- `preview` / `preview_n`：默认只向用户展示**最近 `preview_n` 个（默认 3 个）**即可
+- `total`：总数；若大于 `preview_n`，用户可说「更多」「全部」「列出全部」——此时用 Markdown 列出剩余项（**只展示 `name`**，不罗列每条 `path`），再请用户回复**序号**或**日期名（YYYYMMDD）**；用户若粘贴目录路径则按路径解析
+
+选定目录后，将解析出的**绝对路径**作为 `<dir>` 传入 `search` / `quick-search` / `classify`。
+
+若 `folders` 为空，提示用户在 `images` 下先上传或创建日期目录（可用 `init-today-folder`、`upload-image`），或**手动提供**任意搜索目录路径。
+
+**向用户展示候选目录时（示例模版）** — 用 Markdown 呈现，**只展示日期文件夹名**，不要把磁盘绝对路径列给用户：
+
+- 📅📂 **最近可用的日期文件夹（任选其一）**
+  - 1️⃣ 📁 `20260410`
+
+  - 2️⃣ 📁 `20260409`
+
+  - 3️⃣ 📁 `20260408`
+- 💬 请回复**序号**或**日期名**；需要查看更多请说「更多」。内部调用命令时仍使用 JSON 里的 `path` 字段。✨
+
+### 1. 添加/注册用户
+
+**触发词**：「添加 xxx 到照片分类器」「注册 xxx」「把这张照片记为 xxx」
+
+**流程**：
+
+1. 获取用户提供的**用户名**、**照片路径**，以及是否绑定 **DM 接收方**（均可选）。用户常以自然语言写出类似：**虾友：xxx，ID:23725**（虾友即 DM 对象；**23725** 即 `friendId`）。解析规则：**xxx** → `--friend-label`；**23725** → `--friend-id`（正整数，与 `send_dm_message.py` 的 `--user-id` / 接口 `userId` 一致）。可只填 `friendId`、不填展示名。
+2. 检查用户名是否已存在：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "张三"
+```
+输出：`{"exists": true/false, "name": "张三"}`
+
+3. **如果不存在** → 注册新用户（无虾友号）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json add "张三" "/path/to/photo.jpg"
+```
+若用户提供了 `friendId`，追加 `--friend-id <正整数>`；若有展示名，追加 `--friend-label "xxx"`（注意转义或引号，避免 shell 拆词）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json add "张三" "/path/to/photo.jpg" --friend-label "小李" --friend-id 23725
+```
+输出：`{"success": true/false, "message": "...", "name": "张三", "image_url": "https://...", "friendId": 23725, "friendLabel": "小李"}`（`friendId` / `friendLabel` 仅在实际传入时出现）
+   - `success: true` → 提示：`🎉✨ **注册成功** · xxx`，并使用返回的 `image_url` 展示照片：`![image](image_url)`；若返回含 `friendId` / `friendLabel`，可顺带一句已绑定 DM（不必冗长）
+   - `success: false` → 提示：`❌🙈 照片中未发现有效的人脸信息，注册失败！`
+
+4. **如果已存在** → 提示用户选择操作：
+   ```
+   ⚡👤 用户名已存在，请选择操作：
+   1️⃣ 🔄 更新照片（替换主照片）
+   2️⃣ ✏️ 重新命名
+   3️⃣ ➕ 同时保留多张照片
+   ```
+   - **更新照片**：
+   ```bash
+   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json replace "张三" "/path/to/new.jpg"
+   ```
+     输出包含 `image_url` 字段。
+     - 成功：`✅🔄 **照片已更新** · xxx`，使用 `image_url` 展示照片：`![image](image_url)`
+     - 失败：`❌🙈 照片中未发现有效的人脸信息，更新失败！`
+   - **重新命名**：
+   ```bash
+   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json rename "张三" "李三"
+   ```
+     - 提示：`✏️📛 **用户名已更新** · xxx → yyy`
+   - **保留多张**：
+   ```bash
+   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json append "张三" "/path/to/extra.jpg"
+   ```
+     输出包含 `image_url` 字段。
+     - 成功：`✅➕ **新照片已追加** · xxx`，使用 `image_url` 展示照片：`![image](image_url)`
+     - 失败：`❌🙈 照片中未发现有效的人脸信息，添加失败！`
+
+### 2. 搜索用户照片
+
+**触发词**：「用照片分类器在 yy 文件夹下查找 xxx」「搜索 xxx 的照片」
+
+**流程**：
+
+1. 从用户表述中提取**用户名**和**搜索目录**。若**未指定搜索目录**，先按上文「未指定搜索目录时」列出最近 3 个日期文件夹供选择（支持「更多」展示全部），得到 `<dir>` 后再继续。
+2. 检查用户名是否存在（`check` 命令），不存在则提示：`❌🔍 **未找到该用户** · 请确认姓名后重试`
+3. 使用**子会话**执行搜索（可能耗时较长）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json search "张三" "<dir>"
+```
+（`<dir>` 为用户指定路径，或从 `list-date-folders` 选中的 `path`。）**命令返回后立刻关闭并删除该子会话。**
+输出：
+```json
+{"name": "张三", "count": 3, "results": [{"image_path": "...", "face_index": 0, "similarity": 0.85}, ...]}
+```
+4. 将结果通知到当前会话，以表格形式展示：
+   ```
+   🔎✨ **人脸搜索结果** · 👤 <用户名>
+   ───────────────────────
+   ```
+   | 🖼️ 照片路径 | 📊 相似度 |
+   |:----:|:----:|
+   | /path/to/photo.jpg | 0.85 |
+5. 展示结果后按「结果导出」执行 `pack` 生成下载链接（见 §6）；`pack` 返回后若含 `dm_lines`（向虾友推送**下载链接**的状态），须在链接展示之后**再**逐行展示（可与搜索结果本身区分开）。
+
+### 3. 直接搜索（不注册）
+
+**触发词**：「用这张照片搜索 yy 文件夹」「直接用照片查找」「不注册直接搜」
+
+**流程**：
+
+1. 获取用户提供的**照片路径**和**搜索目录**。若**未指定搜索目录**，先按「未指定搜索目录时」列出最近 3 个日期文件夹供选择（支持「更多」），得到 `<dir>` 后再继续。
+2. 使用**子会话**执行搜索（先提取人脸 embedding，再匹配，可能耗时较长）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json quick-search "/path/to/face.jpg" "<dir>"
+```
+**命令返回后立刻关闭并删除该子会话。**
+输出：
+```json
+{"success": true/false, "count": 3, "results": [...], "message": "..."}
+```
+   - `success: false` → 表示照片中未检测到有效人脸，提示：`❌🙈 **未检测到人脸** · 无法搜索`
+3. 将结果通知到当前会话，以表格形式展示：
+   ```
+   🪪🖼️ **直接搜索**（未注册）· 已用查询图匹配
+   ───────────────────────
+   ```
+   | 🖼️ 照片路径 | 📊 相似度 |
+   |:----:|:----:|
+   | /path/to/photo.jpg | 0.85 |
+4. 展示结果后按「结果导出」执行 `pack` 生成下载链接（见 §6）；`pack` 返回后若含 `dm_lines`，须在链接展示之后**再**逐行展示。
+
+### 4. 一键分类
+
+**触发词**：「用照片分类器对 xx 文件夹进行分类」「一键分类」「对这些照片按人分类」
+
+**流程**：
+
+1. 从用户表述中提取**搜索目录**。若**未指定搜索目录**，先按「未指定搜索目录时」列出最近 3 个日期文件夹供选择（支持「更多」），得到 `<dir>` 后再继续。
+2. 使用**子会话**执行分类（可能耗时较长）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json classify "<dir>"
+```
+**命令返回后立刻关闭并删除该子会话。**
+输出（节选）：
+```json
+{
+  "user_count": 2,
+  "users": {"张三": {"count": 3, "results": [...]}, "李四": {"count": 1, "results": [...]}},
+  "dm": {"张三": {"success": true, "friendId": 23725, "friendLabel": "小李"}},
+  "dm_lines": ["✅ 💌 已向虾友「小李」发送成功", "📭 「李四」暂未绑定虾友，跳过私信"]
+}
+```
+   - `dm`：仅当配置里**至少有一位用户**登记了 `friendId` 时出现；脚本在分类结束后**自动调用** `{baseDir}/scripts/send_dm_message.py`（`--user-id` = `friendId`），将**该用户本轮分类结果摘要**发出。失败时含 `"success": false` 与 `detail`。
+   - `dm_lines`：**只要本轮参与分类的用户数 ≥1 即出现**（与是否有人绑定 `friendId` 无关）。为**最终提示专用**短句数组，顺序与本轮 `users` 中用户顺序一致。句式固定：
+     - 已绑定且发送成功：`✅ 💌 已向虾友「xxx」发送成功` — **xxx** 优先为配置中的 `friendLabel`，否则为 `friendId` 数字字符串。
+     - 已绑定且发送失败：`❌ 💢 虾友「xxx」发送失败：<原因>`（原因取自 `dm` 中对应用户的 `detail`）。
+     - 未绑定 `friendId`：`📭 「<本地用户名>」暂未绑定虾友，跳过私信`。
+   - `user_count: 0` → 提示：`❌👥 **暂无注册用户** · 请先注册人脸后再分类`
+3. 将结果通知到当前会话，对每个用户分别展示：
+   ```
+   🗂️✨ **一键分类完成** · 共 👥 N 位注册用户参与匹配
+   ───────────────────────
+   ```
+   对每个有匹配结果的用户：
+   ```
+   👤✅ **张三** · 📸 匹配 M 张
+   ```
+   | 🖼️ 照片路径 | 📊 相似度 |
+   |:----:|:----:|
+   | /path/to/photo.jpg | 0.85 |
+
+   无匹配结果的用户：
+   ```
+   👤💤 **王五** · 本轮暂无匹配
+   ```
+4. **分类摘要 DM（必须在表格之后、`pack` 之前展示）**：若 `classify` 的 JSON 含 `dm_lines`（本轮**分类结果摘要**的私信状态），在分类表格**之后**单独加一块，**逐行原样**展示。示例：
+   ```
+   📬 **虾友发送状态（分类摘要）**
+   ✅ 💌 已向虾友「小李」发送成功
+   📭 「李四」暂未绑定虾友，跳过私信
+   ```
+   无 `dm_lines` 时（仅 `user_count: 0` 等异常）跳过本块。
+5. 展示结果后按「结果导出」执行 `pack` 生成下载链接（见 §6）。**`pack` 成功后还会自动向对应 `friendId` 私信「打包下载链接」**；若 `pack` 的 JSON 另含 `dm_lines`（**下载链接**的私信状态），须在下载链接展示之后**再**逐行展示，可与上一步标题区分，例如「下载链接私信状态」。
+
+### 5. 删除用户
+
+**触发词**：「删除照片分类器中 xxx 的信息」「把 xxx 从照片分类器移除」
+
+**流程**：
+
+1. 从用户表述中提取**用户名**
+2. 检查用户名是否存在（`check` 命令），不存在则提示：`❌🔍 **未找到该用户** · 请确认姓名后重试`
+3. 提示确认：`⚠️🗑️ **确认删除用户 xxx？** · 此操作不可撤销`
+   - 用户确认 →
+   ```bash
+   uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json delete "张三"
+   ```
+   提示：`🗑️✨ **用户已删除** · xxx`
+   - 用户取消 → 提示：`↩️👋 **已取消删除**`
+
+### 6. 结果导出（搜索/分类完成后）
+
+搜索或分类完成后，结果已保存在 `config.json` 中。展示匹配结果表格（分类场景下若已有「分类摘要」`dm_lines`，须先展示完毕）后，**不要先弹出与导出无关的菜单**，直接执行 **`pack`** 生成下载链接（压缩包可能较大，超时默认 120 秒）。
+
+**`pack` 成功后，脚本会自动调用** `{baseDir}/scripts/send_dm_message.py`，向**已绑定 `friendId` 的注册用户**私信发送**对应用户的打包下载链接**；正文模板为：先提示「「用户名」的照片已为您送达」，再附 URL，并提醒 **24 小时内下载**、逾期链接可能失效。无 `friendId` 的用户条目会体现在返回的 `dm_lines` 里（`📭 「xxx」暂未绑定虾友，跳过私信`）。**仅 `quick-search` 结果、无注册用户名时**，无法绑定虾友，不会发链接私信。
+
+- **单用户 `search`**（指定 `--name`）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json pack --name "张三" --timeout 120
+```
+输出（节选）：`{"success": true, "url": "https://...", "zip_path": "/tmp/.../search_results.zip", "dm": {...}, "dm_lines": [...]}`（有 `friendId` 时含 `dm` / `dm_lines`）  
+成功提示：`📦🔗 **下载链接已就绪** ✨` → `<url>` → 若有 `dm_lines`，再展示「下载链接私信状态」块。
+
+- **`quick-search`（直接搜索）**：结果存于 `quick_search_result`，执行 **不带 `--name`** 的 `pack`（与仅含直接搜索结果时一致）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json pack --timeout 120
+```
+成功提示：`📦🔗 **下载链接已就绪** ✨` → `<url>`（通常**无**虾友私信，因无注册用户上下文）
+
+- **一键 `classify`**（不指定 `--name`，**每位用户单独打包**）：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json pack --timeout 120
+```
+输出示例（节选）：
+```json
+{
+  "success": true,
+  "user_urls": {"张三": "https://...", "李四": "https://..."},
+  "errors": null,
+  "dm": {"张三": {"success": true, "friendId": 23725, "friendLabel": "小李", "url": "https://..."}},
+  "dm_lines": ["✅ 💌 已向虾友「小李」发送成功", "📭 「李四」暂未绑定虾友，跳过私信"]
+}
+```
+成功提示：先逐用户展示链接，例如：
+```
+📦✨ **各用户独立下载包**
+───────────────────────
+👤 张三 📎 <url>
+👤 李四 📎 <url>
+```
+再展示 `dm_lines`（下载链接私信状态）。  
+部分失败：列出已成功链接，并对失败用户提示：`⚠️❌ **<用户名>** · 下载包生成失败：<原因>`；`dm_lines` 中亦会有对应失败说明。全部失败：`❌📦 下载链接全部失败`。
+
+`pack` 完成后，**结果导出即结束**。若用户另行要求把文件复制到本地目录，可再使用命令表中的 `copy`（非本 skill 默认流程）。
+
+### 7. 上传图片到待搜索目录
+
+**触发词**：「上传这张图片到待搜索目录」「上传这些图片到待搜索目录」「上传这些照片」「把图片放到今天目录供搜索」「把图片移到待搜索目录」
+
+**流程**：
+
+1. 获取用户提供的**图片路径**（支持单张或多张）
+2. 直接执行：
+```bash
+uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json upload-image "/path/to/a.jpg" "/path/to/b.jpg"
+```
+3. 单张时输出：`{"success": true/false, "folder_path": "/abs/path/to/images/YYYYMMDD", "file_path": "/abs/path/to/images/YYYYMMDD/a.jpg", "failed": []}`
+4. 多张时输出：`{"success": true/false, "folder_path": "/abs/path/to/images/YYYYMMDD", "uploaded": [...], "failed": [...]}`
+5. 成功后提示：`✅📤 **已放入待搜索目录** → <folder_path> ✨`；如果有失败文件，提示：`⚠️ 部分失败：` 并列出项。
+
+## Example Workflow
+
+- 用户：「把这张照片添加为张三」
+  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "张三"`
+  2. 不存在 → `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json add "张三" "/path/to/photo.jpg"`
+  3. 提示：`🎉✨ **注册成功** · 张三`
+
+- 用户：「用照片分类器在 /home/photos 下查找张三」
+  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "张三"` → 存在
+  2. 子会话执行 `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json search "张三" "/home/photos"`
+  3. 展示结果表格 → `pack --name "张三" --timeout 120` 生成下载链接（见 §6）→ 若有 `dm_lines`，展示下载链接私信状态
+
+- 用户：「用这张照片在 /home/photos 里找找有没有类似的」
+  1. 子会话执行 `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json quick-search "/tmp/face.jpg" "/home/photos"`
+  2. 成功 → 展示表格 → `pack --timeout 120`（不带 `--name`）；失败 → 提示未检测到有效人脸
+
+- 用户：「用照片分类器对 /home/album 进行分类」
+  1. 子会话执行 `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json classify "/home/album"`
+  2. 展示各用户结果（及分类摘要 `dm_lines` 若有）→ `pack --timeout 120`（多用户各一链接，见 §6）→ 展示链接及 **`pack` 返回的 `dm_lines`**（下载链接私信状态）
+
+- 用户：「删除照片分类器中李四的信息」
+  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json check "李四"` → 存在
+  2. 提示确认 → 用户确认 → `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json delete "李四"`
+  3. 提示：`🗑️✨ **用户已删除** · 李四`
+
+- 用户：「把这些图片放到待搜索目录」
+  1. `uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json upload-image "/tmp/a.jpg" "/tmp/b.jpg"`
+  2. 全部成功后提示：`✅📤 **已放入待搜索目录** → <folder_path> ✨`
+
+## Notes
+
+- 建议始终通过 `-c` 传入 `{baseDir}/references/config.json` 的绝对路径，避免相对路径导致找不到配置文件。
+- `search`、`quick-search` 和 `classify` 可能耗时较长（取决于搜索目录中的图片数量），应在**子会话**中执行；**结束后立即关闭并删除该子会话**，再将结果展示与 `pack` 放在**主会话**中完成。
+- `images/` 目录用于存放待搜索图片；`upload-image` 内部会创建当天目录并串行逐张处理图片。
+- 搜索过程中会在图片所在目录下创建 `.embedding` 隐藏目录缓存 embedding 结果，后续搜索同一目录会自动跳过已处理的图片。
+- `pack` 与 `copy` 均依赖 `config.json` 中保存的搜索结果（`search_result` 或 `quick_search_result` 等），须先执行 `search`、`classify` 或 `quick-search`。默认流程只需 **`pack`**；`copy` 为可选，由用户另行提出时再执行。
+- **`classify`** 会向 `friendId` 发**分类结果摘要**；**`pack`** 会向 `friendId` 发**打包下载链接**（两次私信、用途不同）；若只需其一，可后续再改脚本或配置（当前实现为两者都发）。
+- `pack` 的压缩文件存放在系统临时目录中，上传完成后可忽略清理。上传超时默认 120 秒，文件特别大时可通过 `--timeout` 增大。
+- `config.json` 中的 `query_threshold`（默认 0.7）控制人脸检测置信度阈值，`search_similarity_threshold`（默认 0.3）控制搜索匹配的最低相似度。
+- `{baseDir}` 指本 skill 根目录（如 `skills/image-classify`），调用时替换为实际绝对路径。
+- `friendId`（虾友号）与可选 `friendLabel` 写在用户条目下；**注册时**通过 `add ... --friend-id` / `--friend-label` 写入。后续若需修改可编辑 `config.json`（本 skill 未单独提供改绑子命令）。旧键名仍兼容读取。