image-sense

使用**本地 OpenAI 兼容 VLM（带视觉能力）**批量识别当前目录下的图片（jpg/png），读取图片属性后启动一个临时 Web 服务，让你在浏览器里完成批量改名。

1. 前置：配置本地模型

工具使用本地 vlm 模型，会优先读取环境变量；如未设置，会尝试从 ~/.zshrc 中解析以下变量：

export LOCAL_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxx"
export LOCAL_BASE_URL="http://127.0.0.1:8086/v1"
export LOCAL_MODEL="gemma-4-e2b-it-4bit"

说明：这是 OpenAI 兼容接口（/v1），并且模型具备视觉能力（VLM）。

2. 安装

pnpm add -g image-sense

3. 使用

在包含图片的目录下执行：

提示：工具会在 stdout 输出识别进度和每张图片读到的属性；属性读取完成后会打印 Web 访问地址。

image-sense

执行后流程如下：

1. 扫描当前目录图片
2. 调用本地 VLM 读取属性（主体/场景/人数/动作或互动/宠物/服装），并在控制台打印结果
3. 启动临时 Web 服务，打印类似：
   • 访问地址：http://127.0.0.1:xxxxx/
4. 你在浏览器里：
   • 查看 320x320 容器内的图片
   • 勾选/取消勾选图片
   • 通过顶部模板开关批量生成“目标文件名（无扩展名）”，也可手动编辑
   • 点击“执行更名”后由服务端完成改名，并在页面底部输出 undo 命令（可复制用于回滚）

3.1 识别维度（模型输出）

每张图片会被识别为以下 6 个维度（均为中文、尽量简短）：

• 主体（subject）：人物 / 猫咪 / 汽车 / 风景 / 建筑 / 食物…
• 场景（scene）：办公室/健身房/卧室/室内/花园/海边/院子里/街头/厨房/森林/公园/天空/太空…
• 人数（people）：由模型给出 personCount（人物数量）后映射为：无人 / 单人 / 双人 / 多人
• 动作或互动（action）：
  • 单人：站立/散步/健身/跑步/拍照/摆姿势…
  • 多人：散步 / 喝茶 / 烘焙 / 园艺 / 依偎 / 荡秋千 / 做饭 / 拥抱 / 聊天 / 合影 / 插花 / 玩耍…
• 宠物（pet）：如果画面中有猫/狗等宠物，则输出简短词（如：猫咪/狗狗/小猫/小狗）；没有则为空
• 服装（clothing）：尽量简洁；单人或多人都可填主角服装；无法判断可为空

3.2 默认命名算法（Web 模板）

Web 页面顶部提供文件名模板开关，默认全部开启，顺序为：

主体 - 场景 - 人数 - 动作或互动 - 宠物 - 服装

默认文件名生成规则：

1. 对每个维度做“文件名安全化”（移除空白/下划线、以及 macOS 不允许字符 /\\:*?"<>| 等）
2. 取模板中开启的维度，按顺序拼接，用 - 连接
3. 为空的维度会被跳过；如果最终为空，则使用 未命名
4. 扩展名保持不变（例如 .jpg / .png）

4. 重名处理

如果同一个文件夹下出现相同的目标文件名，服务端会自动追加后缀 _1、_2…（在扩展名前）。

5. 提示

• 建议你在改名前先备份；改名后页面底部会提供 undo 命令用于回滚。
• 按 Ctrl+C 结束服务；退出时会清理临时文件（优先移到回收站）。