@xiaoyuanhao/yunzhi-cli 2.0.0

package/lib/arguments.cjs

@@ -0,0 +1,37 @@
+const { unknownOption } = require('./suggestions.cjs');
+const { Failure, invalid } = require('./result.cjs');
+
+// The flags remain command-specific; no unrecognized option reaches the Gateway.
+function options(args, values, booleans = [], raw = [], strict = false) {
+  const payload = {};
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    const name = flag.slice(2).replaceAll('-', '_');
+    if (flag.startsWith('--') && (values.includes(name) || booleans.includes(name)) && name !== 'label_id') {
+      if (seen.has(name)) throw invalid(flag + ' 不能重复传入。');
+      seen.add(name);
+    }
+    if (booleans.includes(name) && flag.startsWith('--')) { payload[name] = true; continue; }
+    if (!flag.startsWith('--') || !values.includes(name)) throw unknownOption(flag, values.concat(booleans).map(name => '--' + name.replaceAll('_', '-')));
+    const value = args[++i];
+    if (!value?.trim() || ['--help', '-h'].includes(value)
+        || (value.startsWith('--') && values.concat(booleans).includes(value.slice(2).replaceAll('-', '_')))
+        || (strict && value.startsWith('--'))) throw invalid(flag + ' 需要非空参数。');
+    if (name === 'label_id') (payload.label_ids ||= []).push(raw.includes(name) ? value : value.trim());
+    else payload[name] = raw.includes(name) ? value : value.trim();
+  }
+  return payload;
+}
+function required(payload, ...names) {
+  for (const name of names) if (!payload[name]) throw invalid('--' + name.replaceAll('_', '-') + ' 为必填参数。');
+}
+function confirm(payload) {
+  if (!payload.yes) throw new Failure(10, 'confirmation', 'confirmation_required', '执行前必须明确传入 --yes。');
+  delete payload.yes;
+}
+function limit(payload, maximum) {
+  if (!/^[+]?\d+$/.test(String(payload.limit)) || +payload.limit < 1 || +payload.limit > maximum) throw invalid(`--limit 必须在 1 到 ${maximum} 之间。`);
+  payload.limit = +payload.limit;
+}
+module.exports = { options, required, confirm, limit };

package/lib/auth.cjs

