@sovovs/bycli 2.1.60 → 2.1.62

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",
@@ -34190,6 +34388,130 @@
     "sourceFile": "zhihu/answer-detail.js",
     "navigateBefore": "https://www.zhihu.com"
   },
+  {
+    "site": "zhihu",
+    "name": "answer-waiting-draft",
+    "description": "保存知乎回答草稿（新回答或已有回答的编辑草稿，不发布）",
+    "access": "write",
+    "domain": "www.zhihu.com",
+    "strategy": "cookie",
+    "browser": "conditional",
+    "args": [
+      {
+        "name": "target",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Question ID, question/own-answer URL, question:<id>, or answer:<questionId>:<answerId>"
+      },
+      {
+        "name": "text",
+        "type": "str",
+        "required": false,
+        "positional": true,
+        "help": "Plain-text answer body; use either text or --file"
+      },
+      {
+        "name": "file",
+        "type": "str",
+        "required": false,
+        "help": "UTF-8 text file containing the answer body"
+      },
+      {
+        "name": "mode",
+        "type": "str",
+        "default": "auto",
+        "required": false,
+        "help": "auto detects new/edit; new refuses an existing answer; edit requires your existing answer",
+        "choices": [
+          "auto",
+          "new",
+          "edit"
+        ]
+      },
+      {
+        "name": "existing",
+        "type": "str",
+        "default": "error",
+        "required": false,
+        "help": "Policy when the editor already has content; identical text is left unchanged",
+        "choices": [
+          "error",
+          "replace",
+          "append",
+          "prepend"
+        ]
+      },
+      {
+        "name": "separator",
+        "type": "str",
+        "default": "\n\n",
+        "required": false,
+        "help": "Literal separator for append/prepend (default: a blank line)"
+      },
+      {
+        "name": "prefix",
+        "type": "str",
+        "required": false,
+        "help": "Literal text before the supplied body (include any desired newline)"
+      },
+      {
+        "name": "suffix",
+        "type": "str",
+        "required": false,
+        "help": "Literal text after the supplied body (include any desired newline)"
+      },
+      {
+        "name": "expected-title",
+        "type": "str",
+        "required": false,
+        "help": "Require an exact question title before editing"
+      },
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 30,
+        "required": false,
+        "help": "Total editor/save verification wait budget in seconds (1–120)"
+      },
+      {
+        "name": "close-editor",
+        "type": "boolean",
+        "default": true,
+        "required": false,
+        "help": "Close editor after verified save; false leaves it open (combine with --keep-tab true)"
+      },
+      {
+        "name": "dry-run",
+        "type": "boolean",
+        "required": false,
+        "help": "Preview resolved input locally without opening or modifying the editor"
+      },
+      {
+        "name": "execute",
+        "type": "boolean",
+        "required": false,
+        "help": "Actually save the draft; never publishes an answer"
+      }
+    ],
+    "columns": [
+      "status",
+      "outcome",
+      "question_id",
+      "answer_id",
+      "mode",
+      "url",
+      "characters",
+      "verified",
+      "published",
+      "editor_open",
+      "message"
+    ],
+    "type": "js",
+    "modulePath": "zhihu/answer-waiting-draft.js",
+    "sourceFile": "zhihu/answer-waiting-draft.js",
+    "navigateBefore": false
+  },
   {
     "site": "zhihu",
     "name": "collection",
@@ -34631,6 +34953,50 @@
     "sourceFile": "zhihu/search.js",
     "navigateBefore": "https://www.zhihu.com"
   },
+  {
+    "site": "zhihu",
+    "name": "waiting",
+    "description": "知乎写回答（等你来答）问题列表",
+    "access": "read",
+    "domain": "www.zhihu.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "type",
+        "type": "str",
+        "default": "recommend",
+        "required": false,
+        "help": "Question category: recommend 为你推荐, invited 邀请回答, latest 最新问题, hot 人气问题",
+        "choices": [
+          "recommend",
+          "invited",
+          "latest",
+          "hot"
+        ]
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "Maximum questions to return (1–1000; stops when the page stops loading)"
+      }
+    ],
+    "columns": [
+      "rank",
+      "id",
+      "title",
+      "views",
+      "answers",
+      "followers",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "zhihu/waiting.js",
+    "sourceFile": "zhihu/waiting.js",
+    "navigateBefore": "https://www.zhihu.com"
+  },
   {
     "site": "zlibrary",
     "name": "info",

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 });