engine7 7.1.120 → 7.1.121

package/templates/skills/email/scripts/imap.js

@@ -0,0 +1,540 @@
+#!/usr/bin/env node
+
+/**
+ * IMAP Email CLI — engine7 email skill v2（imapflow）
+ *
+ * v2 改造（设计 docs/superpowers/specs/2026-10-10-installer-email-skill-design.md）：
+ * - --json 统一错误分类：{ok:false, reason:'auth_failed'|'network'|'timeout'|'rate_limited'|'config_missing'|'unknown'}
+ *   「邮箱里没有」是成功（ok:true, reason:'no_new_mail'）——绝不能和连接失败混报（239 事故防线）
+ * - 新命令 list-subjects / list-senders（envelope-only，不拉正文）
+ * - 凭证：stateDir config tools.email 优先，.env 回退（见 email-config.js）
+ * - 连接重试：network/timeout 指数退避 ×3；auth_failed 不重试快败
+ */
+
+const { ImapFlow } = require('imapflow')
+const { simpleParser } = require('mailparser')
+const path = require('path')
+const fs = require('fs')
+const { resolveEmailConfig, classifyError } = require('./email-config.js')
+
+// IMAP ID information for server compatibility (163.com, QQ, etc.)
+const IMAP_ID = {
+  name: 'moltbot',
+  version: '0.0.1',
+  vendor: 'netease',
+  'support-email': 'kefu@188.com'
+}
+
+const DEFAULT_MAILBOX = process.env.IMAP_MAILBOX || 'INBOX'
+const RETRYABLE = new Set(['network', 'timeout'])
+
+// Parse command-line arguments
+function parseArgs() {
+  const args = process.argv.slice(2)
+  const command = args[0]
+  const options = {}
+  const positional = []
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const value = args[i + 1]
+      options[key] = value || true
+      if (value && !value.startsWith('--')) i++
+    } else {
+      positional.push(arg)
+    }
+  }
+
+  return { command, options, positional }
+}
+
+// Create imapflow connection config（凭证来自 email-config：config 块优先，.env 回退）
+function createImapConfig() {
+  const cfg = resolveEmailConfig()
+  if (!cfg) {
+    const err = new Error('缺少邮件配置：先在 stateDir config 配 tools.email，或提供 .env')
+    err.reason = 'config_missing'
+    throw err
+  }
+  return {
+    host: cfg.imap.host,
+    port: cfg.imap.port,
+    secure: true,
+    auth: { user: cfg.imap.user, pass: cfg.imap.pass },
+    enableUTF8Accept: true,
+    connectionTimeout: 10000,
+    authTimeout: 10000,
+    tls: { rejectUnauthorized: process.env.IMAP_REJECT_UNAUTHORIZED !== 'false' },
+    id: IMAP_ID,
+    logger: false,
+  }
+}
+
+// Connect to IMAP server（network/timeout 指数退避重试 ×3；auth/配置错误快败）
+async function connect() {
+  const config = createImapConfig()
+  let lastErr
+  for (let attempt = 0; attempt <= 3; attempt++) {
+    const client = new ImapFlow(config)
+    try {
+      await client.connect()
+      return client
+    } catch (err) {
+      lastErr = err
+      const reason = err.reason || classifyError(err)
+      if (!RETRYABLE.has(reason)) throw err
+      if (attempt < 3) {
+        const delay = 1000 * Math.pow(2, attempt)
+        console.error(`[imap] connect ${reason}, retry ${attempt + 1}/3 in ${delay}ms`)
+        await new Promise(r => setTimeout(r, delay))
+      }
+    }
+  }
+  throw lastErr
+}
+
+// Open mailbox (folder)
+async function openMailbox(client, mailbox, readOnly = true) {
+  return await client.getMailboxLock(mailbox, { readOnly })
+}
+
+// Parse email from raw source or structured data
+async function parseEmail(source, includeAttachments = false) {
+  const parsed = await simpleParser(source)
+
+  return {
+    from: parsed.from?.text || 'Unknown',
+    to: parsed.to?.text,
+    subject: parsed.subject || '(no subject)',
+    date: parsed.date,
+    text: parsed.text,
+    html: parsed.html,
+    snippet: parsed.text
+      ? parsed.text.slice(0, 200)
+      : (parsed.html ? parsed.html.slice(0, 200).replace(/<[^>]*>/g, '') : ''),
+    attachments: parsed.attachments?.map((a) => ({
+      filename: a.filename,
+      contentType: a.contentType,
+      size: a.size,
+      content: includeAttachments ? a.content : undefined,
+      cid: a.cid,
+    })),
+  }
+}
+
+// Build search criteria for imapflow (SearchObject format)
+function buildSearchCriteria(options) {
+  const criteria = {}
+
+  if (options.unseen) criteria.seen = false
+  if (options.seen) criteria.seen = true
+  if (options.flagged) criteria.flagged = true
+  if (options.answered) criteria.answered = true
+
+  if (options.from) criteria.from = options.from
+  if (options.subject) criteria.subject = options.subject
+  if (options.to) criteria.to = options.to
+
+  if (options.recent) {
+    criteria.since = parseRelativeTime(options.recent)
+  } else {
+    if (options.since) criteria.since = formatImapDate(new Date(options.since))
+    if (options.before) criteria.before = formatImapDate(new Date(options.before))
+  }
+
+  if (options.uid) criteria.uid = options.uid
+
+  if (Object.keys(criteria).length === 0) return { all: true }
+  return criteria
+}
+
+// Fetch and parse messages from UIDs
+// ⚠️ 1010 冒烟实测：QQ 大邮箱 INBOX 上万封，all-search 返回全量 UID——不截断就逐封拉全文
+// （每封 fetchOne source=true），表现为「挂死」。UID 升序 ⇒ slice(-limit) = 最新 N 封，
+// 先截再拉（妹妹验收 P1「check --recent 会拉正文，大邮箱几百封就卡死」的活体版，这邮箱 10721 封）。
+async function fetchAndParseMessages(client, uids, limit = 25) {
+  const results = []
+  const toFetch = uids.slice(-Math.max(1, limit))
+
+  for (const uid of toFetch) {
+    try {
+      const message = await client.fetchOne(uid, {
+        source: true,
+        envelope: true,
+        flags: true,
+        uid: true,
+      }, { uid: true })
+
+      if (!message || !message.source) continue
+
+      const parsed = await parseEmail(message.source)
+
+      results.push({
+        uid: message.uid,
+        seq: message.seq,
+        flags: message.flags,
+        ...parsed,
+      })
+    } catch (err) {
+      console.warn(`Failed to fetch UID ${uid}: ${err.message}`)
+    }
+  }
+  results.sort((a, b) => new Date(b.date) - new Date(a.date))
+  return results.slice(0, limit)
+}
+
+// === envelope-only 快路径（不下载正文；list-subjects/list-senders 的基础） ===
+async function fetchEnvelopes(client, uids, limit = 50) {
+  const out = []
+  const capped = uids.slice(-Math.max(limit, 1) * 5) // 从最新往回取的范围保护
+  for await (const message of client.fetch(capped.join(','), { envelope: true, uid: true }, { uid: true })) {
+    out.push({
+      uid: message.uid,
+      from: message.envelope?.from?.[0]?.address || message.envelope?.from?.[0]?.name || '',
+      fromName: message.envelope?.from?.[0]?.name || '',
+      subject: message.envelope?.subject || '(no subject)',
+      date: message.envelope?.date || null,
+    })
+  }
+  out.sort((a, b) => new Date(b.date) - new Date(a.date))
+  return out.slice(0, limit)
+}
+
+/** 聚合发件人分布（纯函数，可测）：[{from,subject,date}] → [{address,count,lastDate,lastSubject}] */
+function aggregateSenders(envelopes) {
+  const map = new Map()
+  for (const e of envelopes) {
+    if (!e.from) continue
+    const addr = String(e.from).toLowerCase()
+    const cur = map.get(addr) || { address: addr, count: 0, lastDate: null, lastSubject: '' }
+    cur.count++
+    if (!cur.lastDate || new Date(e.date) > new Date(cur.lastDate)) {
+      cur.lastDate = e.date
+      cur.lastSubject = e.subject
+    }
+    map.set(addr, cur)
+  }
+  return [...map.values()].sort((a, b) => b.count - a.count || new Date(b.lastDate) - new Date(a.lastDate))
+}
+
+function formatImapDate(date) {
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+  const d = new Date(date)
+  const day = String(d.getUTCDate()).padStart(2, '0')
+  const month = months[d.getUTCMonth()]
+  const year = d.getUTCFullYear()
+  return `${day}-${month}-${year}`
+}
+
+// Parse relative time (e.g., "2h", "30m", "7d") to IMAP date
+function parseRelativeTime(timeStr) {
+  const match = timeStr.match(/^(\d+)(m|h|d)$/)
+  if (!match) {
+    throw new Error('Invalid time format. Use: 30m, 2h, 7d')
+  }
+  const value = parseInt(match[1])
+  const unit = match[2]
+  const now = new Date()
+  let past
+  switch (unit) {
+    case 'm': past = new Date(now.getTime() - value * 60 * 1000); break
+    case 'h': past = new Date(now.getTime() - value * 60 * 60 * 1000); break
+    case 'd': past = new Date(now.getTime() - value * 24 * 60 * 60 * 1000); break
+    default: throw new Error('Unknown time unit')
+  }
+  return formatImapDate(past)
+}
+
+// search UIDs inside an already-opened client（多个命令共用）
+async function searchUids(client, criteria) {
+  const searchResult = await client.search(criteria, { uid: true })
+  return Array.isArray(searchResult) ? searchResult : []
+}
+
+// Check for new/unread emails
+async function checkEmails(mailbox = DEFAULT_MAILBOX, limit = 10, recentTime = null, unreadOnly = false) {
+  const client = await connect()
+  try {
+    const lock = await openMailbox(client, mailbox, true)
+
+    const criteria = {}
+    if (unreadOnly) criteria.seen = false   // 修复：imapflow 键是 seen:false（原写成 unseen:true 被忽略）
+    if (recentTime) criteria.since = parseRelativeTime(recentTime)
+    if (Object.keys(criteria).length === 0) criteria.all = true
+
+    const uids = await searchUids(client, criteria)
+    if (uids.length === 0) return []
+
+    return await fetchAndParseMessages(client, uids, limit)
+  } finally {
+    await client.logout()
+  }
+}
+
+// List subjects only（不下载正文——监控「有没有新邮件」的落地命令）
+async function listSubjects(limit = 20, recentTime = null, mailbox = DEFAULT_MAILBOX) {
+  const client = await connect()
+  try {
+    const lock = await openMailbox(client, mailbox, true)
+    const criteria = {}
+    if (recentTime) criteria.since = parseRelativeTime(recentTime)
+    if (Object.keys(criteria).length === 0) criteria.all = true
+    const uids = await searchUids(client, criteria)
+    if (uids.length === 0) return []
+    return await fetchEnvelopes(client, uids, limit)
+  } finally {
+    await client.logout()
+  }
+}
+
+// List sender distribution（监控选址：先看发件人分布再决定搜什么）
+async function listSenders(limit = 50, recentTime = null, mailbox = DEFAULT_MAILBOX) {
+  const envelopes = await listSubjects(limit, recentTime, mailbox)
+  return aggregateSenders(envelopes)
+}
+
+// Fetch full email by UID
+async function fetchEmail(uid, mailbox = DEFAULT_MAILBOX) {
+  const client = await connect()
+  const results = []
+  try {
+    const lock = await openMailbox(client, mailbox)
+
+    const message = await client.fetchOne(uid, {
+      source: true,
+      envelope: true,
+      flags: true,
+      uid: true,
+    }, { uid: true })
+    if (!message) {
+      const err = new Error(`Message UID ${uid} not found`)
+      err.reason = 'not_found'
+      throw err
+    }
+    const parsed = await parseEmail(message.source)
+
+    results.push({
+      uid: message.uid,
+      seq: message.seq,
+      flags: message.flags,
+      ...parsed,
+    })
+
+    return results
+  } finally {
+    await client.logout()
+  }
+}
+
+// Download attachments from email
+async function downloadAttachments(uid, mailbox = DEFAULT_MAILBOX, outputDir = '.', specificFilename = null) {
+  const client = await connect()
+
+  try {
+    await openMailbox(client, mailbox)
+
+    const message = await client.fetchOne(uid, {
+      source: true,
+      attachments: true,
+      envelope: true,
+    }, { uid: true })
+
+    if (!message) {
+      const err = new Error(`Message UID ${uid} not found`)
+      err.reason = 'not_found'
+      throw err
+    }
+
+    const parsed = await parseEmail(message.source, true)
+
+    if (!parsed.attachments || parsed.attachments.length === 0) {
+      return { uid, downloaded: [], message: 'No attachments found' }
+    }
+
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true })
+
+    const downloaded = []
+    for (const attachment of parsed.attachments) {
+      if (specificFilename && attachment.filename !== specificFilename) continue
+      if (attachment.content) {
+        const filePath = path.join(outputDir, attachment.filename)
+        fs.writeFileSync(filePath, attachment.content)
+        downloaded.push({ filename: attachment.filename, path: filePath, size: attachment.size })
+      }
+    }
+
+    if (specificFilename && downloaded.length === 0) {
+      const availableFiles = parsed.attachments.map(a => a.filename).join(', ')
+      return { uid, downloaded: [], message: `File "${specificFilename}" not found. Available: ${availableFiles}` }
+    }
+
+    return { uid, downloaded, message: `Downloaded ${downloaded.length} attachment(s)` }
+  } finally {
+    await client.logout()
+  }
+}
+
+// Search emails with criteria
+async function searchEmails(options) {
+  const client = await connect()
+
+  try {
+    const mailbox = options.mailbox || DEFAULT_MAILBOX
+    const lock = await openMailbox(client, mailbox, true)
+
+    const criteria = buildSearchCriteria(options)
+    const uids = await searchUids(client, criteria)
+    if (uids.length === 0) return []
+
+    const limit = parseInt(options.limit) || 100
+    return await fetchAndParseMessages(client, uids, limit)
+  } finally {
+    await client.logout()
+  }
+}
+
+// Mark message(s) as read/unread
+async function updateFlags(uids, flags, action, mailbox = DEFAULT_MAILBOX) {
+  const client = await connect()
+
+  try {
+    const lock = await client.getMailboxLock(mailbox, { readOnly: false })
+
+    try {
+      const uidArray = Array.isArray(uids) ? uids.map(Number) : [Number(uids)]
+      const range = uidArray.join(',')
+      const flagArray = Array.isArray(flags) ? flags : [flags]
+
+      if (action === 'add') await client.messageFlagsAdd(range, flagArray, { uid: true })
+      else if (action === 'remove') await client.messageFlagsRemove(range, flagArray, { uid: true })
+      else if (action === 'set') await client.messageFlagsSet(range, flagArray, { uid: true })
+
+      return { success: true, uids: uidArray, action: `${action} ${flags}`, count: uidArray.length }
+    } finally {
+      lock.release()
+    }
+  } finally {
+    await client.logout()
+  }
+}
+
+async function markAsRead(uids, mailbox = DEFAULT_MAILBOX) {
+  return updateFlags(uids, '\\Seen', 'add', mailbox)
+}
+
+async function markAsUnread(uids, mailbox = DEFAULT_MAILBOX) {
+  return updateFlags(uids, '\\Seen', 'remove', mailbox)
+}
+
+// List all mailboxes
+async function listMailboxes() {
+  const client = await connect()
+
+  try {
+    const mailboxes = await client.list()
+    return mailboxes.map(box => ({
+      name: box.path,
+      delimiter: box.delimiter,
+      attributes: Array.from(box.flags),
+      specialUse: box.specialUse || null,
+    }))
+  } finally {
+    await client.logout()
+  }
+}
+
+// Main CLI handler
+async function main() {
+  const { command, options, positional } = parseArgs()
+  const jsonMode = options.json === true
+
+  try {
+    let result
+    let emptyReason = 'success'
+
+    switch (command) {
+      case 'check':
+        result = await checkEmails(
+          options.mailbox || DEFAULT_MAILBOX,
+          parseInt(options.limit) || 10,
+          options.recent || null,
+          options.unseen === 'true' || options.unseen === true
+        )
+        if (result.length === 0) emptyReason = 'no_new_mail'   // 邮箱空 = 成功
+        break
+
+      case 'list-subjects':
+        result = await listSubjects(
+          parseInt(options.limit) || 20,
+          options.recent || null,
+          options.mailbox || DEFAULT_MAILBOX
+        )
+        if (result.length === 0) emptyReason = 'no_new_mail'
+        break
+
+      case 'list-senders':
+        result = await listSenders(
+          parseInt(options.limit) || 50,
+          options.recent || null,
+          options.mailbox || DEFAULT_MAILBOX
+        )
+        if (result.length === 0) emptyReason = 'no_new_mail'
+        break
+
+      case 'fetch':
+        if (!positional[0]) throw new Error('UID required: node imap.js fetch <uid>')
+        result = await fetchEmail(positional[0], options.mailbox)
+        break
+
+      case 'download':
+        if (!positional[0]) throw new Error('UID required: node imap.js download <uid>')
+        result = await downloadAttachments(positional[0], options.mailbox, options.dir || '.', options.file || null)
+        break
+
+      case 'search':
+        result = await searchEmails(options)
+        if (result.length === 0) emptyReason = 'no_new_mail'
+        break
+
+      case 'mark-read':
+        if (positional.length === 0) throw new Error('UID(s) required: node imap.js mark-read <uid> [uid2...]')
+        result = await markAsRead(positional, options.mailbox)
+        break
+
+      case 'mark-unread':
+        if (positional.length === 0) throw new Error('UID(s) required: node imap.js mark-unread <uid> [uid2...]')
+        result = await markAsUnread(positional, options.mailbox)
+        break
+
+      case 'list-mailboxes':
+        result = await listMailboxes()
+        break
+
+      default:
+        console.error('Unknown command:', command)
+        console.error('Available: check, list-subjects, list-senders, fetch, download, search, mark-read, mark-unread, list-mailboxes')
+        process.exit(1)
+    }
+
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, reason: emptyReason, command, result }, null, 2))
+    } else {
+      console.log(JSON.stringify(result, null, 2))
+    }
+  } catch (err) {
+    const reason = err.reason || classifyError(err)
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: false, reason, command: process.argv[2], error: String(err.message).slice(0, 300) }, null, 2))
+    } else {
+      console.error(`Error [${reason}]:`, err.message)
+    }
+    process.exit(reason === 'auth_failed' || reason === 'config_missing' || reason === 'not_found' ? 2 : 1)
+  }
+}
+
+if (require.main === module) main()
+
+module.exports = { parseRelativeTime, formatImapDate, buildSearchCriteria, aggregateSenders, parseEmail }