@@ -0,0 +1,193 @@
+const { setTimeout: wait } = require('node:timers/promises');
+const { unknownOption } = require('./suggestions.cjs');
+const { cleanup, attach } = require('./diagnostics.cjs');
+const { Failure, invalid, success, optionalFields, cleanupFailure } = require('./result.cjs');
+const { loadConfig, expired, putCredential, removeCredential, saveConfig } = require('./storage.cjs');
+const { tokenFor } = require('./session.cjs');
+const { version } = require('./version.cjs');
+const { request, publicResult, gatewayURL } = require('./gateway.cjs');
+
+const user = { user_id: 'string', name: 'string' };
+const tenant = { tenant_id: 'string', name: 'string' };
+const authorization = { event: 'string', user, tenant, requested_scopes: ['string'], newly_granted_scopes: ['string'],
+  already_granted_scopes: ['string'], granted_scopes: ['string'], expires_at: 'string' };
+const pending = { event: 'string', authorization_url: 'string', device_code: 'string', expires_at: 'string', requested_scopes: ['string'] };
+function invalidAuthorization(message, envelope) {
+  const error = new Failure(1, 'api', 'invalid_response', message);
+  if (typeof envelope.request_id === 'string' && envelope.request_id) error.result.value.request_id = envelope.request_id;
+  return error;
+}
+function loginOptions(args, allowDeviceCode = true) {
+  const options = allowDeviceCode ? ['--scope', '--device-code'] : ['--scope'];
+  const scopes = [];
+  let deviceCode = '';
+  for (let i = 0; i < args.length; i++) {
+    const option = args[i];
+    if (!options.includes(option)) throw unknownOption(option, options);
+    if (option === '--device-code' && deviceCode) throw invalid(option + ' 不能重复传入。');
+    if (++i >= args.length || !args[i].trim() || ['--scope', '--device-code', '--help', '-h'].includes(args[i])
+        || (!allowDeviceCode && args[i].startsWith('-'))) throw invalid(option + ' 需要非空参数。');
+    if (option === '--scope') scopes.push(args[i]); else deviceCode = args[i];
+  }
+  if (deviceCode) {
+    if (scopes.length) throw invalid('--device-code 不能与 --scope 同时使用。');
+  }
+  if (!deviceCode && !scopes.length) throw invalid('缺少 --scope。请使用原业务错误返回的 error.required_scopes，每个权限分别传入一次 --scope。');
+  return { scopes, deviceCode };
+}
+async function login(args, signal) {
+  const { scopes, deviceCode } = loginOptions(args);
+  if (deviceCode) return complete(deviceCode, signal);
+  const config = await loadConfig();
+  const token = expired(config.current_profile) ? '' : await tokenFor(config.current_profile);
+  try {
+    const result = await request(config, 'auth/sessions', token, { requested_scopes: scopes,
+      client_id: 'yunzhi-cli', cli_version: version, source: 'workbuddy' }, signal);
+    const output = publicResult(result, pending);
+    const data = output.value.data;
+    let validURL = false, urlError;
+    try { const url = new URL(data.authorization_url); validURL = ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password; } catch (error) { urlError = error; }
+    if (data.event !== 'authorization_pending' || !validURL || !data.device_code.trim()
+        || !Array.isArray(data.requested_scopes) || !data.requested_scopes.length
+        || !Number.isFinite(Date.parse(data.expires_at))) {
+      const failure = invalidAuthorization('Agent Gateway 返回了无效授权会话。', result);
+      throw urlError ? attach(failure, urlError) : failure;
+    }
+    output.value.data.message = '授权会话已创建。请向用户展示 authorization_url，等待用户明确确认网页授权完成后，使用 device_code 兑换登录态。';
+    return output;
+  } catch (error) {
+    if (token && error.result?.value.error.type === 'authentication' && error.result.value.error.subtype === 'auth_required') {
+      const failure = new Failure(3, 'authentication', 'stale_session_requires_logout',
+        '当前 CLI 登录已失效。请执行 auth logout，成功后使用本次所需权限重新创建授权会话。', { required_scopes: scopes });
+      if (error.result.value.request_id) failure.result.value.request_id = error.result.value.request_id;
+      throw attach(failure, error);
+    }
+    throw error;
+  }
+}
+async function complete(deviceCode, signal) {
+  const config = await loadConfig();
+  const resolvedURL = gatewayURL(config);
+  const envelope = await request(config, 'auth/sessions/token', '', { device_code: deviceCode, client_id: 'yunzhi-cli' }, signal);
+  signal?.throwIfAborted();
+  const result = publicResult(envelope, authorization);
+  const data = result.value.data;
+  if (data.event !== 'authorization_complete' || !data?.user?.user_id.trim() || !data.tenant?.tenant_id.trim()
+      || !Array.isArray(data.granted_scopes) || !Number.isFinite(Date.parse(data.expires_at))) {
+    throw invalidAuthorization('Agent Gateway 返回了无效授权响应。', envelope);
+  }
+  const oldProfile = config.current_profile;
+  const reuse = envelope.data.reuse_existing_credential === true;
+  let reference;
+  if (reuse) {
+    if (!oldProfile || expired(oldProfile) || !await tokenFor(oldProfile)) {
+      throw new Failure(3, 'authentication', 'stale_session_requires_logout', '当前 CLI 登录已失效，无法复用本地登录态。请报告错误并停止本次兑换。');
+    }
+    if (oldProfile.user?.user_id !== data.user.user_id || oldProfile.tenant?.tenant_id !== data.tenant.tenant_id) {
+      throw invalidAuthorization('授权响应的用户或组织与待复用的本地登录态不一致。', envelope);
+    }
+    reference = oldProfile.credential_ref;
+  } else {
+    if (typeof envelope.data.access_token !== 'string' || !envelope.data.access_token) {
+      throw invalidAuthorization('授权响应缺少 Access Token。', envelope);
+    }
+    reference = await putCredential(envelope.data.access_token);
+  }
+  config.gateway_url = resolvedURL;
+  config.current_profile = { credential_ref: reference, user: data.user, tenant: data.tenant,
+    granted_scopes: data.granted_scopes, expires_at: data.expires_at };
+  try { await saveConfig(config); }
+  catch (error) {
+    if (!reuse) {
+      try { await removeCredential(reference); }
+      catch (cleanupError) { cleanup(error, cleanupError); }
+    }
+    throw error;
+  }
+  if (!reuse && oldProfile) {
+    try { await removeCredential(oldProfile.credential_ref); }
+    catch (error) { throw cleanupFailure(error, result); }
+  }
+  return result;
+}
+async function localStatus(args, signal) {
+  if (args.filter(arg => arg === '--verify').length > 1) throw invalid('--verify 不能重复传入。');
+  if (args.some(arg => arg !== '--verify')) throw unknownOption(args.find(arg => arg !== '--verify'), ['--verify']);
+  const config = await loadConfig();
+  const profile = config.current_profile;
+  if (!profile) return success({ authenticated: false, verified: false, token_status: 'missing' });
+  const last = { user: profile.user, tenant: profile.tenant };
+  const token = await tokenFor(profile);
+  if (!token) return success({ authenticated: false, verified: false, token_status: 'missing', last_known_profile: last });
+  if (expired(profile)) return success({ authenticated: false, verified: false, token_status: 'expired', expires_at: profile.expires_at, last_known_profile: last });
+  if (!args.includes('--verify')) return success({ authenticated: true, verified: false, user: profile.user, tenant: profile.tenant,
+    granted_scopes: profile.granted_scopes, expires_at: profile.expires_at, token_status: 'unverified' });
+  try {
+    const timeout = AbortSignal.timeout(8000);
+    const result = await request(config, 'auth/me', token, undefined, signal ? AbortSignal.any([signal, timeout]) : timeout);
+    if (typeof result.data?.user?.user_id !== 'string' || !result.data.user.user_id.trim()
+        || typeof result.data?.tenant?.tenant_id !== 'string' || !result.data.tenant.tenant_id.trim()) {
+      throw invalidAuthorization('Agent Gateway 返回了无效身份响应。', result);
+    }
+    return publicResult({ ...result, data: { ...result.data, authenticated: true, verified: true } }, {
+      authenticated: 'boolean', verified: 'boolean', user, tenant, granted_scopes: ['string'], token_status: 'string', expires_at: 'string',
+    });
+  } catch (error) {
+    if (error.result?.value.error.type === 'authentication' && error.result.value.error.subtype === 'auth_required') {
+      return success({ authenticated: false, verified: true, token_status: 'invalid', last_known_profile: last });
+    }
+    throw error;
+  }
+}
+async function status(args, signal) {
+  const result = await localStatus(args, signal);
+  return publicResult(result.value, { authenticated: 'boolean', verified: 'boolean', token_status: 'string',
+    ...optionalFields({ user, tenant, granted_scopes: ['string'], expires_at: 'string', last_known_profile: { user, tenant } }) });
+}
+async function logout(args) {
+  if (args.length) throw unknownOption(args[0], []);
+  const config = await loadConfig();
+  if (config.current_profile) await removeCredential(config.current_profile.credential_ref);
+  delete config.current_profile;
+  await saveConfig(config);
+  return success({ status: 'logged_out' });
+}
+async function connect(args) {
+  loginOptions(args, false);
+  const limit = AbortSignal.timeout(300000);
+  let expiry;
+  try {
+    const current = await status(['--verify'], limit);
+    if (current.value.data.authenticated) return current;
+    // Only a confirmed missing, expired or invalid login reaches this point.
+    await logout([]);
+    limit.throwIfAborted();
+    const session = (await login(args, limit)).value.data;
+    const remaining = Date.parse(session.expires_at) - Date.now();
+    if (remaining <= 0) throw new Failure(3, 'authentication', 'authorization_expired', '授权会话已过期，请重新连接。');
+    expiry = remaining < 300000 ? AbortSignal.timeout(remaining) : undefined;
+    const signal = expiry ? AbortSignal.any([limit, expiry]) : limit;
+    process.stderr.write(session.authorization_url + '\n');
+    while (true) {
+      await wait(3000, undefined, { signal });
+      try {
+        const completed = await complete(session.device_code, signal);
+        completed.value.data.authenticated = true;
+        completed.value.data.message = '校园号已连接，登录状态已保存。';
+        return completed;
+      } catch (error) {
+        if (error.result?.value.error.type !== 'authentication'
+            || error.result.value.error.subtype !== 'authorization_pending') throw error;
+      }
+    }
+  } catch (error) {
+    const failure = error.result?.value.error;
+    if (failure?.operation_completed || failure?.cleanup_failed || failure?.partial_file) throw error;
+    if (limit.aborted || expiry?.aborted) throw attach(new Failure(3, 'authentication',
+      limit.aborted ? 'authorization_timeout' : 'authorization_expired',
+      limit.aborted ? '等待授权超过 5 分钟，请重新连接。' : '授权会话已过期，请重新连接。'), error);
+    throw error;
+  }
+}
+
+module.exports = { login, connect, status, logout };

