---
name: inventory-management
description: "库存管理工具。当用户需要导入商品表、管理库存、出入库操作、查询库存、低库存预警、查看出入库记录、库存盘点或导出数据时使用。"
---

# Inventory Management（库存管理）

支持多项目、自定义字段的库存管理 skill。用户可上传 CSV/XLSX 文件创建项目，系统自动解析表头生成字段配置，支持出入库、库存查询、低库存预警、变动记录、数据导出等全流程操作。

## 重要原则

- **字段由用户定义**：商品字段不是预设的，而是从用户上传的文件表头自动解析。每个项目有独立的字段配置。
- **关键字段必须明确**：每个项目需要指定「唯一标识字段」（如 SKU/编号）和「库存数量字段」（如 库存/数量），才能正常执行出入库操作。
- **删除操作需确认**：删除商品或删除项目前，必须向用户确认，不得自动执行。
- **出库校验**：出库数量不得超过当前库存，超出时提示库存不足。
- **信息不全时主动询问**：如用户说「入库 100 个」但未说明哪个商品或哪个项目，需先确认。
- **单项目时可省略 --project**：若用户只有一个项目，所有命令可省略 `--project` 参数，自动使用唯一项目。

## 流程概览

| 步骤 | 说明 | 脚本子命令 |
|------|------|------------|
| 自然语言建表 | 用户描述字段，直接创建空项目（无需文件） | `create` |
| 从文件建表 | 上传 CSV/XLSX 文件，解析表头创建项目并导入数据 | `init` |
| 追加导入 | 向已有项目追加/更新商品数据 | `import` |
| 项目管理 | 查看/删除项目 | `project-list` / `project-delete` |
| 字段管理 | 查看/新增/删除自定义字段 | `field-list` / `field-add` / `field-delete` |
| 商品管理 | 添加/编辑/删除/查询/详情 | `product-add` / `product-edit` / `product-delete` / `product-list` / `product-detail` |
| 入库 | 采购入库/退货入库/其他入库 | `stock-in` |
| 出库 | 销售出库/退货出库/报损/其他 | `stock-out` |
| 库存查询 | 查全部/单个/低库存预警/按字段筛选 | `stock-query` |
| 变动记录 | 查看出入库历史流水 | `stock-log` |
| 导出 | 导出商品或流水为 CSV | `export` |

## 自然语言建表（create）

**当用户用自然语言描述要管理的商品和字段时，优先使用 `create` 命令**，无需用户提供文件。将用户描述的字段转换为 `--fields` 参数即可。

```bash
# 简单格式：逗号分隔字段名，类型自动推断（含"数量/价/库存"的→number，含"日期"的→date，其余→text）
python3 {baseDir}/scripts/inventory.py create --project 服装仓库 --fields "SKU,名称,颜色,尺码,库存数量,售价" --key-field SKU --stock-field 库存数量

# 带类型的简单格式：用冒号指定类型
python3 {baseDir}/scripts/inventory.py create --project 食品仓库 --fields "条码:text,品名:text,保质期:date,库存:number,进价:number,售价:number" --key-field 条码 --stock-field 库存

# JSON 格式（完全控制字段定义）
python3 {baseDir}/scripts/inventory.py create --project 原材料 --fields '[{"name":"物料编号","type":"text"},{"name":"名称","type":"text"},{"name":"库存数量","type":"number"},{"name":"单价","type":"number"}]' --key-field 物料编号 --stock-field 库存数量
```

- `--project`：项目名称（必填）。
- `--fields`：字段定义（必填），支持两种格式：
  - **简单格式**：`"字段1,字段2,字段3"` 或 `"字段1:类型,字段2:类型"`，类型可选 `text`（默认）/ `number` / `date`。
  - **JSON 格式**：`'[{"name":"字段名","type":"类型"},...]'`。
  - 不指定类型时根据字段名自动推断：含「数量/库存/价/金额/成本」→ number，含「日期/时间/保质期」→ date，其余 → text。
- `--key-field`：唯一标识字段名（可选，自动推断匹配「SKU/编码/编号/货号」的字段）。
- `--stock-field`：库存数量字段名（可选，自动推断匹配「库存/数量」的字段）。
- 创建后项目为空表（0 条商品），可通过 `product-add` 逐条添加或 `import` 批量导入。

