@xiaoyuanhao/yunzhi-cli 2.0.0

package/lib/download.cjs

@@ -0,0 +1,80 @@
+const { attach, cleanup } = require('./diagnostics.cjs');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { Failure, optionalFields } = require('./result.cjs');
+const { options, required } = require('./arguments.cjs');
+const { session } = require('./session.cjs');
+const { version } = require('./version.cjs');
+const { request, publicResult } = require('./gateway.cjs');
+const local = (message, extra) => new Failure(5, 'local', 'storage_error', message, extra);
+const network = error => {
+  const failure = new Failure(4, 'network', 'download_failed', '原文件下载失败。');
+  return error ? attach(failure, error) : failure;
+};
+const exists = target => new Failure(5, 'local', 'output_already_exists', '本地目标文件已经存在，本次未覆盖。', { local_path: target, hint: '报告实际 local_path，由用户决定另存或覆盖；不要自动改名或覆盖。' });
+
+async function download(namespace, args) {
+  const parsed = options(args, ['file', 'output'], ['overwrite'], ['file', 'output']);
+  required(parsed, 'file');
+  const { config, token } = await session('school-library:read');
+  const envelope = await request(config, namespace + '/download', token, { file: parsed.file });
+  const data = envelope.data;
+  try {
+    const url = new URL(data.download_url);
+    if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password || url.hash ||
+        typeof data.name !== 'string' || !data.name || ['.', '..'].includes(data.name) || /[/\\\0]/.test(data.name) ||
+        !Number.isSafeInteger(data.size_bytes) || data.size_bytes < 0) throw new Error();
+  } catch (error) { throw attach(new Failure(1, 'api', 'invalid_response', 'Agent Gateway 返回了无效下载响应。'), error); }
+  let target;
+  try { target = path.resolve(parsed.output || data.name); } catch (error) { throw attach(local('无法解析本地目标路径。'), error); }
+  // Validate the public response before creating or replacing any user file.
+  const result = publicResult({ ...envelope, data: { ...data, local_path: target } }, {
+    ...optionalFields({ file_id: 'string', kind: 'string', space: 'string', name: 'string', path: 'string', file_ext: 'string', size_bytes: 'integer' }), local_path: 'string',
+  });
+  try {
+    const info = await fs.lstat(target);
+    if (!parsed.overwrite) throw exists(target);
+    if (!info.isFile() || info.isSymbolicLink()) throw local('覆盖目标必须是普通文件。');
+  } catch (error) { if (error instanceof Failure) throw error; if (error.code !== 'ENOENT') throw attach(local('无法检查本地目标文件。'), error); }
+  let handle, opened = false, primaryError;
+  try {
+    try { handle = await fs.open(target, parsed.overwrite ? 'w' : 'wx'); opened = true; }
+    catch (error) {
+      if (!parsed.overwrite && error.code === 'EEXIST') throw attach(exists(target), error);
+      throw attach(local('无法打开本地目标文件。'), error);
+    }
+    let response;
+    try { response = await fetch(data.download_url, { headers: { 'User-Agent': 'yunzhi-cli/' + version }, signal: AbortSignal.timeout(25 * 60 * 1000) }); }
+    catch (error) { throw network(error); }
+    if (!response.ok) {
+      const failure = network(new Error('HTTP ' + response.status + ' ' + response.statusText));
+      try { await response.body?.cancel(); } catch (error) { cleanup(failure, error); }
+      throw failure;
+    }
+    let size = 0;
+    try {
+      for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > data.size_bytes) throw network(new Error('Download exceeds expected size: ' + size + ' > ' + data.size_bytes));
+        try { await handle.writeFile(chunk); } catch (error) { throw attach(local('无法写入本地文件。'), error); }
+      }
+    } catch (error) { if (error instanceof Failure) throw error; throw network(error); }
+    if (size !== data.size_bytes) throw network(new Error('Download size mismatch: expected ' + data.size_bytes + ', received ' + size));
+    try { await handle.sync(); await handle.close(); handle = undefined; }
+    catch (error) { throw attach(local('无法写入本地文件。'), error); }
+    return result;
+  } catch (error) {
+    primaryError = error;
+    if (opened && error instanceof Failure) Object.assign(error.result.value.error, { local_path: target, partial_file: true });
+    throw error;
+  } finally {
+    if (handle) {
+      try { await handle.close(); }
+      catch (error) {
+        if (primaryError) cleanup(primaryError, error);
+        else throw attach(local('无法关闭本地文件。', { local_path: target, partial_file: true }), error);
+      }
+    }
+  }
+}
+module.exports = { download };

package/lib/gateway.cjs

