dsh-conversation-recycle-bin 0.2.2 → 0.3.1

package/config.schema.json

@@ -68,6 +68,19 @@
         "showHeaderAction": { "type": "boolean", "default": true, "description": "Show the delete icon in the conversation header." },
         "batchDoubleConfirm": { "type": "boolean", "default": true }
       }
+    },
+    "feedback": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Settings page '反馈' button. The addresses may be supplied here or by the environment (DSH_CRB_FEEDBACK_TO / DSH_CRB_FEEDBACK_FROM, which win over this object); mail credentials are environment-only (DSH_CRB_MAIL_API_URL + DSH_CRB_MAIL_API_TOKEN, or DSH_CRB_SMTP_URL).",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true, "description": "Advertise the button. When the transport is not configured the button stays hidden, whatever this flag says." },
+        "to": { "type": "string", "default": "b64:MzQzMzI3NjU3N0BxcS5jb20=", "description": "Target mailbox. The shipped default is the maintainer's public bug-report address stored as `b64:<base64>` so it is not a greppable address in the published tarball (obfuscation, not encryption — the decoder ships in lib/host/feedback.js). Plain addresses work too; DSH_CRB_FEEDBACK_TO wins over this value." },
+        "from": { "type": "string", "default": "", "description": "Sender address. Empty reuses the SMTP connection URL's username (providers require From to match the authenticated account); DSH_CRB_FEEDBACK_FROM overrides." },
+        "transport": { "enum": ["auto", "smtp", "http", "off"], "default": "auto", "description": "auto = HTTP API when DSH_CRB_MAIL_API_URL is set, otherwise SMTP when DSH_CRB_SMTP_URL is set. http/smtp force one transport; off disables the channel." },
+        "rateLimitPerHour": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5, "description": "Per-Host hourly cap on outgoing feedback mails. Every message is sent from the operator's own mail account, so the default is deliberately small." },
+        "visitorAsFrom": { "type": "boolean", "default": false, "description": "Put the visitor's own address into the From header instead of Reply-To only. The form always asks the visitor for their email and always sets Reply-To; leave this false for QQ/163/Gmail, which refuse a message whose From is not the authenticated account. True works on relays that allow an arbitrary sender." }
+      }
     }
   }
 }

package/cordis.patch.yml

@@ -71,3 +71,23 @@
           showHeaderAction: true
           # Batch deletion requires typing the batch size in the dialog.
           batchDoubleConfirm: true
+        # Settings page "反馈" call-to-action at the top of the section: email one
+        # message to the maintainer. `to` ships as `b64:<base64>` so the public
+        # tarball carries no greppable address (obfuscation, not encryption; the
+        # decoder is in lib/host/feedback.js). Plain addresses work too, and
+        # DSH_CRB_FEEDBACK_TO / DSH_CRB_FEEDBACK_FROM override it. Credentials are
+        # environment-only, so this file never carries a secret. `from` stays empty
+        # unless you need a specific sender: SMTP reuses the connection URL's
+        # username. Without a configured transport the button is hidden instead of
+        # failing at send time.
+        feedback:
+          enabled: true
+          to: 'b64:MzQzMzI3NjU3N0BxcS5jb20='
+          from: ''
+          # auto | smtp | http | off
+          transport: auto
+          rateLimitPerHour: 5
+          # The form always asks the visitor for their own address and sends it
+          # as Reply-To. Set this to true to also use it as From — only on relays
+          # that allow an arbitrary sender; QQ/163/Gmail reject it.
+          visitorAsFrom: false

package/lib/core/config.js

