@qinsilk/scm-agent-tools 0.1.0 → 0.2.0

package/README.md

@@ -46,4 +46,4 @@ scm-agent status
 
 AI Key 只保存在你自己的电脑（`~/.scm-agent/config.json`，仅本用户可读）；工具只能查询你本人在网页上有权限看的数据；所有查询会被系统日志记录。
 
-全部命令的详细说明（给你或你的 AI 看）：[docs/cli.md](docs/cli.md)。
+全部命令的详细说明（给你或你的 AI 看）：[docs/cli.md](docs/cli.md)。接口返回的每个字段是什么意思：[docs/api.md](docs/api.md)。

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/query.js

@@ -1,4 +1,5 @@
-// 四组业务命令：商品、物料、生产单、物料采购单。design 命令族查询设计款与 IE 核价。
+// 四组业务命令：商品、物料、生产单、物料采购单。design 命令族查询设计款与 IE 核价，
+// design-order 命令族查询版单（旗舰版功能）。
 // 每个命令默认输出人类可读表格；全局 --json 时输出原始 JSON（供 AI 解析）。
 const { call } = require('../api');
 const { printTable } = require('../table');
@@ -204,6 +205,61 @@ const design = {
   },
 };
 
+const designOrder = {
+  command: 'design-order',
+  describe: '查询版单（旗舰版功能）',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'list',
+        describe: '版单列表（至少给一项条件）',
+        builder: (y) => y
+          .option('sn', { describe: '关键词：款号/名称/版单号/备注/货号', type: 'string' })
+          .option('states', { describe: '版单状态（逗号分隔）：1未开始 2进行中 3已结束 4废版 9撤销 10审批中 12审批拒绝', type: 'string' })
+          .option('review-state', { describe: '审版状态：2未设置审版 3待审 4已审', type: 'number' })
+          .option('node', { describe: '当前节点名称，如：纸样、车板', type: 'string' })
+          .option('overdue', { describe: '逾期筛选：pattern纸样逾期 sweep车版逾期', type: 'string' })
+          .option('dateType', { describe: '日期字段：business下版（默认） create创建 update更新 finish预计完成 delivery交付', type: 'string', default: 'business' })
+          .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-order/list', {
+            searchKey: argv.sn, states: argv.states, reviewState: argv.reviewState,
+            node: argv.node, overdue: argv.overdue, dateType: argv.dateType,
+            from: argv.from, to: argv.to, page: argv.page, limit: argv.limit,
+          });
+          return { list: data.list, total: data.total, columns: [
+            { field: 'designOrderSn', label: '版单号' },
+            { field: 'designSn', label: '款号' },
+            { field: 'designName', label: '名称' },
+            { field: 'stateText', label: '状态' },
+            { field: 'currentProgressState', label: '当前节点' },
+            { field: 'designOrderSerialName', label: '版次' },
+            { field: 'businessTime', label: '下版日期' },
+            { field: 'finishTime', label: '预计完成' },
+            { field: 'totalNumber', label: '打版数' },
+            { field: 'supplierName', label: '供应商' },
+          ] };
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '版单详情（打版数量、节点进度、BOM、工艺要求、同款全部版单）',
+        builder: (y) => y
+          .option('sn', { describe: '版单号', type: 'string' })
+          .option('id', { describe: '版单id（先用 list 查到）', type: 'number' }),
+        handler: (argv) => run(argv, async () => {
+          if (!argv.sn && !argv.id) {
+            throw new Error('请提供版单号 --sn 或版单 id --id（二选一）');
+          }
+          const data = await call('GET', '/api/agent/v1/design-order/detail', { sn: argv.sn, id: argv.id });
+          return { data, columns: null };
+        }),
+      })
+      .demandCommand(1, '请指定子命令：list 或 detail');
+  },
+};
+
 /** 统一执行：异常输出可读文案并以非 0 退出；--json 输出原始数据 */
 async function run(argv, task) {
   try {
@@ -226,4 +282,4 @@ async function run(argv, task) {
   }
 }
 
-module.exports = { goods, material, produce, materialPurchase, design };
+module.exports = { goods, material, produce, materialPurchase, design, designOrder };