@@ -0,0 +1,124 @@
+const { detail, attach } = require('./diagnostics.cjs');
+const { Failure, internal, fields, optional } = require('./result.cjs');
+const fs = require('node:fs');
+const { randomBytes } = require('node:crypto');
+const { Readable } = require('node:stream');
+
+const learningToolUploadTimeoutMs = 25 * 60 * 1000;
+
+function gatewayURL(config) {
+  const raw = (config.gateway_url?.trim() || process.env.YUNZHI_GATEWAY_URL?.trim() ||
+    'https://opc.api.xiaoyuanhao.com');
+  try {
+    // Check before URL normalization removes dot segments.
+    const pathname = raw.replace(/^https?:\/\/[^/]+/, '');
+    if (/[?#]/.test(raw) || /\/\//.test(pathname) || /(?:^|\/)\.{1,2}(?:\/|$)/.test(decodeURIComponent(pathname))) throw new Error();
+    const url = new URL(raw);
+    if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password) throw new Error();
+    return url.href.replace(/\/$/, '');
+  } catch (error) { throw internal('validate_gateway_url', '本地 Gateway URL 无效。', error); }
+}
+async function execute(scope, endpoint, payload, schema) {
+  const { config, token } = await require('./session.cjs').session(scope);
+  return publicResult(await request(config, endpoint, token, payload), schema);
+}
+
+async function request(config, endpoint, token, payload, signal = AbortSignal.timeout(80000)) {
+  const address = gatewayURL(config) + '/api/v1/cli/' + endpoint;
+  const response = await send(address, {
+      method: payload === undefined ? 'GET' : 'POST',
+      headers: { 'Content-Type': 'application/json', 'User-Agent': 'yunzhi-cli/' + require('./version.cjs').version,
+        ...(token ? { Authorization: 'Bearer ' + token } : {}) },
+      body: payload === undefined ? undefined : JSON.stringify(payload),
+      redirect: 'error', signal,
+    });
+  return responseEnvelope(response);
+}
+
+async function multipartRequest(config, endpoint, token, values, filePath) {
+  const boundary = 'yunzhi-' + randomBytes(18).toString('hex');
+  async function* parts() {
+    for (const name of Object.keys(values).sort()) for (const value of values[name]) {
+      yield Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`);
+    }
+    yield Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="learning-tool.zip"\r\nContent-Type: application/zip\r\n\r\n`);
+    for await (const chunk of fs.createReadStream(filePath)) yield chunk;
+    yield Buffer.from(`\r\n--${boundary}--\r\n`);
+  }
+  const address = gatewayURL(config) + '/api/v1/cli/' + endpoint;
+  const response = await send(address, {
+    method: 'POST', body: Readable.from(parts()), duplex: 'half', redirect: 'error',
+    headers: { 'Content-Type': `multipart/form-data; boundary=${boundary}`,
+      'User-Agent': 'yunzhi-cli/' + require('./version.cjs').version,
+      Authorization: 'Bearer ' + token }, signal: AbortSignal.timeout(learningToolUploadTimeoutMs),
+  });
+  return responseEnvelope(response);
+}
+
+async function send(address, options) {
+  try { return await fetch(address, options); }
+  catch (error) {
+    const cause = error.cause || error;
+    const codes = cause.errors?.map(item => item.code) || [cause.code];
+    const notConnected = codes.length && codes.every(code => ['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ENETUNREACH', 'EHOSTUNREACH'].includes(code));
+    const timeout = error.name === 'TimeoutError' || ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT'].includes(cause.code);
+    const interrupted = ['ECONNRESET', 'EPIPE', 'UND_ERR_SOCKET'].includes(cause.code);
+    const subtype = notConnected ? 'connection_failed' : timeout ? 'request_timeout' : interrupted ? 'connection_interrupted' : 'network_error';
+    const message = notConnected ? '无法连接业务服务，本次请求未能建立连接。'
+      : timeout ? '等待业务服务响应超时，暂时无法确认本次操作结果。'
+      : interrupted ? '与业务服务的连接中断，暂时无法确认本次操作结果。'
+      : '请求业务服务时发生网络错误，暂时无法确认本次操作结果。';
+    throw new Failure(4, 'network', subtype, message, { step: 'send_gateway_request', detail: detail(error) });
+  }
+}
+
+async function responseEnvelope(response) {
+  let text;
+  try { text = await response.text(); }
+  catch (error) { throw new Failure(4, 'network', 'response_read_failed', '未能完整接收业务服务的返回，暂时无法确认本次操作结果。', { step: 'read_gateway_response', detail: detail(error) }); }
+  let envelope;
+  try { envelope = JSON.parse(text); }
+  catch (error) { throw new Failure(1, 'api', 'invalid_response', '已收到业务服务响应，但无法解析 JSON，暂时无法确认本次操作结果。', { step: 'decode_gateway_response', detail: detail(error) }); }
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) throw new Failure(1, 'api', 'invalid_response', '已收到业务服务响应，但响应格式无效，暂时无法确认本次操作结果。');
+  if (!response.ok || envelope.ok !== true) {
+    const invalidError = cause => {
+      const message = cause?.message?.startsWith('响应字段 ') ? cause.message
+        : '业务服务的错误响应缺少有效的 error.type、error.subtype 或 error.message。';
+      const failure = new Failure(1, 'api', 'invalid_response', message + '暂时无法确认本次操作结果。');
+      if (typeof envelope.request_id === 'string' && envelope.request_id) failure.result.value.request_id = envelope.request_id;
+      return cause ? attach(failure, cause) : failure;
+    };
+    let error;
+    try {
+      error = fields(envelope.error, { type: 'string', subtype: 'string', message: 'string', hint: optional('string'), detail: optional('string'), required_scopes: optional(['string']), current_status: optional('string') }, 'error');
+      let details = require('./business-schemas.cjs').errors[error.subtype];
+      if (!details && ['page_publish_result_unknown'].includes(error.subtype)
+        && envelope.error.details?.upload_stage != null)
+        details = { upload_stage: 'string' };
+      if (details && envelope.error.details != null) error.details = fields(envelope.error.details, details, 'error.details');
+    }
+    catch (error) { throw invalidError(error); }
+    if (!error?.type || !error.subtype || !error.message) throw invalidError();
+    const codes = { authentication: 3, authorization: 3, configuration: 3, validation: 2, network: 4, security: 6, policy: 6 };
+    const failure = new Failure(codes[error.type] || 1, error.type, error.subtype, error.message, error);
+    if (typeof envelope.request_id === 'string' && envelope.request_id) failure.result.value.request_id = envelope.request_id;
+    throw failure;
+  }
+  return envelope;
+}
+function publicResult(envelope, schema) {
+  let data;
+  try {
+    if (!envelope.data || typeof envelope.data !== 'object' || Array.isArray(envelope.data)) throw new Error('invalid response');
+    data = fields(envelope.data, schema);
+  }
+  catch (error) {
+    const failure = attach(new Failure(1, 'api', 'invalid_response', error.message.startsWith('响应字段 ') ? error.message : '业务服务返回的数据不是有效对象。'), error);
+    if (typeof envelope.request_id === 'string' && envelope.request_id) failure.result.value.request_id = envelope.request_id;
+    throw failure;
+  }
+  const value = { ok: true, data };
+  if (typeof envelope.request_id === 'string' && envelope.request_id) value.request_id = envelope.request_id;
+  return { code: 0, value };
+}
+module.exports = { gatewayURL, execute, request, multipartRequest, publicResult };

