Storage Manager

SKILL.md

---
name: Storage Manager - Complete Edition
description: 飞书收纳管家完整版 - 智能位置匹配 + 位置图片管理 + 一键入库
read_when:
  - 需要记录物品存放位置
  - 需要智能匹配相似位置
  - 需要为位置添加视觉标签
  - 需要管理个人物品收纳
metadata: {"clawdbot":{"emoji":"🗃️","requires":{"bins":["python3"]}}}
allowed-tools: Bash(storage-manager:*)
---

# 🗃️ 飞书收纳管家 - 完整版

## ✨ 核心特色

### 🧠 **智能位置匹配**
- **自动匹配**：>75%相似度自动匹配现有位置
- **无需确认**：全程自动化，无需用户二次确认
- **智能识别**：自动区分"蓝色行李箱"和"白色行李箱"

### 📸 **位置图片管理**
- **位置标签**：为每个位置添加视觉标签图片
- **智能提醒**：新位置自动要求拍照
- **图片复用**：相同位置自动使用现有位置图片
- **位置视觉化**：通过图片快速识别位置

### 🔧 **三大核心功能**
1. **物品入库工具** - 智能位置匹配 + 图片关联
2. **物品检索工具** - 快速查找物品位置
3. **位置更新工具** - 智能更新位置信息

## 🚀 功能详解

### **1. 智能位置匹配系统**
#### 工作原理：
```
用户输入："1号纸箱" 
→ 系统搜索：匹配到现有位置"1号纸箱里"（相似度100%）
→ 自动选择：使用现有位置，无需确认
→ 入库完成：物品记录到匹配的位置
```

#### 匹配规则：
- **阈值：** 75%相似度自动匹配
- **示例：**
  - "白色行李箱" → 匹配到 "白色行李箱里" (100%)
  - "电视柜左边抽屉" → 匹配到 "电视柜左抽屉" (92%)
  - "蓝色行李箱" → 创建新位置 (颜色不同)
  - "2号纸箱" → 创建新位置 (数字不同)

### **2. 位置图片管理系统**
#### 工作流程：
```
1. 新位置出现 → 系统提示需要拍照
2. 用户上传位置图片 → 系统保存映射
3. 后续物品入库相同位置 → 自动关联位置图片
4. 位置图片缓存 → 提升使用效率
```

#### 使用场景：
- **厨房柜子** → 上传柜子照片作为位置标签
- **客厅电视柜** → 上传电视柜照片
- **卧室衣柜** → 上传衣柜照片
- **办公桌抽屉** → 上传抽屉照片

## 📋 使用指南

### **准备工作**
1. 设置环境变量：
```bash
export FEISHU_APP_ID="your_app_id"
export FEISHU_APP_SECRET="your_app_secret"
export FEISHU_BITABLE_TOKEN="your_bitable_token"
export FEISHU_TABLE_ID="your_table_id"
```

### **基础命令**

#### **1. 物品入库（智能匹配）**
```bash
# 基础入库
storage-manager add "护照" "双肩包内层"

# 带物品图片入库
storage-manager add "感冒药" "电视柜左抽屉" --image="medicine.jpg"

# 自动匹配示例：
# 输入："白色行李箱" → 匹配到："白色行李箱里"
# 输入："厨房柜子上" → 匹配到："厨房柜子上层"
```

#### **2. 为新位置添加图片**
```bash
# 当新位置被创建时，系统会提示需要拍照
# 上传位置图片：
storage-manager add-location-photo "2号纸箱" --image="box_location.jpg"
```

#### **3. 物品检索**
```bash
# 查找物品位置
storage-manager search "梳子"

# 返回结果：
# 🔍 找到 3 条记录:
#   1. 梳子 (位置: 1号纸箱里, 有图片附件)
#   2. 测试梳子 (位置: 测试位置, 有图片附件)
#   3. 测试物品-梳子 (位置: 测试位置-1号纸箱, 有图片附件)
```

#### **4. 位置更新**
```bash
# 更新物品位置
storage-manager update "护照" "办公桌抽屉"
```

### **使用示例**

#### **场景1：新物品入库到现有位置**
```bash
# 用户输入
storage-manager add "牙刷" "白色行李箱"

# 系统处理
[智能匹配] 匹配到现有位置: '白色行李箱' -> '白色行李箱里' (100%)
[API] 记录创建成功
✅ 物品入库成功!
   物品: 牙刷
   位置: 白色行李箱里
```

