Storage Manager

---

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. 设置环境变量：

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. 物品入库（智能匹配）

# 基础入库
storage-manager add "护照" "双肩包内层"
带物品图片入库
storage-manager add "感冒药" "电视柜左抽屉" --image="medicine.jpg"
自动匹配示例：
输入："白色行李箱" → 匹配到："白色行李箱里"
输入："厨房柜子上" → 匹配到："厨房柜子上层"

#### 2. 为新位置添加图片

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

#### 3. 物品检索

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

#### 4. 位置更新

# 更新物品位置
storage-manager update "护照" "办公桌抽屉"

使用示例

#### 场景1：新物品入库到现有位置

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

#### 场景2：新位置出现，需要拍照

# 用户输入
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         # 技能文档

数据处理流程

# 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 | 附件 | 位置图片标签 |

位置图片映射表

{
  "厨房柜子上层": "file_token_1",
  "客厅电视柜": "file_token_2",
  "卧室衣柜": "file_token_3",
  "书房书架": "file_token_4"
}

🛠️ 安装与配置

方法一：通过clawhub安装（推荐）

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 | | 入库失败 | 字段不匹配 | 检查表格字段名称和类型 |

调试命令

# 检查系统状态
storage-manager add "测试物品" "测试位置"
查看详细日志
DEBUG=1 storage-manager add "测试物品" "测试位置"

📈 版本历史

v1.0.0 - 完整版发布 (2026-04-14)

✅ 智能位置匹配系统

✅ 位置图片管理功能

✅ 一键物品入库

✅ 完整错误处理

✅ 详细文档说明

---

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