@sovovs/bycli 2.1.60 → 2.1.61

package/README.zh-CN.md

@@ -50,6 +50,19 @@ bycli 12306 stations 北京        # 公开命令,无需登录
 bycli juejin search bycli        # 掘金搜索
 ```
 
+### 浩鲸邮箱
+
+在 Chrome 中登录 `mail.iwhalecloud.com` 并连接 Browser Bridge 后：
+
+```bash
+bycli iwhalecloud list --sort date --order desc --limit 50 -f yaml
+bycli iwhalecloud read "<emailId>" -f yaml
+bycli iwhalecloud download "<emailId>" --output ./mail-downloads -f yaml
+```
+
+支持默认顺序和 9 个字段的服务端排序、自动分页、邮件正文与附件下载。
+详细参数见[浩鲸邮箱适配器文档](./docs/adapters/browser/iwhalecloud.md)。
+
 ### 搜索适配器
 
 当前可用的搜索命令包括:

package/cli-manifest.json

@@ -14674,6 +14674,204 @@
     "sourceFile": "instagram/user.js",
     "navigateBefore": "https://www.instagram.com"
   },
+  {
+    "site": "iwhalecloud",
+    "name": "download",
+    "description": "下载浩鲸邮件附件到本地目录，同名文件自动编号",
+    "access": "read",
+    "example": "bycli iwhalecloud download \"<emailId>\" --attachment all --output ./mail-downloads -f yaml",
+    "domain": "mail.iwhalecloud.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "emailId",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "list 返回的 emailId（请加引号）"
+      },
+      {
+        "name": "attachment",
+        "type": "str",
+        "default": "all",
+        "required": false,
+        "help": "all（不含内嵌图片）、附件 ID 或 read 中的序号（从 1 开始）"
+      },
+      {
+        "name": "output",
+        "type": "str",
+        "default": ".",
+        "required": false,
+        "help": "本地输出目录"
+      }
+    ],
+    "columns": [
+      "emailId",
+      "attachmentId",
+      "name",
+      "path",
+      "size",
+      "contentType"
+    ],
+    "type": "js",
+    "modulePath": "iwhalecloud/download.js",
+    "sourceFile": "iwhalecloud/download.js",
+    "navigateBefore": false,
+    "siteSession": "persistent"
+  },
+  {
+    "site": "iwhalecloud",
+    "name": "list",
+    "description": "浩鲸邮箱邮件列表：服务端分页、默认排序及 9 种字段排序",
+    "access": "read",
+    "example": "bycli iwhalecloud list --sort date --order desc --limit 50 -f yaml",
+    "domain": "mail.iwhalecloud.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "folder",
+        "type": "str",
+        "default": "inbox",
+        "required": false,
+        "help": "邮件文件夹",
+        "choices": [
+          "inbox",
+          "sent",
+          "drafts",
+          "trash",
+          "spam"
+        ]
+      },
+      {
+        "name": "folder-id",
+        "type": "str",
+        "required": false,
+        "help": "自定义文件夹的 OWA FolderId，优先于 --folder"
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "返回数量，1–10000；自动分页"
+      },
+      {
+        "name": "offset",
+        "type": "int",
+        "default": 0,
+        "required": false,
+        "help": "服务端起始偏移，0 表示第一封"
+      },
+      {
+        "name": "sort",
+        "type": "str",
+        "default": "default",
+        "required": false,
+        "help": "default 保留服务端默认顺序",
+        "choices": [
+          "default",
+          "date",
+          "from",
+          "to",
+          "subject",
+          "attachments",
+          "importance",
+          "size",
+          "sent",
+          "created"
+        ]
+      },
+      {
+        "name": "order",
+        "type": "str",
+        "default": "default",
+        "required": false,
+        "help": "默认：姓名/主题升序，其余降序；显式方向须指定 --sort",
+        "choices": [
+          "default",
+          "asc",
+          "desc"
+        ]
+      }
+    ],
+    "columns": [
+      "emailId",
+      "subject",
+      "fromName",
+      "fromEmail",
+      "toDisplay",
+      "date",
+      "times",
+      "unread",
+      "hasAttachments",
+      "importance",
+      "size",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "iwhalecloud/list.js",
+    "sourceFile": "iwhalecloud/list.js",
+    "navigateBefore": false,
+    "siteSession": "persistent"
+  },
+  {
+    "site": "iwhalecloud",
+    "name": "read",
+    "description": "读取浩鲸邮件完整正文、收件人和附件列表（不标记已读）",
+    "access": "read",
+    "example": "bycli iwhalecloud read \"<emailId>\" -f yaml",
+    "domain": "mail.iwhalecloud.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "emailId",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "list 返回的 emailId（请加引号）"
+      },
+      {
+        "name": "body-type",
+        "type": "str",
+        "default": "text",
+        "required": false,
+        "help": "正文格式",
+        "choices": [
+          "text",
+          "html"
+        ]
+      }
+    ],
+    "columns": [
+      "emailId",
+      "subject",
+      "fromName",
+      "fromEmail",
+      "toDisplay",
+      "date",
+      "times",
+      "unread",
+      "hasAttachments",
+      "importance",
+      "size",
+      "url",
+      "to",
+      "cc",
+      "bcc",
+      "recipientCounts",
+      "bodyType",
+      "body",
+      "attachments"
+    ],
+    "type": "js",
+    "modulePath": "iwhalecloud/read.js",
+    "sourceFile": "iwhalecloud/read.js",
+    "navigateBefore": false,
+    "siteSession": "persistent"
+  },
   {
     "site": "jd",
     "name": "add-cart",

package/clis/iwhalecloud/browser-download.js

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+import { CommandExecutionError, TimeoutError } from '@sovovs/bycli/errors';
+
+// Stream through Chrome's authenticated connection and certificate trust store.
+// Only a 192 KiB chunk crosses the Browser Bridge at once; no cookie export.
+export async function browserDownloadResponse(page, attachmentId) {
+  const key = `__bycliAttachment_${randomUUID().replaceAll('-', '')}`;
+  const start = await page.evaluate(async (id, stateKey) => {
+    if (location.origin !== 'https://mail.iwhalecloud.com') return { status: 401 };
+    const cookie = document.cookie.split(';').map(x => x.trim()).find(x => x.startsWith('X-OWA-CANARY='));
+    if (!cookie) return { status: 401 };
+    if (window[stateKey]) return window[stateKey].start;
+    const state = { pending: new Uint8Array(0), sequence: -1 };
+    window[stateKey] = state;
+    state.start = (async () => {
+      try {
+        const response = await fetch(`/owa/service.svc/s/GetFileAttachment?id=${encodeURIComponent(id)}`, {
+          credentials: 'same-origin', redirect: 'manual', signal: AbortSignal.timeout(120000),
+          headers: { 'X-OWA-CANARY': decodeURIComponent(cookie.slice('X-OWA-CANARY='.length)) },
+        });
+        // Cross-origin/manual redirects are opaque in browsers (status 0).
+        if (response.status !== 200 || !response.body) {
+          await response.body?.cancel();
+          delete window[stateKey];
+          return { status: response.status || 401 };
+        }
+        state.reader = response.body.getReader();
+        return { status: response.status, contentType: response.headers.get('content-type') ?? 'application/octet-stream' };
+      } catch (error) {
+        delete window[stateKey];
+        return { failed: true, timeout: error.name === 'TimeoutError' || error.name === 'AbortError' };
+      }
+    })();
+    return state.start;
+  }, attachmentId, key);
+  if (start?.timeout) throw new TimeoutError('OWA attachment request', 120);
+  if (!start || start.failed) throw new CommandExecutionError('Could not open the OWA attachment download');
+  if (start.status !== 200) return new Response(null, { status: start.status });
+  const cleanup = async () => {
+    await page.evaluate(async stateKey => {
+      const state = window[stateKey];
+      delete window[stateKey];
+      if (state?.reader) await state.reader.cancel().catch(() => {});
+    }, key);
+  };
+  let sequence = 0;
+  return new Response(new ReadableStream({
+    async pull(controller) {
+      try {
+        const chunk = await page.evaluate(async (stateKey, requestedSequence) => {
+          const state = window[stateKey];
+          if (!state) return { missing: true };
+          // Bridge retries must return the same in-flight or completed chunk.
+          if (state.sequence === requestedSequence) return state.chunk;
+          if (requestedSequence !== state.sequence + 1) return { missing: true };
+          state.sequence = requestedSequence;
+          state.chunk = (async () => {
+            if (!state.pending.length) {
+              const result = await state.reader.read();
+              if (result.done) return { done: true };
+              state.pending = result.value;
+            }
+            const bytes = state.pending.subarray(0, 196608);
+            state.pending = state.pending.subarray(bytes.length);
+            let binary = '';
+            for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+            return { base64: btoa(binary) };
+          })();
+          return state.chunk;
+        }, key, sequence++);
+        if (chunk?.done) {
+          await cleanup();
+          controller.close();
+        } else if (typeof chunk?.base64 === 'string') controller.enqueue(Buffer.from(chunk.base64, 'base64'));
+        else throw new CommandExecutionError('OWA attachment transfer was interrupted; retry download');
+      } catch (error) {
+        await cleanup().catch(() => {});
+        controller.error(error);
+      }
+    },
+    cancel: cleanup,
+  }, { highWaterMark: 0 }), { headers: { 'content-type': start.contentType } });
+}

package/clis/iwhalecloud/client.js

@@ -0,0 +1,97 @@
+import { Strategy } from '@sovovs/bycli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError, TimeoutError } from '@sovovs/bycli/errors';
+
+export const HOST = 'mail.iwhalecloud.com';
+export const BASE = `https://${HOST}`;
+export const metadata = { site: 'iwhalecloud', domain: HOST, access: 'read', strategy: Strategy.COOKIE,
+  browser: true, navigateBefore: false, siteSession: 'persistent' };
+export const idArg = { name: 'emailId', positional: true, required: true, help: 'list 返回的 emailId（请加引号）' };
+export const SORT_FIELDS = Object.freeze({ date: 'DateTimeReceived', from: 'From', to: 'DisplayTo',
+  subject: 'Subject', attachments: 'HasAttachments', importance: 'Importance', size: 'Size',
+  sent: 'DateTimeSent', created: 'DateTimeCreated' });
+const FOLDERS = Object.freeze({ inbox: 'inbox', sent: 'sentitems', drafts: 'drafts', trash: 'deleteditems', spam: 'junkemail' });
+export function integer(value, name, min, max) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < min || n > max) throw new ArgumentError(`${name} must be an integer between ${min} and ${max}`);
+  return n;
+}
+export function requiredId(value) {
+  const id = String(value ?? '').trim();
+  if (!id) throw new ArgumentError('emailId is required; use an emailId returned by list');
+  return id;
+}
+export function folderId(args) {
+  if (args['folder-id']) return { __type: 'FolderId:#Exchange', Id: String(args['folder-id']) };
+  const key = String(args.folder ?? 'inbox');
+  if (!Object.hasOwn(FOLDERS, key)) throw new ArgumentError(`Unknown folder; choose ${Object.keys(FOLDERS).join(', ')} or --folder-id`);
+  return { __type: 'DistinguishedFolderId:#Exchange', Id: FOLDERS[key] };
+}
+export async function connect(page) {
+  await page.goto(`${BASE}/owa/`, { waitUntil: 'load' });
+}
+
+// Keep the session token inside the browser; never include it in CLI output or errors.
+export async function request(page, action, body) {
+  const result = await page.evaluate(async (actionName, requestBody) => {
+    if (location.origin !== 'https://mail.iwhalecloud.com' || /\/auth\//i.test(location.pathname)) return { auth: true };
+    const cookie = document.cookie.split(';').map(x => x.trim()).find(x => x.startsWith('X-OWA-CANARY='));
+    if (!cookie) return { auth: true };
+    try {
+      const response = await fetch(`/owa/service.svc?action=${actionName}`, {
+        method: 'POST', credentials: 'same-origin', redirect: 'error', signal: AbortSignal.timeout(30000),
+        headers: { 'Content-Type': 'application/json; charset=utf-8', Action: actionName,
+          'X-OWA-CANARY': decodeURIComponent(cookie.slice('X-OWA-CANARY='.length)) },
+        body: JSON.stringify({ __type: `${actionName}JsonRequest:#Exchange`,
+          Header: { __type: 'JsonRequestHeaders:#Exchange', RequestServerVersion: 'Exchange2013' }, Body: requestBody }),
+      });
+      if ([401, 403, 440].includes(response.status)) return { auth: true };
+      if (!response.ok) return { status: response.status };
+      const text = await response.text();
+      if (/^\s*</.test(text)) return { auth: true };
+      try { return { data: JSON.parse(text) }; } catch { return { malformed: true }; }
+    } catch (error) {
+      return { timeout: error.name === 'TimeoutError' || error.name === 'AbortError', failed: true };
+    }
+  }, action, body);
+  if (result?.auth) throw new AuthRequiredError(HOST);
+  if (result?.timeout) throw new TimeoutError(`iwhalecloud ${action}`, 30);
+  if (!result?.data) throw new CommandExecutionError(`iwhalecloud ${action} request failed${result?.status ? ` (HTTP ${result.status})` : ''}`);
+  const messages = result.data.Body?.ResponseMessages?.Items;
+  if (!Array.isArray(messages) || !messages.length) throw new CommandExecutionError(`iwhalecloud ${action}: invalid response envelope`);
+  for (const message of messages) {
+    if (message.ResponseClass !== 'Success' || message.ResponseCode !== 'NoError') {
+      const code = String(message.ResponseCode ?? 'UnknownError');
+      if (['ErrorInvalidClientAccessToken', 'ErrorInvalidUserSid'].includes(code)) throw new AuthRequiredError(HOST);
+      if (code === 'ErrorItemNotFound') throw new EmptyResultError(`iwhalecloud ${action}`, 'The mail may have been moved or deleted; refresh list');
+      throw new CommandExecutionError(`iwhalecloud ${action}: ${code}`);
+    }
+  }
+  return messages[0];
+}
+
+export function mailRow(item) {
+  if (!item?.ItemId?.Id) throw new CommandExecutionError('OWA returned an item without an emailId');
+  const sender = item.From?.Mailbox ?? item.Sender?.Mailbox ?? {};
+  return { emailId: item.ItemId.Id, subject: item.Subject ?? '', fromName: sender.Name ?? '', fromEmail: sender.EmailAddress ?? '',
+    toDisplay: item.DisplayTo ?? '', date: item.DateTimeReceived ?? '', times: { sentAt: item.DateTimeSent ?? '', createdAt: item.DateTimeCreated ?? '' },
+    unread: typeof item.IsRead === 'boolean' ? !item.IsRead : null, hasAttachments: item.HasAttachments ?? false,
+    importance: item.Importance ?? '', size: item.Size ?? 0,
+    url: `${BASE}/owa/#path=/mail/item/${encodeURIComponent(item.ItemId.Id)}` };
+}
+export const listColumns = ['emailId', 'subject', 'fromName', 'fromEmail', 'toDisplay', 'date', 'times', 'unread', 'hasAttachments', 'importance', 'size', 'url'];
+
+export async function getMail(page, emailId, bodyType = 'text') {
+  const message = await request(page, 'GetItem', { __type: 'GetItemRequest:#Exchange', ShapeName: 'ItemPart',
+    ItemShape: { __type: 'ItemResponseShape:#Exchange', BaseShape: 'AllProperties', BodyType: bodyType === 'html' ? 'HTML' : 'Text',
+      MaximumBodySize: 0, MaximumRecipientsToReturn: 10000 }, ItemIds: [{ __type: 'ItemId:#Exchange', Id: emailId }] });
+  if (!Array.isArray(message.Items) || message.Items.length !== 1 || message.Items[0]?.ItemId?.Id !== emailId) {
+    throw new CommandExecutionError('OWA GetItem did not return the requested mail');
+  }
+  return message.Items[0];
+}
+export function attachmentsOf(item) {
+  if (item.Attachments != null && !Array.isArray(item.Attachments)) throw new CommandExecutionError('OWA returned invalid attachments');
+  return (item.Attachments ?? []).map((a, index) => ({ index: index + 1, attachmentId: a.AttachmentId?.Id ?? '',
+    name: a.Name ?? '', contentType: a.ContentType ?? '', size: a.Size ?? 0, inline: a.IsInline ?? false,
+    kind: a.__type?.split(':')[0] ?? 'Unknown' }));
+}

package/clis/iwhalecloud/download.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { cli } from '@sovovs/bycli/registry';
+import { ArgumentError, AuthRequiredError, CliError, CommandExecutionError, EmptyResultError, TimeoutError } from '@sovovs/bycli/errors';
+import { metadata, idArg, requiredId, connect, getMail, attachmentsOf, BASE, HOST } from './client.js';
+import { browserDownloadResponse } from './browser-download.js';
+
+function safeName(name) {
+  const leaf = String(name).replaceAll('\\', '/').split('/').pop() ?? '';
+  const clean = leaf.replace(/[<>:"/\\|?*\x00-\x1f\x7f]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
+  // Keep UTF-8 filenames below filesystem byte limits, preserving the extension.
+  const ext = path.extname(clean).slice(0, 20);
+  let stem = clean.slice(0, clean.length - ext.length) || 'attachment';
+  while (Buffer.byteLength(stem + ext) > 220) stem = Array.from(stem).slice(0, -1).join('');
+  return stem + ext;
+}
+async function reserveFile(directory, name) {
+  const ext = path.extname(name); const stem = name.slice(0, name.length - ext.length);
+  for (let index = 0; index < 10000; index++) {
+    const file = path.join(directory, index ? `${stem} (${index})${ext}` : name);
+    try { return { file, handle: await fs.open(file, 'wx', 0o600) }; }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  throw new CommandExecutionError('Too many files with the same attachment name');
+}
+
+export async function runDownload(page, args, deps = {}) {
+  const id = requiredId(args.emailId);
+  const output = path.resolve(String(args.output ?? '.'));
+  await connect(page);
+  const item = await getMail(page, id);
+  const attachments = attachmentsOf(item);
+  const selector = String(args.attachment ?? 'all');
+  const selected = selector === 'all' ? attachments.filter(a => !a.inline)
+    : attachments.filter(a => a.attachmentId === selector || String(a.index) === selector);
+  if (!selected.length) throw new EmptyResultError('iwhalecloud download', 'No matching attachments; use read to inspect attachment IDs and indexes');
+  if (selected.length > 1 && selector !== 'all') throw new ArgumentError('Attachment selector is ambiguous; use the attachment ID');
+  if (selected.some(a => !a.attachmentId || a.kind !== 'FileAttachment')) {
+    throw new CommandExecutionError('Only file attachments can be downloaded; select a FileAttachment ID shown by read');
+  }
+  try { await fs.mkdir(output, { recursive: true }); }
+  catch { throw new CommandExecutionError('Cannot create attachment output directory', 'Choose a writable directory with --output'); }
+  const rows = [];
+  for (const attachment of selected) {
+    let reserved;
+    let response;
+    try {
+      response = deps.fetch
+        ? await deps.fetch(`${BASE}/owa/service.svc/s/GetFileAttachment?id=${encodeURIComponent(attachment.attachmentId)}`)
+        : await browserDownloadResponse(page, attachment.attachmentId);
+      if ([301, 302, 303, 307, 308, 401, 403, 440].includes(response.status)) throw new AuthRequiredError(HOST);
+      if (!response.ok || !response.body) throw new CommandExecutionError(`Attachment download failed (HTTP ${response.status})`);
+      const contentType = response.headers.get('content-type') ?? '';
+      if (contentType.includes('text/html') && !attachment.contentType.includes('text/html')) throw new AuthRequiredError(HOST);
+      reserved = await reserveFile(output, safeName(attachment.name));
+      await pipeline(Readable.fromWeb(response.body), reserved.handle.createWriteStream());
+      const stat = await fs.stat(reserved.file);
+      rows.push({ emailId: id, attachmentId: attachment.attachmentId, name: attachment.name,
+        path: reserved.file, size: stat.size, contentType: attachment.contentType });
+    } catch (error) {
+      if (reserved) { await reserved.handle.close().catch(() => {}); await fs.unlink(reserved.file).catch(() => {}); }
+      if (response?.body && !response.body.locked) await response.body.cancel().catch(() => {});
+      const saved = rows.length ? `; ${rows.length} earlier attachment(s) were saved in ${output}` : '';
+      if (error instanceof CliError) { error.message += saved; throw error; }
+      if (error.name === 'TimeoutError' || error.name === 'AbortError') throw new TimeoutError(`Attachment download${saved}`, 120);
+      throw new CommandExecutionError(`Attachment download failed${saved}`, 'Check connectivity and retry; existing files will not be overwritten');
+    }
+  }
+  return rows;
+}
+cli({ ...metadata, name: 'download', description: '下载浩鲸邮件附件到本地目录，同名文件自动编号',
+  example: 'bycli iwhalecloud download "<emailId>" --attachment all --output ./mail-downloads -f yaml',
+  args: [idArg, { name: 'attachment', default: 'all', help: 'all（不含内嵌图片）、附件 ID 或 read 中的序号（从 1 开始）' },
+    { name: 'output', default: '.', help: '本地输出目录' }],
+  columns: ['emailId', 'attachmentId', 'name', 'path', 'size', 'contentType'], func: runDownload });

package/clis/iwhalecloud/list.js

@@ -0,0 +1,59 @@
+import { cli } from '@sovovs/bycli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@sovovs/bycli/errors';
+import { metadata, SORT_FIELDS, integer, folderId, connect, request, mailRow, listColumns } from './client.js';
+
+export async function runList(page, args) {
+  const limit = integer(args.limit ?? 20, 'limit', 1, 10000);
+  let offset = integer(args.offset ?? 0, 'offset', 0, 2147483647);
+  const sort = String(args.sort ?? 'default');
+  const order = String(args.order ?? 'default');
+  if (sort !== 'default' && !Object.hasOwn(SORT_FIELDS, sort)) throw new ArgumentError(`Unknown sort: ${sort}`);
+  if (!['default', 'asc', 'desc'].includes(order)) throw new ArgumentError('order must be default, asc or desc');
+  if (sort === 'default' && order !== 'default') throw new ArgumentError('Specify --sort to use --order; default preserves server ordering');
+  const folder = folderId(args);
+  await connect(page);
+  const rows = [];
+  const seen = new Set();
+  while (rows.length < limit) {
+    // Split the validated total into server pages; do not cap the caller's total.
+    const remaining = limit - rows.length;
+    const batchSize = remaining > 100 ? 100 : remaining;
+    const body = { __type: 'FindItemRequest:#Exchange',
+      ItemShape: { __type: 'ItemResponseShape:#Exchange', BaseShape: 'AllProperties' },
+      ParentFolderIds: [folder], Traversal: 'Shallow',
+      Paging: { __type: 'IndexedPageView:#Exchange', BasePoint: 'Beginning', Offset: offset, MaxEntriesReturned: batchSize } };
+    if (sort !== 'default') {
+      const ascending = order === 'asc' || (order === 'default' && ['from', 'to', 'subject'].includes(sort));
+      body.SortOrder = [{ __type: 'SortResults:#Exchange', Order: ascending ? 'Ascending' : 'Descending',
+        Path: { __type: 'PropertyUri:#Exchange', FieldURI: SORT_FIELDS[sort] } }];
+      if (sort !== 'date') body.SortOrder.push({ __type: 'SortResults:#Exchange', Order: 'Descending',
+        Path: { __type: 'PropertyUri:#Exchange', FieldURI: 'DateTimeReceived' } });
+    }
+    const message = await request(page, 'FindItem', body);
+    const root = message.RootFolder;
+    if (!root || !Array.isArray(root.Items)) throw new CommandExecutionError('OWA FindItem returned invalid items');
+    for (const item of root.Items) {
+      const row = mailRow(item);
+      if (seen.has(row.emailId)) throw new CommandExecutionError('Mailbox changed while paging; repeat list to avoid incomplete results');
+      seen.add(row.emailId); rows.push(row);
+      if (rows.length === limit) break;
+    }
+    if (root.IncludesLastItemInRange === true || rows.length >= limit) break;
+    const next = root.IndexedPagingOffset;
+    if (!root.Items.length || !Number.isSafeInteger(next) || next <= offset) throw new CommandExecutionError('OWA pagination did not advance');
+    offset = next;
+  }
+  if (!rows.length) throw new EmptyResultError('iwhalecloud list', 'No mail at this folder/offset');
+  return rows;
+}
+
+cli({ ...metadata, name: 'list', description: '浩鲸邮箱邮件列表：服务端分页、默认排序及 9 种字段排序',
+  example: 'bycli iwhalecloud list --sort date --order desc --limit 50 -f yaml',
+  args: [
+    { name: 'folder', default: 'inbox', choices: ['inbox', 'sent', 'drafts', 'trash', 'spam'], help: '邮件文件夹' },
+    { name: 'folder-id', help: '自定义文件夹的 OWA FolderId，优先于 --folder' },
+    { name: 'limit', type: 'int', default: 20, help: '返回数量，1–10000；自动分页' },
+    { name: 'offset', type: 'int', default: 0, help: '服务端起始偏移，0 表示第一封' },
+    { name: 'sort', default: 'default', choices: ['default', ...Object.keys(SORT_FIELDS)], help: 'default 保留服务端默认顺序' },
+    { name: 'order', default: 'default', choices: ['default', 'asc', 'desc'], help: '默认：姓名/主题升序，其余降序；显式方向须指定 --sort' },
+  ], columns: listColumns, func: runList });

package/clis/iwhalecloud/read.js

@@ -0,0 +1,25 @@
+import { cli } from '@sovovs/bycli/registry';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { metadata, idArg, requiredId, connect, getMail, mailRow, listColumns, attachmentsOf } from './client.js';
+
+export async function runRead(page, args) {
+  const id = requiredId(args.emailId);
+  const bodyType = String(args['body-type'] ?? 'text');
+  if (!['text', 'html'].includes(bodyType)) throw new ArgumentError('body-type must be text or html');
+  await connect(page);
+  const item = await getMail(page, id, bodyType);
+  if (typeof item.Body?.Value !== 'string' || item.Body.IsTruncated === true) {
+    throw new CommandExecutionError('OWA did not return a complete mail body', 'Open the mail in Outlook to check content restrictions');
+  }
+  const recipients = entries => (entries ?? []).map(entry => {
+    const mailbox = entry.Mailbox ?? entry;
+    return { name: mailbox.Name ?? '', email: mailbox.EmailAddress ?? '' };
+  });
+  return [{ ...mailRow(item), to: recipients(item.ToRecipients), cc: recipients(item.CcRecipients), bcc: recipients(item.BccRecipients),
+    recipientCounts: item.RecipientCounts ?? {}, bodyType: item.Body?.BodyType ?? bodyType, body: item.Body?.Value ?? '',
+    attachments: attachmentsOf(item) }];
+}
+cli({ ...metadata, name: 'read', description: '读取浩鲸邮件完整正文、收件人和附件列表（不标记已读）',
+  example: 'bycli iwhalecloud read "<emailId>" -f yaml',
+  args: [idArg, { name: 'body-type', default: 'text', choices: ['text', 'html'], help: '正文格式' }],
+  columns: [...listColumns, 'to', 'cc', 'bcc', 'recipientCounts', 'bodyType', 'body', 'attachments'], func: runRead });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.1.60",
+  "version": "2.1.61",
   "publishConfig": {
     "access": "public"
   },

package/scripts/recorder.sh

@@ -1,186 +0,0 @@
-#!/usr/bin/env bash
-# 录制三端管理脚本
-#   daemon : 浏览器底座(19825),由 bycli 管理;扩展连这口
-#   be     : Recorder Local Service(19826),同源托管真实工作台 UI(dashboard/dist)
-#   web    : Umi dev server(8000),mock 模式,仅前端开发用(无真实录制)
-#
-# 用法:
-#   scripts/recorder.sh start   [daemon|be|all]       # 默认=真实录制环境(daemon+be,自动停 mock)
-#   scripts/recorder.sh start   --mock                # 仅此参数才起 mock 前端(web :8000,假数据)
-#   scripts/recorder.sh stop    [daemon|be|web|all]
-#   scripts/recorder.sh restart [daemon|be|vnc|all]   # restart all=daemon+be(不含 mock);改了 .env/dist 后用;vnc=删旧容器换新镜像
-#   scripts/recorder.sh status                        # 看三端
-#   scripts/recorder.sh build   [core|be|ui|ext|all] # 重建 dist(改源码后;all 含扩展,需手动重载)
-#
-# 真实录制(带 LLM)启动:scripts/recorder.sh start   → 打开 http://127.0.0.1:19826/workbench
-#
-# embedded_iframe 录制模式(P2,公开站页内嵌入;**本机默认开**):起 be 默认带 flag——
-#   EMBEDDED=0 scripts/recorder.sh start              # 显式关闭页内嵌入模式
-#   IFRAME_FRAME_SRC=https://juejin.cn scripts/recorder.sh restart be   # 只放该 origin(hardened)
-#   inline env 经 `env VAR=…` 注入,优先级高于 --env-file(.env 不覆盖已存在的 process env)。
-#
-# vnc 录制模式(容器内 Chromium+扩展+daemon,noVNC 投画面;**本机默认开**,需 podman + 镜像):
-#   scripts/recorder.sh build vnc                     # 构建容器镜像 bycli-verify:latest(需先 build ext + npm run build)
-#   scripts/recorder.sh restart vnc                   # 重启镜像:删旧容器(bycli-vnc),be 下次 bind 用新镜像重建(改镜像后用)
-#   VNC=0 scripts/recorder.sh restart be              # 显式关闭 vnc 模式
-#   选 VNC 模式后 be 自动 podman run 起容器、前端 iframe 投 noVNC 画面;录的数据走容器网关→be→合成链。
-set -uo pipefail
-
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-RUN="$ROOT/.recorder-run"; mkdir -p "$RUN"
-DAEMON_PORT=19825; BE_PORT=19826; WEB_PORT=8000
-
-port_pid() { lsof -ti "tcp:$1" -sTCP:LISTEN 2>/dev/null | head -1; }
-alive()    { [ -n "${1:-}" ] && kill -0 "$1" 2>/dev/null; }
-
-# ───────────────────────── daemon(交给 bycli 管) ─────────────────────────
-need_bycli() { command -v bycli >/dev/null || { echo "✗ bycli 不在 PATH(在仓库根 npm link)"; return 1; }; }
-daemon_start()   { need_bycli || return 1; bycli daemon start   2>&1 | tail -1; }
-daemon_stop()    { need_bycli && { bycli daemon stop 2>&1 | tail -1; } || true; }
-daemon_restart() { need_bycli || return 1; bycli daemon restart 2>&1 | tail -1; }
-daemon_status()  { local p; p="$(port_pid $DAEMON_PORT)"; [ -n "$p" ] && echo "● daemon  RUNNING  :$DAEMON_PORT  pid=$p" || echo "○ daemon  stopped  :$DAEMON_PORT"; }
-
-# ───────────────────────── vnc(podman 容器,be 自动编排) ────────────────
-# 容器名与 vncOrchestrator.ts 保持一致(BYCLI_VNC_CONTAINER 覆盖,默认 bycli-vnc)。
-VNC_CONTAINER="${BYCLI_VNC_CONTAINER:-bycli-vnc}"
-VNC_IMAGE="${BYCLI_VNC_IMAGE:-bycli-verify:latest}"
-need_podman() { command -v podman >/dev/null || { echo "✗ podman 不在 PATH(VNC 模式需 podman)"; return 1; }; }
-# 重启镜像:删旧容器,be 下次 bind 时用当前镜像重建(build vnc 换镜像后调用)。
-vnc_restart() {
-  need_podman || return 1
-  [ -n "$(podman images -q "$VNC_IMAGE" 2>/dev/null)" ] || { echo "✗ 镜像 $VNC_IMAGE 不存在 → scripts/recorder.sh build vnc"; return 1; }
-  if [ -n "$(podman ps -aq -f "name=^${VNC_CONTAINER}$" 2>/dev/null)" ]; then
-    podman rm -f "$VNC_CONTAINER" >/dev/null 2>&1 && echo "✓ 已删旧容器 $VNC_CONTAINER(be 下次 bind 用新镜像 $VNC_IMAGE 重建)"
-  else
-    echo "○ 容器 $VNC_CONTAINER 未运行(be 下次 bind 会用新镜像 $VNC_IMAGE 新建)"
-  fi
-}
-vnc_stop() {
-  need_podman || return 1
-  if [ -n "$(podman ps -aq -f "name=^${VNC_CONTAINER}$" 2>/dev/null)" ]; then
-    podman rm -f "$VNC_CONTAINER" >/dev/null 2>&1 && echo "✓ vnc 容器 $VNC_CONTAINER 已删"
-  else echo "○ vnc 容器未运行"; fi
-}
-vnc_status() {
-  command -v podman >/dev/null || { echo "○ vnc     (podman 未装)"; return; }
-  local st; st="$(podman inspect "$VNC_CONTAINER" --format '{{.State.Status}}' 2>/dev/null)"
-  [ -n "$st" ] && echo "● vnc     $st  container=$VNC_CONTAINER  image=$VNC_IMAGE" || echo "○ vnc     no container  ($VNC_CONTAINER)"
-}
-
-# ───────────────────────── be(node 进程,PID 文件) ──────────────────────
-be_start() {
-  [ -f "$ROOT/dashboard-be/dist/server.js" ] || { echo "✗ be 未构建 → scripts/recorder.sh build be"; return 1; }
-  [ -f "$ROOT/dashboard-be/.env" ]           || { echo "✗ 缺 dashboard-be/.env → cp dashboard-be/.env.example dashboard-be/.env 并填值"; return 1; }
-  [ -d "$ROOT/dashboard/dist" ]              || echo "⚠ dashboard/dist 不存在,be 将 API-only(无 UI)→ scripts/recorder.sh build ui"
-  if [ -n "$(port_pid $BE_PORT)" ]; then echo "● be 已在 :$BE_PORT(先 stop/restart)"; return 0; fi
-  # embedded_iframe 模式(P2):EMBEDDED=1 → 注入 flag 开 frame-src + 前端模式选项。
-  # 经 `env VAR=…` 内联注入,优先级高于 --env-file(.env 不覆盖已存在的 process env)。
-  # 三种录制模式默认全开(本机录制工作台);显式 EMBEDDED=0 / VNC=0 可单独关。
-  # 注:只在本机 be 启动注入,不动 recorder-core 的 fail-closed 发布默认(全局 CSP 安全底线不变)。
-  local envv=()
-  if [ "${EMBEDDED:-1}" = 1 ]; then
-    envv+=(FEATURE_EMBEDDED_IFRAME_RECORDING=1)
-    [ -n "${IFRAME_FRAME_SRC:-}" ] && envv+=("RECORDER_IFRAME_FRAME_SRC=$IFRAME_FRAME_SRC")
-    echo "  ⚙ embedded_iframe 模式 ON${IFRAME_FRAME_SRC:+(frame-src=$IFRAME_FRAME_SRC)}"
-  fi
-  if [ "${VNC:-1}" = 1 ]; then
-    envv+=(FEATURE_VNC_RECORDING=1)
-    echo "  ⚙ vnc 容器模式 ON(be 自动 podman run bycli-verify:latest;需先 build vnc)"
-  fi
-  ( cd "$ROOT" && nohup env ${envv[@]+"${envv[@]}"} node --env-file=dashboard-be/.env dashboard-be/dist/server.js >"$RUN/be.log" 2>&1 & echo $! >"$RUN/be.pid" )
-  sleep 1; be_status; echo "  日志: $RUN/be.log"
-}
-be_stop() {
-  # 端口权威:pid 文件 + 实际占 19826 的进程都杀(防重复实例残留)
-  local stopped=0 pf; pf="$(cat "$RUN/be.pid" 2>/dev/null)"
-  for pid in "$pf" "$(port_pid $BE_PORT)"; do
-    if alive "$pid"; then kill "$pid" 2>/dev/null; echo "✓ be 已停(pid=$pid)"; stopped=1; fi
-  done
-  [ "$stopped" = 0 ] && echo "○ be 未运行"
-  rm -f "$RUN/be.pid"
-}
-be_restart() { be_stop; sleep 1; be_start; }
-be_status()  { local p; p="$(port_pid $BE_PORT)"; [ -n "$p" ] && echo "● be      RUNNING  http://127.0.0.1:$BE_PORT/workbench  pid=$p" || echo "○ be      stopped  :$BE_PORT"; }
-
-# ───────────────────────── web(Umi dev,mock) ───────────────────────────
-web_start() {
-  if [ -n "$(port_pid $WEB_PORT)" ]; then echo "● web 已在 :$WEB_PORT"; return 0; fi
-  ( cd "$ROOT/dashboard" && nohup npm run dev >"$RUN/web.log" 2>&1 & echo $! >"$RUN/web.pid" )
-  echo "✓ web 启动中(mock,http://127.0.0.1:$WEB_PORT)  日志: $RUN/web.log"
-}
-web_stop() {
-  local pid; pid="$(cat "$RUN/web.pid" 2>/dev/null)"; [ -z "$pid" ] && pid="$(port_pid $WEB_PORT)"
-  if alive "$pid"; then pkill -P "$pid" 2>/dev/null; kill "$pid" 2>/dev/null; echo "✓ web 已停"; else echo "○ web 未运行"; fi
-  rm -f "$RUN/web.pid"
-}
-web_restart() { web_stop; sleep 1; web_start; }
-web_status()  { local p; p="$(port_pid $WEB_PORT)"; [ -n "$p" ] && echo "● web     RUNNING  http://127.0.0.1:$WEB_PORT (mock)  pid=$p" || echo "○ web     stopped  :$WEB_PORT (mock dev)"; }
-
-# ───────────────────────── build ────────────────────────────────────────
-do_build() {
-  case "${1:-all}" in
-    core) npm --prefix "$ROOT/packages/recorder-core" run build ;;
-    be)   npm --prefix "$ROOT/dashboard-be" run build ;;
-    ui)   ( cd "$ROOT/dashboard" && npm run build ) ;;
-    ext)  ( cd "$ROOT/extension" && npm run build ) ;;
-    vnc)  # VNC 录制模式容器镜像(Chromium+扩展+daemon+x11vnc+websockify+网关);be 起容器时复用 bycli-verify:latest。
-          command -v podman >/dev/null || { echo "✗ podman 不在 PATH(VNC 模式需 podman)"; return 1; }
-          [ -f "$ROOT/extension/dist/background.js" ] || { echo "✗ 扩展未构建 → scripts/recorder.sh build ext"; return 1; }
-          [ -f "$ROOT/dist/src/daemon.js" ]            || { echo "✗ dist 未构建 → npm run build"; return 1; }
-          echo "▶ 构建 VNC 容器镜像 bycli-verify:latest(首次装 chromium 较慢)…"
-          ( cd "$ROOT" && podman build -f podman-verify/Dockerfile -t bycli-verify:latest . ) ;;
-    all)  npm --prefix "$ROOT/packages/recorder-core" run build \
-            && npm --prefix "$ROOT/dashboard-be" run build \
-            && ( cd "$ROOT/dashboard" && npm run build ) \
-            && ( cd "$ROOT/extension" && npm run build ) \
-            && echo "↻ 扩展已重建 → chrome://extensions 重载 byCLI(确认版本号刷新)" ;;
-    *) echo "build: core|be|ui|ext|vnc|all"; return 1 ;;
-  esac
-}
-
-# ───────────────────────── dispatch ─────────────────────────────────────
-action="${1:-}"; shift || true
-case "$action" in
-  start)
-    # mock 仅在显式 --mock 时启动;其余参数视作服务名
-    mock=0; svcs=()
-    for a in "$@"; do if [ "$a" = "--mock" ]; then mock=1; else svcs+=("$a"); fi; done
-    if [ "$mock" = 1 ]; then
-      echo "▶ 启动【mock 前端】(web :$WEB_PORT,假数据,无真实录制)"
-      web_start
-    elif [ ${#svcs[@]} -eq 0 ]; then
-      # 默认 = 真实录制环境:停掉 mock web(防 :8000 误测)→ 起 daemon + be
-      echo "▶ 启动【真实录制环境】(daemon + be);mock web 若在跑将被停掉以免混淆"
-      [ -n "$(port_pid $WEB_PORT)" ] && web_stop
-      daemon_start; be_start
-      echo; echo "✅ 真实录制 → http://127.0.0.1:$BE_PORT/workbench(mock 需 start --mock)"
-    else
-      [ "${svcs[0]}" = "all" ] && svcs=(daemon be)
-      for t in "${svcs[@]}"; do
-        case "$t" in
-          daemon|be) "${t}_start" ;;
-          web) echo "✗ web 是 mock,请用:scripts/recorder.sh start --mock" ;;
-          *) echo "未知服务: $t(daemon|be|all,mock 用 --mock)" ;;
-        esac
-      done
-    fi ;;
-  stop|restart)
-    # all 语义:restart 只起真实环境(daemon+be,不复活 mock,与 start 默认一致);
-    #          stop 则全停(含 mock web,teardown)。mock 启停一律显式 web/--mock。
-    if [ $# -eq 0 ]; then targets=(daemon be)
-    elif [ "${1:-}" = all ]; then
-      [ "$action" = stop ] && targets=(daemon be web) || targets=(daemon be)
-    else targets=("$@"); fi
-    [ "$action" = stop ] && targets=($(printf '%s\n' "${targets[@]}" | tail -r 2>/dev/null || printf '%s\n' "${targets[@]}"))
-    for t in "${targets[@]}"; do
-      case "$t" in daemon|be|web|vnc) "${t}_${action}" ;; *) echo "未知服务: $t(daemon|be|web|vnc|all)";; esac
-    done ;;
-  status)
-    daemon_status; be_status; web_status; vnc_status ;;
-  build)
-    do_build "${1:-all}" ;;
-  ""|-h|--help|help)
-    awk 'NR>1 && /^#/{sub(/^# ?/,"");print;next} NR>1{exit}' "${BASH_SOURCE[0]}" ;;
-  *)
-    echo "未知命令: $action(start|stop|restart|status|build)"; exit 1 ;;
-esac