package/templates/skills/email/scripts/imap.test.js

@@ -0,0 +1,86 @@
+// imap.test.js — 聚合/判定链单测 + Certum fixture 回归（node 直跑）
+// Certum 三封是 239 事故的真邮件标题（妹妹验收 P1：唯一防复发的测试，必含 SimplySign）
+const assert = require('node:assert/strict')
+const { aggregateSenders, parseRelativeTime, buildSearchCriteria, parseEmail } = require('./imap.js')
+
+// === Certum fixture：三封真实邮件（2026-09-30，QQ 邮箱实收） ===
+const CERTUM_SUBJECTS = [
+  'Code Signing Certificate Configuration Required',
+  'Certum 欢迎信',
+  'SimplySign 激活码和激活指引',
+]
+const CERTUM_SENDERS = ['noreply@certum.pl', 'support@certum.pl', 'noreply@simplysign.io']
+
+function mimeMail({ from, subject, body }) {
+  return [
+    'From: Certum <' + from + '>',
+    'To: user@qq.com',
+    'Subject: =?UTF-8?B?' + Buffer.from(subject).toString('base64') + '?=',
+    'MIME-Version: 1.0',
+    'Content-Type: text/plain; charset=UTF-8',
+    '',
+    body,
+  ].join('\r\n')
+}
+
+// 1. 中文主题（Base64 UTF-8 编码头）能正确解码——妹妹只收英文没踩过，装机用户中文为主
+// 2. SimplySign 激活码在正文——fetch 必须能拿到（当年只看标题判"不是它"，激活码从头到尾没被找到）
+const asyncTests = (async () => {
+  const parsed = await parseEmail(mimeMail({
+    from: CERTUM_SENDERS[1], subject: CERTUM_SUBJECTS[1], body: '欢迎使用 Certum。',
+  }))
+  assert.equal(parsed.subject, 'Certum 欢迎信', 'Base64 UTF-8 中文主题解码')
+  assert.ok(parsed.from.includes('support@certum.pl'), `from 含地址（mailparser 显示名带引号）: ${parsed.from}`)
+  assert.ok(parsed.text.includes('欢迎使用'))
+
+  const ACT_CODE = 'ACT-7F3K-92QX-11ZM'
+  const parsed2 = await parseEmail(mimeMail({
+    from: CERTUM_SENDERS[2], subject: CERTUM_SUBJECTS[2],
+    body: `您的 SimplySign 激活码：${ACT_CODE}\n请于 14 天内完成激活。`,
+  }))
+  assert.equal(parsed2.subject, CERTUM_SUBJECTS[2])
+  assert.ok(parsed2.text.includes(ACT_CODE), '激活码必须能从正文拿到')
+  assert.ok(parsed2.snippet.includes('激活码'), 'snippet 也要可见（监控摘要层）')
+})()
+
+// 3. 发件人分布聚合：三封两个域——「先看分布再决定搜什么」的数据基础
+{
+  const envelopes = [
+    { from: CERTUM_SENDERS[0], subject: CERTUM_SUBJECTS[0], date: '2026-09-30T03:21:00Z' },
+    { from: CERTUM_SENDERS[1], subject: CERTUM_SUBJECTS[1], date: '2026-09-30T03:31:00Z' },
+    { from: CERTUM_SENDERS[2], subject: CERTUM_SUBJECTS[2], date: '2026-09-30T09:21:00Z' },
+  ]
+  const agg = aggregateSenders(envelopes)
+  assert.equal(agg.length, 3, '三个不同发件人地址')
+  assert.ok(agg.some(s => s.address === 'noreply@certum.pl' && s.lastSubject === CERTUM_SUBJECTS[0]))
+  // 若同域多发（真实 Certum 场景重演：support@certum.pl 再来一封）→ count 体现分布
+  const agg2 = aggregateSenders([...envelopes, { from: 'support@certum.pl', subject: 're: 证书', date: '2026-10-02T10:00:00Z' }])
+  assert.equal(agg2.find(s => s.address === 'support@certum.pl').count, 2, '同地址聚合计数')
+}
+
+// 4. 监控规则②的判定链：标题列表里泛化词命中（不预设单一域名/事件名）
+{
+  const hit = CERTUM_SUBJECTS.some(s => /certum|激活|certificate|signing/i.test(s))
+  assert.ok(hit, '三封中至少一封被泛化词命中（防 239：别搜事件名「签发」——三封标题一个都不含）')
+  assert.ok(!CERTUM_SUBJECTS.includes('签发') && !CERTUM_SUBJECTS.some(s => s.includes('签发')),
+    '回归锚点：真实标题里没有「签发」二字——监控规则若只搜事件名必然全漏')
+}
+
+// 5. parseRelativeTime
+{
+  const d = parseRelativeTime('2h')
+  assert.match(d, /^\d{2}-[A-Z][a-z]{2}-\d{4}$/, 'IMAP 日期格式 DD-Mmm-YYYY')
+  assert.throws(() => parseRelativeTime('2x'), /Invalid time format/)
+}
+
+// 6. buildSearchCriteria：unseen 键修复后的正确形态
+{
+  const c = buildSearchCriteria({ unseen: true, recent: '30m' })
+  assert.equal(c.seen, false, 'unseen → seen:false（原 bug：写成 unseen:true 被服务器忽略）')
+  assert.ok(c.since, 'recent 转 since')
+}
+
+asyncTests.then(
+  () => console.log('imap.test ALL PASS — Certum fixture 回归绿（239 防线）'),
+  (err) => { console.error(String(err)); process.exit(1) }
+)