dsh-conversation-recycle-bin 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to `dsh-conversation-recycle-bin` are documented here.
 The format follows Keep a Changelog; the project uses Semantic Versioning.
 
+## [0.3.0] — 2026-10-18
+
+### Added
+
+- **设置页「反馈」横幅（`feedback` 配置段 + `POST /conversation-recycle-bin/api/feedback`）**：设置页最上方新增一条「反馈」横幅（主色按钮，位于标题之上；`dc-feedback-bar`），表单含类型（问题 / 建议 / 其他）、标题、正文、可选联系方式，并自动附带插件版本、平台与语言（不含任何对话内容）。提交时按钮进入「正在发送…」禁用态，成功后弹 toast 并关闭对话框，失败按错误码给出可读原因。Host 侧 `lib/host/feedback.js` 负责校验、渲染与投递：标题 4–120 字、正文 10–4000 字、联系方式 ≤200 字（Host 复核，客户端只是提前禁用按钮）；每条反馈每小时默认最多 5 条（`feedback.rateLimitPerHour`），全部从操作者自己的邮箱发出。
+- **两种投递通道，均为环境变量注入凭证**：`http`（`DSH_CRB_MAIL_API_URL` + `DSH_CRB_MAIL_API_TOKEN`，POST JSON）与 `smtp`（`DSH_CRB_SMTP_URL`，按需 `import('nodemailer')`）。`nodemailer` 只声明为 `optionalDependencies`（`^10.1.2`），装不上不影响插件其余功能，缺失时明确返回 `reason: nodemailer-missing`。收件人/发件人由配置项 `feedback.to` / `feedback.from` 给出，**环境变量 `DSH_CRB_FEEDBACK_TO` / `DSH_CRB_FEEDBACK_FROM` 优先于它们**（同一份包被多人/多机使用时不必改配置文件）；`feedback.to` 默认即维护者收件箱，以 `b64:<base64>` 形式随包分发（避免公开 tarball 中出现可被正则抓取的 `name@domain`；属混淆而非加密，解码器在 `lib/host/feedback.js`，明文地址同样可用），`feedback.from` 默认留空并复用 SMTP 连接串里的用户名（服务商要求 From 与登录账号一致）。**任何凭证都不进配置文件、不进代码库**。
+- **反馈通道与删除开关解耦**：`enabled:false` 只关闭删除；`/state.feedback` 单独报告 `enabled`、`transport`、`toConfigured`。通道未配置时设置页不渲染按钮，直接请求也返回 `503 E_FEEDBACK_DISABLED`（带 `reason: not-configured | disabled | off`），而不是在点击后才失败。
+- 新增错误码 `E_FEEDBACK_DISABLED`(503) / `E_FEEDBACK_INVALID`(400) / `E_FEEDBACK_RATE_LIMITED`(429) / `E_FEEDBACK_TRANSPORT`(502)；投递失败只记错误码与 HTTP 状态，**正文、标题、联系方式不进 Host 日志**。
+- **收件地址以 `b64:<base64>` 打包**：默认收件箱不再以明文 `name@domain` 出现在 `cordis.patch.yml` / `config.schema.json` / README / CHANGELOG 中，避免公开 tarball 被正则抓取。这是**混淆而非加密**——解码器 `decodeAddress()` 就在 `lib/host/feedback.js` 里，拿到包的人总能还原；明文地址与环境变量照旧可用。
+
+### Changed
+
+- `npm test` 增加 `test/feedback.test.mjs`（15 个用例：配置归一化、通道判定、校验/渲染、HTTP 通路、失败状态、限流窗口、未配置、SMTP 缺依赖、两条路由用例），用例总数 106 → 121；`npm run check` 增加 `lib/host/feedback.js` 语法检查。
+- `cordis.patch.yml` / `config.schema.json` 增加 `feedback` 默认段（`to` 默认为维护者公开反馈邮箱、`from` 留空、`transport: auto`、`rateLimitPerHour: 5`）。
+
 ## [0.2.2] — 2026-10-18
 
 对 0.2.1 的双环境（桌面/网页）全面审计修复轮。问题编号对应 `AUDIT-2026-10-17-desktop-web.md`；每个问题在该文档中都有平台、复现条件、原因与修复方向的完整记录。

package/README.md

@@ -188,8 +188,9 @@ dsh-conversation-recycle-bin/
 │     ├─ catalog.js             # archive/detach/pin 与日志移动
 │     ├─ lifecycle.js           # live 会话停机：cancel + archive + drain
 │     ├─ memory.js               # 适配器装配
+│     ├─ feedback.js             # 反馈校验/渲染/投递（http 或 smtp，凭证只读环境变量）
 │     └─ api.js                 # 同源 HTTP API、确认 token、限流
