@xiaoyuanhao/yunzhi-cli 2.0.0

package/lib/report-schemas.cjs

@@ -0,0 +1,22 @@
+const { optionalFields, nullableFields, nullable, present } = require('./result.cjs');
+const source = { ...optionalFields({ name: 'string', org_name: 'string', reporter_name: 'string', contributor_name: 'string',
+  file_ext: 'string', type: 'string', size_bytes: 'integer', updated_at: 'string', category_name: 'string', labels: ['string'], web_url: 'string' }), file_id: present('string') };
+const detail = { ...optionalFields({ report_id: 'string', status: 'string', source,
+  target: optionalFields({ space: 'string', org_name: 'string', library_name: 'string', directory_name: 'string', path: 'string' }),
+  remark: 'string', submitted_at: 'string', processed_at: 'string',
+  actual: optionalFields({ file_id: 'string', name: 'string', path: 'string', web_url: 'string' }),
+  timeline: [optionalFields({ status: 'string', actor_name: 'string', reason: 'string', occurred_at: 'string' })],
+}), approval_preview: present({ ...nullableFields({ category_name: 'string', folder_id: 'string', library_name: 'string', directory_name: 'string', path: 'string' }), labels: ['string'] }) };
+const event = optionalFields({ event: 'string', report_id: 'string', status: 'string', source_name: 'string', reason: 'string' });
+module.exports = {
+  errors: {
+    report_already_exists: { report_id: 'string', status: 'string', source_name: 'string' },
+    report_not_pending: { current_status: 'string' },
+  },
+  'report/submit': event, 'report/cancel': event, 'review/reject': event,
+  'report/show': detail, 'review/show': detail,
+  'report/list': { reports: [{ ...optionalFields({ report_id: 'string', source_name: 'string', status: 'string', target_org_name: 'string', target_directory_name: 'string', target_path: 'string', submitted_at: 'string', processed_at: 'string' }), file_id: present('string') }], next_cursor: nullable('string') },
+  'report/history': { source: nullable(source), attempts: [optionalFields({ report_id: 'string', status: 'string', submitted_at: 'string', processed_at: 'string', reason: 'string' })] },
+  'review/list': { reviews: [optionalFields({ report_id: 'string', status: 'string', source_name: 'string', source_file_ext: 'string', category_name: 'string', source_org_name: 'string', reporter_name: 'string', target_library_name: 'string', target_directory_name: 'string', target_path: 'string', submitted_at: 'string', processed_at: 'string' })], next_cursor: nullable('string') },
+  'review/approve': { event: 'string', report_id: 'string', status: 'string', file_id: 'string', name: 'string', path: 'string' },
+};

package/lib/reports.cjs

@@ -0,0 +1,43 @@
+const { invalid } = require('./result.cjs');
+const { options, required, confirm, limit } = require('./arguments.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(namespace, command, args) {
+  let payload, scope = 'school-library:read';
+  switch (command) {
+    case 'report/submit':
+      payload = options(args, ['file_id', 'remark', ...(namespace === 'lesson-prep' ? ['target_folder_id'] : [])], [], [], true);
+      required(payload, 'file_id');
+      if (payload.remark && ([...payload.remark].length > 500 || payload.remark.includes('\0'))) throw invalid('--remark 最多 500 个字符，且不能包含空字符。');
+      scope = 'school-library:write'; break;
+    case 'report/list':
+    case 'review/list': {
+      const review = command === 'review/list';
+      const names = ['status', 'limit', 'cursor', ...(review ? ['query'] : [])];
+      payload = { status: review ? 'pending' : null, ...(review ? { query: null } : {}), limit: 20, cursor: null,
+        ...options(args, names, [], names, true) };
+      const statuses = ['pending', 'approved', 'rejected', 'delisted', review ? 'all' : 'cancelled'];
+      if (payload.status !== null && !statuses.includes(payload.status)) throw invalid('--status 必须是 ' + statuses.join('、') + '。');
+      limit(payload, 100); break;
+    }
+    case 'report/show': case 'report/history': case 'report/cancel':
+      payload = options(args, ['report_id'], [], [], true); required(payload, 'report_id');
+      if (command === 'report/cancel') scope = 'school-library:write';
+      break;
+    case 'review/show': case 'review/approve': case 'review/reject': {
+      const reject = command === 'review/reject', write = command !== 'review/show';
+      payload = options(args, ['report_id', reject ? 'reason' : 'folder_id'], write ? ['yes'] : [], [], true);
+      required(payload, 'report_id');
+      if (reject) {
+        required(payload, 'reason');
+        if ([...payload.reason].length > 500 || payload.reason.includes('\0')) throw invalid('--reason 必须为 1 到 500 个字符，且不能包含空字符。');
+      }
+      if (write) { confirm(payload); scope = 'school-library:manage'; }
+      break;
+    }
+    default: throw invalid('未知命令。');
+  }
+  const schemas = require('./report-schemas.cjs');
+  return gateway.execute(scope, namespace + '/' + command, payload, schemas[command]);
+}
+module.exports = { execute };

