@qinsilk/scm-agent-tools 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# scm-agent-tools —— 让 AI 帮你查秦丝生产ERP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+配合秦丝生产ERP「AI 助手」使用的命令行工具与 AI 技能。装好之后，你对 AI 助手说一句话就能查数据：
+
+- 「查一下款 A123 的生产单」
+- 「A123 完成裁床了吗」
+- 「帮我看下最近的物料采购单」
+- 「找一下叫华达呢的物料」
+
+也能一句话生成官方报表文件：
+
+- 「生成今天的生产日报」
+- 「导出近一个月的工厂评估报表」
+- 「跟明达厂出一份对账单」
+- 「导出服装成品盘存表」
+
+官方技能库共 16 个报表技能（生产日报、生产节点看板、生产单工序跟进表、服装成品盘存表、生产成本报表、供应商对账导出等），全部只读、开箱即用；你还可以让 AI 按自己公司的业务定制专属报表。
+
+## 你需要先准备
+
+一个生产ERP账号，并在网页右上角「AI 助手」页面生成一个 AI Key（页面有一键复制的话术，把它粘贴给你的 AI 助手即可全自动安装；下文是手动安装步骤）。
+
+## 手动安装
+
+电脑需要 Node.js 18+。终端执行：
+
+```bash
+npm install -g @qinsilk/scm-agent-tools
+scm-agent skills install
+scm-agent login --key qsk-你的Key
+scm-agent status
+```
+
+看到「生产ERP CLI 已配置完成」就成功了。国内安装慢时加 `--registry=https://registry.npmmirror.com`。
+
+## 常见问题
+
+| 你看到的 | 怎么办 |
+|---|---|
+| AI Key 无效 / 已过期 / 已吊销 | 回生产ERP网页「AI 助手」页面重新生成，再执行一次 login |
+| 权限不足 | 这是账号本身没有该数据的权限，找管理员开通 |
+| 请求过于频繁 | 稍等一分钟再用 |
+| 想切断工具的全部权限 | 网页「AI 助手」页面对应 Key 点「吊销」，立即生效 |
+
+## 隐私
+
+AI Key 只保存在你自己的电脑（`~/.scm-agent/config.json`，仅本用户可读）；工具只能查询你本人在网页上有权限看的数据；所有查询会被系统日志记录。
+
+全部命令的详细说明（给你或你的 AI 看）：[docs/cli.md](docs/cli.md)。

package/cli/api.js

