物品管理 (Item Management)
用自然语言管理个人物品数据库，支持添加、查询、编辑、统计、导出和到期提醒。
功能一览
| 功能 | 说明 |
|---|
| 增删改查 | 添加/编辑/删除物品，查看清单和详情 |
| 日均成本 | 自动计算购入至今的日均花费 |
| 到期提醒 | 即将到期/已过期进度条 |
| 子物品 | 套装内物品独立管理 |
| 历史追踪 | 记录价格、数量、状态变化 |
| 导出 | 支持 CSV / JSON / HTML 三种格式 |
| 备份恢复 | JSON 格式完整备份，支持合并/完整恢复 |
| 统计报告 | 生成可打印的 HTML 报告（Ctrl+P 转 PDF） |
数据存储位置（跨平台）
用户数据存储在用户家目录下，独立于技能目录，技能更新不会丢失数据：
| 操作系统 | 数据路径 |
|---|
| Windows | C:\Users\用户名\item-management-data\ |
| macOS | ~/Library/Application Support/item-management/ |
| Linux | ~/.local/share/item-management/ |
| 自定义 | 可通过 OPENCLAW_WORKSPACE 或 XDG_DATA_HOME 环境变量指定 |
数据目录结构：
item-management-data/
items.db ← SQLite 数据库（所有物品数据）
backups/ ← JSON 备份文件夹
backup_20260428_180129.json
backup_20260428_120000.json
备份文件是纯 JSON，可以用任何文本编辑器打开，也是跨平台迁移的关键。
备份与恢复（重要！）
为什么要备份？
技能数据存在用户本地，如果重装系统/换电脑，数据会丢失。
每次重要变更后建议备份，并上传到云端。
创建备份
item backup # 一键备份到数据目录
item backup --path /path/to/backup.json # 指定路径
恢复数据
item restore # 从最新备份恢复
item restore backup_20260428_180129.json # 指定文件
item restore --merge backup.json # 合并模式（只添加不重复）
查看存储信息（含云备份）
item info # 显示数据库路径、备份列表
重要：执行 item info 后，AI 必须额外展示云备份板块。
云备份状态展示规则
AI 需要检查配置文件 ~/.qclaw/workspace/item-management-cloud-config.json（工作区目录下），按以下规则展示：
1. 配置文件不存在（未配置云备份）：
☁️ **云备份：未配置**
推荐方案：
| 方案 | 特点 |
|------|------|
| 📁 OneDrive/iCloud | 放到云盘同步文件夹，全自动同步 |
| ⏰ 定时+云盘 | OpenClaw 定时备份 + 云盘自动同步 |
| 📧 邮箱 | 备份发到自己邮箱，最简单 |
| ☁️ 微云 | 腾讯生态，扫码授权即可 |
| 🐙 GitHub Gist | 有版本历史 |
想配置的话直接说「帮我配置云备份」
2. 配置文件存在（已配置）：
读取 JSON 配置并展示当前状态：
☁️ **云备份：已配置**
- 方式：{provider}（如 onedrive / weiyun / email / gist）
- 路径/目标：{path_or_target}
- 上次云端备份：{last_backup_time}
- 状态：✅ 正常 / ❌ 需要重新授权
💡 立即备份？说「备份物品到云端」
💡 想换方案？说「帮我配置云备份」
配置文件格式（item-management-cloud-config.json）：
{
"provider": "onedrive",
"path": "D:\\OneDrive\\物品架",
"last_backup": "2026-04-28 19:30:00",
"auto_backup": true,
"cron_job_id": "job_xxx"
}
当用户成功配置云备份后，AI 必须创建/更新此配置文件。
换电脑/重装后怎么做？
- 在新设备上安装技能
- 把备份 JSON 文件传到新设备
- 运行
item restore your_backup.json 恢复所有数据
云端同步建议
备份文件（JSON）可以上传到：
- 微云/QQ网盘 - 腾讯系生态
- iCloud / OneDrive / Google Drive - 自动同步
- 邮箱附件 - 简单可靠
- GitHub Gist - 有版本控制
核心字段说明
| 字段 | 说明 |
|---|
name | 物品名称（必填） |
brand | 品牌 |
quantity | 数量（默认1） |
unit | 单位（默认"个"） |
production_date | 生产日期（YYYY-MM-DD） |
expiry_date | 保质期到期日 |
warranty_date | 保修期到期日 |
opened_date | 开封日期 |
location | 存放位置 |
notes | 备注 |
price | 单价（元） |
tags | 标签（逗号分隔） |
image_path | 图片路径 |
status | 状态：active / consumed（已用完）/ discarded（已丢弃） |
自然语言命令映射
添加物品
用户说："记录一个新物品"、"添加一个..."、"买了个..."、"记录一下"
→ 解析参数，调用 item_cli.py add
# 示例解析
item_cli("add", "SK-II 护肤精华露",
brand="SK-II", qty=1, price=899.0,
expiry="2026-10-01", location="卧室梳妆台",
opened="2025-04-01",
tags="护肤,化妆品,面部护理")
查看物品
- "查看我的物品"、"列出所有物品"、"物品清单" →
item list
- "按品牌排序" →
item list --sort brand
- "按过期日排序" →
item list --sort expiry_date
- "只看护肤类的" →
item list --tag 护肤
查看详情
- "查看某物品详情" →
item get <id>
- "物品#3 详细信息" →
item get 3
更新物品
- "把某物品数量改为2" →
item update <id> --qty 2
- "标记某物品已开封" →
item update <id> --opened 2025-04-01
- "标记某物品已用完" →
item update <id> --status consumed
删除物品
- "删除某物品" →
item delete <id>（先确认）
子物品（套装）
- "给物品5添加一个子物品：替换装" →
item sub-add 5 替换装 --qty 2
- "列出物品5的所有子物品" →
item sub-list 5
历史记录
- "查看某物品的变更历史" →
item history <item_id>
（自动记录：价格、开封日期、数量、状态变化）
到期提醒
- "哪些物品快过期了" →
item expiring --days 7（默认7天）
- "已经过期的物品" →
item expired
数据统计
- "物品统计数据"、"我有多少东西" →
item stats
（输出：总品类数、总件数、总估算价值、按月新增趋势）
导出
- "导出 CSV" →
item export --format csv
- "导出 JSON" →
item export --format json
- "导出 HTML 表格" →
item export --format html
item export --out path.csv 指定保存路径
统计报告
- "生成报告" →
item report 输出完整 HTML 页面
（含概览统计、即将到期、已过期、全量物品列表、月度趋势）
用浏览器打开后按 Ctrl+P → 另存为 PDF 即可打印
搜索
- "搜一下我有几个SK-II的" →
item search SK-II
- "找找化妆品" →
item search 化妆品
日均成本
每个物品会自动计算日均花费（单价 ÷ 购入天数），显示在「单价」下方。
- 购入当天：日均 = 单价（购入不足1天）
- 保质期至不为空时：同时显示到期倒计时进度条
调用 _date_progress(expiry_str) 生成可视化状态：
days_until > 7 → ✅ 剩余 N 天到期（正常，绿色）
0 ≤ days_until ≤ 7 → ⏳ 即将到期：还剩 N 天（黄色预警）
days_until < 0 → ⚠️ 已过期 N 天（红色警告）
expiry_date 为空 → — 状态未知
执行方式
物品架是 自然语言技能，通过对话触发即可。
触发关键词
| 意图 | 触发词（任选其一） |
|---|
| 添加物品 | 「添加一个XX」「记录一个新物品」「买个了XX」 |
| 查看清单 | 「我的物品」「物品清单」「列出所有物品」 |
| 查看统计 | 「物品统计」「我有多少东西」 |
| 搜索物品 | 「搜一下XX」「找找XX」 |
| 物品详情 | 「查看XX详情」「XX详细信息」 |
| 更新物品 | 「把XX的数量改成N」「把XX标记为已开封」 |
| 删除物品 | 「删除XX」「把手表删掉」 |
| 到期提醒 | 「哪些快过期了」「已经过期的物品」 |
| 备份恢复 | 「备份物品」「恢复物品数据」「帮我配置云备份」「备份物品到云端」 |
| 存储信息 | 「查看物品存储信息」「数据存在哪」「云备份状态」 |
| 导出报告 | 「导出CSV」「生成报告」 |
| 搜索历史 | 「查看XX的变更记录」 |
手动调试
在终端中进入技能目录后执行：
# 进入技能目录（自动定位）
cd ~/.qclaw/skills/item-management/scripts
# 查看物品
python item_cli.py list
# 添加物品
python item_cli.py add 手表 --price 200 --prod 2026-04-28
# 备份
python item_cli.py backup
💡 CLI 会自动将数据写入用户家目录（~/item-management-data/），无需指定路径，也不依赖技能目录。
输出格式要求
- 输出使用中文
- 物品列表前显示总数（如"📦 共 12 种物品"）
- 每条物品之间用空行分隔
- 统计页面数字对齐展示
- 列表需要包含所有核心字段
⚠️ 强制回复规则（必须遵守）
每次回复用户物品相关内容时，回复末尾必须包含以下两行：
*💡 试试对我说：查看物品统计 / 搜索XX / 备份物品*
*想备份数据防丢失？直接说「查看物品存储信息」*
规则说明：
- 第一行是使用提示，随机换一个有用的命令提示，如：查看所有物品 / 物品统计 / 搜索XX / 备份物品 / 哪些快过期了 / 导出报告
- 第二行是备份提示，固定文案：
*想备份数据防丢失？直接说「查看物品存储信息」*
- 两行都用 Markdown 斜体（
*...*），视觉上弱化，不抢主内容
- 没有例外，无论是添加、查看、统计、搜索、更新、删除，都必须带这两行