package/lib/learning-tool-archive.cjs

@@ -0,0 +1,275 @@
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { createDeflateRaw, createInflateRaw } = require('node:zlib');
+const { Readable, Transform } = require('node:stream');
+const { Failure } = require('./result.cjs');
+
+const MAX_PACKAGE = 500 * 1024 * 1024;
+const MAX_FILE = 100 * 1024 * 1024;
+const MAX_FILES = 2000;
+const MAX_NAME = 1024;
+const allowed = new Set('.html .htm .css .js .mjs .json .txt .csv .pdf .wasm .png .jpg .jpeg .webp .gif .svg .mp3 .wav .ogg .mp4 .webm .woff .woff2 .ttf .otf'.split(' '));
+const attribute = /\b(?:src|href)\s*=\s*["']([^"']+)["']/gis;
+const cssURL = /\burl\s*\(\s*["']?([^"')]+)/gis;
+
+function invalid(subtype, message) { return new Failure(2, 'validation', subtype, message); }
+function safeName(name) {
+  if (!name || Buffer.byteLength(name) > MAX_NAME || name.includes('\\') || name.startsWith('/') ||
+      /^[a-zA-Z]:/.test(name) || name.includes('\0') || /[\x00-\x1f\x7f]/.test(name)) return false;
+  const clean = path.posix.normalize(name.replace(/\/$/, ''));
+  return clean !== '.' && clean !== '..' && !clean.startsWith('../') && clean === name.replace(/\/$/, '');
+}
+function supported(name) { return allowed.has(path.posix.extname(name).toLowerCase()); }
+
+async function normalize(source) {
+  let sourceInfo;
+  try { sourceInfo = await fsp.lstat(source); }
+  catch (error) { throw invalid('invalid_local_source', '本地学具 source 不存在或不可读取。'); }
+  if (sourceInfo.isSymbolicLink()) throw invalid('unsafe_learning_tool_source', '本地学具 source 不能是符号链接。');
+  const temporary = await fsp.mkdtemp(path.join(os.tmpdir(), 'yunzhi-learning-tool-'));
+  const archivePath = path.join(temporary, 'learning-tool.zip');
+  const cleanup = async () => fsp.rm(temporary, { recursive: true, force: true });
+  try {
+    let entries;
+    const extension = path.extname(source).toLowerCase();
+    if (sourceInfo.isDirectory()) entries = await directoryEntries(source);
+    else if (!sourceInfo.isFile()) throw invalid('invalid_learning_tool_source', 'source 只接受目录、ZIP 或单个自包含 HTML。');
+    else if (extension === '.zip') {
+      if (sourceInfo.size > MAX_PACKAGE) throw invalid('learning_tool_package_too_large', 'ZIP 不能超过 500 MiB。');
+      entries = await zipEntries(source);
+    } else if (extension === '.html' || extension === '.htm') {
+      await validateStandalone(source, sourceInfo.size);
+      entries = [{ name: 'index.html', size: sourceInfo.size, open: () => fs.createReadStream(source) }];
+    } else throw invalid('invalid_learning_tool_source', 'source 只接受目录、ZIP 或单个自包含 HTML。');
+    validateEntries(entries);
+    await write(archivePath, entries);
+    const result = await fsp.stat(archivePath);
+    if (result.size > MAX_PACKAGE) throw invalid('learning_tool_package_too_large', '规范化后的 ZIP 不能超过 500 MiB。');
+    const digest = createHash('sha256');
+    for await (const chunk of fs.createReadStream(archivePath)) digest.update(chunk);
+    const names = new Set(entries.map(entry => entry.name));
+    const coverFile = ['cover.webp', 'cover.png', 'cover.jpg'].find(name => names.has(name)) || null;
+    return { archive_path: archivePath, sha256: digest.digest('hex'), cover_file: coverFile, cleanup };
+  } catch (error) { await cleanup(); throw error; }
+}
+
+async function directoryEntries(root) {
+  const entries = [];
+  async function visit(directory, prefix = '') {
+    let children;
+    try { children = await fsp.readdir(directory, { withFileTypes: true }); }
+    catch (error) { throw invalid('invalid_local_source', '本地学具目录不可读取。'); }
+    children.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+    for (const child of children) {
+      const location = path.join(directory, child.name);
+      const info = await fsp.lstat(location);
+      const name = prefix ? prefix + '/' + child.name : child.name;
+      if (info.isSymbolicLink()) throw invalid('unsafe_learning_tool_source', '学具目录不能包含符号链接。');
+      if (info.isDirectory()) await visit(location, name);
+      else if (!info.isFile()) throw invalid('unsafe_learning_tool_source', '学具目录只能包含普通静态文件。');
+      else entries.push({ name, size: info.size, open: () => fs.createReadStream(location) });
+    }
+  }
+  await visit(root);
+  return entries;
+}
+
+function validateEntries(entries) {
+  if (entries.length > MAX_FILES) throw invalid('learning_tool_too_many_files', '学具文件数不能超过 2,000。');
+  const names = new Set(); let total = 0;
+  for (const entry of entries) {
+    if (!safeName(entry.name)) throw invalid('unsafe_learning_tool_source', '学具包含不安全路径。');
+    if (names.has(entry.name)) throw invalid('unsafe_learning_tool_source', '学具包含重复路径。');
+    names.add(entry.name);
+    if (!supported(entry.name)) throw invalid('unsupported_learning_tool_file', '学具包含不支持的静态文件：' + entry.name);
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_FILE)
+      throw invalid('learning_tool_file_too_large', '学具中的单个文件不能超过 100 MiB。');
+    total += entry.size;
+    if (total > MAX_PACKAGE) throw invalid('learning_tool_extracted_too_large', '学具文件合计不能超过 500 MiB。');
+  }
+  if (!names.has('index.html')) throw invalid('learning_tool_index_missing', '学具根目录必须包含 index.html。');
+}
+
+async function validateStandalone(location, size) {
+  if (size > MAX_FILE) throw invalid('learning_tool_file_too_large', '单个 HTML 不能超过 100 MiB。');
+  let content;
+  try { content = await fsp.readFile(location, 'utf8'); }
+  catch (error) { throw invalid('invalid_local_source', '本地 HTML 不可读取。'); }
+  for (const expression of [attribute, cssURL]) {
+    expression.lastIndex = 0;
+    for (const match of content.matchAll(expression)) {
+      const value = match[1].trim().toLowerCase();
+      if (!value || value.startsWith('#') || value.startsWith('data:') || value.startsWith('blob:') || value.startsWith('https://')) continue;
+      throw invalid('standalone_html_has_local_assets', '单个 HTML 引用了旁边文件；请改用包含附件的目录或 ZIP。');
+    }
+  }
+}
+
+async function zipEntries(location) {
+  const parsed = await inspect(location, true);
+  const files = parsed.filter(entry => !entry.directory);
+  const names = new Set(files.map(entry => entry.name));
+  let prefix = '';
+  if (!names.has('index.html')) {
+    const top = new Set(files.map(entry => entry.name.split('/')[0]));
+    if (top.size !== 1) throw invalid('learning_tool_index_missing', 'ZIP 根目录或唯一顶层目录必须包含 index.html。');
+    prefix = [...top][0] + '/';
+    if (!names.has(prefix + 'index.html')) throw invalid('learning_tool_index_missing', 'ZIP 根目录或唯一顶层目录必须包含 index.html。');
+  }
+  return files.map(entry => ({
+    name: prefix ? entry.name.slice(prefix.length) : entry.name,
+    size: entry.size,
+    open: () => openZipEntry(location, entry),
+  }));
+}
+
+async function inspect(location, includeDirectories = false) {
+  const handle = await fsp.open(location, 'r');
+  try {
+    const stat = await handle.stat();
+    const tailSize = Math.min(stat.size, 65557);
+    const tail = Buffer.alloc(tailSize);
+    await handle.read(tail, 0, tailSize, stat.size - tailSize);
+    let eocd = -1;
+    for (let index = tail.length - 22; index >= 0; index--) {
+      if (tail.readUInt32LE(index) === 0x06054b50) { eocd = index; break; }
+    }
+    if (eocd < 0 || tail.readUInt16LE(eocd + 4) !== 0 || tail.readUInt16LE(eocd + 6) !== 0)
+      throw invalid('invalid_learning_tool_archive', 'ZIP 无法读取。');
+    const count = tail.readUInt16LE(eocd + 10);
+    const centralSize = tail.readUInt32LE(eocd + 12);
+    const centralOffset = tail.readUInt32LE(eocd + 16);
+    if (count > MAX_FILES || centralSize > 16 * 1024 * 1024 || centralOffset + centralSize > stat.size)
+      throw invalid('invalid_learning_tool_archive', 'ZIP 目录无效或文件数超限。');
+    const central = Buffer.alloc(centralSize);
+    await handle.read(central, 0, centralSize, centralOffset);
+    const entries = []; let offset = 0;
+    for (let index = 0; index < count; index++) {
+      if (offset + 46 > central.length || central.readUInt32LE(offset) !== 0x02014b50)
+        throw invalid('invalid_learning_tool_archive', 'ZIP 目录无效。');
+      const flags = central.readUInt16LE(offset + 8);
+      const method = central.readUInt16LE(offset + 10);
+      const crc = central.readUInt32LE(offset + 16);
+      const compressedSize = central.readUInt32LE(offset + 20);
+      const size = central.readUInt32LE(offset + 24);
+      const nameLength = central.readUInt16LE(offset + 28);
+      const extraLength = central.readUInt16LE(offset + 30);
+      const commentLength = central.readUInt16LE(offset + 32);
+      const external = central.readUInt32LE(offset + 38);
+      const localOffset = central.readUInt32LE(offset + 42);
+      if (flags & 1 || ![0, 8].includes(method) || nameLength < 1 || nameLength > MAX_NAME ||
+          [compressedSize, size, localOffset].includes(0xffffffff))
+        throw invalid('invalid_learning_tool_archive', 'ZIP 使用了不支持的加密、压缩或 ZIP64 格式。');
+      const end = offset + 46 + nameLength + extraLength + commentLength;
+      if (end > central.length) throw invalid('invalid_learning_tool_archive', 'ZIP 目录无效。');
+      const nameBuffer = central.subarray(offset + 46, offset + 46 + nameLength);
+      const name = new TextDecoder('utf-8', { fatal: true }).decode(nameBuffer);
+      const mode = external >>> 16;
+      const directory = name.endsWith('/');
+      if (!safeName(name) || (mode & 0o170000) === 0o120000 || (!directory && mode && (mode & 0o170000) !== 0o100000))
+        throw invalid('unsafe_learning_tool_archive', 'ZIP 包含符号链接、特殊文件或不安全路径。');
+      if (!directory) entries.push({ name, size, compressedSize, method, crc, localOffset });
+      else if (includeDirectories) entries.push({ name, directory: true });
+      offset = end;
+    }
+    if (offset !== central.length) throw invalid('invalid_learning_tool_archive', 'ZIP 目录包含多余数据。');
+    return entries;
+  } catch (error) {
+    if (error instanceof Failure) throw error;
+    throw invalid('invalid_learning_tool_archive', 'ZIP 无法读取。');
+  } finally { await handle.close(); }
+}
+
+async function openZipEntry(location, entry) {
+  const handle = await fsp.open(location, 'r');
+  const header = Buffer.alloc(30);
+  try {
+    await handle.read(header, 0, 30, entry.localOffset);
+    if (header.readUInt32LE(0) !== 0x04034b50) throw new Error('local header');
+    const start = entry.localOffset + 30 + header.readUInt16LE(26) + header.readUInt16LE(28);
+    await handle.close();
+    const compressed = entry.compressedSize === 0 ? Readable.from([])
+      : fs.createReadStream(location, { start, end: start + entry.compressedSize - 1 });
+    const stream = entry.method === 8 ? compressed.pipe(createInflateRaw()) : compressed;
+    return checkedStream(stream, entry);
+  } catch (error) { await handle.close().catch(() => {}); throw invalid('invalid_learning_tool_archive', 'ZIP 文件无法解压。'); }
+}
+
+function checkedStream(stream, expected) {
+  async function* check() {
+    let crc = 0xffffffff, size = 0;
+    for await (const chunk of stream) {
+      size += chunk.length;
+      if (size > MAX_FILE) throw invalid('learning_tool_file_too_large', '学具中的单个文件不能超过 100 MiB。');
+      crc = crc32Update(crc, chunk);
+      yield chunk;
+    }
+    crc = (crc ^ 0xffffffff) >>> 0;
+    if (size !== expected.size || crc !== expected.crc)
+      throw invalid('invalid_learning_tool_archive', 'ZIP 文件大小或校验值无效。');
+  }
+  return Readable.from(check());
+}
+
+async function write(destination, entries) {
+  const output = fs.createWriteStream(destination, { flags: 'wx' });
+  let offset = 0;
+  const central = [];
+  const writeChunk = chunk => new Promise((resolve, reject) => {
+    output.write(chunk, error => error ? reject(error) : resolve());
+  });
+  try {
+    for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+      const name = Buffer.from(entry.name);
+      const localOffset = offset;
+      const local = Buffer.alloc(30);
+      local.writeUInt32LE(0x04034b50, 0); local.writeUInt16LE(20, 4); local.writeUInt16LE(0x0808, 6);
+      local.writeUInt16LE(8, 8); local.writeUInt16LE(name.length, 26);
+      await writeChunk(local); await writeChunk(name); offset += local.length + name.length;
+      const source = await entry.open();
+      let crc = 0xffffffff, size = 0, compressedSize = 0;
+      const tracker = new Transform({ transform(chunk, encoding, callback) {
+        crc = crc32Update(crc, chunk); size += chunk.length; callback(null, chunk);
+      } });
+      const compressed = source.pipe(tracker).pipe(createDeflateRaw());
+      for await (const chunk of compressed) { await writeChunk(chunk); compressedSize += chunk.length; offset += chunk.length; }
+      crc = (crc ^ 0xffffffff) >>> 0;
+      if (size !== entry.size) throw invalid('invalid_local_source', '学具文件在打包期间发生变化。');
+      const descriptor = Buffer.alloc(16);
+      descriptor.writeUInt32LE(0x08074b50, 0); descriptor.writeUInt32LE(crc, 4);
+      descriptor.writeUInt32LE(compressedSize, 8); descriptor.writeUInt32LE(size, 12);
+      await writeChunk(descriptor); offset += descriptor.length;
+      central.push({ name, crc, size, compressedSize, localOffset });
+    }
+    const centralOffset = offset;
+    for (const entry of central) {
+      const header = Buffer.alloc(46);
+      header.writeUInt32LE(0x02014b50, 0); header.writeUInt16LE(0x0314, 4); header.writeUInt16LE(20, 6);
+      header.writeUInt16LE(0x0808, 8); header.writeUInt16LE(8, 10); header.writeUInt32LE(entry.crc, 16);
+      header.writeUInt32LE(entry.compressedSize, 20); header.writeUInt32LE(entry.size, 24);
+      header.writeUInt16LE(entry.name.length, 28); header.writeUInt32LE((0o100644 << 16) >>> 0, 38);
+      header.writeUInt32LE(entry.localOffset, 42);
+      await writeChunk(header); await writeChunk(entry.name); offset += header.length + entry.name.length;
+    }
+    const eocd = Buffer.alloc(22); const centralSize = offset - centralOffset;
+    eocd.writeUInt32LE(0x06054b50, 0); eocd.writeUInt16LE(central.length, 8); eocd.writeUInt16LE(central.length, 10);
+    eocd.writeUInt32LE(centralSize, 12); eocd.writeUInt32LE(centralOffset, 16);
+    await writeChunk(eocd);
+    await new Promise((resolve, reject) => output.end(error => error ? reject(error) : resolve()));
+  } catch (error) { output.destroy(); throw error; }
+}
+
+const crcTable = Array.from({ length: 256 }, (_, value) => {
+  let crc = value;
+  for (let bit = 0; bit < 8; bit++) crc = (crc & 1) ? (0xedb88320 ^ (crc >>> 1)) : (crc >>> 1);
+  return crc >>> 0;
+});
+function crc32Update(crc, buffer) {
+  for (const value of buffer) crc = crcTable[(crc ^ value) & 0xff] ^ (crc >>> 8);
+  return crc >>> 0;
+}
+
+module.exports = { normalize, inspect, write };

