@qinsilk/scm-agent-tools 0.1.0 → 0.2.0

package/docs/cli.md

@@ -38,6 +38,17 @@ scm-agent update
 
 从 npm 重新安装最新版（`npm install -g @qinsilk/scm-agent-tools@latest`）；技能与命令行一起更新。
 
+## docs — 查看说明文档
+
+```
+scm-agent docs                                   # 列出包内文档与它们的本机绝对路径
+scm-agent docs api --find cutBedState            # 只输出包含该关键词的行
+scm-agent docs api --print                       # 输出完整文档
+```
+
+包内有两份文档：`cli`（本文件，讲命令与参数）与 `api`（接口返回字段字典，讲字段含义、取值枚举、单位、为空的原因）。
+AI 想知道某个字段是什么意思时用 `--find`，不要整份读入上下文。
+
 ## goods — 商品
 
 ```
@@ -83,6 +94,18 @@ scm-agent design ie-list --from 2026-10-01 --to 2026-10-24           # 按开发
 
 设计款状态值：2设计中 3待确定 4修改中 5审核通过 6取消 15开发池 16版型资产库。`design list` 的 `--dateType` 决定日期区间作用的时间字段：update更新时间（默认）/ create创建时间 / dev开发时间；`design ie-list` 的 `--dateType` 只有 dev开发时间（默认）/ create创建时间。IE 核价行中 `materials` 物料行、`processFees` 工序费用行、`costFees` 特殊工艺费用行、`accountItems` 其他费用行；无供应商资料权限时供应商字段为空，工序开启隐藏价格时单价为空（与网页可见范围一致）。
 
+## design-order — 版单（旗舰版功能）
+
+```
+scm-agent design-order list --sn A123                  # 关键词：款号/名称/版单号/备注/货号（至少给一项条件）
+scm-agent design-order list --states 1,2 --from 2026-10-01 --to 2026-10-24    # 按状态与下版日期区间
+scm-agent design-order list --node 纸样                 # 当前节点为纸样的版单
+scm-agent design-order list --overdue pattern           # 纸样逾期的版单（sweep 为车版逾期）
+scm-agent design-order detail --sn FS1024001            # 版单详情（也可 --id <版单id>）
+```
+
+版单状态值：1未开始 2进行中 3已结束 4废版 9撤销 10审批中 12审批拒绝；审版状态（`--review-state`）：2未设置审版 3待审 4已审。列表默认只查未开始/进行中/审批中（与网页一致），要查已结束、废版、撤销的版单需显式传 `--states`；按版单号查详情不受该默认限制。`--dateType` 决定日期区间作用的时间字段：business下版日期（默认）/ create创建 / update更新 / finish预计完成 / delivery交付。详情返回节点进度（`nodes`）、打版数量明细（`dtRows`，颜色×尺码×数量）、BOM 物料行（`bomRows`）、尺码指示（`parts`）、工艺要求（`techniques`）、工序（`workProcesses`）与该设计款全部版单（`serialOrders`）。版单为旗舰版专属功能，未开通的企业返回 482 与提示文案；供应商字段与工序单价按用户权限遮蔽（与网页可见范围一致）。
+
 ## log — 数据变动日志与接口日志
 
 ```
@@ -124,6 +147,55 @@ scm-agent report <报表名> [参数] [--out 输出目录]
 | `goods-first-order` | 商品首单面料工序单价 Excel（最小公倍数合并单元格） | `--sn --limit` |
 
 各报表的详细说明、文件名规则与注意事项见同名技能的 SKILL.md（`skills/<中文名>/SKILL.md`）。