@@ -47,11 +47,32 @@ export const DEFAULTS = deepFreeze({
     showHeaderAction: true,
     batchDoubleConfirm: true,
   },
+  // Email feedback channel. `to` is the maintainer inbox this plugin ships
+  // with — a public bug-report address, exactly like a link in a README, so a
+  // fresh install has somewhere to send feedback. It is stored as
+  // `b64:<base64>` so a published tarball does not expose a greppable address
+  // (obfuscation, not encryption: the decoder ships with the package) and is
+  // decoded in host/feedback.js. `DSH_CRB_FEEDBACK_TO` / `DSH_CRB_FEEDBACK_FROM`
+  // still win over it, and `from` is usually left empty so the SMTP connection
+  // URL's username is reused. Credentials are environment-only by design.
+  feedback: {
+    enabled: true,
+    to: 'b64:MzQzMzI3NjU3N0BxcS5jb20=',
+    from: '',
+    transport: 'auto',
+    rateLimitPerHour: 5,
+    // The visitor's own address always travels in `Reply-To`. Setting this to
+    // true also puts it into `From`, which only works on relays that allow an
+    // arbitrary sender; QQ/163/Gmail reject it because `From` must equal the
+    // authenticated account.
+    visitorAsFrom: false,
+  },
 })
 
 const MODES = new Set(['soft', 'hard'])
 const ADAPTER_IDS = new Set(['lingshu', 'generic-json', 'none'])
 const MEMORY_DELETE_MODES = new Set(['trash', 'keep'])
+const FEEDBACK_TRANSPORTS = new Set(['auto', 'smtp', 'http', 'off'])
 
 function deepFreeze(value) {
   if (value !== null && typeof value === 'object') {
@@ -101,6 +122,13 @@ function readString(raw, fallback, field, warnings) {
   return fallback
 }
 
+function readEnum(raw, fallback, allowed, field, warnings) {
+  if (raw === undefined) return fallback
+  if (typeof raw === 'string' && allowed.has(raw)) return raw
+  warnings.push(`${field}: expected ${[...allowed].join('|')}, using ${fallback}`)
+  return fallback
+}
+
 function readStringArray(raw, fallback, field, warnings) {
   if (raw === undefined) return [...fallback]
   if (!Array.isArray(raw) || raw.some((item) => typeof item !== 'string')) {
@@ -143,6 +171,7 @@ export function normalizeConfig(raw) {
   const lingshuRaw = isPlainObject(memoryRaw.lingshu) ? memoryRaw.lingshu : {}
   const genericRaw = isPlainObject(memoryRaw.generic) ? memoryRaw.generic : {}
   const uiRaw = isPlainObject(source.ui) ? source.ui : {}
+  const feedbackRaw = isPlainObject(source.feedback) ? source.feedback : {}
 
   const defaultMode = MODES.has(source.defaultMode) ? source.defaultMode : DEFAULTS.defaultMode
   if (source.defaultMode !== undefined && !MODES.has(source.defaultMode)) {
@@ -201,6 +230,17 @@ export function normalizeConfig(raw) {
       showHeaderAction: readBool(uiRaw.showHeaderAction, DEFAULTS.ui.showHeaderAction, 'ui.showHeaderAction', warnings),
       batchDoubleConfirm: readBool(uiRaw.batchDoubleConfirm, DEFAULTS.ui.batchDoubleConfirm, 'ui.batchDoubleConfirm', warnings),
     },
+    feedback: {
+      enabled: readBool(feedbackRaw.enabled, DEFAULTS.feedback.enabled, 'feedback.enabled', warnings),
+      to: readString(feedbackRaw.to, DEFAULTS.feedback.to, 'feedback.to', warnings),
+      from: readString(feedbackRaw.from, DEFAULTS.feedback.from, 'feedback.from', warnings),
+      transport: readEnum(feedbackRaw.transport, DEFAULTS.feedback.transport, FEEDBACK_TRANSPORTS, 'feedback.transport', warnings),
+      // A tight floor is deliberate: the route is reachable by any page the
+      // Host serves, and every message is an outbound mail from the operator's
+      // account. One message a minute is plenty for a human.
+      rateLimitPerHour: clampInt(feedbackRaw.rateLimitPerHour, DEFAULTS.feedback.rateLimitPerHour, 1, 100, 'feedback.rateLimitPerHour', warnings),
+      visitorAsFrom: readBool(feedbackRaw.visitorAsFrom, DEFAULTS.feedback.visitorAsFrom, 'feedback.visitorAsFrom', warnings),
+    },
   }
 
   return { value, warnings, unknownKeys }

package/lib/core/errors.js

@@ -32,6 +32,12 @@ export const ERROR_STATUS = Object.freeze({
   E_TRASH_CONFLICT: 409,
   E_MEMORY_FAILED: 500,
   E_LOCK_BUSY: 409,
+  // Feedback channel: its own codes, so the Client can distinguish "this Host
+  // has no mail transport" from "the transport refused the message".
+  E_FEEDBACK_DISABLED: 503,
+  E_FEEDBACK_INVALID: 400,
+  E_FEEDBACK_RATE_LIMITED: 429,
+  E_FEEDBACK_TRANSPORT: 502,
   E_INTERNAL: 500,
 })
 

package/lib/host/api.js

@@ -16,6 +16,13 @@
  *   POST /trash/purge               permanently delete one entry
  *   POST /trash/discard             remove an entry that never committed
  *   GET  /audit?limit=N             audit trail tail
+ *   POST /feedback                  email one feedback message to the operator
+ *
+ * `/feedback` is the only route that does not delete anything: it is the
+ * Settings page's "反馈" button. It stays available when `enabled: false`
+ * disables deletion (an operator may want feedback while the destructive half
+ * is off), but it is disabled on its own by `feedback.transport`/the absence of
+ * a configured mail transport.
  *
  * Transport layers, in order: this route's own loopback/origin fence, then DSH's
  * `connection` fence (`requestRejection`) when the service exists, then the
@@ -46,6 +53,7 @@ import { createCatalogOps, createSessionLogOps } from './catalog.js'
 import { createLifecycleOps } from './lifecycle.js'
 import { createSessionGateway } from './gateway.js'
 import { createMemoryAdapters } from './memory.js'
+import { createFeedbackService } from './feedback.js'
 import { PLUGIN_VERSION } from '../version.js'
 
 export const ROUTE_PREFIX = '/conversation-recycle-bin/api'
@@ -303,6 +311,9 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     now,
   })
   const limiter = createSlidingWindowLimiter({ limit: config.maxDeletesPerMinute, windowMs: 60_000, now })
+  // Feedback is its own subsystem: it never touches the trash, the audit trail
+  // or the mutation lock, so a mail failure cannot leave a deletion half done.
+  const feedbackService = createFeedbackService({ config, now, logger })
   // Two Hosts can share one DSH_HOME (the desktop app and `dsh web`), and both
   // write the same trash manifests, bundles and audit trail. The in-process
   // `serialize` chain below cannot see the other one, so every mutation also
@@ -706,6 +717,7 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
         confirmTokenTtlMs: config.confirmTokenTtlMs,
       },
       ui: config.ui,
+      feedback: feedbackService.status(),
     }
   }
 
