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

✨ 核心特色

🧠 智能位置匹配

• 自动匹配：>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)

• ✅ 智能位置匹配系统
• ✅ 位置图片管理功能
• ✅ 一键物品入库
• ✅ 完整错误处理
• ✅ 详细文档说明

---

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