package/lib/learning-tool.cjs

@@ -0,0 +1,82 @@
+const { options, required, confirm, limit } = require('./arguments.cjs');
+const { invalid, optionalFields, nullable, required: requiredField } = require('./result.cjs');
+const { session } = require('./session.cjs');
+const gateway = require('./gateway.cjs');
+const archive = require('./learning-tool-archive.cjs');
+
+const entry = optionalFields({ type: 'string', folder_id: 'string', file_id: 'string', kind: 'string',
+  name: 'string', path: 'string', file_ext: 'string', file_size: 'integer', category_id: 'string',
+  label_ids: ['string'], updated_at: 'string', origin: 'string', run_url: 'string', cover_url: 'string',
+  can_update: 'boolean', can_move: 'boolean', can_remove: 'boolean' });
+const schemas = {
+  ls: { entries: requiredField([entry]), next_cursor: nullable('string') },
+  'upload-options': require('./business-schemas.cjs')['upload-options'],
+  upload: { file_id: requiredField('string'), title: requiredField('string'), path: requiredField('string'),
+    folder_id: requiredField('string'), origin: requiredField('string'), run_url: requiredField('string'),
+    cover_url: nullable('string'), size_bytes: 'integer', sha256: requiredField('string'), message: requiredField('string') },
+  update: entry, move: entry,
+  remove: { removed: 'boolean', file_id: requiredField('string'), mode: requiredField('string'), message: 'string' },
+};
+
+async function execute(command, args) {
+  if (command === 'upload') return upload(args);
+  let payload, scope = 'school-library:write';
+  if (command === 'ls') {
+    payload = listArguments(args); scope = 'school-library:read';
+  } else if (command === 'upload-options') {
+    payload = options(args, ['folder_id'], [], ['folder_id']); required(payload, 'folder_id');
+    scope = 'school-library:read';
+  } else if (command === '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 至少需要一个修改项。');
+  } else if (command === 'move') {
+    payload = options(args, ['file_id', 'folder_id', 'category_id', 'label_id'], ['clear_category', 'clear_labels']);
+    required(payload, 'file_id', 'folder_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 (!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。');
+  } else if (command === 'remove') {
+    payload = options(args, ['file_id'], ['yes']); required(payload, 'file_id'); confirm(payload);
+  } else throw invalid('未知命令。');
+  return gateway.execute(scope, 'learning-tool/' + command, payload, schemas[command]);
+}
+
+function listArguments(args) {
+  const payload = { path: '/', limit: 100, cursor: null };
+  let pathSet = false; const flags = [];
+  for (let index = 0; index < args.length; index++) {
+    const value = args[index];
+    if (value === '--limit' || value === '--cursor') {
+      if (flags.includes(value)) throw invalid(value + ' 不能重复传入。');
+      flags.push(value);
+      if (++index >= args.length || !args[index].trim() || args[index].startsWith('--')) throw invalid(value + ' 需要非空参数。');
+      if (value === '--limit') payload.limit = args[index]; else payload.cursor = args[index];
+    } else if (value.startsWith('-') || pathSet) throw invalid('learning-tool ls 包含未知参数。');
+    else { payload.path = value; pathSet = true; }
+  }
+  limit(payload, 200);
+  return payload;
+}
+
+async function upload(args) {
+  const payload = options(args, ['source', 'folder_id', 'title', 'category_id', 'label_id'], [], ['source']);
+
+  required(payload, 'source', 'folder_id', 'title');
+  const normalized = await archive.normalize(payload.source);
+  try {
+    const { config, token } = await session('school-library:write');
+    const values = { folder_id: [payload.folder_id], title: [payload.title], sha256: [normalized.sha256] };
+    if (normalized.cover_file) values.cover_file = [normalized.cover_file];
+    if (payload.category_id) values.category_id = [payload.category_id];
+    if (payload.label_ids) values.label_id = payload.label_ids;
+    const envelope = await gateway.multipartRequest(
+      config, 'learning-tool/upload', token, values, normalized.archive_path);
+    return gateway.publicResult(envelope, schemas.upload);
+  } finally { await normalized.cleanup(); }
+}
+
+module.exports = { execute, schemas };