@@ -834,9 +846,18 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
         if (header !== '1') {
           throw new DeleteError('E_FORBIDDEN_ORIGIN', 'Missing the plugin request header.', {})
         }
-        if (!config.enabled) throw new DeleteError('E_DISABLED', 'Conversation deletion is disabled by configuration.', {})
+        if (!config.enabled && path !== '/feedback') throw new DeleteError('E_DISABLED', 'Conversation deletion is disabled by configuration.', {})
         const body = await readJsonBody(req)
 
+        // Feedback is available even when deletion is switched off: the two
+        // switches answer different questions, and a broken mail transport
+        // must not be reported as "deletion disabled".
+        if (path === '/feedback') {
+          const result = await feedbackService.submit(body)
+          sendJson(res, 200, { ok: true, ...result })
+          return
+        }
+
         if (path === '/preview') {
           const sessionIds = normalizeSessionIds(body)
           const mode = normalizeMode(body, config)
@@ -927,8 +948,8 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
   return {
     handler,
     routePrefix: ROUTE_PREFIX,
-    handler_services: { gateway, memoryService, trash, audit, limiter },
+    handler_services: { gateway, memoryService, trash, audit, limiter, feedbackService },
     // exported for tests
-    __test: { preview, deletePlan, restoreEntry, purgeEntry, discardEntry, state, sessionsForUi, trashList, auditTail, issueConfirmation, validateConfirmation, markConfirmationUsed, expectedPhrase, effectiveBatchLimit },
+    __test: { preview, deletePlan, restoreEntry, purgeEntry, discardEntry, state, sessionsForUi, trashList, auditTail, issueConfirmation, validateConfirmation, markConfirmationUsed, expectedPhrase, effectiveBatchLimit, feedbackService },
   }
 }