package/lib/result.cjs

@@ -0,0 +1,73 @@
+const { attach, cleanup } = require('./diagnostics.cjs');
+class Failure extends Error {
+  constructor(code, type, subtype, message, extra = {}) {
+    super(message);
+    this.result = { code, value: { ok: false, error: { type, subtype, message, ...extra } } };
+  }
+}
+const success = data => ({ code: 0, value: { ok: true, data } });
+const invalid = message => new Failure(2, 'validation', 'invalid_arguments', message);
+const internal = (step, message, cause) => {
+  const failure = new Failure(5, 'internal', 'cli_internal_error', message, { step });
+  return cause ? attach(failure, cause) : failure;
+};
+const authRequired = (message, scope = 'school-library:read') => new Failure(3, 'authentication', 'auth_required', message, {
+  required_scopes: [scope],
+});
+
+// Preserve the primary failure; only attach already-projected public results.
+function cleanupFailure(error, completed, cause) {
+  if (!(error instanceof Failure)) return error;
+  if (cause) cleanup(error, cause);
+  else error.result.value.error.cleanup_failed = true;
+  if (completed) {
+    error.result.value.error.operation_completed = true;
+    error.result.value.data = completed.value.data;
+    if (completed.value.request_id) error.result.value.request_id = completed.value.request_id;
+  }
+  return error;
+}
+
+// Only explicitly declared fields may cross the CLI output boundary.
+const required = schema => ({ $required: schema });
+const optional = schema => ({ $optional: schema });
+const nullable = schema => ({ $nullable: schema });
+const present = schema => ({ $present: schema });
+const optionalFields = schema => Object.fromEntries(Object.entries(schema).map(([key, type]) => [key, optional(type)]));
+const nullableFields = schema => Object.fromEntries(Object.entries(schema).map(([key, type]) => [key, nullable(type)]));
+function fields(value, schema, path = 'data') {
+  if (schema.$required !== undefined) {
+    if (value == null || (schema.$required === 'string' && (typeof value !== 'string' || !value.trim()))) {
+      throw new Error(`响应字段 ${path} 缺失或无效。`);
+    }
+    return fields(value, schema.$required, path);
+  }
+  if (schema.$present !== undefined) return value == null ? value : fields(value, schema.$present, path);
+  if (schema.$optional !== undefined) return value == null ? undefined : fields(value, schema.$optional, path);
+  if (schema.$nullable !== undefined) return value == null ? null : fields(value, schema.$nullable, path);
+  if (Array.isArray(schema)) {
+    if (value == null) return null;
+    if (!Array.isArray(value)) throw new Error(`响应字段 ${path} 类型无效。`);
+    return value.map((item, index) => fields(item, schema[0], `${path}[${index}]`));
+  }
+  if (typeof schema === 'string') {
+    if (schema === 'integer') {
+      if (value == null) return 0;
+      if (!Number.isSafeInteger(value)) throw new Error(`响应字段 ${path} 类型无效。`);
+      return value;
+    }
+    if (value == null) return { string: '', number: 0, boolean: false }[schema];
+    if (typeof value !== schema) throw new Error(`响应字段 ${path} 类型无效。`);
+    return value;
+  }
+  if (value == null) value = {};
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(`响应字段 ${path} 类型无效。`);
+  const result = {};
+  for (const [key, type] of Object.entries(schema)) {
+    const projected = fields(value[key], type, `${path}.${key}`);
+    if (projected !== undefined) result[key] = projected;
+  }
+  return result;
+}
+
+module.exports = { Failure, success, invalid, internal, authRequired, cleanupFailure, fields, required, optional, nullable, present, optionalFields, nullableFields };