-└─ test/                        # 104 个用例，覆盖用户要求的 5 类场景 + live 删除 + 记忆锁 + 原地刷新 + 部分失败/跨进程/未完成条目 + Client 半渲染冒烟
+└─ test/                        # 121 个用例，覆盖用户要求的 5 类场景 + live 删除 + 记忆锁 + 原地刷新 + 部分失败/跨进程/未完成条目 + 反馈通道 + Client 半渲染冒烟
 ```
 
 ---
@@ -198,7 +199,7 @@ dsh-conversation-recycle-bin/
 
 ```powershell
 cd D:\Users\34332\AI\dsh-conversation-recycle-bin
-npm test        # = manifest && client-module && core && cascade && memory && trash-audit && api（104 个用例）
+npm test        # = manifest && client-module && core && cascade && memory && trash-audit && feedback && api（121 个用例）
 npm run check   # 语法 + manifest
 ```
 
@@ -226,3 +227,87 @@ npm run check   # 语法 + manifest
 5. UI 依赖当前版本的 slot 约定；宿主升级若改 slot props，入口会失效但不会破坏宿主。0.1.4 的原地刷新还会调用 `uiWorkspace.clearArchivedCurrent/clearMain`（宿主 `.d.ts` 中标为 private）；两者都不存在时会退回整页刷新，不会留下过期视图，但属于对私有方法的依赖，宿主升级需复核。
 6. 回收站 manifest 的并发写由 `<dataDir>/mutation.lock` 跨进程锁保护（抢不到锁返回 `E_LOCK_BUSY`）；但**会话日志内容**的跨进程写保护仍是 best-effort：`foreignWriterGraceMs` 只能发现"窗口内仍在增长"的日志，另一个 Host 的空闲 live 会话（两次写入之间）无法被本进程识别。桌面端与 `dsh web` 同时运行时，仍应先关闭另一端的会话再彻底删除。
 7. 未完成条目（failed/pending/restoring/purging）若仍持有已移动的会话日志或记忆文件，出于数据安全不允许 `discard`（会报 `E_TRASH_CONFLICT`）；设置页对这类条目提供「恢复」按钮，可直接恢复回会话列表，不再出现"失败了却没有出口"的死条目。日志与记忆都已不在磁盘上的条目才可以 discard。
+
+---
+
+## 9. 反馈通道（设置页「反馈」按钮）
+
+设置页**最上方**新增一条「反馈」横幅（主色按钮，位于标题之上）：把问题或建议写成一条消息，由**宿主进程**通过邮件发到维护者邮箱。凭证只在宿主侧读取，页面拿不到、也发不出任何邮件。
+
+### 9.1 为什么是「页面 → 宿主路由 → 邮件」三段
+
+浏览器既不能开 SMTP 连接，也不该持有邮件服务凭证。因此 `client.js` 只负责表单与校验提示，`POST /conversation-recycle-bin/api/feedback` 由 `lib/host/feedback.js` 校验、渲染并投递。表单里的「类型 / 标题 / 正文 / 联系方式」之外，只额外附带**对话框里已展示给用户**的上下文（插件版本、平台、语言）；对话内容、会话 id、工作区路径都不会进入邮件。
+
+### 9.2 配置项（`feedback` 段，非机密）
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `feedback.enabled` | `true` | 是否允许该通道。通道本身没配好时按钮依旧不显示 |
+| `feedback.to` | `b64:…`（维护者收件箱） | 收件人。默认值以 `b64:<base64>` 形式携带，公开 tarball 里没有可直接抓取的 `name@domain` 串（这是**混淆，不是加密**：解码器就在 `lib/host/feedback.js`，拿到包的人总能解出来）。也接受明文地址；`DSH_CRB_FEEDBACK_TO` 优先于它 |
+| `feedback.from` | `''` | 发件人。留空时 SMTP 通道复用连接串里的用户名（服务商通常要求 From 与登录账号一致）；`DSH_CRB_FEEDBACK_FROM` 优先于它 |
+| `feedback.transport` | `auto` | `auto` = 有 `DSH_CRB_MAIL_API_URL` 走 http，否则有 `DSH_CRB_SMTP_URL` 走 smtp；`http`/`smtp` 强制单通道（配不全就报未配置，不会静默换道）；`off` 关闭 |
+| `feedback.rateLimitPerHour` | `5` | 每宿主每小时发送上限（1–100）。邮件从操作者自己的账号发出，默认值刻意压低 |
+
+### 9.3 环境变量（优先级高于配置项；凭证只走这里，不进配置文件）
+
+> 冲突时**环境变量赢**：`DSH_CRB_FEEDBACK_TO` 覆盖 `feedback.to`，`DSH_CRB_FEEDBACK_FROM` 覆盖 `feedback.from`。这样多台机器/多人共用一个 package 时，各自改环境变量即可，不必改配置。
+
+| 变量 | 用途 |
+|---|---|
+| `DSH_CRB_FEEDBACK_TO` | 收件人（优先于 `feedback.to`） |
+| `DSH_CRB_FEEDBACK_FROM` | 发件人（优先于 `feedback.from`） |
+| `DSH_CRB_MAIL_API_URL` | 邮件 HTTP API 地址（Resend 兼容形状，也可指向自建转发网关） |
+| `DSH_CRB_MAIL_API_TOKEN` | 该 API 的 Bearer token |
+| `DSH_CRB_MAIL_API_AUTH_HEADER` | 可选，鉴权头名，默认 `authorization`，值为 `Bearer <token>` |
+| `DSH_CRB_SMTP_URL` | SMTP 连接串，如 `smtps://user:pass@smtp.example.com:465` |
+
+HTTP 通道发出的 JSON 固定为 `{from, to: [收件人], subject, text, reply_to}`，`text` 是纯文本（不生成 HTML）；`reply_to` 只在联系方式看起来可用时填写。SMTP 通道按需 `import('nodemailer')`：它已声明为 `optionalDependencies`（`^10.1.2`），正常安装会随包就位；以 `link:` 方式开发安装时插件从自身真实目录解析，需在**本仓库**跑一次 `npm install`。仍未安装时返回 `E_FEEDBACK_TRANSPORT` + `reason: nodemailer-missing`。
+
+#### 9.3.1 QQ 邮箱开通示例
+
+QQ 邮箱不能直接用登录密码发信，要先取**授权码**（设置 → 账号 → POP3/SMTP 服务 → 开启 → 生成授权码），再把两件事写进环境变量（`@` 在连接串里必须写成 `%40`；`<你的QQ号>` 换成实际号码）：
+
+```powershell
+setx DSH_CRB_SMTP_URL 'smtps://<你的QQ号>%40qq.com:你的授权码@smtp.qq.com:465'
+# 可选：换收件人/发件人（不设就用包内默认的维护者收件箱）
+setx DSH_CRB_FEEDBACK_TO 'your-feedback@example.com'
+# 设置后重启 DSH 桌面端（setx 只对新进程生效）
+```
+
+需要自己生成一个 `b64:` 地址（放进 profile patch 而不是环境变量时）：
+
+```powershell
+node -e "console.log('b64:' + Buffer.from('your-feedback@example.com','utf8').toString('base64'))"
+```
+
+
+### 9.4 本地验证
+
+```powershell
+cd D:\Users\34332\AI\dsh-conversation-recycle-bin
+npm run check                      # 语法 + manifest（含 feedback.js）
+node test/feedback.test.mjs        # 15 个反馈用例
+npm test                           # 全量 121 个用例
+
+# 端到端：用本机收件桩观察真实投递路径，不外发邮件
+$env:DSH_CRB_MAIL_API_URL   = 'http://127.0.0.1:9099/emails'
+$env:DSH_CRB_MAIL_API_TOKEN = 'dev-token'
+$env:DSH_CRB_FEEDBACK_TO    = 'feedback@example.test'
+# 另一个终端起桩：
+# node -e "require('http').createServer((q,s)=>{let b='';q.on('data',c=>b+=c);q.on('end',()=>{console.log(q.method,q.url,b);s.end('{}')})}).listen(9099)"
+```
+
+起桩后打开设置页点「反馈」，填表发送：桩终端应打印 `POST /emails {...}`，页面出现「反馈已发送，谢谢！」。测 SMTP 通路时改设 `DSH_CRB_SMTP_URL`（本仓库已按 `optionalDependencies` 声明 `nodemailer`，先在本仓库 `npm install` 一次；未安装时返回 `E_FEEDBACK_TRANSPORT` + `reason: nodemailer-missing`，这是预期行为）。
+
+### 9.5 失败排查
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 设置页没有「反馈」按钮 | 通道未配置（`/state.feedback.enabled === false`） | 设好 `DSH_CRB_MAIL_API_URL` + token，或 `DSH_CRB_SMTP_URL`；确认 `feedback.transport` 不是 `off`、`enabled` 不是 `false` |
+| 点击后 503 `E_FEEDBACK_DISABLED` | 同上一行（按钮来自旧页面渲染） | 刷新页面；看 `/state.feedback.reason`：`not-configured` / `disabled` / `off` |
+| 400 `E_FEEDBACK_INVALID` | 标题 4–120 字、正文 10–4000 字、联系方式 ≤200 字不满足 | `details.field` 指明字段，`details.min`/`details.max` 给出边界 |
+| 429 `E_FEEDBACK_RATE_LIMITED` | 超过 `feedback.rateLimitPerHour` | 等 `details.retryAfterMs` 后重试，或调高上限 |
+| 502 `E_FEEDBACK_TRANSPORT` | 邮件服务返回非 2xx / 网络失败 / 未装 nodemailer / 暴露不出 `createTransport` | 看宿主日志 `[conversation-recycle-bin] feedback delivery failed (<transport>): <code> <message>`（只含错误码与通道，不含正文）；核对 URL、token、SMTP 授权码 |
+| 接口 200 但收件箱没有 | 服务端已受理，但被对方退信或进了垃圾箱 | 查发件账号退信；`feedback.from` 用与 SMTP 账号一致的地址，并检查收件人域名 |
+
+> 隐私边界：邮件正文 = 用户输入 + 对话框里已展示的上下文；宿主日志只记错误码、通道与耗时。删除开关（`enabled`）与反馈通道互相独立——关掉删除不影响反馈，反之亦然。