+报表要用的接口字段含义见 [api.md](api.md)。
+
+## data — 取报表数据（自定义报表用）
+
+```
+scm-agent data                                    # 列出全部数据集与必填条件
+scm-agent data <数据集> [参数] [--page N] [--limit N] [--json]
+```
+
+官方报表格式固定；用户想按自己公司的口径重新统计时，用 `data` 取原始数据，再由 AI 计算与排表。
+数据集对应官方报表内部使用的那批报表数据接口，权限、限流与报表完全相同（每 Key 每分钟 30 次、每天 600 次）。
+
+三条固定规则：
+
+1. **必填条件不满足时不发请求**，报错里带一条可复制的示例命令。
+2. **日期跨度上限 92 天**，超过直接报错；要更久就拆成几段。
+3. **分页数据集一次只取一页**，末尾提示还有多少条，用 `--page N` 翻页；不自动翻页。
+
+| 数据集 | 必填条件 | 用途 |
+|---|---|---|
+| `company-config` | 无 | 物料小数位、是否启用生产批次号 |
+| `goods-rich` | `--sn` 或 `--search-key` | 商品档案、价格、库存、首单面料、翻单信息；`--on-sale -1` 含停用款 |
+| `goods-bom` | `--id` | 单商品 BOM 全量（物料行、工序单价、尺寸表） |
+| `sku-inventory` | `--storehouse` 或 `--all-storehouses` 二选一 | 单品库存；只含已转大货商品；`--all-storehouses` 是全部仓库合计 |
+| `produce-cost` | `--from --to` | 生产成本（每行含五类成本明细） |
+| `produce-material` | `--from --to` | 物料需求（在途与缺口） |
+| `produce-store-in` | `--from --to` | 生产入库单列表 |
+| `produce-store-in-detail` | `--sn` | 生产入库单详情（明细与委外加工费） |
+| `store-in-statistics` | `--from --to` | 成品入库统计（行级含颜色尺码与金额） |
+| `ticket-statistics` | `--from --to` | 菲票统计（领包人、部门、交货状态） |
+| `factory-evaluation` | `--from --to` | 按加工厂聚合的单数、裁床数、按时交货率 |
+| `supplier-list` | 无 | 供应商名录（对账第一步，取供应商 id） |
+| `supplier-balance` | `--supplier-id --from --to` | 单供应商对账 11 表 |
+| `work-processes` | `--sn` | 生产单工序节点（id 用于查明细） |
+| `work-process-detail` | `--work-process-id` | 单个工序节点的汇报记录 |
+| `material-data` | `--sns`（最多 20 个） | 批量物料占用与使用状态 |
+
+两点限制要如实告诉用户：
+
+- 关键词参数都是单值模糊匹配，「统计这 5 个款」要分 5 次查询。
+- 跨数据集关联（比如采购单与入库单按单号对上）要分两次取数再本地对齐，算错的风险由 AI 承担；这类需求优先用官方报表。
+
+各数据集的字段含义、取值枚举与为空原因见 [api.md](api.md) 的「数据集：」章节。
+
+## 自己做报表时怎么查字段
+
+官方报表之外，用户希望按自己公司的口径做报表或统计时，先用 `--json` 看返回结构，再用
+`scm-agent docs api --find <字段名>` 确认字段含义、取值枚举、单位与为空的原因。
+`api.md` 覆盖了全部命令与数据集的字段。
 
 ## 写命令的确认方式（所有写命令通用）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qinsilk/scm-agent-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "秦丝生产ERP AI 助手 CLI：供 AI Agent 查询商品、物料、生产单、物料采购单数据",
   "bin": {
     "scm-agent": "./cli/scm-agent.js"
@@ -9,7 +9,7 @@
     "cli/",
     "skills/",
     "reports/",
-    "docs/cli.md"
+    "docs/"
   ],
   "engines": {
     "node": ">=18"

package/skills/qinsilk-scm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qinsilk-scm
-description: 查询秦丝生产ERP数据：商品、物料、生产单（含裁床等工序进度）、物料采购单、设计款与IE核价，并生成官方报表（生产日报、生产节点看板、生产成本报表、服装成品盘存表、供应商对账等 16 个），还能查数据变动日志（谁在什么时候改了什么、通过什么操作改的），以及员工管理与权限管理（创建员工、给角色增加或移除权限）。当用户说「查生产单」「A123 完成裁床了吗」「最近的物料采购单」「找一下叫XX的物料」「设计款列表」「这款的IE核价」「WL1002 是谁改的」「这个名字什么时候改的」「生成生产日报」「导出服装成品盘存表」「跟XX厂出对账单」「帮我创建名称为张三的员工」「帮我给仓库管理员增加XX的YY权限」「帮我给张三去掉XX权限」等涉及生产ERP数据或员工权限的问题时使用。
+description: 查询秦丝生产ERP数据：商品、物料、生产单（含裁床等工序进度）、物料采购单、设计款与IE核价、版单（打版工单与节点进度），并生成官方报表（生产日报、生产节点看板、生产成本报表、服装成品盘存表、供应商对账等 16 个），还能查数据变动日志（谁在什么时候改了什么、通过什么操作改的），以及员工管理与权限管理（创建员工、给角色增加或移除权限），也支持按用户自己的口径做个性化报表（查接口字段含义、取值枚举与单位）。当用户说「查生产单」「A123 完成裁床了吗」「最近的物料采购单」「找一下叫XX的物料」「设计款列表」「这款的IE核价」「A123 的版单到哪个节点了」「上周下的版单」「WL1002 是谁改的」「这个名字什么时候改的」「生成生产日报」「导出服装成品盘存表」「跟XX厂出对账单」「帮我创建名称为张三的员工」「帮我给仓库管理员增加XX的YY权限」「帮我给张三去掉XX权限」「我想按我们公司的口径做一张统计表」「这个字段是什么意思」「官方报表格式不合适，帮我重新排一份」等涉及生产ERP数据或员工权限的问题时使用。
 ---
 
 # 秦丝生产ERP 查询与管理
@@ -25,23 +25,54 @@ description: 查询秦丝生产ERP数据：商品、物料、生产单（含裁
 | 某张采购单的明细 | `scm-agent material-purchase detail --sn <采购单号>` |
 | 设计款列表 / 款 A123 的设计进度 / 最近的设计款 | `scm-agent design list --sn A123`（日期筛选 `--dateType update\|create\|dev --from 2026-10-01 --to 2026-10-24`，至少给一项条件） |
 | 这款的IE核价 / 每个颜色的核价明细 / 导出IE核价 | `scm-agent design ie-list --sn A123`（`--dateType dev\|create`，可不带条件全量翻页） |
+| 版单列表 / 款 A123 的版单 / 上周下的版单 | `scm-agent design-order list --sn A123`（`--states` 逗号分隔状态：1未开始 2进行中 3已结束 4废版 9撤销 10审批中 12审批拒绝；`--node 纸样` 按当前节点；`--overdue pattern\|sweep` 纸样/车版逾期；`--dateType business下版（默认）\|create\|update\|finish\|delivery`；至少给一项条件） |
+| A123 的版单到哪个节点了 / 版单的打版数量、BOM、工艺要求 | `scm-agent design-order detail --sn <版单号>`（也可 `--id <版单id>`；返回节点进度、打版数量明细、BOM、尺码指示、工艺要求与同款全部版单） |
 | 生成/导出报表（日报、看板、盘存表、对账单、成本报表等） | `scm-agent report <报表名>`（全部报表见 `scm-agent report --help`；每个报表有同名中文技能，含参数与输出说明，优先按对应技能执行） |
 | WL1002 是谁改的 / 这个名称什么时候改的 / 改动记录 | 两步：① `scm-agent log db-change --keywords WL1002`（可加 `--table scm_material --from 2026-09-01`，至少给一项条件，返回时间倒序的变动行：操作人、操作类型、变动字段值）② 需要知道具体操作入口时，取某行的 `requestId` 执行 `scm-agent log api --request-id <请求标识>`，得到操作内容与接口路径 |
 | 创建员工 / 建子账号 | `scm-agent user add --name 张三 --login-name abcd --password 1234 --roles 设计师,版师`（先预览，用户同意后加 `--confirm`） |
 | 张三有哪几个角色 / 查员工角色 / 张三的 uid | 两步：① `scm-agent user search --name 张三`（按姓名/手机号/工号模糊，拿到 uid，同名时按部门区分）② `scm-agent user detail --uid <uid>`（返回角色列表） |
 | 查角色 / 角色有哪些权限 | `scm-agent role list`、`scm-agent role detail --name 设计师`（返回权限清单与使用该角色的用户） |
 | 给仓库管理员增加XX的YY权限 / 去掉权限 | `scm-agent role add-permission --name 仓库管理员 --permissions "XX的YY"` 或 `role remove-permission`（先预览，用户同意后加 `--confirm`；`--permissions` 可给多个，逗号分隔） |
+| 这个字段是什么意思 / 返回里的 XX 是什么 / 想自己做报表 | `scm-agent docs api --find <字段名>`（输出该字段的含义、取值枚举、单位与为空的原因） |
+| 按我们公司的口径出统计表 / 把 BOM、库存、对账原始数据给我 | `scm-agent data --list` 选数据集再取数（必填条件见输出；日期跨度上限 92 天；一次一页） |
 | 列出有哪些权限 / 权限叫什么名字 | `scm-agent permission list --keyword 查看` |
 
 - 列表默认每页 20 条，加 `--limit 100 --page N` 翻页；需要精确解析时加 `--json`。
 - 生产单详情中的工序进度：`workProcesses` 数组里 `core=2` 的是裁床工序；单据级 `cutBedState` 含义：1不含裁床 2待裁床 3裁床中 4已完成。状态值见命令输出的列头注释。
 - IE 核价是设计款×颜色一行的明细：`materials` 物料行、`processFees` 工序费用行、`costFees` 特殊工艺费用行、`accountItems` 其他费用行；无供应商资料权限时供应商字段为空，工序开启隐藏价格时单价为空，如实说明即可，不要猜测。
+- 版单是旗舰版功能：企业未开通旗舰版时命令返回「版单管理为旗舰版专属功能」，向用户如实转述并建议在网页确认开通，不要当成工具故障。版单列表默认只查未开始/进行中/审批中（与网页一致），要查已结束、废版、撤销的版单需显式传 `--states`；按版单号查详情不受该默认限制。详情里的供应商字段与工序单价同样受用户权限遮蔽，为空时如实说明。
 - report 命令会生成文件（可能耗时几分钟，逐单取数内置节流），完成后向用户汇报文件路径与关键统计，不要把文件内容粘贴到对话。
 - 数据变动日志的关键词按完整词匹配变动数据（用完整货号 WL1002 查询能命中，只输入 WL 查不到）；默认查近 30 天，更早的加 `--from`；操作时间没有请求标识的旧记录显示 `-` 且无法查接口日志。返回「还有更多」时可用提示的 `--line-num/--scroll-id` 续查。子账号查接口日志只能看到自己发起的请求（他人请求标识查到空是正常权限行为，与网页一致）。
 - 权限不足提示（如「权限不足，请联系管理员设置「商品管理的查看」权限」）引号内是**一整段权限中文名**，把它原样作为 `--permissions` 参数即可，不要拆开或改写。
 - **权限备注会重名**（真实环境 931 项菜单里有 48 个重名备注，最典型的是「商品管理的查看」对应按设计师、跟单员、品牌、设计助理判断四个变体）。命令按「菜单 id → 权限 key → 备注精确 → 唯一包含」的顺序解析，命中多项时不猜，会报错列出带**标题、权限 key、菜单 id** 的候选。此时把候选转述给用户，让他选一个后用权限 key 或菜单 id 重新提交；不要自己挑一个继续。
 - 角色名支持精确或唯一前缀匹配；有歧义时命令会报错列出候选，让用户选择后用 `--id` 重试。
 
+## 用户要自己做报表时（官方报表之外）
+
+用户说「我想按我们公司的口径统计一张表」「官方报表不是我要的格式，你帮我重新排一份」
+「这个字段是什么意思」时，按下面四步做，不要凭字段名猜含义：
+
+1. 先想清楚要什么数据：单据类（生产单、采购单）用查询命令加 `--json` 看结构，
+   例如 `scm-agent produce detail --sn <单号> --json`；BOM、库存、对账、统计这类
+   查询命令没有的数据，用 `scm-agent data --list` 选数据集。
+2. `data` 命令的必填条件写在 `--list` 输出里，缺条件会直接报错并给示例命令；
+   日期跨度上限 92 天，要更久就按季度拆段，分几次查再合并。
+3. 用 `scm-agent docs api --find <字段名>` 查字段含义、取值枚举、单位与为空的原因。
+   不要 `--print` 整份文档——它有两千多行，会占满上下文，只查需要的那几个字段。
+   「数据集：」开头的章节是 `data` 命令的，每节开头有一张「常用字段」摘要表，做统计先看它。
+4. 字段说明里写「无某某权限时为空」的，空值表示当前账号看不到，不是没有数据；
+   写「仅详情接口返回」的，列表里恒为 null。这两种都不能当成 0 统计。
+
+**取数的两条限制要如实告诉用户**：
+
+- 关键词参数一次只能给一个词，「统计这 5 个款」是 5 次查询，先说明耗时。
+- `data` 一次只取一页（默认 20 条，`--limit 100` 到顶），末尾会提示还有多少条；
+  要全量时逐页取，取完再算，不要边取边猜。
+
+**哪些需求该回到官方报表**：需要跨数据集关联（采购单与入库单按单号对上）、
+需要服务端算好的口径（按时交货率以外的复杂聚合）、或数据量明显超过几十页时，
+官方报表更可靠；如实说明，不要用近似字段拼。
+
 ## 写操作铁律（所有写命令通用）
 
 本节适用于全部写命令：当前是 `user add`、`role add-permission`、`role remove-permission`，以后新增的写命令同样遵守。