sophhub 0.1.0

package/skills/builtin/inventory-management/SKILL.md

@@ -0,0 +1,241 @@
+---
+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`，无需额外确认项目。