@qinsilk/scm-agent-tools 0.0.0-stage → 0.2.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)。接口返回的每个字段是什么意思：[docs/api.md](docs/api.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/data.js

@@ -0,0 +1,112 @@
+// data 命令族：给 AI 一条受控取数入口，对应报表内部接口（数据集定义见 cli/datasets.js）。
+// 三条固定限制在这里实施：强制条件不满足不发请求；日期跨度上限在本地校验；
+// 分页数据集一次只取一页，末尾提示还有多少条（不自动翻页，翻页由调用方显式 --page）。
+// 官方报表不受影响：reports/*.js 仍然直接调这些接口拉全量。
+const { call } = require('../api');
+const { printTable } = require('../table');
+const {
+  DATASETS, findDataset, listDatasets, requireText, validateArgs, buildQuery, unknownOptions, ALL_OPTIONS, kebab,
+} = require('../datasets');
+
+const data = {
+  command: 'data [name]',
+  describe: '取报表数据（16 个数据集；scm-agent data --list 查看全部与必填条件）',
+  builder: (y) => {
+    y.positional('name', {
+      describe: '数据集名（见 scm-agent data --list）',
+      type: 'string',
+    });
+    y.option('list', {
+      describe: '列出全部数据集、必填条件与用途',
+      type: 'boolean',
+    });
+    // 参数并集来自数据集定义；单个数据集不接受的参数在 handler 里提示，
+    // 这样 --help 一处就能看到全部参数，而错误信息仍然具体。
+    for (const option of ALL_OPTIONS) {
+      y.option(option.name, { describe: option.describe, type: option.type });
+    }
+    return y;
+  },
+  handler: async (argv) => {
+    try {
+      await runData(argv);
+    } catch (e) {
+      console.error(`错误：${e.message}`);
+      process.exitCode = 1;
+    }
+  },
+};
+
+async function runData(argv) {
+  if (argv.list || !argv.name) {
+    printDatasetList();
+    return;
+  }
+
+  const dataset = findDataset(argv.name);
+  if (!dataset) {
+    throw new Error(`没有数据集「${argv.name}」。可用：${DATASETS.map((d) => d.name).join('、')}（scm-agent data --list 查看必填条件）`);
+  }
+
+  const extra = unknownOptions(dataset, argv);
+  if (extra.length) {
+    throw new Error(`数据集 ${dataset.name} 不接受参数 ${extra.join('、')}；它支持：${dataset.options.map((o) => '--' + kebab(o.name)).join('、') || '（无参数）'}`);
+  }
+
+  const invalid = validateArgs(dataset, argv);
+  if (invalid) {
+    throw new Error(invalid);
+  }
+
+  const query = buildQuery(dataset, argv);
+  const payload = await call('GET', dataset.path, query);
+
+  if (argv.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  // 分页数据集：{ page, limit, total, list }
+  if (dataset.paged) {
+    const rows = payload.list || [];
+    console.log(`共 ${payload.total} 条，当前显示 ${rows.length} 条`);
+    if (!rows.length) {
+      console.log('（无数据）');
+      return;
+    }
+    printTable(rows, dataset.columns);
+    const page = Number(argv.page) || 1;
+    const taken = (page - 1) * (Number(argv.limit) || 20) + rows.length;
+    if (payload.total > taken) {
+      console.log(`\n还有 ${payload.total - taken} 条未取；用 --page ${page + 1} 继续，或加 --limit 100 减少请求次数`);
+    }
+    return;
+  }
+
+  // 数组型单条接口（工序节点、物料占用）：一次返回全部行，没有分页
+  if (Array.isArray(payload)) {
+    console.log(`共 ${payload.length} 条`);
+    if (!payload.length) {
+      console.log('（无数据）');
+      return;
+    }
+    printTable(payload, dataset.columns);
+    return;
+  }
+
+  // 单对象（BOM、对账 11 表、工序明细、公司配置）：字段太多，直接输出 JSON
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+/** data --list：数据集名、必填条件、用途 */
+function printDatasetList() {
+  console.log('数据集清单（字段说明：scm-agent docs api --find <字段名>）：');
+  printTable(listDatasets(), [
+    { field: 'name', label: '数据集' },
+    { field: 'require', label: '必填条件' },
+    { field: 'describe', label: '用途' },
+  ]);
+  console.log('\n日期类数据集跨度上限 92 天；分页数据集一次只取一页，用 --page 翻页。');
+}
+
+module.exports = { data, runData, printDatasetList, requireText };

package/cli/commands/docs.js

@@ -0,0 +1,121 @@
+// 文档命令族：把包内附带的说明文档路径与内容交给 AI。
+// 文档随 npm 包发布，AI 的上下文里看不到文件系统，因此需要一条命令拿到绝对路径，
+// 或者按关键词只取需要的那几行，避免把整份文档读进上下文。
+const fs = require('fs');
+const path = require('path');
+
+/** 包内文档清单：命令里用的短名 → 文件名与用途 */
+const DOCS = {
+  cli: { file: 'cli.md', describe: '全部命令、参数、错误码与写命令的确认方式' },
+  api: { file: 'api.md', describe: '接口返回字段字典：字段含义、取值枚举、单位、为空的原因' },
+};
+
+function docsRoot() {
+  return path.join(__dirname, '..', '..', 'docs');
+}
+
+function docPath(name) {
+  const entry = DOCS[name];
+  if (!entry) {
+    throw new Error(`没有文档「${name}」。可用：${Object.keys(DOCS).join('、')}`);
+  }
+  const filePath = path.join(docsRoot(), entry.file);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`文档文件不存在：${filePath}（安装可能不完整，执行 scm-agent update 重新安装）`);
+  }
+  return filePath;
+}
+
+/**
+ * 按关键词筛出文档里相关的行：匹配行本身，加上它上方最近的一级或二级标题，
+ * 让 AI 即使只拿到几行也能判断属于哪个接口、哪个层级。
+ */
+function findLines(lines, keyword) {
+  const lower = keyword.toLowerCase();
+  const hits = [];
+  let lastHeading = '';
+  for (const line of lines) {
+    if (line.startsWith('#')) {
+      lastHeading = line;
+    }
+    if (line.toLowerCase().includes(lower)) {
+      hits.push({ heading: lastHeading, line });
+    }
+  }
+  return hits;
+}
+
+const docs = {
+  command: 'docs [name]',
+  describe: '查看包内文档的位置与内容（命令说明、接口字段字典）',
+  builder: (yargs) => yargs
+    .positional('name', {
+      describe: `文档名：${Object.keys(DOCS).join(' 或 ')}（不填则列出全部文档）`,
+      type: 'string',
+    })
+      .option('find', {
+        describe: '只输出包含该关键词的行（用于查某个字段或命令，避免读入整份文档）',
+        type: 'string',
+      })
+      .option('print', {
+        describe: '输出整份文档内容',
+        type: 'boolean',
+        default: false,
+      })
+      .example('scm-agent docs', '列出全部文档与文件位置')
+      .example('scm-agent docs api --find cutBedState', '查单个字段的含义')
+      .example('scm-agent docs api --print', '输出完整字段字典'),
+  handler: (argv) => {
+    try {
+      if (!argv.name) {
+        console.log('包内文档（文件随 npm 包安装，路径为本机绝对路径）：');
+        for (const [name, entry] of Object.entries(DOCS)) {
+          const filePath = path.join(docsRoot(), entry.file);
+          const exists = fs.existsSync(filePath);
+          console.log(`  ${name.padEnd(4)} ${entry.describe}`);
+          console.log(`       ${exists ? filePath : '（缺失，执行 scm-agent update 重新安装）'}`);
+        }
+        console.log('\n查某个字段或命令：scm-agent docs api --find <关键词>');
+        return;
+      }
+
+      const filePath = docPath(argv.name);
+      const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+
+      if (argv.find) {
+        const hits = findLines(lines, argv.find);
+        if (!hits.length) {
+          console.log(`文档 ${argv.name} 里没有包含「${argv.find}」的内容。`);
+          process.exitCode = 1;
+          return;
+        }
+        let lastHeading = null;
+        for (const hit of hits) {
+          // 命中的行本身就是标题时不再重复输出一次标题
+          const isHeading = hit.line.startsWith('#');
+          if (!isHeading && hit.heading && hit.heading !== lastHeading) {
+            console.log(`\n${hit.heading}`);
+            lastHeading = hit.heading;
+          }
+          console.log(hit.line);
+        }
+        console.log(`\n（以上为 ${path.basename(filePath)} 中匹配「${argv.find}」的内容，共 ${hits.length} 行）`);
+        return;
+      }
+
+      if (argv.print) {
+        console.log(lines.join('\n'));
+        return;
+      }
+
+      // 默认只给路径：AI 的上下文有限，整份文档通常不需要一次读完
+      console.log(`${path.basename(filePath)}（${lines.length} 行）：${filePath}`);
+      console.log('查单个字段：加 --find <关键词>；需要全文：加 --print');
+    } catch (e) {
+      console.error(`错误：${e.message}`);
+      process.exitCode = 1;
+    }
+  },
+};
+
+module.exports = { docs, DOCS, findLines, docPath };

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 };