**使用场景示例**：
- 用户说「帮我建一个服装库存表，要有 SKU、名称、颜色、尺码、库存和售价」→ 用 `create` 命令
- 用户说「我有一个 Excel 表，帮我导入」→ 用 `init` 命令
- 用户说「帮我管理一下仓库库存」但没提供文件 → 先问用户需要哪些字段，再用 `create` 命令

## 从文件初始化项目（init）

当用户提供了 CSV 或 XLSX 文件时使用。脚本自动解析表头生成字段配置，并导入全部数据。

```bash
# 自动推断关键字段（脚本会从表头猜测唯一标识和库存字段，输出推断结果供确认）
python3 {baseDir}/scripts/inventory.py init --project 原材料 --file /path/to/materials.csv

# 明确指定关键字段（跳过推断）
python3 {baseDir}/scripts/inventory.py init --project 原材料 --file /path/to/materials.csv --key-field 物料编号 --stock-field 库存数量

# XLSX 文件同理
python3 {baseDir}/scripts/inventory.py init --project 成品 --file /path/to/products.xlsx --key-field SKU --stock-field 库存
```

- 支持 `.csv`（自动检测 UTF-8/GBK 编码）和 `.xlsx` 格式。
- `--project`：项目名称（必填），同名项目不可重复创建。
- `--key-field`：唯一标识字段名（可选，不传时脚本自动推断并输出结果）。
- `--stock-field`：库存数量字段名（可选，不传时脚本自动推断并输出结果）。
- 若自动推断失败或存在歧义，脚本会输出所有列名并提示用户手动指定。
- **输出**：项目创建成功，导入 N 条商品，字段列表，关键字段配置。

**自动推断规则**：
- 唯一标识：优先匹配包含「SKU」「编码」「编号」「货号」「条码」「ID」的列名。
- 库存数量：优先匹配包含「库存」「数量」「stock」「qty」的列名。

## 追加导入（import）

向已有项目追加数据。key 已存在的行更新，新 key 的行插入。

```bash
python3 {baseDir}/scripts/inventory.py import --project 原材料 --file /path/to/new_materials.csv
```

- 文件表头必须与项目字段配置一致（允许少列，不允许多出未知列）。
- **输出**：新增 N 条，更新 M 条，跳过 K 条（附原因）。

## 项目管理

```bash
# 查看所有项目
python3 {baseDir}/scripts/inventory.py project-list

# 删除项目（会同时删除该项目下所有商品和变动记录）
python3 {baseDir}/scripts/inventory.py project-delete --project 原材料
```

- `project-list` 输出：项目名称、商品数量、字段数、创建时间。
- `project-delete` 需用户确认后再执行，**不得自动执行**。

## 字段管理

```bash
# 查看某项目的字段配置
python3 {baseDir}/scripts/inventory.py field-list --project 成品

# 为项目新增一个自定义字段
python3 {baseDir}/scripts/inventory.py field-add --project 成品 --name 保质期 --type date

# 删除单个字段
python3 {baseDir}/scripts/inventory.py field-delete --project 食品仓库 --name 条码

# 批量删除多个字段（逗号分隔）
python3 {baseDir}/scripts/inventory.py field-delete --project 食品仓库 --name "条码,保质期,进价,售价"
```

- `field-add`：`--type` 可选 `text`（默认）、`number`、`date`。新增字段后已有商品该字段值为空。
- `field-delete`：`--name` 传要删除的字段名，多个用逗号分隔。**唯一标识字段和库存数量字段不可删除**。删除后会同步清除所有商品中对应字段的数据。

## 商品管理

```bash
# 添加单个商品（JSON 格式传入字段值）
python3 {baseDir}/scripts/inventory.py product-add --project 成品 --data '{"SKU":"BT-003","商品名":"蓝牙音箱","库存":0,"售价":299}'

# 编辑商品
python3 {baseDir}/scripts/inventory.py product-edit --project 成品 --key BT-003 --set '{"售价":259,"商品名":"蓝牙音箱Pro"}'

# 删除商品（软删除）
python3 {baseDir}/scripts/inventory.py product-delete --project 成品 --key BT-003

# 查询商品列表
python3 {baseDir}/scripts/inventory.py product-list --project 成品
python3 {baseDir}/scripts/inventory.py product-list --project 成品 --search 蓝牙
python3 {baseDir}/scripts/inventory.py product-list --project 成品 --filter 颜色=红色

# 商品详情
python3 {baseDir}/scripts/inventory.py product-detail --project 成品 --key BT-001
```

