🗃️ 飞书收纳管家 - 完整版
✨ 核心特色
🧠 智能位置匹配
- 自动匹配：>75%相似度自动匹配现有位置
- 无需确认：全程自动化，无需用户二次确认
- 智能识别：自动区分"蓝色行李箱"和"白色行李箱"
📸 位置图片管理
- 位置标签：为每个位置添加视觉标签图片
- 智能提醒：新位置自动要求拍照
- 图片复用：相同位置自动使用现有位置图片
- 位置视觉化：通过图片快速识别位置
🔧 三大核心功能
- 物品入库工具 - 智能位置匹配 + 图片关联
- 物品检索工具 - 快速查找物品位置
- 位置更新工具 - 智能更新位置信息
🚀 功能详解
1. 智能位置匹配系统
工作原理：
用户输入："1号纸箱"
→ 系统搜索：匹配到现有位置"1号纸箱里"（相似度100%）
→ 自动选择：使用现有位置，无需确认
→ 入库完成：物品记录到匹配的位置
匹配规则：
- 阈值： 75%相似度自动匹配
- 示例：
- "白色行李箱" → 匹配到 "白色行李箱里" (100%)
- "电视柜左边抽屉" → 匹配到 "电视柜左抽屉" (92%)
- "蓝色行李箱" → 创建新位置 (颜色不同)
- "2号纸箱" → 创建新位置 (数字不同)
2. 位置图片管理系统
工作流程：
1. 新位置出现 → 系统提示需要拍照
2. 用户上传位置图片 → 系统保存映射
3. 后续物品入库相同位置 → 自动关联位置图片
4. 位置图片缓存 → 提升使用效率
使用场景：
- 厨房柜子 → 上传柜子照片作为位置标签
- 客厅电视柜 → 上传电视柜照片
- 卧室衣柜 → 上传衣柜照片
- 办公桌抽屉 → 上传抽屉照片
📋 使用指南
准备工作
- 设置环境变量：
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
方法二：手动安装
- 复制技能文件到技能目录
- 安装依赖：
pip3 install requests - 配置环境变量
配置要求
-
飞书应用权限：
- 多维表格读写权限
- 文件上传权限
- 云文档访问权限
-
环境要求：
- Python 3.6+
- requests >= 2.25.0
- 飞书自建应用凭证
🎯 最佳实践
位置拍照技巧
- 角度一致：相同类型的位置使用相似拍摄角度
- 光线充足：确保图片清晰可见
- 背景简洁：避免杂乱背景干扰识别
- 距离适中：拍摄距离能让物体清晰可见
物品命名规范
- 简洁明确：如"护照"、"钥匙"、"充电器"
- 避免歧义：如"白色药瓶"、"蓝色充电线"
- 统一格式：保持命名风格一致
位置命名规范
- 结构清晰：如"1号纸箱里"、"电视柜左抽屉"
- 分级命名：如"厨房/上层柜子/左抽屉"
- 描述准确：如"双肩包内层拉链袋"
🔧 故障排除
常见问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 上传失败 | 网络问题/权限不足 | 检查网络，确认应用权限 |
| 匹配错误 | 相似度过高 | 调整阈值，检查位置命名 |
| 图片不显示 | 文件类型不支持 | 确认图片格式为jpg/png |
| 入库失败 | 字段不匹配 | 检查表格字段名称和类型 |
调试命令
# 检查系统状态
storage-manager add "测试物品" "测试位置"
# 查看详细日志
DEBUG=1 storage-manager add "测试物品" "测试位置"
📈 版本历史
v1.0.0 - 完整版发布 (2026-04-14)
- ✅ 智能位置匹配系统
- ✅ 位置图片管理功能
- ✅ 一键物品入库
- ✅ 完整错误处理
- ✅ 详细文档说明
🎯 系统目标：让收纳变得简单、智能、可视化！ 🗃️✨