package/lib/business-schemas.cjs

@@ -0,0 +1,24 @@
+const { optionalFields, nullableFields, nullable, required } = require('./result.cjs');
+const { snippet } = require('./lesson-prep.cjs');
+const resource = { ...optionalFields({ type: 'string', file_id: 'string', kind: 'string', space: 'string', name: 'string',
+  path: 'string', file_ext: 'string', file_size: 'integer', label_ids: ['string'], updated_at: 'string', web_url: 'string' }), category_id: nullable('string') };
+const folder = optionalFields({ event: 'string', folder_id: 'string', name: 'string', path: 'string', deleted_folder_count: 'integer' });
+const textbook = optionalFields({ event: 'string', textbook_id: 'string', folder_id: 'string', name: 'string', path: 'string' });
+module.exports = {
+  errors: {
+    ...require('./report-schemas.cjs').errors,
+    invalid_pattern: { syntax: ['string'], examples: ['string'] },
+    file_report_pending: { report_id: 'string', report_status: 'string' },
+    textbook_already_added: { textbook_id: 'string', folder_id: 'string', name: 'string', path: 'string' },
+    page_cleanup_failed: { file_id: 'string', delete_stage: 'string', lesson_registration_removed: 'boolean' },
+
+  },
+  update: resource, move: resource, remove: { removed: 'boolean', file_id: 'string', mode: 'string' },
+  'folder/create': folder, 'folder/update': folder, 'folder/delete': folder,
+  'textbook/add': textbook, 'textbook/remove': textbook,
+  'textbook/available': { items: [nullableFields({ textbook_id: 'string', name: 'string', school_stage: 'string', subject: 'string', grade: 'string', version: 'string', volume: 'string' })], next_cursor: nullable('string') },
+  'reference/search': { items: [{ ...nullableFields({ file_id: 'string', space: 'string', name: 'string', provider: 'string', file_ext: 'string', updated_at: 'string', web_url: 'string', score: 'number' }), snippets: [snippet] }], next_cursor: nullable('string') },
+  'reference/add': { file_id: 'string', source_file_id: 'string', folder_id: 'string', kind: 'string', name: 'string', path: 'string', message: 'string' },
+  'upload-options': { target: required({ folder_id: required('string'), name: required('string'), path: required('string') }), category_options: required([{ category_id: required('string'), name: required('string') }]), label_options: required([{ label_id: required('string'), name: required('string') }]) },
+  web: { pages: [{ name: 'string', web_url: 'string' }] },
+};

