dsh-email 0.14.7 → 0.15.0

package/CHANGELOG.md

@@ -1,20 +1,32 @@
-# Changelog
+# 更新记录
 
-## 0.14.7（2026-10-02）
+[返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
+
+[历史英文记录](docs/CHANGELOG.en.md)
+
+## 0.15.0 (2026-10-03)
+
+- 新增 email_draft 和本地草稿工作台，支持编辑 To/Cc、发件账号、正文、附件上传与预览下载，再明确确认发送。
+- 发送使用已预览的附件字节；草稿版本冲突、账号或规则变化、重复确认均被拦截。结果不明时先核对邮箱，不自动重发；回执列明接受与拒绝的地址。
+- 新增按账号保存的可信地址/域名规则和匹配预览。全部 To/Cc 匹配且主动启用后才跳过 email_send 的插件确认；回复、宿主权限和草稿手动确认保留。
+- 关闭设置可恢复当前会话中未保存的编辑；修复窄屏侧栏挤压和自定义服务器账号被误标为未完成。
+- 验证范围详见 [0.15.0 验收](docs/validation/0.15.0.md)。
+
+## 0.14.7 (2026-10-02)
 
 - Fix account cards displaying preset endpoints instead of explicitly configured servers; refresh the summary after saves and provider changes without persisting projections.
 - Upgrade ImapFlow, Mailparser, Nodemailer and the transitive IP address parser; use Nodemailer's bundled types.
 - Handle missing IMAP messages, empty searches and missing attachment streams with explicit recovery errors.
 - Add regression coverage for endpoint display and empty IMAP responses. Windows: 304 tests; production dependency audit: 0 findings.
 
-## 0.14.6（2026-10-02）
+## 0.14.6 (2026-10-02)
 
 - 完成 [PR #18](https://github.com/STARDUSTLC666/dsh-email/pull/18) 的兼容合并：未修改的表单端点不再产出空对象，避免旧设置和不完整草稿覆盖配置文件里手动填写的 IMAP/SMTP 服务器。
 - 保留 0.14.2 的共享端点归一化规则：Outlook 使用 587/STARTTLS；不含占位 host 的显式 465/TLS 设置、已修改的端口组合和新版 Harness 配置保持有效。
 - 新增旧设置运行时和不完整草稿的服务器保留回归，感谢 SenkjM 提供修复方向。
 - Windows / Node 24.16.0 下 297 项邮件测试通过；两项新增回归在修复前失败、修复后通过。未进行真实邮箱授权或 SMTP 投递验收。
 
-## 0.14.5（2026-10-01）
+## 0.14.5 (2026-10-01)
 
 - 修复 [#20](https://github.com/STARDUSTLC666/dsh-email/issues/20)：具名账号的服务商预设不再被顶层共享服务器遮蔽；Gmail 不再因继承 Outlook 端点被误判为 OAuth2。保留账号显式端点、传输超时和旧单账号继承规则。
 - 账号映射转换为卡片时沿用相同端点规则；新版设置服务保存卡片时排除表单派生的共享 imap/smtp，避免修改 Outlook 后改变其他账号的连接。
@@ -23,59 +35,98 @@
 - 空地址卡片点击测试时先提示填写邮箱地址，不再测试隐藏表单中的旧凭据；保存后及时更新 Outlook 内置应用 ID 和独立登录密码的提示。
 - Windows 下新增十项行为回归，整套邮件 295 项通过；官方 Harness 0.2.0-rc.2 源码构建及 18 插件同载检查通过。原生桌面已实测新增卡片、服务商切换、自动保存与删除；最后的字段提示修正有组件行为回归，尚未再次实机操作。未验证真实邮箱登录、OAuth2 授权或发信成功。
 
-## 0.14.4（2026-09-29）
+## 0.14.4 (2026-09-29)
 
 - 修复：SMTP 发送改为**每次发送独占连接**，取消（AbortSignal）时只销毁本次连接的 socket 并立即拒绝，不再影响同账号的其它发送，也不会在取消后仍把邮件发出去。
 - 修复：OAuth2 令牌刷新与取消的竞态——取消后即使令牌刷新成功也不再继续发送。
 - 测试：修正 TLS fixture 的两处握手缺陷（STARTTLS 明文阶段未发送 220；取消用例把 greeting 压住导致走不到 TLS 升级），TLS 与取消回归现可稳定通过（285 项）。
-## 0.14.3（2026-09-28）
+
+## 0.14.3 (2026-09-28)
 
 - 兼容验证更新到 Harness 0.2.0-rc.1：282 项邮件测试与 18 插件共同加载检查通过。
 - 运行时代码未变；同步中英文兼容性声明。
 
-## 0.14.2（2026-09-28）
+## 0.14.2 (2026-09-28)
 
 - 修复 [#17](https://github.com/STARDUSTLC666/dsh-email/issues/17)：空主机配合未修改的表单默认端口/TLS 不再覆盖服务商预设；Outlook 恢复 587/STARTTLS。旧设置转换和 Harness 0.1.7 已迁移配置共用归一化规则，保留自定义主机、非默认组合和不含占位 host 的显式端口覆盖。
 - 感谢 [SenkjM 的 PR #18](https://github.com/STARDUSTLC666/dsh-email/pull/18) 提供复现与修复方向。本次补齐新版运行时路径并避免误删明确的端口设置；282 项邮件测试通过。配置和界面验证不代表真实 SMTP 投递已验证。
 
-## 0.14.1（2026-09-27）
+## 0.14.1 (2026-09-27)
 
 - 未补全的账号和服务器预设会显示未保存提示；避免草稿丢失和错误的“已保存”状态。测试连接只校验所选账号，错误直接指向设置页中的对应字段。
 
-> 完整历史（含详细改动说明）。README 只保留最近几个版本的一句话摘要。
-
-## 中文版
-
-- **0.13.2（2026-09-21）**：同名附件优先按真实 MIME 分段编号下载；旧解析元数据按一对一匹配，避免多个序号都取到第一个同名文件。保留正文分段下载和附件索引缓存，新增文件字节级回归，268 项测试通过。
-- **0.13.1（2026-09-19）**：**新增**：内置一份公共客户端注册（`15dcd5aa-…`，贡献者 [gurio-wine](https://github.com/gurio-wine) 在 [PR #13](https://github.com/STARDUSTLC666/dsh-email/pull/13) 注册，并授权本项目内置使用，特此致谢）——Outlook / Exchange Online 的 OAuth2 登录**开箱即用**，不再需要每个用户自己注册应用。设置页卡片会显示当前生效的应用 ID：留空即用内置的社区应用，填入自己的 `clientId` 即覆盖（账号级仍可覆盖顶层简写）。**文档**：README 说明内置应用来自谁、代价是什么、如何换成自己的；并说明 token 与签发它的应用 ID 绑定，将来替换内置注册需要这些账号重新登录一次。测试 262 → 264 项。
-- **0.13.0（2026-09-18）**：**修复**：①长正文截断会把整段正文丢成空（无断点时硬切，保留正文）；②`email_watch` / 网页弹窗的游标会永久漏报一次超过 `limit` 条的新邮件（改为最旧优先分批、游标只推进到实际返回那批）；③附件索引缓存未绑定 UIDVALIDITY，服务器重编号后可能按旧索引写出错误附件（缓存键并入 uidValidity）。**性能**：10 个工具声明 `timeoutMs`（search/watch 120s，其余 60s）；watch/弹窗轮询只 FETCH 本轮要报的条数（此前每轮最多 FETCH 100 封未读信封）；读信与正文搜索只下载 text/* 分段，不再把整封（含附件）拉下来。**口径**：搜索回退路径明确标注为扫描口径（「本页 N 条（仅扫描最近 X 封）」，不再冒充全文件夹匹配数）。**行为变化**：`email_read` 的 `attachments` 只列可下载的 `disposition=attachment`（内嵌图片不再列出）；回退扫描改为逐封下载文本分段（省流量、往返略增）。测试 237 → 262 项。
-- **0.12.0（2026-09-18）**：**新增发送别名**（`senderName` / `authUser` / `authPassword`）：`user` 只作为发件地址与信箱身份，登录名与登录密码可以另填——Gmail / Workspace 的别名发信、以及「登录账号 ≠ From 地址」的 SMTP 中继不再被 `535 Username and Password not accepted` 拒绝，From 也能带显示名。设置页账号卡片新增「发件显示名 / 登录账号 / 登录账号的密码」三栏（与授权码同一套三态：留空保留已存值、清空即删除）。**新增** `email_search` 的 `offset`，命中多于一页时可翻页。**修复与优化**：文件夹 UIDVALIDITY 变化时重建 `email_watch` / 弹窗的增量基线（不再把重编号后的整箱当成新邮件）；搜索的命中复核与结果列表合并为一次 FETCH；`email_attachment` 复用 `email_read` 已解析的 MIME 索引，不再把整封邮件（含附件）重下一遍；`email_folders` 结果缓存 60 秒；网页端新邮件弹窗在标签页不可见时暂停轮询、失败指数退避、皮肤快照降频。**工程**：CI 增加「`lib/` 与 `src/` 不允许漂移」和客户端 bundle 语法检查。测试 237 → 252 项。发送别名的方向来自 [@TianLanDaoRen](https://github.com/TianLanDaoRen) 的 [PR #8](https://github.com/STARDUSTLC666/dsh-email/pull/8)（本实现按 0.11.0 之后的代码重写）。
-- **0.11.0（2026-09-18）**：合入 gurio-wine 的设置页四连（[PR #11](https://github.com/STARDUSTLC666/dsh-email/pull/11)–[#14](https://github.com/STARDUSTLC666/dsh-email/pull/14)），并在评审后修掉其中若干问题。**新增**：①多账号卡片编辑器（增删改 / 改名 / 设默认 / 按账号单独测试连接，编辑即保存，不再需要点「保存并应用」）与服务器预设管理（`serverPresets`，自定义服务商端点，不含凭证）；②Outlook / Exchange Online 的 OAuth2 设备码登录（IMAP 与 SMTP 双端，access token 自动刷新，密码认证账号完全不受影响）；③设置面板文案中英双语，跟随宿主 Settings → General 的语言实时切换；④账号可显式钉住 `authKind`（自动 / oauth2 / password），给仍能用应用密码连 Exchange Online 的混合或本地租户留退路。**评审修复**：SMTP 的 OAuth2 认证形状原本一封也发不出去（nodemailer 的 `XOAuth2` 只读 `accessToken`、从不读 `pass`，实测报 `EAUTH`）；保存面板不再无条件抹掉账号手写的 imap/smtp 端点（运行时解析以账号自己的值优先，原行为会把自建服务器账号静默改指预设，无 provider 的账号则直接失去连接信息）；改名保留授权码与高级键，且不允许顶掉同名账号；设置路由增加 Host / Origin / Content-Type 同源校验（此前任意网页都能跨源改设置，DNS rebinding 还能读走含明文授权码的快照）；响应不再回显解析后的账号映射（那是一份含明文密码、前端从不读取的副本）；服务器原始报错经凭据脱敏后才展示（IMAP/SMTP 会回显被拒的认证串，其中含 access token）；删除账号即清理其 token，未提交的保存不清；版本冲突自动重基，而不是拿旧 revision 反复重试。**不内置任何第三方 OAuth2 应用注册**：OAuth2 账号需自带 `clientId`，见下文「Outlook OAuth2」。测试 81 → 237 项。**修复 `email_search`**：QQ 这类服务器会对任意关键词返回同一批无关 UID，现在服务器命中会先用 envelope 复核（subject/from/to/cc），核实不到就回退本地正文扫描，不会再出现「不存在的关键词也匹配 40 条」（[#15](https://github.com/STARDUSTLC666/dsh-email/issues/15)）。
-- **0.10.8（2026-09-16）**：合入 GUODnuli 的 [PR #9](https://github.com/STARDUSTLC666/dsh-email/pull/9)，将设置页及新邮件弹窗的文字、边框引用改为官方主题变量，修复深色主题文字不可读；复验官方 Harness 0.1.5-rc.2 和 0.1.6-alpha.1。
-- **0.10.7（2026-09-11）**：复验官方 Harness 0.1.5-rc.1，更新整套同载与真实服务验证记录；运行时代码未变。
-- **0.10.6（2026-09-10）**：修复单账号设置页授权码留空时，空字符串遮蔽 `DSH_EMAIL_PASSWORD`，导致“测试连接”和保存后工具调用报未配置的问题；显式密码仍优先，多账号不会借用该环境变量。更新设置页工具数量、多账号说明，并补充真实 QQ 邮箱验证结果。
-- **0.10.5（2026-09-08）**：补充官方 Harness 0.1.3-alpha.2 的安装、工具注册及 Web 设置接口验证，更新 Node 版本要求，明确 `email_health` 只检查配置；运行时代码与 0.10.4 相同。
-- **0.10.4（2026-09-07）**：将 `mailparser` 最低版本提升到 `3.9.22` 并更新锁文件，使用 `html-to-text 10.0.1 → deepmerge-ts 8.0.2` 的修复链处理 [CVE-2026-40345](https://github.com/RebeccaStevens/deepmerge-ts/security/advisories/GHSA-ggr8-5vv4-36mx)。不依赖插件作为下游依赖安装时不生效的根级 `pnpm.overrides`；新增真实依赖链与 HTML 邮件解析回归测试。依赖告警不等于已证实邮件输入可触发该漏洞。
-- **0.10.1**：补发制品——已发布的 0.10.0 打包时只含 `email_mark`，本版同时包含 `email_mark` 与 `email_reply`，代码与 0.10.0 的 main 一致。
-- **0.10.0**：新增 `email_mark`（已读/未读/星标/移动文件夹，补齐收发闭环的整理侧）与 `email_reply`（回复/回复全部/转发，自动线程头+引文，走发信审批门）；连接池按读/写模式分别管理邮箱打开状态。
-- **0.9.1**：修复设置页空主机遮蔽 provider 预设（#3/#6）；IMAP 连接超时不再杀死整个 DSH 进程（#4）；暗色模式输入控件可见（#2）；密码栏提示环境变量 `DSH_EMAIL_PASSWORD` 免明文方案（#5）。
-- **0.9.0**：新增 `email_watch` 增量新邮件检查工具（游标式，适合定时提醒）；Web 端新增「鲸鱼娘递信」新邮件弹窗（本地皮肤素材运行时读取 + 内置回退图）。
-- **0.8.2**：`since` / `until` 参数描述与其余参数统一为英文，方便多语言 agent 理解。
-- **0.8.0/0.8.1**：`email_list` / `email_search` 新增 `since` / `until` 日期范围过滤；新增 `email_health` 账号配置自检；适配 harness 0.1.2（清理已删除的客户端注入声明）。
-- **0.6.2**：服务器端搜索补齐 `cc`，搜索范围真正覆盖主题 / 发件人 / 收件人 / 抄送；正文回退扫描也匹配 `to` / `cc`，单封解析失败不中断整批；列表强制 UID 降序「最新在前」；`email_send` 附件参数严格校验。
-
-## English
-
-- **0.13.2 (2026-09-21)**: download attachments by their real MIME section IDs, fixing duplicate filenames selecting the first file. Legacy parsed metadata matches sections one-to-one. Body-only reads and attachment-index caching remain intact; 268 tests pass, including downloaded-file byte checks.
-- **0.13.0 (2026-09-18)**: **Fixes**: (1) long bodies could be truncated to nothing (now hard-cut with the body preserved); (2) the `email_watch` / popup cursor permanently skipped new mail beyond one `limit` batch (now oldest-first batching, cursor only advances over what was actually returned); (3) the attachment index cache ignored UIDVALIDITY, so a renumbered mailbox could download the wrong attachment (cache key now includes uidValidity). **Performance**: all ten tools declare `timeoutMs` (120s for search/watch, 60s otherwise); watch/popup polls FETCH only the rows they report (previously up to 100 unread envelopes per poll); reads and body search download text/* parts only instead of the whole message with its attachments. **Semantics**: the body-scan fallback now labels itself as such ("this page only, scanning the newest N messages") instead of claiming a folder-wide match count. **Behaviour change**: `email_read` now lists only downloadable `disposition=attachment` entries (inline images are no longer listed); the fallback scan fetches per message (fewer bytes, slightly more round trips). Tests 237 → 262.
-- **0.12.0 (2026-09-18)**: **send-as alias** (`senderName` / `authUser` / `authPassword`): `user` is now only the From address and the mailbox identity, while the login user and password can differ — Gmail / Workspace aliases and SMTP relays where the login is not the From address no longer fail with `535 Username and Password not accepted`, and the From header can carry a display name. The account card gained three fields (same three-state contract as the authorization code: empty keeps the stored value, clearing deletes the key). **New**: `offset` for `email_search`, so results beyond the first page are reachable. **Fixes and optimisations**: a changed folder UIDVALIDITY re-seeds the `email_watch` / popup baseline instead of reporting the renumbered mailbox as new; search verification and the result rows share one FETCH; `email_attachment` reuses the MIME index `email_read` already parsed instead of downloading the whole message again; `email_folders` is cached for 60s; the web new-mail popup pauses while the tab is hidden, backs off on failures and refreshes its skin snapshot less often. **Engineering**: CI now rejects `lib/` drift against `src/` and syntax-checks the hand-written client bundle. Tests 237 → 252. The send-as direction came from [@TianLanDaoRen](https://github.com/TianLanDaoRen)'s [PR #8](https://github.com/STARDUSTLC666/dsh-email/pull/8) (this implementation is a rewrite on top of 0.11.0).
-- **0.11.0 (2026-09-18)**: merge gurio-wine's four settings-page PRs ([#11](https://github.com/STARDUSTLC666/dsh-email/pull/11)–[#14](https://github.com/STARDUSTLC666/dsh-email/pull/14)) with post-review fixes. **Added**: ① visual multi-account card editor (add/edit/delete, rename, set-default, per-account connection test — edits auto-save; no "Save & Apply" button) and server-preset management (`serverPresets`, custom provider endpoints, no credentials); ② OAuth2 device-code login for Outlook / Exchange Online (IMAP and SMTP share one token; automatic refresh; password-auth accounts unaffected); ③ bilingual settings-panel copy that follows the host's Settings → General language in real time; ④ accounts can pin `authKind` (auto / oauth2 / password), giving hybrid or on-premises tenants that still accept app passwords an escape hatch. **Review fixes**: SMTP OAuth2 could never send (nodemailer's `XOAuth2` reads only `accessToken`, never `pass` — confirmed `EAUTH`); saving no longer unconditionally wipes account-level hand-written imap/smtp endpoints (runtime prefers the account's own host; the old behavior silently re-pointed custom-server accounts to presets, and accounts without a provider lost connection info entirely); rename preserves stored auth codes and advanced keys and refuses to overwrite an existing account name; settings routes now enforce Host / Origin / Content-Type same-origin checks (previously any web page could cross-origin-write settings; DNS rebinding could read snapshots containing plaintext auth codes); responses no longer echo the resolved account map (a plaintext-password copy the front end never reads); raw server errors are credential-scrubbed before display (IMAP/SMTP echo rejected auth strings containing access tokens); deleting an account cleans its tokens (uncommitted saves do not); version conflicts auto-rebase instead of retrying with a stale revision. **No third-party OAuth2 app registration is bundled**: OAuth2 accounts must supply their own `clientId` — see "Outlook OAuth2" below. Tests: 81 → 237. **`email_search` fix**: servers like QQ answer any keyword with the same unrelated uid list; hits are now re-verified against the envelopes (subject/from/to/cc) and fall back to the local body scan when none survive, so an impossible keyword no longer "matches" 40 messages ([#15](https://github.com/STARDUSTLC666/dsh-email/issues/15)).
-- **0.10.8 (2026-09-16)**: integrate GUODnuli's [PR #9](https://github.com/STARDUSTLC666/dsh-email/pull/9), replacing nonexistent text and border variables in settings and notifications with official theme tokens; revalidate Harness 0.1.5-rc.2 and 0.1.6-alpha.1.
-- **0.10.7 (2026-09-11)**: revalidate official Harness 0.1.5-rc.1 and refresh suite co-load and live-service evidence; runtime code is unchanged.
-- **0.10.6 (2026-09-10)**: fix an empty authorization-code field shadowing `DSH_EMAIL_PASSWORD` in single-account connection tests and saved settings. Explicit passwords still take precedence; named accounts cannot borrow this environment variable. Refresh the settings tool count, multi-account guidance and real QQ mailbox validation notes.
-- **0.10.5 (2026-09-08)**: document installation, tool registration and the Web settings endpoint in official Harness 0.1.3-alpha.2; update Node requirements and clarify that `email_health` checks configuration only. Runtime code is unchanged from 0.10.4.
-- **0.10.4 (2026-09-07)**: raise the minimum `mailparser` version to `3.9.22` and update the lockfile to use the patched `html-to-text 10.0.1 → deepmerge-ts 8.0.2` dependency chain for [CVE-2026-40345](https://github.com/RebeccaStevens/deepmerge-ts/security/advisories/GHSA-ggr8-5vv4-36mx). This does not rely on root-only `pnpm.overrides`, which cannot fix consumers installing this plugin as a dependency. Add runtime dependency-chain and HTML-message parsing regression tests. An affected dependency is not proof that mail input can trigger this vulnerability.
-- **0.9.0**: new `email_watch` incremental new-mail tool (cursor-based, ideal for scheduled notifications); new "whale-girl courier" new-mail popup in the web UI (local skin artwork read at runtime + built-in fallback).
-- **0.8.2**: `since` / `until` parameter descriptions unified to English, consistent with the other parameters, so multilingual agents read them correctly.
-- **0.8.0/0.8.1**: `email_list` / `email_search` gained `since` / `until` date-range filters; new `email_health` account-configuration self-check; adapted to harness 0.1.2 (removed the deleted client-injection declaration).
-- **0.6.2**: server-side search covers `cc` (subject / sender / recipients / CC); the body fallback scan also matches `to` / `cc` and one malformed message no longer aborts the batch; lists are UID-descending (newest first); `email_send` strictly validates attachment paths.
+## 0.14.0 (2026-09-23)
+
+- 适配 Harness 0.1.7 设置接口；自动导入旧版邮箱设置，旧账号直接显示为可编辑卡片。编辑即时保存，刷新后保留；保留高级参数与已有密码，清空账号后不再重新出现。
+
+## 0.13.2 (2026-09-21)
+
+- 同名附件优先按真实 MIME 分段编号下载；旧解析元数据按一对一匹配，避免多个序号都取到第一个同名文件。保留正文分段下载和附件索引缓存，新增文件字节级回归，268 项测试通过。
+
+## 0.13.1 (2026-09-19)
+
+- **新增**：内置一份公共客户端注册（`15dcd5aa-…`，贡献者 [gurio-wine](https://github.com/gurio-wine) 在 [PR #13](https://github.com/STARDUSTLC666/dsh-email/pull/13) 注册，并授权本项目内置使用，特此致谢）——Outlook / Exchange Online 的 OAuth2 登录**开箱即用**，不再需要每个用户自己注册应用。设置页卡片会显示当前生效的应用 ID：留空即用内置的社区应用，填入自己的 `clientId` 即覆盖（账号级仍可覆盖顶层简写）。**文档**：README 说明内置应用来自谁、代价是什么、如何换成自己的；并说明 token 与签发它的应用 ID 绑定，将来替换内置注册需要这些账号重新登录一次。测试 262 → 264 项。
+
+## 0.13.0 (2026-09-19)
+
+- **修复**：①长正文截断会把整段正文丢成空（无断点时硬切，保留正文）；②`email_watch` / 网页弹窗的游标会永久漏报一次超过 `limit` 条的新邮件（改为最旧优先分批、游标只推进到实际返回那批）；③附件索引缓存未绑定 UIDVALIDITY，服务器重编号后可能按旧索引写出错误附件（缓存键并入 uidValidity）。**性能**：10 个工具声明 `timeoutMs`（search/watch 120s，其余 60s）；watch/弹窗轮询只 FETCH 本轮要报的条数（此前每轮最多 FETCH 100 封未读信封）；读信与正文搜索只下载 text/* 分段，不再把整封（含附件）拉下来。**口径**：搜索回退路径明确标注为扫描口径（「本页 N 条（仅扫描最近 X 封）」，不再冒充全文件夹匹配数）。**行为变化**：`email_read` 的 `attachments` 只列可下载的 `disposition=attachment`（内嵌图片不再列出）；回退扫描改为逐封下载文本分段（省流量、往返略增）。测试 237 → 262 项。
+
+## 0.12.0 (2026-09-18)
+
+- **新增发送别名**（`senderName` / `authUser` / `authPassword`）：`user` 只作为发件地址与信箱身份，登录名与登录密码可以另填——Gmail / Workspace 的别名发信、以及「登录账号 ≠ From 地址」的 SMTP 中继不再被 `535 Username and Password not accepted` 拒绝，From 也能带显示名。设置页账号卡片新增「发件显示名 / 登录账号 / 登录账号的密码」三栏（与授权码同一套三态：留空保留已存值、清空即删除）。**新增** `email_search` 的 `offset`，命中多于一页时可翻页。**修复与优化**：文件夹 UIDVALIDITY 变化时重建 `email_watch` / 弹窗的增量基线（不再把重编号后的整箱当成新邮件）；搜索的命中复核与结果列表合并为一次 FETCH；`email_attachment` 复用 `email_read` 已解析的 MIME 索引，不再把整封邮件（含附件）重下一遍；`email_folders` 结果缓存 60 秒；网页端新邮件弹窗在标签页不可见时暂停轮询、失败指数退避、皮肤快照降频。**工程**：CI 增加「`lib/` 与 `src/` 不允许漂移」和客户端 bundle 语法检查。测试 237 → 252 项。发送别名的方向来自 [@TianLanDaoRen](https://github.com/TianLanDaoRen) 的 [PR #8](https://github.com/STARDUSTLC666/dsh-email/pull/8)（本实现按 0.11.0 之后的代码重写）。
+
+## 0.11.0 (2026-09-18)
+
+- 合入 gurio-wine 的设置页四连（[PR #11](https://github.com/STARDUSTLC666/dsh-email/pull/11)–[#14](https://github.com/STARDUSTLC666/dsh-email/pull/14)），并在评审后修掉其中若干问题。**新增**：①多账号卡片编辑器（增删改 / 改名 / 设默认 / 按账号单独测试连接，编辑即保存，不再需要点「保存并应用」）与服务器预设管理（`serverPresets`，自定义服务商端点，不含凭证）；②Outlook / Exchange Online 的 OAuth2 设备码登录（IMAP 与 SMTP 双端，access token 自动刷新，密码认证账号完全不受影响）；③设置面板文案中英双语，跟随宿主 Settings → General 的语言实时切换；④账号可显式钉住 `authKind`（自动 / oauth2 / password），给仍能用应用密码连 Exchange Online 的混合或本地租户留退路。**评审修复**：SMTP 的 OAuth2 认证形状原本一封也发不出去（nodemailer 的 `XOAuth2` 只读 `accessToken`、从不读 `pass`，实测报 `EAUTH`）；保存面板不再无条件抹掉账号手写的 imap/smtp 端点（运行时解析以账号自己的值优先，原行为会把自建服务器账号静默改指预设，无 provider 的账号则直接失去连接信息）；改名保留授权码与高级键，且不允许顶掉同名账号；设置路由增加 Host / Origin / Content-Type 同源校验（此前任意网页都能跨源改设置，DNS rebinding 还能读走含明文授权码的快照）；响应不再回显解析后的账号映射（那是一份含明文密码、前端从不读取的副本）；服务器原始报错经凭据脱敏后才展示（IMAP/SMTP 会回显被拒的认证串，其中含 access token）；删除账号即清理其 token，未提交的保存不清；版本冲突自动重基，而不是拿旧 revision 反复重试。**不内置任何第三方 OAuth2 应用注册**：OAuth2 账号需自带 `clientId`，见下文「Outlook OAuth2」。测试 81 → 237 项。**修复 `email_search`**：QQ 这类服务器会对任意关键词返回同一批无关 UID，现在服务器命中会先用 envelope 复核（subject/from/to/cc），核实不到就回退本地正文扫描，不会再出现「不存在的关键词也匹配 40 条」（[#15](https://github.com/STARDUSTLC666/dsh-email/issues/15)）。
+
+## 0.10.8 (2026-09-16)
+
+- 合入 GUODnuli 的 [PR #9](https://github.com/STARDUSTLC666/dsh-email/pull/9)，将设置页及新邮件弹窗的文字、边框引用改为官方主题变量，修复深色主题文字不可读；复验官方 Harness 0.1.5-rc.2 和 0.1.6-alpha.1。
+
+## 0.10.7 (2026-09-12)
+
+- 复验官方 Harness 0.1.5-rc.1，更新整套同载与真实服务验证记录；运行时代码未变。
+
+## 0.10.6 (2026-09-10)
+
+- 修复单账号设置页授权码留空时，空字符串遮蔽 `DSH_EMAIL_PASSWORD`，导致“测试连接”和保存后工具调用报未配置的问题；显式密码仍优先，多账号不会借用该环境变量。更新设置页工具数量、多账号说明，并补充真实 QQ 邮箱验证结果。
+
+## 0.10.5 (2026-09-08)
+
+- 补充官方 Harness 0.1.3-alpha.2 的安装、工具注册及 Web 设置接口验证，更新 Node 版本要求，明确 `email_health` 只检查配置；运行时代码与 0.10.4 相同。
+
+## 0.10.4 (2026-09-07)
+
+- 将 `mailparser` 最低版本提升到 `3.9.22` 并更新锁文件，使用 `html-to-text 10.0.1 → deepmerge-ts 8.0.2` 的修复链处理 [CVE-2026-40345](https://github.com/RebeccaStevens/deepmerge-ts/security/advisories/GHSA-ggr8-5vv4-36mx)。不依赖插件作为下游依赖安装时不生效的根级 `pnpm.overrides`；新增真实依赖链与 HTML 邮件解析回归测试。依赖告警不等于已证实邮件输入可触发该漏洞。
+
+## 0.10.1 (2026-09-01)
+
+- 补发制品——已发布的 0.10.0 打包时只含 `email_mark`，本版同时包含 `email_mark` 与 `email_reply`，代码与 0.10.0 的 main 一致。
+
+## 0.10.0 (2026-09-01)
+
+- 新增 `email_mark`（已读/未读/星标/移动文件夹，补齐收发闭环的整理侧）与 `email_reply`（回复/回复全部/转发，自动线程头+引文，走发信审批门）；连接池按读/写模式分别管理邮箱打开状态。
+
+## 0.9.1 (2026-09-01)
+
+- 修复设置页空主机遮蔽 provider 预设（#3/#6）；IMAP 连接超时不再杀死整个 DSH 进程（#4）；暗色模式输入控件可见（#2）；密码栏提示环境变量 `DSH_EMAIL_PASSWORD` 免明文方案（#5）。
+
+## 0.9.0 (2026-08-31)
+
+- 新增 `email_watch` 增量新邮件检查工具（游标式，适合定时提醒）；Web 端新增「鲸鱼娘递信」新邮件弹窗（本地皮肤素材运行时读取 + 内置回退图）。
+
+## 0.8.2 (2026-08-31)
+
+- `since` / `until` 参数描述与其余参数统一为英文，方便多语言 agent 理解。
+
+## 0.8.0/0.8.1
+
+- `email_list` / `email_search` 新增 `since` / `until` 日期范围过滤；新增 `email_health` 账号配置自检；适配 harness 0.1.2（清理已删除的客户端注入声明）。
+
+## 0.6.2
+
+- 服务器端搜索补齐 `cc`，搜索范围真正覆盖主题 / 发件人 / 收件人 / 抄送；正文回退扫描也匹配 `to` / `cc`，单封解析失败不中断整批；列表强制 UID 降序「最新在前」；`email_send` 附件参数严格校验。
+
+## 更早的改动
+
+完整历史可查阅 [GitHub 提交记录](https://github.com/STARDUSTLC666/dsh-email/commits/main)。

package/README.en.md

@@ -1,266 +1,48 @@
 # dsh-email
 
-## 0.14.7 update (2026-10-02)
+[中文](README.md)
 
-- Account cards display the effective IMAP/SMTP endpoints. Changing providers clears stale display values without persisting the endpoint summary into account configuration.
-- Upgrade to ImapFlow 2.2.1, Mailparser 3.9.33 and Nodemailer 10.0.13, adapt upstream types and empty responses, and eliminate the production dependency audit findings.
-- Give recovery guidance when a message or attachment disappears during a request; empty search responses remain empty lists.
-- All 304 tests pass on Windows, including local SMTP TLS, STARTTLS, cancellation and OAuth2 protocol fixtures. Production mailbox login and delivery still require user acceptance.
+Read, send, search and organize email from DSH with multiple accounts.
 
-## 0.14.6 update (2026-10-02)
+[![npm](https://img.shields.io/npm/v/dsh-email)](https://www.npmjs.com/package/dsh-email) [![downloads](https://img.shields.io/npm/dm/dsh-email)](https://www.npmjs.com/package/dsh-email)
 
-Completes [PR #18](https://github.com/STARDUSTLC666/dsh-email/pull/18): untouched saved form endpoints and partial drafts with empty endpoints preserve explicitly configured row IMAP/SMTP servers. The Outlook 587/STARTTLS fix and deliberate port/TLS overrides remain supported.
+## What it does
 
-All 297 email tests pass on Windows / Node `24.16.0`. Both new server-preservation regressions failed before the fix and pass afterward. This change has not been validated through real mailbox login, OAuth2 authorization or delivery.
+- Read, send, reply and forward using IMAP and SMTP.
+- Manage attachments, search results and mailbox organization.
+- Configure multiple accounts, Outlook OAuth2 and send approval.
+- Prepare and edit local drafts, review To/Cc, content and attachment bytes, then confirm sending.
+- Manage trusted recipients per account and preview address, group and Cc matches.
 
-## 0.14.5 update (2026-10-01)
+## Install
 
-Fixes [#20](https://github.com/STARDUSTLC666/dsh-email/issues/20): a named account's provider selects its own servers, so Gmail no longer inherits shared Outlook endpoints or becomes an OAuth2 account. Card saves exclude form-derived shared endpoints. Explicit account endpoints and legacy single-account configuration remain supported; top-level sender aliases and login credentials now take effect. Connection failures identify the selected account and actual IMAP host and port, with echoed credentials redacted.
-
-An empty card asks for its email address before testing. Outlook's built-in application ID updates from the saved snapshot, avoiding a false missing-ID warning. Stored separate login passwords are acknowledged without exposing their values.
-
-Validation host: Harness `0.2.0-rc.2` built from the official release tag (commit `639ed01539`), Windows and Node `24.16.0`. All 295 email tests pass; all 18 plugins mount together, with 10 email tools. Native Desktop checks covered adding a card, switching Outlook/Gmail, automatic saving and deletion. The final field-hint fixes have component behavior regressions but have not been retested in the native UI. Successful real-mailbox login, OAuth2 authorization and sending remain unverified.
-
-![npm](https://img.shields.io/npm/v/dsh-email) ![downloads](https://img.shields.io/npm/dm/dsh-email) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-email) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-email?style=social)
-
-[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
-
-![dsh-email banner](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/banner.png)
-
-Email plugin for DeepSeek Harness: **10 IMAP/SMTP tools** cover reading and searching mail, sending, replies and forwarding, attachments, message flags and moves, incremental new-mail checks, and configuration health. Supports multiple accounts, send approval, Web settings and new-mail popups. Configure an account with presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud to get started.
-
-Pure Node, **cross-platform** (one codebase for Windows / macOS / Linux), no shell, no native binaries.
-
-## Tools
-
-| Tool | Purpose |
-|---|---|
-| `email_list` | List the newest mail in a folder (unread filter, pagination, summaries only, no body) |
-| `email_read` | Read one message's full text by uid (HTML auto-converted to plain text, oversized bodies truncated) |
-| `email_search` | Search subject/sender/recipient/CC by keyword (server-side subject/from/to/cc; hits are re-checked against the envelopes, so "match-everything" servers such as QQ are rejected); when nothing believable is returned, it falls back to a body scan of the most recent 30 messages by default (including to/cc) |
-| `email_send` | Send mail on your behalf (attachments supported). **Prompts for confirmation before sending by default**, showing recipients, subject and attachment count; only sends after you approve |
-| `email_folders` | List the mailbox folders (INBOX/Sent/Junk/custom…); feed the `path` to other tools |
-| `email_attachment` | Download an attachment by index (saved to the session workspace by default so the model can read it directly; size capped by `maxAttachmentBytes`) |
-| `email_health` | Check account configuration and IMAP/SMTP host details offline; makes no network connection. Use Test connection in Web settings to verify IMAP connectivity |
-| `email_watch` | Incremental new-mail check: the first call seeds a baseline, every later call reports only unread mail newer than the last check — ideal for scheduled new-mail notifications |
-| `email_mark` | Mark messages as read/unread, add/remove stars, or move messages to another folder |
-| `email_reply` | Reply, reply-all or forward with thread headers and quoted content; uses the same send-approval gate |
-
-### New-mail notifications (web UI)
-
-Once an account is configured, a "whale-girl courier" popup lives in the bottom-right corner of the main UI: it checks for new mail every 30 seconds and shows a card (sender + subject) when something arrives, auto-dismissing after 12 seconds. The popup shares the cursor logic with `email_watch` but keeps its own counter, so they never consume each other's mail.
-
-The popup artwork prefers the locally installed [dsh-deep-whale](https://github.com/Small-tailqwq/dsh-deep-whale) whale-girl skin assets (**never bundled** — read at runtime from your own installation): the artwork is a derivative of the original whale-girl character by [上善](https://www.pixiv.net/users/62155430) (skin by Small-tailqwq), published under CC BY-NC-SA 4.0 (Attribution-NonCommercial-ShareAlike); the popup shows the full attribution chain. Without the skin, a bundled community whale-girl artwork is used (copyright stays with the original author, personal non-commercial use only; removed on request via issue).
-
-Example:
-
-> Check the 10 newest unread messages in my QQ mailbox and list the ones that need a reply.
-
-### Changelog
-
-- **0.14.0 (2026-09-23)**: supports Harness 0.1.7 settings. Existing mailbox settings migrate automatically and appear as editable cards; edits auto-save and survive refresh and restart. Advanced options and saved passwords are preserved; removing all cards no longer resurrects a hidden legacy account.
-
-- **0.13.2 (2026-09-21)**: download attachments by their real MIME section IDs, fixing duplicate filenames selecting the first file. Legacy parsed metadata matches sections one-to-one. Body-only reads and attachment-index caching remain intact; 268 tests pass, including downloaded-file byte checks.
-- **0.13.1 (2026-09-19)**: ships a community public-client registration (thanks [gurio-wine](https://github.com/gurio-wine)), so Outlook / Exchange Online works out of the box; supply your own `clientId` to override it — the card shows which application is in effect. 264 tests.
-- **0.13.0 (2026-09-18)**: fixes for bodies truncated to nothing, `email_watch` skipping new mail, and the attachment cache ignoring UIDVALIDITY; all ten tools declare a timeout; reads and body search download text parts only; the scan fallback labels its own semantics. 262 tests.
-- **0.12.0 (2026-09-18)**: send-as alias (`senderName` / `authUser` / `authPassword`) and `offset` paging for `email_search`; QQ match-everything searches no longer trusted; popup polling pauses while the tab is hidden.
-- **0.11.0 (2026-09-18)**: gurio-wine’s four settings-page PRs (card editor / OAuth2 device-code login / bilingual panel / pinned `authKind`) plus the review fixes for SMTP OAuth2 and same-origin settings routes.
-- **0.10.8 and earlier**: see [CHANGELOG.md](CHANGELOG.md).
-## Compatibility
-
-The current baseline is Harness **0.2.0-rc.2** built from its official release tag on 2026-09-30. All 18 plugins mount together with 99 tools and 35 skills; registration and output checks pass. New email regressions cover provider isolation, card saves, endpoint diagnostics, sender aliases and editor hints. The native UI scope and remaining live-service checks are described above.
-
-**0.11.0 co-load verification (2026-09-18, locally built Harness `0.1.5-rc.2`, `web` profile)**: the plugin mounted without errors; the settings route answered GET with 200 and no `raw` field in the response; a `text/plain` POST was refused with **415**, proving the same-origin guard holds in the real host; under a `application/json` POST the card projection was correct, and an account pinning `authKind: password` reported both `authKindDeclared` and `authKind` as `password`; the panel actually rendered account cards, the eight provider presets with localized labels, the three-way authentication selector, the application (client) ID field with its hint, the missing-ID warning banner (so `--dsw-alias-state-warn-primary` is genuinely defined in the real host) and the Sign in with Microsoft button; the browser console was clean; save worked end to end, and afterwards `accountsYaml` was restored to empty with the original account intact. Offline tests: 231 green. **Still not done**: an end-to-end OAuth2 run against a real Outlook tenant (the device-code flow needs a human to authorize in a browser) and real sending; the `clientId` paths are covered only against a fake authority. Uses the `cordis.patch.yml` + `dsh.bundle.patch` bundle model. Node requirements are 22.19 or later within 22.x, or 24 or later. Live external-service workflows require separate configuration and validation.
-
-On 2026-09-10, npm `dsh-email@0.10.6` passed real QQ mailbox folder/list/read/search calls, the settings page's connection test and Save & Apply, and separate SMTP authentication. An empty authorization-code field correctly used `DSH_EMAIL_PASSWORD`. This recheck did not connect to a real mailbox or send, modify or delete mail.
-
-Follows the official [plugin packaging and installation requirements](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md): an ESM entry point, prebuilt `lib/`, `dsh.bundle.patch` and a `cordis.patch.yml` layer. The plugin explicitly injects its required services and supplies JSON Schema parameters, canonical output and rendering, without importing host-internal services; configuration uses the public `@deepseek-ai/schemastery` package. Use Node 22.19 or later within 22.x, or Node 24 or later. Harness is evolving rapidly; the version above is the tested baseline.
-
-## Installation
-
-```sh
-dsh plugin --profile web add dsh-email
-```
-
-(Or install a specific GitHub commit: `dsh plugin --profile web add github:STARDUSTLC666/dsh-email#<commit>`. The repository includes prebuilt `lib/` artifacts; no `prepare` build is required.)
-
-After installing, restart `dsh web`. The plugin ships with an empty config and **won't crash startup**; calling any email tool before configuration returns a clear configuration hint.
-
-**Two configuration methods (pick one):**
-
-1. **Web settings (recommended)**: after restart, open **Settings → Mail (dsh-email)**, fill in the email address and authorization code in an account card — edits auto-save, no button to click; each card also has its own "Test connection" button. Zero YAML, zero restart.
-2. **YAML**: hand-write the `accounts` map in the cordis.patch.yml template below. The settings page's `accountsYaml` is written by the card editor (it overrides `accounts` when non-empty); the panel itself no longer provides a raw-YAML textarea. Fields not modeled by cards (e.g. `socketTimeoutMs`, `connectionTimeoutMs`) can still be hand-written in YAML and are preserved in place when cards are saved. Authentication method (`authKind`) has a selector on the card — no need to hand-write it.
-
-The whole settings page follows DSH's light and dark themes: every panel style references the official `--dsw-alias-*` design tokens instead of hard-coded colors, so switching themes takes effect immediately (0.10.8 referenced a border token that does not exist, which produced a glaring light-gray border in dark mode; that is fixed).
-
-Multiple accounts can be edited visually in the settings page: account cards add, edit and delete accounts, rename them, pick the default, and run "Test connection" per account name; a half-filled account never blocks saving — it just gets an "incomplete" badge. Card edits are debounced and auto-saved; there is no longer a "write to YAML text, then click save" step. Version conflicts (settings changed elsewhere) are automatically rebased and re-saved once, rather than repeatedly failing with a stale revision. When a card is saved, an already-stored authorization code is kept by default (leave the password field empty to keep it, type into it to overwrite); comments in the YAML are preserved in place where possible — with an explicit notice when they cannot be. Rename re-keys in place, preserving auth codes and advanced keys, and refuses to overwrite an existing account name. Account-level hand-written imap/smtp endpoints are only cleaned when the **provider actually changes** — runtime resolution prefers the account's own host, so a routine save never silently re-points the connection target.
-
-On Harness 0.1.7, the page saves directly to the current profile’s `tool-email` entry and applies changes live. Installations using the default entry automatically import the retired `dsh-email` section from `settings.yaml` or `settings.yaml.imported` once. Existing profile values win, and the original file is preserved. Older hosts retain their original settings storage. Authorization-code fields are marked secret, but saving a filled field still writes its value to the local settings file. For a single account, set `DSH_EMAIL_PASSWORD` and leave the authorization-code field empty to avoid saving it; the environment value is not copied into settings.
-
-## Uninstall
+In DSH Desktop, install `dsh-email` from the Plugins panel. If the bundled dsh command is available:
 
 ```bash
-dsh plugin --profile web remove dsh-email
+dsh plugin --profile desktop add dsh-email
 ```
 
-Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+For the web version, replace `desktop` with `web`. Restart DSH after installation.
 
+## Start using it
 
-## Configuration
+Add an account and test it in Settings → Email. Ask to list recent unread messages or prepare a reply; review recipients and content before sending.
 
-In your profile's `cordis.patch.yml` (under `$DSH_HOME/profiles/<name>/`), override the `tool-email` line, then restart:
+To edit before sending, ask: “Prepare a message with email_draft; do not send yet.” Open Drafts to save edits, inspect attachments and confirm. See [drafts and recipient rules](docs/DRAFTS.en.md).
 
-```yaml
-- id: tool-email
-  config:
-    provider: qq          # qq | 163 | 126 | sina | aliyun | gmail | outlook | icloud
-    user: you@qq.com
-    password: 你的授权码   # 强烈建议改用环境变量 DSH_EMAIL_PASSWORD，见下
-```
+## Requirements and configuration
 
-No preset needed? Hand-write any IMAP/SMTP server:
+Requires mail credentials, an app password or provider OAuth authorization. Mail authentication is separate from the DSH model API key.
 
-```yaml
-- id: tool-email
-  config:
-    user: you@corp.example
-    password: 你的授权码
-    imap: { host: imap.corp.example, port: 993, secure: true }
-    smtp: { host: smtp.corp.example, port: 465, secure: true }
-    inboxFolder: INBOX
-```
-
-Multiple accounts: one `tool-email` line can hold several mailboxes; select one with the `account` argument when calling a tool:
-
-```yaml
-- id: tool-email
-  config:
-    accounts:
-      work: { provider: qq, user: work@qq.com, password: 授权码1 }
-      home: { provider: '163', user: home@163.com, password: 授权码2 }
-    defaultAccount: work        # 省略 account 参数时用这个
-    downloadDir: E:/attachments # 可选，默认 $DSH_HOME/email-downloads
-```
-
-Top-level `provider`/`user`/`password`/`imap`/`smtp`/`inboxFolder` remain available as shared defaults for all accounts (the v0.1 single-account style stays fully compatible).
-
-To reuse one set of connection endpoints across accounts, define your own provider presets with `serverPresets` (a YAML map: key = preset name, value has an optional `label` plus `imap`/`smtp`):
-
-```yaml
-- id: tool-email
-  config:
-    serverPresets: |
-      corp:
-        label: 公司邮箱
-        imap: { host: imap.corp.example, port: 993, secure: true }
-        smtp: { host: smtp.corp.example, port: 465, secure: true }
-```
-
-The settings page's "Server presets" fold-out edits these presets visually, and the account cards' provider dropdown automatically gains the preset names — picking one pre-fills its endpoints into the account. A preset holds connection endpoints only — **never an email address or authorization code**. `port`/`secure` may be omitted (defaults are 993/465 with SSL).
-
-## Presets
-
-| provider | IMAP | SMTP |
-|---|---|---|
-| `qq` | imap.qq.com:993 (SSL) | smtp.qq.com:465 (SSL) |
-| `163` | imap.163.com:993 | smtp.163.com:465 |
-| `126` | imap.126.com:993 | smtp.126.com:465 |
-| `sina` | imap.sina.com:993 | smtp.sina.com:465 |
-| `aliyun` | imap.aliyun.com:993 | smtp.aliyun.com:465 |
-| `gmail` | imap.gmail.com:993 | smtp.gmail.com:465 |
-| `outlook` | outlook.office365.com:993 | smtp.office365.com:587 (STARTTLS) |
-| `icloud` | imap.mail.me.com:993 | smtp.mail.me.com:587 (STARTTLS) |
-
-### Full configuration options
-
-| Field | Default | Description |
-|---|---|---|
-| `provider` | — | Preset name; auto-fills imap/smtp addresses. Explicitly written host/port/secure take precedence |
-| `user` | required | Login email address |
-| `password` | required* | Authorization code / app-specific password; *can also use the env var `DSH_EMAIL_PASSWORD` |
-| `senderName` | — | Display name for the From header; the address itself stays `user` |
-| `authUser` | = `user` | Login account. Alias / SMTP-relay setups: `user` is the address mail is sent from, this is the account IMAP/SMTP authenticates with |
-| `authPassword` | = `password` | Password for `authUser`; only needed when the login account differs from `user` and has its own password |
-| `imap.host/port/secure` | per preset | Incoming server (also `connectionTimeoutMs` / `socketTimeoutMs` for timeouts) |
-| `smtp.host/port/secure` | per preset | Outgoing server |
-| `inboxFolder` | `INBOX` | Default folder for read/send tools |
-| `sendApproval` | `true` | Confirm before sending (strongly recommended) |
-| `maxBodyChars` | `20000` | Body truncation limit for `email_read` (1000–200000) |
-| `accounts` | — | Named account map; account-level fields override top-level shorthand |
-| `accountsYaml` | — | YAML text of the account map, written by the settings-page card editor; overrides `accounts` when non-empty |
-| `clientId` | built-in community app (below) | Application (client) ID for OAuth2 accounts: empty uses the plugin's built-in public client, a value overrides it (account-level also overrides the top-level shorthand) |
-| `authKind` | derived from provider | Authentication method override: `oauth2` / `password`. When omitted, derived from provider and IMAP host; hybrid or on-premises tenants that still accept app passwords for Exchange Online can pin `password`. The card's "Authentication method" selector writes this key |
-| `serverPresets` | — | YAML text of custom provider presets (key = preset name, value has optional `label` + `imap`/`smtp`); endpoints only, no credentials. The settings-page dropdown lists preset names and pre-fills endpoints into account cards; editing a preset does not reconnect established connections |
-| `defaultAccount` | auto (single account) | Account used when the `account` argument is omitted (required for multi-account) |
-| `downloadDir` | `.dsh-email-downloads` under session workspace (fallback `$DSH_HOME/email-downloads`) | Download directory for `email_attachment`; pinned once explicitly set |
-| `maxAttachmentBytes` | 20 MiB | Per-attachment and total size cap (1024–512 MiB) |
-| `idleTimeoutMs` | `60000` | IMAP idle connection recycle time (connection reuse; consecutive ops are faster) |
-| `bodySearchFallback` | `true` | Fall back to client-side body scan of recent messages when server search returns nothing |
-| `bodySearchLimit` | `30` | Number of messages for the body fallback scan (5–200) |
-
-## Getting an authorization code
-
-Every provider requires an authorization code / app-specific password instead of your login password:
-
-- **QQ Mail**: Settings → Account → enable IMAP/SMTP → generate authorization code
-- **163/126**: Settings → POP3/SMTP/IMAP → enable → add authorization code
-- **Gmail**: enable 2-Step Verification → Security → App passwords
-- **Outlook**: Microsoft account security → App password (some accounts need 2-step verification first)
-
-## Security
-
-- **The authorization code is the key to your mailbox.** It lives on this machine (`cordis.patch.yml` or `settings.yaml` in the profile); never commit it to any Git repo; prefer the `DSH_EMAIL_PASSWORD` env var.
-- `email_send` goes through the DSH approval channel by default: every send shows "send mail to xx, subject "xx"" and only sends after you approve. Environments without an approval channel (e.g. headless with no UI) **refuse to send outright** — that is the secure default.
-- When the session is in **Full Access** mode, the harness approval policy is never (no confirmation dialogs) — `email_send` is **blocked with a clear hint**. Two ways out: ① switch the access mode back to Read Only / Write; ② turn off `sendApproval` (uncheck "Confirm before sending" in the settings page), explicitly declaring you accept the risk.
-- This plugin performs no outbound telemetry; credentials are used in memory only to connect to your mail servers.
-
-## Outlook OAuth2 (device-code login)
-
-Microsoft has disabled username+password basic auth for Exchange Online: personal outlook.com accounts and most tenants now require OAuth2. This plugin supports the device-code flow — IMAP and SMTP share a single token with automatic refresh.
-
-**Where the bundled application ID comes from**: the device-code flow needs an app registration, and making every user register one is a wall nobody should have to climb — so the plugin ships one: `15dcd5aa-00dd-487f-82d7-1d2b2c299e14`, registered by contributor [gurio-wine](https://github.com/gurio-wine) in [PR #13](https://github.com/STARDUSTLC666/dsh-email/pull/13) and used here with their permission — thank you. The cost is stated plainly: the Microsoft consent screen names **their** application (enterprise security teams may refuse it), and the sign-in logs and telemetry land in **their** tenant, including your UPN. If they ever delete the app, every account that did not bring its own id stops signing in at once, with no better error than "clientId may be wrong". **Registering your own (free, ~10 minutes) keeps you independent — paste it into the card to override the built-in value; leaving the field empty keeps using the bundled one.**
-
-**Using your own application instead (optional, free, ~10 minutes)**:
-
-1. Open the [Entra admin center](https://entra.microsoft.com/) → **App registrations** → **New registration**.
-2. Under **Supported account types**, select "Accounts in any organizational directory and personal Microsoft accounts" — this determines whether personal outlook.com accounts can sign in. Choosing incorrectly yields `AADSTS700016` or `AADSTS50020`.
-3. Leave the **Redirect URI** blank (the device-code flow does not need one). Click Register.
-4. On the Overview page, copy the **Application (client) ID** — this is the `clientId` you will supply.
-5. In the left sidebar, go to **Authentication** → scroll to the bottom → set **Allow public client flows** to **Yes** and save. Without this, login fails with an `AADSTS700028`-style "device-code flow not enabled" error.
-6. In the left sidebar, go to **API permissions** → Add a permission → Microsoft Graph → **Delegated permissions** → check `IMAP.AccessAsUser.All`, `SMTP.Send`, and `offline_access` (the last one is essential for obtaining a refresh token — without it, every expiry forces a fresh login). Personal tenants generally need no admin consent; enterprise tenants may require an admin to click "Grant admin consent" once.
-
-**Filling it into the plugin (overrides the built-in value)**: Settings → Mail (dsh-email) → the account card's "Application (client) ID" field (the card shows which application is in effect; empty keeps the bundled community app); or in YAML (account-level `clientId`, which can also be set at the top level as a default for all accounts).
-
-**Login flow**: click "Sign in to Microsoft account" on the card → the panel shows a `microsoft.com/devicelogin` link and a code → open the link in a browser, enter the code, and complete authorization → the panel polls until it shows "Signed in: your@email". Both receiving and sending then use this token.
-
-**Caveats**:
-
-- Enterprise tenants may additionally require an admin to enable **IMAP** and **SMTP AUTH** for the mailbox in the Exchange admin center. The typical symptom of SMTP AUTH being off: receiving works fine, sending is rejected.
-- The token is bound to the application ID that issued it: changing `clientId` is treated as "switched apps" and requires re-login (this is intentional — it prevents using the old app's credentials against the new one). The bundled app is shared by every account that names none: a future release that replaces it with the project's own registration will ask those accounts to sign in once more.
-- If your tenant is hybrid or on-premises and SMTP AUTH is still enabled, app passwords work: select "Password / authorization code" in the card's "Authentication method" selector — no OAuth2 needed.
-
-## Known limitations
-
-- **OAuth2 covers Outlook / Exchange Online only, and works out of the box (your own app ID optional)**: device-code login supports both IMAP and SMTP and defaults to the bundled community application (see "Outlook OAuth2" above), so no registration is needed to sign in; if your organisation refuses third-party apps, paste your own `clientId` into the card to override it. Other environments that mandate OAuth (e.g. Google Workspace) remain unusable; use the provider's app-specific password / authorization code instead.
-- **Search match counts**: server hits are re-checked against the envelopes (see `email_search` above); when they hold up, "N matches" is the count the server reported while every listed row really carries the keyword. The local body-scan fallback only looked at the newest `bodySearchLimit` messages, so it renders "N rows on this page (only the newest N scanned)" instead of "N matches".
-- **Body search**: the server side only searches subject / from / to / cc. Most servers (e.g. QQ) have unreliable IMAP `TEXT` / `HEADER` search, so with no results it falls back to a body scan of the most recent `bodySearchLimit` messages (slower; disable with `bodySearchFallback`).
-- **Attachments**: inline images aren't downloadable separately yet; a failed attachment match errors instead of downloading the wrong file (safe default).
-- **Password storage**: the authorization code saved in the settings page is written in plaintext to the local `settings.yaml` (the secret mark only keeps it out of logs / exports / diagnostics; no disk encryption). Don't hand `settings.yaml` to untrusted people.
-- **OAuth2 token storage**: access / refresh tokens are stored as plaintext JSON at `$DSH_HOME/data/dsh-email/oauth2-tokens.json` (deliberately kept out of `settings.yaml`, so they are not included in settings exports). The file is written with `mode: 0o600`, but that permission bit only takes effect **at file creation** and is **effectively a no-op on Windows** — do not hand this file to untrusted people. Tokens are bound to the issuing application ID; changing `clientId` requires re-login. Deleting an account cleans up its tokens.
-- **Local edits are undone by `pnpm install`**: if you deploy by editing files inside `node_modules/dsh-email/`, any `pnpm install` restores the registry version (0.10.7, for example). To keep changes long-term, install from a local path or a Git commit instead.
-
-## Development
-
-```sh
-pnpm install
-pnpm run build   # tsc → lib/
-pnpm test        # build + offline tests; no real mailbox required
-```
+Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
 
-`src/index.ts` composes the plugin. `runtime.ts` owns live settings, account pools, and separate tool/web watch cursors. `tools.ts` wires the ten tool implementations. `tool-contract.ts` defines parameters, output schemas, and text rendering. `approval.ts` owns the outgoing-mail gate. IMAP/SMTP transport remains in `mail-client.ts`, and browser routes remain in `web.ts` — which also hosts the parsing, serialization (comment-preserving, keeping stored authorization codes) and custom-preset snapshot the account-card editor depends on.
+## Documentation
 
-Tests cover pool replacement after live settings changes, unload cleanup, cancellation and workspace propagation, independent tool/web cursors, account-card serialization and preset parsing, and rejected approval preventing send execution. In-memory clients replace mailbox connections.
+- [Usage and troubleshooting](docs/USAGE.en.md)
+- [Changelog](CHANGELOG.md)
+- [Validation scope and history](docs/VALIDATION.md)
+- [Report a problem or suggest a feature](https://github.com/STARDUSTLC666/dsh-email/issues)
 
 ## License
 
-MIT. This is a community plugin, not affiliated with DeepSeek; `@deepseek-ai/*` is an officially reserved namespace.
+[MIT](LICENSE)