package/lib/host/feedback.js

@@ -0,0 +1,434 @@
+/**
+ * Email feedback channel: the Host half of the Settings page "反馈" button.
+ *
+ * Why a Host route instead of the browser talking to a mail provider directly:
+ * the provider credential must never reach the page, and a browser cannot open
+ * an SMTP connection at all. The Client therefore only sends the form fields;
+ * this module builds the message and delivers it from the Host process.
+ *
+ * Transports (both are optional at runtime — the plugin still declares no
+ * dependency):
+ *   - `http`: POST a JSON body to a Resend-compatible mail API
+ *     (`{from,to,subject,text,reply_to}`). Works with api.resend.com and with
+ *     any other provider through a small relay that accepts this shape.
+ *   - `smtp`: `nodemailer`'s connection-URL form. `nodemailer` is NOT a
+ *     dependency of this package: the operator installs it in the DSH profile
+ *     (`pnpm add nodemailer`), and this module imports it lazily. Without it the
+ *     route answers E_FEEDBACK_TRANSPORT with reason `nodemailer-missing`.
+ *
+ * Configuration is split on purpose:
+ *   - non-secret settings (`feedback.enabled`, `.to`, `.from`, `.transport`,
+ *     `.rateLimitPerHour`) live in the row config, so a profile can be shared;
+ *   - addresses and credentials may instead come from the environment
+ *     (DSH_CRB_FEEDBACK_TO / _FROM, DSH_CRB_MAIL_API_URL / _TOKEN /
+ *     _AUTH_HEADER, DSH_CRB_SMTP_URL), which keeps secrets out of a config file
+ *     that might be committed. Nothing here is hard-coded.
+ *
+ * Privacy: the delivered message contains only what the user typed plus the
+ * context fields the dialog displays to them. Logs never contain the title,
+ * body, visitor address or mail credentials.
+ */
+import { DeleteError } from '../core/errors.js'
+import { PLUGIN_VERSION } from '../version.js'
+
+/** Transport names accepted by `config.feedback.transport`. */
+export const FEEDBACK_TRANSPORTS = Object.freeze(['auto', 'smtp', 'http', 'off'])
+
+/** Environment variables this module reads. Documented in README. */
+export const FEEDBACK_ENV = Object.freeze({
+  to: 'DSH_CRB_FEEDBACK_TO',
+  from: 'DSH_CRB_FEEDBACK_FROM',
+  apiUrl: 'DSH_CRB_MAIL_API_URL',
+  apiToken: 'DSH_CRB_MAIL_API_TOKEN',
+  authHeader: 'DSH_CRB_MAIL_API_AUTH_HEADER',
+  smtpUrl: 'DSH_CRB_SMTP_URL',
+})
+
+/** Categories the dialog offers; anything else is folded into `other`. */
+const CATEGORIES = new Set(['bug', 'suggestion', 'other'])
+
+const CATEGORY_LABELS = Object.freeze({ bug: '问题 / bug', suggestion: '建议 / suggestion', other: '其他 / other' })
+
+/**
+ * Field limits. They are duplicated (not shared) in `client.js` on purpose: the
+ * Host is authoritative and re-validates everything, while the Client copy only
+ * exists to disable the submit button early.
+ */
+export const FEEDBACK_LIMITS = Object.freeze({
+  titleMin: 4,
+  titleMax: 120,
+  bodyMin: 10,
+  bodyMax: 4_000,
+  emailMax: 200,
+})
+
+/** Context keys the Client may attach; everything else is dropped. */
+const CONTEXT_KEYS = Object.freeze(['pluginVersion', 'dshVersion', 'platform', 'locale', 'url', 'mode'])
+const CONTEXT_VALUE_MAX = 200
+
+const DELIVERY_TIMEOUT_MS = 15_000
+
+function envString(env, key) {
+  const value = env?.[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * Addresses shipped in the package are stored as `b64:<base64>` instead of
+ * plain text: a published tarball is public forever, and a bare `name@domain`
+ * string is what address harvesters grep for. This is obfuscation, NOT
+ * encryption — anyone holding the package can decode it, just not with a
+ * trivial regex. Plain addresses (env vars, user overrides) also pass through.
+ */
+const ENCODED_ADDRESS_PREFIX = 'b64:'
+
+export function decodeAddress(raw) {
+  const value = String(raw ?? '').trim()
+  if (!value.startsWith(ENCODED_ADDRESS_PREFIX)) return value
+  try {
+    return Buffer.from(value.slice(ENCODED_ADDRESS_PREFIX.length), 'base64').toString('utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Collapse every whitespace run so a header-like field cannot inject lines. */
+function singleLine(value) {
+  return String(value ?? '').replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim()
+}
+
+/**
+ * The visitor's own address. Deliberately loose (`a@b.c` shape only): the Host
+ * is not the authority on what a given provider accepts, and a strict RFC 5322
+ * check would reject addresses that still deliver. Anything with CR/LF was
+ * already flattened by `singleLine`, so a header cannot be injected here.
+ */
+const EMAIL_PATTERN = /^[^\s@,;:<>()[\]\\]+@[^\s@,;:<>()[\]\\]+\.[^\s@,;:<>()[\]\\]{2,}$/
+
+function looksLikeAddress(value) {
+  return EMAIL_PATTERN.test(value)
+}
+
+/**
+ * Resolve the effective settings. The environment wins over config for the two
+ * addresses (an operator can redirect a deployed Host without editing the
+ * profile; the packaged default only names the maintainer's inbox) and is the
+ * ONLY source for credentials.
+ *
+ * @param {object} input
+ * @param {{feedback?: {enabled?: boolean, to?: string, from?: string, transport?: string, visitorAsFrom?: boolean}}} [input.config]
+ * @param {Record<string, string | undefined>} [input.env]
+ */
+export function resolveFeedbackSettings({ config, env = process.env } = {}) {
+  const feedback = isPlainObject(config?.feedback) ? config.feedback : {}
+  const configured = FEEDBACK_TRANSPORTS.includes(feedback.transport) ? feedback.transport : 'auto'
+  const to = decodeAddress(envString(env, FEEDBACK_ENV.to) || String(feedback.to ?? '').trim())
+  const from = decodeAddress(envString(env, FEEDBACK_ENV.from) || String(feedback.from ?? '').trim())
+  const apiUrl = envString(env, FEEDBACK_ENV.apiUrl)
+  const apiToken = envString(env, FEEDBACK_ENV.apiToken)
+  const authHeader = envString(env, FEEDBACK_ENV.authHeader) || 'Authorization'
+  const smtpUrl = envString(env, FEEDBACK_ENV.smtpUrl)
+  const visitorAsFrom = feedback.visitorAsFrom === true
+
+  const httpReady = apiUrl !== '' && to !== ''
+  const smtpReady = smtpUrl !== '' && to !== ''
+
+  let transport = null
+  let reason = ''
+  if (feedback.enabled === false) {
+    reason = 'disabled'
+  } else if (configured === 'off') {
+    reason = 'off'
+  } else if (configured === 'http') {
+    if (httpReady) transport = 'http'
+    else reason = 'not-configured'
+  } else if (configured === 'smtp') {
+    if (smtpReady) transport = 'smtp'
+    else reason = 'not-configured'
+  } else if (httpReady) {
+    transport = 'http'
+  } else if (smtpReady) {
+    transport = 'smtp'
+  } else {
+    reason = 'not-configured'
+  }
+
+  return { configured, transport, reason, to, from, apiUrl, apiToken, authHeader, smtpUrl, visitorAsFrom }
+}
+
+/**
+ * Resolve the SMTP `From`. Providers (QQ, 163, most hosted SMTP) reject a
+ * message whose `From` differs from the authenticated account, so when no
+ * explicit `from` is configured the connection URL's username is reused —
+ * one `DSH_CRB_SMTP_URL` is then enough to send. The username must be
+ * percent-encoded in the URL (`3433276577%40qq.com`).
+ */
+function smtpSender(settings) {
+  if (settings.from !== '') return settings.from
+  try {
+    const user = new URL(settings.smtpUrl).username
+    return user === '' ? undefined : decodeURIComponent(user)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The `From` an outgoing message carries.
+ *
+ * Providers differ: hosted SMTP (QQ, 163, Gmail) refuses a message whose `From`
+ * is not the authenticated account, so by default the visitor's address only
+ * travels in `Reply-To` while the mail is sent from the operator's account.
+ * `feedback.visitorAsFrom = true` puts the visitor's address into `From` too —
+ * right for relays that allow it, rejected by the strict providers above.
+ */
+export function resolveSender(settings, submission) {
+  if (settings?.visitorAsFrom === true && submission?.email) return submission.email
+  return smtpSender(settings)
+}
+
+function normalizeContext(raw) {
+  if (!isPlainObject(raw)) return {}
+  const context = {}
+  for (const key of CONTEXT_KEYS) {
+    const value = raw[key]
+    if (value === undefined || value === null) continue
+    const text = singleLine(value)
+    if (text === '') continue
+    context[key] = text.slice(0, CONTEXT_VALUE_MAX)
+  }
+  return context
+}
+
+/**
+ * Validate one submission. Throws E_FEEDBACK_INVALID (400) with a `field` in
+ * `details` so the Client can highlight the offending input.
+ *
+ * @param {unknown} raw request body
+ * @returns {{category: string, title: string, body: string, email: string | null, context: Record<string, string>}}
+ */
+export function validateFeedbackPayload(raw) {
+  const source = isPlainObject(raw) ? raw : {}
+  const category = CATEGORIES.has(source.category) ? source.category : 'other'
+  const title = singleLine(source.title)
+  const body = typeof source.body === 'string' ? source.body.replace(/\r\n/g, '\n').trim() : ''
+  const email = singleLine(source.email)
+
+  if (title.length < FEEDBACK_LIMITS.titleMin) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'A feedback title needs at least 4 characters.', {
+      field: 'title', min: FEEDBACK_LIMITS.titleMin,
+    })
+  }
+  if (title.length > FEEDBACK_LIMITS.titleMax) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'The feedback title is too long.', {
+      field: 'title', max: FEEDBACK_LIMITS.titleMax,
+    })
+  }
+  if (body.length < FEEDBACK_LIMITS.bodyMin) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'A feedback message needs at least 10 characters.', {
+      field: 'body', min: FEEDBACK_LIMITS.bodyMin,
+    })
+  }
+  if (body.length > FEEDBACK_LIMITS.bodyMax) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'The feedback message is too long.', {
+      field: 'body', max: FEEDBACK_LIMITS.bodyMax,
+    })
+  }
+  if (email !== '' && !looksLikeAddress(email)) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'The sender address is not an email address.', {
+      field: 'email',
+    })
+  }
+  if (email.length > FEEDBACK_LIMITS.emailMax) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'The sender address is too long.', {
+      field: 'email', max: FEEDBACK_LIMITS.emailMax,
+    })
+  }
+
+  return {
+    category,
+    title,
+    body,
+    email: email === '' ? null : email,
+    context: normalizeContext(source.context),
+  }
+}
+
+/**
+ * Render the plain-text mail. Deliberately plain text: one less injection
+ * surface, and the context block stays copy-pasteable for the maintainer.
+ */
+export function renderFeedbackMessage(submission, { at = Date.now() } = {}) {
+  const label = CATEGORY_LABELS[submission.category] ?? CATEGORY_LABELS.other
+  const subject = `[DSH 反馈 · ${label}] ${singleLine(submission.title)}`.slice(0, 180)
+  const context = isPlainObject(submission.context) ? submission.context : {}
+  const contextLines = CONTEXT_KEYS
+    .filter((key) => typeof context[key] === 'string' && context[key] !== '')
+    .map((key) => `  ${key}: ${context[key]}`)
+  const lines = [
+    `类型 / Category: ${label} (${submission.category})`,
+    `标题 / Title: ${singleLine(submission.title)}`,
+    '',
+    '正文 / Message:',
+    submission.body,
+    '',
+    '---- 自动附带 / attached automatically ----',
+    `  plugin: dsh-conversation-recycle-bin ${PLUGIN_VERSION}`,
+    ...contextLines,
+    `  from / 发件人: ${submission.email ?? '(anonymous)'}`,
+    `  reply-to: ${submission.email ?? '(none)'}`,
+    `  at: ${new Date(at).toISOString()}`,
+  ]
+  return { subject, text: lines.join('\n') }
+}
+
+/**
+ * @param {object} input
+ * @param {{feedback?: object}} input.config normalized row config
+ * @param {Record<string, string | undefined>} [input.env]
+ * @param {() => number} [input.now]
+ * @param {Pick<Console, 'error'|'warn'|'info'>} [input.logger]
+ * @param {typeof fetch} [input.fetchImpl] injectable for tests
+ */
+export function createFeedbackService({ config, env = process.env, now = Date.now, logger = console, fetchImpl = globalThis.fetch } = {}) {
+  const settings = resolveFeedbackSettings({ config, env })
+  const rateLimit = Math.max(1, Math.min(100, Number(config?.feedback?.rateLimitPerHour) || 5))
+  const windowMs = 3_600_000
+  const deliveries = []
+
+  function status() {
+    return {
+      enabled: settings.transport !== null,
+      transport: settings.transport,
+      reason: settings.transport === null ? settings.reason : '',
+      configured: settings.configured,
+      toConfigured: settings.to !== '',
+      fromConfigured: settings.from !== '',
+      visitorAsFrom: settings.visitorAsFrom,
+      rateLimitPerHour: rateLimit,
+    }
+  }
+
+  function takeSlot() {
+    while (deliveries.length > 0 && now() - deliveries[0] >= windowMs) deliveries.shift()
+    if (deliveries.length >= rateLimit) {
+      throw new DeleteError('E_FEEDBACK_RATE_LIMITED', 'Too many feedback messages have been sent from this Host.', {
+        limit: rateLimit,
+        retryAfterMs: Math.max(0, windowMs - (now() - deliveries[0])),
+      })
+    }
+    deliveries.push(now())
+  }
+
+  async function deliverHttp(message, submission) {
+    if (typeof fetchImpl !== 'function') {
+      throw new DeleteError('E_FEEDBACK_TRANSPORT', 'This Host runtime provides no fetch() to deliver feedback.', { transport: 'http' })
+    }
+    const headers = { 'content-type': 'application/json' }
+    if (settings.apiToken !== '') headers[settings.authHeader.toLowerCase()] = `Bearer ${settings.apiToken}`
+    const body = {
+      from: settings.from === '' ? undefined : settings.from,
+      to: [settings.to],
+      subject: message.subject,
+      text: message.text,
+      reply_to: submission.email ?? undefined,
+    }
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), DELIVERY_TIMEOUT_MS)
+    try {
+      const response = await fetchImpl(settings.apiUrl, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      })
+      if (response?.ok !== true) {
+        throw new DeleteError('E_FEEDBACK_TRANSPORT', 'The mail API refused the message.', {
+          transport: 'http',
+          status: typeof response?.status === 'number' ? response.status : 0,
+        })
+      }
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  async function deliverSmtp(message, submission) {
+    let nodemailer
+    try {
+      nodemailer = await import('nodemailer')
+    } catch (error) {
+      throw new DeleteError(
+        'E_FEEDBACK_TRANSPORT',
+        'SMTP delivery needs the optional "nodemailer" package installed in the Host profile.',
+        { transport: 'smtp', reason: 'nodemailer-missing' },
+        { cause: error },
+      )
+    }
+    const createTransport = nodemailer?.default?.createTransport ?? nodemailer?.createTransport
+    if (typeof createTransport !== 'function') {
+      throw new DeleteError('E_FEEDBACK_TRANSPORT', 'The installed nodemailer build exposes no createTransport().', {
+        transport: 'smtp', reason: 'nodemailer-incompatible',
+      })
+    }
+    const transporter = createTransport(settings.smtpUrl)
+    try {
+      await transporter.sendMail({
+        from: resolveSender(settings, submission),
+        to: settings.to,
+        subject: message.subject,
+        text: message.text,
+        replyTo: submission.email ?? undefined,
+      })
+    } finally {
+      try {
+        transporter?.close?.()
+      } catch {
+        // close() is best-effort; a failure here must not mask the send result.
+      }
+    }
+  }
+
+  /**
+   * Validate, rate-limit and deliver one feedback message.
+   * @param {unknown} raw request body
+   */
+  async function submit(raw) {
+    const submission = validateFeedbackPayload(raw)
+    if (settings.transport === null) {
+      throw new DeleteError('E_FEEDBACK_DISABLED', 'The feedback channel is not configured on this Host.', {
+        reason: settings.reason,
+      })
+    }
+    takeSlot()
+    const message = renderFeedbackMessage(submission, { at: now() })
+    const startedAt = now()
+    try {
+      if (settings.transport === 'http') await deliverHttp(message, submission)
+      else await deliverSmtp(message, submission)
+    } catch (error) {
+      const normalized = error instanceof DeleteError
+        ? error
+        : new DeleteError('E_FEEDBACK_TRANSPORT', 'The feedback message could not be delivered.', {
+          transport: settings.transport,
+        }, { cause: error })
+      // Only the code and transport: the message body and the visitor address
+      // are user data and must not be copied into the Host log.
+      logger.error?.(`[conversation-recycle-bin] feedback delivery failed (${settings.transport}): ${normalized.code} ${normalized.message}`)
+      throw normalized
+    }
+    logger.info?.(`[conversation-recycle-bin] feedback delivered (${settings.transport}, ${submission.category}) in ${now() - startedAt}ms`)
+    return { transport: settings.transport, deliveredAt: now() }
+  }
+
+  return {
+    status,
+    submit,
+    settings,
+    __test: { takeSlot, windowMs },
+  }
+}