package/lib/business.cjs

@@ -0,0 +1,57 @@
+const { invalid } = require('./result.cjs');
+const { writeScope } = require('./session.cjs');
+const { options, required, confirm, limit } = require('./arguments.cjs');
+const gateway = require('./gateway.cjs');
+
+function parse(namespace, command, args) {
+  let payload, scope = writeScope(namespace);
+  switch (command) {
+    case 'update':
+      payload = options(args, ['file_id', 'title', 'category_id', 'label_id'], ['clear_category', 'clear_labels']);
+      required(payload, 'file_id');
+      if (payload.category_id && payload.clear_category) throw invalid('--category-id 与 --clear-category 不能同时使用。');
+      if (payload.label_ids && payload.clear_labels) throw invalid('--label-id 与 --clear-labels 不能同时使用。');
+      if (Object.keys(payload).length === 1) throw invalid('update 至少需要一个修改项。');
+      break;
+    case 'move':
+    case 'reference/add':
+      payload = options(args, [command === 'move' ? 'file_id' : 'source_file_id', 'folder_id']);
+      required(payload, command === 'move' ? 'file_id' : 'source_file_id', 'folder_id');
+      break;
+    case 'remove':
+    case 'textbook/remove':
+    case 'folder/delete': {
+      const id = command === 'remove' ? 'file_id' : 'folder_id';
+      payload = options(args, [id], ['yes']); required(payload, id); confirm(payload); break;
+    }
+    case 'folder/create':
+    case 'folder/update': {
+      const id = command === 'folder/create' ? 'parent_folder_id' : 'folder_id';
+      payload = options(args, [id, 'name']); required(payload, id, 'name');
+      if ([...payload.name].length > 100 || payload.name.includes('/') || ['.', '..'].includes(payload.name)) throw invalid('--name 必须为 1 到 100 个字符，不能包含 /，也不能为 . 或 ..。');
+      break;
+    }
+    case 'textbook/add':
+      payload = options(args, ['textbook_id']); required(payload, 'textbook_id'); break;
+    case 'textbook/available':
+    case 'reference/search':
+      payload = { query: null, limit: command === 'reference/search' ? 10 : 20, cursor: null,
+        ...options(args, ['query', 'limit', 'cursor'], [], ['cursor', 'limit']) };
+      limit(payload, command === 'reference/search' ? 20 : 100);
+      if (command === 'reference/search') required(payload, 'query');
+      scope = 'school-library:read'; break;
+    case 'upload-options':
+      payload = options(args, ['folder_id'], [], ['folder_id']); required(payload, 'folder_id'); scope = 'school-library:read'; break;
+    case 'web':
+      payload = options(args, []); scope = 'school-library:read'; break;
+    default: throw invalid('未知命令。');
+  }
+  return { payload, scope };
+}
+
+async function execute(namespace, command, args) {
+  const { payload, scope } = parse(namespace, command, args);
+  const schemas = require('./business-schemas.cjs');
+  return gateway.execute(scope, namespace + '/' + command, payload, schemas[command]);
+}
+module.exports = { execute };