package/lib/session.cjs

@@ -0,0 +1,24 @@
+const { detail } = require('./diagnostics.cjs');
+const { authRequired, Failure } = require('./result.cjs');
+const { loadConfig, readCredential, expired } = require('./storage.cjs');
+
+async function tokenFor(profile) {
+  if (!profile) return '';
+  try { return await readCredential(profile.credential_ref); }
+  catch (error) {
+    if (error.code === 'ENOENT') return '';
+    throw new Failure(5, 'internal', 'local_storage_error', '无法读取本地凭据。', { step: 'read_credential', detail: detail(error) });
+  }
+}
+
+async function session(scope) {
+  const config = await loadConfig();
+  if (!config.current_profile) throw authRequired('本机尚未登录校园号。', scope);
+  if (expired(config.current_profile)) throw authRequired('本机校园号登录已过期。', scope);
+  const token = await tokenFor(config.current_profile);
+  if (!token) throw authRequired('本机登录凭据缺失，无法执行本次业务。', scope);
+  return { config, token };
+}
+
+function writeScope(namespace) { return namespace === 'school-library' ? 'school-library:manage' : 'school-library:write'; }
+module.exports = { session, tokenFor, writeScope };

package/lib/storage.cjs

@@ -0,0 +1,122 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { randomBytes } = require('node:crypto');
+const { internal, Failure } = require('./result.cjs');
+const { detail, cleanup } = require('./diagnostics.cjs');
+
+const root = () => process.env.YUNZHI_CONFIG_DIR?.trim() || path.join(os.homedir(), '.yunzhi');
+async function loadConfig() {
+  try {
+    const config = JSON.parse(await fs.readFile(path.join(root(), 'config.json'), 'utf8'));
+    if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('invalid config');
+    return config;
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw internal('read_config', '无法读取本地配置。', error);
+  }
+}
+async function credentialPath(reference, creating = false) {
+  if (!/^cred_[0-9a-f]{32}$/.test(reference)) throw new Error('invalid credential reference');
+  const directory = path.join(root(), 'credentials');
+  for (const name of [root(), directory]) {
+    const info = await fs.lstat(name);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('invalid credential directory');
+  }
+  const file = path.join(directory, reference);
+  let info;
+  try { info = await fs.lstat(file); }
+  catch (error) { if (creating && error.code === 'ENOENT') return file; throw error; }
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error('invalid credential');
+  return file;
+}
+async function readCredential(reference) {
+  return fs.readFile(await credentialPath(reference), 'utf8');
+}
+const expired = profile => Boolean(profile?.expires_at && Date.parse(profile.expires_at) <= Date.now());
+
+async function ensureDirectory(directory) {
+  await fs.mkdir(directory, { recursive: true });
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('invalid directory');
+}
+function diagnostic(error) {
+  return { detail: error.detail || detail(error), ...(error.cleanup_failed ? { cleanup_failed: true } : {}) };
+}
+const storageFailure = (step, message, error) => new Failure(5, 'internal', 'local_storage_error', message, { step, ...diagnostic(error) });
+async function closeFile(handle, primaryError) {
+  try { await handle.close(); }
+  catch (error) {
+    if (!primaryError) throw error;
+    primaryError.detail ||= detail(primaryError);
+    cleanup(primaryError, error);
+  }
+}
+async function clearFile(file) {
+  const info = await fs.lstat(file);
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error('invalid cleanup target');
+  const handle = await fs.open(file, 'r+');
+  let primaryError;
+  try { await handle.truncate(0); await handle.sync(); }
+  catch (error) { primaryError = error; throw error; }
+  finally { await closeFile(handle, primaryError); }
+}
+async function removeCredential(reference) {
+  let file;
+  try { file = await credentialPath(reference); }
+  catch (error) { if (error.code === 'ENOENT') return; throw storageFailure('delete_credential', '无法清理本地凭据。', error); }
+  try { await clearFile(file); }
+  catch (error) { throw storageFailure('delete_credential', '无法清理本地凭据。', error); }
+}
+async function putCredential(token) {
+  const reference = 'cred_' + randomBytes(16).toString('hex');
+  let file, created = false;
+  try {
+    await ensureDirectory(root());
+    await ensureDirectory(path.join(root(), 'credentials'));
+    file = await credentialPath(reference, true);
+    const handle = await fs.open(file, 'wx');
+    created = true;
+    let primaryError;
+    try {
+      await handle.writeFile(token, 'utf8');
+      await handle.sync();
+    } catch (error) { primaryError = error; throw error; }
+    finally { await closeFile(handle, primaryError); }
+    return reference;
+  } catch (error) {
+    const failure = storageFailure('write_credential', '无法写入本地凭据文件。', error);
+    if (created) {
+      try { await clearFile(file); }
+      catch (cleanupError) { cleanup(failure, cleanupError); }
+    }
+    throw failure;
+  }
+}
+async function saveConfig(config) {
+  const destination = path.join(root(), 'config.json');
+  let opened = false;
+  try {
+    const content = JSON.stringify(config, null, 2) + '\n';
+    await ensureDirectory(root());
+    try {
+      const info = await fs.lstat(destination);
+      if (!info.isFile() || info.isSymbolicLink()) throw new Error('invalid config target');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const handle = await fs.open(destination, 'w');
+    opened = true;
+    let primaryError;
+    try {
+      await handle.writeFile(content);
+      await handle.sync();
+    } catch (error) { primaryError = error; throw error; }
+    finally { await closeFile(handle, primaryError); }
+  } catch (error) {
+    throw new Failure(5, 'internal', 'profile_write_failed', '无法保存本地配置；本次配置写入未完成。', {
+      step: 'save_profile', ...diagnostic(error),
+      ...(opened ? { local_path: destination, partial_file: true } : {}),
+    });
+  }
+}
+
+module.exports = { root, loadConfig, readCredential, expired, putCredential, removeCredential, saveConfig };

package/lib/suggestions.cjs

@@ -0,0 +1,46 @@
+const { invalid } = require('./result.cjs');
+
+function distance(left, right) {
+  let row = Array.from({ length: right.length + 1 }, (_, i) => i);
+  for (let i = 0; i < left.length; i++) {
+    const next = [i + 1];
+    for (let j = 0; j < right.length; j++) next.push(Math.min(next[j] + 1, row[j + 1] + 1, row[j] + (left[i] === right[j] ? 0 : 1)));
+    row = next;
+  }
+  return row[right.length];
+}
+function candidates(input, names, maximum) {
+  if (input.length > 100) return [];
+  const word = input.replace(/^--/, '');
+  return [...new Set(names)].map(name => {
+    const value = name.replace(/^--/, '');
+    let prefix = 0;
+    while (word[prefix] && word[prefix] === value[prefix]) prefix++;
+    return { name, prefix, distance: distance(word, value), segment: word.split('-').some(part => part && value.split('-').includes(part)) };
+  }).filter(item => item.prefix >= 3 || item.distance <= Math.max(2, Math.floor(word.length / 3)) || item.segment)
+    .sort((a, b) => b.prefix - a.prefix || a.distance - b.distance || a.name.localeCompare(b.name))
+    .slice(0, maximum).map(item => item.name);
+}
+function unknownOption(input, names) {
+  const error = invalid('包含未知参数：' + input);
+  error.result.value.error.candidates = candidates(input, names, 3);
+  return error;
+}
+function unknownCommand(words, names) {
+  let prefix = [];
+  for (const word of words) {
+    const children = [...new Set(names.filter(name => name.startsWith(prefix.length ? prefix.join(' ') + ' ' : ''))
+      .map(name => name.split(' ')[prefix.length]))];
+    if (!children.includes(word)) {
+      const error = invalid('未知命令：' + [...prefix, word].join(' ') + '。');
+      const help = prefix.length ? prefix.join(' ') + ' --help' : '--help';
+      Object.assign(error.result.value.error, { candidates: candidates(word, children, 6).map(name => [...prefix, name].join(' ')), hint: '请核对候选；使用 ' + help + ' 查看可用命令，不自动执行候选。' });
+      return error;
+    }
+    prefix.push(word);
+  }
+  const error = invalid('命令不完整。');
+  Object.assign(error.result.value.error, { candidates: [], hint: '使用 ' + (prefix.length ? prefix.join(' ') + ' --help' : '--help') + ' 查看可用命令。' });
+  return error;
+}
+module.exports = { unknownOption, unknownCommand };

package/lib/upload.cjs

@@ -0,0 +1,76 @@
+const { attach } = require('./diagnostics.cjs');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { Failure, nullableFields, cleanupFailure } = require('./result.cjs');
+const { options, required } = require('./arguments.cjs');
+const { session, writeScope } = require('./session.cjs');
+const { request, publicResult } = require('./gateway.cjs');
+const extensions = new Set('pdf doc docx ppt pptx xls xlsx jpg jpeg png gif mp4 avi mov mp3 wav txt m3u8 flv mpd'.split(' '));
+
+async function upload(namespace, args) {
+  const parsed = options(args, ['file', 'folder_id', 'title', 'category_id', 'label_id'], [], ['file', 'folder_id', 'category_id', 'label_id']);
+  required(parsed, 'file', 'folder_id');
+  let handle, result, primaryError;
+  let stage = 'local_file';
+  try { handle = await fs.open(parsed.file, 'r'); }
+  catch (error) { throw attach(new Failure(2, 'validation', 'invalid_local_file', '本地文件不可读取，上传尚未开始。'), error); }
+  try {
+    let info;
+    try { info = await handle.stat(); if (!info.isFile()) throw new Error(); }
+    catch (error) { throw attach(new Failure(2, 'validation', 'invalid_local_file', '本地路径不存在或不是普通文件，上传尚未开始。'), error); }
+    if (info.size === 0) throw new Failure(2, 'validation', 'invalid_local_file', '本地文件为空，上传尚未开始。');
+    const name = path.basename(parsed.file), extension = path.extname(name);
+    if (!extensions.has(extension.slice(1).toLowerCase())) throw new Failure(2, 'validation', 'unsupported_file_type', '不支持该文件格式，上传尚未开始。');
+    if (info.size >= 500 * 1024 * 1024) throw new Failure(2, 'validation', 'file_too_large', '文件必须小于 500 MiB，上传尚未开始。');
+    const base = name.slice(0, name.length - extension.length);
+    const title = parsed.title || (base.trim() ? base : name);
+    const { config, token } = await session(writeScope(namespace));
+    stage = 'upload_authorization';
+    const prepared = await request(config, namespace + '/upload/prepare', token, { folder_id: parsed.folder_id, file_name: name, size_bytes: info.size });
+    let grant;
+    try {
+      const value = prepared.data;
+      const text = input => { if (typeof input !== 'string' || !input.trim()) throw new Error(); return input.trim(); };
+      grant = { object_key: text(value.object_key), bucket: text(value.bucket), region: text(value.region),
+        secret_id: text(value.credentials.secret_id), secret_key: text(value.credentials.secret_key), session_token: text(value.credentials.session_token) };
+      const expires = text(value.credentials.expires_at);
+      if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(grant.bucket) || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(grant.region) ||
+          !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(expires) || !Number.isFinite(Date.parse(expires)) || Date.parse(expires) <= Date.now()) throw new Error();
+    } catch (error) { throw attach(new Failure(1, 'api', 'invalid_response', 'Agent Gateway 返回了无效上传授权。'), error); }
+    stage = 'file_transfer';
+    try { await require('./cos-upload.cjs').put(handle, info.size, grant); }
+    catch (error) { throw attach(new Failure(4, 'network', 'upload_failed', '文件传输结果无法确认，业务资源创建尚未开始。'), error); }
+    stage = 'resource_creation';
+    const completed = await request(config, namespace + '/upload/complete', token, {
+      folder_id: parsed.folder_id, object_key: grant.object_key, title, category_id: parsed.category_id || null, label_ids: parsed.label_ids || [],
+    });
+    const output = publicResult(completed, nullableFields({ type: 'string', file_id: 'string', kind: 'string', name: 'string', path: 'string',
+      file_ext: 'string', file_size: 'integer', updated_at: 'string', indexing: 'string',
+      ...(namespace === 'school-library' ? { space: 'string', web_url: 'string' } : {}),
+    }));
+    if (typeof output.value.data.file_id !== 'string' || !output.value.data.file_id.trim()) {
+      const failure = new Failure(1, 'api', 'invalid_response', '响应字段 data.file_id 缺失或无效，暂时无法确认业务资源创建结果。');
+      if (output.value.request_id) failure.result.value.request_id = output.value.request_id;
+      throw failure;
+    }
+    result = output;
+    return result;
+  } catch (error) {
+    if (error instanceof Failure) {
+      const failure = error.result.value.error;
+      failure.upload_stage = stage;
+      if (stage === 'resource_creation') {
+        failure.file_transferred = true;
+        failure.message = '文件传输已完成；业务资源创建阶段：' + failure.message;
+      } else if (stage === 'upload_authorization') failure.message = '取得上传授权阶段失败，文件传输尚未开始。' + failure.message;
+    }
+    primaryError = error;
+    throw error;
+  } finally {
+    try { await handle.close(); }
+    catch (error) {
+      throw cleanupFailure(primaryError || new Failure(5, 'local', 'storage_error', '无法关闭上传源文件。', { step: 'close_upload_source' }), result, error);
+    }
+  }
+}
+module.exports = { upload };

package/lib/version.cjs

@@ -0,0 +1,3 @@
+// The package manifest owns the CLI release identity.
+const { version } = require('../package.json');
+module.exports = { version };

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@xiaoyuanhao/yunzhi-cli",
+  "version": "2.0.0",
+  "description": "Yunzhi Campus CLI for lesson preparation and school library workflows",
+  "bin": {
+    "yunzhi-cli": "yunzhi-cli.cjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "yunzhi-cli.cjs",
+    "lib/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/yunzhi-cli.cjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+const { detail } = require('./lib/diagnostics.cjs');
+const { run } = require('./lib/cli.cjs');
+
+run(process.argv.slice(2)).then(({ code, value, text }) => {
+  (code ? process.stderr : process.stdout).write(text === undefined ? JSON.stringify(value) + '\n' : text);
+  process.exitCode = code;
+}).catch(error => {
+  process.stderr.write(JSON.stringify({ ok: false, error: {
+    type: 'internal', subtype: 'cli_internal_error', message: 'CLI 执行失败。', detail: detail(error),
+  } }) + '\n');
+  process.exitCode = 5;
+});