#### **场景2：新位置出现，需要拍照**
```bash
# 用户输入
storage-manager add "游戏机" "书房书架"

# 系统处理
[智能匹配] 创建新位置: '书房书架'
[位置图片] ⚠️ 新位置需要拍照: '书房书架'

# 系统提示
📸 需要位置拍照!
   位置: 书房书架
   下一步: 请上传位置图片后重新提交

# 用户上传位置图片
storage-manager add-location-photo "书房书架" --image="bookshelf.jpg"

# 系统处理
[位置图片] '书房书架' -> 图片token: XXXXXXXXXXXXXX
✅ 位置图片添加成功!
   位置: 书房书架
   文件token: XXXXXXXXXXXXXX

# 重新入库
storage-manager add "游戏机" "书房书架"
```

## 🏗️ 技术架构

### **核心模块**
```
📦 storage-manager/
├── 🧠 SmartLocationMatcher     # 智能位置匹配
├── 📸 LocationImageManager    # 位置图片管理  
├── 🔧 FeishuStorageManager   # 飞书API集成
├── 🎯 cli_final.py           # 命令行接口
└── 📚 SKILL_final.md         # 技能文档
```

### **数据处理流程**
```python
# 1. 位置匹配
location, is_existing = matcher.match_location(user_input)

# 2. 位置图片检查
if not is_existing and image_manager.needs_photo(location):
    return {"status": "needs_location_photo"}

# 3. 创建记录
fields = {
    "Item_Name": item_name,
    "Location": location,
    "Image": item_image_token,        # 物品图片
    "Location_Image": location_image_token  # 位置图片
}

# 4. 入库完成
create_record(fields)
```

## 📊 数据结构

### **飞书多维表格结构**
| 字段名 | 类型 | 说明 |
|--------|------|------|
| **AI收纳管家-物品位置记录** | 文本 | 物品名称 |
| **Location** | 文本 | 存放位置（智能匹配） |
| **Image** | 附件 | 物品图片 |
| **Location_Image** | 附件 | 位置图片标签 |

### **位置图片映射表**
```json
{
  "厨房柜子上层": "file_token_1",
  "客厅电视柜": "file_token_2",
  "卧室衣柜": "file_token_3",
  "书房书架": "file_token_4"
}
```

## 🛠️ 安装与配置

### **方法一：通过clawhub安装（推荐）**
```bash
clawhub install storage-manager-complete
```

### **方法二：手动安装**
1. 复制技能文件到技能目录
2. 安装依赖：`pip3 install requests`
3. 配置环境变量

### **配置要求**
1. **飞书应用权限：**
   - 多维表格读写权限
   - 文件上传权限
   - 云文档访问权限

2. **环境要求：**
   - Python 3.6+
   - requests >= 2.25.0
   - 飞书自建应用凭证

## 🎯 最佳实践

### **位置拍照技巧**
1. **角度一致**：相同类型的位置使用相似拍摄角度
2. **光线充足**：确保图片清晰可见
3. **背景简洁**：避免杂乱背景干扰识别
4. **距离适中**：拍摄距离能让物体清晰可见

### **物品命名规范**
1. **简洁明确**：如"护照"、"钥匙"、"充电器"
2. **避免歧义**：如"白色药瓶"、"蓝色充电线"
3. **统一格式**：保持命名风格一致

### **位置命名规范**
1. **结构清晰**：如"1号纸箱里"、"电视柜左抽屉"
2. **分级命名**：如"厨房/上层柜子/左抽屉"
3. **描述准确**：如"双肩包内层拉链袋"

## 🔧 故障排除

### **常见问题**
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| **上传失败** | 网络问题/权限不足 | 检查网络，确认应用权限 |
| **匹配错误** | 相似度过高 | 调整阈值，检查位置命名 |
| **图片不显示** | 文件类型不支持 | 确认图片格式为jpg/png |
| **入库失败** | 字段不匹配 | 检查表格字段名称和类型 |

### **调试命令**
```bash
# 检查系统状态
storage-manager add "测试物品" "测试位置"

# 查看详细日志
DEBUG=1 storage-manager add "测试物品" "测试位置"
```

## 📈 版本历史

### **v1.0.0 - 完整版发布 (2026-04-14)**
- ✅ 智能位置匹配系统
- ✅ 位置图片管理功能
- ✅ 一键物品入库
- ✅ 完整错误处理
- ✅ 详细文档说明

---

**🎯 系统目标：让收纳变得简单、智能、可视化！** 🗃️✨