- `product-add`：`--data` 为 JSON 字符串，字段名须与项目字段配置匹配。唯一标识字段和库存字段必填。
- `product-edit`：`--set` 为 JSON 字符串，只传需要修改的字段。
- `product-delete`：软删除（标记 status=deleted），向用户确认后再执行。
- `product-list`：展示表格，包含所有自定义字段 + 当前库存。`--search` 对所有文本字段模糊匹配，`--filter` 精确筛选。
- `product-detail`：展示单个商品全部字段及最近 10 条库存变动记录。

## 入库

```bash
python3 {baseDir}/scripts/inventory.py stock-in --project 原材料 --key M-001 --quantity 500
python3 {baseDir}/scripts/inventory.py stock-in --project 原材料 --key M-001 --quantity 500 --type purchase --remark "供应商A第三批"
```

- `--key`：商品唯一标识值（必填）。
- `--quantity`：入库数量，正整数（必填）。
- `--type`：`purchase`（采购，默认）、`return`（退货入库）、`other`（其他）。
- `--remark`：备注（可选）。
- **输出**：入库成功，商品 xxx 库存 100 → 600。

## 出库

```bash
python3 {baseDir}/scripts/inventory.py stock-out --project 成品 --key BT-001 --quantity 5
python3 {baseDir}/scripts/inventory.py stock-out --project 成品 --key BT-001 --quantity 5 --type sale --remark "订单#12345"
```

- `--type`：`sale`（销售，默认）、`return`（退货出库）、`damage`（报损）、`other`（其他）。
- 出库数量不得超过当前库存，超出时报错并提示当前库存量。

## 库存查询

```bash
# 查询全部库存
python3 {baseDir}/scripts/inventory.py stock-query --project 成品

# 查询单个商品
python3 {baseDir}/scripts/inventory.py stock-query --project 成品 --key BT-001

# 低库存预警
python3 {baseDir}/scripts/inventory.py stock-query --project 成品 --low-stock

# 按字段筛选
python3 {baseDir}/scripts/inventory.py stock-query --project 成品 --filter 颜色=红色
```

- 输出表格包含：唯一标识、所有自定义字段、当前库存、是否低于阈值。
- `--low-stock`：仅展示库存 ≤ 低库存阈值的商品。

## 变动记录

```bash
# 查看某商品的全部变动
python3 {baseDir}/scripts/inventory.py stock-log --project 成品 --key BT-001

# 按时间范围查询
python3 {baseDir}/scripts/inventory.py stock-log --project 成品 --from 2026-01-01 --to 2026-03-31

# 按方向筛选
python3 {baseDir}/scripts/inventory.py stock-log --project 成品 --direction in
```

- 输出字段：时间、商品标识、方向（入库/出库）、类型、数量、变动前→变动后、备注。

## 导出

```bash
# 导出商品数据为 CSV
python3 {baseDir}/scripts/inventory.py export --project 成品 --type products --output /path/to/output.csv

# 导出变动记录为 CSV
python3 {baseDir}/scripts/inventory.py export --project 成品 --type logs --output /path/to/logs.csv
```

- `--type`：`products`（商品数据）或 `logs`（变动记录）。
- `--output`：输出文件路径（可选，默认输出到脚本同目录下 `export_<项目名>_<类型>_<时间戳>.csv`）。

## 脚本与配置

- 脚本路径：`scripts/inventory.py`
- 数据库路径：默认 `~/.openclaw/workspace/inventory-management/inventory.db`（目录不存在时自动创建），可通过环境变量 `INVENTORY_DB_PATH` 自定义。
- 依赖：`openpyxl`（仅 XLSX 导入时需要，CSV 无第三方依赖）。

## 何时向用户确认

- 用户说「入库/出库」但未指定项目名或商品标识时，先确认。
- 用户说「删除商品」或「删除项目」时，展示将被删除的内容并等待确认。
- `init` 时若自动推断的关键字段存在歧义（如多个列都包含「编号」），须列出候选并让用户选择。
- 用户只有一个项目时，操作命令可省略 `--project`，无需额外确认项目。
