Imported from QianQianLuLu1/FlashGaze (SKILL.md). Install upstream with npx skills add QianQianLuLu1/FlashGaze. Copyright stays with the author.

FlashGaze 图片评分技能

触发场景

当用户表达以下意图时激活此技能：

• "帮我筛选/选出好的照片"
• "评估这批图片的质量"
• "给这些图片打分"
• "哪些照片质量比较高"
• "批量评价图片"
• "清理这个目录里质量差的图片"
• "删除评分低的图片"

三种工作模式

前置安装

pip install -e .
# 如需 MCP Server 功能
pip install -e ".[mcp]"
# 如需使用非 qwen 的 VLM 提供商（openai / anthropic / ollama）
pip install -e ".[vlm-multi]"

零依赖兼容：默认 qwen 提供商走原有 requests.post 路径，无需安装 litellm，老用户配置零修改。 仅当显式指定 --vlm-provider openai/anthropic/ollama 时才需要 pip install -e ".[vlm-multi]"。

VLM API Key（可选，--no-vlm 模式不需要）：

# Windows PowerShell
$env:FLASHGAZE_API_KEY="sk-your-key"
# Linux / macOS
export FLASHGAZE_API_KEY="sk-your-key"

模式一：目录评分（CLI）

零成本快速初筛（推荐首选）

flashgaze <图片目录路径> --top 30 --json --no-vlm

VLM 精筛（需要 API Key）

flashgaze <图片目录路径> --top 30 --json

筛选并复制到新目录

flashgaze <图片目录路径> --top 30 --json --export

阈值模式（分数 >= 75 入选）

flashgaze <图片目录路径> --threshold 75 --json

模式二：上传图片评分（MCP）

AI Agent 收到用户上传的图片后，传入路径列表进行评分：

# MCP 工具调用示例
score_uploaded_images(
    image_paths=["C:/photos/img1.jpg", "C:/photos/img2.jpg"],
    top=5,
    no_vlm=True
)

返回 JSON 包含 summary.skipped 字段，列出不存在或不支持格式的路径。

模式三：工作空间清理（MCP）

对工作空间目录下的图片评分，原地删除低分图：

安全保证

• 仅删除 workspace 目录内的文件，绝不影响目录外任何资料
• 双重路径穿越检查：解析真实路径后用 relative_to 校验，防止 ../ 或符号链接逃逸
• 默认 dry_run=True：先试运行确认要删除哪些文件，确认后设 dry_run=False 才真正删除
• 删除前再次校验：每个文件删除前都重新检查路径边界

使用流程

# 第一步：试运行，查看将要删除哪些文件
cleanup_workspace_images(
    workspace="C:/my-photos",
    top=30,
    no_vlm=True,
    dry_run=True  # 默认值，只报告不删除
)

# 第二步：确认后实际删除
cleanup_workspace_images(
    workspace="C:/my-photos",
    top=30,
    no_vlm=True,
    dry_run=False  # 真正删除低分图
)

阈值模式

cleanup_workspace_images(
    workspace="C:/my-photos",
    threshold=75.0,  # 分数低于 75 的图片将被删除
    no_vlm=True,
    dry_run=False
)

返回结构

{
  "status": "success",
  "code": 0,
  "summary": {
    "workspace": "C:/my-photos",
    "total": 120,
    "selected": 30,
    "to_delete": 90,
    "deleted": 90,
    "mode": "actual_delete",
    "elapsed_ms": 15420
  },
  "kept_images": [...],
  "deleted_files": ["img_001.jpg", "img_002.jpg", ...],
  "blocked_files": []
}

blocked_files 列出因安全检查被拦截的文件（路径在工作空间外等）。

MCP Server 配置

在 AI 工具的 MCP 配置中添加：

{
  "mcpServers": {
    "flashgaze": {
      "command": "python",
      "args": ["-m", "flashgaze.mcp_server"]
    }
  }
}

MCP 工具列表

返回码

Agent 调用要点