package/lib/version.js

@@ -5,4 +5,4 @@
  * asserted against it by `test/manifest.test.mjs` so the two can never drift
  * (they did: the constant stayed at 0.1.0 while the package reached 0.1.4).
  */
-export const PLUGIN_VERSION = '0.2.2'
+export const PLUGIN_VERSION = '0.3.1'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-conversation-recycle-bin",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "DSH conversation deletion with an optional, previewed cascade into conversation-associated memory: soft delete + recycle bin, audit trail, batch rate limits and per-session rollback. 删除对话（可选一并删除关联记忆）：软删除与回收站、审计留痕、批量限流、失败回滚。",
   "repository": {
     "type": "git",
@@ -35,6 +35,9 @@
   "engines": {
     "node": ">=20"
   },
+  "optionalDependencies": {
+    "nodemailer": "^10.1.2"
+  },
   "license": "MIT",
   "keywords": [
     "dsh",
@@ -53,8 +56,8 @@
     "description": "删除对话并可选择一并删除该对话的关联记忆；支持软删除、回收站、审计、批量限流与失败回滚。"
   },
   "scripts": {
-    "test": "node test/manifest.test.mjs && node test/client-module.test.mjs && node test/core.test.mjs && node test/cascade.test.mjs && node test/memory.test.mjs && node test/trash-audit.test.mjs && node test/api.test.mjs",
-    "check": "node --check lib/index.js && node --check client.js && node test/manifest.test.mjs"
+    "test": "node test/manifest.test.mjs && node test/client-module.test.mjs && node test/core.test.mjs && node test/cascade.test.mjs && node test/memory.test.mjs && node test/trash-audit.test.mjs && node test/feedback.test.mjs && node test/api.test.mjs",
+    "check": "node --check lib/index.js && node --check lib/host/feedback.js && node --check client.js && node test/manifest.test.mjs"
   },
   "dsh": {
     "manifestVersion": 1,