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

package/cli/commands/staff.js

@@ -0,0 +1,505 @@
+// 员工与权限管理命令族：创建员工、查用户角色、角色与权限菜单的查询、角色权限增减。
+// 写命令（user add、role add-permission、role remove-permission）默认只做查询与解析并
+// 输出预览，不发出任何写请求；加 --confirm 才真正执行——这是「改动前必须让用户确认」
+// 的机制，调用方（AI）必须先把预览展示给用户并取得同意。
+const crypto = require('node:crypto');
+const { call } = require('../api');
+const { printTable } = require('../table');
+
+/** 与网页一致的密码转换：明文 md5 后大写。服务端在此基础上二次加密存库 */
+function md5Upper(text) {
+  return crypto.createHash('md5').update(String(text), 'utf8').digest('hex').toUpperCase();
+}
+
+function splitNames(value) {
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean);
+  return String(value || '').split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+}
+
+/** 权限的展示名：备注优先（网页权限不足提示引号内的就是它） */
+function menuLabel(menu) {
+  return menu.remark || menu.label || `id=${menu.id}`;
+}
+
+/**
+ * 权限的完整描述，用于需要区分同名项的场合。
+ * 备注会重名：同一个「商品管理的查看」对应按设计师/跟单员/品牌/设计助理判断四个变体，
+ * 只显示备注时用户无法分辨，因此连同功能标题、权限 key 与菜单 id 一起给出。
+ */
+function describeMenu(menu) {
+  const parts = [menuLabel(menu)];
+  if (menu.label && menu.label !== menu.remark) {
+    parts.push(`标题：${menu.label}`);
+  }
+  if (menu.permission) {
+    parts.push(menu.permission);
+  }
+  parts.push(`id=${menu.id}`);
+  return parts.join('｜');
+}
+
+function describeRole(role) {
+  return `${role.name}(id=${role.id}${role.isSystem ? '，系统角色' : ''})`;
+}
+
+// ------------------------------------------------------------------ 服务端查询与解析
+
+async function fetchRoles(name) {
+  const params = {};
+  if (name) params.name = name;
+  return call('GET', '/api/agent/v1/role/list', params);
+}
+
+/**
+ * 按名称解析角色：先精确匹配，再唯一前缀匹配；匹配不到或有歧义时报错并列出候选。
+ * id 优先于名称。
+ */
+async function resolveRole({ id, name }) {
+  if (id) {
+    return { id, name: null };
+  }
+  if (!name) {
+    throw new Error('请用 --id 指定角色 id，或用 --name 指定角色名');
+  }
+  const roles = await fetchRoles(name);
+  const exact = roles.filter((r) => r.name === name);
+  if (exact.length === 1) {
+    return exact[0];
+  }
+  if (exact.length > 1) {
+    throw new Error(`存在多个同名角色「${name}」，请用 --id 指定：${exact.map(describeRole).join('；')}`);
+  }
+  const prefix = roles.filter((r) => r.name.startsWith(name));
+  if (prefix.length === 1) {
+    return prefix[0];
+  }
+  const candidates = roles.slice(0, 8).map(describeRole).join('；') || '（无）';
+  throw new Error(`没有找到角色「${name}」。相近角色：${candidates}。可执行 scm-agent role list --name ${name} 查看`);
+}
+
+/** 把用户给的多个角色名解析为角色行，全部可解析才继续 */
+async function resolveRoles(names) {
+  const all = await fetchRoles();
+  const rows = [];
+  for (const name of names) {
+    let hit = all.filter((r) => r.name === name);
+    if (hit.length === 0) {
+      hit = all.filter((r) => r.name.startsWith(name));
+    }
+    if (hit.length !== 1) {
+      const candidates = all.filter((r) => r.name.includes(name)).slice(0, 8).map(describeRole).join('；') || '（无）';
+      throw new Error(`角色「${name}」没有唯一匹配（${hit.length} 个）。候选：${candidates}`);
+    }
+    if (!rows.some((r) => r.id === hit[0].id)) {
+      rows.push(hit[0]);
+    }
+  }
+  return rows;
+}
+
+/**
+ * 把用户给的多个权限名解析为菜单行。
+ *
+ * 每项依次尝试：①按菜单 id（纯数字）②精确匹配权限 key ③精确匹配备注
+ * ④唯一包含匹配。备注会重名（例如「商品管理的查看」有按设计师、跟单员、
+ * 品牌、设计助理判断四个变体），命中多项时不猜，把带标题与权限 key 的候选
+ * 列出来让调用方去问用户，用户可用更明确的标题或权限 key 重新提交。
+ */
+async function resolvePermissions(spec) {
+  const items = splitNames(spec);
+  if (!items.length) {
+    throw new Error('请用 --permissions 指定权限（逗号分隔，可用中文名、英文权限 key 或菜单 id）');
+  }
+  const menus = (await call('GET', '/api/agent/v1/permission/list')).filter((m) => m.state === 1);
+  const rows = [];
+  const problems = [];
+  for (const item of items) {
+    const hits = resolveOnePermission(menus, item);
+    if (hits.length === 1) {
+      if (!rows.some((m) => m.id === hits[0].id)) {
+        rows.push(hits[0]);
+      }
+    } else if (hits.length === 0) {
+      problems.push(`「${item}」没有匹配`);
+    } else {
+      problems.push(`「${item}」有 ${hits.length} 个候选，需指定其中一个：${hits.slice(0, 6).map(describeMenu).join('；')}`);
+    }
+  }
+  if (problems.length) {
+    throw new Error(`权限解析失败：${problems.join('；')}。可执行 scm-agent permission list --keyword <词> 查看全部候选，再用带标题的完整名称、权限 key 或菜单 id 作为 --permissions`);
+  }
+  return rows;
+}
+
+/** 单项解析：id → 权限 key → 备注精确 → 唯一包含匹配。返回命中列表（0、1 或多条）。 */
+function resolveOnePermission(menus, item) {
+  if (/^\d+$/.test(item)) {
+    const byId = menus.filter((m) => String(m.id) === item);
+    if (byId.length) {
+      return byId;
+    }
+  }
+  const byKey = menus.filter((m) => m.permission === item);
+  if (byKey.length) {
+    return byKey;
+  }
+  const byRemark = menus.filter((m) => m.remark === item);
+  if (byRemark.length) {
+    return byRemark;
+  }
+  return menus.filter((m) => (m.remark || '').includes(item) || (m.label || '').includes(item) || (m.permission || '').includes(item));
+}
+
+// ------------------------------------------------------------------ 输出
+
+/**
+ * 预览后的确认提示。这段文字是写给 Agent 读的：CLI 在 Agent 的子进程里运行，
+ * 没有交互终端，无法自己弹确认框；确认必须由 Agent 用宿主提供的交互式提问工具完成。
+ */
+function printConfirmHint() {
+  console.log('\n以上为将要提交的改动，当前没有修改任何数据。');
+  console.log('请调用 AskUserQuestion（Codex 用 request_user_input；宿主没有该工具时改为文字提问），'
+    + '给出「确认」与「取消」两个选项并附上改动摘要；用户想改参数会自己用对话框自带的「Other」输入文字。');
+  console.log('选「确认」后加 --confirm 重新执行本命令；选「取消」不发写请求；'
+    + '「Other」里写了新要求则按它重新预览并再次确认。');
+}
+
+function printAffectedUsers(detail) {
+  const affected = detail.affectedUsers || [];
+  if (affected.length) {
+    console.log(`影响范围：使用该角色的 ${affected.length} 个用户——${affected.map((u) => u.name || u.uid).join('、')}`);
+  } else {
+    console.log('影响范围：当前没有用户使用该角色。');
+  }
+}
+
+// ------------------------------------------------------------------ 写命令实现
+
+/** 创建员工。无 --confirm 时输出预览；有 --confirm 时提交（密码先做与网页一致的 md5 大写） */
+async function runUserAdd(argv) {
+  const passwordMd5 = md5Upper(argv.password);
+  const roleRows = argv.roles ? await resolveRoles(splitNames(argv.roles)) : [];
+  const preview = {
+    action: '创建员工（子账号）',
+    name: argv.name,
+    loginName: argv.loginName,
+    passwordMd5,
+    roles: roleRows.map((r) => ({ id: r.id, name: r.name })),
+    phone: argv.phone,
+    departmentId: argv.departmentId,
+    workSn: argv.workSn,
+  };
+  if (!argv.confirm) {
+    if (argv.json) {
+      console.log(JSON.stringify(preview, null, 2));
+    } else {
+      console.log('【预览】将创建员工（子账号）：');
+      console.log(`  姓名：${argv.name}`);
+      console.log(`  登录账号：${argv.loginName}`);
+      console.log('  密码：********（已按网页规则加密，不再显示）');
+      console.log(`  角色：${roleRows.map((r) => `${r.name}(id=${r.id})`).join('、') || '（不关联角色）'}`);
+      if (argv.phone) console.log(`  手机号：${argv.phone}`);
+      if (argv.departmentId) console.log(`  部门 id：${argv.departmentId}`);
+      if (argv.workSn) console.log(`  工号：${argv.workSn}`);
+    }
+    printConfirmHint();
+    return;
+  }
+  const body = {
+    name: argv.name,
+    loginName: argv.loginName,
+    password: passwordMd5,
+    roleIds: roleRows.length ? roleRows.map((r) => r.id) : undefined,
+    phone: argv.phone,
+    departmentId: argv.departmentId,
+    workSn: argv.workSn,
+  };
+  Object.keys(body).forEach((key) => body[key] === undefined && delete body[key]);
+  const data = await call('POST', '/api/agent/v1/user/add', body);
+  if (argv.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  console.log(`✔ 已创建员工：${data.name}（uid=${data.uid}），登录账号 ${data.loginName}${data.roleNames ? `，角色：${data.roleNames.join('、')}` : ''}`);
+}
+
+/** 角色权限增减。mode 为 add 或 remove；无 --confirm 时输出预览（含受影响用户） */
+async function runRolePermission(argv, mode) {
+  const role = await resolveRole({ id: argv.id, name: argv.name });
+  const detail = await call('GET', '/api/agent/v1/role/detail', { roleId: role.id });
+  if (detail.isSystem) {
+    throw new Error(`「${detail.name}」是系统内置角色，不能修改权限。可建议用户复制一个自定义角色再调整`);
+  }
+  const permissions = await resolvePermissions(argv.permissions);
+  const current = detail.permissions || [];
+  const verb = mode === 'add' ? '增加' : '移除';
+  if (mode === 'add') {
+    const already = permissions.filter((p) => current.some((c) => c.menuId === p.id));
+    if (already.length) {
+      throw new Error(`该角色已拥有：${already.map(describeMenu).join('；')}`);
+    }
+  } else {
+    const notOwned = permissions.filter((p) => !current.some((c) => c.menuId === p.id));
+    if (notOwned.length) {
+      throw new Error(`该角色没有这些权限：${notOwned.map(describeMenu).join('；')}`);
+    }
+  }
+  const after = mode === 'add' ? current.length + permissions.length : current.length - permissions.length;
+  if (!argv.confirm) {
+    if (argv.json) {
+      console.log(JSON.stringify({
+        action: `${verb}角色权限`,
+        role: { id: detail.roleId, name: detail.name },
+        permissions: permissions.map((p) => ({ menuId: p.id, name: menuLabel(p), label: p.label, permission: p.permission })),
+        currentCount: current.length,
+        afterCount: after,
+        affectedUsers: detail.affectedUsers,
+      }, null, 2));
+    } else {
+      console.log(`【预览】将给角色「${detail.name}」${verb}以下权限：`);
+      permissions.forEach((p) => console.log(`  - ${describeMenu(p)}`));
+      console.log(`该角色现有权限 ${current.length} 项，改动后 ${after} 项。`);
+      printAffectedUsers(detail);
+    }
+    printConfirmHint();
+    return;
+  }
+  const body = { roleId: detail.roleId };
+  body[mode === 'add' ? 'addMenuIds' : 'removeMenuIds'] = permissions.map((p) => p.id);
+  const data = await call('POST', '/api/agent/v1/role/update-permission', body);
+  if (argv.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  const changed = (mode === 'add' ? data.added : data.removed) || [];
+  console.log(`✔ 已${verb}角色「${data.roleName}」的 ${changed.length} 项权限（${changed.map((p) => p.remark || p.label).join('、')}），该角色现有 ${data.totalPermissions} 项权限。`);
+}
+
+// ------------------------------------------------------------------ 命令定义
+
+const user = {
+  command: 'user',
+  describe: '员工管理（创建子账号、搜员工、查员工角色）',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'add',
+        describe: '创建员工（子账号）。默认只预览，加 --confirm 才创建',
+        builder: (y) => y
+          .option('name', { describe: '姓名', demandOption: true, type: 'string' })
+          .option('login-name', { describe: '登录账号（字母或数字，不能是 11 位手机号）', demandOption: true, type: 'string' })
+          .option('password', { describe: '密码（明文，命令内部加密后提交）', demandOption: true, type: 'string' })
+          .option('roles', { describe: '角色名，逗号分隔（如：设计师,版师）', type: 'string' })
+          .option('phone', { describe: '手机号', type: 'string' })
+          .option('department-id', { describe: '部门 id', type: 'number' })
+          .option('work-sn', { describe: '工号', type: 'string' })
+          .option('confirm', { describe: '确认执行（不加则只预览）', type: 'boolean', default: false }),
+        handler: (argv) => runStaff(argv, () => runUserAdd(argv)),
+      })
+      .command({
+        command: 'search',
+        describe: '按姓名/手机号/工号搜员工（用于查 uid，再交给 user detail）',
+        builder: (y) => y.option('name', { describe: '姓名、手机号或工号的一部分', demandOption: true, type: 'string' }),
+        handler: (argv) => runStaff(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/user-list', { searchKey: argv.name, page: argv.page, limit: argv.limit });
+          if (argv.json) {
+            return { json: data };
+          }
+          const rows = data.list.map((u) => ({
+            name: u.name,
+            uid: u.uid,
+            department: u.departmentName || '-',
+            state: u.status === 1 ? '正常' : '停用',
+            phone: u.phone || '-',
+            workSn: u.workSn || '-',
+          }));
+          if (!rows.length) {
+            console.log('（无数据）');
+            return {};
+          }
+          console.log(`共 ${data.total} 个员工（本页 ${rows.length} 条）`);
+          printTable(rows, [
+            { field: 'name', label: '姓名' },
+            { field: 'uid', label: '用户id' },
+            { field: 'department', label: '部门' },
+            { field: 'state', label: '状态' },
+            { field: 'phone', label: '手机号' },
+            { field: 'workSn', label: '工号' },
+          ]);
+          return {};
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '员工详情（基本信息与拥有的角色）',
+        builder: (y) => y.option('uid', { describe: '员工用户 id', demandOption: true, type: 'number' }),
+        handler: (argv) => runStaff(argv, async () => {
+          const data = await call('GET', '/api/agent/v1/user/detail', { uid: argv.uid });
+          if (argv.json) {
+            return { json: data };
+          }
+          console.log(`员工：${data.name}（uid=${data.uid}），登录账号 ${data.loginName}，状态 ${data.status === 1 ? '正常' : data.status}`);
+          const roles = (data.roles || []).map((r) => ({ name: r.name, id: r.id, _row: r }));
+          if (roles.length) {
+            console.log(`拥有 ${roles.length} 个角色：`);
+            printTable(roles, [
+              { field: 'name', label: '角色名' },
+              { field: 'id', label: '角色id' },
+            ]);
+            console.log('给「某个用户」调整权限时，改的是他其中一个角色的权限；多个角色时必须先让用户选择改哪一个。');
+          } else {
+            console.log('该员工没有角色。');
+          }
+          return {};
+        }),
+      })
+      .demandCommand(1, '请指定子命令：add、search 或 detail');
+  },
+};
+
+const role = {
+  command: 'role',
+  describe: '角色与权限管理（查角色、给角色增加/移除权限）',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'list',
+        describe: '角色列表（含系统内置角色）',
+        builder: (y) => y.option('name', { describe: '按角色名模糊过滤', type: 'string' }),
+        handler: (argv) => runStaff(argv, async () => {
+          const data = await fetchRoles(argv.name);
+          if (argv.json) {
+            return { json: data };
+          }
+          const rows = data.map((r) => ({
+            name: r.name,
+            type: r.isSystem ? '系统' : '自定义',
+            state: r.state === 1 ? '有效' : '无效',
+            id: r.id,
+            remark: r.remark || '-',
+          }));
+          if (!rows.length) {
+            console.log('（无数据）');
+            return {};
+          }
+          console.log(`共 ${rows.length} 个角色`);
+          printTable(rows, [
+            { field: 'name', label: '角色名' },
+            { field: 'type', label: '类型' },
+            { field: 'state', label: '状态' },
+            { field: 'id', label: '角色id' },
+            { field: 'remark', label: '备注' },
+          ]);
+          return {};
+        }),
+      })
+      .command({
+        command: 'detail',
+        describe: '角色详情（现有权限与使用该角色的用户）',
+        builder: (y) => y
+          .option('id', { describe: '角色 id', type: 'number' })
+          .option('name', { describe: '角色名（精确或唯一前缀）', type: 'string' }),
+        handler: (argv) => runStaff(argv, async () => {
+          const roleRow = await resolveRole(argv);
+          const data = await call('GET', '/api/agent/v1/role/detail', { roleId: roleRow.id });
+          if (argv.json) {
+            return { json: data };
+          }
+          console.log(`角色：${data.name}(id=${data.roleId})，${data.isSystem ? '系统内置角色（不能修改）' : '自定义角色'}，现有权限 ${(data.permissions || []).length} 项`);
+          const affected = data.affectedUsers || [];
+          console.log(`使用该角色的用户（${affected.length} 个）：${affected.map((u) => u.name || u.uid).join('、') || '（无）'}`);
+          const rows = (data.permissions || []).map((p) => ({
+            name: p.remark || p.label || '-',
+            permission: p.permission || '-',
+            menuId: p.menuId,
+          }));
+          if (rows.length) {
+            printTable(rows, [
+              { field: 'name', label: '权限' },
+              { field: 'permission', label: '权限key' },
+              { field: 'menuId', label: '菜单id' },
+            ]);
+          }
+          return {};
+        }),
+      })
+      .command({
+        command: 'add-permission',
+        describe: '给角色增加权限。默认只预览，加 --confirm 才执行',
+        builder: rolePermissionOptions(),
+        handler: (argv) => runStaff(argv, () => runRolePermission(argv, 'add')),
+      })
+      .command({
+        command: 'remove-permission',
+        describe: '给角色移除权限。默认只预览，加 --confirm 才执行',
+        builder: rolePermissionOptions(),
+        handler: (argv) => runStaff(argv, () => runRolePermission(argv, 'remove')),
+      })
+      .demandCommand(1, '请指定子命令：list、detail、add-permission 或 remove-permission');
+  },
+};
+
+function rolePermissionOptions() {
+  return (y) => y
+    .option('id', { describe: '角色 id', type: 'number' })
+    .option('name', { describe: '角色名（精确或唯一前缀；与 --id 二选一）', type: 'string' })
+    .option('permissions', { describe: '权限，逗号分隔；可用中文备注（权限不足提示引号内的文字）或英文权限 key', demandOption: true, type: 'string' })
+    .option('confirm', { describe: '确认执行（不加则只预览）', type: 'boolean', default: false });
+}
+
+const permission = {
+  command: 'permission',
+  describe: '权限菜单查询（中文名/权限 key/菜单 id 的对照）',
+  builder(yargs) {
+    return yargs
+      .command({
+        command: 'list',
+        describe: '权限菜单列表（可用 keyword 过滤）',
+        builder: (y) => y.option('keyword', { describe: '按标题/备注/权限 key 过滤', type: 'string' }),
+        handler: (argv) => runStaff(argv, async () => {
+          const params = {};
+          if (argv.keyword) params.keyword = argv.keyword;
+          const data = await call('GET', '/api/agent/v1/permission/list', params);
+          if (argv.json) {
+            return { json: data };
+          }
+          const rows = data.map((m) => ({
+            name: m.remark || m.label || '-',
+            label: m.label || '-',
+            permission: m.permission || '-',
+            type: m.type === 1 ? '目录' : m.type === 2 ? '页面' : '操作',
+            id: m.id,
+          }));
+          if (!rows.length) {
+            console.log('（无数据）');
+            return {};
+          }
+          console.log(`共 ${rows.length} 项`);
+          printTable(rows, [
+            { field: 'name', label: '权限备注' },
+            { field: 'label', label: '标题' },
+            { field: 'permission', label: '权限key' },
+            { field: 'type', label: '类型' },
+            { field: 'id', label: '菜单id' },
+          ]);
+          return {};
+        }),
+      })
+      .demandCommand(1, '请指定子命令：list');
+  },
+};
+
+/** 统一执行壳：任务返回 { json } 时按 --json 决定输出；异常输出可读文案并以非 0 退出 */
+async function runStaff(argv, task) {
+  try {
+    const result = await task();
+    if (result && result.json !== undefined && argv.json) {
+      console.log(JSON.stringify(result.json, null, 2));
+    }
+  } catch (e) {
+    console.error(`错误：${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { user, role, permission, md5Upper, resolveRole, resolveRoles, resolvePermissions, menuLabel, describeMenu, resolveOnePermission };

package/cli/config.js

@@ -0,0 +1,46 @@
+// 服务器地址默认值与本机配置文件路径。
+// 配置文件保存 AI Key 与访问令牌，权限 600，任何情况下不进入仓库与对话输出。
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_SERVER = 'https://scm.qinsilk.com';
+
+/** 配置根目录：默认用户主目录；SCM_AGENT_HOME 环境变量可覆盖（多环境调试用） */
+function homeDir() {
+  return process.env.SCM_AGENT_HOME || os.homedir();
+}
+
+function configDir(home = homeDir()) {
+  return path.join(home, '.scm-agent');
+}
+
+function configPath(home = homeDir()) {
+  return path.join(configDir(home), 'config.json');
+}
+
+function readConfig(home = homeDir()) {
+  const file = configPath(home);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/**
+ * 保存配置。文件权限设为 600（仅本用户可读写），目录不存在时先创建。
+ */
+function writeConfig(config, home = homeDir()) {
+  const dir = configDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = configPath(home);
+  fs.writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 });
+  // Windows 上 writeFileSync 的 mode 只在新建时生效，已是其他权限时需要显式收紧
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch (e) {
+    // 部分文件系统不支持 chmod，忽略
+  }
+}
+
+module.exports = { DEFAULT_SERVER, configDir, configPath, readConfig, writeConfig };