Storage Manager

飞书收纳管家完整版 - 智能位置匹配 + 位置图片管理 + 一键入库

Security Scan

The skill implements the described Feishu storage features, but it fails to declare required credentials and embeds hard-coded Feishu credentials/tokens in the code — meaning if you don't supply your own credentials the skill will send your images/records to whatever account those defaults belong to.

Purpose & Capability

Name/description, SKILL.md, and code all match: this is a Feishu Bitable + image upload storage manager, so network access to open.feishu.cn and image upload capabilities are expected. However the registry metadata did not declare the FEISHU_* environment variables even though SKILL.md and the code require them. That mismatch (metadata says no required env vars; documentation and code require credentials) is a coherence problem and surprising for a skill that integrates with an external service.

Instruction Scope

SKILL.md instructs the agent/user to set FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_BITABLE_TOKEN, FEISHU_TABLE_ID and to run CLI commands. The runtime code uploads files and creates records via Feishu APIs (open.feishu.cn). The instructions do not ask for unrelated system data, but the code will accept image files from disk and upload them to Feishu — expected for purpose. The concern is that the runtime will proceed using built-in defaults (hard-coded credentials) if you don't set env vars, causing data to be sent to a third-party account without explicit notice.

Install Mechanism

There is no platform install spec (instruction-only), which is lower risk. An included install.sh exists and will install requests (pip3), chmod files, and create a symlink under ~/.local/bin/storage-manager — standard for a CLI tool. No remote downloads or archive extraction from untrusted URLs were seen. Install script writes into the user home (~/.local/bin) which is typical for user-level CLI installs.

Credentials

The skill logically needs Feishu credentials, and SKILL.md documents FEISHU_APP_ID/FEISHU_APP_SECRET/FEISHU_BITABLE_TOKEN/FEISHU_TABLE_ID. But the skill metadata did not declare these as required. Worse, multiple code files (e.g., final_integrated.py, complete_system.py, location_image_manager.py) include default hard-coded values for app_id, app_secret, bitable_token and table_id. Those embedded secrets are disproportionate and risky: if you don't override them, your uploads/records will go to the account tied to those defaults.

Persistence & Privilege

The skill is not force-enabled (always:false) and does not request system-wide privileges. The install script creates a user-level symlink and example .env file — typical for CLI tools. The skill does not modify other skills' configurations or require platform-level persistence beyond a user-installed CLI.

Scan Findings in Context

[hardcoded-credentials] unexpected: Multiple source files (final_integrated.py, complete_system.py, etc.) set default values for FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_BITABLE_TOKEN, FEISHU_TABLE_ID. For a tool that integrates with a user's Feishu app, embedding default credentials is unexpected and dangerous because it can redirect data to a third-party account.

[network-endpoint-open-feishu] expected: The code contacts https://open.feishu.cn open-apis for token, drive upload, and bitable record creation — this is expected for a Feishu Bitable integration.

[local-install-script-symlink] expected: install.sh creates a symlink in ~/.local/bin/storage-manager and installs requests if missing; this behavior is typical for CLI installation but modifies user home.

What to consider before installing

What to consider before installing: - Do not rely on the code's defaults. The package includes hard-coded Feishu credentials/tokens in several Python files; if you don't supply your own FEISHU_* environment variables, images and records will be uploaded to the account tied to those defaults. Treat that as potential data exfiltration. - Recommended immediate steps before use: 1) Inspect the code files (final_integrated.py, complete_system.py, location_image_manager.py, etc.) and remove or replace any hard-coded FEISHU_APP_ID / FEISHU_APP_SECRET / FEISHU_BITABLE_TOKEN / FEISHU_TABLE_ID values. Ensure they are not present in the deployed copy. 2) Provide your own Feishu credentials via environment variables (FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_BITABLE_TOKEN, FEISHU_TABLE_ID) and verify the code reads them (it does, but defaults exist). Test with throwaway data first. 3) If you do not control the Feishu app the code would use (i.e., you don't know the owner of the hard-coded credentials), do not run the skill with real/personal images or sensitive data. 4) Consider running the tool in an isolated environment (container/VM) and monitor network calls (to confirm they go to your configured app and not elsewhere). 5) If you will install via the provided install.sh, review the script and remove or modify the symlink creation step if you prefer not to alter ~/.local/bin automatically. - If you are not comfortable auditing or editing the code, avoid installing this skill or request a version from the author that does not contain embedded secrets and that properly declares required environment variables in its metadata.

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

✨ 核心特色

🧠 智能位置匹配

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

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

---

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