@@ -0,0 +1,114 @@
+// HTTP 访问层：AI Key 换令牌、令牌缓存与自动续期、错误翻译。
+// 使用 Node 18 内置 fetch，零第三方依赖。
+const { readConfig, writeConfig } = require('./config');
+
+/** 服务端业务错误码到用户可读文案的映射 */
+const ERROR_TEXT = {
+  481: 'AI Key 无效或已过期，请在生产ERP网页「AI 助手」页面重新生成',
+  482: '权限不足：当前用户没有访问该数据的权限',
+  483: 'AI Key 已吊销，请在生产ERP网页「AI 助手」页面重新生成',
+  484: '请求过于频繁，请稍后再试',
+};
+
+/** 令牌提前 5 分钟续期，避免请求途中过期 */
+const TOKEN_REFRESH_AHEAD_MS = 5 * 60 * 1000;
+
+/**
+ * 用 AI Key 换取访问令牌并保存到配置。
+ * 失败时抛出带用户可读 message 的 Error，不重试（避免放大爆破限制）。
+ */
+async function login(key, server) {
+  const response = await request(server, 'POST', '/api/agent/v1/token', { key }, { auth: false });
+  const config = { server, key, accessToken: response.accessToken, tokenExpiresAt: Date.now() + response.expiresIn * 1000, userInfo: { userName: response.userName, companyName: response.companyName, scopeText: response.scopeText } };
+  writeConfig(config);
+  return response;
+}
+
+/**
+ * 带认证调用业务接口。令牌临近过期时自动重新交换。
+ */
+async function call(method, apiPath, queryParams = {}) {
+  const config = requireConfig();
+  let current = ensureFreshToken(config);
+  let result;
+  try {
+    result = await request(config.server, method, apiPath, buildQuery(queryParams), { token: (await current).accessToken });
+  } catch (e) {
+    // 令牌失效时强制刷新一次再重试（服务器重启、Redis 清空等场景）
+    if (e.code === 481) {
+      const refreshed = await login(config.key, config.server);
+      result = await request(config.server, method, apiPath, buildQuery(queryParams), { token: refreshed.accessToken });
+    } else {
+      throw e;
+    }
+  }
+  return result;
+}
+
+/**
+ * 确保令牌可用：临近或已过期时重新交换。返回带有效令牌的配置。
+ */
+async function ensureFreshToken(config) {
+  if (!config.accessToken || !config.tokenExpiresAt || config.tokenExpiresAt - Date.now() < TOKEN_REFRESH_AHEAD_MS) {
+    const response = await login(config.key, config.server);
+    return { ...config, accessToken: response.accessToken };
+  }
+  return config;
+}
+
+function requireConfig() {
+  const config = readConfig();
+  if (!config || !config.key || !config.server) {
+    throw new Error('尚未配置。请先执行：scm-agent login --key qsk-xxxx [--server https://scm.qinsilk.com]');
+  }
+  return config;
+}
+
+function buildQuery(params) {
+  const clean = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null && v !== '') {
+      clean[k] = v;
+    }
+  }
+  return clean;
+}
+
+/**
+ * 底层请求。服务端统一返回 { status, message, data }：
+ * status === 200 视为成功返回 data；否则抛出带 code 的 Error。
+ */
+async function request(server, method, apiPath, body, { token, auth = true } = {}) {
+  const url = new URL(apiPath, server);
+  const headers = { 'Content-Type': 'application/json' };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  let response;
+  if (method === 'GET') {
+    if (body && Object.keys(body).length) {
+      for (const [k, v] of Object.entries(body)) {
+        url.searchParams.set(k, String(v));
+      }
+    }
+    response = await fetch(url, { headers });
+  } else {
+    response = await fetch(url, { method, headers, body: JSON.stringify(body) });
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch (e) {
+    throw new Error(`服务器响应异常（HTTP ${response.status}）：${server}`);
+  }
+  if (payload.status === 200) {
+    return payload.data;
+  }
+  const error = new Error(ERROR_TEXT[payload.status] || payload.message || `请求失败（${payload.status}）`);
+  error.code = payload.status;
+  throw error;
+}
+
+module.exports = { login, call, request, requireConfig, ERROR_TEXT };

package/cli/commands/log.js

@@ -0,0 +1,152 @@
+// 日志查询命令族：db-change 按关键词查数据库变动日志，api 按请求标识查接口日志。
+// 典型用法是两步：先用 db-change 查到「谁在什么时候改了什么」，再用返回的
+// requestId 查 api 得到「通过什么接口操作」。默认输出人类可读表格；--json 输出原始 JSON。
+const { call } = require('../api');
+const { printTable } = require('../table');
+
+/** 毫秒时间戳转本地时间文本，取不到时显示 - */
+function formatTime(ms) {
+  if (ms === null || ms === undefined) {
+    return '-';
+  }
+  const date = new Date(ms);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} `
+    + `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+/** data 是对象时列出变动字段名，帮助不展开 JSON 就看出改了什么 */
+function fieldSummary(data) {
+  if (data === null || data === undefined) {
+    return '-';
+  }
+  if (typeof data === 'object' && !Array.isArray(data)) {
+    return Object.keys(data).join(',');
+  }
+  return String(data);
+}
+
+const log = {
+  command: 'log',
+  describe: '查询数据变动日志与接口日志',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'db-change',
+        describe: '数据库变动日志（按关键词/表名/操作人查，至少给一项条件，时间倒序）',
+        builder: (y) => y
+          .option('keywords', { describe: '关键词，逗号分隔（如物料货号 WL1002），只匹配变动数据，多个词都要命中', type: 'string' })
+          .option('table', { describe: '数据库表名（如 scm_material）', type: 'string' })
+          .option('uid', { describe: '操作人用户id（可先用 user-list 或上一条日志的 uid）', type: 'number' })
+          .option('request-id', { describe: '请求标识：查同一请求的全部变动', type: 'string' })
+          .option('from', { describe: '开始日期（yyyy-MM-dd），默认近 30 天', type: 'string' })
+          .option('to', { describe: '结束日期（yyyy-MM-dd）', type: 'string' })
+          .option('limit', { describe: '本批条数（默认 20，最大 100）', type: 'number' })
+          .option('line-num', { describe: '续查行号（来自上一次返回）', type: 'string' })
+          .option('scroll-id', { describe: '续查游标（来自上一次返回）', type: 'string' }),
+        handler: (argv) => runLog(argv, async () => {
+          if (!argv.keywords && !argv.table && !argv.uid && !argv.requestId) {
+            throw new Error('请至少给一项条件：--keywords、--table、--uid 或 --request-id');
+          }
+          const params = {
+            keywords: argv.keywords,
+            table: argv.table,
+            uid: argv.uid,
+            requestId: argv.requestId,
+            from: argv.from,
+            to: argv.to,
+            limit: argv.limit,
+            lineNum: argv.lineNum,
+            scrollId: argv.scrollId,
+          };
+          Object.keys(params).forEach((key) => params[key] === undefined && delete params[key]);
+          const data = await call('GET', '/api/agent/v1/log/db-change', params);
+          const rows = data.rows.map((row) => ({
+            time: formatTime(row.operationTime),
+            operator: row.userName || row.uid || '-',
+            operation: row.operationType,
+            table: row.table,
+            fields: fieldSummary(row.data),
+            requestId: row.requestId || '-',
+            _row: row,
+          }));
+          return {
+            rows,
+            data,
+            columns: [
+              { field: 'time', label: '时间' },
+              { field: 'operator', label: '操作人' },
+              { field: 'operation', label: '操作' },
+              { field: 'table', label: '表名' },
+              { field: 'fields', label: '变动字段' },
+              { field: 'requestId', label: '请求标识' },
+            ],
+          };
+        }),
+      })
+      .command({
+        command: 'api',
+        describe: '接口日志（按请求标识查同一请求的接口操作，标识来自 db-change 的返回）',
+        builder: (y) => y
+          .option('request-id', { describe: '请求标识（db-change 返回的 requestId 原值）', demandOption: true, type: 'string' }),
+        handler: (argv) => runLog(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/log/api', { requestId: argv.requestId });
+          const rows = data.map((row) => ({
+            time: formatTime(row.time),
+            operator: row.operatorName || '-',
+            description: row.description || '-',
+            methodPath: row.methodPath || '-',
+            device: row.device || '-',
+            _row: row,
+          }));
+          return {
+            rows,
+            data,
+            columns: [
+              { field: 'time', label: '时间' },
+              { field: 'operator', label: '操作人' },
+              { field: 'description', label: '操作内容' },
+              { field: 'methodPath', label: '接口路径' },
+              { field: 'device', label: '设备' },
+            ],
+          };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：db-change 或 api');
+  },
+};
+
+/** 输出表格与续查提示；--json 输出原始数据；异常输出可读文案并以非 0 退出 */
+async function runLog(argv, task) {
+  try {
+    const { rows, data, columns } = await task();
+    if (argv.json) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    if (rows.length === 0) {
+      console.log('（无数据）');
+      return;
+    }
+    if (data.hasMore) {
+      console.log(`本批 ${rows.length} 条，还有更多：加 --line-num ${JSON.stringify(data.lineNum)} --scroll-id ${JSON.stringify(data.scrollId)} 续查`);
+    } else {
+      console.log(`共 ${rows.length} 条`);
+    }
+    printTable(rows, columns);
+    rows.forEach((row) => {
+      if (row._row && row._row.methodArgs !== undefined && row._row.methodArgs !== null) {
+        const args = String(row._row.methodArgs);
+        console.log(`\n${row.time} ${row.description} 参数：${args.slice(0, 200)}${args.length > 200 ? '...（更多用 --json 查看）' : ''}`);
+      }
+    });
+    if (rows.some((row) => row._row && row._row.requestId)) {
+      console.log('\n变动数据的完整字段值用 --json 查看；要知道具体通过什么操作改的，用请求标识执行：scm-agent log api --request-id <请求标识>');
+    }
+  } catch (e) {
+    console.error(`错误：${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { log, formatTime, fieldSummary };

package/cli/commands/query.js

@@ -0,0 +1,229 @@
+// 四组业务命令：商品、物料、生产单、物料采购单。design 命令族查询设计款与 IE 核价。
+// 每个命令默认输出人类可读表格；全局 --json 时输出原始 JSON（供 AI 解析）。
+const { call } = require('../api');
+const { printTable } = require('../table');
+
+const goods = {
+  command: 'goods',
+  describe: '查询商品',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'search',
+        describe: '按款号/名称/条码搜商品',
+        builder: (y) => y.option('name', { describe: '搜索关键词（款号、名称或条码）', demandOption: true, type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/goods/search', { searchKey: argv.name, page: argv.page, limit: argv.limit });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'goodsSn', label: '款号' },
+            { field: 'name', label: '名称' },
+            { field: 'isOnSale', label: '上架(1是0否)' },
+            { field: 'tagPrice', label: '吊牌价' },
+            { field: 'storedNumber', label: '库存' },
+            { field: 'produceNumber', label: '生产中' },
+            { field: 'produceOrderNumber', label: '生产单数' },
+          ] };
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '商品详情（颜色尺码与工序）',
+        builder: (y) => y.option('id', { describe: '商品id（先用 search 查到）', demandOption: true, type: 'number' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/goods/detail', { goodsId: argv.id });
+          return { data, columns: null };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：search 或 detail');
+  },
+};
+
+const material = {
+  command: 'material',
+  describe: '查询物料',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'search',
+        describe: '按名称/货号/条码搜物料',
+        builder: (y) => y.option('name', { describe: '搜索关键词（物料名称、货号或条码）', demandOption: true, type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/material/search', { searchKey: argv.name, page: argv.page, limit: argv.limit });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'sn', label: '货号' },
+            { field: 'name', label: '名称' },
+            { field: 'type', label: '类型(1面料0辅料)' },
+            { field: 'state', label: '状态(1启用)' },
+            { field: 'price', label: '价格' },
+            { field: 'stockNumber', label: '库存' },
+            { field: 'defaultSupplierName', label: '默认供应商' },
+          ] };
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '物料详情（单品颜色规格）',
+        builder: (y) => y.option('id', { describe: '物料id（先用 search 查到）', demandOption: true, type: 'number' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/material/detail', { id: argv.id });
+          return { data, columns: null };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：search 或 detail');
+  },
+};
+
+const produce = {
+  command: 'produce',
+  describe: '查询生产单',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'list',
+        describe: '生产单列表（至少给一项条件）',
+        builder: (y) => y
+          .option('sn', { describe: '关键词：单号/款号/商品名', type: 'string' })
+          .option('state', { describe: '状态：1草稿 2生产中 3生产完成 4待生产 9已撤销', type: 'number' })
+          .option('from', { describe: '业务日期起（yyyy-MM-dd）', type: 'string' })
+          .option('to', { describe: '业务日期止（yyyy-MM-dd）', type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/produce/list', { searchKey: argv.sn, state: argv.state, from: argv.from, to: argv.to, page: argv.page, limit: argv.limit });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'ordersSn', label: '生产单号' },
+            { field: 'goodsSn', label: '款号' },
+            { field: 'goodsName', label: '商品' },
+            { field: 'stateName', label: '状态' },
+            { field: 'sumNumber', label: '下单数' },
+            { field: 'sumInNumber', label: '入库数' },
+            { field: 'deliveryTime', label: '交期' },
+            { field: 'cutBedState', label: '裁床状态' },
+          ] };
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '生产单详情（明细与工序进度，裁床工序 core=2）',
+        builder: (y) => y.option('sn', { describe: '生产单号', demandOption: true, type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/produce/detail', { sn: argv.sn });
+          return { data, columns: null };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：list 或 detail');
+  },
+};
+
+const materialPurchase = {
+  command: 'material-purchase',
+  describe: '查询物料采购单',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'list',
+        describe: '物料采购单列表（至少给一项条件）',
+        builder: (y) => y
+          .option('sn', { describe: '关键词：单号/供应商/生产单号/物料', type: 'string' })
+          .option('state', { describe: '状态：1草稿 2待入库 3部分入库 4全部入库 9撤销', type: 'number' })
+          .option('from', { describe: '业务日期起（yyyy-MM-dd）', type: 'string' })
+          .option('to', { describe: '业务日期止（yyyy-MM-dd）', type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/material-purchase/list', { searchKey: argv.sn, state: argv.state, from: argv.from, to: argv.to, page: argv.page, limit: argv.limit });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'ordersSn', label: '采购单号' },
+            { field: 'supplierName', label: '供应商' },
+            { field: 'state', label: '状态' },
+            { field: 'sumPurchaseNumber', label: '采购数' },
+            { field: 'amount', label: '金额' },
+            { field: 'expectTime', label: '预计到料' },
+          ] };
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '物料采购单详情（物料明细）',
+        builder: (y) => y.option('sn', { describe: '采购单号', demandOption: true, type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/material-purchase/detail', { sn: argv.sn });
+          return { data, columns: null };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：list 或 detail');
+  },
+};
+
+const design = {
+  command: 'design',
+  describe: '查询设计款与IE核价',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'list',
+        describe: '设计款列表（至少给一项条件）',
+        builder: (y) => y
+          .option('sn', { describe: '关键词：款号/名称/条码/货号', type: 'string' })
+          .option('state', { describe: '状态：2设计中 3待确定 4修改中 5审核通过 6取消 15开发池 16版型资产库', type: 'number' })
+          .option('dateType', { describe: '日期字段：update更新 create创建 dev开发（默认 update）', type: 'string', default: 'update' })
+          .option('from', { describe: '日期起（yyyy-MM-dd）', type: 'string' })
+          .option('to', { describe: '日期止（yyyy-MM-dd）', type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/design/list', { searchKey: argv.sn, designState: argv.state, dateType: argv.dateType, from: argv.from, to: argv.to, page: argv.page, limit: argv.limit });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'designSn', label: '款号' },
+            { field: 'name', label: '名称' },
+            { field: 'designState', label: '状态(2设计中3待确定4修改中5审核通过6取消15开发池16版型资产库)' },
+            { field: 'designBrandName', label: '品牌' },
+            { field: 'designCategoryName', label: '分类' },
+            { field: 'designDesignerName', label: '设计师' },
+            { field: 'followerName', label: '跟单员' },
+            { field: 'costPrice', label: '成本价' },
+            { field: 'designStoredNumber', label: '库存' },
+            { field: 'designOrderCount', label: '板单数' },
+          ] };
+        }),
+      })
+      .command({
+        command: 'ie-list',
+        describe: 'IE核价报表（设计款×颜色的物料/工序/费用明细）',
+        builder: (y) => y
+          .option('sn', { describe: '关键词：名称/货号/款号/条码', type: 'string' })
+          .option('dateType', { describe: '日期字段：dev开发 create创建（默认 dev）', type: 'string', default: 'dev' })
+          .option('from', { describe: '日期起（yyyy-MM-dd）', type: 'string' })
+          .option('to', { describe: '日期止（yyyy-MM-dd）', type: 'string' }),
+        handler: (argv) => run(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/design/ie-list', { searchKey: argv.sn, dateType: argv.dateType, from: argv.from, to: argv.to, page: argv.page, limit: argv.limit });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'designSn', label: '款号' },
+            { field: 'name', label: '名称' },
+            { field: 'colorName', label: '颜色' },
+            { field: 'costPrice', label: '成本价' },
+            { field: 'designerName', label: '设计师' },
+          ] };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：list 或 ie-list');
+  },
+};
+
+/** 统一执行：异常输出可读文案并以非 0 退出；--json 输出原始数据 */
+async function run(argv, task) {
+  try {
+    const { list, total, columns, data } = await task();
+    if (argv.json) {
+      console.log(JSON.stringify({ total, list, data }, null, 2));
+      return;
+    }
+    if (columns) {
+      if (total !== undefined) {
+        console.log(`共 ${total} 条，当前显示 ${list.length} 条`);
+      }
+      printTable(list, columns);
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+  } catch (e) {
+    console.error(`错误：${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { goods, material, produce, materialPurchase, design };