package/lib/cli.cjs

@@ -0,0 +1,184 @@
+const { attach } = require('./diagnostics.cjs');
+const { version } = require('./version.cjs');
+const { Failure, invalid, success } = require('./result.cjs');
+const guidance = require('./command-guidance.cjs');
+const { unknownCommand, unknownOption } = require('./suggestions.cjs');
+const usage = {
+  'auth login': '--scope <scope> [--scope <scope>...]\n  或 auth login --device-code <device_code>',
+  'auth connect': '--scope <scope> [--scope <scope>...]',
+  'auth status': '[--verify]', 'auth logout': '',
+  'lesson-prep ls': '[path] [--limit 1..200] [--cursor <cursor>]',
+  'lesson-prep glob': '[path] [--pattern <pattern>] [--type all|folder|file] [--limit 1..200] [--cursor <cursor>]',
+  'lesson-prep search': '[path] --query <query> [--limit 1..20] [--cursor <cursor>]',
+  'lesson-prep grep': '[path] --pattern <text> [--pattern <text>...] [--glob <glob>] [--ignore-case] [--limit 1..100] [--cursor <cursor>]',
+  'lesson-prep fetch': '--file <file_id|absolute_business_path> [--start-line <line>] [--limit 1..500]',
+  'learning-tool ls': '[path] [--limit 1..200] [--cursor <cursor>]',
+  'learning-tool upload-options': '--folder-id <folder_id>',
+  'learning-tool upload': '--source <path> --folder-id <folder_id> --title <title> [--category-id <category_id>] [--label-id <label_id>...]',
+  'learning-tool update': '--file-id <file_id> [--title <title>] [--category-id <category_id> | --clear-category] [--label-id <label_id>... | --clear-labels]',
+  'learning-tool move': '--file-id <file_id> --folder-id <folder_id> [--category-id <category_id> | --clear-category] [--label-id <label_id>... | --clear-labels]',
+  'learning-tool remove': '--file-id <file_id> --yes',
+  'config set': 'gateway-url <http(s)-url>', version: '',
+};
+for (const namespace of ['lesson-prep', 'school-library']) {
+  for (const command of ['ls', 'glob', 'search', 'grep', 'fetch']) usage[namespace + ' ' + command] = usage['lesson-prep ' + command];
+  for (const [command, flags] of Object.entries({
+    download: '--file <file_id|absolute_business_path> [--output <local_file>] [--overwrite]',
+    'upload-options': '--folder-id <folder_id>',
+    upload: '--file <local_file> --folder-id <folder_id> [--title <title>] [--category-id <category_id>] [--label-id <label_id>...]',
+    update: '--file-id <file_id> [--title <title>] [--category-id <category_id> | --clear-category] [--label-id <label_id>... | --clear-labels]',
+    move: '--file-id <file_id> --folder-id <folder_id>', remove: '--file-id <file_id> --yes',
+    'folder create': '--parent-folder-id <folder_id> --name <name>', 'folder update': '--folder-id <folder_id> --name <name>', 'folder delete': '--folder-id <folder_id> --yes',
+    'textbook available': '[--query <text>] [--limit 1..100] [--cursor <cursor>]', 'textbook add': '--textbook-id <textbook_id>', 'textbook remove': '--folder-id <folder_id> --yes',
+    'report submit': '--file-id <file_id>' + (namespace === 'lesson-prep' ? ' [--target-folder-id <folder_id>]' : '') + ' [--remark <remark>]',
+    'report list': '[--status pending|approved|rejected|delisted|cancelled] [--limit 1..100] [--cursor <cursor>]',
+    'report show': '--report-id <report_id>', 'report history': '--report-id <report_id>', 'report cancel': '--report-id <report_id>',
+  })) usage[namespace + ' ' + command] = flags;
+}
+Object.assign(usage, {
+  'lesson-prep reference search': '--query <text> [--limit 1..20] [--cursor <cursor>]',
+  'lesson-prep reference add': '--source-file-id <file_id> --folder-id <folder_id>',
+  'school-library web': '',
+  'school-library review list': '[--status all|pending|approved|rejected|delisted] [--query <text>] [--limit 1..100] [--cursor <cursor>]',
+  'school-library review show': '--report-id <report_id> [--folder-id <folder_id>]',
+  'school-library review approve': '--report-id <report_id> [--folder-id <folder_id>] --yes',
+  'school-library review reject': '--report-id <report_id> --reason <reason> --yes',
+});
+
+const summaries = {
+  auth: '登录与授权', config: '本地配置', 'lesson-prep': '备课空间', 'school-library': '校本库',
+  'learning-tool': '本地 HTML 学具制作成品与个人备课学具',
+  folder: '目录管理', textbook: '教材管理', report: '资源上报', review: '上报审批', reference: '资源引用',
+  'auth connect': '连接校园号并等待授权完成',
+  'auth login': '创建授权会话或兑换登录态', 'auth status': '查看当前登录身份和组织',
+  'auth logout': '退出本机 CLI 登录', 'config set': '设置 Gateway 地址', version: '显示当前 CLI 发行版本',
+  ls: '列出目录的直接子项', glob: '按名称或路径查找文件和目录', search: '搜索资源正文',
+  grep: '在解析正文中查找指定文字', fetch: '读取资源的解析正文', download: '将资源原文件保存到本地',
+  'upload-options': '查看目标目录可选的分类和标签', upload: '上传本地文件并创建资源',
+  update: '修改资源标题、分类或标签', move: '移动资源到指定目录', remove: '移除资源',
+  'folder create': '创建目录', 'folder update': '修改目录名称', 'folder delete': '删除目录',
+  'textbook available': '查找可添加的教材', 'textbook add': '添加教材目录', 'textbook remove': '移除教材目录',
+  'report submit': '提交资源上报，等待审批', 'report list': '查看自己的上报记录',
+  'report show': '查看上报详情', 'report history': '查看资源的历次上报', 'report cancel': '撤销待审批上报',
+  'reference search': '搜索可引用的源资源', 'reference add': '将源资源引用到备课目录',
+  web: '获取校本库业务页面地址', 'review list': '查看审批列表', 'review show': '查看审批详情及目标预览',
+  'review approve': '通过上报并创建目标资源', 'review reject': '拒绝上报并记录原因',
+};
+
+const loginHelp = `登录与授权：创建授权会话，或在网页授权完成后兑换登录态。
+
+1. 创建授权会话（首次登录或追加权限）
+用法：yunzhi-cli auth login --scope <scope> [--scope <scope>...]
+参数：
+  --scope  必填，可重复，无默认值。使用原业务错误返回的 error.required_scopes，每个权限分别传入一次。
+  仅要求登录或切换账号、组织且尚未明确业务时，先询问要办理的业务，不自行选择默认权限。
+示例：
+  yunzhi-cli auth login --scope school-library:read
+返回：
+  ok=true、data.event=authorization_pending 表示会话创建成功，尚未完成登录。
+  data.authorization_url 是完整授权地址；data.device_code 用于后续兑换。
+  data.expires_at 是会话过期时间；data.requested_scopes 是本次权限；data.message 提示下一步。
+下一步：
+  向用户展示完整授权地址，等待用户明确确认网页授权完成后再兑换，不轮询。
+
+2. 兑换登录态
+用法：yunzhi-cli auth login --device-code <device_code>
+参数：
+  --device-code  必填，使用创建会话时返回的 data.device_code，不能与 --scope 同时使用。
+示例：
+  yunzhi-cli auth login --device-code <device_code>
+返回：
+  ok=true、data.event=authorization_complete 表示登录授权完成，可以恢复原业务命令。
+  data.user、data.tenant 是当前用户和组织；data.granted_scopes 是已授权权限；data.expires_at 是登录过期时间。
+下一步：
+  成功后重试原业务命令。
+
+除 --scope 外，参数不能重复传入。
+默认输出 JSON。失败时阅读 error.message 及返回的引导字段，并按认证指南处理。
+`;
+
+async function execute(args) {
+  if (args[0] === 'help' || ['--help', '-h'].includes(args.at(-1))) {
+    const command = (args[0] === 'help' ? args.slice(1) : args.slice(0, -1)).join(' ');
+    const commands = Object.keys(usage).filter(item => !command || item === command || item.startsWith(command + ' '));
+    if (usage[command] !== undefined) {
+      const text = command === 'auth login' ? loginHelp
+        : guidance.render(command, usage[command]);
+      const reference = require('./command-reference.cjs').reference(command);
+      return { code: 0, text: text + (reference ? '\n命令参考（相对产品 Skill 根目录）：\n' + reference + '\n' : '') };
+    }
+    if (commands.length) {
+      const depth = command ? command.split(' ').length + 1 : 1;
+      const children = [...new Set(commands.map(item => item.split(' ').slice(0, depth).join(' ')))];
+      const title = command || '校园号 CLI';
+      return { code: 0, text: `${title}\n\n可用命令：\n` + children.map(item =>
+        `  ${item}  ${summaries[item] || summaries[item.split(' ').slice(1).join(' ')]}\n`).join('')
+        + '\n使用 yunzhi-cli <命令> --help 查看下一级或命令详情。\n' };
+    }
+    throw unknownCommand(command.split(' ').filter(Boolean), Object.keys(usage));
+  }
+  if (!Object.keys(usage).some(name => name.split(' ').every((word, index) => args[index] === word))) throw unknownCommand(args, Object.keys(usage));
+  if (args[0] === 'version' && args.length > 1) throw unknownOption(args[1], []);
+  if (args[0] === 'version' && args.length === 1) {
+    return { code: 0, value: { ok: true, data: { version } } };
+  }
+  if (args[0] === 'learning-tool' && ['ls', 'upload-options', 'upload', 'update', 'move', 'remove'].includes(args[1]))
+    return require('./learning-tool.cjs').execute(args[1], args.slice(2));
+  if (['lesson-prep', 'school-library'].includes(args[0]) && ['ls', 'glob', 'search', 'grep', 'fetch'].includes(args[1])) return require('./lesson-prep.cjs').read(args[1], args.slice(2), args[0]);
+  if (['lesson-prep', 'school-library'].includes(args[0])) {
+    if (args[1] === 'download') return require('./download.cjs').download(args[0], args.slice(2));
+    if (args[1] === 'upload') return require('./upload.cjs').upload(args[0], args.slice(2));
+    if (args[1] === 'report' || (args[1] === 'review' && args[0] === 'school-library')) return require('./reports.cjs').execute(args[0], args[1] + '/' + args[2], args.slice(3));
+    const grouped = ['folder', 'textbook', 'reference'].includes(args[1]);
+    const command = grouped ? args[1] + '/' + args[2] : args[1];
+    if ((args[1] === 'reference' && args[0] !== 'lesson-prep') || (command === 'web' && args[0] !== 'school-library')) throw invalid('未知命令。');
+    return require('./business.cjs').execute(args[0], command, args.slice(grouped ? 3 : 2));
+  }
+  if (args[0] === 'auth' && ['login', 'connect', 'status', 'logout'].includes(args[1])) return require('./auth.cjs')[args[1]](args.slice(2));
+  if (args[0] === 'config' && args[1] === 'set') {
+    const filtered = args.slice(2);
+    if (filtered.some(arg => arg.startsWith('--'))) throw unknownOption(filtered.find(arg => arg.startsWith('--')), []);
+    if (filtered.length !== 2 || filtered[0] !== 'gateway-url') throw invalid('用法：config set gateway-url <http(s)-url>。');
+    const { gatewayURL } = require('./gateway.cjs');
+    const { loadConfig, saveConfig } = require('./storage.cjs');
+    let next;
+    try { next = gatewayURL({ gateway_url: filtered[1] }); } catch (error) { throw attach(invalid('Gateway URL 必须是有效的 HTTP(S) 地址。'), error); }
+    if (!filtered[1].trim()) throw invalid('Gateway URL 必须是有效的 HTTP(S) 地址。');
+    const config = await loadConfig();
+    if (config.current_profile && gatewayURL(config) !== next) throw new Failure(6, 'security', 'gateway_change_requires_logout', '切换 Gateway 前必须先退出当前 CLI 登录。');
+    config.gateway_url = next;
+    await saveConfig(config);
+    return success({ gateway_url: next });
+  }
+  return { code: 2, value: { ok: false, error: {
+    type: 'validation', subtype: 'invalid_arguments', message: '未知命令。',
+  } } };
+}
+
+async function run(args) {
+  const command = Object.keys(usage).filter(item => item.split(' ').every((word, index) => args[index] === word))
+    .sort((left, right) => right.length - left.length)[0];
+  let result;
+  try { result = await execute(args); }
+  catch (error) { if (error instanceof Failure) result = error.result; else throw error; }
+  if (command && result.value?.ok && !guidance.validResult(command, result.value.data)) {
+    const failure = new Failure(1, 'api', 'invalid_response', guidance.resultProblem(command, result.value.data));
+    if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+    result = failure.result;
+  }
+  if (command && result.value) {
+    if (result.value.ok) {
+      const next = guidance.message(command, result.value.data);
+      if (next && !result.value.data.message) result.value.data.message = next;
+    } else {
+      const error = result.value.error;
+      if (error.candidates) error.hint = `请核对候选；使用 ${command} --help 查看参数，不自动执行候选。`;
+      const exchanging = command === 'auth login' && args.includes('--device-code');
+      if (!error.hint || ['请根据错误信息处理后重试。', '请修正参数后重试。'].includes(error.hint) || error.operation_completed || error.cleanup_failed
+          || exchanging) error.hint = guidance.errorHint(command, error, exchanging);
+    }
+  }
+  return result;
+}
+
+module.exports = { run };