package/client.js

@@ -147,6 +147,36 @@ window.__ModuleLoader__.load({
         'state.unavailable': 'unavailable',
         'state.rate': '{used}/{limit} deletions this minute',
         'state.batch': 'Effective batch limit: {limit}',
+        'feedback.button': 'Feedback',
+        'feedback.bannerTitle': 'Ran into a problem or have an idea?',
+        'feedback.bannerHint': 'Send one email to the maintainer. It carries your text plus the plugin version, platform and language — no conversation content.',
+        'feedback.title': 'Send feedback',
+        'feedback.intro': 'Tell the maintainer what went wrong or what you would like to see. The message is sent by email from this Host; nothing is uploaded anywhere else.',
+        'feedback.categoryLabel': 'Type',
+        'feedback.categoryBug': 'Problem / bug',
+        'feedback.categorySuggestion': 'Suggestion',
+        'feedback.categoryOther': 'Other',
+        'feedback.titleLabel': 'Title',
+        'feedback.titlePlaceholder': 'One line that summarises it',
+        'feedback.bodyLabel': 'Message',
+        'feedback.bodyPlaceholder': 'What happened, what you expected, and the steps that led to it.',
+        'feedback.contactLabel': 'Contact (optional)',
+        'feedback.contactPlaceholder': 'An email address or another way to reach you',
+        'feedback.contextLabel': 'Attached automatically',
+        'feedback.contextHint': 'Plugin version, platform and language. Conversation content is never attached.',
+        'feedback.send': 'Send',
+        'feedback.sending': 'Sending…',
+        'feedback.sent': 'Feedback sent. Thank you!',
+        'feedback.tooShortTitle': 'The title needs at least {min} characters.',
+        'feedback.tooLongTitle': 'The title may be at most {max} characters.',
+        'feedback.tooShortBody': 'The message needs at least {min} characters.',
+        'feedback.tooLongBody': 'The message may be at most {max} characters.',
+        'feedback.tooLongContact': 'The contact field may be at most {max} characters.',
+        'feedback.unavailable': 'The feedback channel is not configured on this Host.',
+        'error.E_FEEDBACK_DISABLED': 'The feedback channel is not configured on this Host.',
+        'error.E_FEEDBACK_INVALID': 'The feedback form is incomplete or too long.',
+        'error.E_FEEDBACK_RATE_LIMITED': 'Several messages were sent recently; try again a little later.',
+        'error.E_FEEDBACK_TRANSPORT': 'The message could not be delivered. Check the Host mail configuration and retry.',
         'error.E_CONFIRM_PHRASE': 'The confirmation phrase does not match.',
         'error.E_CONFIRM_EXPIRED': 'The confirmation expired; the counts were reloaded.',
         'error.E_CONFIRM_INVALID': 'The confirmation is stale; the plan was reloaded.',
@@ -263,6 +293,36 @@ window.__ModuleLoader__.load({
         'state.unavailable': '不可用',
         'state.rate': '本分钟已删除 {used}/{limit}',
         'state.batch': '单次上限：{limit} 个（受每分钟额度约束）',
+        'feedback.button': '反馈',
+        'feedback.bannerTitle': '遇到问题，或有改进建议？',
+        'feedback.bannerHint': '写一条消息发给维护者，正文之外只附带插件版本、平台与语言，不含任何对话内容。',
+        'feedback.title': '发送反馈',
+        'feedback.intro': '把遇到的问题或想要的功能告诉维护者。消息由本机宿主通过邮件发送，不会上传到其他位置。',
+        'feedback.categoryLabel': '类型',
+        'feedback.categoryBug': '问题 / Bug',
+        'feedback.categorySuggestion': '建议',
+        'feedback.categoryOther': '其他',
+        'feedback.titleLabel': '标题',
+        'feedback.titlePlaceholder': '用一句话概括',
+        'feedback.bodyLabel': '正文',
+        'feedback.bodyPlaceholder': '发生了什么、预期是什么、如何复现。',
+        'feedback.contactLabel': '联系方式（选填）',
+        'feedback.contactPlaceholder': '邮箱或其他能找到你的方式',
+        'feedback.contextLabel': '自动附带',
+        'feedback.contextHint': '插件版本、平台与语言；不会附带任何对话内容。',
+        'feedback.send': '发送',
+        'feedback.sending': '正在发送…',
+        'feedback.sent': '反馈已发送，谢谢！',
+        'feedback.tooShortTitle': '标题至少需要 {min} 个字符。',
+        'feedback.tooLongTitle': '标题最多 {max} 个字符。',
+        'feedback.tooShortBody': '正文至少需要 {min} 个字符。',
+        'feedback.tooLongBody': '正文最多 {max} 个字符。',
+        'feedback.tooLongContact': '联系方式最多 {max} 个字符。',
+        'feedback.unavailable': '当前宿主未配置反馈通道。',
+        'error.E_FEEDBACK_DISABLED': '当前宿主未配置反馈通道。',
+        'error.E_FEEDBACK_INVALID': '反馈内容不完整或超出长度限制。',
+        'error.E_FEEDBACK_RATE_LIMITED': '最近已发送多条反馈，请稍后再试。',
+        'error.E_FEEDBACK_TRANSPORT': '邮件发送失败，请检查宿主的邮件配置后重试。',
         'error.E_CONFIRM_PHRASE': '确认短语不匹配。',
         'error.E_CONFIRM_EXPIRED': '确认已过期；计数已重新加载。',
         'error.E_CONFIRM_INVALID': '确认已失效；计划已重新加载。',
@@ -696,6 +756,16 @@ window.__ModuleLoader__.load({
       h('path', { d: 'M20 4v5h-5' }))
     }
 
+    function GlyphFeedback({ size = 14 }) {
+      return h('svg', {
+        width: size, height: size, viewBox: '0 0 24 24', fill: 'none',
+        stroke: 'currentColor', strokeWidth: 1.8, strokeLinecap: 'round', strokeLinejoin: 'round',
+        'aria-hidden': 'true',
+      },
+      h('path', { d: 'M4 6h16a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1Z' }),
+      h('path', { d: 'm3.5 7 8.5 6 8.5-6' }))
+    }
+
     function Button({ children, onClick, variant = 'secondary', disabled = false, type = 'button', title }) {
       return h('button', {
         type,
@@ -746,6 +816,48 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /* ------------------------------------------------------------------ *
+     * Feedback form (pure helpers, shared with the Host's validation)
+     * ------------------------------------------------------------------ */
+
+    // Mirrors FEEDBACK_LIMITS in `lib/host/feedback.js`. The Host re-validates
+    // every field; this copy only exists to disable the submit button early and
+    // to point at the offending input.
+    const FEEDBACK_LIMITS = Object.freeze({
+      titleMin: 4,
+      titleMax: 120,
+      bodyMin: 10,
+      bodyMax: 4_000,
+      contactMax: 200,
+    })
+
+    /**
+     * @param {{title?: string, body?: string, contact?: string}} input
+     * @returns {{ok: true} | {ok: false, key: string, vars: Record<string, number>}}
+     */
+    function validateFeedbackInput(input) {
+      const title = String(input?.title ?? '').trim()
+      const body = String(input?.body ?? '').trim()
+      const contact = String(input?.contact ?? '').trim()
+      if (title.length < FEEDBACK_LIMITS.titleMin) return { ok: false, key: 'feedback.tooShortTitle', vars: { min: FEEDBACK_LIMITS.titleMin } }
+      if (title.length > FEEDBACK_LIMITS.titleMax) return { ok: false, key: 'feedback.tooLongTitle', vars: { max: FEEDBACK_LIMITS.titleMax } }
+      if (body.length < FEEDBACK_LIMITS.bodyMin) return { ok: false, key: 'feedback.tooShortBody', vars: { min: FEEDBACK_LIMITS.bodyMin } }
+      if (body.length > FEEDBACK_LIMITS.bodyMax) return { ok: false, key: 'feedback.tooLongBody', vars: { max: FEEDBACK_LIMITS.bodyMax } }
+      if (contact.length > FEEDBACK_LIMITS.contactMax) return { ok: false, key: 'feedback.tooLongContact', vars: { max: FEEDBACK_LIMITS.contactMax } }
+      return { ok: true }
+    }
+
+    /** Context the dialog shows before sending; nothing here is user content. */
+    function collectFeedbackContext() {
+      const userAgent = typeof navigator !== 'undefined' && typeof navigator.userAgent === 'string'
+        ? navigator.userAgent
+        : ''
+      return {
+        platform: userAgent.slice(0, 160),
+        locale: currentLocaleId(),
+      }
+    }
+
     /* ------------------------------------------------------------------ *
      * Confirmation dialog
      * ------------------------------------------------------------------ */
@@ -994,6 +1106,155 @@ window.__ModuleLoader__.load({
       return store === undefined ? 'not detected' : adapterReason(store.reason)
     }
 
+    /* ------------------------------------------------------------------ *
+     * Feedback dialog
+     * ------------------------------------------------------------------ */
+
+    /**
+     * Settings page "反馈" button.
+     *
+     * The Host performs the delivery, so the page never holds a mail
+     * credential. The auto-attached context is rendered BEFORE the user
+     * commits, so nothing leaves the machine that they did not see.
+     */
+    function FeedbackDialog({ payload }) {
+      useLocaleTick()
+      const feedback = payload?.feedback ?? null
+      const version = typeof payload?.version === 'string' ? payload.version : ''
+      const [category, setCategory] = useState('bug')
+      const [title, setTitle] = useState('')
+      const [body, setBody] = useState('')
+      const [contact, setContact] = useState('')
+      const [busy, setBusy] = useState(false)
+      const [error, setError] = useState(null)
+      const validation = validateFeedbackInput({ title, body, contact })
+      const context = collectFeedbackContext()
+      // A Host without a mail transport advertises `enabled: false`; the form is
+      // still rendered read-only so the explanation is visible instead of a
+      // button that fails on click.
+      const unavailable = feedback?.enabled !== true
+
+      useEffect(() => {
+        function onKey(event) {
+          if (event.key === 'Escape' && busy !== true) dialogStore.close()
+        }
+        window.addEventListener('keydown', onKey)
+        return () => window.removeEventListener('keydown', onKey)
+      }, [busy])
+
+      async function submit() {
+        if (busy || unavailable || validation.ok !== true) return
+        setBusy(true)
+        setError(null)
+        try {
+          await api('/feedback', {
+            method: 'POST',
+            timeoutMs: 30_000,
+            body: {
+              category,
+              title: title.trim(),
+              body: body.trim(),
+              contact: contact.trim(),
+              context: {
+                pluginVersion: version,
+                platform: context.platform,
+                locale: context.locale,
+              },
+            },
+          })
+          flashStore.show(t('feedback.sent'))
+          dialogStore.close()
+        } catch (caught) {
+          // The Host log already records the stable code; this keeps the form
+          // path debuggable from the browser console without a network tab.
+          console.error('[conversation-recycle-bin] feedback submission failed:', caught?.code ?? caught)
+          setError(caught)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      return h('div', {
+        className: 'dc-backdrop',
+        onMouseDown: (event) => {
+          if (event.target === event.currentTarget && busy !== true) dialogStore.close()
+        },
+      },
+      h('div', { className: 'dc-dialog', role: 'dialog', 'aria-modal': 'true', 'aria-labelledby': 'dc-feedback-title' },
+        h('h2', { id: 'dc-feedback-title', className: 'dc-dialog-title' }, t('feedback.title')),
+        h('p', { className: 'dc-dialog-body' }, t('feedback.intro')),
+        unavailable ? h('div', { className: 'dc-error', role: 'alert' }, t('feedback.unavailable')) : null,
+        h(ErrorBanner, { error }),
+
+        h('label', { className: 'dc-field' },
+          h('span', { className: 'dc-field-label' }, t('feedback.categoryLabel')),
+          h('select', {
+            className: 'dc-input',
+            value: category,
+            disabled: busy,
+            onChange: (event) => setCategory(event.target.value),
+          },
+          h('option', { value: 'bug' }, t('feedback.categoryBug')),
+          h('option', { value: 'suggestion' }, t('feedback.categorySuggestion')),
+          h('option', { value: 'other' }, t('feedback.categoryOther')))),
+
+        h('label', { className: 'dc-field' },
+          h('span', { className: 'dc-field-label' }, t('feedback.titleLabel')),
+          h('input', {
+            type: 'text',
+            className: 'dc-input',
+            value: title,
+            maxLength: FEEDBACK_LIMITS.titleMax,
+            placeholder: t('feedback.titlePlaceholder'),
+            disabled: busy,
+            autoFocus: true,
+            onChange: (event) => setTitle(event.target.value),
+          })),
+
+        h('label', { className: 'dc-field' },
+          h('span', { className: 'dc-field-label' }, t('feedback.bodyLabel')),
+          h('textarea', {
+            className: 'dc-input dc-textarea',
+            value: body,
+            rows: 6,
+            maxLength: FEEDBACK_LIMITS.bodyMax,
+            placeholder: t('feedback.bodyPlaceholder'),
+            disabled: busy,
+            onChange: (event) => setBody(event.target.value),
+          })),
+
+        h('label', { className: 'dc-field' },
+          h('span', { className: 'dc-field-label' }, t('feedback.contactLabel')),
+          h('input', {
+            type: 'text',
+            className: 'dc-input',
+            value: contact,
+            maxLength: FEEDBACK_LIMITS.contactMax,
+            placeholder: t('feedback.contactPlaceholder'),
+            disabled: busy,
+            onChange: (event) => setContact(event.target.value),
+          })),
+
+        h('div', { className: 'dc-context' },
+          h('div', { className: 'dc-context-title' }, t('feedback.contextLabel')),
+          h('div', { className: 'dc-hint' }, t('feedback.contextHint')),
+          h('ul', { className: 'dc-context-list' },
+            h('li', null, `plugin: ${version === '' ? '—' : version}`),
+            h('li', null, `platform: ${context.platform === '' ? '—' : context.platform}`),
+            h('li', null, `locale: ${context.locale}`))),
+
+        validation.ok !== true ? h('div', { className: 'dc-hint' }, t(validation.key, validation.vars)) : null,
+        busy ? h(Spinner, { label: t('feedback.sending') }) : null,
+
+        h('div', { className: 'dc-actions' },
+          h(Button, { onClick: () => dialogStore.close(), disabled: busy }, t('action.cancel')),
+          h(Button, {
+            variant: 'primary',
+            onClick: () => { void submit() },
+            disabled: busy || unavailable || validation.ok !== true,
+          }, busy ? t('feedback.sending') : t('feedback.send')))))
+    }
+
     /* ------------------------------------------------------------------ *
      * Dialog host / overlay entry
      * ------------------------------------------------------------------ */
@@ -1014,8 +1275,15 @@ window.__ModuleLoader__.load({
     function DialogHost() {
       const payload = useDialogState()
       const flash = useFlashMessage()
+      // `kind` is optional: every pre-0.2.2 caller opens a delete dialog, so a
+      // payload without a kind keeps its old meaning.
+      const dialog = payload === null
+        ? null
+        : payload.kind === 'feedback'
+          ? h(FeedbackDialog, { payload, key: payload.key ?? 'feedback' })
+          : h(DeleteDialog, { payload, key: payload.key ?? (payload.sessionIds ?? []).join(',') })
       const content = h(React.Fragment, null,
-        payload === null ? null : h(DeleteDialog, { payload, key: payload.key ?? payload.sessionIds.join(',') }),
+        dialog,
         flash === null ? null : h('div', { className: 'dc-toast', role: 'status' }, flash))
       return portalIntoBody(content)
     }
@@ -1294,13 +1562,34 @@ window.__ModuleLoader__.load({
         : (state?.limits?.maxBatchSessions ?? 0)
       const overLimit = effectiveBatch > 0 && selectedIds.length > effectiveBatch
 
+      const openFeedback = () => dialogStore.open({
+        kind: 'feedback',
+        key: 'feedback',
+        version: typeof state?.version === 'string' ? state.version : '',
+        feedback: state?.feedback ?? null,
+      })
+
       return h('div', { className: 'dc-root' },
+        // Top-of-section call to action, above the title: it is the first thing
+        // a user unsure about the plugin should see. Rendered only when the Host
+        // reports a configured transport, so a profile without mail settings
+        // never shows a button that cannot work (the dialog would otherwise
+        // explain a failure to send).
+        state?.feedback?.enabled === true
+          ? h('div', { className: 'dc-feedback-bar' },
+            h('div', { className: 'dc-feedback-bar-text' },
+              h('div', { className: 'dc-feedback-bar-title' }, t('feedback.bannerTitle')),
+              h('div', { className: 'dc-feedback-bar-hint' }, t('feedback.bannerHint'))),
+            h(Button, { variant: 'primary', title: t('feedback.button'), onClick: openFeedback },
+              h(GlyphFeedback, { size: 14 }), ' ', t('feedback.button')))
+          : null,
         h('div', { className: 'dc-header' },
           h('div', null,
             h('h1', { className: 'dc-title' }, t('section.title')),
             h('p', { className: 'dc-hint' }, t('section.subtitle'))),
-          h(Button, { onClick: () => { void refresh() }, disabled: loading, title: t('action.refresh') },
-            h(GlyphRefresh, { size: 13 }), ' ', t('action.refresh'))),
+          h('div', { className: 'dc-header-actions' },
+            h(Button, { onClick: () => { void refresh() }, disabled: loading, title: t('action.refresh') },
+              h(GlyphRefresh, { size: 13 }), ' ', t('action.refresh')))),
 
         h(ErrorBanner, { error }),
 
@@ -1436,6 +1725,13 @@ window.__ModuleLoader__.load({
 .dc-phrase-label{display:block;font-size:12px;color:var(--dsw-alias-state-warn-primary,#d46b08);margin-bottom:5px;line-height:1.5}
 .dc-input{width:100%;box-sizing:border-box;height:32px;padding:0 9px;border:1px solid var(--dsw-alias-border-l2,#c9cdd4);border-radius:7px;background:var(--dsw-alias-bg-base,#fff);color:inherit;font:inherit;font-size:13px}
 .dc-input-small{width:90px;height:28px}
+.dc-header-actions{display:flex;gap:8px;align-items:center;flex-wrap:wrap;justify-content:flex-end}
+.dc-field{display:flex;flex-direction:column;gap:5px;margin:10px 0}
+.dc-field-label{font-size:12px;font-weight:600;color:var(--dsw-alias-label-primary,#1f2329)}
+.dc-textarea{height:auto;min-height:96px;padding:8px 9px;line-height:1.55;resize:vertical}
+.dc-context{margin:12px 0 4px;padding:9px 10px;border:1px solid var(--dsw-alias-border-l1,#e5e6eb);border-radius:8px;background:var(--dsw-alias-bg-layer-1,#f7f8fa)}
+.dc-context-title{font-size:12px;font-weight:600;margin-bottom:2px}
+.dc-context-list{margin:6px 0 0;padding-left:16px;font-size:11px;line-height:1.7;color:var(--dsw-alias-label-secondary,#646a73);word-break:break-all}
 .dc-actions{display:flex;gap:8px;justify-content:flex-end;align-items:center;margin-top:14px;flex-wrap:wrap}
 .dc-btn{height:30px;padding:0 12px;border-radius:7px;border:1px solid var(--dsw-alias-border-l2,#c9cdd4);background:var(--dsw-alias-bg-layer-1,#f7f8fa);color:var(--dsw-alias-label-primary,#1f2329);font:inherit;font-size:12px;cursor:pointer;display:inline-flex;align-items:center;gap:5px}
 .dc-btn:hover:not(:disabled){background:var(--dsw-alias-bg-layer-2,#eff0f2)}
@@ -1459,6 +1755,10 @@ window.__ModuleLoader__.load({
 .dc-header-action{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border:0;border-radius:7px;background:transparent;color:var(--dsw-alias-label-secondary,#646a73);cursor:pointer}
 .dc-header-action:hover{background:var(--dsw-alias-bg-layer-2,#eff0f2);color:var(--dsw-alias-state-error-primary,#d93026)}
 .dc-root{padding:18px 22px 32px;max-width:900px;font:inherit;color:var(--dsw-alias-label-primary,#1f2329)}
+.dc-feedback-bar{display:flex;align-items:center;justify-content:space-between;gap:16px;flex-wrap:wrap;padding:12px 14px;margin-bottom:16px;border:1px solid var(--dsw-alias-brand-primary,#4d6bfe);border-radius:10px;background:var(--dsw-alias-bg-layer-1,#f7f8fa)}
+.dc-feedback-bar-text{min-width:220px;flex:1 1 auto}
+.dc-feedback-bar-title{font-size:13px;font-weight:600;line-height:1.5}
+.dc-feedback-bar-hint{font-size:12px;color:var(--dsw-alias-label-secondary,#646a73);line-height:1.5;margin-top:2px}
 .dc-header{display:flex;justify-content:space-between;align-items:flex-start;gap:16px;margin-bottom:14px}
 .dc-title{font-size:17px;font-weight:600;margin:0}
 .dc-state{display:flex;gap:24px;flex-wrap:wrap;padding:10px 12px;border:1px solid var(--dsw-alias-border-l1,#e5e6eb);border-radius:9px;background:var(--dsw-alias-bg-layer-1,#f7f8fa);margin-bottom:14px}
@@ -1565,7 +1865,9 @@ window.__ModuleLoader__.load({
     exports.__api = api
     // Direct component handles keep the hook-level behavior testable without a
     // DOM renderer (the registered wrapper alone only builds an element).
-    exports.__components = { DeleteMenuRow, HeaderDeleteAction, DeleteDialog, SettingsSection, IncompleteEntries, BatchSessionRow }
+    exports.__components = { DeleteMenuRow, HeaderDeleteAction, DeleteDialog, SettingsSection, IncompleteEntries, BatchSessionRow, FeedbackDialog }
+    exports.__validateFeedbackInput = validateFeedbackInput
+    exports.__feedbackLimits = FEEDBACK_LIMITS
     exports.__selectableSessionIds = selectableSessionIds
     exports.__adapterLabel = adapterLabel
     exports.__adapterReason = adapterReason

package/config.schema.json

@@ -68,6 +68,18 @@
         "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." }
+      }
     }
   }
 }

package/cordis.patch.yml

@@ -71,3 +71,19 @@
           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

package/lib/core/config.js

@@ -47,11 +47,27 @@ 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,
+  },
 })
 
 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 +117,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 +166,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 +225,16 @@ 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),
+    },
   }
 
   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,400 @@
+/**
+ * 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, contact 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,
+  contactMax: 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()
+}
+
+/**
+ * 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}}} [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 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 }
+}
+
+/**
+ * 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
+  }
+}
+
+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, contact: 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 contact = singleLine(source.contact)
+
+  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 (contact.length > FEEDBACK_LIMITS.contactMax) {
+    throw new DeleteError('E_FEEDBACK_INVALID', 'The contact field is too long.', {
+      field: 'contact', max: FEEDBACK_LIMITS.contactMax,
+    })
+  }
+
+  return {
+    category,
+    title,
+    body,
+    contact: contact === '' ? null : contact,
+    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,
+    `  contact: ${submission.contact ?? '(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 !== '',
+      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.contact ?? 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: smtpSender(settings),
+        to: settings.to,
+        subject: message.subject,
+        text: message.text,
+        replyTo: submission.contact ?? 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 contact 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.0'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-conversation-recycle-bin",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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,