package/lib/lesson-prep.cjs

@@ -0,0 +1,73 @@
+const { invalid, optionalFields, nullableFields, nullable } = require('./result.cjs');
+const { unknownOption } = require('./suggestions.cjs');
+const gateway = require('./gateway.cjs');
+
+const entry = optionalFields({ type: 'string', folder_id: 'string', file_id: 'string', kind: 'string', space: 'string',
+  name: 'string', path: 'string', file_ext: 'string', file_size: 'integer', category_id: 'string',
+  label_ids: ['string'], updated_at: 'string', web_url: 'string', source_file_deleted: 'boolean' });
+
+const locator = optionalFields({ source_type: 'string', segment_index: 'integer', begin_time: 'number', end_time: 'number',
+  page: 'integer', section: 'string', kind: 'string', slide: 'integer' });
+const snippet = nullableFields({ text: 'string', score: 'number', section: 'string', locator, start_line: 'integer', end_line: 'integer' });
+const searchItem = optionalFields({ type: 'string', file_id: 'string', kind: 'string', space: 'string', name: 'string',
+  path: 'string', file_ext: 'string', updated_at: 'string', score: 'number', snippets: [snippet], source_file_deleted: 'boolean' });
+const grepMatch = optionalFields({ type: 'string', file_id: 'string', kind: 'string', space: 'string', name: 'string',
+  path: 'string', line: 'integer', text: 'string', text_truncated: 'boolean', updated_at: 'string', web_url: 'string', source_file_deleted: 'boolean' });
+const fetchResult = optionalFields({ file_id: 'string', kind: 'string', space: 'string', name: 'string', path: 'string', file_ext: 'string',
+  updated_at: 'string', web_url: 'string', start_line: 'integer', content: 'string', next_start_line: 'integer', source_file_deleted: 'boolean' });
+const schemas = { ls: { entries: [entry], next_cursor: nullable('string') }, glob: { matches: [entry], next_cursor: nullable('string') },
+  search: { items: [searchItem], next_cursor: nullable('string') }, grep: { matches: [grepMatch], next_cursor: nullable('string') }, fetch: fetchResult };
+
+async function read(command, args, namespace = 'lesson-prep') {
+  const payload = command === 'fetch' ? { file: '', start_line: 1, limit: 200 } : { path: '/', limit: 100, cursor: null };
+  if (command === 'glob') Object.assign(payload, { pattern: '**/*', type: 'all' });
+  if (command === 'search') Object.assign(payload, { query: '', limit: 10 });
+  if (command === 'grep') Object.assign(payload, { patterns: [], glob: null, ignore_case: false, limit: 50 });
+  const maximum = { ls: 200, glob: 200, search: 20, grep: 100, fetch: 500 }[command];
+  const extraOptions = { ls: [], glob: ['--pattern', '--type'], search: ['--query'],
+    grep: ['--pattern', '--glob'], fetch: ['--file', '--start-line'] }[command];
+  let pathSet = false;
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    if (['--limit', ...(command !== 'fetch' ? ['--cursor'] : []), ...extraOptions, ...(command === 'grep' ? ['--ignore-case'] : [])].includes(args[i])
+        && !(command === 'grep' && args[i] === '--pattern')) {
+      if (seen.has(args[i])) throw invalid(args[i] + ' 不能重复传入。');
+      seen.add(args[i]);
+    }
+    if (command === 'grep' && args[i] === '--ignore-case') { payload.ignore_case = true; continue; }
+    if (args[i] === '--limit' || (args[i] === '--cursor' && command !== 'fetch') || extraOptions.includes(args[i])) {
+      const option = args[i];
+      if (++i >= args.length || ['--limit', '--cursor', '--ignore-case', '--help', '-h', ...extraOptions].includes(args[i])) throw invalid(option + ' 需要参数。');
+      if (option === '--cursor') payload.cursor = args[i];
+      else if (option === '--limit') {
+        if (!/^[+]?\d+$/.test(args[i]) || +args[i] < 1 || +args[i] > maximum) throw invalid(`--limit 必须在 1 到 ${maximum} 之间。`);
+        payload.limit = +args[i];
+      } else if (option === '--start-line') {
+        if (!/^[+]?\d+$/.test(args[i]) || +args[i] < 1 || +args[i] > 2147483647) throw invalid('--start-line 必须是 1 到 2147483647 之间的整数。');
+        payload.start_line = +args[i];
+      } else if (option === '--type') {
+        if (!['all', 'folder', 'file'].includes(args[i])) throw invalid('--type 必须是 all、folder 或 file。');
+        payload.type = args[i];
+      } else {
+        if (!args[i].trim()) throw invalid(option + ' 需要非空参数。');
+        if (command === 'grep' && option === '--pattern') {
+          if ([...args[i]].length > 200 || payload.patterns.length >= 10) throw invalid('--pattern 最多 10 次，每个最多 200 个字符。');
+          payload.patterns.push(args[i]);
+        } else payload[option.slice(2)] = option === '--query' ? args[i].trim() : args[i];
+      }
+    } else {
+      if (command === 'fetch' || pathSet || args[i].startsWith('-')) throw unknownOption(args[i], ['--limit', ...(command !== 'fetch' ? ['--cursor'] : []), ...extraOptions, ...(command === 'grep' ? ['--ignore-case'] : [])]);
+      payload.path = args[i]; pathSet = true;
+    }
+  }
+  if (command === 'fetch' && !payload.file) throw invalid('--file 不能为空。');
+  if (command === 'search' && !payload.query) throw invalid('--query 不能为空。');
+  if (command === 'grep' && !payload.patterns.length) throw invalid('至少需要一个 --pattern。');
+  const schema = namespace === 'school-library' && command === 'search' ? {
+    items: [{ ...nullableFields({ type: 'string', file_id: 'string', kind: 'string', space: 'string', name: 'string',
+      path: 'string', file_ext: 'string', updated_at: 'string', web_url: 'string', score: 'number' }), snippets: [snippet] }],
+    next_cursor: nullable('string'),
+  } : schemas[command];
+  return gateway.execute('school-library:read', namespace + '/' + command, payload, schema);
+}
+module.exports = { read, snippet };