@eduwork/dsh-mail 0.1.0-alpha.5

package/CHANGELOG.en.md

@@ -0,0 +1,43 @@
+# Changelog
+
+[简体中文](CHANGELOG.md) | **English**
+
+## Unreleased
+
+## 0.1.0-alpha.5 - 2026-09-05
+
+- Move the npm identity to `@eduwork/dsh-mail`; update installation/module paths and Client registration together.
+- Keep the Host export name, row id, settings namespace and security scope using `dsh-mail-assistant`, as well as `DSH_MAIL_ASSISTANT_PASSWORD` and `.dsh-mail-assistant/attachments`. The Client ModuleLoader uses the new package name.
+- Keep the previous unscoped version installable and document Profile migration.
+
+- Removed build-time transitive packages that were mistakenly listed as production dependencies; the Host runtime remains fully embedded in the published artifact.
+- Limited Dependabot automation to minor and patch updates for development dependencies; major updates, the DSH compatibility baseline, and `tsdown` minor updates now require manual review.
+- Added a publish-manifest assertion to the Host bundle check so external runtime dependencies cannot be reintroduced silently.
+
+## 0.1.0-alpha.4 - 2026-09-01
+
+- First public npm preview.
+- Replaced repository placeholders and unpublished-install text with the public repository and exact npm installation path.
+- Added GitHub CI, CodeQL, Dependabot, issue/PR templates, governance, and a public-release checklist.
+- Added dependency-license, bilingual-documentation, link, secret, and npm-package-content checks.
+- Kept IMAP/SMTP runtime libraries inside the Host bundle so consumers do not install a duplicate runtime dependency tree.
+- Revalidated real filesystem paths before local attachment writes to reject symlink or junction workspace escapes.
+
+## 0.1.0-alpha.3 - 2026-08-31
+
+- Updated the reviewed baseline to DeepSeek Harness `0.1.2-alpha.2` and `@deepseek-ai/cordis` `4.0.2`.
+- Routed `mail_send` through DSH permission presets: ordinary sessions ask per call; Full Access skips prompts only after sending is independently enabled.
+- Added read-only `mail_list_folders` for archive and provider-specific folder discovery.
+- Added stable cursor pagination, newest/oldest ordering, and `matched`, `returned`, `hasMore`, and `nextCursor` fields to `mail_find`.
+- Added bounded IMAP error normalization without exposing remote diagnostics.
+
+## 0.1.0-alpha.2 - 2026-08-30
+
+- Reworked settings around mailbox account, servers, advanced options, and Agent access.
+- Preserved the alpha.1 settings schema and credential reference.
+
+## 0.1.0-alpha.1 - 2026-08-29
+
+- Initial internal preview.
+- Added `mail_find`, `mail_read`, `mail_get_attachment`, and `mail_send`.
+- Established read-only IMAP, DSH Credential storage, independent read/send controls, workspace attachment boundaries, and untrusted-mail fencing.

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# 变更日志
+
+**简体中文** | [English](CHANGELOG.en.md)
+
+## 未发布
+
+## 0.1.0-alpha.5 - 2026-09-05
+
+- npm 包身份改为 `@eduwork/dsh-mail`，同步安装路径、组合模块路径与客户端注册。
+- 保留 Host 导出名、插件行 id、settings namespace 和安全作用域中的 `dsh-mail-assistant`，保留 `DSH_MAIL_ASSISTANT_PASSWORD` 与 `.dsh-mail-assistant/attachments`；客户端 ModuleLoader 使用新包名。
+- 旧无作用域版本保留可安装，并提供 Profile 迁移说明。
+
+- 移除误列为生产依赖的打包时传递依赖；Host 运行库继续完整内嵌在发布产物中。
+- Dependabot 只自动提交开发依赖的 minor/patch 更新；major、DSH 兼容基线和 `tsdown` minor 更新改为人工评估。
+- Host bundle 检查新增发布清单约束，防止重新引入外部运行时依赖。
+
+## 0.1.0-alpha.4 - 2026-09-01
+
+- 首个公开 npm 预览版。
+- 仓库元数据、安装入口、默认中文与英文镜像文档更新为公开地址。
+- 增加 GitHub CI、CodeQL、Dependabot、Issue/PR 模板、治理规则和公开发布检查表。
+- 新增依赖许可证、文档镜像、链接、敏感信息和 npm 包内容检查。
+- Host bundle 内嵌 IMAP/SMTP 运行库，发布包不再要求终端用户重复安装这些依赖。
+- 下载附件在本地写入前重新验证真实路径，拒绝由符号链接或目录联接造成的工作区逃逸。
+
+## 0.1.0-alpha.3 - 2026-08-31
+
+- 兼容基线更新到 DeepSeek Harness `0.1.2-alpha.2` 和 `@deepseek-ai/cordis` `4.0.2`。
+- `mail_send` 接入 DSH 原生权限预设：普通权限逐次确认，Full Access 在发信能力已单独开启时免确认。
+- 增加只读 `mail_list_folders`，允许发现归档目录和服务商自定义目录。
+- 增加稳定的 `mail_find` 游标分页、正序/倒序以及 `matched`、`returned`、`hasMore`、`nextCursor`。
+- 增加有限且不泄露服务端诊断的 IMAP 错误归一化。
+
+## 0.1.0-alpha.2 - 2026-08-30
+
+- 设置流程调整为邮箱账号、服务器、高级选项和 Agent 权限四部分。
+- 保持 alpha.1 的设置 Schema 和 Credential Ref 兼容。
+
+## 0.1.0-alpha.1 - 2026-08-29
+
+- 首个内部预览版。
+- 提供 `mail_find`、`mail_read`、`mail_get_attachment` 和 `mail_send`。
+- 默认只读 IMAP、DSH Credential 存储、独立读/发开关、工作区附件限制和邮件不可信数据标记。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-mail-assistant contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,95 @@
+# dsh-mail-assistant
+
+> npm package: `@eduwork/dsh-mail@0.1.0-alpha.5`. The previous unscoped package remains available during migration. See [migration and data compatibility](docs/EDUWORK-MIGRATION.en.md).
+
+[简体中文](README.md) | **English**
+
+A security-focused mail assistant plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). It reads through standard IMAP and sends through standard SMTP, while deliberately refusing to become another full mail client.
+
+Current version: `0.1.0-alpha.5`. This is a public alpha preview for isolated environments and dedicated test mailboxes. Complete your own security and compliance review before connecting a critical mailbox.
+
+## Scope
+
+The plugin exposes exactly five agent tools:
+
+| Tool | Capability | Hard boundary |
+| --- | --- | --- |
+| `mail_list_folders` | List server mailbox folders | Read-only; returns exact paths for archive/history searches |
+| `mail_find` | Page through mail by metadata and date | At most 50 rows per page; opaque continuation cursor; no body search |
+| `mail_read` | Read one plain-text message and attachment metadata | Read-only IMAP; never marks mail as read |
+| `mail_get_attachment` | Save one attachment into the session workspace | Size cap, random name, no overwrite, workspace only |
+| `mail_send` | Send or reply with plain text and workspace attachments | Ordinary permissions ask each time; Full Access skips prompts; sending must still be enabled separately |
+
+It does not delete, move, archive, label, change flags, manage contacts or rules, poll in the background, wake agents, auto-reply, compose HTML, or provide a mailbox UI.
+
+## Secure defaults
+
+- Reading and sending are both disabled after installation. Startup performs no mail network access.
+- Passwords and app passwords live only behind the DSH credential reference `DSH_MAIL_ASSISTANT_PASSWORD`; they never enter `settings.yaml` or a browser read response.
+- IMAP always uses a read-only mailbox lock and never calls `STORE`, `COPY`, `MOVE`, or `EXPUNGE`.
+- Subjects, bodies, addresses, and filenames are untrusted external data. They cannot authorize a send, request a secret, or change system policy.
+- Historical searches expose `hasMore` and `nextCursor`; complete-coverage tasks must continue until `hasMore=false` instead of treating the first page as the entire mailbox.
+- Sending is plain-text only. Recipient headers reject newline injection, and attachments must be regular files inside the current session workspace.
+- Only implicit TLS and STARTTLS are supported; certificate validation cannot be disabled.
+- A connection loss during SMTP DATA returns `unknown` and tells the agent not to retry automatically.
+
+See the complete [security model](docs/security-model.en.md).
+
+## Install
+
+Prerequisites: Node.js 22+, DSH `0.1.2-alpha.2`, and a Profile with the official Settings, Credentials, Tools, Filesystem, Permission Presets, Approval, and Web Client capabilities.
+
+For normal use, pin the reviewed exact npm version:
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-mail@0.1.0-alpha.5
+```
+
+Use a source checkout for auditing, development, or unpublished changes:
+
+```bash
+git clone https://github.com/freedomkk-qfeng/dsh-mail-assistant.git
+cd dsh-mail-assistant
+npm ci
+npm run check
+dsh plugin --profile web add .
+```
+
+From the parent directory:
+
+```bash
+dsh plugin --profile web add ./dsh-mail-assistant
+```
+
+DSH links the checkout; it does not scan the invoking directory. Keep a source checkout in place. Use `@eduwork/dsh-mail@alpha` only when intentionally following prerelease updates.
+
+## Configure and verify
+
+Open **Settings → Mail assistant**. Enter the email address, app password, and optional sender display name first; choose a common provider or manually configure IMAP/SMTP; use Advanced settings only when needed; then enable agent reading and sending independently. After saving, ask the agent to find recent mail. The plugin intentionally does not log in during startup or save.
+
+The v0.1 authentication profile is username plus password/app password over standard IMAP/SMTP. Providers that require OAuth2 are outside the current scope.
+
+## DSH composition
+
+The plugin uses official DSH seams: `ctx.credentials`, `ctx.settings`, `settings.section`, `ctx.tools`, `ctx.permissionPresets`, `tools/pre-execute`, `ctx.fs`, and the Client Loader. Ordinary permissions route sends through the composed Approval service; Full Access proceeds without a prompt. It does not fork the upstream Web client.
+
+DSH `0.1.2-alpha.2` has bounded binary reads but no binary-write filesystem seam. `mail_get_attachment` therefore uses `ctx.fs` to resolve and fence the local destination before an exclusive local write. A remote/non-local FS Provider may not support that one tool. See [compatibility](docs/compatibility.en.md).
+
+## Documentation
+
+- [Getting started](docs/getting-started.en.md)
+- [Architecture](docs/architecture.en.md)
+- [Tool contract](docs/tool-contract.en.md)
+- [Security model](docs/security-model.en.md)
+- [Compatibility](docs/compatibility.en.md)
+- [Public release checklist](docs/release-checklist.en.md)
+- [Contributing](CONTRIBUTING.en.md)
+- [Governance](GOVERNANCE.en.md)
+- [Support](SUPPORT.en.md)
+- [Security reporting](SECURITY.en.md)
+
+The integration approach was informed by the MIT-licensed community project [`STARDUSTLC666/dsh-email`](https://github.com/STARDUSTLC666/dsh-email), with a redesigned permission, credential, read-only, workspace, untrusted-content, and approval boundary. See [third-party notices](THIRD_PARTY_NOTICES.en.md).
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,115 @@
+# dsh-mail-assistant
+
+> npm 包：`@eduwork/dsh-mail@0.1.0-alpha.5`。旧无作用域包保留供迁移；安装切换与数据兼容见 [迁移说明](docs/EDUWORK-MIGRATION.md)。
+
+**简体中文** | [English](README.en.md)
+
+面向 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 的安全型邮件助手插件。它通过标准 IMAP 读取邮件、通过标准 SMTP 发送纯文本邮件，但刻意不成为另一个邮箱客户端。
+
+当前版本：`0.1.0-alpha.5`。这是公开 alpha 预览版，适合隔离环境和专用测试邮箱；连接重要邮箱前仍应完成组织自己的安全与合规审查。
+
+## 定位与边界
+
+插件只提供五个 Agent 工具：
+
+| 工具 | 能力 | 关键约束 |
+| --- | --- | --- |
+| `mail_list_folders` | 列出服务器上的邮箱目录 | 只读；返回精确路径，便于查找归档和历史邮件 |
+| `mail_find` | 按主题、发件人、收件人与日期分页查找邮件 | 每页最多 50 条；用不透明游标持续拉取，不搜索或执行正文指令 |
+| `mail_read` | 读取一封邮件的纯文本正文和附件元数据 | IMAP `EXAMINE`/只读锁；不修改已读状态 |
+| `mail_get_attachment` | 把一个附件保存到会话工作区 | 大小上限、随机文件名、不覆盖、仅工作区内 |
+| `mail_send` | 发送或回复纯文本邮件，可附加工作区文件 | 普通权限逐次确认；Full Access 免确认；仍需单独开启发信能力 |
+
+明确不做：删除、移动、归档、标签、已读/未读修改、联系人、规则、后台轮询、自动唤醒、自动回复、HTML 邮件创作和完整邮箱 UI。
+
+## 安全默认值
+
+- 安装后读信和发信权限都为关闭；启动时不连接邮箱。
+- 密码或客户端授权码只通过 DSH Credential Provider 保存，固定引用为 `DSH_MAIL_ASSISTANT_PASSWORD`；不会进入 `settings.yaml` 或浏览器回读。
+- IMAP 始终使用只读 mailbox lock，不调用 `STORE`、`COPY`、`MOVE`、`EXPUNGE`。
+- 邮件正文、标题、地址和附件名全部标记为不可信外部数据；它们不能授权发信、请求密钥或改变系统规则。
+- 历史检索显式返回 `hasMore` 和 `nextCursor`；需要完整覆盖时，Agent 必须持续翻页至 `hasMore=false`，不能把首屏结果误当成整个邮箱。
+- 发信只接受纯文本。收件地址拒绝换行注入，附件必须是当前会话工作区内的普通文件。
+- 只支持隐式 TLS 或 STARTTLS，证书校验不可关闭。
+- SMTP 在 DATA 阶段断线或超时时返回 `unknown`，并明确禁止 Agent 自动重试，避免重复发信。
+
+完整威胁模型见[安全模型](docs/security-model.md)。
+
+## 安装
+
+要求：Node.js 22+、DSH `0.1.2-alpha.2`，且所用 Profile 已包含 Settings、Credentials、Tools、Filesystem、Permission Presets、Approval 和 Web Client 官方能力。
+
+普通使用请固定经过复核的 npm 精确版本：
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-mail@0.1.0-alpha.5
+```
+
+需要审计、开发或验证尚未发布的改动时，再从源码安装：
+
+```bash
+git clone https://github.com/freedomkk-qfeng/dsh-mail-assistant.git
+cd dsh-mail-assistant
+npm ci
+npm run check
+dsh plugin --profile web add .
+```
+
+从父目录也可以显式传入路径：
+
+```bash
+dsh plugin --profile web add ./dsh-mail-assistant
+```
+
+DSH 会链接本地 checkout，不会扫描当前目录；源码安装后请保留这个目录。明确希望持续跟随预发布更新时可以使用：
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-mail@alpha
+```
+
+## 配置与首次验证
+
+1. 打开 DSH 的“设置 → 邮件助手”。
+2. 填写邮箱地址、客户端授权码和可选的发件人显示名称。
+3. 选择邮箱服务商自动填写服务器；单位邮箱或自建邮箱使用“手动配置”。
+4. 登录用户名、收件箱目录和安全上限收纳在“高级设置”中，通常无需修改。
+5. 配置完成后，分别决定是否开放“允许 Agent 读信”和“允许 Agent 发信”。
+6. 保存后，在对话中让 Agent“查一下最近的邮件”。插件不会在保存时主动登录邮箱。
+
+无 UI 的部署可在 `cordis.patch.yml` 中覆盖非敏感配置，并把密码放入 DSH 凭据引用 `DSH_MAIL_ASSISTANT_PASSWORD`（本地 Credential Provider 也会按引用名读取同名环境变量）。不要把密码写进 Bundle 或 patch。
+
+不同服务商对普通密码、应用密码和 OAuth2 的支持不同。此插件的 v0.1 只实现用户名 + 密码/授权码的标准 IMAP/SMTP 登录；强制 OAuth2 的邮箱不在当前支持范围内。
+
+## 与 DSH 的组合关系
+
+插件复用 DSH 原生能力，而不是 fork 客户端：
+
+- `ctx.credentials`：保存和逐次解析授权码；
+- `ctx.settings` 与 `settings.section`：配置存储和设置页；
+- `ctx.tools`：工具注册、单调拒绝 guard 和统一执行管线；
+- `ctx.permissionPresets` 与原生 `tools/pre-execute`：普通权限逐次确认，Full Access 免确认；
+- `ctx.fs`：发送附件的工作区解析、包含性检查和有界读取；
+- DSH Client Loader：动态加载设置页，不修改官方 Web 应用。
+
+二进制写入尚未出现在 DSH `ctx.fs` seam 中，因此 `mail_get_attachment` 在本地 Host 文件系统上通过 `ctx.fs` 完成路径解析与包含性校验后，以独占写方式落盘。远程/非本地 FS Provider 可能不支持该工具；其他读信和发信能力不受影响。详见[兼容性](docs/compatibility.md)。
+
+## 文档
+
+- [快速接入](docs/getting-started.md)
+- [架构与扩展边界](docs/architecture.md)
+- [工具契约](docs/tool-contract.md)
+- [安全模型](docs/security-model.md)
+- [兼容性与限制](docs/compatibility.md)
+- [公开发布检查表](docs/release-checklist.md)
+- [贡献指南](CONTRIBUTING.md)
+- [治理规则](GOVERNANCE.md)
+- [支持](SUPPORT.md)
+- [安全问题报告](SECURITY.md)
+
+## 致谢与来源
+
+本项目参考了社区插件 [`STARDUSTLC666/dsh-email`](https://github.com/STARDUSTLC666/dsh-email) 对 ImapFlow、Nodemailer、MailParser 与 DSH 的组合经验，但重新划定了能力边界，并改用 DSH Credentials、默认关闭权限、只读 IMAP、工作区附件边界、邮件不可信标记和 DSH 原生权限预设。第三方依赖与许可证见[第三方组件声明](THIRD_PARTY_NOTICES.md)。
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.en.md

@@ -0,0 +1,9 @@
+# Security policy
+
+[简体中文](SECURITY.md) | **English**
+
+`0.1.0-alpha.x` is a prerelease for local testing and should not be connected to a critical mailbox.
+
+Do not open a public issue for authorization bypass, credential disclosure, workspace escape, unexpected message mutation, approval bypass, duplicate sending, or remote-code-execution risk. Use GitHub [Private Vulnerability Reporting](https://github.com/freedomkk-qfeng/dsh-mail-assistant/security/advisories/new).
+
+Include only minimal reproduction steps, affected versions, and sanitized protocol facts. Never attach real app passwords, cookies, full messages, personal addresses, or unsanitized diagnostics. High-impact outbound, credential, and workspace-boundary issues receive priority, although no fixed prerelease SLA is promised.

package/SECURITY.md

@@ -0,0 +1,11 @@
+# 安全政策
+
+**简体中文** | [English](SECURITY.en.md)
+
+当前 `0.1.0-alpha.x` 为预发布版本，只接受本地测试，不建议直接接入重要邮箱。
+
+如发现授权绕过、凭据泄露、工作区逃逸、邮件状态意外修改、审批绕过、重复发信或远程代码执行风险，请不要公开 issue。请通过 GitHub [Private Vulnerability Reporting](https://github.com/freedomkk-qfeng/dsh-mail-assistant/security/advisories/new) 私密报告。
+
+报告请只包含最小复现步骤、受影响版本和脱敏后的协议事实。不要附上真实授权码、Cookie、完整邮件、个人地址或未清理的诊断包。
+
+我们会确认收到、评估影响、准备修复和回归测试，再协商披露时间。预发布阶段不承诺固定 SLA，但会优先处理可导致外发、凭据或工作区越界的问题。

package/THIRD_PARTY_NOTICES.en.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+[简体中文](THIRD_PARTY_NOTICES.md) | **English**
+
+`dsh-mail-assistant` is distributed under the MIT License. Its build uses or embeds:
+
+- [ImapFlow](https://github.com/postalsys/imapflow) — MIT License — IMAP client;
+- [Nodemailer](https://github.com/nodemailer/nodemailer) — MIT-0 License — SMTP message submission;
+- [MailParser](https://github.com/nodemailer/mailparser) — MIT License — MIME parsing;
+- [Schemastery](https://github.com/shigma/schemastery) — MIT License — DSH-compatible settings schema;
+- [React](https://github.com/facebook/react) — MIT License — DSH Client settings surface (peer dependency).
+
+The project was informed by the MIT-licensed integration approach in [`STARDUSTLC666/dsh-email`](https://github.com/STARDUSTLC666/dsh-email), but redesigns the permission, credential, read-only IMAP, workspace, untrusted-content, and approval boundaries. No third-party project endorses this plugin.
+
+Exact direct and transitive versions are recorded in `package-lock.json`. Review the lockfile, license-check output, and final npm tarball before every public release.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# 第三方组件声明
+
+**简体中文** | [English](THIRD_PARTY_NOTICES.en.md)
+
+`dsh-mail-assistant` 自身使用 MIT 许可证。构建产物包含或使用以下直接依赖：
+
+- [ImapFlow](https://github.com/postalsys/imapflow) — MIT License — IMAP 客户端；
+- [Nodemailer](https://github.com/nodemailer/nodemailer) — MIT-0 License — SMTP 邮件提交；
+- [MailParser](https://github.com/nodemailer/mailparser) — MIT License — MIME 解析；
+- [Schemastery](https://github.com/shigma/schemastery) — MIT License — DSH 兼容的设置 Schema；
+- [React](https://github.com/facebook/react) — MIT License — DSH Client 设置界面（peer dependency）。
+
+项目参考了 MIT 许可的社区项目 [`STARDUSTLC666/dsh-email`](https://github.com/STARDUSTLC666/dsh-email) 在 ImapFlow、Nodemailer、MailParser 与 DSH 之间的组合思路，但重新设计了权限、凭据、只读 IMAP、工作区、邮件不可信内容和审批边界。没有任何第三方项目为本插件背书。
+
+直接和间接依赖的精确版本记录在 `package-lock.json`。每次公开发布前必须重新审查锁文件、许可证检查结果和最终 npm tarball。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-mail-assistant installs disabled and performs no network access at boot.
+# Configure it in Settings -> Mail assistant, or override this row for headless
+# deployments. Store the password/app password through the DSH credential ref
+# DSH_MAIL_ASSISTANT_PASSWORD; never put it in this file.
+- insert:
+    - id: dsh-mail-assistant
+      name: '@eduwork/dsh-mail'
+      config: {}

package/docs/EDUWORK-MIGRATION.en.md

@@ -0,0 +1,23 @@
+# eduwork npm scope migration
+
+[简体中文](EDUWORK-MIGRATION.md) | **English**
+
+Starting with this version, the npm package is `@eduwork/dsh-mail@0.1.0-alpha.5`, replacing `dsh-mail-assistant`. The npm `eduwork` organization exists. The GitHub repository and checkout directory remain `dsh-mail-assistant`. Consult the npm registry for current publication status.
+
+## Installation and migration
+
+```sh
+dsh plugin --profile web add @eduwork/dsh-mail@0.1.0-alpha.5
+```
+
+Back up an existing Profile's package.json and cordis.patch.yml, then update its dependency and dsh.profile.bundles entries. Update module name paths in custom patches too. Do not enable both package identities together; restart the Host after switching. These are separate npm packages, so updating the old package cannot migrate an installation automatically.
+
+## Data compatibility
+
+Keep the Host export name, row id, settings namespace and security scope using `dsh-mail-assistant`, as well as `DSH_MAIL_ASSISTANT_PASSWORD` and `.dsh-mail-assistant/attachments`. The Client ModuleLoader uses the new package name.
+
+Storage directories and user configuration content do not change. Product-managed Profiles migrate their owned dependencies through the product upgrader; community plugins remain unchanged.
+
+## Release scope
+
+This is an alpha package-identity migration retaining the declared DSH peer baseline. Build, tests, documentation, license and tarball checks cover this change. It adds no claims of real institutional sign-in, real email delivery or production acceptance. Stable releases still require the complete deployment checks. Keep previous versions installable and add a migration notice only after the new package passes installation validation.

package/docs/EDUWORK-MIGRATION.md

@@ -0,0 +1,23 @@
+# eduwork npm 作用域迁移
+
+**简体中文** | [English](EDUWORK-MIGRATION.en.md)
+
+从本版本起，npm 包使用 `@eduwork/dsh-mail@0.1.0-alpha.5`，替代旧的 `dsh-mail-assistant`。npm `eduwork` 组织已创建；GitHub 仓库和本地 checkout 目录继续使用 `dsh-mail-assistant`。包的当前发布状态以 npm registry 为准。
+
+## 安装与迁移
+
+```sh
+dsh plugin --profile web add @eduwork/dsh-mail@0.1.0-alpha.5
+```
+
+已有 Profile 先备份 package.json 与 cordis.patch.yml，再更新依赖和 dsh.profile.bundles；手写 patch 的模块路径 name 也需切换。不要同时启用新旧两份插件，切换后重启 Host。旧版本和新作用域版本是不同 npm 包，旧包的更新不会自动迁移安装。
+
+## 数据兼容
+
+保留 Host 导出名、插件行 id、settings namespace 和安全作用域中的 `dsh-mail-assistant`，保留 `DSH_MAIL_ASSISTANT_PASSWORD` 与 `.dsh-mail-assistant/attachments`；客户端 ModuleLoader 使用新包名。
+
+本次迁移不修改存储目录或用户配置内容。产品管理的 Profile 由产品升级逻辑迁移其受管依赖；社区插件保持原状。
+
+## 发布范围
+
+此版本为 alpha 包身份迁移，沿用声明的 DSH peer 基线。构建、测试、文档、开源和 tarball 检查针对本次变更执行；不新增真实学校登录、真实邮件发送或生产部署验收结论。稳定发布仍须完成公开发布检查表中的完整部署验收。旧包保持可安装，新包安装验证通过后添加迁移提示，不撤回旧版本。

package/docs/architecture.en.md

@@ -0,0 +1,68 @@
+# Architecture and extension boundary
+
+[简体中文](architecture.md) | **English**
+
+## Composition
+
+`dsh-mail-assistant` is one Host + Client Bundle:
+
+```text
+DSH Web Client
+  └─ settings.section: Mail assistant
+       ├─ remote.settings      non-secret account/server settings
+       └─ remote.credentials   write-only app password
+
+DSH Host
+  ├─ ctx.settings             live configuration
+  ├─ ctx.credentials          resolve app password per operation
+  ├─ ctx.tools                five tools, capability guard, execution pipeline
+  ├─ ctx.permissionPresets
+  │    ├─ ordinary preset     one approval for mail_send
+  │    └─ Full Access         no per-call prompt
+  ├─ ctx.fs                   workspace resolution and bounded binary reads
+  ├─ ImapFlow                 read-only IMAP
+  └─ Nodemailer               controlled SMTP submission
+```
+
+The plugin does not provide a Credential, Settings, Filesystem, Permission Preset, Approval, or Web Shell provider. The DSH Profile owns those services, allowing ordinary Web, local desktop, and other product compositions to reuse the same package.
+
+## Configuration and credentials
+
+Non-secret fields live in the `dsh-mail-assistant` settings namespace. The app password uses the fixed credential reference `DSH_MAIL_ASSISTANT_PASSWORD`. The Host resolves it at the beginning of every tool call and never caches it across operations, so rotation applies to the next call.
+
+The settings page only invokes `credentials.describe/set/unset`. It can observe configured/writable state, but it cannot read the credential value back into the browser.
+
+## Message identity and pagination
+
+The model never constructs an IMAP UID directly. `mail_find` returns an opaque handle that binds folder, UIDVALIDITY, and UID. A later read reopens the same folder and revalidates UIDVALIDITY. If a mailbox is rebuilt or its UID namespace changes, the old handle fails and instructs the caller to search again. Attachment handles additionally bind the message and MIME part and are compared with the current body structure before download.
+
+Handles prevent stale or accidental addressing; they are not bearer authorization and contain no password. Capability settings, the current credential, session workspace, and DSH permission preset remain authoritative.
+
+A `mail_find` continuation cursor binds the complete filter, direction, UIDVALIDITY, and preceding-page UID boundary. Newest-first continuation only moves toward lower UIDs, so messages arriving during pagination do not duplicate earlier pages; oldest-first moves in the opposite direction. Every page reruns server-side search and checks UIDVALIDITY. `mail_list_folders` discovers exact paths; `mail_find` opens one explicit folder. No mailbox synchronization or local mail database exists.
+
+## Connection lifecycle
+
+Each tool call creates one short-lived connection and closes it after the operation:
+
+- no background IDLE or polling;
+- no startup or save-time probe;
+- no connection pool across calls;
+- cancellation closes the protocol connection;
+- protocol logging is disabled.
+
+This trades a small amount of latency for simpler credential rotation, cleanup, and failure isolation. Any future pool must still re-resolve credentials per operation and invalidate immediately on settings or credential changes.
+
+## Binary boundary
+
+Outbound attachments use `ctx.fs`: resolve from the session `cwd`, verify containment, require a regular file, enforce an aggregate size bound, then use bounded `readBytes`.
+
+The Host artifact embeds the IMAP/SMTP implementation libraries in `lib/index.js`. Users do not install a second protocol runtime after npm, source-package, or offline-product installation, and plugin dependencies cannot collide with a product's private Node runtime during updates.
+
+DSH `0.1.2-alpha.2` does not expose `writeBytes`. Attachment download therefore requires a local Host filesystem. The plugin resolves the logical destination with `ctx.fs`, creates the directory, resolves real workspace and directory paths, rechecks containment to reject pre-existing symlinks or junctions, and finally performs a random-name `wx` exclusive write. Replace this local adapter when DSH provides an official binary-write seam.
+
+## Extension rules
+
+- OAuth2 requires a separate authentication adapter; tokens never belong in settings.
+- Multiple accounts require independent Credential Keys/Refs and an explicit account parameter; YAML must not carry passwords.
+- Polling, auto-reply, move, delete, and flag mutation are separate high-risk product boundaries.
+- Background or scheduled sending requires an explicit deployment mode and recipient allowlist. Interactive Full Access cannot silently become background authorization.

package/docs/architecture.md

@@ -0,0 +1,76 @@
+# 架构与扩展边界
+
+**简体中文** | [English](architecture.en.md)
+
+## 组合结构
+
+`dsh-mail-assistant` 是一个 Host + Client Bundle：
+
+```text
+DSH Web Client
+  └─ settings.section: 邮件助手设置页
+       ├─ remote.settings      非敏感账号和服务器配置
+       └─ remote.credentials   授权码只写
+
+DSH Host
+  ├─ ctx.settings       动态配置
+  ├─ ctx.credentials    每次操作重新解析授权码
+  ├─ ctx.tools          五个模型工具、能力 guard 与 pre-execute 权限通路
+  ├─ ctx.permissionPresets
+  │    ├─ 普通权限      mail_send 请求一次性确认
+  │    └─ Full Access   mail_send 不弹确认
+  ├─ ctx.fs             工作区路径与有界二进制读取
+  ├─ ImapFlow           只读 IMAP
+  └─ Nodemailer         受控 SMTP
+```
+
+插件不提供 Credential Provider、Settings Provider、Permission Preset/Approval UI、Filesystem Provider 或 Web Shell；这些都由部署使用的 DSH Profile 负责。这样普通 Web、本地桌面宿主和其他组合可以复用同一插件。
+
+## 配置与密钥
+
+非敏感字段保存在 `dsh-mail-assistant` settings namespace。授权码使用固定 Credential Ref `DSH_MAIL_ASSISTANT_PASSWORD`。Host 在每个工具调用开始时重新解析引用，不跨操作缓存密码，因此轮换后的值会在下一次调用生效。
+
+设置页只能调用 `credentials.describe/set/unset`：它能看到“是否配置”和“是否可写”，不能读回实际值。
+
+## 邮件标识
+
+模型不会直接拼接 IMAP UID。`mail_find` 返回的不透明 message handle 同时包含：
+
+- folder；
+- UIDVALIDITY；
+- UID。
+
+后续读取会再次打开同一 folder 并验证 UIDVALIDITY。邮箱重建或 UID 空间变化时，旧 handle 会明确失败，要求重新查找。附件 handle 绑定 message handle 和当前 MIME part；下载前再次对照实时 body structure。
+
+handle 用于完整性检查和防误用，不是授权令牌，也不包含密码。它目前是可解码但严格校验的结构；所有能力仍由当前配置、凭据、会话工作区和权限预设共同决定。
+
+`mail_find` 的翻页游标还绑定完整筛选条件、方向和上一页 UID 边界。默认 newest 方向只继续读取更小的 UID，因此翻页期间新收到的邮件不会造成重复；oldest 方向反向处理。每页都会重新执行服务器端搜索，并检查 UIDVALIDITY。游标不保存邮件内容，也不是跨账号授权。
+
+目录发现与检索分离：`mail_list_folders` 只执行 IMAP `LIST`，`mail_find` 每次只打开一个明确目录。插件不会后台同步全邮箱，也不会建立本地邮件数据库。
+
+## 连接生命周期
+
+每次工具调用创建短生命周期连接，操作完成即关闭：
+
+- 无后台 IDLE；
+- 无启动探测；
+- 无跨调用邮箱连接池；
+- 中止信号会关闭底层连接；
+- 连接日志关闭，避免协议内容进入应用日志。
+
+这个选择牺牲少量延迟，换取更简单的凭据轮换、资源回收和故障边界。以后若引入连接池，必须保持按操作重新解析凭据，并在凭据或设置变化时立即失效。
+
+## 二进制边界
+
+发送附件完全走 `ctx.fs`：以会话 `cwd` 解析、验证包含关系、检查普通文件、累计大小，再通过 `readBytes` 有界读取。
+
+Host 产物会把 IMAP/SMTP 运行依赖编入 `lib/index.js`。因此通过 npm、源码包或 ChatECNU Work 离线装配安装后，终端用户都不需要再安装 Node 依赖；这也避免了插件依赖与宿主随版本更新的私有 Node 运行时互相覆盖。
+
+DSH `0.1.2-alpha.2` 暂无 `writeBytes`。下载附件因此只在本地 Host FS 上可用：插件先用 `ctx.fs` 解析逻辑路径，创建目录后再解析工作区与目标目录的真实路径并重新验证包含关系，最后把随机文件名以 `wx` 独占模式写入。这样会拒绝预置符号链接或目录联接造成的工作区逃逸。未来官方提供二进制写 seam 后，应删除这段本地适配，直接复用官方能力。
+
+## 后续扩展规则
+
+- OAuth2 认证应增加独立认证适配层，不得把 token 放进 settings。
+- 多账号需要为每个账号使用独立 Credential Key/Ref 和明确 account 参数，不得用 YAML 承载密码。
+- 后台轮询、自动回复、移动和删除属于新的高风险产品边界，不应顺手加入本插件。
+- 后台或计划任务发信仍属于新的高风险边界，应使用显式部署模式和收件人 allowlist；不能把交互会话里的 Full Access 自动扩张为后台授权。

package/docs/compatibility.en.md

@@ -0,0 +1,37 @@
+# Compatibility and known limits
+
+[简体中文](compatibility.md) | **English**
+
+Package `@eduwork/dsh-mail@0.1.0-alpha.5` retains the alpha.4 runtime and settings contracts. See [migration](EDUWORK-MIGRATION.en.md).
+
+## Reviewed baseline
+
+- DeepSeek Harness `0.1.2-alpha.2`;
+- Node.js 22+;
+- dynamic Web Client Bundle;
+- local Host filesystem;
+- IMAP4rev1/IMAP4rev2 and SMTP Submission with username plus password/app-password authentication.
+
+The DSH Profile provides `settings`, `credentials`, `tools`, `permissionPresets`, `approval`, and `fs`. The settings page also depends on official Remotes, Renderer, and Settings Client packages. Ordinary sending requires an interactive approval path; Full Access does not prompt.
+
+## Protocol scope
+
+- IMAP uses read-only mailbox semantics and UIDVALIDITY to reject stale UIDs.
+- SMTP supports implicit TLS and STARTTLS, never plaintext.
+- XOAUTH2/OIDC mailbox login is not implemented. Gmail, Microsoft 365, and similar providers work only when tenant policy permits app passwords and SMTP AUTH.
+- The plugin does not append a copy to the IMAP Sent folder; server policy decides whether sent mail is retained.
+- S/MIME, PGP, calendar invitations, and nested `message/rfc822` are treated as ordinary MIME data without specialized semantics.
+
+## DSH binary-write limitation
+
+DSH `0.1.2-alpha.2` exposes `ctx.fs.readBytes` but no `writeBytes`:
+
+- outbound local attachments use the official seam end to end;
+- downloads require `ctx.fs.processPath()` and the Host Node process to share one filesystem;
+- after creating the destination directory the plugin resolves real paths and rechecks workspace containment;
+- E2B, remote containers, and other non-shared Filesystem Providers should disable or expect a clear `mail_get_attachment` failure;
+- migrate to the official binary-write API and remove the local adapter when one becomes available.
+
+## Version policy
+
+During `0.x`, a DSH alpha may change the Client Loader, settings slots, or tool schemas. For every upgrade, run the full automated suite and real IMAP/SMTP acceptance in an isolated Profile. Compilation alone is insufficient.