1. stdout 取 JSON，stderr 取日志：两个流互不污染，Agent 可靠解析
2. 先判返回码：returncode == 0 才解析 stdout
3. 设超时：大批量建议 timeout=600 秒
4. 可复现：--no-vlm 模式下同一张图多次评分完全一致
5. 降级健壮：单张图片损坏不中断，该图 error 字段记录原因，整体仍返回 0
6. 清理模式先 dry_run：先 dry_run=True 确认待删文件列表，再 dry_run=False 执行
7. VLM 字段可能为空：vlm_reason / vlm_provider 在 --no-vlm 或 VLM 失败时为空串，解析时需容错
8. 多 VLM 提供商路由：非 qwen 提供商需目标机器已 pip install -e ".[vlm-multi]"，否则自动降级为纯 CV，不报错

CLI 选项速查

VLM 提供商

通过 LiteLLM 统一调用层支持 4 个 VLM 提供商，无任何厂商专属适配代码。默认 qwen 走原有 requests.post 路径，零新依赖、100% 向后兼容；其他 3 个提供商经 LiteLLM 路由（需 pip install -e ".[vlm-multi]"）。

环境变量配置示例

# 1. 通义千问（默认，100% 向后兼容，无需 litellm）
export FLASHGAZE_VLM_PROVIDER=qwen
export FLASHGAZE_API_KEY=sk-xxxxxxxx
export FLASHGAZE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
export FLASHGAZE_MODEL=qwen-vl-max

# 2. OpenAI GPT-4o（需 litellm）
export FLASHGAZE_VLM_PROVIDER=openai
export FLASHGAZE_API_KEY=sk-xxxxxxxx
export FLASHGAZE_API_BASE=https://api.openai.com/v1
export FLASHGAZE_MODEL=gpt-4o

# 3. Anthropic Claude 3（需 litellm，api_base 留空走 LiteLLM 默认）
export FLASHGAZE_VLM_PROVIDER=anthropic
export FLASHGAZE_API_KEY=sk-ant-xxxxxxxx
export FLASHGAZE_API_BASE=
export FLASHGAZE_MODEL=claude-3-5-sonnet-20241022

# 4. Ollama 本地 VLM（需 litellm，无需真实 key）
export FLASHGAZE_VLM_PROVIDER=ollama
export FLASHGAZE_API_KEY=ollama
export FLASHGAZE_API_BASE=http://localhost:11434
export FLASHGAZE_MODEL=llama3.2-vision

降级行为

• 未安装 litellm 但 provider != qwen：VLM 调用返回 ok=False，error="litellm_not_installed"，主流程自动回退纯 CV
• 非法 provider / scene 值：在 build_config 阶段回退到默认值并记 warning，不抛异常
• VLM 网络错误 / 超时 / 解析失败：重试耗尽后返回 ok=False，vlm_adjustment=0.0，vlm_reason=""，批处理不中断

场景化评分

--scene 参数切换 VLM 提示词，针对不同场景使用差异化评分侧重点。auto（默认）由 VLM 自行判断场景，与原版单一提示词语义一致。

# 人像目录使用场景化提示词
flashgaze ./portraits --scene portrait --top 20 --json

# 风光目录
flashgaze ./landscapes --scene landscape --top 30 --json

auto 模式不会额外调用 VLM 做场景识别（避免双倍 token 消耗），而是把"请自行判断"写进提示词，由 VLM 一次完成。

评分可解释性

每张经过 VLM 调整的图片在 JSON / CSV 输出中携带两个新字段：

• vlm_reason — VLM 评分理由（≤20 字中文），如 背景虚化 / 逆光剪影 / 技术失误。--no-vlm 或 VLM 失败时为空串
• vlm_provider — 产生本次调整的 VLM 提供商标识，如 qwen / openai。--no-vlm 或 VLM 失败时为空串

{
  "file": "DSC_0042.jpg",
  "score": 92.75,
  "vlm_adjustment": 5.0,
  "vlm_reason": "背景虚化突出主体",
  "vlm_provider": "qwen"
}

硬上限约束：

• vlm_reason 入库前裁剪到 20 字（按字符数计，不按字节）
• vlm_adjustment 始终 clamp 到 [-vlm_max_adjustment, +vlm_max_adjustment]（默认 ±10）
• VLM 响应格式异常时降级为 vlm_adjustment=0.0 + 空理由，不抛异常

可选 CV 增强维度

四个增强维度默认全部关闭，依赖缺失时优雅降级（不报错，对应字段返回 null/0/false）。

启用 composition/noise/color 任一维度但未提供 --weights 时，会自动注入合理默认权重（如全启用 → sharpness 0.35 / exposure 0.25 / composition 0.20 / noise 0.10 / color 0.10）。